使用规范
怎么用 AI 做一个需求：先看启动流程，再跟着完整例子走一遍。
一、一句话说明
每个需求交付三样东西，都在同一个预览地址下：
可演示的 demo
在 fanzy-web 上真实改出来的页面，可以点、可以操作。
需求文档
界面截图 + 功能序号标注，逐条写「做什么 / 不做什么 / 验收标准」。
场景测试用例
基于 demo 整理场景路径，可检索，逐步回放操作标注，并查看模块总录像。
二、新需求启动流程（每次开新需求都必须走）
你只需要说「开始一个新需求」，AI 会按下面 4 个阶段执行。同一阶段的待确认问题会一次性整理给你，各阶段的拍板节点仍分别确认。
第 1 步：准备检查（AI 自动执行，你只看结果）
| 检查项 | 不通过时 |
|---|---|
| Node / pnpm / git 环境 | 对 AI 说「帮我运行 scripts/setup.sh 安装环境」；AI 先说明密码和回车提示，再启动并跟进安装，结束后自动自检 |
| GitHub 只读 key 能否连通 | 指向 配置获取指南 · GitHub |
| Cloudflare 配置是否有效（只校验，不发布） | 指向 配置获取指南 · Cloudflare |
| Claude / Codex 规范是否同步 | AI 自动修复 |
| 磁盘空间 | 提示清理 |
| 是否有未完成的需求 | 问你：先继续旧需求，还是开新需求 |
第 2 步：本次需求的版本号 / 需求标题
AI 会问你需求标题，并建议英文短名和版本号。三者确定后，生成唯一的版本包名，例如 v2026.11.05-member-renew：
- 需求标题：中文，例如「会员续费提醒弹窗」——显示在首页和文档标题
- 英文短名：例如
member-renew——用于文件夹和链接，避免中文链接被转码 - 版本号：默认今天日期
v2026.11.05；同一天第二个需求自动变成v2026.11.05-2
确认后 AI 会一次性创建三个同名版本包：
prd/v2026.11.05-member-renew/ 需求文档
demo/v2026.11.05-member-renew/ demo（含 meta.json：标题、负责人、基线、进度）
testcases/v2026.11.05-member-renew/ 场景测试用例第 3 步：选择基线代码
AI 会问：是否基于 fanzy-web 的最新代码迭代？
是（大多数情况）
AI 拉取最新代码，列出最近活跃的分支（更新时间、更新人）让你选。不选就使用默认主分支 master。
否，基于历史版本
AI 列出历史版本包，在某个旧 demo 的基础上继续修改。
不知道选哪个分支时，问研发「这个需求要基于哪个版本做」，或直接用默认。
第 4 步：启动确认
需求：会员续费提醒弹窗
版本包：v2026.11.05-member-renew
基线：3.10.3/dev @ f560e30（2026-10-30 Jason）
已创建：prd / demo / testcases 三个版本包
下一步：澄清需求边界你回复「确认」后正式开始。
三、完整例子：登录页新人福利提示
下面是用这套工作台真实做出来的一个需求，三件套都可以直接打开：
① 开工自检 + ② 启动流程
③ 澄清需求
AI 先整理完整问题清单再提问，避免一问一答地拆成多轮。批量回答后，AI 汇总「做什么 / 不做什么 / 验收标准」给你统一确认，再进入 demo。
④ 做 demo
AI 实际做的：在独立工作区修改 5 个文件（新增福利组件、模拟数据、多语言文案，在登录页挂载），打包到 demo/v2026.10.30-login-welcome/dist/，改动保存为 source.patch。
⑤ 需求文档
⑥ 场景测试用例
⑦ 发布
⑧ 交给研发
插曲 A：中途改需求
插曲 B：测试没通过
UI 与交互规范
工作台首页、手册、问卷、需求文档和场景测试报告统一采用同一套界面方案，后续更新和新生成页面默认沿用。保留现有布局、区域顺序、网格和手机适配，只优化背景、卡片表面、图标和交互反馈。
| 区域 / 状态 | 统一处理方式 |
|---|---|
| 界面、卡片、标题 | 近黑分层背景，少量暖金点缀，轻微表面提亮与细描边，标题配线性图标；信息卡片保持阅读属性 |
| 可点击卡片与按钮 | 默认可辨认；电脑悬浮提亮/轻微上浮；点击轻微按压；手机使用按压反馈 |
| 输入框 | 聚焦只高亮自身边框，不叠加外描边和光晕双框 |
| 键盘、选中、禁用 | 按钮、链接和可展开场景保留明确焦点；选中状态高亮；禁用项不冒充可点击入口 |
| 复制与测试回放 | 复制后给出明确反馈；步骤、主图、进度与缩略图选中同步；截图列表铺满内容宽度，超出后仅在自身区域横向滚动 |
| 动效与手机 | 180ms 轻动效，响应减少动态效果设置；检查电脑和 320/390px 手机，无整页横向溢出 |
维护入口：统一外观与状态在 assets/workspace.css，结构在 assets/site.css，标题图标在 scripts/ui-icons.mjs，所有生成页面由 scripts/page.mjs 自动加载。更新后由 AI 重新生成手册及版本文档/报告并检查交互，避免各页样式逐渐不一致。业务 demo 按 FanzyWeb 自身规范制作。
文案表与场景测试交付
文案使用位置按「界面-具体控件」描述，支持一键复制整张文案表。回放配有所有步骤的缩略图列表，播放同步选中，点击缩略图直接定位。总录像按可阅读的演示节奏录制，操作前后和模拟场景切换都留出查看时间。
demo 确认后，需求文档最后附「新增国际化文案」表，按本版本基线核对新增 key、使用位置与全部语言。场景测试用例页会声明其用途为研发、测试的场景路径参考，需要据此完善最终上线代码的正式测试用例。
每条场景可用「上一步 / 下一步 / 自动播放」查看操作前后的 HTML 图文回放；图中框出点击或输入位置，标注动作和模拟条件切换。顶部默认一段总录像录下整个需求的实际测试过程，不再按每条场景拆视频。独立交付模块才按模块分段；筛选重跑会明确标出只覆盖本次选中的场景，历史资料保留。
发布、交付与历史版本
- 发布前检查目标版本三件套和测试结果，并核实默认「登录页新人福利提示」模板是否已在线上；缺失才补发。
- 发布成功后核验线上访问，逐项展示工作台首页、demo、需求文档、测试报告/录像的完整网址，方便辨认和复制，不只给快捷入口名称。示例见 四个完整交付路径。
- 工作台首页始终是最新索引；同一版本重发更新原来的三个链接，地址不变。不同版本各自保留，已发布的旧版本不会被其他版本覆盖。
- 同一版本的三个链接不是每次发布的历史快照。需要同时保留修改前后成果时，先确认创建新版本包。详见 发布更新与历史版本规则。
四、规则
可以让 AI 做
- 开始需求、继续某个需求
- 拉最新代码、查看分支、换基线
- 改 demo 的样式、文案、交互
- 生成 / 修改需求文档、场景测试用例
- 发布、查看发布记录
AI 会拒绝
- 提交、推送代码，创建分支
- 让 demo 调用后端接口
- 发布到研发环境
- 把密钥写进任何页面或对话
- 删除版本包和发布记录
必须你拍板
- 启动汇总（版本包、基线）
- 需求要点清单
- demo 效果
- 测试失败怎么处理
- 发布
- 一个需求一个版本包：同一需求的修改覆盖原版本包；新需求开新的版本包
- demo 不涉及服务端：需求里的数据都是模拟的，需求文档会注明哪些是假数据；页面原有的其他内容可能因为没有后端而显示为空，属于正常现象
- 需要登录才能看到的页面：AI 会做一个免登录的演示入口
五、切换 AI 工具（Claude ⇄ Codex）
工作台的规范只有一份（AGENTS.md + skill），两个工具读的是同一份；需求进度记录在 demo/<版本包>/meta.json，不依赖对话记忆。
- 在 A 工具里做到任意阶段，直接关掉即可（改动已经保存在工作区）
- 用 B 工具打开同一个工作台文件夹
- 说「继续登录页新人福利需求」，AI 会读取进度记录并从上次的阶段接着做