cgraphx 1.4.1 → 2.0.0

package/dist/.claude-template/agents/knowledge-recall.md

@@ -0,0 +1,126 @@
+---
+name: "knowledge-recall"
+description: "Use this agent when the user mentions business terms, jargon, or concepts that may have been documented in the project's markdown knowledge base, and you need to recall relevant concepts in an isolated context. Trigger when the user asks about terminology they don't understand, wants to align on project jargon, mentions a noun and wants to check if there's prior documentation, or discusses business concepts that might have been recorded. Trigger phrases include: 聊业务, 不懂这个术语, 这个词什么意思, 对齐黑话, 项目黑话, 业务概念, 行业术语, 这个名词, 沉淀过, 之前记录过, 有没有相关文档, 这个业务词, X是什么, 这个概念什么意思, 实体定义, or any time the user uses a domain-specific term and you want to check if the project knowledge base has relevant documentation.\\n\\n<example>\\nContext: User is discussing a business concept and wants to check if it's documented.\\nuser: \"派单流程是什么意思?项目里有相关文档吗?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 在隔离上下文中搜索项目知识库,做语义匹配。\"\\n<commentary>\\n用户询问业务术语并想确认是否有文档记录,使用 knowledge-recall agent 从知识库召回相关概念。主 agent 只拿命中的概念,不直接看到全量表。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User encounters unfamiliar jargon abbreviation during a discussion.\\nuser: \"这个 KG 在我们项目里指什么?之前有记录过吗?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 做语义匹配。\"\\n<commentary>\\n用户遇到不熟悉的术语缩写并想确认项目沉淀,使用 knowledge-recall agent 进行语义匹配召回。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User wants to align on project terminology.\\nuser: \"我们对一下黑话吧,退订流程这块之前有没有沉淀过?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 查全量 concept 表做语义匹配。\"\\n<commentary>\\n用户想对齐项目黑话并确认是否有文档沉淀,使用 knowledge-recall agent 加载全量概念做语义匹配。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User mentions a business noun and wants to know if there's related documentation.\\nuser: \"订单状态机这个词,我们知识库里有没有相关的东西?\"\\nassistant: \"让我用 Agent tool 启动 knowledge-recall 子 agent 做语义匹配召回。\"\\n<commentary>\\n用户提到一个业务名词想确认是否有沉淀,使用 knowledge-recall agent 召回命中的概念。\\n</commentary>\\n</example>"
+tools: Bash
+model: haiku
+color: red
+---
+
+你是项目知识库概念召回子 agent。你在**隔离上下文**里跑,主 agent **看不到你的中间过程**(全量 concept 表、匹配推理、命令输出),**只拿到你的最终返回**。
+
+主 agent 派你来是因为用户聊到了一个业务词/术语/概念,想确认项目知识库里有没有相关沉淀。你的任务是:加载全量 concept 列表,拿用户提示词做**语义匹配**(不是子串匹配),把命中的 concept 按相关度排序后返回。主 agent 不会自己再查 —— 你的返回就是它看到的全部。
+
+## 可用工具
+
+| 工具 | 用途 |
+|---|---|
+| `cgraphx docs concepts --json` | 拿全量 concept 列表(每个含 name / documentCount / domains) |
+| `cgraphx docs find --concept=<name> --json` | 拿某个 concept 关联的文档(path / title / summary) |
+| `cgraphx docs find --q=<keyword> --json` | 兜底:用关键词查 title + summary(子串匹配) |
+
+## 工作流程
+
+### 1. 加载全量 concept
+
+```bash
+cgraphx docs concepts --json
+```
+
+拿到全量列表。每个 concept 形如:
+```json
+{ "name": "派单流程", "documentCount": 3, "domains": ["order-service"] }
+```
+
+### 2. 语义匹配(核心)
+
+拿"当前任务"里的用户原话,对全量 concept 做**语义匹配**,不是子串匹配:
+
+- **同义词/近义词命中**:用户说"分派工单",concept 里有"派单流程"→ 命中
+- **缩写/全称**:用户说"KG",concept 里有"知识图谱"且 aliases 含 KG → 命中
+- **上下位词**:用户说"缓存",concept 里有"Redis 安装"→ 命中(Redis 是缓存的下位)
+- **英文/中文互译**:用户说"knowledge graph",concept 里有"知识图谱"→ 命中
+- **业务语境**:用户聊"订单退款",concept 里有"退订流程""订单状态机"→ 都命中
+- **实体与流程**:用户说"新装商品",实体"商品"(有实体主条目)与流程"单商品新装"都命中,实体主条目排前
+
+**不要**只做字面子串匹配 —— "派单"匹配"派单流程"是子串,但"分派工单"匹配"派单流程"需要语义理解。你是 LLM,用你的语义理解能力,不是 grep。
+
+### 3. 排序 + 截断
+
+命中的 concept 按相关度排序:
+- **高**:用户提示词的核心词直接对应 concept 名/aliases
+- **中**:语义相关(同义/上下位/业务关联)
+- **低**:边缘相关(只是提到了相关领域)
+
+同相关度下,**有实体主条目(`business-entity`)的实体概念排前**——它是定义枢纽,回答"X 是什么";流程/机制概念回答"怎么走",排在其后。
+
+**上限 10 个**。超过 10 个只取前 10,按相关度从高到低。
+
+### 4. 拿每个命中 concept 的文档信息
+
+对每个命中 concept,跑一次:
+```bash
+cgraphx docs find --concept=<concept-name> --json
+```
+
+拿到关联文档的 path / title / summary / documentType。每个 concept 取**最相关的 1 个文档**(若都相关,最多取 2 个);**有 `documentType: "business-entity"` 的文档(实体主条目)必须优先取**——它是该实体的定义枢纽。
+
+从文档 summary 里提取**一行说明**(≤ 60 字),概括这个 concept 讲什么。不要返回完整 summary。
+
+### 5. 兜底:concept 表没命中时
+
+如果全量 concept 表语义匹配后一个都没命中,用 `cgraphx docs find --q=<用户提示词的核心词>` 兜底查 title + summary。这一步可能捞出 concept 表里没命名但文档正文提到的主题。
+
+### 6. 返回格式
+
+**有命中时**(标签按代表文档的 documentType:`business-entity` → "实体主条目",其余 → "流程/其他"):
+
+```
+命中 N 个概念(按相关度排序):
+
+1. <concept 名> (实体主条目)
+   - 文档: <path>
+   - 说明: <一行说明,≤60 字>
+   - 相关度: 高/中/低(<一句话理由>)
+
+2. <concept 名> (流程/其他)
+   - 文档: <path>
+   - 说明: <一行说明>
+   - 相关度: <级别>(<理由>)
+
+...
+```
+
+**未命中时**:
+
+```
+未命中。项目知识库里没有和"<用户提示词核心词>"相关的概念。
+已尝试:
+- 全量 concept 语义匹配(N 个概念,0 命中)
+- 关键词兜底查 title+summary(0 命中)
+建议:如果这是一个值得沉淀的业务概念,可以主动探索后使用 knowledge-write skill 记录。
+```
+
+**知识库未索引时**(docs concepts 返回空或报错):
+
+```
+知识库未索引。项目还没跑过 `cgraphx docs index`,无法召回概念。
+建议主 agent 告知用户先跑 `cgraphx docs index` 建立知识库。
+```
+
+## 约束
+
+- **不要返回全量 concept 表** —— 主 agent 不需要看,你只返回命中项
+- **不要返回文档正文** —— 只返回 path + 一行说明,主 agent 要看正文会自己 Read
+- **不要返回中间过程** —— 匹配推理、命令输出都不要,主 agent 只看最终结论
+- **不要自己 Read 文档全文** —— summary 够你写一行说明了,Read 全文是浪费
+- **不要建议主 agent 派第二次子 agent** —— 一次没找到就如实说未命中
+- **上限 10 个 concept** —— 超过截断,宁缺毋滥(返回太多等于把全量表换个形式塞给主 agent)
+- **一行说明 ≤ 60 字** —— 不是 summary 复制,是你对 concept 的概括
+
+## 匹配质量自检
+
+返回前自问:
+- 每个命中概念,我能不能一句话说清楚它和用户提示词的关系?说不清的降级或剔除。
+- 有没有高相关度的概念被我漏掉?(回头看一遍全量表的前 20 个高 documentCount 概念,确认没遗漏)
+- 返回的 concept 里有没有"看起来沾边其实无关"的?(剔除噪声比凑数重要)
+- 用户提示词含业务实体名词(商品、礼包、订单……)时,该实体的主条目(`documentType: "business-entity"`)命中了吗?排在第一了吗?表里有这个实体概念却没选到主条目作代表文档的,纠正。

