cgraphx 1.4.3 → 2.0.1

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

@@ -4,7 +4,7 @@
 
 | 产物 | 路径 | 用途 |
 |---|---|---|
-| Markdown 报告 | `docs/features/<feature-id>/<文件前缀>-测试报告.md` | 给人看:汇总 + 逐接口结果 + 失败分类 + DB 核实小结 + 下一步建议 |
+| Markdown 报告 | `docs/features/<feature-id>/<文件前缀>-测试报告.md` | 给人看:汇总 + 逐场景详细结果 + 失败汇总 + DB 核实小结 + 下一步建议 |
 | JSONL 验证记录 | `docs/features/<feature-id>/<文件前缀>-测试验证.jsonl` | AI 逐接口 DB 验证记录,供下游 skill 程序化处理 |
 
 **JSON 中间结果**(R3 `bru run --output` 产的)临时,**不归档**——跑完即丢。
@@ -23,36 +23,69 @@
 
 | 指标 | 值 |
 |---|---|
-| 总接口数 | N |
+| 总场景数 | N |
 | 通过 | N |
 | 失败 | N |
 | 跳过 | N |
 | 总耗时 | ms |
 | 通过率 | % |
 
-### §2. 逐接口结果
+### §2. 逐接口结果 ⭐ 核心
 
-| 方法 | 路径 | 场景 | 状态 | HTTP | 断言 | DB 核实 | 耗时(ms) |
-|---|---|---|---|---|---|---|---|
+按接口聚合展示，每个接口包含:
 
-- 查询接口的 DB 核实列填 `-`
-- 写接口填 通过 / 失败 / 未核实
+1. **接口头**: 方法 + 路径 + 状态 + 场景数 + 总耗时
+2. **场景摘要**: 所有场景一行一个（状态 + 耗时 + 展示级别）
+3. **场景详情**: 仅详细展示的场景（见下方"展示级别判定规则"）
 
-### §3. 失败原因分类
+#### 展示级别判定规则
 
-按状态枚举分组,每组列具体接口 + 预期 vs 实际 + 可能原因 + 建议下一步。
+| 场景类型 | 展示级别 | 说明 |
+|---|---|---|
+| **主场景（正常流程）** | **详细** | 核心业务路径，必须详细记录 |
+| **涉及业务规则的异常/边界** | **详细** | 如：库存不足、余额不足、状态机流转等 |
+| **简单边界（空值/格式错误/越权）** | **简单** | 如：必填字段缺失、格式非法、无权限等 |
+| **失败场景** | **详细** | 无论类型，失败场景必须详细展示 |
+
+**约束**: 一个接口最多 2 个详细展示的场景。
+
+#### 场景摘要格式（简单展示）
+
+```markdown
+#### 场景摘要
+
+| 场景 | 状态 | 耗时 | 展示级别 |
+|---|---|---|---|
+| 正常查询 | ✅ 通过 | 120 ms | **详细** |
+| id 不存在 | ✅ 通过 | 110 ms | 简单 |
+| id 格式非法 | ✅ 通过 | 115 ms | 简单 |
+```
+
+#### 场景详情格式（详细展示）
+
+包含：场景头 + 入参 + 请求 + 响应 + 断言判定 + DB 核实 + 失败分析（仅失败）
+
+### §3. 失败汇总
+
+| 状态 | 数量 | 接口 |
+|---|---|---|
+| 失败-DB副作用 | N | 接口名 |
+| 失败-断言 | N | 接口名 |
+| 失败-HTTP | N | 接口名 |
+| **合计** | **N** | |
 
 ### §4. 写接口 DB 核实小结
 
-| 接口 | 核实结论 | 查询表 | 预期 | 实际 |
+| 接口 | 场景 | 结论 | 查询表 | 预期 | 实际 | 差异 |
+|---|---|---|---|---|---|---|
 
 仅在本次有写接口时填。
 
 ### §5. 下一步建议
 
-按失败类型给建议,不自动调下游 skill:
+按失败类型给建议，不自动调下游 skill:
 
-- 失败-DB副作用 → 疑似代码 bug,走 `/implementation`
+- 失败-DB副作用 → 疑似代码 bug，走 `/implementation`
 - 失败-断言 → 确认是代码 bug 还是断言写错
 - 失败-HTTP → 确认路由注册
 
@@ -62,13 +95,15 @@
 
 ## JSONL 字段
 
-每行一个 JSON,逐接口(每场景)一条。字段:
+每行一个 JSON，逐接口(每场景)一条。字段:
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `interface` | string | 方法 + 路径(如 `GET /api/v1/users/:id`) |
-| `scenario` | string | 场景名(如 `正常` / `缺prodInstId`) |
+| `scenario` | string | 场景名(如 `正常查询` / `缺prodInstId`) |
 | `http_status` | number | HTTP 状态码 |
+| `request` | object | {method, url, headers, body} |
+| `response` | object | {status, headers, body} |
 | `assertions` | array | 断言结果:[{name, passed, expected, actual}] |
 | `db_verification` | object | {required: bool, conclusion: "通过"/"失败"/"无法核实"/"not_required", queries: [], expected, actual, error} |
 | `final_status` | string | 状态枚举(见下方) |
@@ -86,19 +121,19 @@
 |---|---|
 | `通过` | HTTP 通 + 断言通 + (写接口)DB 核实通 |
 | `失败-断言` | HTTP 通但断言失败 |
