最小例子：从零走完一次
用一个最小的练习需求「登录页底部加一行客服邮箱」，把工作台从环境检查到发布上线完整走一遍。每一步都写了：你说什么、AI 做什么、你检查什么、怎样算完成。照着做，大约 40 分钟。
| 阶段 | 步骤 | 你怎么完成 | 操作手册（直接定位） | 需要你拍板 |
|---|---|---|---|---|
| 准备（首次使用逐项完成） | 0. 安装环境 | 帮我运行 scripts/setup.sh 安装环境 | 安装与终端提示 | 密码 / 回车（出现时） |
| 0.4 配置 GitHub 只读密钥 | 找研发负责人获取只读 key，放进 git/keys/，让 AI 检查 | 获取密钥 · 放入文件夹 · 仓库配置 | — | |
| 0.5 配置 Cloudflare 发布账号 | 获取账号 ID、API Token，填写本机发布配置 | 找账号 ID · 创建 Token · 填写配置 | — | |
| 1. 配置后重新自检 | 帮我自检一下工作台 | 自检与报错处理 | — | |
| 开始 | 2. 发问卷，开新需求 | 填写问卷并粘贴给 AI | 打开问卷界面 · 启动流程 · 基线分支操作 | ✔ 版本号 + 基线 |
| 3. 澄清需求 | 回答 AI 问题，核对做什么 / 不做什么 | 澄清对话示例 | ✔ 需求要点 | |
| 做三件套 | 4. 做 demo | 开始做 demo | 制作与修改 · 查看手机效果 | ✔ demo 效果 |
| 5. 生成需求文档 | 生成需求文档 | 生成与修改 · 文档检查项 | ✔ 需求文档 | |
| 6. 生成并执行场景测试用例 | 生成并执行场景测试用例 | 执行测试 · 查看结果与录像 | ✔ 测试结果 | |
| 发布上线 | 7. 发布 | 发布这个版本 | 发布与查看线上版本 | ✔ 确认发布 |
| 8. 交给研发 | 生成交付说明 | 查找代码改动包 | — | |
| 收尾 | 9. 改一处再发布（可选） | 告诉 AI 修改内容，确认后重新发布 | 修改 demo · 覆盖发布 | ✔ 重新发布 |
完整步骤大纲：从安装环境到发布上线
首次使用先完成安装、配置和自检；后面的需求流程按拍板节点确认。括号里是这一步结束时会产生的东西。
- 安装环境（首次使用需要）
- 用 Claude Code 或 Codex 打开工作台文件夹，说「帮我运行 scripts/setup.sh 安装环境」
- AI 先解释操作，再启动安装；你只在需要时允许控制终端、输入电脑密码或按回车，AI 继续跟进
- AI 自动自检，缺账号配置时继续下面两步；操作说明见 安装手册
- 配置 GitHub 只读密钥（解决“未配置只读 key / 仓库无法访问”）
- 配置 Cloudflare 发布账号（解决“accountId / apiToken 未填写”）
- 重新自检（确认配置有效，必需项全部通过）
- 说「帮我自检一下工作台」；报错时按 自检处理表 继续处理，通过后再开需求
- 填问卷（得到一段给 AI 的开工内容）
- 打开 新需求问卷，填标题、负责人、想做什么 3 个必填项
- 基线选「基于 FanzyWeb 最新版本」（默认 master）；要用其他版本时，先问开发要分支名再填
- 其余能填就填：背景、目标、页面入口、流程、不做什么、特殊情况、素材、演示数据、验收方式
- 右侧实时生成给 AI 的内容，检查无误后点「复制给 AI」
- 发给 AI（AI 开始执行启动流程）
- 在 Claude Code 或 Codex 里粘贴问卷内容
- 本地图片、视频直接拖进对话框；问卷里写了本地路径的，AI 会按路径读取
- 发送
- 启动确认（创建版本包：
prd/demo/testcases/三个文件夹）- AI 自动做环境检查；有 ✘ 先按提示处理
- AI 给出版本号（如
v2026.10.31-login-support）和标题，你确认或修改 - AI 拉取所选基线代码，汇总「需求 / 版本包 / 基线」，你确认
- 澄清需求（需求要点清单）
- AI 把问卷里所有空着、模糊或矛盾的问题一次性列出，每题附选项与推荐项；你按编号回答，或统一说「全部按推荐」
- AI 整理出「做什么 / 不做什么 / 验收标准 / 演示数据」，你确认
- 做 demo（可在浏览器打开的 demo）
- 说「开始做 demo」，AI 改代码、准备模拟数据、补齐所有语言的文案并打包
- 打开 AI 给的本地链接查看效果，想调整就直接说
- 满意后说「确认」
- 生成需求文档（带标注截图的需求文档页面）
- 说「生成需求文档」，AI 截图、标功能序号、逐条写做什么 / 不做什么 / 验收标准
- 检查标注位置和每条边界，确认
- 生成并执行场景测试用例（可搜索、可播放录像的场景测试用例页面）
- 说「生成并执行场景测试用例」，AI 按验收标准写用例并逐条执行
- 全部通过就确认；有失败时决定修 demo 还是调整验收标准
- 发布上线（版本独立链接 + 工作台首页入口）
- 说「发布这个版本」，AI 检查三件套，告诉你要上线什么、上线后的链接
- 你说「确认」，AI 通过 API 上传这个版本，并刷新工作台首页
- 用手机打开首页，点开三个按钮检查；说「看看线上有哪些版本」核对
- 交给研发（一段可以直接发群的交付说明）
- 说「生成交付说明」，复制发到研发群
下面用练习需求把每一步的真实对话演示一遍。
0. 安装与配置（第一次用才需要）
0.1 打开工作台，让 AI 安装
- 拿到工作台文件夹，用 Claude Code 或 Codex 打开它。不知道怎么打开时，查看 快速入门 · 用 AI 打开工作台。
- 复制下面的话发给 AI，不需要自己输入安装命令。
Homebrew 用来安装和管理开发工具；配套的测试浏览器供 AI 自动截图、测试和录屏使用，会单独存放，不影响你平时使用的 Chrome。
0.2 需要你操作时，看这三种提示
| 你看到什么 | 你怎么做 | 之后谁继续 |
|---|---|---|
| 系统询问是否允许 AI 控制「终端」 | 选择「允许」。这只授权打开终端，不代表安装完成。 | AI 启动安装并检查进展 |
终端出现 Password: | 在终端输入电脑开机密码，按回车。输入时不显示字符，是正常现象。 | 安装程序继续；AI 检查是否还有提示 |
终端出现 Press RETURN/ENTER to continue | 按一次回车。 | 安装程序继续下载和安装；AI 跟进结果 |
AI 做什么：安装过程中检查同一个窗口或安装进度，告诉你当前在装什么。下载慢或失败时，由 AI 检查原因；不会要求你再问「下一步怎么做」才继续。你说「已经允许了」时，AI 会核实实际进度，不会直接当成成功。
0.3 等自动自检，分清安装结果
| AI 告诉你的结果 | 接下来怎么办 |
|---|---|
| 安装及自检全部通过 | 可以进入下面第 2 步；这次刚得到的自检结果可以沿用。 |
| 工具、依赖和测试浏览器已安装，但缺 GitHub / Cloudflare 配置 | 继续下面 0.4 补配置，不用反复运行安装。 |
| 安装失败，停在某一步 | AI 说明具体原因并处理或安全重试；不能把失败说成完成。 |
0.4 配置 GitHub 只读密钥
git/github_readonly 存在，且当前没有有效的密钥配置，AI 会先问「是否使用 ifanzy-web 的默认配置只读认证？」。回复「使用默认只读认证」后，AI 更新本机认证配置并自检，无需重新生成密钥；未同意时配置不变。只有连接检查通过，才代表认证可用。- 向研发负责人索取
github_readonly，由负责人按 生成密钥与仓库授权说明 完成只读授权。 - 按 把私钥放进工作台：访达 → 工作台文件夹 →
git→keys，放入没有.pub扩展名的github_readonly。 - 对 AI 说「只读密钥已放好，请按现有文件配置 GitHub 只读访问并自检」，由 AI 按 仓库地址、默认分支与密钥路径 核对本机配置。不要把密钥内容发到聊天里。
完成标志：自检报告 GitHub 仓库可以访问。失败时查看 GitHub 常见问题，不能仅凭文件已放好就判断成功。
0.5 配置 Cloudflare 发布账号
- 已有账号可直接继续；没有时按 Cloudflare 账号 注册或向管理员索取。
- 按 账号 ID：对应后台界面与复制方法 获取
accountId。 - 按 API Token：创建入口与权限设置 获取
apiToken。 - 按 发布手册 · 一次性配置 把这两个参数填入本机
deploy/cloudflare.json；填写位置也可查看 快速入门 · 放 key、填参数。项目名按 项目名与站点地址 核对，首次发布会自动建项目。 - 填好后说「发布配置已填好，帮我自检一下工作台」。校验只检查配置，不会发布。
完成标志：自检报告 Cloudflare 配置有效。权限或 Token 报错时查看 发布常见报错，处理后再自检。
完成标志：安装任务已结束，AI 明确报告自检通过。只有文件存在不代表配置有效；检查未通过时先处理，再进入新需求流程。
1. 环境检查
操作手册：自检与报错处理（直接跳到对应章节）。
你检查：必需检查项全部通过。没有历史需求时，可能提示代码尚未克隆，AI 会在开始需求时处理；发现未完成需求时，先按 AI 提示决定继续还是新建。有 ✘ 怎么办：AI 会说明原因并给出链接，按 配置获取指南 · 自检 处理后，再说一次「帮我自检一下工作台」。刚在第 0 步自检通过且环境没有变化，可以沿用结果。
2. 发问卷，开新需求
操作手册：新需求启动流程（直接跳到对应章节）。
打开 新需求问卷，只填下面几项（其余空着），点「复制给 AI」，粘贴发送：
需求标题：练习：登录页客服邮箱
负责人：（你的名字）
想做什么：手机 H5 登录页最下方加一行小字「Need help? support@fanzy.example」，未登录的访客都能看到，点邮箱可以复制
基线：基于 FanzyWeb 最新版本（默认 master）
这次明确不做的：不做真实发邮件、不改登录逻辑
你会怎么检查做对了：登录页底部能看到这行字；点邮箱后提示已复制你检查：版本号和基线分支是你想要的。完成标志：打开版本首页（本地预览），能看到「练习：登录页客服邮箱」这一行，状态是「启动确认」。
3. 澄清需求
本步骤的待确认问题会一次性整理，不需要每回答一项就等待下一个问题；已确认的内容不重复询问，只有新依赖或矛盾才补问。
操作手册：需求澄清对话示例（直接跳到对应章节）。
完成标志：AI 说「已记录，进入 demo」。
4. 做 demo
操作手册：查看 demo 与手机效果（直接跳到对应章节）。
你检查：打开链接，拉到最底部看到那行字；点邮箱看到 Copied 提示；想调整就直接说，例如「字再小一点，颜色淡一点」。
完成标志：AI 记录「demo 已确认」。
5. 生成需求文档
操作手册：文档内容与检查项（直接跳到对应章节）。
你检查：截图上的 ①② 位置对不对；每条的「不做什么」是否和你想的一致；文档最后新增国际化文案表是否涵盖全部新增 key 和所有语言。完成标志：你说「确认」。
6. 生成并执行场景测试用例
操作手册：结果页、失败原因和录像（直接跳到对应章节）。
你检查：点开任意一条场景，按上一步/下一步查看操作与触发位置，再播放顶部总录像；用搜索框搜「复制」能找到 TC-02。完成标志：全部通过，你说「确认」。有失败时 AI 会问你是修 demo 还是改验收标准。
7. 发布上线
每次发布都检查默认「登录页新人福利提示」模板，线上缺失才补发；已存在不重传。发布核验通过后，AI 必须列出首页、demo、需求文档、测试报告/录像的四个完整网址。详见 模板检查及完整路径交付格式。
操作手册：发布与查看线上版本（直接跳到对应章节）。
你检查：
- 用手机打开工作台首页，找到「练习：登录页客服邮箱」，三个按钮都能打开
- 在 demo 页面里刷新一次，页面正常（不是 404）
- 对 AI 说「看看线上有哪些版本」，列表里有这个版本
完成标志：以上 3 项都正常。全程不需要打开 Cloudflare 后台。
8. 交给研发
操作手册：查找代码改动包及文件清单（直接跳到对应章节）。
完成标志：把这段文字复制发到研发群。代码不需要你提交，研发会按正式规范重新实现。
9. 改一处再发布（可选，体验覆盖更新）
操作手册：再次发布与查看线上版本（直接跳到对应章节）。