AI 一站式开发工作流 Skill（v1 · 锦鸿行实战复盘版）

基于锦鸿行活动报名微信小程序实战（175 文件 / 12918 行代码 / PR #3 合入）复盘提炼。

核心理念：AI 直接读取 PRD → 一次性生成完整代码 → 推送 PR，不走 6 站 NPC 转移链。

与 ai-pipeline-factory-skill 的区别：
| 维度 | Pipeline（NPC 调度） | One-Shot（本 Skill） |
|------|---------------------|---------------------|
| 开发模式 | 6 站 NPC 协作 + 仓库转移 | 单 Agent 一次生成 |
| 耗时 | 60-80min（含 NPC 等待） | 3-5min（代码生成） + 2min（推送） |
| 积分消耗 | 6 次 NPC 调用 | 1 次 AI 生成 |
| 适用项目 | 大型 Web SPA（需独立前后端） | 全栈项目 / 小程序 / 单体应用 |
| 代码一致性 | 多 NPC 可能风格差异 | 单次生成风格一致 |
| 验收 | verify-stage.sh 30+项 | 代码结构自检 checklist |

前置条件

输入要求

• PRD 仓库：CNB 上的一个仓库，包含 PRD.md 或 docs/PRD-v2.md
• PRD 格式：结构化的 Markdown 文档（含技术架构、功能模块、数据库设计、页面结构、接口设计等章节）

完整工作流（5 步，一步到位）

第一步：获取 PRD（3 个子步骤）

1.1 克隆项目仓库

# 方案 A：标准克隆（推荐，速度快）
git clone --depth 1 https://cnb.cool/{org}/{repo}.git /sandbox/workspace/{repo}-src

# 方案 B：如果 git clone 报 IO 错误，用 API 下载 archive
curl -s -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Accept: application/vnd.cnb.api+json" \
  "https://api.cnb.cool/{org}/{repo}/-/git/archive?ref=main" \
  -o /sandbox/workspace/{repo}-main.tar.gz
tar xzf /sandbox/workspace/{repo}-main.tar.gz -C /sandbox/workspace/{repo}-src/

踩坑备忘：
- 如果 git clone 报「无法读取包文件: 输入/输出错误」，立即切换到方案 B（API archive）
- sparse clone（--filter=blob:none）可能导致后续 git add 报错，需 git config core.sparseCheckout false

1.2 定位 PRD 文件

搜索提示词 → workspace: "PRD" in /sandbox/workspace/{repo}-src/
搜索提示词 → workspace: "PRD-v2" in /sandbox/workspace/{repo}-src/

优先查找：
- docs/PRD-v2.md（升级版 PRD）
- PRD.md（原始 PRD）
- README.md（如果没有独立 PRD 文件）

1.3 深度阅读 PRD

读取提示词 → file_read: /sandbox/workspace/{repo}-src/docs/PRD-v2.md
  问题: "提取以下关键信息：1)技术架构和技术栈 2)功能模块列表 3)数据库设计（表名+字段） 4)页面结构（路由+组件） 5)接口设计（API列表+入参出参） 6)角色权限体系 7)非功能性需求"

必读章节（按优先级）：
1. 技术架构（决定技术栈）
2. 功能模块（决定文件结构）
3. 数据库设计（决定后端接口）
4. 页面结构（决定前端页面）
5. 接口设计（决定云函数/API）
6. 角色权限（决定鉴权逻辑）
7. 产品里程碑、业务流程、非功能需求（补充细节）

第二步：技术栈决策 + 项目规划

2.1 自动识别平台类型

根据 PRD 中的技术架构章节，自动判断：

2.2 规划文件结构

根据平台类型和 PRD 页面结构，生成项目骨架规划：

规划提示词模板：
"基于 PRD 的以下信息，规划完整的项目文件结构：

技术栈：{技术栈}
页面列表：{PRD页面结构章节}
数据库表：{PRD数据库设计章节}
接口列表：{PRD接口设计章节}
角色体系：{PRD角色权限章节}

要求：
1. 前端：列出每个页面的 wxml/wxss/js/json 文件路径（小程序）或 tsx 文件路径（Web）
2. 后端：列出每个接口的云函数目录（小程序）或 API 路由文件（Web）
3. 公共模块：列出共享工具、鉴权、数据库封装等
4. 配置文件：app.json / cloudbaserc.json（小程序）或 package.json / vite.config.ts（Web）
5. 标注每个文件的核心职责（1句话）"

小程序标准文件结构：