-| `失败-DB副作用` | HTTP 通 + 断言通,但 DB 数据不符合预期 |
+| `失败-DB副作用` | HTTP 通 + 断言通，但 DB 数据不符合预期 |
 | `失败-HTTP` | 4xx / 5xx |
 | `失败-连接` | 超时 / connection refused(仅在服务就绪后仍失败时记) |
 | `跳过` | skill 主动跳过(如 .bru 缺失、环境降级) |
 
-**服务未就绪导致的暂停不记入报告,不算失败**(服务未起时 skill 在 R2 暂停,根本没进 R3)。
+**服务未就绪导致的暂停不记入报告，不算失败**(服务未起时 skill 在 R2 暂停，根本没进 R3)。
 
 ## JSON 中间结果处理
 
 R3 的 `bru run --output <path>` 产的 JSON:
 
-- 跑完 R3 后,R4 / R5 读它做核实和汇总
-- R5 完成后**立即丢弃**(skill 删除临时文件,或放系统临时目录自动清理)
+- 跑完 R3 后，R4 / R5 读它做核实和汇总
+- R5 完成后**立即丢弃**(skill 删除临时文件，或放系统临时目录自动清理)
 - 不归档到 `docs/features/<feature-id>/`
 
-理由:JSON 是 bruno 的原始执行记录,字段多且对用户不友好;最终给用户看的是 Markdown 报告 + JSONL 验证记录。保留 JSON 会造成"两份真相"混淆。
+理由:JSON 是 bruno 的原始执行记录，字段多且对用户不友好；最终给用户看的是 Markdown 报告 + JSONL 验证记录。保留 JSON 会造成"两份真相"混淆。

package/dist/.claude-template/skills/subagent-implement/SKILL.md

@@ -7,219 +7,96 @@ description: 复杂 plan 的子 agent 实现流程 — 主 agent 作为 controll
 
 ## 定位
 
-把已确认的 plan(`docs/features/<feature-id>/plan/`)拆成多个独立任务,**主 agent 作为 controller**,按依赖批次派 implementer 子 agent 实现。主 agent 默认负责协调、验证和收口;仅对 reviewer 指出的低风险微修可直接修改。所有任务完成后派 final quality reviewer 整体审查。
+- **主 agent 是统帅不是先锋**:只协调、把关、收口;实现全部派隔离上下文的 implementer 子 agent。
+- **质量靠结构,不靠自觉**:四件套注入让执行者无法漂移,sanity check 把每任务关,quality-reviewer 把最终关。
+- **门槛**:有 plan(或明确任务清单)+ ≥3 个任务 + 跨多文件域,或主 agent 上下文装不下。单文件/单模块/1-2 个任务 → 走 `implementation`;任务强耦合(后任务依赖前任务实时反馈)→ 走 `implementation`。
 
-**与 implementation 的差别**:
-- `implementation` —— 主 agent 在主会话顺序执行,自己改代码。适合**单点改动 / 小范围 / 1-3 文件**
-- `subagent-implement`(本 skill)—— 主 agent 以协调为主,派子 agent 在隔离上下文实现。适合**复杂 plan / 多任务 / 跨多文件**
+## 流程
 
-## 何时用(决策树)
-
-```
-有 plan(docs/features/<feature-id>/plan/)或明确任务清单?
-├── 否 → 不要用本 skill,走 implementation 或先 write-plan
-└── 是 → 任务数 ≥ 3 且跨多文件?
-    ├── 否(简单任务) → 走 implementation,主会话直接做
-    └── 是(复杂 plan) → 走本 skill
-        └── 任务能拆成相对独立的子任务?
-            ├── 是 → 本 skill 标准模式(按依赖批次执行;默认串行,显式无冲突可并行)
-            └── 否(任务高度耦合,后任务依赖前任务实时反馈) → 走 implementation
 ```
+1. 读 plan 一次 → 提取所有任务全文 → TodoWrite 跟踪
+   (前置:plan 已过 write-plan 的 Plan Review)
 
-**典型适用场景**:
-- feature plan 拆了 5+ 个任务,跨 schema / backend / frontend / test 多个域
-- 多个独立工具/命令的实现
-- 同时改 N 个 skill 文件(参考 `2026-06-27-exploration-subagent-dispatch` plan)
-- 多语言/多框架并行支持
-
-**不适用**:
-- 单文件 bug 修复 → `implementation`
-- 重构单个模块 → `implementation`
-- 任务间强耦合(后任务必须基于前任务实时调整)→ `implementation`
+2. 按依赖批次执行(默认串行;并行条件见红线①):
+   派 implementer(四件套)→ 处理 status → sanity check → 标记完成
+   → 任务标了「独立提交」且 sanity check 通过 → 按 plan「提交规范」节提交(小步原子提交)
 
-## 核心流程
+3. 全部完成 → 派 quality-reviewer 整体审查(必派、仅一次、在自审+sanity check 之后)
+   → 不通过:主 agent 微修或派 fix 子 agent → 重审
 