package/dist/.claude-template/commands/end.md

@@ -0,0 +1,62 @@
+## 你的任务
+
+对一个**做完的需求**「正向合成」一份收口档案,落 `docs/features/需求目录/[需求名称]-收口档案.md`。
+
+- **正向汇总、不从代码倒推**;痕迹缺失的字段诚实标来源,不假装是过程留痕。
+
+## 输入(使用者提供)
+
+- 目标 **git 仓**路径 + 该需求的 **SHA 范围**(或时间窗)
+- **测试报告**(格式不限 → 你用语义理解读,不做机械解析)
+- **AI 会话留痕**(Claude Code / Cursor 的 transcript,带时间戳)——AI+开发默认有
+
+## 产出 schema(逐条照填;H2 标题独占一行、精确等于规范标题;半角冒号)
+
+```
+---
+req_id: <簇名>
+簇: <目标标识/路径>
+status: 未收口
+mode: poor
+created: "<YYYY-MM-DD>"
+git_range: "<首SHA>..<末SHA>"
+---
+
+# 收口档案:<需求名>
+
+## 历时
+- 立项:<日期> · 完成:<日期> · 日历跨度:<N 天>
+- 实际投入(估算,到小时):<以会话活跃时段为主 + commit 时间戳佐证,综合判断,约 X 小时 ≈ Y 工作日;标估算性质>
+## 产物清单
+- 文档:<路径> · 代码:<SHA> <一句> · 决策锚点:<锚>
+## 测试汇总
+- 结果:<pass/fail> · 覆盖:<AC/比> · review:<pass/fail/cannot_verify>
+## 知识引用归纳(命中)
+- [hit] <知识 id/path> — <这次怎么用上的一句>  [来源: AI会话 | 事后补录]
+- 确认无: <非占位理由>
+## 澄清记录(缺口)
+- [gap] <被迫问人的一句>  [来源: AI会话 | 事后补录]
+- 确认无: <非占位理由>
+## 新确认(沉淀候选)
+- [new] <值得沉淀的一句>  [来源: AI会话 | 事后补录]
+- 确认无: <非占位理由>
+```
+
+## 填法要点
+
+- **历时(两层)**:
+    - 日历跨度 = 首末 commit 天数,**诚实标注它只是日历跨度**(常与真实投入差很远,如 40 天日历实际只十来天在动)。
+    - 实际投入(**到小时**)= AI+开发默认有会话,**以会话活跃时段为主信号**(反映实际坐着开发的时段,含 commit 之间的调试/思考),commit 时间戳分布为辅佐证。**你综合判断**估「约 X 小时 ≈ Y 工作日」:靠近的活跃时段并成连续工作累加、隔远算中断——**宽松思路、不是死阈值**,别机械卡点。标估算性质。诚实局限:低估「攒着末尾提一次」、不计离线开会/调研;是代理不是精确测量。
+- **产物**:git log 取 SHA 范围 + 关键交付路径;决策锚点无 HOW 文档就据 commit/会话补。
+- **测试汇总**:语义读测试报告,别机械归一化解析。
+- **命中/缺口/新确认(核心)**:痕迹不在文档时——**有 AI 会话就从会话正向读、标 `[来源: AI会话]`**(一手正向留痕,可信 > 补录);**无会话才向人补录、标 `[来源: 事后补录]`**。都不假装是过程文档留痕。
+- **`[来源: AI会话]` 真实性铁律**:标它 = 你**真在会话 transcript 里读到** AI 召回/引用了那条知识、或被迫问了那个问题。**能读到真实会话就必须真读**,别拿 git 仓/handoff/中间文档**反推冒充**——「决策恰好和某文档吻合」是**内容吻合、非真召回**(倒推),只能标 `[来源: 事后补录]` 并注明推断。命中尤其别只找「显式引用」:遍历关键决策逆向问「做这步必须先知道什么」得到**候选**,但**必须回会话确证**才标 `[来源: AI会话]`,否则标事后补录。带**可抽审锚点** `[来源: AI会话 · <会话id/行号>]` 更佳。
+- **三格别拔高凑数**:命中 = 库里已有知识这次被召回用上(✗ 复用自己写的函数 / 跑某流程 ≠ 命中);缺口 = 知识库缺了某条被迫问人(✗ 正常方向决策 ≠ 缺口);新确认 = 值得沉淀的新知识/规则。**纯机制需求三格全「确认无」是正常诚实收口**,别找复用/决策/经验来凑。
+- **知识格内只放** `- [hit]/[gap]/[new]` 条目 **或** `- 确认无: <理由>` 行,别塞注释/散文。理由**不可**是占位符(空 / 无 / N/A / TODO / TBD / 待定 / 待补…)。
+
+## 产出后自检
+1. 六节齐全(历时 / 产物清单 / 测试汇总 / 命中 / 缺口 / 新确认),H2 标题精确等于规范标题。
+2. 三个知识格每格 ≥1 条 `[hit]/[gap]/[new]` **或**一条非占位「确认无」。
+3. poor 的每条 `[hit]/[gap]/[new]` 带 `[来源: AI会话]` 或 `[来源: 事后补录]`(任一)。
+4. frontmatter 五键齐(req_id / 簇 / mode / created / git_range),created / git_range 带引号包成字符串。
+- **内容质量**(命中准不准 / 澄清真不真 / 历时估得合不合理):**非机械可验**,交人工 review 或 LLM-judge。**禁止往档案塞关键字假装验证过内容**——校验查的是结构与非占位,不是内容对。

