cgraphx 1.2.0 → 1.3.0

package/dist/.claude-template/hooks/precommit-check/precommit-check.cjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook for Bash: precommit-check
+ *
+ * 守门员:拦截 git commit(当暂存含修改/删除/重命名文件时),要求 agent
+ * 先调用 /precommit-review skill 审查 staged diff,再带
+ * CGRAPHX_PRECOMMIT_REVIEWED=1 前缀重试。纯新增文件直接放行,不制造摩擦。
+ *
+ * 本脚本不做差异判断 —— 只做"是不是 git commit + 有没有非纯新增文件"的
+ * 事实判定。真正的可疑模式识别由 /precommit-review skill 让 agent 自己
+ * 跑 git diff --cached 比对完成。
+ *
+ * 输出协议(PreToolUse):命中拦截时输出
+ *   { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *                           permissionDecision: "deny",
+ *                           permissionDecisionReason: <指名 /precommit-review> } }
+ * 不命中时静默 exit 0(放行)。任何异常都吞掉 exit 0,永不阻断正常流程。
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+const ENV_BYPASS = 'CGRAPHX_PRECOMMIT_REVIEWED=1';
+
+function readInput() {
+  try {
+    const data = fs.readFileSync(0, 'utf-8');
+    return data ? JSON.parse(data) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+}
+
+function main() {
+  const input = readInput();
+  const cmd = String((input && input.tool_input && input.tool_input.command) || '');
+
+  // 只拦 git commit(覆盖 -m / --amend / --fixup 等所有子形式)
+  if (!/\bgit\s+commit\b/.test(cmd)) return;
+
+  // 已审查过的重试 —— agent 在 skill 审查后会带 ENV_BYPASS 前缀重提交
+  if (cmd.includes(ENV_BYPASS)) return;
+
+  // 拿暂存文件状态
+  let staged;
+  try {
+    staged = execSync('git diff --cached --name-status', {
+      encoding: 'utf-8',
+      cwd: process.cwd(),
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }) || '';
+  } catch (e) {
+    return; // 非 git 仓库 / git 不可用 —— 不阻断
+  }
+  if (!staged.trim()) return; // 没暂存任何东西,交给 git 报错
+
+  // 纯新增(A)直接放行;M/D/R/C/T/U 等都视为"非纯新增"
+  const nonNew = staged
+    .split('\n')
+    .filter(Boolean)
+    .filter((line) => line.split('\t')[0] !== 'A');
+
+  if (nonNew.length === 0) return; // 纯新增,放行
+
+  const reason =
+    `本次 git commit 暂存了 ${nonNew.length} 个修改/删除/重命名文件,提交前请先调用 ` +
+    `\`/precommit-review\` skill 审查 staged diff —— 检查被注释的开关(如 // @Component / @JmsListener / @Scheduled)、` +
+    `被注释的业务调用、未闭合的逻辑、写死的魔法字符串、TODO/临时标记等可疑修改。\n\n` +
+    `审查通过(或确认无需修改)后,用以下形式重试提交以跳过本检查:\n` +
+    `  ${ENV_BYPASS} git commit ...\n\n` +
+    `(本 hook 不做差异判断,只做守门;真正的可疑识别由 /precommit-review skill 让 agent 自己比对 staged diff 完成。)`;
+
+  deny(reason);
+}
+
+try {
+  main();
+} catch (e) {
+  // hook 永不阻断正常流程 —— 任何意外都放行
+}

package/dist/.claude-template/skills/cgraphx-guide/how-to-use.html

@@ -186,49 +186,61 @@ footer {
 footer p { margin: 0; }
 
 /* docs/ 目录速查 */
-.docs-map {
-  list-style: none;
-  padding-left: 0;
-  margin: 0;
-}
-.docs-map li {
-  padding: 12px 0;
-  border-bottom: 1px dashed var(--color-border);
-  margin-bottom: 0;
+.docs-tree {
+  background: var(--color-bg-subtle);
+  border: 1px solid var(--color-border);
+  border-left: 4px solid var(--color-cgraphx);
+  border-radius: var(--radius);
+  padding: 22px 26px;
+  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  font-size: 13.5px;
+  line-height: 1.8;
+  color: var(--color-text);
+  overflow-x: auto;
+  margin: 0 0 16px;
+  white-space: pre;
 }
-.docs-map li:last-child { border-bottom: none; padding-bottom: 0; }
-.docs-map .dir {
+.docs-tree b {
   font-weight: 600;
   color: var(--color-primary-dark);
-  background: var(--color-bg-code);
-  padding: 2px 6px;
-  border-radius: 3px;
-  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-  font-size: 0.85em;
-  margin-right: 8px;
-  white-space: nowrap;
 }
-.docs-map .desc {
-  color: var(--color-text-secondary);
-  font-size: 14.5px;
+.docs-tree .skill {
+  color: var(--color-primary);
+  font-weight: 600;
 }
-.docs-map .owner {
-  display: block;
-  margin-top: 6px;
-  font-size: 13px;
+.docs-tree .ann {
   color: var(--color-text-tertiary);
-  line-height: 1.6;
 }
-.docs-map .owner code { font-size: 12.5px; }
-.docs-map .owner .label {
+.docs-tree .must {
+  color: #2e7d32;
   font-weight: 600;
+}
+.docs-tree .opt {
+  color: #e65100;
+  font-weight: 600;
+}
+.docs-legend {
+  display: flex;
+  gap: 20px;
+  flex-wrap: wrap;
+  font-size: 13px;
   color: var(--color-text-secondary);
-  margin-right: 4px;
+  margin: 0 0 20px;
 }
-.docs-map .owner .manual {
-  color: var(--color-text-tertiary);
-  font-style: italic;
+.docs-legend span {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+.docs-legend .dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
 }
+.docs-legend .dot.must { background: #2e7d32; }
+.docs-legend .dot.opt { background: #e65100; }
+.docs-legend .dot.local { background: var(--color-cgraphx); }
 
 /* Responsive */
 @media (max-width: 768px) {
@@ -250,7 +262,7 @@ footer p { margin: 0; }
   <div class="eyebrow">cgraphx 安装与使用</div>
   <h1>cgraphx 怎么用</h1>
   <p class="subtitle">本地优先的代码智能 · 给 AI agent 用的代码图谱</p>
-  <p class="meta">最后更新:2026-07-02</p>
+  <p class="meta">最后更新:2026-07-13</p>
 </header>
 
 <section>
@@ -313,6 +325,16 @@ footer p { margin: 0; }
       </ul>
     </div>
 
+    <div class="phase">
+      <div class="phase-label">编码完成后 · 按需</div>
+      <ul class="phase-list">
+        <li><code>/write-api</code> 自动生成 bruno 测试接口<em>（识别新增接口 → 生成测试规格 + .bru + 多环境配置 + bruno.json,只造弹药不跑测试）</em></li>
+        <li><code>/run-api-test</code> 跑接口测试 + 核实写接口 DB 副作用 + 出报告<em>（指定需求或接口触发；写接口必须查 DB 验数据,HTTP 200 ≠ 通过；失败只报告不修不重跑）</em></li>
+        <li><code>/write-api-doc</code> 生成静态 HTML 接口文档<em>（与 write-api / run-api-test 独立并列）</em></li>
+        <li><code>/code-impact-docgen</code> 自测通过后合成 feature 设计文档</li>
+      </ul>
+    </div>
+
     <div class="phase">
       <div class="phase-label">工作回顾 · 按需</div>
       <ul class="phase-list">
@@ -347,54 +369,53 @@ footer p { margin: 0; }
 
 <section>
   <h2>docs/ 目录速查</h2>
-  <p>翻文档时知道去哪儿找 —— 哪个目录由哪个 skill 自动维护、哪些是项目自身的文档。</p>
-
-  <ul class="docs-map">
-    <li>
-      <code class="dir">docs/knowledge/</code>
-      <span class="desc">业务知识库 —— 决策 / 概念定义 / 历史教训,被 <code>codegraph_docs_*</code> 索引。</span>
-      <span class="owner"><span class="label">维护:</span><code>code-impact-markdown</code>、<code>code-impact-init</code> 写;<code>code-impact-api</code> 查;<code>code-impact-docgen</code> 从这里合成人类阅读文档。</span>
-    </li>
-    <li>
-      <code class="dir">docs/features/</code>
-      <span class="desc">单次需求的工作目录 —— <code>{date}-{slug}/</code> 下集中放 PRD / spec / plan / knowledge。</span>
-      <span class="owner"><span class="label">维护:</span>全流程 skills —— <code>clarify-requirements</code> → <code>write-prd</code> → <code>write-spec</code> → <code>write-plan</code> → <code>implementation</code> / <code>subagent-implement</code>。</span>
-    </li>
-    <li>
-      <code class="dir">docs/schema-knowledge/</code>
-      <span class="desc">DB schema 知识沉淀 —— 表结构 / 字段含义 / 业务假设的验证记录。</span>
-      <span class="owner"><span class="label">维护:</span><code>db-query</code>(查 MySQL / PostgreSQL 后自动沉淀)。</span>
-    </li>
-    <li>
-      <code class="dir">docs/reports/</code>
-      <span class="desc">时间线报告 —— 日报 / 周报 / 月报 HTML。</span>
-      <span class="owner"><span class="label">维护:</span><code>developer-timeline</code>。</span>
-    </li>
-    <li>
-      <code class="dir">docs/published/</code>
-      <span class="desc">面向人类阅读的合成文档(HTML / Markdown),对外可分享。</span>
-      <span class="owner"><span class="label">维护:</span><code>code-impact-docgen</code>(从 <code>docs/knowledge/</code> 合成产出)。</span>
-    </li>
-    <li>
-      <code class="dir">docs/benchmarks/</code>
-      <span class="desc">cgraphx 自身的性能基准 / 检索质量对比文档。</span>
-      <span class="owner"><span class="manual">无 skill 维护 —— maintainer 配合 <code>agent-eval</code> 手动产出。</span></span>
-    </li>
-    <li>
-      <code class="dir">docs/design/</code>
-      <span class="desc">cgraphx 自身的设计文档 —— 架构 / 算法 / 方法论 playbooks。</span>
-      <span class="owner"><span class="manual">无 skill 维护 —— maintainer 手动维护。</span></span>
-    </li>
-    <li>
-      <code class="dir">docs/plans/</code>
-      <span class="desc">历史遗留的早期计划文档;新需求一律走 <code>docs/features/{id}/plan/</code>。</span>
-      <span class="owner"><span class="manual">无 skill 维护 —— 仅历史归档,不要往这里写新文件。</span></span>
-    </li>
-  </ul>
+  <p>翻文档时知道去哪儿找 —— 哪个目录由哪个 skill 自动维护。</p>
+
+  <div class="docs-legend">
+    <span><span class="dot must"></span>必有</span>
+    <span><span class="dot opt"></span>可选(按需)</span>
+    <span><span class="dot local"></span>本地测试相关</span>
+  </div>
+
+  <pre class="docs-tree"><b>docs/</b>                                              <span class="ann"># 必有</span>
+├── <b>bruno/</b>                                          <span class="ann"># 本地,write-api + run-api-test 维护</span>
+│   ├── bruno.json                                  <span class="ann"># bruno app 识别整个 collection</span>
+│   ├── <b>environments/</b>
+│   │   ├── local.bru                               <span class="ann"># write-api 生成骨架,用户填 secret</span>
+│   │   ├── staging.bru
+│   │   └── production.bru
+│   ├── <b>common/</b>                                   <span class="ann"># 通用接口(登录 / 健康检查等)</span>
+│   │   └── &lt;接口名&gt;/&lt;场景&gt;.bru
+│   └── <b>&lt;服务名&gt;/</b>                                <span class="ann"># 如 a-service / b-service</span>
+│       └── <b>&lt;接口名&gt;/</b>                              <span class="ann"># 接口跨 feature 复用,不绑 feature-id</span>
+│           ├── &lt;场景1&gt;.bru                          <span class="ann"># 如 正常.bru</span>
+│           └── &lt;场景2&gt;.bru                          <span class="ann"># 如 缺prodInstId.bru</span>
+│
+├── <b>features/</b>                                       <span class="ann"># 必有,全流程 skills 维护</span>
+│   └── <b>&lt;前缀&gt;/</b>                                   <span class="ann"># 前缀 = 需求/bug编号 + 名称,如 CRM-req19230-号百商品详情查询接口</span>
+│       ├── &lt;前缀&gt;-需求文档.md                       <span class="skill">/write-prd</span>
+│       ├── &lt;前缀&gt;-spec.md                           <span class="must">必有</span>  <span class="skill">/write-spec</span>
+│       ├── <b>plan/</b>                                <span class="opt">可选</span>  <span class="ann">(按复杂度)</span>  <span class="skill">/write-plan</span>
+│       ├── &lt;前缀&gt;-api-spec.md                      <span class="skill">/write-api</span>
+│       ├── &lt;前缀&gt;-测试报告.md                        <span class="skill">/run-api-test</span>
+│       ├── &lt;前缀&gt;-测试验证.jsonl                    <span class="skill">/run-api-test</span>
+│       └── &lt;前缀&gt;-设计文档.md                        <span class="skill">/code-impact-docgen</span>
+│
+├── <b>knowledge/</b>                                     <span class="ann"># 公共必选,业务知识库</span>
+│                                                      <span class="skill">/code-impact-init</span> <span class="ann">批量写</span>
+│                                                      <span class="skill">/code-impact-markdown</span> <span class="ann">按需写</span>
+│
+└── <b>schema-knowledge/</b>                             <span class="opt">可选</span>  <span class="ann">DB schema 知识</span>
+                                                       <span class="skill">/db-query</span> <span class="ann">自动写</span>
+  </pre>
+
+  <div class="highlight">
+    <p><strong>两个核心目录</strong>——<code>docs/features/</code> 是单次需求工作目录(必须有 spec.md),<code>docs/knowledge/</code> 是跨需求共享的业务知识库。<strong>bruno/ 和 schema-knowledge/ 按需出现</strong>,只在跑接口测试 / 查 DB 时产生。</p>
+  </div>
 </section>
 
 <footer>
-  <p>cgraphx 使用说明 · 2026-07-02</p>
+  <p>cgraphx 使用说明 · 2026-07-13</p>
 </footer>
 
 </div>

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 产物清单固定四项