+4. 收尾:汇报 + 沉淀提示 + 未提交任务的 commit/PR 交用户决定(push 永远归用户)
 ```
-1. 读 plan 一次 → 提取所有任务全文 + context → TodoWrite 跟踪
-   (前置:plan 已过 write-plan 的 Plan Review 阶段,完整性 / spec 对齐已审)
-
-2. 按依赖批次执行任务:
-   a. 默认一次派 1 个 implementer;只有任务在 plan 中被标为"可并行"且通过无冲突检查时,才同批派多个 implementer
-   b. 派 implementer 子 agent(把任务全文 + context 拼进 prompt;可附 index.md 摘要,不让子 agent 读全 plan)
-   c. 处理 implementer status(见下文)
-   d. **主 agent sanity check**:
-      - 看 implementer 报告合理性(改了哪些文件 / 测试是否真绿 / 自审发现是否已修)
-      - 不通过 → 派 implementer 修 / 补 context / 主 agent 做低风险微修 / 上报
-   e. 通过 → 标记任务完成 → 下个任务或下一批
-
-3. 所有任务完成后:
-   - 派 final quality-reviewer 子 agent(整体审查:架构、命名一致性、文件组织、跨任务问题)
-   - 不通过 → 按问题大小选择主 agent 低风险微修或派 fix 子 agent 修 → quality-reviewer 重审
-   - 通过 → 收尾(提示用户走 commit / PR / finish-feature)
-
-4. 收尾汇报:
-   - 完成的任务清单
-   - 各阶段审查发现的问题 + 修复情况
-   - 剩余风险 / 未覆盖项
-```
-
-**审查粒度**(关键设计):
-- **spec/plan 忠实度审查按风险派** —— plan 阶段已经审可执行性;执行阶段对高风险、探索性强、跨契约任务再派 spec-reviewer,重点查漏做 / 多做 / 误解 / plan drift。
-- **quality 审查仅最终一次** —— 代码质量问题(命名、架构、文件组织、跨任务协同)跨任务才能看出,集中审更经济。
-- **implementer 自审** —— 子 agent 完成后自己先 review,主 agent sanity check 看报告和 plan 忠实度即可。
-
-**为什么这样设计**:plan 阶段的 plan-document-reviewer 已经把"plan 是否完整可执行"的问题解决了。执行阶段按风险派 spec-reviewer,避免每个小任务都重复审查,同时保留高风险任务和 plan 偏离风险的独立验证。
 
-## 任务调度策略
+### 派任:四件套注入
 
-**默认串行**:没有明确并行标记时,一次只派 1 个 implementer,避免上下文偏差和代码冲突。
+不把整套 plan 丢给 implementer。每个子 agent 的 prompt 只装:
 
-**允许显式无冲突并行**:只有同时满足以下条件,主 agent 才能同批派多个 implementer:
+1. **任务全文**(含 必须严格执行 / 允许局部适配 / 完成条件 / 对应 spec 条款)
+2. **index.md 契约节** —— 该任务引用的跨任务共享契约,原文注入(不是"见 index"的指涉)
+3. **任务引用的 spec 条款** —— 原文,不转述
+4. **任务「强制引用」的规范** —— plan 标注的 docs/guides/ 文件 + 章节标题(schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md),要求 implementer 开工前读;controller 不自行补齐(标注是 plan 的职责,缺标注是 plan 质量问题)
 
-- plan 的 `index.md` 把这些任务列为可并行,且任务之间没有依赖关系。
-- 涉及文件集合不重叠;如果改同一目录,改动对象也必须清楚分离。
-- 不共享 schema、公共类型、公共 API、全局配置、测试 fixture、锁文件或生成物。
-- 验证命令不会互相污染状态(例如共享数据库、快照、临时文件)。
-- 每个并行任务的 prompt 都写明"本批并行任务列表"和"禁止触碰其他任务文件"。
+另给:依赖任务的完成摘要、相关代码上下文、验证命令。**不给**:无关子计划、其他任务的实现细节、会诱导扩范围的背景材料。implementer 觉得不够 → 返回 `NEEDS_CONTEXT`;可允许它只读 `index.md`,仍不读完整 plan 目录。
 
-**并行收口**:
+### status 协议
 
-- 任一并行任务返回 `BLOCKED` / `NEEDS_CONTEXT` / `DONE_WITH_CONCERNS(correctness/scope)` 时,暂停同批后续合并判断,先解决该任务。
-- 同批任务完成后,主 agent 必须看整体 `git diff`,确认没有文件冲突、重复实现或概念命名分叉,再进入下一批。
-- 如果发现同批任务实际发生文件重叠或公共契约冲突,停止并行模式,改为串行修复。
-
-## 何时该派 spec-reviewer(可选)
-
-**默认不派**:低风险任务的 plan 完整性已经在 plan-document-reviewer 阶段审过,implementer 报告 + 主 agent sanity check + 跑测试通常足以判断完成。
-
-**例外允许派**(主 agent 判断或用户要求):
-
-| 场景 | 为什么派 |
+| Status | 主 agent 处理 |
 |---|---|
-| **任务探索性强** —— plan 阶段无法预知实际行为(如外部 API 输出字段、第三方库行为) | 实际实现可能跟 plan 假设不一致,需要独立验证 |
-| **跨多文件耦合** —— 一个改动影响多处(如改公共类型签名) | 影响范围大,扩散代价高 |
-| **plan-document-reviewer 标了"高风险"任务** | 主 agent 在 plan 阶段已知风险,执行时复查 |
-| **用户主动要求** | 用户判断需要 |
-| **plan 没经过 Plan Review**(write-plan 跳过了) | 没有 plan 阶段审查兜底,建议派(非强制,主 agent 判断) |
-
-**派的方法**:用同目录下 `spec-reviewer-prompt.md` 模板,把任务全文 + implementer 报告 + 工作目录拼成 prompt,派 `general-purpose` 子 agent。
-
-## 主 agent 是 controller(默认不是 implementer)
+| **DONE** | sanity check → 进下个任务 |
+| **DONE_WITH_CONCERNS** | concerns 关于 correctness/scope/plan drift → 先解决;关于 observation(如"文件偏大")→ 记录后进 sanity check |
+| **NEEDS_CONTEXT** | 补 context 重派 |
+| **PLAN_CONFLICT** | 暂停,回到用户/plan/spec 确认。小偏差(实现细节/行号/变量名)implementer 自行调整并报告;大偏差(架构/模块缺失/业务规则/数据口径/API/权限/schema/验收要变)必须上报,不得让 implementer 自行换方案 |
+| **BLOCKED** | 辨因:context 不够 → 补;推理不够 → 换更强 model;任务太大 → 拆分;plan 错了 → 上报。不许同 model 原地重试 |
 
