Scaffold and deploy a production-ready full-stack website on EdgeOne Pages from a single natural language request.
When to use this skill
- User wants to start a new full-stack website (e-commerce, AI chatbot, SaaS admin) with zero config
- User mentions: e-commerce, shopping cart, payment, AI chat, admin dashboard, login/register, or similar
- User wants Edge Functions + Cloud Functions + KV + MySQL on EdgeOne Pages
Do NOT use for:
- Adding a single API/function to an existing project → use
edgeone-pages-dev - Deploying an already-built project → use
edgeone-pages-deploy - Pure static sites or blogs without business logic
⛔ Critical Rules (never skip)
- ALWAYS ask the user to confirm the scenario first. Three built-in templates are available:
- E-commerce (🛒):Auth + Cart + Payment (WeChat/Alipay) + Orders + Admin
- AI Assistant (🤖):Auth + AI Chat (SSE streaming) + Admin
- SaaS Admin (📊):Auth + RBAC Admin + Subscription Payments
- Never fabricate the user's requirements. If information is missing, ask clarifying questions before generating code.
- Respect EdgeOne Pages platform constraints:
- KV is only accessible from Edge Functions (not Cloud Functions)
- Cloud Functions directory must be named
cloud-functions/ - bcrypt must run inside Cloud Functions
- AI SSE streaming must be implemented in Cloud Functions (Edge cannot use
waitUntil)
- Payment idempotency is mandatory. Use Edge
putIfNotExistswith 24h TTL (< WeChat retry window of 72h). - Never commit
.env.localor any real API keys. Ensure.gitignorecovers it. - Always verify EdgeOne Pages CLI is installed before deployment.
Main Flow
Step 1 — Confirm scenario
Use ask_followup_question to ask:
What type of website do you want to build?
- 🛒 E-commerce site — login/registration, shopping cart, WeChat/Alipay payment, order management
- 🤖 AI customer service site — login/registration, AI chat (SSE streaming), visitor messages
- 📊 SaaS admin dashboard — login/registration, RBAC permissions, data dashboard
- ⚙️ Custom — freely combine modules
Branch:
- E-commerce → use
references/templates.md§ "E-commerce template" - AI Assistant → use
references/templates.md§ "AI assistant template" - SaaS Admin → use
references/templates.md§ "Admin dashboard template" - Custom → confirm which modules are needed
Step 2 — Collect requirements
Read references/templates.md and confirm with user:
- Site name / domain
- Which modules to enable (Auth always required)
- Payment providers (WeChat / Alipay / Both / None)
- AI provider (if AI Chat enabled)
Output: a Spec object
{
"scenario": "e-commerce | ai-assistant | saas-admin | custom",
"siteName": "...",
"modules": ["auth", "cart", "payment", "ai-chat", "admin"],
"paymentProviders": ["wx", "ali"],
"aiProvider": "openai | hunyuan | none",
"envVars": ["JWT_SECRET", "DATABASE_URL", ...]
}
Show the Spec back and ask for confirmation.
Step 3 — Generate project structure
Based on the selected template, generate the following directory tree:
<project>/
├── client/ # Next.js frontend (SPA)
│ ├── app/ (pages: login, register, cart, checkout, orders, admin/*)
│ ├── lib/ (api client, auth service, cart service, SSE client)
│ └── middleware (optional, for pure SPA)
├── edge-functions/ # Edge Functions (V8 + KV)
│ ├── _middleware.js # JWT check + KV session + rate limit
│ └── api/
│ ├── auth/login.js # JWT issue + KV session
│ ├── auth/me.js # KV session read
│ ├── auth/refresh.js # RT rotation with KV version lock
│ ├── auth/logout.js
│ ├── internal/idempotency.js # Edge atomic idempotency lock ← P0
│ ├── products/list.js # KV cache + MySQL fallback
│ ├── cart/*.js # KV cart
│ ├── orders/list.js # MySQL read
│ └── ai/history.js # KV AI session history
├── cloud-functions/ # Cloud Functions (Node.js + MySQL)
│ ├── api/
│ │ ├── auth/register.js # bcrypt cost=12 ← P0
│ │ ├── pay/create-order.js
│ │ ├── pay/wx-notify.js # Edge idempotency lock ← P0
│ │ ├── pay/ali-notify.js
│ │ ├── order/create.js # SELECT FOR UPDATE ← P0
│ │ ├── order/cancel.js
│ │ ├── admin/products.js
│ │ └── ai/chat-stream.js # SSE streaming ← AI module
│ └── utils/
│ ├── db.js # MySQL pool (mysql2/promise)
│ └── payment-sdk.js # WeChat V3 / Alipay SDK
├── db/
│ ├── migrations/001_init.sql # users, products, orders, order_items
│ └── seed.sql
├── docs/
│ └── env-vars.md # Environment variable matrix
└── references/
└── auth-module.md / payment-module.md / ai-chat-module.md / kv-storage.md
Generate each file according to references/ documents.
Step 4 — Environment variables
Read references/env-setup.md (or inline from SKILL.md § Environment Variables) and:
- List all required env vars for the selected modules
- Ask user to provide values (or provide placeholder examples)
- Remind: never commit
.env.local
Step 5 — Local verification
Guide user to run locally:
npm run dev # Next.js on http://localhost:3000
Verify:
- Homepage renders
- Auth signup/login works
- Selected modules (cart / payment / AI chat) are functional
Step 6 — Deploy to EdgeOne Pages
6.1 — Check edgeone-pages-deploy skill
Check if ~/.codebuddy/skills/edgeone-pages-deploy/ exists (or Windows equivalent). If yes → go to 6.2. If no → go to 6.3.
6.2 — Hand off to deploy skill
✅ The project is ready, and it can be deployed at any time after running successfully locally.
Tell the AI "deploy to EdgeOne Pages", and it will automatically load the
edgeone-pages-deployskill to complete the launch.
6.3 — Manual deploy
# Install CLI (first time)
npm install -g edgeone@latest
# Login
edgeone login --site china
# Deploy
cd <project>
edgeone pages deploy -n <project-name>
⚠️ The final URL contains
eo_token/eo_timequery params — must be kept, removing them causes 401.
Routing
| Step | Read |
|---|---|
| Scenario confirmation + module matrix | references/templates.md |
| Auth module (JWT, KV session, bcrypt, RT) | references/auth-module.md |
| Payment module (idempotency, WeChat/Alipay, callbacks) | references/payment-module.md |
| AI Chat module (SSE, history, streaming) | references/ai-chat-module.md |
| KV Storage strategy (single query, layered access) | references/kv-storage.md |
Quick Reference
Demo: https://geek-mall-demo-4qaxvmeh.edgeone.cool
Platform constraints:
- KV → Edge Functions only
- bcrypt → Cloud Functions only
- AI SSE → Cloud Functions only
- Platform Middleware → CORS, CSP, Bearer check, Payment callback IP whitelist (direct return)
P0 Security (all implemented):
- Payment idempotency: Edge
putIfNotExists(24h TTL) - Order atomicity:
SELECT FOR UPDATE+ optimistic lock + MySQL CHECK - RT concurrency: KV version optimistic lock (409 retry)
- Price integrity: Server-side MySQL (never trust frontend price)
- Payment callback isolation: Platform Middleware direct return
- Password: bcrypt cost ≥ 12
Template repos: https://github.com/TencentEdgeOne/edgeone-pages-skills
⚠️ Security and compliance notes
1. Deployment confirmation mechanism
Before deployment, the AI Agent displays the list of files to be deployed and a summary of changes, and requests user confirmation before executing the deployment.
2. Payment security
- The payment callback implements HMAC-SHA256 signature verification (WeChat official algorithm)
- Verify the consistency of appid/mchid merchant identity
- Verify that the callback amount exactly matches the order amount
- Only accept transaction statuses with result_code=SUCCESS
- KV idempotency lock prevents duplicate callback processing
3. Data retention policy
| Data type | Storage location | Retention period |
|---|---|---|
| KV Session | EdgeOne KV | 7-day TTL |
| AI chat history | EdgeOne KV | 30-day TTL |
| Audit logs | EdgeOne KV | 90-day TTL |
| Order data | MySQL | Permanent (required for business) |
4. Cron scheduled tasks
- PENDING timeout after 30 minutes → CANCELLED
- SHIPPED for more than 7 days → COMPLETED
- Provides a one-click disable script
cloud-functions/cron/disable-cron.js
5. Usage recommendations
- Verify all features in a test project
- Use test/sandbox merchant IDs
- Review the generated code and environment variables before deployment
- Complete signature verification testing before enabling real payments