cgraphx 1.1.0 → 1.3.0

package/dist/.claude-template/skills/code-impact-init/SKILL.md

@@ -9,7 +9,7 @@ Automated project exploration skill. Discovers entry points, explores each in de
 
 **Dependencies:**
 - `code-impact-markdown` skill must be installed in the same project（沉淀业务理解到 `docs/knowledge/*.md`）
-- cgraphx 已 `init` 的项目索引（提供代码结构事实：symbols / 调用链 / impact）。优先通过 `codegraph_explore` MCP 工具,不可用时走 Bash CLI(`cgraphx query` / `cgraphx callers` / `cgraphx callees` / `cgraphx impact` / `cgraphx affected`)。两者都不可用时降级为 grep 模式(精度损失,详见各 Phase 的 fallback 说明)
+- cgraphx 已 `init` 的项目索引（提供代码结构事实：symbols / 调用链 / impact）。优先通过 `codegraph_explore` / `codegraph_impact` / `codegraph_node` 等 MCP 工具,不可用时走 Bash CLI(`cgraphx query` / `cgraphx callers` / `cgraphx callees` / `cgraphx affected`)。两者都不可用时降级为 grep 模式(精度损失,详见各 Phase 的 fallback 说明)
 
 ## Trigger
 
@@ -98,9 +98,9 @@ code-impact-init 协调 cgraphx 的**两个互补子系统**：
 
 ```
 Phase 1 Step 1.5:  cgraphx init（一次性，几分钟，建代码图谱）
-Phase 1-2:         查询用 cgraphx query / callers / callees / impact / affected（毫秒级，子 agent 主用）
+Phase 1-2:         查询用 cgraphx query / callers / callees / affected CLI,或 codegraph_explore / codegraph_impact / codegraph_node MCP（毫秒级，子 agent 主用）
 Phase 2 末尾:      cgraphx docs index（同步子 agent 写的 .md 到知识图谱）
-Phase 3 Step 1:    cgraphx impact 找高中心性 symbols
+Phase 3 Step 1:    【已 deprecated — 原 cgraphx impact CLI 已去除】用 codegraph_impact MCP 主观评估影响面,或等阶段 2 gitnexus impact 工具
 Phase 3 Step 2:    cgraphx docs concepts --sort=doc-count 找高中心性 concepts
 Phase 3 Step 3:    交叉验证 → cross-cutting pending
 Phase 3 末尾:      cgraphx docs index（同步 Phase 3 文档）
@@ -466,49 +466,50 @@ Time →
 - 每批次跑 = 累计 N 批次 × 单次耗时，几天到几周
 - 根本解是 markdown 知识库做增量 index endpoint（P0 #1，留作下一轮）
 
-### Phase 3: Cross-cutting Deep-dive（基于 cgraphx impact + cgraphx docs concepts 交叉）
+### Phase 3: Cross-cutting Deep-dive（基于 codegraph_impact MCP + cgraphx docs concepts 交叉）
 
-**核心思路**：cross-cutting concern = **代码层面被多个 entry 依赖的高中心性 symbol**（`cgraphx impact` 的 `nodeCount` 测量）+ **业务层面已被多文档提及但无专属文档的 concept**（`cgraphx docs concepts --sort=doc-count` 测量）。两者交叉验证，比单纯靠 markdown concept 频率更准——concept 在 markdown 里出现可能是子 agent 主观判断，cgraphx impact 是代码事实。
+> **【2026-07-05 deprecated notice】** 原Phase 3 依赖 `cgraphx impact <symbol> --json` CLI 返回 `{nodeCount, edgeCount, affected[]}` 用于脚本循环 + 数值排序。该 CLI 在阶段 1 已去除(实测无法替代 MCP)。当前替代:
+> - **代码层面找高中心性 symbol** — 用 `codegraph_impact(symbol)` MCP 工具,从返回的格式化报告里**主观评估**影响面广度(返回文本包含 affected symbols 列表 + 树状结构,agent 看大小估计中心性)
+> - **完整 nodeCount 排序机制** — 等阶段 2 gitnexus 内核迁入后,用 gitnexus 的 `impact` 工具(基于 KuzuDB + Cypher,支持结构化返回)
+> - Phase 3 的"交叉验证"思路仍然有效,只是代码层面从"机器排序"降级为"agent 主观判断"
 
-**Step 1 — 代码层面：找高中心性 symbols（cgraphx impact nodeCount）**
+**核心思路**：cross-cutting concern = **代码层面被多个 entry 依赖的高中心性 symbol**（`codegraph_impact` MCP 评估)+ **业务层面已被多文档提及但无专属文档的 concept**（`cgraphx docs concepts --sort=doc-count` 测量）。两者交叉验证，比单纯靠 markdown concept 频率更准——concept 在 markdown 里出现可能是子 agent 主观判断，codegraph_impact 是代码事实。
 
-`cgraphx impact <symbol> --json` 返回 `{ symbol, depth, nodeCount, edgeCount, affected[] }`。**`nodeCount` 是中心性指标**——影响半径内的节点数，数字越大中心性越高。
+**Step 1 — 代码层面：找高中心性 symbols（codegraph_impact MCP 主观评估）**
 
-```bash
-CODEGRAPH="cgraphx"
-
-# 1. 从 docs/knowledge/*.md frontmatter related_code 提取 symbol 列表
-# related_code 可能是文件路径或 symbol 名,两种都收
-SYMBOLS=$(for f in docs/knowledge/*.md; do
-  awk '/^---$/{c++; next} c==1 && /^related_code:/{flag=1; next} flag && /^  - /{gsub(/^  - /,""); print}' "$f"
-done | sort -u)
+`codegraph_impact(symbol, depth)` MCP 返回该 symbol 的影响半径报告(affected symbols list + 树状结构 + 统计)。agent 看返回报告的**规模**(涉及的文件数 / 模块数 / 跨服务 hop 数)主观判断中心性。
 
-# 2. 对每个 symbol 跑 impact,按 nodeCount(中心性指标)排序
-TMP=$(mktemp)
-while IFS= read -r sym; do
-  [ -z "$sym" ] && continue
-  $CODEGRAPH impact "$sym" --json 2>/dev/null \
-    | jq -r --arg sym "$sym" '[.nodeCount // 0, $sym] | @tsv' >> "$TMP"
-done <<< "$SYMBOLS"
-
-# 3. 取 top 30
-sort -t$'\t' -k1 -rn "$TMP" | head -30 > high-centrality-symbols.txt
-rm -f "$TMP"
+**MCP 调用路径**(取代原 shell 循环):
+```
+对每个 Phase 2 探索到的 entry symbol:
+  → 调用 codegraph_impact(symbol, depth=2) MCP
+  → 看返回报告里 affected symbols 的数量 + 跨文件 / 跨模块分布
+  → 主观标记"高中心性 / 中中心性 / 低中心性"
+  → 取高中心性 top 30 作为 Phase 3 deep-dive 候选
+```
 
-cat high-centrality-symbols.txt
+**原 shell 脚本路径(已废弃,留作历史参考)**:
+```bash
+# 原 cgraphx impact CLI 已去除,以下脚本不工作,仅作历史参考
+# CODEGRAPH="cgraphx"
+# while IFS= read -r sym; do
+#   $CODEGRAPH impact "$sym" --json 2>/dev/null \
+#     | jq -r --arg sym "$sym" '[.nodeCount // 0, $sym] | @tsv' >> "$TMP"
+# done <<< "$SYMBOLS"
+# sort -t$'\t' -k1 -rn "$TMP" | head -30 > high-centrality-symbols.txt
 ```
 
 **注释说明**：
-- `cgraphx impact <symbol> --json` 输出 `{symbol, depth, nodeCount, edgeCount, affected[]}`
-- **`nodeCount` 是中心性指标**（影响半径内的节点数，数字越大中心性越高）
-- 如果 `related_code` 字段是文件路径而不是 symbol，需要先 `cgraphx query --kind=function --kind=method` 在该文件下找 symbol，再跑 impact
+- ~~`cgraphx impact <symbol> --json` 输出 `{symbol, depth, nodeCount, edgeCount, affected[]}`~~（CLI 已去除)
+- **替代**:`codegraph_impact(symbol)` MCP 返回格式化影响半径报告,agent 主观评估规模
+- 如果 `related_code` 字段是文件路径而不是 symbol，需要先 `cgraphx query --kind=function --kind=method` 在该文件下找 symbol，再调 codegraph_impact MCP
 
-**MCP 优先路径**（可选）：
-> 把 Phase 2 探索到的 entry symbols 喂给 `codegraph_explore` MCP 工具，一次性返回各符号的 impact 信息。比 shell 循环 + 文件拼接快得多，而且 agent 能直接看结构化结果做判断。
+**MCP 调用优势**：
+> 把 Phase 2 探索到的 entry symbols 喂给 `codegraph_impact` MCP 工具，agent 直接看结构化结果做判断,比 shell 循环 + 文件拼接更直接。
 
-**为什么这么设计**：cgraphx 用 `impact nodeCount` 排序找中心性，不需要 cypher 接口。
+**为什么这么设计**：用 `codegraph_impact` MCP 评估中心性，不需要 cypher 接口;等阶段 2 gitnexus 内核迁入后可升级到结构化 nodeCount 排序。
 
-被多个 entry 依赖的 symbol 就是代码层面的 cross-cutting concern（如业务项目的 OrderService、PaymentGateway、AuthMiddleware——它们的 `nodeCount` 远高于工具类）。
+被多个 entry 依赖的 symbol 就是代码层面的 cross-cutting concern（如业务项目的 OrderService、PaymentGateway、AuthMiddleware——它们的影响半径远大于工具类）。
 
 **Step 2 — 业务层面：找高中心性 concepts（cgraphx docs concepts）**
 
@@ -537,10 +538,10 @@ jq '[.[] | {name, doc_count: .documentCount}] | sort_by(-.doc_count) | .[:30]' \
 对每个 cross-cutting concern 创建 pending item：
 - `type: "cross_cutting_concept"`
 - `entry_symbol`: 高中心性 symbol
-- `entry_files`: `cgraphx impact <symbol> --json` 输出的 `affected[].filePath`
+- `entry_files`: `codegraph_impact(<symbol>)` MCP 报告里 affected symbols 的 `filePath`
 - `related_documents`: markdown 知识库里连接到该 concept 的已有文档路径
 
-跑 Phase 2 探索循环，但用下方的 **Cross-cutting Sub-Agent Template**（强调基于 `cgraphx impact` + 已有文档整合，不重读代码）。
+跑 Phase 2 探索循环，但用下方的 **Cross-cutting Sub-Agent Template**（强调基于 `codegraph_impact` MCP + 已有文档整合，不重读代码）。
 
 **Step 5 — Finalize**
 
@@ -686,7 +687,7 @@ $CODEGRAPH docs find --q="{name}" --limit=5 --json
 1. 从起始符号开始，用 cgraphx 拿完整调用链：
    - 跟踪函数调用链（至少 4-5 层深度，用 `cgraphx callers` / `cgraphx callees`）
    - 识别数据模型、状态转换、错误处理路径（cgraphx 给位置，Read 看实现）
-   - 关注跨模块/跨文件的依赖关系（用 `cgraphx impact {entry_symbol} --json` 看 affected[]）
+   - 关注跨模块/跨文件的依赖关系（用 `codegraph_impact({entry_symbol})` MCP 看影响半径 + affected symbols)
    - 记录外部服务调用（数据库、消息队列、HTTP 调用——通常在 callees 里）
 
 2. 识别业务概念和非显而易见的约束：
@@ -737,16 +738,15 @@ For Phase 3 deep-dive items with `type: "cross_cutting_concept"`：
 中心性 symbol：{entry_symbol}（被 N 个 entry 依赖的高中心性代码符号）
 关联已有文档（Read 这些）：{document_paths}
 
-【工具优先级：cgraphx impact > Read 已有文档 > Read 代码】
+【工具优先级：codegraph_impact MCP > Read 已有文档 > Read 代码】
 
-1. **先看代码影响面**（cgraphx impact）—— 知道这个 symbol 在多少模块/调用链里出现：
+1. **先看代码影响面**（codegraph_impact MCP）—— 知道这个 symbol 在多少模块/调用链里出现：
 
-```bash
-CODEGRAPH="cgraphx"
-# 拿完整 impact 看覆盖广度
-# 输出 {symbol, depth, nodeCount, edgeCount, affected[]}
-# 用 nodeCount 作中心性,affected[] 看影响面涉及的文件/模块
-$CODEGRAPH impact {entry_symbol} --json
+```
+# MCP 调用(取代原 cgraphx impact CLI)
+# 返回格式化影响半径报告:affected symbols + 树状结构 + 跨文件 / 跨模块分布
+# 用报告规模作中心性,涉及的文件/模块分布看影响面
+调用 codegraph_impact({entry_symbol}, depth=2) MCP
 ```
 
 2. **Read 关联已有文档**（{document_paths}）—— 知道业务层面已经记录了什么。
@@ -758,7 +758,7 @@ $CODEGRAPH impact {entry_symbol} --json
 项目名称：{project_name}
 
 【任务】
-1. 用 cgraphx impact 输出构建"代码影响面"：哪些模块/调用链依赖这个 symbol（看 `affected[]` 的 `filePath` 分布），跨多少文件/包，`nodeCount` 多大
+1. 用 codegraph_impact MCP 返回构建"代码影响面"：哪些模块/调用链依赖这个 symbol（看报告中 affected symbols 的 `filePath` 分布），跨多少文件/包，规模多大
 2. 用已有文档（{document_paths}）构建"业务已知"：业务侧如何描述这个 concept
 3. 找 gap：
    - 代码影响面 ≠ 业务已知 → 缺失视角（例：代码层面 OrderService 被 5 个模块调用，但业务文档只覆盖了 2 个）
@@ -775,7 +775,7 @@ document_type 建议：
 
 frontmatter：
 - related_documents 填引用的已有文档
-- related_code 填 cgraphx impact 输出 affected[] 里的高中心性文件
+- related_code 填 codegraph_impact MCP 报告里 affected symbols 涉及的高中心性文件
 - concepts 填此核心 concept + 关联 concept
 
 完成后返回 JSON：

package/dist/.claude-template/skills/developer-timeline/SKILL.md

@@ -266,6 +266,15 @@ cgraphx timeline show <id>
 - ISO 8601:`2026-06-01` / `2026-06-01T00:00:00Z`
 - 相对:`7d` / `12h` / `30m` / `now`
 
+**时区语义(重要)**:
+
+- 所有 `ts` 字段存储为 UTC ISO。
+- 日期字符串 `2026-06-01` 按**本地时区**解释(本地零点,不是 UTC 零点)。`--since=2026-06-01` 覆盖的是本地 6/1 全天,而非 UTC 6/1(后者在 UTC+N 时区会漏掉本地凌晨的工作)。
+- `--format=table` 的 `ts(local)` 列、stats 的 `Window (local)` 行、`byDay` 按日分组 —— **全部按本地时区呈现**,直接是用户墙上时钟的时间,无需再做转换。
+- `--format=json` 的 `ts` / `windowStart` / `windowEnd` **保留 UTC ISO**(带 `Z` 后缀)作为机器可读契约,程序消费时再自行转本地;只有 `byDay[].day` 是本地日期 `YYYY-MM-DD`(分组键,人看的)。
+
+生成 HTML 报告时,从 `--format=table` 拿到的时间已经是本地时间字符串,直接贴进 HTML 即可,不要把 UTC ISO 原样展示给用户。
+
 ### 输出选择
 
 - `table`:推荐给 agent 读,密度高。

package/dist/.claude-template/skills/precommit-review/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: precommit-review
+description: 提交前审查 staged diff 的可疑修改。Use when 被 precommit-check hook 拦截后 / git commit 前审查 / 提交前自检 / 检查可疑修改 / 被注释的开关 / 未闭合逻辑 / 魔法字符串 / 临时标记。agent 自己跑 git diff --cached 逐项判断,不做脚本正则。
+---
+
+## 何时用
+
+- precommit-check hook 拦截了你的 `git commit`,要求审查 → 立刻用本 skill
+- 主动想在提交前自检可疑修改
+- 任何"提交前再过一遍"的兜底场景
+
+## 你要做什么
+
+本 skill 不做脚本正则匹配 —— 你(agent)自己跑 git 命令拿 diff,逐项判断。
+
+### 步骤
+
+1. **列暂存文件**:`git diff --cached --name-status` —— 看哪些文件是 M/D/R(非纯新增)
+2. **拿实际改动**:`git diff --cached` —— 取 staged-vs-HEAD 的完整 diff
+3. **逐项审查**(下面清单),每命中一项就记下来
+4. **把发现讲给用户**,问是否放行
+5. 若干净或用户确认 → 用 `CGRAPHX_PRECOMMIT_REVIEWED=1 git commit ...` 重试提交(带这个 env 前缀,precommit-check hook 会放行)
+
+### 审查清单(逐项判断,不是正则)
+
+- **被注释的开关**:新增的 `// @Component` / `// @Service` / `// @JmsListener` / `// @Scheduled` / `// @ConditionalOnProperty` / `// @Bean` / `// @EventListener` / `// @PostConstruct` 等。Spring 注解被注释 = bean 不加载 / 监听不触发 / 定时不跑 —— 高危,直击历史事故
+- **被注释的业务调用**:新增的 `// executorService.submit(...)` / `// consumer.connect()` / `// consumer.listenTopic(...)` / `// consumeMessage(...)` / `// .start()` / `// .run()` 等。关键链路被注释 = 功能静默失效
+- **未闭合的逻辑**:新增代码块括号失衡、`if`/`try`/`for` 没有配对的 `}`/`catch`/`)`、`return` 在不该断的地方 —— 编译器能抓多数,但看一眼补齐
+- **写死的魔法字符串/数字**:可疑硬编码(密码、URL、ID、阈值)写死在代码里 —— 应抽常量
+- **TODO/FIXME/临时/暂时**:新增行里带这些标记,确认是否应提交还是该当下处理掉
+
+### 判断原则
+
+- 只看**本次新增的**改动(diff 里 `+` 开头的行),不看历史代码
+- 命中任何一项都该 surface 给用户,让用户决定
+- 不替用户改代码 —— 你只审查、报告、等指示
+
+## 输出格式
+
+把发现的每一项按 `文件:行号 + 类别 + 原文` 列给用户,例如:
+
+```
+[关闭的开关] zqassis-service/.../CTGMQConsumerRunner.java:30
+  +//@Component    ← bean 不再装载,确认是否有意
+
+[被注释的业务调用] zqassis-service/.../CTGMQConsumerRunnerPull.java:49
+  +//        executorService.submit(this::consumeMessage);    ← 关键链路被关,确认是否有意
+```
+
+若一项都没命中,明说"未发现可疑修改",提示可用 `CGRAPHX_PRECOMMIT_REVIEWED=1 git commit ...` 提交。

package/dist/.claude-template/skills/run-api-test/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: run-api-test
+description: 在 write-api 生成 .bru 后,跑接口测试 + 核实写接口 DB 副作用 + 出报告。触发时由用户指定需求或接口:指定需求→跑该需求所有接口所有场景,报告归该需求目录;只指定接口→主动问测哪个需求(AI 反查 .bru docs 段关联需求列表让用户选);都没指定→主动问。服务未就绪暂停等待;写接口必须查 DB 验数据(HTTP 200 ≠ 通过);失败只报告不修代码不重跑,交用户决定。不调 write-api / write-api-doc,不改 .bru。Use when 用户要求跑接口测试 / 验证接口 / 测一下需求 X 的接口 / 跑下这个接口;write-api 跑完后用户要求执行测试;代码改完后用户想验证修复。
+---
+
+# Run API Test
+
+## 定位
+
+打靶 skill:在 `write-api` 生成 `.bru` 之后,跑接口测试 + 核实写接口 DB 副作用 + 出报告。不改 .bru、不修代码、不重跑,失败交用户决定。
+
+`write-api` 负责"造弹药",`run-api-test` 负责"打靶"。两者独立,同一份 .bru 可被多次复用(调整代码或断言后重跑)。
+
+## HARD-GATE
+
+- **服务未就绪不盲跑** — 本地服务未起时暂停等待,不把 connection refused 当失败记入报告
+- **写接口必须核实 DB 副作用** — HTTP 200 ≠ 测试通过,POST/PUT/DELETE/PATCH 必须由 AI 用 `db-query skill` 查 DB 验数据
+- **env 文件不自动生成** — `docs/bruno/environments/local.bru` 缺失时报错退出,提示用户先跑 `/write-api`,不自己生成
+- **报告永远归一个 feature 目录** — 即使测试涉及的接口关联多个 feature,报告归用户触发时指定的需求目录,不混
+
+## Trigger
+
+**使用此 skill 当**:
+- 用户完成 `/write-api` 后,要求"跑接口测试""跑一下测试""验证接口"
+- 用户说"run-api-test""测一下需求 X 的接口""跑下这个接口"
+- 代码改完后,用户想重跑接口测试验证修复
+
+**不要使用此 skill 当**:
+- 生成测试接口 → 用 `/write-api`(本 skill 假设 .bru 已存在)
+- 写 HTML 接口文档 → 用 `/write-api-doc`
+- 修代码 / 改 .bru → 用户手动或走 `/implementation`(本 skill 只测不修)
+- 探索陌生项目 → 用 `/code-impact-init`
+- 查代码调用关系 → 用 `/cgraphx` 或 `codegraph_explore` MCP
+
+## 与既有 skill 边界
+
+| skill | 关系 | 说明 |
+|---|---|---|
+| `write-api` | 上游 | 产 .bru + 测试规格 + environments;本 skill 消费这些产物跑测试,不调它也不改 .bru |
+| `write-api-doc` | 独立并列 | 不互相调用;本 skill 产测试报告 + JSONL,write-api-doc 产 HTML 接口文档 |
+| `cgraphx` / `codegraph_explore` | 可选复用 | R1 确定测试范围时,若需定位接口 handler 可用(但通常用户已给接口名,直接用即可) |
+| `db-query` | 复用 | R4 核实写接口 DB 副作用;受 db-query 既有只读约束 |
+| `implementation` / `subagent-implement` | 下游 | 测试失败后由用户决定是否调起修 bug |
+| `code-impact-docgen` | 独立 | 自测后产设计文档 |
+
+## 依赖
+
+- `.bru` 文件已存在(由 `/write-api` 生成,在 `docs/bruno/<服务>/<接口名>/<场景>.bru` 或 `docs/bruno/common/<接口名>/<场景>.bru`)
+- `docs/bruno/environments/local.bru` 存在(不存在时报错退出,提示先跑 `/write-api`)
+- 本地服务可启动(若需手动启动,R2 暂停等待)
+- 项目已配置 db-query profile(R4 核实写接口副作用用)—— 未配置则 R4 降级,见 `references/db-verification.md`
+
+## feature-id 与文件前缀规则
+
+复用既有规则(同 `/write-prd` / `/write-spec` / `/write-plan` / `/write-api-doc` / `/write-api` 的算法):
+
+- feature-id 格式:`YYYY-MM-DD-[业务ID-]<标题>`
+- 文件前缀:有业务ID = `<业务ID>-<标题>`,无业务ID = `<标题>`
+- 文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`
+
+产物文件名(归用户指定的 feature 目录):
+- Markdown 报告:`docs/features/<feature-id>/<文件前缀>-测试报告.md`
+- JSONL 验证记录:`docs/features/<feature-id>/<文件前缀>-测试验证.jsonl`
+
+格式见 `references/report-format.md`。
+
+## 触发逻辑(用户给的是什么?)
+
+这是本 skill 的核心,直接写在 SKILL.md(不抽 reference),因为这是流程编排不是规范细节。
+
+```
+用户触发 /run-api-test
+      ↓
+用户给的是什么?
+      ├─ 指定了需求(feature-id / spec / 需求名)
+      │   → AI 查该需求的 <文件前缀>-api-spec.md,拿到接口清单 + 场景
+      │   → 提示用户确认"本次测试需求 X,涉及 N 接口 M 场景,确认?"
+      │   → 用户确认后进入 R1
+      │
+      ├─ 只指定了接口(接口名/路径)
+      │   → skill 主动问"测哪个需求?"
+      │   → AI 反查该接口 .bru docs 段的"关联需求"列表(可能多个)
+      │   → 列出来让用户选(若 0 个需求,提示用户先跑 /write-api)
+      │   → 选定后,AI 查该需求 api-spec.md 拿该接口的场景
+      │   → 提示用户确认后进入 R1
+      │
+      └─ 都没指定
+          → skill 主动问"请指定需求(feature-id/spec)或接口名"
+          → 拿到回答后回到上面两条分支
+```
+
+**关键约束**:
+- 不管走哪条分支,最终都要锁定一个 feature-id,**报告归该 feature 目录**
+- AI 反查 .bru docs 段关联需求时,读 `docs/bruno/<服务>/<接口名>/*.bru` 里 docs 段的"关联需求"段
+- 用户确认环节不能省 —— AI 理解的范围必须显示给用户,避免跑错需求或接口
+
+## 工作流
+
+按 R1-R5 顺序执行,每步规范细节在对应 reference 文件。
+
+### R1. 确定测试范围
+
+- **前置**:触发逻辑锁定一个 feature-id
+- **行为**:按 `references/test-scope.md` 拿到本次测试的 .bru 清单
+  - 查 `<文件前缀>-api-spec.md` 拿接口清单 + 场景 + .bru 路径
+  - 交叉校验 .bru 文件实际存在
+  - 显示测试范围给用户确认
+- **校验失败**(api-spec 不存在 / .bru 缺失)→ 报错并退出
+- **用户取消** → 退出
+- **结果**:得到本次跑的 .bru 清单
+
+### R2. 本地服务就绪处理
+
+- **前置**:R1 测试范围已确认
+- **行为**:按 `references/service-readiness.md` 做服务就绪检测(两种 TCP 策略,任一通过即就绪)
+- **env 文件缺失** → 报错退出,提示先跑 `/write-api`(本 skill 不生成 env)
+- **服务未就绪** → 暂停提示用户启动,等待回车;不盲跑、不重试
+- **就绪** → 继续 R3
+
+### R3. 跑测试
+
+- **前置**:服务就绪 + env 就绪
+- **行为**:按 `references/bru-run.md` 调用 `bru run` 跑 R1 清单涉及的接口目录
+- **bru run 整体崩溃** → 报"测试执行器异常" + 输出 stderr,**不继续 R4**
+- **结果**:得到每接口每场景的 HTTP 状态、响应体、断言通过情况
+
+### R4. 数据库副作用核实
+
+- **前置**:R3 完成
+- **跳过条件**:R1 清单无写接口(全 GET)→ 跳过本步直接 R5
+- **行为**:按 `references/db-verification.md`,AI 用 `db-query skill` 逐写接口核实副作用
+- **db-query skill 失败** → 该接口记"无法核实" + 状态 `失败-DB副作用`,**不阻塞其他接口**
+- **结果**:逐接口 DB 核实记录写入 JSONL
+
+### R5. 产出测试报告
+
+- **前置**:R3 + R4 完成
+- **行为**:按 `references/report-format.md` 汇总产出
+  - Markdown 报告 `<文件前缀>-测试报告.md`(汇总 + 逐接口结果 + 失败分类 + DB 核实小结 + 下一步建议)
+  - JSONL `<文件前缀>-测试验证.jsonl`(R4 写接口记录 + R5 补齐查询接口记录)
+  - JSON 中间结果丢弃
+- **报告归属**:归用户指定的 feature 目录,即使接口关联多 feature 也不混
+- **结果**:报告落盘;skill 结束
+
+## 异常速查
+
+| 场景 | 行为 |
+|---|---|
+| 用户指定需求但 api-spec 不存在 | 报"需求 X 无测试规格,请先跑 /write-api"并退出 |
+| 用户指定接口但 .bru 不存在 | 报"接口 Y 无 .bru,请先跑 /write-api"并退出 |
+| 用户指定接口但 docs 段无关联需求 | 提示"接口 Y 未声明关联需求,请确认 .bru 由 /write-api 生成" |
+| api-spec §5 列出的 .bru 实际不存在 | 报"需求 X 接口 Y 场景 Z 的 .bru 缺失,请先跑 /write-api"并退出 |
+| 本地服务未启动 | 暂停 + 提示用户启动,等待回车继续 |
+| env 文件缺失 | 报"环境缺失,请先跑 /write-api"并退出,不自动生成 |
+| 服务起了但接口 404 | 记 `失败-HTTP`,标注可能路由未注册或路径不对 |
+| 写接口 HTTP 通但 DB 没改 | 记 `失败-DB副作用`,AI 标注预期 vs 实际差异 |
+| bru run 整体崩溃 | 报"测试执行器异常" + 输出 stderr,不继续 R4 |
+| 同 feature 重复触发 | 覆盖该 feature 报告 + JSONL,不增量合并 |
+| db-query 在 R4 失败 | 该接口记"无法核实" + 状态 `失败-DB副作用`,不阻塞其他接口 |
+| 用户改代码后重跑 | 直接重跑 `/run-api-test` 覆盖报告;只有需重新生成 .bru 入参时才走 `/write-api` |
+
+## 质量检查
+
+跑完后自检:
+- 报告归指定的 feature 目录(`<文件前缀>-测试报告.md` + `<文件前缀>-测试验证.jsonl`)
+- 写接口 DB 核实到位,不存在"只看 HTTP 200 就算过"的写接口
+- 服务未就绪时没盲跑,没产 connection refused 失败报告
+- 失败接口有原因分类(数据问题 / 代码 bug / 服务问题 / 断言过严)
+- 不改 .bru(跑前后 .bru 内容一致)
+- 不自动修代码、不自动重跑
+- env 文件缺失时报错退出,没自己生成
+- JSON 中间结果已丢弃,不归档
+- 用户确认环节有执行(测试范围显示给用户)
+
+## 收尾
+
+提示用户:
+1. 测试报告位置(`<文件前缀>-测试报告.md`)
+2. 通过 / 失败 / 跳过汇总
+3. 失败接口清单 + 原因分类
+4. 下一步建议:
+   - 失败-DB副作用 → 走 `/implementation` 修,修完重跑 `/run-api-test`
+   - 失败-断言 → 确认是代码 bug 还是断言写错
+   - 失败-HTTP → 确认路由注册
+   - 需重新生成 .bru 入参 → 走 `/write-api` 再跑 `/run-api-test`
+
+不主动调用 `/implementation` 或其他下游 skill。不写 knowledge 文件。不修改 spec / plan / 代码 / .bru。

package/dist/.claude-template/skills/run-api-test/assets/template-test-report.md

@@ -0,0 +1,103 @@
+# 接口测试报告模板
+
+适用于 `write-api` skill 在 S7 生成。默认输出到 `docs/features/<feature-id>/<文件前缀>-测试报告.md`。
+
+本模板由 skill 在 S7 填充:汇总 + 逐接口结果 + 失败原因分类 + 下一步建议。
+
+## 完整结构
+
+```markdown
+# 接口测试报告:<feature 标题>
+
+> feature-id: <feature-id>
+> 生成时间: <YYYY-MM-DD HH:MM>
+> 关联测试规格: <文件前缀>-api-spec.md
+> 关联 .bru 集合: docs/bruno/<服务>/<feature-id>/
+
+## 1. 汇总
+
+| 指标 | 值 |
+|---|---|
+| 总接口数 | <N> |
+| 通过 | <N> |
+| 失败 | <N> |
+| 跳过 | <N> |
+| 总耗时 | <ms> |
+
+通过率:<通过/总> %
+
+## 2. 逐接口结果
+
+| 方法 | 路径 | 状态 | HTTP | 断言 | DB 核实 | 耗时(ms) |
+|---|---|---|---|---|---|---|
+| GET | /api/v1/users/:id | 通过 | 200 | 通过 | - | 239 |
+| POST | /api/v1/users | 通过 | 201 | 通过 | 通过 | 512 |
+| PUT | /api/v1/users/:id | 失败-DB副作用 | 200 | 通过 | 失败 | 480 |
+| DELETE | /api/v1/users/:id | 失败-断言 | 200 | 失败 | - | 350 |
+| GET | /api/v1/orders/:id | 失败-HTTP | 404 | - | - | 120 |
+
+状态枚举:通过 / 失败-断言 / 失败-DB副作用 / 失败-HTTP / 失败-连接 / 跳过
+
+## 3. 失败原因分类
+
+### 失败-DB副作用(1 个)
+
+#### PUT /api/v1/users/:id
+- HTTP: 200(接口通)
+- 断言:通过
+- DB 核实:失败
+  - 预期:users 表 name 字段更新为"新名字"
+  - 实际:users 表 name 字段仍为"旧名字"
+  - 差异:name 未更新
+- 可能原因:代码 bug(update 语句未生效)/ 测试数据问题(参数传错)/ 断言过严
+- 建议下一步:走 /implementation 排查 update 逻辑
+
+### 失败-断言(1 个)
+
+#### DELETE /api/v1/users/:id
+- HTTP: 200
+- 断言:失败
+  - 期望:response.body.success = true
+  - 实际:response.body.success = false
+- 可能原因:接口实际未删除(代码 bug)/ 断言写错(响应结构变了)
+- 建议下一步:走 /implementation 排查 delete 逻辑,或调整 .bru 的 tests 段
+
+### 失败-HTTP(1 个)
+
+#### GET /api/v1/orders/:id
+- HTTP: 404
+- 可能原因:路由未注册 / 路径不对 / id 不存在
+- 建议下一步:确认路由注册,或换真实 id
+
+## 4. 写接口 DB 核实小结
+
+| 接口 | 核实结论 | 查询表 | 预期 | 实际 |
+|---|---|---|---|---|
+| POST /api/v1/users | 通过 | users | 新增一行 | 新增一行,id=12346 |
+| PUT /api/v1/users/:id | 失败 | users | name 更新为"新名字" | name 仍为"旧名字" |
+| DELETE /api/v1/users/:id | 未核实(断言已失败) | - | - | - |
+
+## 5. 下一步建议
+
+- 失败-DB副作用(1 个):疑似代码 bug,建议走 `/implementation` 排查 update 逻辑
+- 失败-断言(1 个):需确认是代码 bug 还是断言写错,建议先看响应体再决定
+- 失败-HTTP(1 个):确认路由注册,可能是测试数据问题
+
+修完后重跑 `/write-api` 验证。
+
+## 6. 产物清单
+
+- 测试规格:<文件前缀>-api-spec.md
+- .bru collection:docs/bruno/<服务>/<feature-id>/
+- Markdown 报告:本文件
+- JSONL 验证记录:<文件前缀>-测试验证.jsonl
+```
+
+## 填写说明
+
+- §1 汇总由 S5 + S6 结果统计
+- §2 逐接口结果的"DB 核实"列:查询接口填"-",写接口填"通过/失败/未核实"
+- §3 失败原因分类按状态枚举分组,每组列具体接口 + 预期 vs 实际 + 可能原因 + 建议下一步
+- §4 仅在本次有写接口时填
+- §5 下一步建议按失败类型给,不自动调下游 skill,由用户决定
+- §6 产物清单固定四项

package/dist/.claude-template/skills/run-api-test/assets/template-test-verify.jsonl

@@ -0,0 +1,5 @@
+{"interface": "GET /api/v1/users/:id", "http_status": 200, "assertions": [{"name": "status is 200", "passed": true, "expected": 200, "actual": 200}, {"name": "response has id", "passed": true, "expected": "property id", "actual": "id=12345"}, {"name": "id is number", "passed": true, "expected": "number", "actual": 12345}], "db_verification": {"required": false, "conclusion": "not_required", "queries": [], "expected": null, "actual": null, "error": null}, "final_status": "通过", "duration_ms": 239}
+{"interface": "POST /api/v1/users", "http_status": 201, "assertions": [{"name": "status is 201", "passed": true, "expected": 201, "actual": 201}, {"name": "response has id", "passed": true, "expected": "property id", "actual": "id=12346"}], "db_verification": {"required": true, "conclusion": "通过", "queries": ["SELECT id, name, email FROM users WHERE id = 12346"], "expected": "新增一行 name=测试用户 email=test@example.com", "actual": "新增一行 id=12346 name=测试用户 email=test@example.com", "error": null}, "final_status": "通过", "duration_ms": 512}
+{"interface": "PUT /api/v1/users/:id", "http_status": 200, "assertions": [{"name": "status is 200", "passed": true, "expected": 200, "actual": 200}], "db_verification": {"required": true, "conclusion": "失败", "queries": ["SELECT name FROM users WHERE id = 12345"], "expected": "name 更新为 新名字", "actual": "name 仍为 旧名字", "error": null}, "final_status": "失败-DB副作用", "duration_ms": 480}
+{"interface": "GET /api/v1/orders/:id", "http_status": 404, "assertions": [], "db_verification": {"required": false, "conclusion": "not_required", "queries": [], "expected": null, "actual": null, "error": null}, "final_status": "失败-HTTP", "duration_ms": 120}
+{"interface": "POST /api/v1/users (db-query failed)", "http_status": 201, "assertions": [{"name": "status is 201", "passed": true, "expected": 201, "actual": 201}], "db_verification": {"required": true, "conclusion": "无法核实", "queries": [], "expected": "新增一行", "actual": null, "error": "db-query 连接失败: ConnectionFailedError"}, "final_status": "失败-DB副作用", "duration_ms": 380}

package/dist/.claude-template/skills/run-api-test/references/bru-run.md

@@ -0,0 +1,60 @@
+# R3 跑测试规范
+
+## bru run 命令
+
+```
+bru run docs/bruno/<服务>/<接口名>/ --env local --output <临时 JSON 路径> -r
+```
+
+### 参数说明
+
+| 参数 | 说明 |
+|---|---|
+| 路径参数 | R1 清单涉及的接口目录(从 api-spec §5 取),不是全项目 `docs/bruno/` |
+| `--env local` | 使用 `docs/bruno/environments/local.bru` 的变量(用户切换时透传 `--env staging` / `--env production`) |
+| `--output <path>` | JSON 中间结果输出路径(临时,跑完即丢,不归档) |
+| `-r` | 递归跑目录下所有 .bru |
+
+### 跑哪些接口
+
+**只跑 R1 清单涉及的接口目录**,不是全项目 `docs/bruno/`。
+
+理由:用户指定需求或接口后,范围已锁定;跑全项目是另一个场景(全量回归),用户应自行 `bru run docs/bruno/ -r`,不归本 skill 管。
+
+### 多接口目录的处理
+
+R1 清单可能涉及多个接口目录(如 `getUser/` + `createUser/` + `common/login/`)。两种跑法:
+
+- **分批跑**:每个接口目录单独 `bru run`,结果汇总(更细粒度,易定位崩溃)
+- **合并跑**:把所有路径作为参数一次跑(bru run 支持多路径参数)
+
+推荐**分批跑**——某个接口目录崩溃时不影响其他接口,且日志更清晰。
+
+## 失败处理
+
+### 单接口失败(bru run 正常返回,但某些接口 HTTP 错或断言失败)
+
+不算崩溃,继续 R4。失败的接口在 JSON 中间结果里有状态,汇总到 R5 报告。
+
+### bru run 整体崩溃(进程退出非 0,非单接口失败)
+
+报"测试执行器异常" + 输出 bru 原始 stderr,**不继续 R4**。
+
+崩溃常见原因:
+- bruno CLI 版本 bug
+- .bru 文件语法错(write-api 生成的 .bru 不符合 bruno-lang v2)
+- 环境配置错(env 文件读不了)
+
+崩溃时不继续 R4——继续也没意义(JSON 中间结果可能不完整);让用户判断是修 .bru、调 bruno 版本,还是回 write-api 重新生成。
+
+## JSON 中间结果
+
+`bru run --output <path>` 产出的 JSON,**临时产物,不归档**。
+
+理由:JSON 是 bruno 的执行原始记录,字段多且对用户不友好;最终给用户看的是 R5 的 Markdown 报告 + JSONL 验证记录。JSON 跑完即丢。
+
+## bru CLI 版本
+
+测试工具是开源 bruno(`@usebruno/cli`),要求项目已装 bru CLI(`npm install -g @usebruno/cli` 或项目本地装)。
+
+若 bru 命令不存在 → 报"未找到 bru CLI,请先装 `npm install -g @usebruno/cli`"并退出。