-主 agent 在本 skill 中默认只做协调,但允许处理低风险微修:
+### sanity check(每任务)
 
-- ✅ 读 plan、提取任务全文、构造子 agent prompt
-- ✅ 处理子 agent status、回答子 agent 提问
-- ✅ 跟踪任务进度(TodoWrite)
-- ✅ sanity check 审查结论、决定是否进入下个任务
-- ✅ 对 reviewer 指出的低风险微修可直接 Edit/Write
-- ❌ 不绕过子 agent 自己实现
+看:改了哪些文件 / 测试是否真绿 / 自审发现是否已修 / 契约与引用的规范条目是否被遵循。不通过 → 派 implementer 修 / 补 context / 主 agent 微修 / 上报。
 
-**为什么**:子 agent 在隔离上下文实现,主 agent 上下文保持干净,用于协调多任务;但对拼写、导入、格式、明显小逻辑漏改这类微修,再派 fix agent 会增加延迟和 token。
+### 独立提交(按 plan 标注,小步原子提交)
 
-### 主 agent 可直接微修的条件
+任务标了「独立提交:是」且 sanity check 通过 → 主 agent 提交该任务(不等到全部完成)。这是**用户批准 plan 时一并批准的提交**,不是擅自提交——plan 里写了提交粒度与 message 主题,用户过审 plan 即认可。
 
-必须同时满足:
+- **谁提交:主 agent(controller),不是 implementer**。决定性理由是**验证时序**:单任务时序是「派 implementer → 处理 status → sanity check → 标记完成」,sanity check 发生在 implementer 返回**之后**。若 implementer 自己提交,它是在「自报完工」时提交,controller 的 sanity check 还没跑——一旦不过(测试没真绿、契约被违反),就落了个坏提交得 amend/revert 去擦。提交点必须和验证闸门同侧,而闸门在 controller 手里,所以只有 controller 能保证「只提交验证过的东西」。次要理由:一个写手 = 一种 message 风格(N 个子 agent 各写各的会漂移);controller 手里本来就有 plan 的「提交规范」节。提交是 git 收纳动作,不是「实质实现」,不违反红线⑥。
+- **stage 范围**:implementer 在 DONE 摘要里**报告它改动的确切文件清单**,controller 精确 stage 这些文件后提交。默认串行下这很干净——前面任务都已提交,工作区只剩当前任务的改动。implementer 只改文件、不 `git add`/`commit`(职责边界见 `implementer-prompt.md`)。
+- **并行批的边界**:「独立提交」是**串行流程**的特性。并行批次里,现有流程要求「同批完成后看整体 git diff、确认无冲突」才收口,所以并行批的提交单位是「批」不是「单任务」——批内任务即便标了独立提交,也是批末验证无冲突后统一提交。
+- **怎么写**:按 plan「提交规范」节(从 `git-standards.md` 结晶的提交消息格式 + 提交前检查点)写 message、过检查点。规范已在 plan 上下文里,不必现场重读 `git-standards.md`。
+- **与 precommit 门禁的关系**:门禁仍会拦,但规范已结晶——自查按 plan 已列的检查点过即可,然后 `CGRAPHX_PRECOMMIT_REVIEWED=1 git commit` 重试。门禁退化为兜底,不再是每次提交的学习成本。
+- **没标「独立提交」的任务**:不擅自提交,改动累积,收尾时连同未提交部分一起交用户决定。
+- **push 永远归用户**:即使任务已提交,是否 push、何时 push 由用户定。
 
-- reviewer 或测试报告已经把问题定位到具体文件 / 行 / 小范围。
-- 修复不改变业务规则、公共契约、schema、权限、安全逻辑或任务范围。
-- 预计改动不超过 1-2 个文件,且不需要重新理解大段上下文。
-- 修复后能立刻运行相关验证。
+### 主 agent 微修(仅低风险)
 
-不满足以上条件时,仍派 implementer/fix 子 agent。
+同时满足才可亲自动手:问题已定位到具体文件/行 + 不碰业务规则/公共契约/schema/权限/安全/范围 + ≤2 文件 + 改完能立刻验证。否则派子 agent。
 
-## 子 agent status 协议
+### spec-reviewer(可选,默认不派)
 
-implementer 子 agent 必须返回以下 status 之一:
+plan 完整性已在 Plan Review 审过。仅这些情况派:任务探索性强(实际行为 plan 无法预知)/ 跨多文件耦合(如改公共类型签名)/ plan-reviewer 标了高风险 / 用户要求 / plan 没过 Plan Review。用 `spec-reviewer-prompt.md` 模板。
 
