cgraphx 1.1.0 → 1.2.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/write-api-doc/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: write-api-doc
+description: 在 feature 接口开发完毕后(可选环节),从 spec 的接口章节 + 实际代码反向提取,生成静态只读 HTML 接口文档,默认输出到 docs/features/<feature-id>/<文件前缀>-接口文档.html。覆盖本次 feature 新增的接口(严格新增,不含修改),支持 Node/Python/Java/Go/Rust/C#/PHP/Ruby 主流 web 框架。不依赖 cgraphx 索引、不做交互式 Swagger、不重新定义 spec。
+---
+
+# Write API Doc
+
+## 定位
+
+把 feature 实际落地的新增接口,整理成**静态只读 HTML 接口文档**,作为事后技术沉淀归档到 feature 目录。
+
+接口文档的目标是让后续维护者、对接方、测试、新成员快速看懂本 feature 加了哪些接口、怎么调、返回什么、出错怎么办。接口文档**不重新定义 spec 已锁定的契约**,只是事实沉淀。
+
+<HARD-GATE>
+不要重新定义 spec 已锁定的接口契约、参数语义、错误码、权限边界。如果发现 spec 与代码现实不符,标注【待确认】而不是自行解释。
+不要编造未在代码或 spec 中体现的接口、参数、响应字段或错误码。
+范围严格限定"本次 feature 新增的接口",不得自行扩展到修改的老接口或全项目接口。
+不依赖 cgraphx 索引;不调用 codegraph_explore / cgraphx CLI;只用 grep + Read。
+</HARD-GATE>
+
+## Trigger
+
+使用此 skill 当:
+
+- 用户完成 feature 接口开发后,要求"生成接口文档"、"写 API 文档"、"整理一份 HTML 接口文档"
+- 用户说"自测完了,接口文档沉淀一下"、"该写接口文档了"
+- 用户要求把 feature 新增的接口整理成可分享的 HTML 文档
+
+不要使用此 skill 当:
+
+- 写 spec(使用 `write-spec` skill,接口文档不重新定义规格契约)
+- 写设计文档(使用 `code-impact-docgen` skill,设计文档覆盖架构/模块/决策,接口文档只覆盖接口)
+- 探索陌生项目(使用 `code-impact-init` skill)
+- 查询代码调用关系(使用 `cgraphx` skill 或 `codegraph_explore` MCP)
+
+## 与 code-impact-docgen 的边界
+
+| 维度 | write-api-doc | code-impact-docgen |
+|---|---|---|
+| 主题 | 仅接口 | 整个 feature 的设计(架构/模块/决策/限制/扩展) |
+| 来源 | spec 接口章节 + 代码 | knowledge + spec + plan |
+| 产物 | `<前缀>-接口文档.html` | `<前缀>-设计文档.md`(或 .html) |
+| 触发时机 | 接口开发完毕即可 | 自测通过后 |
+| 关系 | 独立产物,与设计文档并列 | 独立产物,与接口文档并列 |
+
+两个 skill 互不替代;同一个 feature 可以同时产出设计文档和接口文档,各自服务不同读者。
+
+## 依赖
+
+- 当前 feature 目录下有 spec(`docs/features/<feature-id>/<文件前缀>-spec.md`)
+- 用户能提供"本次 feature 改动涉及哪些文件或接口前缀"的提示(若不提供,skill 启动时询问)
+
+## feature-id 与文件前缀规则
+
+**feature-id 识别(优先级从高到低)**:
+
+1. 用户调用时显式传 feature-id 或输出路径参数 → 使用用户指定
+2. skill 自动从 cwd 向上探测最近的 `docs/features/<feature-id>/` 目录 → 使用探测结果
+3. 都失败 → skill 报错并要求用户显式传 feature-id 或输出路径
+
+**文件前缀算法**(与 write-prd / write-spec / write-plan / docgen 一致):
+
+feature-id 格式:`YYYY-MM-DD-[业务ID-]<标题>`
+
+- 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
+- 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
+
+业务ID 段允许字母数字 + 连字符;标题段允许中文、英文或混合。**不得**对中文做英文 slug 转换。
+
+文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`;若含敏感字符,要求用户重命名,不自动替换。
+
+**默认输出路径**:`docs/features/<feature-id>/<文件前缀>-接口文档.html`
+
+用户可显式参数覆盖默认路径。
+
+## 工作流
+
+在写任何 api-doc 内容前,**必须**先与用户确认两件事:
+
+1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
+2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
+
+- 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
+- 用户用 `/write-api-doc` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
+- 不得"先写 api-doc 内容,命名最后再说"。命名决策必须在内容产出之前落定,否则会在文件名上反复返工。
+
+### 第一步:确认需求与识别 feature-id
+
+向用户确认(如果未明确指定):
+
+1. **feature-id / 输出路径** — 默认按上方规则识别,用户可覆盖
+2. **本次 feature 改动涉及哪些文件或接口前缀** — 用于界定"新增接口"的范围
+   - 用户可给:文件列表、模块路径、路由前缀(如 `/api/v2/`、`/admin/users`)、handler 函数名等
+   - 用户给的越精确,skill 越快锁定
+3. **可选:补充章节** — 用户可指定排除某些章节或追加自定义章节
+
+### 第二步:读 spec 拿业务口径
+
+Read `docs/features/<feature-id>/<文件前缀>-spec.md`,重点关注:
+
+- "接口、页面与系统边界"章节 — 拿到本 feature 声明的接口清单、业务输入输出、权限边界、错误语义
+- "数据、状态与口径"章节 — 拿到字段语义和状态枚举
+- "权限、安全与审计"章节 — 拿到鉴权方式和数据可见性
+- "异常与边界场景"章节 — 拿到错误码和异常处理
+
+如果 spec 里没有专门的接口章节,如实记录"spec 未明确接口清单,从代码反向提取"。
+
+### 第三步:grep 找路由注册点
+
+根据用户提示的文件/模块范围,在代码里 grep 路由注册点。下面是常见框架的 grep pattern 库;用户提示的框架优先匹配,其他自适应:
+
+**Node / TypeScript / JavaScript**:
+- Express / Fastify / Koa:`app\.(get|post|put|delete|patch)\s*\(`、`router\.(get|post|put|delete|patch)\s*\(`
+- NestJS:`@(Get|Post|Put|Delete|Patch)\s*\(`、`@Controller\s*\(`
+
+**Python**:
+- FastAPI:`@(app|router)\.(get|post|put|delete|patch)\s*\(`、`@APIRouter\.(get|post|put|delete|patch)`
+- Django / DRF:`urlpatterns\s*=`、`path\s*\(`、`re_path\s*\(`、`@action\s*\(`
+- Flask:`@(app|bp)\.(route|get|post|put|delete|patch)\s*\(`
+
+**Java / Kotlin**:
+- Spring:`@(GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|RequestMapping)\s*\(`、`@RestController\s*(`、`@Controller\s*(`
+
+**Go**:
+- Gin:`(r|router|engine)\.(GET|POST|PUT|DELETE|PATCH)\s*\(`、`\.Handle\s*\(`
+- Echo:`(e|echo)\.(GET|POST|PUT|DELETE|PATCH)\s*\(`
+- net/http:`http\.Handle(Func)?\s*\(`、`mux\.Handle(Func)?\s*\(`
+
+**Rust**:
+- Axum:`\.route\s*\(`、`Router::new\(\)`、`#\[(get|post|put|delete|patch)\s*\(`
+
+**C# / .NET**:
+- ASP.NET:`\[Http(Get|Post|Put|Delete|Patch)\]`、`\[Route\(`、`\.Map(Get|Post|Put|Delete|Patch)\s*\(`
+
+**PHP**:
+- Laravel:`Route::(get|post|put|delete|patch)\s*\(`、`Route::(resource|apiResource)\s*\(`
+
+**Ruby**:
+- Rails:`(get|post|put|delete|patch)\s+['"]`、`resources?\s+:`、`match\s+['"]`
+
+**用户提示其他框架**:agent 根据框架文档自适应 grep pattern,在文档里如实标注"非默认覆盖框架,自适应提取"。
+
+### 第四步:筛选"本次 feature 新增"的接口
+
+- 严格只算**新增**(本 feature 新加的路由注册行)
+- 修改老接口(原有路由,handler 内部改了实现) **不在范围**
+- 删除的接口 **不在范围**
+- 判定方式:用户提示 + spec 接口清单对照。spec 声明 + 代码 grep 都命中的优先算新增;只在代码命中但 spec 没声明的,询问用户是否本次新增
+- 找到 0 个新增接口 → 见"失败处理"
+
+### 第五步:Read handler 源码,提取字段
+
+对每个新增接口,Read 对应的 handler 函数,提取:
+
+- **方法**:HTTP 方法(GET/POST/PUT/DELETE/PATCH)
+- **路径**:完整路由(包括 base path,若可推断)
+- **请求参数**:
+  - path 参数(从路由模板提取,如 `/users/:id` → `id`)
+  - query 参数(从 handler 签名 / 框架注入提取)
+  - body 参数(从 DTO / 解构代码 / 类型注解提取)
+  - header 参数(从鉴权注入 / 自定义 header 提取)
+- **响应示例**:从 return 语句 / 序列化代码 / 类型注解 / spec 错误码推断
+- **错误码**:从异常处理 / 抛错代码 / spec 异常章节提取
+- **业务说明**:结合 spec 的接口业务口径 + handler 实现的关键逻辑,写一句简述
+
+提取不到的字段:在文档里标注"待补充"或"代码未体现",**不要编造**。
+
+### 第六步:组装 HTML 文档
+
+按"章节结构"组装 HTML,生成单文件独立 HTML(内联 CSS、不依赖外部资源)。生成前阅读 [template-api-html.md](template-api-html.md) 获取完整 CSS 和结构参考。
+
+### 第七步:保存文件并反馈
+
+写入 `docs/features/<feature-id>/<文件前缀>-接口文档.html`。
+
+反馈:
+1. 告知用户文件保存位置
+2. 列出本次提取的接口总数和清单
+3. 列出"提取失败 / 字段不全"的接口,提示用户补充代码注释或 spec
+4. 不触发分析(本 skill 只读取 spec + 代码,不写入 `docs/knowledge/`)
+
+## 章节结构
+
+```html
+<!DOCTYPE html>
+<html>
+<head>...</head>
+<body>
+  <div class="container">
+    <!-- 文档头 -->
+    <h1>{feature 标题} — 接口文档</h1>
+    <p class="meta">feature-id: {feature-id} | 生成日期: YYYY-MM-DD | 接口总数: N</p>
+
+    <!-- 目录 -->
+    <nav class="toc">
+      <h3>目录</h3>
+      <ul>
+        <li><a href="#概览">概览</a></li>
+        <li><a href="#接口清单">接口清单</a></li>
+        <li><a href="#接口详情">接口详情</a>
+          <ul>
+            <li><a href="#{anchor-1}">{METHOD} {path-1}</a></li>
+            <li><a href="#{anchor-2}">{METHOD} {path-2}</a></li>
+            ...
+          </ul>
+        </li>
+      </ul>
+    </nav>
+
+    <!-- 概览 -->
+    <section id="概览">
+      <h2>概览</h2>
+      <p>本 feature 新增接口的业务背景(从 spec 摘录)。</p>
+      <table>
+        <tr><th>Base URL</th><td>{若可推断,否则"待补充"}</td></tr>
+        <tr><th>鉴权方式</th><td>{若可推断,否则"待补充"}</td></tr>
+        <tr><th>主要内容</th><td>{一句话总结}</td></tr>
+      </table>
+    </section>
+
+    <!-- 接口清单 -->
+    <section id="接口清单">
+      <h2>接口清单</h2>
+      <table class="endpoint-list">
+        <thead><tr><th>方法</th><th>路径</th><th>简述</th></tr></thead>
+        <tbody>
+          <tr><td><span class="api-method get">GET</span></td><td>/api/path</td><td>...</td></tr>
+          ...
+        </tbody>
+      </table>
+    </section>
+
+    <!-- 接口详情 -->
+    <section id="接口详情">
+      <h2>接口详情</h2>
+
+      <section id="{anchor}" class="endpoint">
+        <h3><span class="api-method get">GET</span> <code>/api/path/:id</code></h3>
+        <p class="endpoint-desc">业务说明...</p>
+
+        <h4>请求参数</h4>
+        <table>
+          <thead><tr><th>位置</th><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr></thead>
+          <tbody>
+            <tr><td>path</td><td>id</td><td>string</td><td>是</td><td>资源 ID</td></tr>
+            <tr><td>query</td><td>expand</td><td>boolean</td><td>否</td><td>是否展开关联</td></tr>
+            ...
+          </tbody>
+        </table>
+
+        <h4>响应示例</h4>
+        <pre><code class="json">{
+  "id": "xxx",
+  "name": "xxx"
+}</code></pre>
+
+        <h4>错误码</h4>
+        <table class="error-table">
+          <thead><tr><th>状态码</th><th>含义</th><th>触发场景</th></tr></thead>
+          <tbody>
+            <tr><td>404</td><td>资源不存在</td><td>id 无效</td></tr>
+            ...
+          </tbody>
+        </table>
+      </section>
+
+      ...
+    </section>
+  </div>
+</body>
+</html>
+```
+
+## 模板
+
+阅读 [template-api-html.md](template-api-html.md) 获取完整 CSS 和结构参考。
+
+模板复用 `template-design-html.md` 的 CSS 变量(`:root` 里的颜色 / 字体 / 间距变量)以保持视觉一致;额外增加 `.api-method`、`.endpoint`、`.endpoint-list`、`.error-table` 等接口文档专用样式。
+
+## 内容来源与改写规则
+
+### 事实性内容必须可溯源
+
+- 接口路径、方法、参数、响应字段:必须来自代码(grep + Read)
+- 业务说明、错误语义、权限边界:必须来自 spec 或代码,二者冲突时以 spec 为准并标注【待确认】
+- base URL、鉴权方式:可推断时填,不可推断时填"待补充",不编造
+
+### 改写但忠实
+
+- handler 里的代码注释、参数解构、return 语句 → 改写为表格化的请求参数 / 响应示例
+- spec 里的业务口径 → 改写为接口的"业务说明"短句
+- 不要照贴 handler 源码;不要贴整段 spec 原文
+
+### 不重新定义契约
+
+- 接口文档**不得**改写 spec 已锁定的接口契约、参数语义、错误码
+- 发现 spec 与代码冲突时,以 spec 为准;代码明显违背 spec 时,标注【待确认】并提示用户
+
+## 失败处理
+
+| 场景 | skill 响应 |
+|---|---|
+| 用户未提供文件/接口前缀提示,且无法从上下文推断 | skill 启动时显式询问,不自行猜测 |
+| grep 找到 0 个新增路由注册点 | 报错并提示:"未在用户指定范围找到新增接口。请确认范围,或检查路由注册是否用框架默认 pattern 之外的方式" |
+| 找到的接口 spec 未声明 | 列出"代码命中但 spec 未声明"的接口清单,询问用户是否本次新增,默认不算 |
+| handler 源码字段提取不全 | 在对应字段标"待补充",在反馈里汇总列出 |
+| spec 与代码明显冲突 | 在文档对应字段标【待确认】,在反馈里列出冲突清单 |
+| 框架不在默认覆盖列表 | agent 自适应 grep pattern,在文档"概览"章节标注"非默认覆盖框架,自适应提取" |
+
+## 收尾方式
+
+输出接口文档后,只提示用户:
+1. 文件保存位置
+2. 提取的接口清单
+3. 字段不全或冲突的待补充清单
+
+不要主动调用 docgen 或其他 skill。不写 knowledge 文件。不修改 spec / plan / 代码。