claude-coding-flow 1.3.2 → 1.4.1

package/bin/flow.js

@@ -2,7 +2,7 @@
 
 const fs = require("fs");
 const path = require("path");
-const { spawn } = require("child_process");
+const { execSync, spawn } = require("child_process");
 
 const PKG_ROOT = path.resolve(__dirname, "..");
 const CWD = process.cwd();
@@ -35,7 +35,20 @@ function mkdirp(dir) {
 function init() {
   console.log(yellow("flow init"));
 
-  // Copy skill commands -> .claude/commands/
+  // 1. git init
+  const gitDir = path.join(CWD, ".git");
+  if (!fs.existsSync(gitDir)) {
+    try {
+      execSync("git init", { cwd: CWD, stdio: "pipe" });
+      console.log(green("  initialized: git repository"));
+    } catch (e) {
+      console.log(red(`  git init failed: ${e.message}`));
+    }
+  } else {
+    console.log(yellow("  skip (exists): git repository"));
+  }
+
+  // 2. Copy skill commands -> .claude/commands/
   const commandsSrc = path.join(PKG_ROOT, "commands");
   const commandsDest = path.join(CWD, ".claude", "commands");
 
@@ -54,7 +67,7 @@ function init() {
     }
   }
 
-  // Copy dashboard -> .dashboard/
+  // 3. Copy dashboard -> .dashboard/
   const dashSrc = path.join(PKG_ROOT, "dashboard");
   const dashDest = path.join(CWD, ".dashboard");
 
@@ -66,8 +79,10 @@ function init() {
     console.log(yellow("  skip (exists): .dashboard/"));
   }
 
-  // Create directories
-  mkdirp(path.join(CWD, "docs"));
+  // 4. Create directories
+  mkdirp(path.join(CWD, "docs", "apis"));
+  mkdirp(path.join(CWD, "docs", "images"));
+  mkdirp(path.join(CWD, "docs", "prds"));
   mkdirp(path.join(CWD, "skills"));
   mkdirp(path.join(CWD, ".worktree"));
 
@@ -89,9 +104,7 @@ function startDashboard() {
   if (fs.existsSync(requirements)) {
     console.log(yellow("Installing dashboard dependencies..."));
     try {
-      require("child_process").execSync(`pip3 install -r "${requirements}"`, {
-        stdio: "inherit",
-      });
+      execSync(`pip3 install -r "${requirements}"`, { stdio: "inherit" });
     } catch {}
   }
 

package/commands/bug-fix.md

@@ -20,8 +20,7 @@ model: inherit
 ### 目录结构
 
 ```
-.worktree/bug-fix/{模块名}-{module_id}/
-  ├── module.json
+.worktree/bug-fix/
   └── {bug标题}-{task_id}/
       ├── task.json
       ├── log.md
@@ -30,11 +29,11 @@ model: inherit
 
 ### 文件格式
 
-**module.json**：`{"id": "{module_id}", "name": "{模块名}", "type": "bug-fix", "created_at": "{timestamp}"}`
+**JSON 文件更新规则**：task.json、module.json 等数据文件用 **Read → 改字段 → Write** 整体重写，禁止用 Edit（单行 JSON 无法保证 old_string 唯一匹配）。log.md 追加内容用 Edit。
 
 **task.json**：
 ```json
-{"id": "{task_id}", "module_id": "{module_id}", "title": "{标题}", "type": "bug-fix",
+{"id": "{task_id}", "module_id": null, "title": "{标题}", "type": "bug-fix",
  "status": "running", "current_phase": 1, "prev_task_id": null,
  "phases": [
    {"phase": 1, "name": "定位", "status": "running", "started_at": "{ts}", "completed_at": null},
@@ -50,8 +49,7 @@ model: inherit
 ### ID 生成
 
 ```bash
-python3 -c "import datetime,random; print(f'mod-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
-python3 -c "import datetime,random; print(f'task-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
+python3 -c "import datetime,random; print(f'bug-task-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
 ```
 
 ---
@@ -73,53 +71,80 @@ python3 -c "import datetime,random; print(f'task-{datetime.date.today().strftime
 ### 前置
 
 ```bash
-cat .worktree/code-gen/*/module.json 2>/dev/null | python3 -c "import sys,json; [print(f'{m[\"id\"]}  {m[\"name\"]}') for l in sys.stdin for m in [json.loads(l)] if m.get('type','code-gen')=='code-gen']" 2>/dev/null
+cd $(git rev-parse --show-toplevel) && for f in $(find .worktree/code-gen -name module.json 2>/dev/null); do python3 -c "import json; m=json.load(open('$f')); print(f'{m[\"id\"]}  {m[\"name\"]}')"; done 2>/dev/null
 ```
 
 ### 第一步：选择 code-gen 模块
 
-有模块 → AskUserQuestion（header=模块，options=模块列表 + "全局搜索"，最多3个已有）；无模块 → 文字提问。
+**动态选项规则**：1-3 个 → AskUserQuestion 列出全部 + `全局搜索` + `自定义输入`；4+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `全局搜索` + `自定义输入`）。**无模块时直接输出文字提问"请输入模块名称"，禁止使用 AskUserQuestion，不推荐、不猜测模块名。**
 
 ### 第二步：选择溯源起点任务
 
 ```bash
-cat .worktree/code-gen/{模块名}-{module_id}/*/task.json 2>/dev/null | python3 -c "import sys,json; [print(f'{t[\"id\"]}  {t[\"title\"]}  prev={t.get(\"prev_task_id\") or \"无\"}') for l in sys.stdin for t in [json.loads(l)]]" 2>/dev/null
+cd $(git rev-parse --show-toplevel) && for f in $(find .worktree/code-gen/{模块名}-{module_id} -name "task.json"); do python3 -c "import json; t=json.load(open('$f')); print(f'{t[\"id\"]}  {t[\"title\"]}  prev={t.get(\"prev_task_id\") or \"无\"}')"; done
 ```
 
-AskUserQuestion（header=溯源起点）：每个任务一个选项 + "从首个任务开始"。选具体任务→从该任务沿 prev_task_id 向前溯源；选首个→从链头向后遍历。
+**动态选项规则**：1-3 个 → AskUserQuestion 列出全部 + `从首个任务开始`；4+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `从首个任务开始`）。选具体任务→从该任务沿 prev_task_id 向前溯源；选首个→从链头向后遍历。无任务时直接从源码搜索。
 
 ### 第三步：Bug 描述
 
-文字提问：`请详细描述你遇到的 Bug（现象、复现步骤、期望行为等）。`
-
-### 第四步：bug-fix 模块
-
-选已有 bug-fix 模块或新建（module.json 含 `type: "bug-fix"`）。
+直接文字提问：`请详细描述你遇到的 Bug（现象、复现步骤、期望行为等）。`
 
 ### 创建任务
 
 1. 生成 task_id
-2. `mkdir -p .worktree/bug-fix/{模块名}-{module_id}/{bug标题}-{task_id}/snapshots`
+2. `mkdir -p .worktree/bug-fix/{bug标题}-{task_id}/snapshots`
 3. 写入 task.json（related_task_id=溯源起点的 code-gen task_id，related_module_id=code-gen 模块 ID）
 4. `date '+%Y-%m-%d %H:%M:%S'` 获取时间戳，阶段一设为 running
 
 ### 定位逻辑
 
-**A. 指定任务向前溯源**：起始任务 → prev_task → ... → 链头，每个任务读 changes.diff + log.md + dev_doc，搜索 bug 关键词。
+按以下优先级逐步定位：
+
+**1. 优先：读取开发日志和代码快照**
+
+从溯源起点任务开始，优先读取 code-gen 任务的 `log.md` 和 `snapshots/changes.diff`：
+- `log.md`：包含需求收集、方案规划、代码生成全流程，可快速锁定 bug 引入环节（如用户补充信息、方案决策）
+- `changes.diff`：包含实际代码变更，直接搜索 bug 关键词定位代码位置
+
+按任务链顺序读取：链头 → 后续任务 → ... → 溯源起点。找到第一个引入 bug 关键词的任务即定位成功。
 
-**B. 从首个任务向后遍历**：按 prev_task_id 构建链 → 从链头逐个向后检查 changes.diff + log.md → 记录源头。
+**2. 补充：全局搜索**
 
-**C. 全局搜索**：
+当日志和快照未定位到时，搜索源码：
 ```bash
 grep -rn "{关键词}" --include="*.java" --include="*.kt" --include="*.py" --include="*.js" --include="*.ts" --include="*.swift" --include="*.dart"
-grep -rn "{关键词}" .worktree/code-gen/*/snapshots/changes.diff
 ```
 
+**3. 需求溯源**（定位到代码位置后必须执行）：
+找到引入 bug 的 code-gen 任务后，继续向上追溯完整链路：
+1. 读取该 code-gen 任务的 `dev_doc` 字段，定位对应的 doc-gen 任务
+2. 读取 doc-gen 任务的 `task.json` + `log.md`，获取原始需求信息
+3. 如果 doc-gen 任务有 `related_task_id`，继续向上追溯关联的 doc-gen 任务
+4. 读取 code-gen 任务的 `log.md`，查看阶段一的需求收集阶段用户是否有补充信息导致 bug 引入
+
+溯源结果记录到 source_info：
+- `root_requirement`: 原始需求文档名
+- `root_doc_gen_task`: 源头 doc-gen 任务 ID
+- `root_code_gen_task`: 引入 bug 的 code-gen 任务 ID
+- `introduction_context`: bug 是在哪个环节被引入的（如"用户补充需求: xxx"）
+- `full_chain`: 完整溯源链路（doc-gen → code-gen → bug 代码位置）
+
 ### 定位结果
 
-更新 task.json source_info：`{requirement, iteration, task_id, location, detail}`
+更新 task.json source_info：`{requirement, iteration, task_id, location, detail, root_requirement, root_doc_gen_task, root_code_gen_task, introduction_context, full_chain}`
+
+日志写入：Bug 描述 → 定位路径（范围+关键词） → 定位过程 → 需求溯源链路 → 定位结果（源头任务/需求/引入环节/位置/原因）
 
-日志写入：Bug 描述 → 定位路径（范围+关键词） → 定位过程 → 定位结果（源头任务/需求/位置/原因）
+### 回写关联
+
+定位完成后，将 bug-fix 任务 ID 回写到源头 code-gen 任务的 task.json：
+```python
+# 读取源头 code-gen 任务的 task.json
+# 在其中追加 bug_fix_refs 字段（数组）
+# 如果不存在则创建，已存在则追加 bug-fix task_id
+{"bug_fix_refs": ["bug-task-20260524-xxxx"]}
+```
 
 ---
 
@@ -138,8 +163,11 @@ grep -rn "{关键词}" .worktree/code-gen/*/snapshots/changes.diff
 3. **真实 git diff 快照**（Bash 执行，禁止手写/中文摘要）：
    ```bash
    mkdir -p {快照目录}
-   git diff HEAD -- {文件列表} > {快照目录}/changes.diff
    ```
+   **逐文件判断跟踪状态**，必须分开执行，禁止用 `;` 或 `||` 拼合：
+   - 已跟踪文件（`git ls-files --error-unmatch {文件} 2>/dev/null` 成功）：`git diff HEAD -- {文件列表}`
+   - 未跟踪文件：`git diff --no-index /dev/null {文件名}`
+   将 Bash 原始输出追加到 `{快照目录}/changes.diff`
 4. log.md：修复方案 + 变更文件表
 
 ---

package/commands/code-gen.md

@@ -32,6 +32,8 @@ model: inherit
 
 ### 文件格式
 
+**JSON 文件更新规则**：task.json、module.json 等数据文件用 **Read → 改字段 → Write** 整体重写，禁止用 Edit（单行 JSON 无法保证 old_string 唯一匹配）。log.md 追加内容用 Edit。
+
 **module.json**：`{"id": "{module_id}", "name": "{模块名}", "type": "code-gen", "created_at": "{timestamp}"}`
 
 **task.json**：
@@ -53,8 +55,8 @@ model: inherit
 ### ID 生成
 
 ```bash
-python3 -c "import datetime,random; print(f'mod-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
-python3 -c "import datetime,random; print(f'task-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
+python3 -c "import datetime,random; print(f'code-mod-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
+python3 -c "import datetime,random; print(f'code-task-{datetime.date.today().strftime(\"%Y%m%d\")}-{random.randbytes(2).hex()}')"
 ```
 
 ### 文档位置解析
@@ -86,7 +88,7 @@ python3 -c "import datetime,random; print(f'task-{datetime.date.today().strftime
 ### 前置
 
 ```bash
-cat .worktree/code-gen/*/module.json 2>/dev/null
+cd $(git rev-parse --show-toplevel) && for f in $(find .worktree/code-gen -name module.json 2>/dev/null); do python3 -c "import json; m=json.load(open('$f')); print(f'{m[\"id\"]}  {m[\"name\"]}')"; done 2>/dev/null
 ```
 
 ### AskUserQuestion 规则
@@ -95,28 +97,32 @@ cat .worktree/code-gen/*/module.json 2>/dev/null
 
 ### 第一步：选择模块
 
-有模块 → AskUserQuestion（header=模块，options=模块列表 + "新建模块"，最多展示3个已有）；无模块 → 文字提问"请输入模块名称"。
+**动态选项规则**：1-3 个 → AskUserQuestion 列出全部 + `自定义输入`；4+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `自定义输入`）。**无模块时直接输出文字提问"请输入模块名称"，禁止使用 AskUserQuestion，不推荐、不猜测模块名。**
 
 ### 第一步半：扫描模块资源
 
 ```bash
-find .worktree/ -name "*-develop.md" -type f 2>/dev/null
-find .worktree/ -name "index.yaml" -path "*/images/*" -type f 2>/dev/null
+cd $(git rev-parse --show-toplevel) && find .worktree/ -name "*-develop.md" -type f 2>/dev/null && find .worktree/ -name "index.yaml" -path "*/images/*" -type f 2>/dev/null
 ```
 
-### 第二步：文字提问任务标题
+### 第二步：直接文字提问任务标题
+
+**禁止使用 AskUserQuestion**，直接输出文字提问，由用户自由输入。不推荐、不猜测标题。
 
 ### 第三步：AskUserQuestion（两批）
 
-**第一批（4问）**：
-1. header=开发文档：**动态选项** — 有 develop.md 时列出文件（最多3个 + 自定义路径），无则 `无开发文档` + `自定义路径`
-2. header=Plan：`是` / `否（推荐）`
-3. header=API：`无接口文档` / `读取 docs/ 全部文件`
-4. header=设计：**动态选项** — 有图片时按任务分组列出（`{任务标题} 的草图 (n张)`）+ `无设计稿` + `Figma 链接`，无图片时 `无设计稿` + `Figma 链接` + `本地图片`
+**动态选项规则**：0 个 → 禁止 AskUserQuestion，直接文字提问；1-3 个 → AskUserQuestion 列出全部 + `自定义输入`；4+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `自定义输入`）。
+
+**第一批（2问）**：
+1. header=开发文档：扫描 develop.md 文件，按上述规则
+2. header=Plan：`否（推荐）` / `是`
+
+**第二批（1问）**：
+3. header=补充：`无补充` / `有补充`
 
-**第二批（1问）**：header=补充：`无补充` / `有补充`
+**设计稿和 API**：不单独询问，阶段二自动从 develop.md 读取。设计稿从同目录 `images/index.yaml` 读取，API 信息从 develop.md 的"接口调用"章节直接提取。
 
-收集完毕 → 展示信息确认清单 → 用户确认后进入阶段二。
+收集完毕 → AskUserQuestion（header=确认，options=`确认开始` / `需要修改`）→ 确认后进入阶段二。
 
 ---
 
@@ -126,7 +132,7 @@ find .worktree/ -name "index.yaml" -path "*/images/*" -type f 2>/dev/null
 
 1. 生成 task_id
 2. `mkdir -p .worktree/code-gen/{模块名}-{module_id}/{任务标题}-{task_id}`
-3. Write task.json（7阶段全 pending）
+3. Write task.json（阶段1 completed，阶段2 running，其余 pending）
 
 **自动关联前序任务**（开发文档来自 doc-gen 时）：
 a. 定位 develop.md 所属 doc-gen 任务
@@ -135,7 +141,7 @@ c. 若不为空 → 找前序 doc-gen 的 develop.md → 搜索 code-gen 中 `de
 d. 若为空 → `prev_task_id: null`
 
 ```bash
-find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路径}" {} \;
+cd $(git rev-parse --show-toplevel) && find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路径}" {} \;
 ```
 
 4. 更新 module.json（如新建）
@@ -149,8 +155,9 @@ find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路
 **A. 开发文档** → 读取 develop.md + 同目录 `images/index.yaml`
 - 失败时回退原始需求文档，仍失败则提示用户
 - **增量模式**（prev_task_id 不为空）：读前序 changes.diff + 已涉及文件，只针对 `[新增]`/`[修改]` 章节生成代码
+- **关联需求参考**：develop.md 所属 doc-gen 任务的 `related_task_id` 不为空时，沿关联链找到对应的 code-gen 任务，加载其 `changes.diff` 和已生成代码作为参考基准。关联需求的代码结构、命名风格、工具类使用应优先复用，保持代码一致性
 
-**B. API 文档** → 从 docs/ 按位置解析，失败标记「API 文档缺失」继续
+**B. API 文档** → 直接从 develop.md 的"接口调用"章节提取，无需额外读取。develop.md 已包含接口地址、方法、请求参数、响应字段等信息。无此章节时标记「API 信息缺失」继续
 
 **C. 设计稿** → 优先读 index.yaml
 - Figma URL：提取 fileKey/nodeId → Figma MCP get_metadata → get_design_context
@@ -158,6 +165,9 @@ find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路
 - 无 index.yaml：回退用户直接输入
 
 **D. Skill 约束** → 递归扫描 `skills/*.md` + `CLAUDE.md`，逐条应用。log.md 只记文件名和更新时间。
+```bash
+cd $(git rev-parse --show-toplevel) && find skills/ -name "*.md" -type f 2>/dev/null
+```
 
 ---
 
@@ -179,7 +189,7 @@ find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路
 
 ⚠️ 闭环规则：每个 ⚠️ 必须在阶段四解决 + 阶段六回顾，不允许标记后不跟进。
 
-等待用户确认后进入编码。
+展示方案后直接进入阶段四编码，无需确认。
 
 ---
 
@@ -190,19 +200,41 @@ find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路
 **`changes.diff` 必须是真实 git diff 输出，禁止中文摘要/省略代码行。**
 
 1. `mkdir -p .worktree/code-gen/{模块}/{任务}/snapshots/`
-2. 已跟踪文件：`git diff HEAD -- {文件列表}`
-3. 未跟踪文件：`git diff --no-index /dev/null {文件名}`
-4. 将 Bash 原始输出 Write 到 `changes.diff`
+2. **逐文件判断跟踪状态**，必须分开执行，禁止用 `;` 或 `||` 拼合：
+   - 已跟踪文件（`git ls-files --error-unmatch {文件} 2>/dev/null` 成功）：`git diff HEAD -- {文件列表}`
+   - 未跟踪文件：`git diff --no-index /dev/null {文件名}`
+3. 将 Bash 原始输出 Write 到 `changes.diff`
 
-排除：.worktree/、.DS_Store、docs/、*.md 配置文件、dashboard/、无关文件。
+排除：.worktree/、.DS_Store、docs/、*.md 配置文件、.dashboard/、无关文件。
 
 ### 编码原则
 
+- **关联需求优先参考**：如果有关联的 code-gen 任务，优先复用其代码结构、类名、方法签名、工具类和组件，保持风格一致
 - **UI 100% 还原**：对照 index.yaml 设计稿，布局/颜色/字号/间距/圆角/阴影等所有视觉属性像素级一致
 - 优先编辑现有文件，复用已有工具类和组件
 - 接口字段注释：根据 API 文档为每个字段生成中文注释
 - 不引入不必要抽象；安全第一；简洁优于通用；只在系统边界校验
 
+### 设计稿绝对还原规则
+
+**当阶段二加载了 Figma design context 或图片时，必须 100% 按照设计信息实现界面，禁止任何自行替换或简化：**
+
+| 维度 | 强制要求 |
+|------|----------|
+| 布局方式 | Figma 用绝对定位就用绝对定位，用 flex 就用 flex，必须忠实还原 |
+| 图片资源 | Figma MCP 返回的图片/图标 URL 必须**下载并引用**，禁止用 SVG/代码自行近似替代 |
+| 精确像素值 | 宽高、间距、圆角、字号、字重等所有数值必须与 Figma 返回数据**完全一致** |
+| 字体 | Figma 指定的字体必须通过 CDN 加载（如 Google Fonts），禁止省略或用系统字体替代 |
+| 元素结构 | Figma 中的分组/嵌套关系必须保持，禁止拆分、重组或合并 |
+| 颜色值 | 必须使用 Figma 返回的精确颜色值（hex/rgba），禁止近似替换 |
+| 容器尺寸 | Dialog/Frame 等容器必须使用 Figma 指定的固定宽高，禁止靠内容撑开 |
+
+**违反示例（禁止）：**
+- Figma 返回 `<img src="asset_url"/>` → 自行改用 `<svg>` 近似 ❌
+- Figma 返回 `position: absolute; top: 45px` → 改用 `margin-top: 29px` 流式布局 ❌
+- Figma 指定 `font-family: 'Inter'` → 省略字体加载，用系统字体 ❌
+- Figma 指定 `height: 426px` → 不设固定高度靠内容撑开 ❌
+
 ---
 
 ## 阶段五：编译校验