-| Status | 含义 | 主 agent 处理 |
-|---|---|---|
-| **DONE** | 实现完成,自审通过,无未经批准偏离 | 主 agent sanity check(跑测试 + 看报告)→ 通过则进入下个任务 |
-| **DONE_WITH_CONCERNS** | 实现完成但有疑虑 | 读 concerns:关于 correctness/scope/plan drift → 先解决;关于 observation(如"文件有点大")→ 记录,进入 sanity check |
-| **NEEDS_CONTEXT** | 缺少必要信息 | 补 context,重新派 implementer |
-| **PLAN_CONFLICT** | plan 与代码现实或更优方案冲突,继续做会改变已锁定契约 | 主 agent 暂停该任务,回到用户/plan/spec 确认;不能让 implementer 自行改方案 |
-| **BLOCKED** | 无法完成 | 评估:context 不够 → 补 context 重派;需更强推理 → 换更强 model;任务太大 → 拆分;plan 错了 → 上报用户 |
+### 并行收口
 
-**红线**:**不要**忽略 BLOCKED 直接重试同 model;**不要**忽略 PLAN_CONFLICT 让子 agent 自行换方案;**不要**让卡住的子 agent"再试一次";**不要**绕过子 agent 自己实现。
+同批任一任务返回 BLOCKED / NEEDS_CONTEXT / DONE_WITH_CONCERNS(correctness/scope)→ 暂停同批后续合并,先解决。同批完成后必须看整体 `git diff`:无文件冲突、无重复实现、无命名分叉,才进下一批。实际发生冲突 → 改串行。
 
-## 模板路径
+### 派任模板
 
-主 agent 派子 agent 时,Read 对应模板,把模板内容 + 当前任务 / 审查目标 拼成 prompt:
+Read 模板 + 任务/审查目标拼成 prompt,派 `general-purpose`:
 
-- `./implementer-prompt.md` — 实现单个任务的子 agent prompt(**每任务必派**;并行批次中每个任务各派一个)
-- `./spec-reviewer-prompt.md` — 单任务 spec 审查的子 agent prompt(**执行结束可选派一次,默认不派**,见"何时该派 spec-reviewer")
-- `./quality-reviewer-prompt.md` — 最终整体质量审查的子 agent prompt(**执行结束必派一次**)
-
-派的方法(参考三个探索 skill 的派子 agent 机制):
-```
-Agent({
-  subagent_type: "general-purpose",
-  prompt: <模板全文> + "\n\n" + <任务 / 审查目标的具体描述>
-})
-```
-
-## context 给法:任务全文 + index 摘要
-
-主 agent 不把整套 plan 丢给 implementer,但应该给足局部任务所需的全局约束:
-
-- 必给:当前任务全文、依赖任务完成摘要、相关代码上下文、验证命令。
-- 建议给:`index.md` 中的目标、明确不包含、全局依赖图、当前任务所在批次、必须严格执行的契约、允许局部适配范围、Plan 冲突上报规则、与当前任务相关的风险/待确认项。
-- 不给:无关子计划全文、其他任务的实现细节、会诱导 implementer 扩大范围的背景材料。
-
-如果 implementer 认为 `index.md` 摘要不够,可以返回 `NEEDS_CONTEXT`;主 agent 补充摘要或允许其只读 `index.md`,但仍不读完整 plan 目录。
-
-## 何时派 vs 不派(主 agent 判断)
-
-| 场景 | 不派(走 implementation) | 派(走本 skill) |
-|---|---|---|
-| 任务量 | 1-2 个简单任务 | ≥3 个任务 |
-| 文件域 | 单文件 / 单模块 | 跨 schema/backend/frontend/test 多域 |
-| 上下文压力 | 主 agent 上下文够用 | 实现过程会挤爆主 agent 上下文 |
-| 隔离价值 | 任务太简单,派反而费 token | 任务复杂,隔离后主 agent 能聚焦协调 |
-
-## 跟其他 skill 的关系
-
-| 阶段 | skill |
-|---|---|
-| 澄清需求 | `clarify-requirements` |
-| 写 PRD | `write-prd` |
-| 写 spec | `write-spec` |
-| 写 plan | `write-plan` |
-| **执行 plan(派子 agent)** | **`subagent-implement`(本 skill)** |
-| 执行 plan(主会话顺序) | `implementation` |
-| 收尾 | `finish-feature` / `commit` / PR |
-
-## 处理 plan 与代码现实的冲突
-
-子 agent 实现时发现 plan 与代码现实冲突(如 plan 引用的文件不存在 / 函数签名变了 / 模块结构改了):
-
-- **小偏差**(实现细节、行号、变量名)→ implementer 自行调整,在报告里说明
-- **大偏差**(架构变了、模块不存在、业务规则/数据口径/API/权限/schema/验收要变)→ implementer 返回 `PLAN_CONFLICT`,主 agent 决定:
-  - 修 plan → 重派 implementer
-  - 改任务范围 → 重新拆分
-  - 上报用户
-
-## 红线(不能做)
-
-- ❌ **不在未证明无冲突时并行派多个 implementer**—— 默认串行;只有 plan 明确可并行且通过无冲突检查才同批并行
-- ❌ **不让 implementer 子 agent 自己读完整 plan 目录**(主 agent 把任务全文 + 必要 index 摘要塞 prompt,节省子 agent Read + 防止子 agent 跑偏到其他任务)
-- ❌ **不跳过 quality-reviewer**(整体质量审查是最后一道关卡,跨任务问题只有这里能发现)
-- ❌ **不每任务派 quality reviewer**(质量集中审更经济;每任务派是浪费)
-- ❌ **不忽略 BLOCKED**(子 agent 卡住必有原因,不能强行 retry 同 model)
-- ❌ **不忽略 PLAN_CONFLICT**(plan 冲突必须回到 controller / 用户 / spec-plan 修改,不能让子 agent 临场改方案)
-- ❌ **不让 quality reviewer 在 implementer 自审之前派**(implementer 自审 + sanity check 没过的实现,quality 审没意义)
-- ❌ **不在主分支直接派 implementer**(应有 feature 分支或 worktree 隔离)
-- ❌ **不让主 agent 绕过子 agent 实现实质任务**(低风险微修例外,但不能扩大为主 agent 接手实现)
+- `./implementer-prompt.md` —— 每任务必派
+- `./spec-reviewer-prompt.md` —— 可选
+- `./quality-reviewer-prompt.md` —— 最终必派一次
 
 ## 收尾
 