{project}/
├── miniprogram/           # 小程序前端
│   ├── app.js             # 全局逻辑（用户登录、角色判断）
│   ├── app.json           # 全局配置（页面路由、TabBar、window）
│   ├── app.wxss           # 全局样式（CSS变量体系 + 公共类）
│   ├── images/            # 图标资源
│   ├── utils/             # 工具模块
│   │   ├── api.js         # 云函数调用封装
│   │   ├── auth.js        # 权限判断
│   │   ├── cloud.js       # CloudBase 初始化
│   │   └── util.js        # 通用工具（日期、格式化）
│   ├── components/        # 自定义组件
│   │   ├── event-card/    # 活动卡片
│   │   ├── empty-state/   # 空状态
│   │   └── loading/       # 加载态
│   └── pages/             # 页面（按角色分组）
│       ├── index/         # 首页（活动列表）
│       ├── search/        # 搜索页
│       ├── event-detail/  # 活动详情
│       ├── register/      # 报名填写
│       ├── pay/           # 支付页
│       ├── order-list/    # 我的订单
│       ├── ticket/        # 电子票
│       ├── user-center/   # 个人中心
│       └── organizer/     # 主办方页面组
│           ├── index/     # 主办方首页
│           ├── create-event/
│           ├── edit-event/
│           ├── manage-event/
│           ├── manage-registration/
│           ├── manage-checkin/
│           ├── finance/
│           └ statistics/
│       └── staff/         # 工作人员
│           └─ bind/       # 邀请码绑定
├── cloudfunction/         # 云函数后端
│   ├── shared/            # 共享模块
│   │   ├── constants.js   # 错误码常量
│   │   ├── auth.js        # 权限验证
│   │   ├── db.js          # 数据库封装
│   │   ├── response.js    # 统一响应格式
│   ├── {function-name}/   # 每个云函数独立目录
│   │   ├── index.js       # 函数入口
│   │   ├── package.json   # 依赖声明
│   └── ...                # 更多云函数
├── cloudbaserc.json       # CloudBase 部署配置
├── project.config.json    # 小程序项目配置（需用户补充 appid）
├── sitemap.json           # 小程序搜索配置
└── README.md              # 项目说明文档

Web SPA 标准文件结构：

{project}/
├── client/                # 用户端前端
│   ├── src/
│   │   ├── pages/         # 页面组件
│   │   ├── components/    # 公共组件
│   │   ├── hooks/         # 自定义 hooks
│   │   ├── api/           # API 调用封装
│   │   ├── store/         # 状态管理 (Zustand)
│   │   ├── utils/         # 工具函数
│   │   └── App.tsx
│   │   └── main.tsx
│   ├── public/
│   │   ├── _routes.json   # SPA fallback
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
├── admin/                 # 管理后台（如需独立）
│   ├── src/
│   ├── public/
│   │   ├── _routes.json
│   ├── vite.config.ts     # base: '/admin/'
│   └── package.json
├── server/                # 后端 API
│   ├── src/
│   │   ├── routes/        # API 路由
│   │   ├── models/        # 数据模型
│   │   ├── middleware/     # 中间件（鉴权等）
│   │   ├── utils/         # 工具函数
│   ├── package.json
├── cloudbaserc.json       # CloudBase 部署配置
└── README.md

第三步：生成代码（核心步骤）

3.1 生成策略：分模块并行

使用 subagent_spawn 并行生成不同模块，提高效率：

# 子代理 1：前端页面（general 类型）
subagent_spawn(type=general):
  "基于以下 PRD 信息，生成微信小程序 {项目名} 的完整前端代码：

  PRD 关键信息：
  - 技术栈：微信小程序原生框架 (WXML+WXSS+JS)
  - 页面列表：{页面结构}
  - 组件列表：{组件定义}
  - 角色体系：{角色权限}
  - 接口列表：{API列表}

  生成要求：
  1. 每个页面生成完整的 4 文件（wxml/wxss/js/json）
  2. 每个组件生成完整的 4 文件
  3. app.js：全局逻辑（onLaunch中调用云函数userLogin、全局角色判断）
  4. app.json：完整页面路由 + TabBar 配置 + window 配置
  5. app.wxss：CSS 变量体系 + 公共样式类（容器/卡片/按钮/文本/Flex/间距/状态标签）
  6. utils/：api.js(云函数调用封装)、auth.js(权限判断)、cloud.js(CloudBase初始化)、util.js(日期/格式化)
  7. 所有页面 JS 中 API 调用必须 try-catch，失败 fallback 到空数据
  8. 所有列表页支持下拉刷新 + 上拉加载更多
  9. 所有表单页有输入验证和提交防重复点击

  输出目录：/sandbox/workspace/{project}-dev/miniprogram/"