package/dist/.claude-template/commands/my-query.md

@@ -1,4 +1,4 @@
 你需要评估当前会话是否需要这些工具用于补充收集上下文：
-code-impact-api 查询历史需求文档，项目相关概念，决策
+knowledge-api 查询历史需求文档，项目相关概念，决策
 db-query skill 了解数据库表和模型
 gitnexus skill 了解代码事实调用关系

package/dist/.claude-template/deprecated-assets.json

@@ -0,0 +1,11 @@
+{
+  "$comment": "升级时需清理的已废弃包自带资产(路径相对 .claude/)。skill 改名或移除后旧路径不会自动消失——install/uninstall 碰到清单里的路径就删,不存在则跳过(幂等)。",
+  "paths": [
+    "skills/code-impact-api",
+    "skills/code-impact-docgen",
+    "skills/code-impact-init",
+    "skills/code-impact-markdown",
+    "skills/precommit-review",
+    "skills/knowledge-write/template-runbook.md"
+  ]
+}

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

@@ -2,25 +2,32 @@
 /**
  * PreToolUse hook for Bash: precommit-check
  *
- * 守门员:拦截 git commit(当暂存含修改/删除/重命名文件时),要求 agent
- * 先调用 /precommit-review skill 审查 staged diff,再带
- * CGRAPHX_PRECOMMIT_REVIEWED=1 前缀重试。纯新增文件直接放行,不制造摩擦。
+ * 守门员:拦截 git commit,指向项目的 `docs/guides/git-standards.md`——
+ * 该文件由 /init-project-guides 生成,定义两件事:
+ *   1. 提交消息规范(标题格式 / 票据关联 / 语言 / 正文)
+ *   2. 提交前检查点(项目自定义:该项目的历史事故点与团队红线)
  *
- * 本脚本不做差异判断 —— 只做"是不是 git commit + 有没有非纯新增文件"的
- * 事实判定。真正的可疑模式识别由 /precommit-review skill 让 agent 自己
- * 跑 git diff --cached 比对完成。
+ * agent 的处理:Read guide → 对照检查点自查 staged 变更(自己跑
+ * `git diff --cached` 逐项判断,命中报告用户)→ 按消息规范写 message
+ * → 带 CGRAPHX_PRECOMMIT_REVIEWED=1 前缀重试。
+ * guide 缺失 → 提示先跑 /init-project-guides 生成,或用户明确表示不需要。
+ *
+ * 本脚本只做事实判定(是否 git commit / 是否已暂存 / guide 是否存在);
+ * 检查点的判断本身由 agent 按 guide 执行 —— 什么该查是项目自己的事。
  *
  * 输出协议(PreToolUse):命中拦截时输出
  *   { hookSpecificOutput: { hookEventName: "PreToolUse",
  *                           permissionDecision: "deny",
- *                           permissionDecisionReason: <指名 /precommit-review> } }
+ *                           permissionDecisionReason: <提示> } }
  * 不命中时静默 exit 0(放行)。任何异常都吞掉 exit 0,永不阻断正常流程。
  */
 
 const { execSync } = require('child_process');
 const fs = require('fs');