-所有任务 + quality 审查通过后:
+1. 汇报:完成清单 / 修复历史 / 剩余风险 / plan 忠实度(`PLAN_FOLLOWED` / `PLAN_ADAPTED` / 是否出现并解决过 `PLAN_CONFLICT`)
+2. 知识沉淀提示(确有内容才问):本次交付让某业务实体参与了新业务或出现新实体(实体 = 名词可指代、有属性和生命周期的业务对象)→ 新建/更新实体主条目(`business-entity`),流程条目在 concepts 声明该实体;或踩坑/隐式约束/取舍决策/跨文件关系值得复用。列候选清单问用户;确认 → 走 `knowledge-write` 完整流程。不要自己直接 Write .md
+3. 提示收尾:已按 plan「独立提交」标注提交的任务清单 + 未提交任务的 commit / PR 交用户决定;push 永远归用户。停下等用户
 
-1. 汇报:完成清单 / 修复历史 / 剩余风险
-   - 说明 plan 忠实度:`PLAN_FOLLOWED` / `PLAN_ADAPTED` / 是否出现并解决过 `PLAN_CONFLICT`
-2. 提示用户下一步:
-   - 走 `finish-feature` 收尾?
-   - 直接 commit?
-   - 创建 PR?
+## 红线(绝对不能做)
 
-不要自动 commit / push —— 主 agent 收尾汇报后停下,等用户决定。
+1. ❌ **未证明无冲突不得并行**:并行须同时满足——plan 标"可并行"且无依赖、文件集不重叠(同目录也要改动对象分离)、不共享 schema/公共类型/API/配置/fixture/锁/生成物、验证命令不互染状态、prompt 写明本批清单与"禁碰他任务文件"。默认串行。
+2. ❌ **不让 implementer 读完整 plan** —— 只拿四件套,防跑偏、省 Read。
+3. ❌ **quality-reviewer 最终必派且仅一次** —— 不跳过、不每任务派、不在自审 + sanity check 通过前派。
+4. ❌ **不忽略 BLOCKED 同 model 重试** —— 卡住必有原因。
+5. ❌ **不忽略 PLAN_CONFLICT 让子 agent 临场换方案** —— 契约级冲突必须回到 controller/用户/spec-plan。
+6. ❌ **主 agent 不绕过子 agent 做实质实现** —— 微修可以,接手不行(主 agent 上下文要留给协调)。
+7. ❌ **不在主分支直接派 implementer** —— 先有 feature 分支或 worktree。
+8. ❌ **不超出 plan「独立提交」标注擅自 commit,绝不自动 push** —— plan 标了独立提交的任务可按 plan 结晶的规范提交(用户批准 plan 即批准这些提交);未标注的任务不擅自提交,累积到收尾交用户;push 任何情况下都归用户决定。

package/dist/.claude-template/skills/subagent-implement/implementer-prompt.md

@@ -1,12 +1,12 @@
 # implementer 子 agent prompt 模板
 
-> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接 `\n\n---\n\n当前任务: <任务全文>`、`\n\nindex 摘要: <目标 / 非目标 / 依赖 / 当前批次>` 和 `\n\n上下文: <scene-setting>`。
+> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接四件套:`\n\n---\n\n① 当前任务: <任务全文,含 对应 spec 条款 / 强制引用 / 必须严格执行 / 允许局部适配 / 完成条件>`、`\n\n② 契约节: <index.md 中该任务引用的跨任务共享契约,原文>`、`\n\n③ spec 条款: <任务对应的 spec 条款,原文>`、`\n\n④ 强制引用规范: <任务标注的 docs/guides/ 文件 + 章节标题>` 和 `\n\n上下文: <scene-setting>`。
 
 ## 你的角色
 
 你是 implementer 子 agent,在**隔离上下文**里实现**单个任务**。主 agent 是 controller,只拿到你的最终返回,**看不到你的中间过程**(读文件、试错、grep 等)。
 
-主 agent 把任务全文 + index 摘要 + context 拼进 prompt 给你。**任务全文 + index 摘要是执行契约,不是参考建议**。不要自己去读完整 plan 目录;如果全局目标、非目标或依赖不清楚,先请求主 agent 补充 `index.md` 摘要,必要时只读 `index.md`。
+主 agent 把四件套拼进 prompt 给你(任务全文 + 契约节原文 + spec 条款原文 + 强制引用规范)。**任务全文 + 契约节是执行契约,不是参考建议**;spec 条款原文是你有疑义时的权威依据(读它,不猜任务转述)。不要自己去读完整 plan 目录;如果全局目标、非目标或依赖不清楚,先请求主 agent 补充 `index.md` 摘要,必要时只读 `index.md`。
 
 ## 工作流
 
