#AI 接管需求开发工作流（前端）

Command 前端 JoySpace Gate 制

Cursor Command，源文件：commands/ai-demand-dev-workflow.md。面向前端需求的全流程编排：从 PRD 理解到 JoySpace 子 PRD / TRD 落盘，再到仓库定位、分支、实现与交付；每个 Gate 出口必须通过 AskQuestion 确认后才能进入下一环节。

#1. 目标与范围

• 面向前端需求，覆盖：PRD 解析、JoySpace 前端子 PRD 落盘（PRD 模版页：JoySpace 模版）、仓库定位、分支准备、代码实现、TRD 交付。
• 目标：降低误解和误操作，保证每次交付都可复核、可回溯；已确认的 PRD 功能点在进仓库前有一份可分享的子 PRD 链接。

#2. 规则优先级

1. 工作区/目录规则（workspace-level）
2. 仓库内规则（repo-level）
3. 本命令中 Gate + AskQuestion 硬约束（执行本工作流时，与各 Gate 冲突的「直接推进」行为以本命令为准）

冲突时按高优先级覆盖，并在执行说明中明确采用依据。

#3. JoySpace 协作总则

• 涉及 JoySpace 文档读写时，默认使用 joyspace-official-full。
• 若本技能与 joyspace-official-full 冲突，JoySpace 路由以 joyspace-official-full 为准。
• TRD 主交付默认是 JoySpace 在线链接，不以本地文档作为主交付。
• TRD 与 前端子 PRD（Gate-1.5）均为 JoySpace 独立产物，但 实现方式统一：均从指定模版页读取正文结构，走 get_normal_json_content → 模版 JSON 内原位填空（严禁增删节点、改变节点类型、调整节点顺序；只允许填写叶子节点的文本内容，详见 5.12）→ create_doc_routing（不传 source_page_id）且 content 为 trim 后以 [ 开头的整包 Slate JSON 数组字符串 → get_normal_json_content 回读校验。禁止将 clone_doc_routing 或 create_doc_routing + source_page_id 的「克隆 + 键值文本填空」作为子 PRD/TRD 的主创建路径（与 joyspace-official-full 中 TRD/整包 JSON 约定一致时，以技能为准）。

#4. 标准执行流水线（Gate 制）

#4.0 AskQuestion 硬约束（全流水线）

• 工具：使用 Cursor AskQuestion（多选/单选结构化提问；用户口语中的「askquestions」均指此工具）。
• 硬规则：每个 Gate 出口必须先发起 AskQuestion，仅在工具返回用户选择后才允许进入下一 Gate；在此之前 禁止 任何「下一步」动作，包括但不限于：读/写业务代码、git 分支与提交、除 Gate-1.5 规定动作外的 JoySpace 写回、扩大检索范围、替用户默认「已确认」等。
• Gate-1.5 例外：在 Gate-1 出口 AskQuestion 已确认「PRD 理解完整且继续」之后、进入 Gate-2 之前，必须执行一次 前端子 PRD 的 JoySpace 创建（见 Gate-1.5 与 5.9）；该创建视为 Gate-1 的固定收尾动作，不属于 Gate-2 及之后的提前越权。
• 有效回答：以 AskQuestion 的返回结果为准。若用户只在对话里文字回复而未触发工具选择，须 再次 用 AskQuestion 将关键决策收敛为选项，直到拿到工具返回。
• 例外：用户在该 Gate 内 明确指令「跳过确认 / 本环节免 AskQuestion」时，须在回复中 逐字引用 该指令并说明跳过范围；无此明确指令不得跳过。若用户声明 跳过 JoySpace 子 PRD 创建，须逐字引用；未声明则 Gate-1 选择继续后 仍须 执行 Gate-1.5。
• Gate 与提问对应（每 Gate 至少一题；可拆多题但不得合并跳过）：

#Gate-1：PRD 识别与确认

• 提炼并输出：需求目标、交互规则、字段约束、前端校验、接口契约、异常话术。
• 出口：使用 AskQuestion 收集用户对「PRD 理解是否完整、是否继续」的选择；未返回选择前不得执行 Gate-1.5、不得进入 Gate-2；若否认，补充信息后重做 Gate-1 并再次 AskQuestion。
• 用户选择「继续」后：必须先完成 Gate-1.5，再进入 Gate-2。

#Gate-1.5：前端子 PRD（JoySpace，硬约束）

• 触发：仅当 Gate-1 出口 AskQuestion 已确认「继续」且 PRD 功能点已对齐后执行；禁止在 Gate-1 确认前创建。
• 保存位置（固定）：team_id=root，folder_id=kQ4IlPyqrperGy9y7I8t（目录链接：保存目录）。用户在本命令中另有逐条明确覆盖指令时可改，否则不得改目录。
• 模版页（固定）：page_id=IBvvS7O8yQcuAwqpRf6N（PRD 模版页）。创建时不得传 source_page_id：必须先 get_normal_json_content(IBvvS7O8yQcuAwqpRf6N)，在模版 JSON 结构内原位填空后，将整包 JSON 数组作为 create_doc_routing 的 content 一次性新建文档（与 5.9 一致，与 TRD 的 5.3 同型）。
• title 建议：【子PRD-前端】{需求简称}（与主需求可区分即可）。
• 填写原则：与 5.6 同型——字段即回答；证据以 Gate-1 已确认 PRD 为主（尚无代码实现，禁止编造接口/页面事实）。
• 前端相关图片与交互图识别迁移（硬约束）：在 get_normal_json_content 获取主 PRD Slate JSON 后，同时扫描 type: "img" 与 type: "boardmix" 节点，按 5.10 判定标准识别「前端相关」图片与交互图；将纳入的 img 节点（完整保留 url、width、height）和 boardmix 节点（完整保留 boardId、temp）嵌入子 PRD 2.2 表「示意图」列对应单元格，不得因数量多而全部省略；img 的 url 直接复用原始链接，禁止重新上传；boardmix 节点前建议加加粗标注说明来源。详细判定规则与已知限制见 5.10。
• 完成定义：create_doc_routing 成功且须回传新建页 link；并执行 get_normal_json_content(新 page_id) 回读校验；若任一步响应含 alignment_check，须在同一回合输出 matched/total/allMatched 及未命中项摘要。
• 禁止：未完成本子 PRD 创建并回传链接即开始 Gate-2 的仓库扫描、git fetch/checkout、或改动业务代码；禁止用克隆模版链替代整包 JSON 新建（见 3、5.9）。

#Gate-2：仓库定位与确认

• 进入条件：Gate-1.5 已完成且子 PRD 链接已交付。
• 子 PRD 实时拉取（硬约束）：进入 Gate-2 的第一步必须执行 get_normal_json_content(子PRD page_id) 拉取子 PRD 当前最新内容——子 PRD 在 Gate-1.5 创建后可能已被人工编辑；以本次拉取结果作为 Gate-2～Gate-5 所有工作的唯一需求依据，不再以原始主 PRD 为主要依据。若拉取内容与 Gate-1.5 回读版本存在差异，须在回复中摘要说明变化点。
• 扫描本仓库并定位改动文件（依据：最新子 PRD 内容）。
• 在本仓库先同步基线分支：优先 master，不存在则 main，并回报结果。
• 输出「文件候选 + 置信度」。
• 出口：AskQuestion 确认「仓库/文件与基线结论是否采纳、是否进入 Gate-3」；未返回选择前不得创建分支或进入 Gate-3。

#Gate-3：分支准备

• 从基线分支创建语义化分支并建立远端 tracking。
• 回报：本地分支、远端分支、tracking 状态。
• 出口：AskQuestion 确认「分支状态是否可开始实现、是否进入 Gate-4」；未返回选择前不得改动业务代码或进入 Gate-4。

#Gate-4：代码实现与自检（仅在此环节进行业务代码的改动，其他环节严禁改动代码）

• 仅在 Gate-1.5 与 Gate-2～Gate-3 全部完成且 Gate-3 出口 AskQuestion 已通过后改代码。
• 实现前子 PRD 刷新（硬约束）：开始写任何业务代码前，必须再次 get_normal_json_content(子PRD page_id) 拉取最新子 PRD（Gate-2→Gate-3 期间可能再次被人工编辑）；若内容有变化须在回复中摘要说明，并以最新版为实现依据。
• 最低自检：关键路径、异常分支、权限控制、接口字段影响。
• 出口：AskQuestion 确认「实现与自检是否认可、是否进入 Gate-5（收尾与 TRD）」；未返回选择前不得写 TRD、不得执行 Gate-5 中的 TRD JoySpace 写回、不得宣称交付完成（Gate-1.5 子 PRD 不在此限，因其已在 Gate-1 后完成）。

#Gate-5：收尾与交付

• TRD 前子 PRD 最终拉取（硬约束）：写 TRD 前，必须再次 get_normal_json_content(子PRD page_id) 取子 PRD 最新版，以其内容作为 TRD 需求依据（而非原始主 PRD）。
• 交付项：改动文件清单、关键行为变化、验证建议、风险点、TRD（强制按照 5. TRD 专项规范 下的约束来写 TRD）。
• 出口：交付内容展示后，AskQuestion 做闭环确认（例如：交付是否收悉、是否还有修订）；未返回选择前不得结束会话或静默收尾。

#5. TRD 专项规范

#5.0 与 Gate / AskQuestion 的关系（硬约束）

• TRD 与 Gate-1.5 子 PRD 均走 整包 Slate JSON 原位填空 + 无 source_page_id 的 create_doc_routing（详见 5.3、5.9）；仅 模版 page_id、触发 Gate、证据来源 不同。执行 TRD 时 不得 用子 PRD 模版 IBvvS7O8yQcuAwqpRf6N 替代 5.2 中的 TRD 模板页；执行子 PRD 时 不得 用 TRD 模版页替代 IBvvS7O8yQcuAwqpRf6N。
• TRD 相关读写属于 Gate-5（或与 Gate-5 同步的收尾）范围；必须在 Gate-4 出口 AskQuestion 已通过 之后执行（用户未选「进入收尾」则不得开始 5.3 及后续写回）。
• 若 TRD 任务被单独触发，仍须在首次写回 JoySpace 前用 AskQuestion 确认：模板、目录、是否按本规范单路径执行；未返回选择前不得调用创建/写回接口。

#5.1 触发条件

• 任何跟 TRD 相关的动作
• 触发后先回显：
  • 已识别为 TRD 任务：将强制写回 JoySpace 并回传在线链接，不在本地生成主交付。

#5.2 默认模板与目录

用户在本命令中逐条明确授权时可覆盖目录或模版页；无授权则不得替换上述 PRD / TRD 模版 page_id。

#5.3 单路径执行（硬约束，TRD 模版）

1. get_normal_json_content 读取 TRD 模板 JSON（模版页见 5.2 中 TRD 模版页）。
2. 产出「字段 → 内容」映射；TRD 需求依据必须取 Gate-5 前最近一次 get_normal_json_content(子PRD page_id) 的实时内容（子 PRD 最新版），而非原始主 PRD 文本。
3. 在模板 JSON 结构内按行头/列头原位填空（命中才填，不确定留空）；严禁增删任何 Slate 节点、改变节点的 type 字段、调整节点顺序；只允许修改叶子 text 节点的字符串值（见 5.12）。
4. 使用创建 API：create_doc_routing，不传 source_page_id，将重写后的 整包 Slate JSON 数组字符串 作为 content 一次性新建文档。
5. get_normal_json_content（新文档 page_id）回读校验并输出统计。

子 PRD 与上列步骤 同型，仅模版与 Gate 不同，全文见 5.9。

禁止（同时约束 TRD 与子 PRD）：

• 不读模版直接创建文档内容
• 先 clone（含 clone_doc_routing 或 create_doc_routing + source_page_id）模版生成新文档再对该新文档做二次写入作为主路径
• 先建空文档再 markdown 覆盖
• 脱离模板结构全文重写
• 低置信度兜底乱填

#5.4 内容落位硬约束

• （TRD 模版） 流程图必须是 Mermaid flowchart TD，落在 2.1、方案流程图 小节（text-draw/diagram 兼容）。
• 表格必须按模板行头/列头落位。
• 评审区与 checklist 区默认禁填。
• 不确定信息留空，禁止「待补充/待确认」。
• （子 PRD 模版 IBvvS7O8yQcuAwqpRf6N） 以该页 实际 Slate 节点 为准落位；若无与 TRD 同名的「2.1」小节，不得为凑 TRD 格式而插入无关标题，但仍须满足：表格按行列头原位、diagram 类节点按模版语义（若有）、不确定留空。

#5.5 完成定义与校验输出

• 至少校验：与模版内容对比有新增/变更、关键字段可回读；TRD 另须满足 5.4 中流程图等 TRD 模版专属项；子 PRD 以 5.9 完成定义为准。
• 若返回 alignment_check，必须输出：matched/total/allMatched + 未命中项。
• 以下任一缺失视为未完成：
  • JoySpace 链接
  • 回读校验结果
  • TRD：流程图落位结论（模版要求时）；子 PRD：按 5.9 模版结构可核验的落位结论（无流程图节点则注明「模版无 diagram 要求」并跳过该项）

#5.6 字段即回答（新增硬约束）

• TRD 与 子 PRD 填写方式均必须是「像回答问题一样回答每个 JSON 字段」，禁止先写长篇摘要再反推字段。
• 执行顺序固定为：字段盘点 → 证据收集 → 字段映射 → 原位回填 → 回读校验。
• TRD：每个已填字段都必须可追溯到证据来源（PRD 原文、代码实现、接口/DTO、日志逻辑）。
• 子 PRD（Gate-1.5 阶段）：证据以 Gate-1 已确认主 PRD 为主；尚无代码事实时 不得 用实现细节冒充 PRD 依据。
• Gate-2 及以后各阶段：需求依据切换为「最新实时拉取的子 PRD 内容」（见各 Gate 子 PRD 实时拉取规则）；主 PRD 仅作背景参考，以子 PRD 最新版优先。
• 无证据字段必须明确填「未提供/无法确认」（若模板要求留空则留空），禁止猜测。
• 事实冲突时按优先级处理：代码实现事实 > PRD 描述 > 口头推断；并在文档中显式说明差异。

#5.7 证据驱动填充清单（新增）

生成 TRD 或 子 PRD 前，至少提取以下事实（子 PRD 阶段尚无代码时，以 PRD 与已确认交互为准，缺项留空）：

• 前端：页面位置、交互入口、校验规则、提示文案、权限置灰/拦截逻辑。
• 后端：权限校验条件、参数约束、业务标签同步、日志写入、异常返回文案。
• 接口与数据：入参、出参、DTO/VO 字段名、关键枚举/常量。

「需求点拆分」必须采用：PRD-点 → 实现(代码事实) → 验收(可验证结果)。

范围In/Out、风险回滚、监控点位 必须绑定具体字段或接口名，避免抽象描述。

#5.8 仓库状态异常处理（新增）

• 若用户要求「直接 TRD」且仓库目录无 .git，不得编造分支信息；在对应字段写「无法确认」。
• 若「已有改动」无法通过 git diff 直接获得，允许通过代码检索与关键类/页面读取补证据。
• 任何无法确认项统一按「不确定信息留空/标记未提供」处理，不影响 TRD 主路径继续执行。

#5.9 子 PRD 单路径（整包 Slate JSON，与 5.3 同型）

• 适用范围：Gate-1.5；模版页固定为 IBvvS7O8yQcuAwqpRf6N；保存目录固定为 上文 Gate-1.5 中的 team_id=root + folder_id=kQ4IlPyqrperGy9y7I8t。
• 步骤（与 5.3 一致，仅将「TRD 模板」替换为「子 PRD 模板 page_id」）：
  1. get_normal_json_content（page_id=IBvvS7O8yQcuAwqpRf6N）读取模版 JSON。
  2. 产出「字段 → 内容」映射（仅基于 Gate-1 已确认材料）。
  3. 在模版 JSON 结构内 原位填空（命中才填，不确定留空）；严禁增删任何 Slate 节点（img/boardmix 嵌入除外，见下）、改变节点 type、调整节点顺序；只允许修改叶子 text 节点的字符串值（见 5.12）；同时按 5.10 规则从主 PRD Slate JSON 中识别前端相关 img 节点与 boardmix 节点，将其嵌入 2.2 表「示意图」列对应单元格（boardmix 节点前加加粗标注说明来源）——此为唯一允许向模版 JSON 追加节点的例外场景。
  4. create_doc_routing：不得传 source_page_id；content 为 trim 后以 [ 开头的 整包 Slate JSON 数组字符串；title 建议 【子PRD-前端】{需求简称}；team_id / folder_id 同 Gate-1.5。
  5. get_normal_json_content（新建文档 page_id）回读校验并输出统计。
• 落位与禁填：遵守 5.4 中适用于子 PRD 模版的分支说明；评审区 / checklist（若模版存在）默认禁填，同 TRD 约定。
• 禁止：使用 clone_doc_routing 或 create_doc_routing + source_page_id 作为子 PRD 主路径；禁止整包 JSON 与「键: 值」克隆填空形态混用。

#5.10 子 PRD 图片与交互图识别迁移规则（Gate-1.5 专用）

• 触发：创建子 PRD（Gate-1.5）时，从已获取的主 PRD get_normal_json_content 结果中同时扫描 type: "img" 和 type: "boardmix" 节点。
• 判定为前端相关（纳入子 PRD）：
  1. 节点位于「功能需求」大章节范围内（含该节所有子行、表格、多栏布局内）；
  2. 节点位于含「原型」「交互图」「示意」「UI」「pc」「app」「商家端」「运营端」等关键词的标题、表格列头或段落标注所属范围内；
  3. 无法明确判断归属时，默认纳入（宁多勿漏）。
• 判定为非前端相关（排除）：
  1. 节点位于「概述」「背景」「竞品分析」「用户分析」「指标支撑」「名词解释」「总体流程（系统架构）」等非功能需求章节；
  2. 节点位于「联动报备」「资金安全」等运营/合规章节；
  3. 明确标注为纯后端架构图或数据流图。
• 落位规则：
  • 按「运营端」「商家端（PC）」「商家端（App/各场景）」等模块分组；
  • 嵌入子 PRD 2.2 表「示意图」列对应行的单元格；img 节点与 boardmix 节点可在同一单元格内并列；
  • boardmix 节点前建议插入一个加粗标注 p 节点（如「批量导入交互图」）以说明来源；
  • 若图片/交互图数量过多导致单元格过长，可在 2.2 节末追加段落分组展示（保留段落标题说明来源）。
• 格式：
  • img 节点：完整复用原 Slate img 节点（type: "img", url, width, height），id 由服务端自动重新分配；不改 url，不重新上传。
  • boardmix 节点：完整复用原 Slate boardmix 节点（type: "boardmix", boardId, temp），id 由服务端自动重新分配；直接使用主 PRD 原始 boardId。
  • JoySpace API 创建新文档时会将每个 boardmix 的白板内容克隆为独立副本（boardId 重新分配，内容与原始白板相同）；回读时看到的 boardId 与主 PRD 不同属预期行为，子 PRD 中的嵌入框展示的是克隆副本，内容可用，无需额外处理。
• 禁止：以「图片/交互图过多/太占篇幅」为由省略全部 img 或 boardmix 节点；不得只贴图片链接或 boardmix 链接文字替代对应节点。

#5.11 Slate 内容格式规范（人类可读性硬约束）

同时适用于 TRD 与 子 PRD（Gate-1.5）；不符合本节约束的文档视为未完成。

• 分点独立节点：凡涉及多条规则/步骤/字段时，每一条必须拆为独立的 Slate 节点（p 或 list）；禁止将多条内容用 \n 拼成单个 text 字符串——即使内容视觉上是换行，也不合格。
• 表格单元格：table-cell.children 内须有多个 p/list 节点，每段/每条一个节点；涉及「入口」「权限校验」「输入校验」「去重」「生效范围」「交互」等标签类内容，每个标签单独一个节点。
• 关键词加粗：列表条目中的标签/属性名（如 入口、权限校验）使用行内加粗 run，后接说明文字在同一节点 children 内。
• 段落标题：概述类内容（背景/目标/收益/边界）保持 list 节点或独立 p 节点，不退化为单一长文本块。
• 嵌套层次：table-cell → p/list → children（含文本 run）；禁止在 table-cell.children 内直接放裸 text 对象，须包裹进 p/list 节点。
• 验收标准：回读校验时，任一 table-cell.children 若仅包含单条带 \n 的纯文本，视为不合格，须重建。

#5.12 模版 JSON 结构锁定（硬约束，同时适用于 TRD 与子 PRD）

核心原则：模版 JSON 是只读骨架，Agent 只允许填写内容，不允许改动结构。任何违反本节约束的文档视为未完成，必须重建。

#允许的操作（白名单，仅此三项）

#禁止的操作（黑名单，以下任一均视为违规）

• 增删节点：禁止向模版 JSON 中新增或删除任何 Slate 节点（p、list、table、table-row、table-cell、h1～h6 等），示意图单元格的 img/boardmix 嵌入除外。
• 改变节点类型：禁止将节点的 type 字段从一种改为另一种（如 p → list、h2 → p）。
• 调整节点顺序：禁止对任何层级的节点数组进行重新排序。
• 改变表格结构：禁止增删表格行（table-row）或表格列（table-cell），不得合并或拆分单元格。
• 改变标题层级：禁止修改标题节点的 type（如 h1→h2）或删除标题节点。
• 插入额外章节：禁止为「凑格式」或「补充说明」而在模版结构外插入新的标题/段落节点。
• 删除空节点：禁止以「节点为空/无内容」为由删除模版中的占位节点；不确定内容留空（{"text": ""}），不得删节点。
• 重写整包结构：禁止抛弃模版 JSON、从零生成新的 Slate 结构替代原模版骨架。

#校验卡点

回读校验（get_normal_json_content 新文档）时，须额外核查：

1. 顶层节点数量与模版原始节点数量一致（img/boardmix 嵌入行除外）；
2. 所有标题节点的 type 与模版一一对应；
3. 所有表格的行数、列数与模版一致；
4. 若上述任一项不符，须在回复中明确报告差异，并说明是否属于本节允许的例外。

#6. 语言与输出风格

• 非代码内容默认中文；代码标识、URL、接口名、分支名可保留原文。
• 默认低噪输出：仅保留「结论、证据、下一步」。

#7. 固定输出模板（复用）

说明：以下「模板」为对用户展示的文案要点；不得仅用自然语言代替确认——每个 Gate 出口仍须配合 AskQuestion 选项（如：进入下一 Gate / 留在本 Gate 补充 / 终止）。

#7.1 Gate-1 模板

我识别到的功能点如下，请确认是否完整。确认后我将按固定目录与模版在 JoySpace 创建【子PRD-前端】并回传链接，再进入仓库定位。

（紧跟 AskQuestion：PRD 理解是否完整、是否继续。）

#7.2 Gate-1.5 子 PRD 回报模板

• 子 PRD 链接：<joyspace-url>
• 保存目录：保存目录
• 所用模版：PRD 模版
• 创建方式：整包 Slate JSON 原位填空 + create_doc_routing（无 source_page_id），见 5.9
• 回读校验：新文档 get_normal_json_content 要点摘要
• alignment_check（若有）：matched/total/allMatched；未命中：<fields>

#7.3 Gate-2 模板

我判断改动仓库/文件如下，请确认是否准确。确认后我再创建分支并开始改动。

（紧跟 AskQuestion：候选与基线结论是否采纳、是否进入 Gate-3。）

#7.4 Gate-3 模板

分支已准备：本地分支 / 远端 / tracking 如下。请确认是否开始改代码。

（紧跟 AskQuestion：是否进入 Gate-4。）

#7.5 Gate-4 模板

代码与自检要点如下。请确认是否进入收尾与 TRD（Gate-5）。

（紧跟 AskQuestion：是否进入 Gate-5。）

#7.6 Gate-5 闭环模板

交付项已列出（含 TRD 链接与校验）。请确认是否收悉或需修订。

（紧跟 AskQuestion：闭环确认。）

#7.7 TRD 结果模板

• 链接：<joyspace-url>
• 校验：matched/total/allMatched
• 未命中：<fields>
• 说明：评审区/checklist 已留空，不确定项已留空

#7.8 TRD 字段映射回报模板

• 证据来源：PRD + 代码实现 + 接口/DTO
• 填写策略：字段即回答，逐字段回填
• 不确定项处理：留空/未提供（不猜测）

#文件导航