SKILL.md 7.94 KB

Edit Raw Blame History



name: downstream-gen
description: A5 下游文档生成——基于 docs/01 和 docs/03 推导，一次性生成 docs/02 + docs/05 + docs/06 § 三 + docs/10，回填 REQ 卡片依赖接口，把模块清单追加到 docs/08 § 二。
user-invocable: false


allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion Bash(cat *) Bash(cp *)

所有输出必须使用中文。


downstream-gen


执行步骤


步骤 0：打印当前位置流程图

用 Bash 执行 cat 命令向用户展示当前位置流程图（stdout 即 ASCII 框图）：
cat "${CLAUDE_PLUGIN_ROOT}/skills/plan/downstream-gen/banners/flow.txt"


A. docs/02 — 开发计划（含 REQ 级开发顺序清单）

清单颗粒度：一行一个 REQ，同一模块的 REQ 必须连续排列。


构建模块依赖 DAG。
对每个模块内部构建 REQ 间依赖，得到模块内 REQ 顺序。
合成 req_order[]：按 module_topo_order[] 依次铺开每个模块内的 REQ 序列（同模块 REQ 连续）。

环依赖打破：


模块级：若模块 DAG 存在环（module_A ↔ module_B），按启发式（字母序 / 被依赖次数多者先）破环排出 module_topo_order，并在参与环的模块里第一个 REQ 的 note 字段填入原因（如 "A↔B 互依赖：先做 A 的骨架"）。

REQ 级（同模块内）：若模块内 REQ 互依赖，同样破环，note 填原因。
非环 REQ note 留 —。


为 req_order[] 每项生成字段：


index：行号（从 1 开始）

req_id：如 REQ-SYS-001


module_id：该 REQ 所属模块，如 module_sys


rationale（选中理由）：依赖驱动的简短描述，如 所属模块无依赖，基础模块 / 依赖 REQ-SYS-001 已在前 / 所属模块依赖 module_sys 已在前


note（备注）：默认 —；仅环依赖打破场景填原因


读取并填充 ${CLAUDE_SKILL_DIR}/templates/docs-02-template.md。
写入 docs/02-开发计划.md。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/02 开发计划已生成


B. docs/05 — API 接口契约


读取 ${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md，写入 docs/05-API接口契约.md 头部。
对所有模块的每个 REQ：读取并推断 ${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md，追加到 docs/05。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/05 API 契约已生成


B2. 回填模块头 + REQ 卡片的 TBD(A5) 字段


在docs/01-需求清单/*/_module.md（模块头）和 docs/01-需求清单/*/REQ-*.md（REQ 卡片）中搜索并回填 TBD(A5 自动补) 
打印回填统计：A5 回填 <M> 处模块"依赖模块" + <N> 处 REQ"依赖接口"。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] REQ 卡片依赖接口已回填


C. docs/06 — 页面清单

对每个有前端页面的模块：读取并填充 ${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md，追加到 docs/06-UI交互规范.md § 三。

完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/06 § 三 页面清单已填入


D. docs/08 — 追加模块清单

读 ${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md，按 module_id 字母序为每个模块渲染 bullet（模块元数据 + REQ 子项清单，REQ 序保持步骤 A 模块内顺序），追加到 docs/08。

完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] 下方模块列表已填入


E. docs/10 — 验收清单（项目级 SOP）
cp "${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md" docs/10-验收检查清单.md


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/10 验收清单已生成


F. 验证 + 勾选 docs/08 进度 + 结束 Plan


一致性检查 + 自主修复循环（最多 3 轮，docs/01 是 REQ SSoT 不动）：


检查项：


每个 docs/01 REQ 都出现在 docs/05（作为接口，如适用）

docs/02 § 二 的 module_id 集合 = docs/08 § 二 的 module_id 集合


不一致 → 按差异类型自主修复：


REQ 缺 docs/05 endpoint → 按步骤 B 规则为该 REQ 推测，并追加到 docs/05

module_id 缺 docs/08 § 二 → 按步骤 D 规则渲染该模块 bullet（含 REQ 子项），按 module_id 字母序插入正确位置

module_id 缺 docs/02 § 二 → 重算该模块的 req_order 段（步骤 A 子流程），按拓扑序插入 docs/02 § 二


修复后重跑检查；通过 → 进入 2；3 轮仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修复摘要让用户介入。


最终占位符扫描（覆盖 Plan 阶段全部产出）：


a. TBD → 自动补齐：Grep 搜索 TBD(A3 自动补) 和 TBD(A5 自动补)。有命中则就地补填（A3 残留 → 查 docs/03 填 依赖表；A5 残留 → 查 docs/05 按 REQ-ID 填 依赖接口），再 Grep 确认 0 命中；仍残留报错停下。

b. 【人工填写：...】 → QA 循环等用户补：
  循环执行直到搜索不到 `【人工填写：` 且用户选「继续」：
  - 0 命中 → 直接放行进入步骤 3
  - 有命中 → 打印残留清单（`<文件:行号> — <内容摘要>`），用 `AskUserQuestion` 弹「继续」/「有疑问想先沟通」二选一；用户回答后重扫验证再决定放行 / 继续循环

  **每次弹 QA 前都重扫一次**——保证用户看到的 N 是最新的，避免「用户以为填完但实际还有残留」直接放行。


完成后，用 Edit 在 docs/08-模块任务管理.md 勾选 A5 父项：


- [ ] A5 下游文档生成 — downstream-gen


打印 Plan 阶段终止横幅并停下（不自动进入 B 阶段）：

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [downstream-gen] ✅ Plan 阶段（A0~A5）全部完成

    所有规划文档已就绪，docs/08 § 一 全部勾选。

    ⚠️ 进入 B 阶段前必须完成：
      1. 审核 docs/01~10 + CLAUDE.md + sql/migrations/V1 + 各 scripts/*

      2. 把全部 Plan 产物 commit：
           git add -A && git commit -m "chore: plan phase done"

      3. 推到远程，按仓库状态二选一：

         情况 A — 远程仓库是全新的（尚无 main / master）：
           git remote add origin <gitlab-url>   # 若尚未添加
           git -c core.hooksPath=/dev/null push -u origin master

         情况 B — 远程已有 main 需要走 MR 审核：
           git checkout -b plan-init
           git push -u origin plan-init
           # 在 GitLab 打开 plan-init → main 的 MR，审核并合并

      4. 补齐 `.env.local` 三个 GITLAB_* 字段

         - `GITLAB_TOKEN`：去 GitLab Profile → Account → Private token 生成后粘贴
         - `GITLAB_PROJECT_ID`，`GITLAB_API_URL`：运行
           bash <plugin-skill-dir>/scripts/derive-gitlab.sh

      5. remote git 就绪后，再运行 /erp-workflow:coding-start
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


参考


${CLAUDE_SKILL_DIR}/templates/docs-02-template.md
${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md
${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md

${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md（追加到 docs/06 § 三）

${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md（模块 bullet 行模板）
${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md

${CLAUDE_SKILL_DIR}/scripts/derive-gitlab.sh（用户可选辅助：在 add origin 之后手动跑一次，自动派生 GITLAB_PROJECT_ID / GITLAB_API_URL 写入 .env.local）