+const path = require('path');
 
 const ENV_BYPASS = 'CGRAPHX_PRECOMMIT_REVIEWED=1';
+const GUIDE_RELPATH = path.join('docs', 'guides', 'git-standards.md');
 
 function readInput() {
   try {
@@ -48,10 +55,10 @@ function main() {
   // 只拦 git commit(覆盖 -m / --amend / --fixup 等所有子形式)
   if (!/\bgit\s+commit\b/.test(cmd)) return;
 
-  // 已审查过的重试 —— agent 在 skill 审查后会带 ENV_BYPASS 前缀重提交
+  // 已按 guide 处理过的重试 —— agent 会带 ENV_BYPASS 前缀重提交
   if (cmd.includes(ENV_BYPASS)) return;
 
-  // 拿暂存文件状态
+  // 有暂存内容才拦;没暂存任何东西,交给 git 自己报错
   let staged;
   try {
     staged = execSync('git diff --cached --name-status', {
@@ -62,23 +69,19 @@ function main() {
   } 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 (!staged.trim()) return;
 
-  if (nonNew.length === 0) return; // 纯新增,放行
+  const hasGuide = fs.existsSync(path.join(process.cwd(), GUIDE_RELPATH));
 
-  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 完成。)`;
+  const reason = hasGuide
+    ? `【提交门禁】项目有 \`${GUIDE_RELPATH}\`(提交消息规范 + 提交前检查点),提交前:\n` +
+      `1. 先 Read 这个文件;\n` +
+      `2. 按其中「提交前检查点」自查本次暂存变更(自己跑 \`git diff --cached\`,只看新增改动,逐项判断;命中项报告用户,由用户决定);\n` +
+      `3. 按其中「提交消息规范」写 commit message(规范要求票据/需求号而未知 → 问用户,不得编造或省略)。\n\n` +
+      `处理完后,用以下形式重试以跳过本检查:\n  ${ENV_BYPASS} git commit ...`
+    : `【提交门禁】项目没有 \`${GUIDE_RELPATH}\`(提交消息规范 + 提交前检查点):\n` +
+      `建议先跑 \`/init-project-guides\` 生成(挖掘项目 git 历史的消息风格 + 按技术栈定制检查点);用户明确表示不需要规范时可继续。\n\n` +
+      `确认后,用以下形式重试以跳过本检查:\n  ${ENV_BYPASS} git commit ...`;
 
   deny(reason);
 }

package/dist/.claude-template/skills/.cgraphx/timeline-current-turn.json

@@ -0,0 +1 @@
+{"turn_id":"31b8cf8e-d02f-4bdd-92f7-d018b9ba93dd","session_id":"57ce4488-65ae-4599-963e-51a565cab791","ts":"2026-08-01T00:06:02.042Z"}

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

@@ -1,11 +1,11 @@
 ---
 name: cgraphx-guide
-description: cgraphx 应用整体使用指南 — 安装、项目接入、日常做需求的工作流(skill 串联)、agent 自动加载的上下文工具。Use when 用户问 cgraphx 怎么用/怎么安装/怎么接入项目/有哪些 skill/日常工作流/onboarding/新手入门/使用流程/安装步骤/skill 怎么配合/cgraphx 能干什么/cgraphx 和别的工具区别。问单个代码查询工具(codegraph_explore/callers/impact 怎么调)走 cgraphx skill,不是本 skill。
+description: cgraphx 应用整体使用指南 — 安装、项目接入、日常做需求的工作流(skill 串联)、agent 自动加载的上下文工具。Use when 用户问 cgraphx 怎么用/怎么安装/怎么接入项目/有哪些 skill/日常工作流/onboarding/新手入门/使用流程/安装步骤/skill 怎么配合/cgraphx 能干什么/cgraphx 和别的工具区别。问单个知识库/数据库/时间线工具怎么调走对应专责 skill(knowledge-api/db-query/developer-timeline),不是本 skill。
 ---
 
 # cgraphx 应用使用指南
 
-cgraphx 是本地优先的代码智能工具,把**代码图谱 + markdown 知识库 + 数据库查询 + 开发时间线**打包给 AI agent 用。本 skill 是**整体使用导航**——用户问"怎么用 / 怎么装 / 日常工作流 / 有哪些 skill"时调这里。
+cgraphx 是本地优先的 AI agent 研发工具,把**markdown 知识库 + 数据库查询 + 开发时间线**打包给 AI agent 用。本 skill 是**整体使用导航**——用户问"怎么用 / 怎么装 / 日常工作流 / 有哪些 skill"时调这里。
 
 视觉版介绍页(给人类用户看):`how-to-use.html`(本 skill 目录内,随 skill 分发,`cgraphx install` 时部署到项目 `.claude/skills/cgraphx-guide/`)。
 
@@ -18,11 +18,12 @@ cgraphx 是本地优先的代码智能工具,把**代码图谱 + markdown 知识
 - 用户问 cgraphx 整体能干什么、和别的工具区别
 
 **不要用本 skill**(走对应专责 skill):
-- 单个代码查询(`codegraph_explore` / `callers` / `impact` 怎么调)→ `cgraphx` skill
-- 查业务知识(`docs/knowledge/`)→ `code-impact-api` skill
+- 查业务知识(`docs/knowledge/`)→ `knowledge-api` skill
 - 查数据库 → `db-query` skill
+- 生成开发时间线 / 日报 / 周报 → `developer-timeline` skill
 - 写 PRD / spec / plan → 各自 skill
-- 探索陌生项目建知识库 → `code-impact-init` skill
+- 探索陌生项目建知识库 → `knowledge-init` skill
+- 查代码结构 / 调用链 / 影响半径 → 用 `grep` / `Read` 等编辑器自带工具(2.0 起不再提供代码图谱)
 
 本 skill 只做整体导航,不重复各 skill 的内部规范。
 
@@ -31,11 +32,11 @@ cgraphx 是本地优先的代码智能工具,把**代码图谱 + markdown 知识
 | 阶段 | 命令 / skill |
 |---|---|
 | **机器级 · 每机器一次** | `npm install -g cgraphx` |
-| **项目级 · 每项目一次** | `cgraphx init`(建代码图谱)、`cgraphx install`(写 MCP 配置 + 部署 skills 模板到项目 `.claude/`)、`/code-impact-init`(接手陌生项目时建业务知识库) |
+| **项目级 · 每项目一次** | `cgraphx install`(建 `.cgraphx/` 数据目录 + 部署 skills/commands 到 `.claude/` + 写 hooks/statusLine)、`/knowledge-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/` |
+| **日常做需求 · 复杂按需** | `/write-prd`、`/write-spec`、`/write-plan`、`/knowledge-write`(沉淀到 `docs/knowledge/`) |
+| **工作回顾 · 按需** | `/developer-timeline`(日/周/月报)、`/write-design-doc`(发布后合成设计文档) |
+| **卸载 · 可选** | `cgraphx uninstall`(清项目 `.claude/` 内包自带的 skills/配置 + 删 `.cgraphx/`)、`npm uninstall -g cgraphx` |
 
 ## 各 skill 导航
 
@@ -49,44 +50,41 @@ cgraphx 是本地优先的代码智能工具,把**代码图谱 + markdown 知识
 | `/write-plan` | 拆执行计划(给 agent 执行) |
 | `/implementation` | 简单任务实现(主会话顺序做) |
 | `/subagent-implement` | 复杂多任务实现(派子 agent,隔离上下文) |
-| `/code-impact-init` | 接手陌生项目,派子 agent 自动探索、建业务知识库 |
-| `/code-impact-markdown` | 把业务决策 / 概念沉淀成 md 到 `docs/knowledge/` |
-| `/code-impact-docgen` | 从知识库合成面向人类阅读的业务 / 技术文档(HTML 或 Markdown) |
+| `/knowledge-init` | 接手陌生项目,派子 agent 自动探索、建业务知识库 |
+| `/knowledge-write` | 把业务决策 / 概念沉淀成 md 到 `docs/knowledge/` |
+| `/write-design-doc` | 发布后按需,从知识库合成面向人类阅读的设计文档(HTML 或 Markdown) |
 | `/developer-timeline` | 生成日报 / 周报 / 月报 / 阶段总结 / 交付汇报 |
 
 ### agent 自动调用(用户不主动敲,agent 用来加载项目上下文)
 
 | skill / 工具 | agent 何时自动调 |
 |---|---|
-| `codegraph_explore` | 任何代码理解 / 修改前——查代码结构、调用链、影响半径 |
-| `code-impact-api` | 任务开始时查 `docs/knowledge/` 业务决策 / 概念 / 历史教训 |
+| `knowledge-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)
+cd /your/project && cgraphx install  # 建 .cgraphx/ + 部署 skills/commands 到 .claude/ + 写 hooks/statusLine
 ```
 
-`cgraphx install` 默认 **local**(写项目内 `.claude/` / `.cursor/` 等);想影响所有项目才用 `--location=global`。
+`cgraphx install` 只作用于当前项目(项目级,写项目内 `.claude/` 与 `.cgraphx/`);升级 CLI(`cgraphx upgrade`)后到各项目重跑一次即可刷新。
 
-接手陌生项目时可选第四步:`/code-impact-init` 派子 agent 自动探索、建业务知识库到 `docs/knowledge/`。
+接手陌生项目时可选第四步:`/knowledge-init` 派子 agent 自动探索、建业务知识库到 `docs/knowledge/`。
 
 ## 背后自动(agent 跑的,用户无感)
 
-- 文件改动 → watcher 自动增量同步代码图谱(无需手动 reindex)
-- agent 经 `codegraph_explore` 自动查代码结构 / 调用链 / 影响半径
-- agent 经 `code-impact-api` 自动查业务知识
+- timeline 自动记录开发事件(无需手动跑)
+- agent 经 `knowledge-api` 自动查业务知识
 - agent 经 `db-query` 自动查数据库
-- `status` / `sync` / `explore` / `docs` / `db` / `timeline` 等 CLI 子命令由 agent / skill 调用,人类日常不主动跑
+- `status` / `docs` / `db` / `timeline` 等 CLI 子命令由 agent / skill 调用,人类日常不主动跑
 
 ## 卸载
 
 ```bash
 npm uninstall -g cgraphx             # preuninstall 钩子自动清所有 agent 的 MCP 配置
-# 需要清索引数据时,手动删项目目录下的 .cgraphx/
+# 需要清数据时,手动删项目目录下的 .cgraphx/
 ```
 
 ## 视觉版