cgraphx 1.1.0 → 1.2.0

package/README.md

@@ -88,7 +88,6 @@ cgraphx node <symbol|file>     # 单符号详情 / 文件内容(带行号)
 cgraphx query <search>         # 按名字搜符号(--kind / --limit / --json)
 cgraphx callers <symbol>       # 谁调用 X
 cgraphx callees <symbol>       # X 调用谁
-cgraphx impact <symbol>        # 改 X 的影响半径(--depth)
 cgraphx affected [files...]    # 改这些文件受影响的测试(--stdin / --filter)
 cgraphx files [path]           # 项目文件结构
 

package/dist/.claude-template/skills/cgraphx/SKILL.md

@@ -39,9 +39,9 @@ cgraphx <subcommand> [args]
 | 看符号定义 | `codegraph_explore` MCP,或 Bash `cgraphx query <name>` 后看返回 | 拿到完整源码 |
 | 谁调用 X | `cgraphx callers <symbol>` | inbound 调用方 |
 | X 调用谁 | `cgraphx callees <symbol>` | outbound 被调用方 |
-| 改 X 的影响面 | `cgraphx impact <symbol>` | impact radius(BFS 影响传播) |
+| 改 X 的影响面 | `codegraph_impact(symbol, depth)` MCP | impact radius(BFS 影响传播,基于索引) |
 | 改文件的受影响测试 | `cgraphx affected [<files>...]` | 找受影响测试文件 |
-| 构建 task 上下文 | `cgraphx context <task>` | 给 AI 一段任务描述,返回相关代码片段 |
+| 构建 task 上下文 | `codegraph_explore` MCP | 给 AI 一段任务描述,返回相关代码片段 + 调用路径 |
 | 看索引状态 | `cgraphx status` | files/nodes/edges 计数、last_indexed_at |
 | 增量同步 | `cgraphx sync` | 文件改了之后 |
 | 全量重建 | `cgraphx index` | 出问题或大改动时 |
@@ -55,7 +55,7 @@ cgraphx <subcommand> [args]
 │   → codegraph_explore MCP(一次拿源码 + 调用路径)
 │
 ├── "改 X 会影响哪里" / "X 的 blast radius" / 重构前评估
-│   → cgraphx impact <symbol>(看影响半径)
+│   → codegraph_impact(symbol) MCP(看影响半径)
 │   → 或 cgraphx affected <file>(看受影响测试)
 │
 ├── "谁调用 X" / "X 的 caller" / 反向追踪

package/dist/.claude-template/skills/cgraphx/agent-prompt.md

@@ -13,10 +13,10 @@
 | 工具 | 用途 |
 |---|---|
 | `codegraph_explore` MCP(首选) | 给一组符号名或自然语言问题,返回相关符号源码 + 调用路径(含 callback / React render / JSX children 等动态派生边) |
+| `codegraph_impact(symbol, depth)` MCP | 改动影响半径(基于索引,返回 Subgraph 含 nodes/edges) |
 | `cgraphx query "<name>"` CLI | 按名字模糊搜符号 |
 | `cgraphx callers <symbol>` CLI | 反向追踪(谁调 X) |
 | `cgraphx callees <symbol>` CLI | 正向追踪(X 调谁) |
-| `cgraphx impact <symbol>` CLI | 改动影响半径 |
 | `cgraphx affected [<files>...]` CLI | 受影响测试文件 |
 | `cgraphx status` CLI | 看索引新鲜度 |
 | `cgraphx files` CLI | 项目文件概览 |

