claude-coding-flow 1.5.0 → 1.6.0

package/bin/flow.js

@@ -98,38 +98,34 @@ function init() {
   if (!settings.permissions.allow) settings.permissions.allow = [];
 
   const allowPatterns = [
-    // Read-only: git
-    "Bash(git rev-parse:*)",
-    "Bash(git ls-files:*)",
-    "Bash(git diff:*)",
-    // Read-only: find (docs, skills, worktree, src)
-    "Bash(find docs/ *)",
-    "Bash(find skills/ *)",
-    "Bash(find .worktree/ *)",
-    "Bash(find src/ *)",
-    // Read-only: grep
-    "Bash(grep -rn * --include=*.java --include=*.kt --include=*.py --include=*.js --include=*.ts --include=*.swift --include=*.dart)",
-    // Read-only: python3 one-liners (ID gen, JSON parsing, date)
-    "Bash(python3 -c *)",
-    // Read-only: ls / cat / test
-    "Bash(ls *)",
-    "Bash(test -f *)",
-    // Write: mkdir / cp for worktree
-    "Bash(mkdir -p .worktree/ *)",
-    "Bash(cp .worktree/ *)",
-    "Bash(cp docs/ .worktree/ *)",
-    // Write: rm temp
-    "Bash(rm -rf .worktree/code-gen/temp)",
-    // Write: date
+    // Basic tools
+    "Edit", "Write", "Read",
+    // Shell read-only
+    "Bash(ls*)", "Bash(cat *)", "Bash(head*)", "Bash(tail*)",
+    "Bash(find *)", "Bash(grep*)", "Bash(wc *)", "Bash(echo *)",
+    "Bash(test -f *)", "Bash(tree *)",
+    // Date
     "Bash(date *)",
+    // File operations
+    "Bash(mkdir *)", "Bash(cp *)", "Bash(mv *)", "Bash(rm *)", "Bash(touch *)",
+    // Python
+    "Bash(python3 *)", "Bash(python *)", "Bash(pip3 install *)", "Bash(pip install *)",
+    // Server
+    "Bash(uvicorn *)",
+    // Java
+    "Bash(javac *)", "Bash(java *)",
+    // Git (covers all subcommands)
+    "Bash(git *)",
+    // Network
+    "Bash(curl *)",
+    // Cd (covers compound commands like "cd ... && find ...")
+    "Bash(cd *)",
+    // Skill
+    "Skill(update-config)",
     // Build commands
-    "Bash(npm run build:*)",
-    "Bash(npx tsc --noEmit)",
-    "Bash(cargo check)",
-    "Bash(go build ./...)",
-    "Bash(make build)",
-    "Bash(./gradlew assembleDebug)",
-    "Bash(./mvnw compile)",
+    "Bash(npm run build:*)", "Bash(npx tsc --noEmit)",
+    "Bash(cargo check)", "Bash(go build ./...)", "Bash(make build)",
+    "Bash(./gradlew assembleDebug)", "Bash(./mvnw compile)",
   ];
 
   let added = 0;

package/commands/bug-fix.md

@@ -7,6 +7,12 @@ model: inherit
 
 你是一位 Bug 定位专家，通过任务链追溯 bug 源头并修复。
 
+## 核心设计理念
+
+本 skill 是**增量 + 可溯源**模式的标准实现：
+- **增量**：定位到 bug 后做最小化修改，不重写不相关的代码
+- **可溯源**：沿任务链溯源——bug-fix 任务 → code-gen 任务（通过 related_task_id） → doc-gen 任务（通过 dev_doc） → 原始需求。通过 code-gen 的 changes.diff 快照快速理解已有代码，无需盲目全文搜索
+
 ## 语言要求
 
 - 交流用**中文**，代码/变量/函数名用**英文**

package/commands/code-gen.md

@@ -144,6 +144,25 @@ d. 若为空 → `prev_task_id: null`
 cd $(git rev-parse --show-toplevel) && find .worktree/code-gen/ -name "task.json" -exec grep -l "{前序develop.md路径}" {} \;
 ```
 
+### 可溯源链路（增量开发的核心）
+
+增量模式下，通过以下链路快速定位已有代码，避免盲目全文搜索：
+
+```
+当前 develop.md(D2)
+  → related_task_id → 前序 develop.md(D1)
+    → 匹配 dev_doc 的 code-gen 任务(E1 的任务)
+      → snapshots/changes.diff(E1 的代码快照)
+        → 快照中涉及的文件 = 增量开发的出发点
+```
+
+**溯源步骤**：
+1. 读取当前 develop.md 所属 doc-gen 任务的 `related_task_id`，定位前序 doc-gen 任务
+2. 读取前序 doc-gen 任务的 `output_doc`（D1 路径）
+3. 在 code-gen 中搜索 `dev_doc` 匹配 D1 的任务（E1 的 code-gen 任务）
+4. 读取 E1 任务的 `snapshots/changes.diff`，获取已生成的文件列表和代码
+5. E1 快照中涉及的文件就是本次增量开发需要修改的文件集合
+
 4. 更新 module.json（如新建）
 
 ### 阶段进度更新
@@ -154,8 +173,12 @@ cd $(git rev-parse --show-toplevel) && find .worktree/code-gen/ -name "task.json
 
 **A. 开发文档** → 读取 develop.md + 同目录 `images/index.yaml`
 - 失败时回退原始需求文档，仍失败则提示用户
-- **增量模式**（prev_task_id 不为空）：读前序 changes.diff + 已涉及文件，只针对 `[新增]`/`[修改]` 章节生成代码
-- **关联需求参考**：develop.md 所属 doc-gen 任务的 `related_task_id` 不为空时，沿关联链找到对应的 code-gen 任务，加载其 `changes.diff` 和已生成代码作为参考基准。关联需求的代码结构、命名风格、工具类使用应优先复用，保持代码一致性
+- **增量模式**（prev_task_id 不为空）：
+  - 通过可溯源链路定位 E1 的 code-gen 任务和 changes.diff 快照
+  - 对比 D1 和 D2 中标记了 `[新增]`/`[修改]`/`[删除]` 的章节，只针对变更章节生成代码
+  - E1 快照中涉及的文件 = 本次需要增删改的文件出发点
+  - 读取这些文件的当前代码，在此基础上做增量修改
+- **关联需求参考**：develop.md 所属 doc-gen 任务的 `related_task_id` 不为空时，沿可溯源链路找到对应的 code-gen 任务，加载其 `changes.diff` 和已生成代码作为参考基准。关联需求的代码结构、命名风格、工具类使用应优先复用，保持代码一致性
 
 **B. API 文档** → 直接从 develop.md 的"接口调用"章节提取，无需额外读取。develop.md 已包含接口地址、方法、请求参数、响应字段等信息。无此章节时标记「API 信息缺失」继续
 
@@ -199,10 +222,12 @@ cd $(git rev-parse --show-toplevel) && find skills/ -name "*.md" -type f 2>/dev/
 
 **`changes.diff` 必须是真实 git diff 输出，禁止中文摘要/省略代码行。**
 
+**快照错误静默处理**：文件可能未 git add/commit，`git diff --no-index` 会返回 exit code 1（表示有差异，非报错）。所有快照相关 git 命令末尾加 `|| true` 静默处理，禁止向用户展示 Error。
+
 1. `mkdir -p .worktree/code-gen/{模块}/{任务}/snapshots/`
 2. **逐文件判断跟踪状态**，必须分开执行，禁止用 `;` 或 `||` 拼合：
-   - 已跟踪文件（`git ls-files --error-unmatch {文件} 2>/dev/null` 成功）：`git diff HEAD -- {文件列表}`
-   - 未跟踪文件：`git diff --no-index /dev/null {文件名}`
+   - 已跟踪文件（`git ls-files -- {文件}` 输出非空）：`git diff HEAD -- {文件列表} || true`
+   - 未跟踪文件：`git diff --no-index /dev/null {文件名} || true`
 3. 将 Bash 原始输出 Write 到 `changes.diff`
 
 排除：.worktree/、.DS_Store、docs/、*.md 配置文件、.dashboard/、无关文件。
@@ -212,7 +237,12 @@ cd $(git rev-parse --show-toplevel) && find skills/ -name "*.md" -type f 2>/dev/
 - **关联需求优先参考**：如果有关联的 code-gen 任务，优先复用其代码结构、类名、方法签名、工具类和组件，保持风格一致
 - **UI 100% 还原**：对照 index.yaml 设计稿，布局/颜色/字号/间距/圆角/阴影等所有视觉属性像素级一致
 - 优先编辑现有文件，复用已有工具类和组件
-- 接口字段注释：根据 API 文档为每个字段生成中文注释
+- **API 注释强制要求**：API 文档中的字段说明必须在代码中以中文注释体现。具体要求：
+  - 请求参数：每个字段的说明、类型、必填、长度限制 → 注释在参数声明上方
+  - 响应参数：每个字段的说明、类型 → 注释在字段声明上方
+  - 枚举值：API 文档中的枚举常量说明 → 注释在枚举定义处
+  - 接口地址和方法：注释在请求函数/方法上方
+  - 错误码：文档中列出的错误码 → 注释在错误处理逻辑处
 - 不引入不必要抽象；安全第一；简洁优于通用；只在系统边界校验
 
 ### 设计稿绝对还原规则

package/commands/doc-gen.md

@@ -82,6 +82,7 @@ docs/
  "phases": [{"phase": 1, "name": "信息收集", "status": "running", "started_at": "{timestamp}", "completed_at": null}],
  "requirement_doc": "{文件名}", "sketch_folder": "{目录名}", "api_doc": "{文件名或null}",
  "output_doc": "{需求名}-develop.md",
+ "input_changes": null,
  "related_task_id": null, "created_at": "{timestamp}", "updated_at": "{timestamp}"}
 ```
 
@@ -128,20 +129,39 @@ find docs/images/ -mindepth 1 -maxdepth 1 -type d 2>/dev/null
 find docs/apis/ -name "*.md" -type f 2>/dev/null
 ```
 
-### 第三步：AskUserQuestion 收集（两批）
+### 第三步：AskUserQuestion 收集
 
-**动态选项规则**：0 个 → AskUserQuestion 提供选项 `无`（description:"暂不指定"）+ `稍后提供`（description:"稍后手动提供路径"），必须逐项弹出；1-3 个 → AskUserQuestion 列出全部 + `自定义输入`；4+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `自定义输入`）。
+#### 全量模式（无前序任务或用户选全新生成）
+
+**动态选项规则**（需求文档 — 必填输入）：0 个 → AskUserQuestion 提供 `稍后提供`（description:"稍后手动提供路径"）；1-3 个 → AskUserQuestion 列出全部 + `自定义输入`，有文件时剩余空位可补充 `读取全部`；4+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `自定义输入`）。
+
+**动态选项规则**（图片、API — 可选输入，**必须始终包含 `无` 选项**）：0 个 → AskUserQuestion 提供选项 `无`（description:"暂不指定"）+ `稍后提供`（description:"稍后手动提供路径"）；1-2 个 → AskUserQuestion 列出全部 + `无`（description:"暂不指定"）+ `自定义输入`；3+ 个 → 文字列出全部（带编号）+ AskUserQuestion（`输入序号` + `无`（description:"暂不指定"）+ `自定义输入`）。
 
 **第一批（3问，每问单独 AskUserQuestion）**：
-1. header=需求文档：扫描 `docs/prds/` 下 `.md` 文件，按上述规则。有文件时剩余空位可补充 `读取全部`
-2. header=图片：扫描 `docs/images/` 下子文件夹，按上述规则。有目录时剩余空位可补充 `无图片`
-3. header=API：扫描 `docs/apis/` 下 `.md` 文件，按上述规则。有文件时剩余空位可补充 `无 API 文档`
+1. header=需求文档：扫描 `docs/prds/` 下 `.md` 文件，按必填输入规则
+2. header=图片：扫描 `docs/images/` 下子文件夹，按可选输入规则
+3. header=API：扫描 `docs/apis/` 下 `.md` 文件，按可选输入规则
 
 **第二批（1问）**：
-4. header=增量：`全新生成` / `增量更新`
+4. header=增量：`全新生成` / `增量更新`（仅当模块内存在前序任务时显示此选项，否则直接全量生成）
 
 收集完毕 → AskUserQuestion（header=确认，options=`确认开始` / `需要修改`）→ 确认后进入处理。
 
+#### 增量模式（有前序任务且用户选增量更新）
+
+**核心原则：只有用户提供了变更版本的输入，才会在 develop.md 中生成对应的增量。未变更的输入沿用前序任务，对应章节原样保留。**
+
+1. **识别前序任务**：读取模块内最新任务的 task.json，获取其 requirement_doc、sketch_folder、api_doc、output_doc 路径
+
+2. **自动推断变更输入**：根据第一批收集结果自动判断，无需再单独询问。用户选了具体文件 → 该输入有变更；用户选了"无" → 该输入沿用前序任务
+   - requirement_doc 非空 → `requirement: true`
+   - sketch_folder 非空 → `images: true`
+   - api_doc 非空 → `api: true`
+
+3. **AskUserQuestion（header=确认）**：展示 `前序任务: {task_id}` + `变更输入: {有变更的项}` + `沿用输入: {未变更的项}` + options=`确认开始` / `需要修改`
+
+收集完毕后，task.json 的 `input_changes` 字段写入：`{"requirement": true/false, "images": true/false, "api": true/false}`
+
 ---
 
 ## 处理阶段
@@ -252,7 +272,35 @@ find docs/apis/ -name "*.md" -type f 2>/dev/null
 
 ### 增量模式
 
-有 `related_task_id` 时：读取旧需求文档 + 旧 develop.md + 新需求文档 → 按章节 diff → 保留相同章节，`<span style="color:red">[新增]</span>`/`[修改]`/`[删除]` 标记变更章节，保留人工修改内容。
+**核心原则：按输入维度增量，只处理变更的输入。**
+
+读取 task.json 的 `input_changes` 字段，确定哪些输入有变更：
+
+**1. 读取前序任务产物**
+- 前序 develop.md（D1）：全文读取，作为 D2 的基础
+- 前序 task.json：获取 requirement_doc、sketch_folder、api_doc 路径
+
+**2. 按输入维度处理**
+
+| 变更输入 | 处理方式 |
+|----------|----------|
+| requirement=true | diff 旧需求文档 vs 新需求文档 → 定位受影响章节 → 在 D2 中标记 `[修改]`/`[新增]`/`[删除]` |
+| requirement=false | D1 中需求相关章节原样保留 |
+| images=true | 重新处理图片/Figma → 更新页面结构分析、组件清单、交互行为等图片相关章节 |
+| images=false | D1 中图片相关章节原样保留 |
+| api=true | diff 旧 API 文档 vs 新 API 文档 → 更新接口调用、数据流等 API 相关章节 |
+| api=false | D1 中 API 相关章节原样保留 |
+
+**3. D2 章节标记规则**
+
+- 变更输入影响的章节：`<span style="color:red">[修改]</span>` / `[新增]` / `[删除]`
+- 未变更输入对应的章节：原样复制，不加标记
+- 保留 D1 中的人工修改内容
+
+**4. D2 的 output_doc 和 related_task_id**
+
+- `output_doc`: 新文件名（如 `{需求名}-v2-develop.md`）
+- `related_task_id`: 前序 doc-gen 任务的 task_id
 
 ### 文件拷贝
 
@@ -272,9 +320,11 @@ cp {引用的 API 文档} .worktree/doc-gen/{模块}/{任务}/apis/
 - 图片资源: index.yaml, 本地图片 {n} 张, Figma 链接 {n} 个
 - API 资源: index.yaml, API 文档 {n} 个
 - 关联任务: {task_id 或 "无"}
+- 输入变更: {全量 或 "requirement:变更, images:沿用, api:变更"}
 
 ## 处理结果
 - 章节匹配: {统计} | 控件提取: {总数} | API 接口: {总数} | 开发文档: {文件名}
+- 增量范围: {全量生成 或 "仅更新 requirement+api 相关章节, images 章节沿用 D1"}
 ```
 
 ### 完成

package/dashboard/static/app.js

@@ -204,7 +204,7 @@ function renderCodeGenCard(task) {
   const bugBadges = (task.bug_fix_details || []).map(b => {
     const statusText = b.status === "resolved" ? "已解决" : "未解决";
     const cls = b.status === "resolved" ? "resolved" : "unresolved";
-    return `<span class="cross-badge traces-to" title="Bug: ${esc(b.title)} (${statusText})">Bug: ${esc(b.title)} (${statusText})</span>`;
+    return `<span class="cross-badge traces-to" title="Bug: ${esc(b.title)} (${statusText})">Bug: ${esc(b.title)} (${statusText}) · ${esc(b.id)}</span>`;
   }).join("");
 
   return `<div class="task-card" data-id="${task.id}" data-type="code-gen">

package/dashboard/static/style.css

@@ -426,9 +426,6 @@ body {
   border-radius: 8px;
   margin-left: 6px;
   white-space: nowrap;
-  max-width: 220px;
-  overflow: hidden;
-  text-overflow: ellipsis;
 }
 
 .cross-badge.based-on {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coding-flow",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Claude Code skills for requirement analysis, code generation and bug fixing",
   "bin": {
     "flow": "bin/flow.js"