@@ -23,11 +23,13 @@
 
 ### 2. 实现
 
+- **开工前先读「强制引用」规范**(任务标注的 docs/guides/ 文件 + 章节;schema 任务按 data-standards.md「Schema 变更约定」执行:需求内增量 `<序号>-<动作名>.sql` + 全量 ddl/<表名>.sql 写透到最终态)
 - **按任务全文的"具体要求"做**,不多不少
 - **遵守 index 摘要里的目标 / 非目标 / 依赖 / 当前批次边界**
 - **不得重新设计 plan 已锁定的业务规则、数据口径、接口契约、schema、权限、安全、迁移、验收或核心技术路径**
 - **遵循项目既有模式**(命名、风格、错误处理、测试方式)
 - **小步修改**,每步可验证
+- **不跑 `git add` / `git commit`** —— 改文件即可,提交是 controller 的事(见红线)
 - **新增抽象只在解决真实重复时** —— 不要为"未来扩展"造抽象
 - **不要顺手重构无关代码** —— 看到的坏味道可以提,但不在本任务里改
 
@@ -80,7 +82,10 @@ Plan 忠实度:
 测试 / 验证:
   - <跑了什么,结果如何>
 
-改动的文件:
+规范遵循:
+  - <读了哪些强制引用规范;契约级条目(命名/字段类型/接口形态/schema 增量+全量等)已对照执行>
+
+改动的文件(controller 据此精确 stage 后提交,务必列全列准——漏列 = 提交丢文件,多列 = 提交进无关改动):
   - <path1>:<一句话改动说明>
   - <path2>:<...>
 
@@ -113,7 +118,7 @@ Concerns / 未解决项(如果有):
 - ❌ 不为了通过测试改测试期望值
 - ❌ 不在卡住时默默继续(返回 BLOCKED 或 NEEDS_CONTEXT)
 - ❌ 不 silently 返回 DONE 当有疑虑(必须 DONE_WITH_CONCERNS)
-- ❌ 不 commit 到主分支(应有 feature 分支,主 agent / 用户决定 commit 时机)
+- ❌ **不做任何 `git add` / `git commit`** —— 你只负责改文件,并在报告「改动的文件」里把改动清单列全列准;提交由 controller 在 sanity check 通过后按 plan「独立提交」标注统一处理(提交点必须和验证闸门同侧,你返回时验证还没跑,所以你提交会落坏提交)
 
 ## 何时该 escalate(BLOCKED 或 NEEDS_CONTEXT)
 

package/dist/.claude-template/skills/subagent-implement/quality-reviewer-prompt.md

@@ -37,7 +37,7 @@
 
 - 是否破坏既有 public API / 类型签名?
 - 是否引入新依赖(本不需要)?
-- 是否遵循项目的 lint / 格式化 / 提交规范?
+- 是否遵循项目的 lint / 格式化 / 提交规范与 docs/guides/ 规范(coding-standards / interface-standards 等)?
 - 是否更新了相关文档(README / CHANGELOG / API doc)?
 
 ### 5. 跨任务问题(本审查独有价值)

package/dist/.claude-template/skills/subagent-implement/spec-reviewer-prompt.md

@@ -28,6 +28,7 @@ implementer 可能:
 - 每条要求是否都有对应的实现?
 - 实现是否真的达成了"完成条件"?
 - 边界情况 / 错误处理是否覆盖 spec 提到的?
+- 任务有「强制引用」规范时,规范的契约级条目是否都落实(表命名/字段类型/接口形态等;没落实 = 必须严格执行项漏做)?
 - 报告说"已实现"但代码里找不到对应改动的项?
 
 **方法**:`git diff <base>..<head>` 看全部改动,对照 spec 每条要求找证据。

package/dist/.claude-template/skills/write-api/SKILL.md

@@ -26,25 +26,24 @@ description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境
 - 跑接口测试 → 用 `/run-api-test`
 - 写 PRD / spec / plan → 用 `/write-prd` / `/write-spec` / `/write-plan`
 - 写 HTML 接口文档 → 用 `/write-api-doc`
-- 探索陌生项目 → 用 `/code-impact-init`
-- 查代码调用关系 → 用 `/cgraphx` 或 `codegraph_explore` MCP
+- 探索陌生项目 → 用 `/knowledge-init`
+- 查代码调用关系 → 用 grep / Read
 
 ## 与既有 skill 边界
 
 | skill | 关系 | 说明 |
 |---|---|---|
 | `run-api-test` | 下游 + 独立 | 消费本 skill 产的 .bru + 测试规格跑测试;本 skill 不调它,跑测试由用户显式触发;同一份 .bru 可被多次 run-api-test 复用 |
-| `cgraphx` / `codegraph_explore` | 复用 | S1 定位 handler、S3 提取参数定义时调用 |
 | `db-query` | 复用 | S3 查真实测试数据;DB 副作用核实由 `/run-api-test` R4 做 |
 | `write-api-doc` | 独立并列 | 不互相调用;本 skill 产 .bru + 测试规格,write-api-doc 产 HTML 接口文档 |
 | `implementation` / `subagent-implement` | 上游 | 编码阶段,跑完触发本 skill |
-| `code-impact-docgen` | 独立 | 自测后产设计文档 |
+| `write-design-doc` | 独立 | 发布后按需产设计文档 |
 
 ## 依赖
 
 - feature 编码已完成(`/implementation` 或 `/subagent-implement` 跑完)
 - `docs/features/<feature-id>/<文件前缀>-spec.md` 存在(S1 优先级 2 要用)