package/dist/.claude-template/skills/cgraphx-guide/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: cgraphx-guide
+description: cgraphx 应用整体使用指南 — 安装、项目接入、日常做需求的工作流(skill 串联)、agent 自动加载的上下文工具。Use when 用户问 cgraphx 怎么用/怎么安装/怎么接入项目/有哪些 skill/日常工作流/onboarding/新手入门/使用流程/安装步骤/skill 怎么配合/cgraphx 能干什么/cgraphx 和别的工具区别。问单个代码查询工具(codegraph_explore/callers/impact 怎么调)走 cgraphx skill,不是本 skill。
+---
+
+# cgraphx 应用使用指南
+
+cgraphx 是本地优先的代码智能工具,把**代码图谱 + markdown 知识库 + 数据库查询 + 开发时间线**打包给 AI agent 用。本 skill 是**整体使用导航**——用户问"怎么用 / 怎么装 / 日常工作流 / 有哪些 skill"时调这里。
+
+视觉版介绍页(给人类用户看):`how-to-use.html`(本 skill 目录内,随 skill 分发,`cgraphx install` 时部署到项目 `.claude/skills/cgraphx-guide/`)。
+
+## 何时用 / 不用本 skill
+
+**用本 skill**:
+- 用户问 cgraphx 怎么安装 / 怎么接入项目
+- 用户问日常怎么用 / 有哪些 skill / 工作流
+- 用户是新手要 onboarding
+- 用户问 cgraphx 整体能干什么、和别的工具区别
+
+**不要用本 skill**(走对应专责 skill):
+- 单个代码查询(`codegraph_explore` / `callers` / `impact` 怎么调)→ `cgraphx` skill
+- 查业务知识(`docs/knowledge/`)→ `code-impact-api` skill
+- 查数据库 → `db-query` skill
+- 写 PRD / spec / plan → 各自 skill
+- 探索陌生项目建知识库 → `code-impact-init` skill
+
+本 skill 只做整体导航,不重复各 skill 的内部规范。
+
+## 整体使用流程
+
+| 阶段 | 命令 / skill |
+|---|---|
+| **机器级 · 每机器一次** | `npm install -g cgraphx` |
+| **项目级 · 每项目一次** | `cgraphx init`(建代码图谱)、`cgraphx install`(写 MCP 配置 + 部署 skills 模板到项目 `.claude/`)、`/code-impact-init`(接手陌生项目时建业务知识库) |
+| **日常做需求 · 必经 2 步** | `/clarify-requirements` 澄清 → `/implementation`(简单)或 `/subagent-implement`(复杂)实现 |
+| **日常做需求 · 复杂按需** | `/write-prd`、`/write-spec`、`/write-plan`、`/code-impact-markdown`(沉淀到 `docs/knowledge/`) |
+| **工作回顾 · 按需** | `/developer-timeline`(日/周/月报)、`/code-impact-docgen`(合成业务/技术文档) |
+| **卸载 · 可选** | `npm uninstall -g cgraphx` + 删 `.cgraphx/` |
+
+## 各 skill 导航
+
+### 用户主动触发(在 Claude Code 里敲 `/skill-name`)
+
+| skill | 何时建议用户调 |
+|---|---|
+| `/clarify-requirements` | 接到模糊需求,先澄清意图、业务边界、技术边界 |
+| `/write-prd` | 要给业务方 / 领导确认业务文档 |
+| `/write-spec` | 写技术规格(归档业务行为 / 规则 / 接口 / 数据,作为 plan 的稳定输入) |
+| `/write-plan` | 拆执行计划(给 agent 执行) |
+| `/implementation` | 简单任务实现(主会话顺序做) |
+| `/subagent-implement` | 复杂多任务实现(派子 agent,隔离上下文) |
+| `/code-impact-init` | 接手陌生项目,派子 agent 自动探索、建业务知识库 |
+| `/code-impact-markdown` | 把业务决策 / 概念沉淀成 md 到 `docs/knowledge/` |
+| `/code-impact-docgen` | 从知识库合成面向人类阅读的业务 / 技术文档(HTML 或 Markdown) |
+| `/developer-timeline` | 生成日报 / 周报 / 月报 / 阶段总结 / 交付汇报 |
+
+### agent 自动调用(用户不主动敲,agent 用来加载项目上下文)
+
+| skill / 工具 | agent 何时自动调 |
+|---|---|
+| `codegraph_explore` | 任何代码理解 / 修改前——查代码结构、调用链、影响半径 |
+| `code-impact-api` | 任务开始时查 `docs/knowledge/` 业务决策 / 概念 / 历史教训 |
+| `db-query` | 验证数据假设 / 查表结构 / 找测试数据(查 MySQL / PostgreSQL,沉淀 schema 到 `docs/schema-knowledge/`) |
+
+## 安装与接入(三步)
+
+```bash
+npm install -g cgraphx               # 装 CLI(Node ≥ 20 且 < 25)
+cd /your/project && cgraphx init     # 建代码图谱索引、开 watcher
+cgraphx install                      # 写 MCP 配置 + 部署 skills 模板到项目 .claude/(默认 local)
+```
+
+`cgraphx install` 默认 **local**(写项目内 `.claude/` / `.cursor/` 等);想影响所有项目才用 `--location=global`。
+
+接手陌生项目时可选第四步:`/code-impact-init` 派子 agent 自动探索、建业务知识库到 `docs/knowledge/`。
+
+## 背后自动(agent 跑的,用户无感)
+
+- 文件改动 → watcher 自动增量同步代码图谱(无需手动 reindex)
+- agent 经 `codegraph_explore` 自动查代码结构 / 调用链 / 影响半径
+- agent 经 `code-impact-api` 自动查业务知识
+- agent 经 `db-query` 自动查数据库
+- `status` / `sync` / `explore` / `docs` / `db` / `timeline` 等 CLI 子命令由 agent / skill 调用,人类日常不主动跑
+
+## 卸载
+
+```bash
+npm uninstall -g cgraphx             # preuninstall 钩子自动清所有 agent 的 MCP 配置
+# 需要清索引数据时,手动删项目目录下的 .cgraphx/
+```
+
+## 视觉版
+
+给人类用户看介绍页时,指向 `how-to-use.html`(本 skill 目录内,部署后在 `.claude/skills/cgraphx-guide/how-to-use.html`)——分阶段卡片布局,一眼看清完整使用流程。

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