# 子代理 2：后端云函数（general 类型）
subagent_spawn(type=general):
  "基于以下 PRD 信息，生成 {项目名} 的完整云函数代码：

  PRD 关键信息：
  - 数据库设计：{6张表的字段定义}
  - 接口设计：{23个云函数的入参出参定义}
  - 角色权限：{4个角色的权限矩阵}
  - 支付流程：{微信支付+退款流程}

  生成要求：
  1. 每个云函数生成 index.js + package.json
  2. shared/ 模块：constants.js(7大类19个错误码)、auth.js(4角色权限矩阵验证)、db.js(数据库CRUD封装+事务)、response.js(统一响应{code,data,message})
  3. 每个云函数入口：
     - 获取 openid（wx.getServerContext）
     - 权限验证（auth.checkPermission）
     - 参数校验
     - 业务逻辑
     - 统一返回（response.success / response.fail）
  4. 支付相关：createPayment(paymentCallback)/applyRefund(refundCallback) 必须用 CloudBase 支付 SDK
  5. 数据统计类函数：支持分页查询 + 时间范围筛选

  输出目录：/sandbox/workspace/{project}-dev/cloudfunction/"

3.2 生成配置文件

配置提示词：
"生成以下配置文件：

1. cloudbaserc.json — CloudBase 部署配置
   - envId: 占位符 '{{CLODBASE_ENV_ID}}'（用户需替换）
   - functionRoot: ./cloudfunction
   - functions: 列出所有23个云函数名 + handler(index.main) + runtime(Nodejs18.15)

2. project.config.json — 小程序项目配置（appid 占位符）
3. sitemap.json — 小程序搜索配置（disallow 非公开页面）
4. README.md — 项目说明文档（产品定位、技术栈、功能模块、数据库、里程碑）"

3.3 代码自检 Checklist

生成完成后，逐项检查：

小程序前端自检：

小程序后端自检：

第四步：推送代码到仓库

4.1 克隆仓库 + 创建分支

# 克隆目标仓库
git clone --depth 1 \
  https://cnb:{CNB_TOKEN}@cnb.cool/{org}/{repo}.git \
  /sandbox/workspace/{repo}-repo

cd /sandbox/workspace/{repo}-repo

# 创建开发分支
git checkout -b feat/{branch-name}
# 分支命名规范：feat/miniprogram-dev / feat/web-spa-dev / feat/fullstack-dev

踩坑备忘：
- 如果 clone 报 IO 错误，用 API archive 方案（见第一步 1.1）
- 如果 sparse-checkout 导致 git add 报错：git config core.sparseCheckout false && git sparse-checkout disable

4.2 复制代码 + 提交

# 复制开发输出到仓库
cp -r /sandbox/workspace/{project}-dev/* /sandbox/workspace/{repo}-repo/

# 创建 .gitignore
echo "node_modules/\n.DS_Store\n*.log\n.env" > .gitignore

# 添加并提交
git add -A
git commit -m "feat: {项目名} {平台类型}完整开发

基于仓库中的 PRD（{PRD版本号}）文档，开发完整的{平台类型}项目。

技术栈：{技术栈描述}
前端：{页面数}个页面 + {组件数}个组件 + {模块数}个工具模块
后端：{云函数数}个云函数 + {共享模块数}个共享模块

使用流水线 ai-pipeline-factory-skill 开发"

4.3 推送 + 创建 PR

# 推送分支
git push -u origin feat/{branch-name}

# 创建 Pull Request（通过 CNB API）
curl -s -X POST "https://api.cnb.cool/{org}/{repo}/-/pulls" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "title": "feat: {项目名} {平台类型}完整开发",
  "body": "## {项目名} — 基于 {PRD版本号} 的完整开发\n\n基于仓库中的 {PRD版本号}（{章节数}章+附录）文档，开发完整的{平台类型}项目。\n\n### 技术栈\n- 前端：{技术栈}\n- 后端：{技术栈}\n\n### 前端（miniprogram/）— {页面数}个页面\n\n{页面列表}\n\n### 后端（cloudfunction/）— {云函数数}个云函数\n\n{云函数表格}\n\n---\n使用工作流 ai-one-shot-dev-skill 开发",
  "base": "main",
  "head": "feat/{branch-name}"
}
EOF

第五步：验收确认

5.1 PR 状态确认

# 查询 PR 状态
curl -s -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Accept: application/vnd.cnb.api+json" \
  "https://api.cnb.cool/{org}/{repo}/-/pulls/{pr_number}" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'PR #{d[\"number\"]}: {d[\"state\"]} — {d[\"title\"]}')"

5.2 代码统计

# 文件数 + 行数统计
cd /sandbox/workspace/{project}-dev
echo "总文件数: $(find . -type f | wc -l)"
echo "代码文件数: $(find . -type f \( -name '*.js' -o -name '*.json' -o -name '*.wxml' -o -name '*.wxss' \) | wc -l)"
echo "总行数: $(find . -type f \( -name '*.js' -o -name '*.json' -o -name '*.wxml' -o -name '*.wxss' \) -exec cat {} + | wc -l)"

5.3 完成标志

• ✅ PR 创建成功（state=open/closed+merged）
• ✅ 文件数 ≥ PRD 要求的功能覆盖
• ✅ 代码结构自检全部通过
• ✅ README.md 描述与 PRD 一致

提示词目录

版本迭代

踩坑备忘（来自锦鸿行实战）