-- 项目已接入 cgraphx 索引(S3 定位 handler)—— 未接入则 S3 降级,见 `references/ai-prompts.md` § 降级处理
+- `docs/guides/interface-standards.md` 存在(接口约定;缺失 → 提示 `/init-project-guides` 补齐,见工作流前置)
 - 项目已配置 db-query profile(S3 查真实数据)—— 未配置则 S3 降级
 
 ## feature-id 与文件前缀规则
@@ -67,6 +66,8 @@ description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境
 
 按 S1-S4 顺序执行,每步的规范细节在对应 reference 文件。
 
+**前置(每次执行,先于 S1):读接口规范** `docs/guides/interface-standards.md` —— 约束 S1 接口识别(路径/版本约定,从 spec/代码里认出真正的接口)与 S3 .bru 生成(请求路径、参数形态、header、错误码断言预期)。**缺失 → 中断,提示用户先跑 `/init-project-guides` 补齐**,用户明确表示不需要规范才可继续——不对齐项目约定的测试接口,测了也白测。
+
 ### S1. 确认接口范围
 
 - **前置**:用户调用 `/write-api`,提供需求(feature-id / spec / 需求名)
@@ -136,6 +137,7 @@ S4 完成后 skill 结束。**不跑 bru run、不核实 DB、不出报告**。
 - .bru 的 docs 段含业务说明(关联需求由目录层级表达,docs 段不写关联需求列表)
 - 入参写真实值,变量化只用于环境级 / 前置动态 / 拿不到时占位
 - header 名 / `{{var}}` 变量名大小写与项目既有 .bru 对齐
+- 接口路径 / 参数形态 / 错误码断言符合 `docs/guides/interface-standards.md`(用户豁免规范的除外)
 - 无程序化配置文件(`.services.yml` / `.config.yml`)
 - **工作流停在 S4,没跑 bru run,没核实 DB,没出报告**
 

package/dist/.claude-template/skills/write-api/assets/template-api-spec.md

@@ -72,8 +72,7 @@
   - {{token}}:登录 token,需先跑通用接口 POST /api/v1/auth/login 拿到
   - {{admin_user_id}}:管理员用户 id,若 DB 无现成数据需用户指定
 
-降级说明(若项目未接入 cgraphx / db-query,在此标注):
-- 未接入 cgraphx:S3 用 grep + Read 兜底,参数提取精度可能下降
+降级说明(若项目未配置 db-query,在此标注):
 - 未配置 db-query:S3 留 {{var}} 占位,S6 DB 核实标"无法核实"
 
 ## 5. 接口映射
@@ -109,4 +108,4 @@
 - AI 在 S2 生成时,§1 的"服务"和"通用"列必须填(由 AI 判断),用户可在 S3 前校正
 - §2-§6 由 AI 根据 spec 接口章节 + 代码 + DB 数据填充
 - §4 的"用户手填"项要与 S3 生成的 .bru 里的 `{{var}}` 占位一一对应
-- 降级说明仅在项目未接入 cgraphx / db-query 时填,正常情况留空或删
+- 降级说明仅在项目未配置 db-query 时填,正常情况留空或删

package/dist/.claude-template/skills/write-api/assets/template-request.bru

@@ -70,3 +70,24 @@ tests {
 docs {
     业务说明: <一句话,从 Javadoc 或 spec 提取;提取不到占位"(scan 阶段未提取到 Javadoc,请补充业务说明)"
 }
+
+# 上传文件的请求格式
+meta {
+  name: 生成seqID
+  type: http
+  seq: 5
+}
+
+post {
+  url: {{baseUrl}}/order-service/service/order_svc_buildOrdProdInstAttrId
+  body: multipartForm
+  auth: none
+}
+
+body:json {
+  {}
+}
+
+body:multipart-form {
+  file: @file(/Users/smdnk/Documents/副本虎翼统计数据_202512_202607.xlsx)
+}

package/dist/.claude-template/skills/write-api/references/ai-prompts.md

@@ -86,7 +86,7 @@ AI 判断时**优先参考 `docs/bruno/common/` 既有接口**,避免重复生
 
 - 接口清单(S1)
 - 测试规格文档(S2 产出)
-- 代码上下文:通过 `codegraph_explore` 拿 handler 源码、参数定义、默认值、必填项
+- 代码上下文:通过 grep + Read 拿 handler 源码、参数定义、默认值、必填项
 - DB 数据:通过 `db-query` 查真实可用数据
 
 ### 输出
@@ -127,7 +127,6 @@ AI 调用失败(超时 / 限流):
 
 | 项目状态 | S3 降级行为 |
 |---|---|
-| 未接入 cgraphx 索引 | S3 用 grep + Read 兜底拿 handler 源码,精度可能下降;在测试规格 §4 标注 |
 | 未配置 db-query profile | S3 留 `{{var}}` 占位 + 测试规格 §4 标注"DB 查询不可用";后续 `/run-api-test` 的 R4 也会降级,标"无法核实" |
 
 降级不中断 skill,继续跑能跑的部分。

package/dist/.claude-template/skills/write-api/references/api-spec-format.md

@@ -60,7 +60,6 @@
   - {{admin_user_id}}:管理员用户 id
 
 降级说明(仅在降级时填,正常情况删):
-- 未接入 cgraphx:S3 用 grep + Read 兜底,参数提取精度可能下降
 - 未配置 db-query:S3 留 {{var}} 占位,S6 DB 核实标"无法核实"
 ```