cgraphx 1.1.0 → 1.3.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/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/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,424 @@
+<!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-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-tree b {
+  font-weight: 600;
+  color: var(--color-primary-dark);
+}
+.docs-tree .skill {
+  color: var(--color-primary);
+  font-weight: 600;
+}
+.docs-tree .ann {
+  color: var(--color-text-tertiary);
+}
+.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: 0 0 20px;
+}
+.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) {
+  .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-13</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>/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">
+        <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>
+
+  <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-13</p>
+</footer>
+
+</div>
+
+</body>
+</html>