@@ -0,0 +1,403 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>cgraphx 怎么用 — 安装与使用</title>
+<style>
+:root {
+  --color-primary: #2B6CB0;
+  --color-primary-dark: #2C5282;
+  --color-text: #1A202C;
+  --color-text-secondary: #4A5568;
+  --color-text-tertiary: #718096;
+  --color-border: #E2E8F0;
+  --color-bg: #FFFFFF;
+  --color-bg-subtle: #F7FAFC;
+  --color-bg-code: #EDF2F7;
+  --color-bg-accent: #FFFAF0;
+  --color-cgraphx: #2B6CB0;
+  --radius: 6px;
+}
+
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
+  font-size: 16px;
+  line-height: 1.75;
+  color: var(--color-text);
+  background: var(--color-bg);
+  margin: 0;
+  padding: 0;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+.container {
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 0 24px;
+}
+
+/* Header */
+header {
+  padding: 80px 0 50px;
+  border-bottom: 1px solid var(--color-border);
+  margin-bottom: 50px;
+}
+header .eyebrow {
+  font-size: 13px;
+  color: var(--color-text-tertiary);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  margin-bottom: 12px;
+  font-weight: 500;
+}
+header h1 {
+  font-size: 38px;
+  font-weight: 700;
+  margin: 0 0 16px;
+  line-height: 1.2;
+  letter-spacing: -0.01em;
+}
+header .subtitle {
+  font-size: 18px;
+  color: var(--color-text-secondary);
+  margin: 0 0 24px;
+}
+header .meta {
+  font-size: 14px;
+  color: var(--color-text-tertiary);
+  margin: 0;
+}
+
+/* Section */
+section { margin-bottom: 56px; }
+
+h2 {
+  font-size: 26px;
+  font-weight: 600;
+  margin: 0 0 24px;
+  padding-bottom: 10px;
+  border-bottom: 2px solid var(--color-border);
+  letter-spacing: -0.01em;
+}
+
+p { margin: 0 0 16px; }
+p strong, li strong { font-weight: 600; }
+
+/* Inline code */
+code {
+  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  font-size: 0.88em;
+  background: var(--color-bg-code);
+  color: var(--color-primary-dark);
+  padding: 2px 6px;
+  border-radius: 3px;
+}
+
+/* Tags */
+.tag {
+  display: inline-block;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 2px 8px;
+  border-radius: 3px;
+  letter-spacing: 0.02em;
+  white-space: nowrap;
+}
+.tag-cgraphx { background: #EBF8FF; color: #2C5282; }
+
+/* Pipeline (单卡片,沿用左侧 code-workflow 卡片样式) */
+.pipeline {
+  border: 1px solid var(--color-border);
+  border-top: 4px solid var(--color-cgraphx);
+  border-radius: var(--radius);
+  padding: 24px 28px;
+  background: var(--color-bg);
+  margin: 0 0 24px;
+}
+.pipeline h4 {
+  margin: 0 0 20px;
+  font-size: 16px;
+  font-weight: 600;
+}
+.phase {
+  margin-bottom: 18px;
+  padding-bottom: 18px;
+  border-bottom: 1px dashed var(--color-border);
+}
+.phase:last-child {
+  margin-bottom: 0;
+  padding-bottom: 0;
+  border-bottom: none;
+}
+.phase-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--color-text-tertiary);
+  font-weight: 600;
+  margin-bottom: 10px;
+}
+.phase-list {
+  padding-left: 20px;
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.75;
+}
+.phase-list li { margin-bottom: 6px; }
+.phase-list code { font-size: 12.5px; }
+.phase-list em {
+  color: var(--color-text-tertiary);
+  font-size: 13px;
+  font-style: normal;
+}
+
+/* Highlight box */
+.highlight {
+  background: var(--color-bg-subtle);
+  border: 1px solid var(--color-border);
+  border-left: 4px solid var(--color-cgraphx);
+  border-radius: var(--radius);
+  padding: 20px 24px;
+  margin: 0 0 16px;
+}
+.highlight p:last-child { margin-bottom: 0; }
+
+/* Lists */
+ul, ol {
+  padding-left: 24px;
+  margin: 0 0 16px;
+}
+li { margin-bottom: 6px; }
+
+/* Footer */
+footer {
+  margin-top: 80px;
+  padding: 30px 0;
+  border-top: 1px solid var(--color-border);
+  text-align: center;
+  color: var(--color-text-tertiary);
+  font-size: 13px;
+}
+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-map li:last-child { border-bottom: none; padding-bottom: 0; }
+.docs-map .dir {
+  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-map .owner {
+  display: block;
+  margin-top: 6px;
+  font-size: 13px;
+  color: var(--color-text-tertiary);
+  line-height: 1.6;
+}
+.docs-map .owner code { font-size: 12.5px; }
+.docs-map .owner .label {
+  font-weight: 600;
+  color: var(--color-text-secondary);
+  margin-right: 4px;
+}
+.docs-map .owner .manual {
+  color: var(--color-text-tertiary);
+  font-style: italic;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  .container { padding: 0 18px; }
+  header { padding: 50px 0 30px; margin-bottom: 30px; }
+  header h1 { font-size: 28px; }
+  header .subtitle { font-size: 16px; }
+  h2 { font-size: 22px; }
+  body { font-size: 15px; }
+  .pipeline { padding: 20px; }
+}
+</style>
+</head>
+<body>
+
+<div class="container">
+
+<header>
+  <div class="eyebrow">cgraphx 安装与使用</div>
+  <h1>cgraphx 怎么用</h1>
+  <p class="subtitle">本地优先的代码智能 · 给 AI agent 用的代码图谱</p>
+  <p class="meta">最后更新:2026-07-02</p>
+</header>
+
+<section>
+  <h2>安装流程</h2>
+
+  <div class="pipeline">
+    <h4><span class="tag tag-cgraphx">cgraphx</span> &nbsp;一次接入 · 三层就绪</h4>
+
+    <div class="phase">
+      <div class="phase-label">机器级 · 每机器一次</div>
+      <ul class="phase-list">
+        <li><code>npm install -g cgraphx</code> 装 CLI<em>（Node ≥ 20 且 &lt; 25）</em></li>
+      </ul>
+    </div>
+
+    <div class="phase">
+      <div class="phase-label">项目级 · 每项目一次</div>
+      <ul class="phase-list">
+        <li><code>cd /your/project &amp;&amp; cgraphx init</code> 建 <code>.cgraphx/</code> 代码图谱索引、开 watcher 自动增量同步</li>
+        <li><code>cgraphx install</code> 写 MCP 配置 + 部署 skills 模板到项目 <code>.claude/</code><em>（默认 local;想影响所有项目才用 <code>--location=global</code>）</em></li>
+        <li><code>/code-impact-init</code> 接手陌生项目时按需跑<em>（派子 agent 自动探索、建 <code>docs/knowledge/</code> 业务知识库）</em></li>
+      </ul>
+    </div>
+
+    <div class="phase">
+      <div class="phase-label">卸载 · 可选</div>
+      <ul class="phase-list">
+        <li><code>npm uninstall -g cgraphx</code><em>（preuninstall 钩子自动清所有 agent 的 MCP 配置）</em></li>
+        <li>删项目目录下 <code>.cgraphx/</code> 清索引数据</li>
+      </ul>
+    </div>
+  </div>
+
+  <div class="highlight">
+    <p><strong>装一次,自动维护</strong>——全局装 CLI,每个项目跑 <code>init</code> + <code>install</code> 就接入完成;之后 watcher 自动同步代码图谱、MCP 配置自动注入,你不需要主动跑命令。卸载也是一条命令。</p>
+  </div>
+</section>
+
+<section>
+  <h2>使用流程</h2>
+
+  <div class="pipeline">
+    <h4><span class="tag tag-cgraphx">cgraphx</span> &nbsp;极简内核 · 按需扩展</h4>
+
+    <div class="phase">
+      <div class="phase-label">日常做需求 · 必经 2 步</div>
+      <ul class="phase-list">
+        <li><code>/clarify-requirements</code> 澄清意图、业务边界、技术边界</li>
+        <li><code>/implementation</code> 实现<em>（简单任务,主会话顺序做）</em>或 <code>/subagent-implement</code><em>（复杂多任务,派子 agent）</em></li>
+      </ul>
+    </div>
+
+    <div class="phase">
+      <div class="phase-label">日常做需求 · 复杂按需</div>
+      <ul class="phase-list">
+        <li><code>/write-prd</code> 写业务文档<em>（给业务方 / 领导确认）</em></li>
+        <li><code>/write-spec</code> 写技术规格<em>（归档业务行为 / 规则 / 接口 / 数据,作为 plan 的稳定输入）</em></li>
+        <li><code>/write-plan</code> 拆执行计划<em>（给 agent 执行）</em></li>
+        <li><code>/code-impact-markdown</code> 沉淀业务决策 / 概念到 <code>docs/knowledge/</code></li>
+      </ul>
+    </div>
+
+    <div class="phase">
+      <div class="phase-label">工作回顾 · 按需</div>
+      <ul class="phase-list">
+        <li><code>/developer-timeline</code> 生成日报 / 周报 / 月报 / 阶段总结 / 交付汇报</li>
+        <li>直接问「我上周做了什么」「这个月干了啥」「X 是哪天做的」也能答</li>
+        <li><code>/code-impact-docgen</code> 从知识库合成面向人类阅读的业务 / 技术文档<em>（HTML 或 Markdown）</em></li>
+      </ul>
+    </div>
+
+    <div class="phase">
+      <div class="phase-label">背后 · agent 自动</div>
+      <ul class="phase-list">
+        <li>agent 经 <code>codegraph_explore</code> 自动查代码结构、调用链、影响半径<em>（你不用主动跑）</em></li>
+        <li>文件改动 → watcher 自动增量同步,无需手动 reindex</li>
+        <li><code>status</code> / <code>sync</code> / <code>explore</code> / <code>docs</code> / <code>db</code> / <code>timeline</code> 等子命令由 agent / skill 调用,人类日常不主动跑</li>
+      </ul>
+    </div>
+
+    <div class="phase">
+      <div class="phase-label">项目上下文 · agent 自动</div>
+      <ul class="phase-list">
+        <li><code>code-impact-api</code> agent 自动查 <code>docs/knowledge/</code> 业务决策 / 概念 / 历史教训</li>
+        <li><code>db-query</code> agent 自动查 MySQL / PostgreSQL 验证数据假设,沉淀 schema 知识到 <code>docs/schema-knowledge/</code></li>
+      </ul>
+    </div>
+  </div>
+
+  <div class="highlight">
+    <p><strong>日常默认 2 步</strong>——澄清 + 实现;复杂需求按需补 <code>prd</code> / <code>spec</code> / <code>plan</code> / 沉淀。<strong>cgraphx 在背后自动同步代码图谱、agent 自动查</strong>,你不需要主动跑命令。</p>
+  </div>
+</section>
+
+<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>
+</section>
+
+<footer>
+  <p>cgraphx 使用说明 · 2026-07-02</p>
+</footer>
+
+</div>
+
+</body>
+</html>

package/dist/.claude-template/skills/clarify-requirements/SKILL.md

@@ -33,11 +33,11 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 你必须为下列每一项创建一个任务,并按顺序完成:
 1. **探索上下文**
    - 按需读项目结构、文档、代码、测试、schema、路由、模型、API、UI、既有约定
-   - 项目里有这些工具可作为上下文补充:
-     - `code-impact-api skill` — 查 docs/knowledge/ 历史决策、业务概念、项目经验
-     - `db-query skill` — 查数据库、查 DDL
-     - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径(MCP 优先;MCP 不可用时走 Bash CLI)
-     - `developer-timeline skill` — 查用户最近做了什么(回顾开发历史)
+   - 项目里有这些工具可作为上下文补充, 对于符合的场景,必须使用:
+     - `code-impact-api skill` — 查 历史决策、业务概念、项目经验时必须使用
+     - `db-query skill` — 查数据库、查 DDL 时必须使用
+     - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径时必须使用
+     - `developer-timeline skill` — 查用户最近做了什么(回顾开发历史) 时必须使用
    - 调用前明确告诉用户"我需要先查 X 来理解背景"。收集完简要陈述发现,不要大段贴原文
    - 在假设任务形态之前,先识别当前行为和既有约束
 
@@ -360,6 +360,15 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 
 边界情况(任务量 2-3 个、文件 3-5 个)由主 agent 根据 plan 是否存在 + 任务独立性判断。
 
+**事后沉淀环节(可选,不在实现前)**:无论选 `/implementation` 还是 `/subagent-implement`,实现推进过程中可按需触发两个事后文档 skill:
+
+| skill | 触发时机 | 产物 | 主题 |
+|---|---|---|---|
+| `/write-api-doc` | 接口开发完毕(不必等所有自测) | `<文件前缀>-接口文档.html` | 仅本次 feature 新增的接口;从 spec 接口章节 + 代码反向提取 |
+| `/code-impact-docgen` | 自测通过后 | `<文件前缀>-设计文档.md` | 整个 feature 的设计(架构/模块/决策);从 knowledge + spec + plan 合成 |
+
+两者互不替代:同一 feature 可以同时产出接口文档和设计文档,各自服务不同读者。默认输出路径都在 `docs/features/<feature-id>/`。
+
 ## 最终输出
 
 结束时,只输出一份澄清总结:
@@ -402,10 +411,12 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 
 **用户控制的下一步**
 接下来你可以选择:
-- 写 PRD(`/write-prd`)
-- 起草 spec(`/write-spec`)
-- 创建实现计划(`/write-plan`)
+- 写 PRD(`/write-prd`)—— 产物 `<文件前缀>-需求文档.md`
+- 起草 spec(`/write-spec`)—— 产物 `<文件前缀>-spec.md`
+- 创建实现计划(`/write-plan`)—— 产物 `plan/<文件前缀>-index.md` 等
 - 开始实现 —— 根据任务规模选(`/implementation` 简单 / `/subagent-implement` 复杂,详见「下游实现 skill 选择」)
+- 接口开发完毕后 —— 用 `/write-api-doc` 生成 `<文件前缀>-接口文档.html`(只覆盖新增接口,可选)
+- 自测通过后 —— 用 `/code-impact-docgen` 生成 `<文件前缀>-设计文档.md` 沉淀到 feature 目录(可选)
 ```
 
 **输出这份总结后,不再继续。** 不自动调用任何下游 skill,不写代码,不写文档。