cgraphx 1.4.0 → 1.4.3

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

@@ -0,0 +1,149 @@
+# cgraphx 怎么用
+
+本地优先的代码智能 · 给 AI agent 用的代码图谱
+
+最后更新:2026-07-16
+
+---
+
+## 安装流程
+
+- `npm install -g cgraphx` 装 CLI(Node ≥ 20 且 < 25)
+
+### 项目级 · 每项目一次
+
+- 项目目录内执行 `cgraphx init` 建 `.cgraphx/` 代码图谱索引和配置文件
+- 项目目录内执行 `cgraphx install` 写 MCP 配置 + 部署 skills 模板到项目 `.claude/`
+- 一定要先 `cgraphx init`, `cgraphx init` 执行的同时可以执行 `cgraphx install`
+
+### 卸载 · 可选
+
+- `npm uninstall -g cgraphx`
+- 删项目目录下 `.cgraphx/` 清索引数据
+
+---
+
+## 使用流程
+
+### 开发流程
+
+做需求的主线。
+
+- 必经 `/clarify-requirements` 澄清意图、业务边界、技术边界
+- 可选 `/write-prd` 写业务文档(给业务方 / 领导确认)
+- 核心 `/write-spec` 写技术规格(归档业务行为 / 规则 / 接口 / 数据)
+- 可选 `/write-plan` 拆执行计划(给 agent 执行)
+- 必经 `/implementation` 实现(简单任务)或 `/subagent-implement`(复杂多任务)
+
+> 日常默认 2 步:澄清 + 实现。复杂需求按需补 prd / spec / plan。cgraphx 在背后自动同步代码图谱,你不需要主动跑命令。
+
+---
+
+### 接口测试流程
+
+**需求开发完成后**
+
+- `/write-api` 基于 spec 或已有代码生成 bruno 测试接口(.bru + 测试规格 + 多环境配置)
+- `/run-api-test` 跑接口测试 + 核实写接口 DB 副作用 + 出报告 —— write-api 后执行;写接口必须查 DB 验数据
+
+> 产物落在 `docs/bruno/`(接口定义)+ `docs/features/<前缀>/`(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。
+
+---
+
+### 单元测试流程
+
+和开发流程平行,共享 spec 作为输入,时序任意(典型是代码先行、测试补充)。
+
+- `/write-unit-test-spec` 基于 spec 产出单元测试规格文档(零代码依赖,该测哪些路径/边界/异常)—— 可选,write-spec 后任意时机
+- `/write-unit-test-code` 基于测试规格 + 已有实现,填实测试代码 + 跑测试 + 出报告 —— 找不到测试规格则退出要求先跑 write-unit-test-spec
+
+```
+                         ┌──→ /write-plan → /implementation              开发流程 · 写代码
+                         │
+/clarify-requirements → /write-spec ──┤
+                         │
+                         └──→ /write-unit-test-spec → /write-unit-test-code   单元测试 · 写测试
+```
+
+> 两条独立线路:开发流程写代码,单元测试流程写测试。产物落在 `docs/features/<前缀>/`(测试规格 + 报告)+ 项目测试目录(.test.ts)。
+
+---
+
+### 知识库管理
+
+沉淀业务决策、概念定义、历史教训到跨需求共享的知识库。
+
+- `/code-impact-markdown` 任何有价值的会话都可以触发沉淀 —— 你只需要关注这一个指令
+- `/code-impact-init` 新项目起步时批量探索 + 写知识库 —— 可选,接手陌生项目时跑
+- `knowledge-recall` 聊业务 / 不懂术语 / 对齐黑话时,派子 agent 召回相关概念 —— agent 自动触发
+- `code-impact-api` 已知概念名,精确查知识库 —— agent 自动触发
+
+> 产物落在 `docs/knowledge/*.md`。写文件前必须过 `cgraphx docs validate` 校验,非法文件会被索引跳过。
+
+---
+
+### 模型知识库管理
+
+数据库 schema 的 DDL 快照 + 探索补充,让 AI 理解表结构和业务语义。
+
+- `/export-table-ddl` 按 profile 批量导出项目用到的表的 CREATE TABLE DDL,按工程分目录 —— 项目接入时跑一次,schema 变了重跑
+- `db-query` 查数据时读本地 DDL 文件(首选),文件不存在才连 DB 兜底;探索发现的隐式关系/含义/陷阱 append 到对应表的 DISCOVERED 块 —— agent 自动触发
+
+> 产物落在 `docs/schema-knowledge/<工程>/`(INDEX.md + ddl/<table>.sql + pending-comments.sql)。重 dump 时 DISCOVERED 块自动保留,积累不丢。
+
+---
+
+## docs/ 目录速查
+
+翻文档时知道去哪儿找 —— 哪个目录由哪个 skill 自动维护。
+
+**图例**:`必有` = 必有 | `可选` = 可选(按需) | `本地测试相关`
+
+```
+docs/ 文档工程                                             # 必有
+├── bruno/  API接口目录          # write-api + run-api-test 维护; bruno app 可以直接打开这个目录识别为接口列表
+│   ├── bruno.json                                 
+│   ├── environments/
+│   │   ├── local.bru                               
+│   │   ├── staging.bru
+│   │   └── production.bru
+│   ├── common/                                   
+│   │   └── <接口名>/<场景>.bru
+│   └── <服务名>/                              
+│       └── <需求前缀>/                           
+│           └── <接口名>/                         
+│               ├── <场景1>.bru                   
+│               └── <场景2>.bru                   
+│
+├── features/   需求目录
+│   └── <日期>-<编号>-<前缀>/  # 如 2026-07-03-CRM-req19230-号百商品详情查询接口
+│       ├── <前缀>-spec.md          /write-spec           必选  clarify 后执行
+│       ├── <前缀>-需求文档.md       /write-prd            可选  需要需求文档时,spec 之后
+│       ├── plan/                /write-plan           可选  大需求,spec/prd 后
+│       ├── <前缀>-单元测试-spec.md  /write-unit-test-spec  可选  spec 后任意时机
+│       ├── <前缀>-单元测试报告.md   /write-unit-test-code  可选  spec+开发完成后
+│       ├── <前缀>-api-spec.md      /write-api            可选  接口测试,开发完成后
+│       ├── <前缀>-测试报告.md       /run-api-test          可选  write-api 后自动产出
+│       ├── <前缀>-测试验证.jsonl    /run-api-test          可选  自动产出
+│       └── <前缀>-设计文档.md       /code-impact-docgen   可选  功能稳定后执行
+│
+├── knowledge/   知识库目录                         /code-impact-markdown 任何有价值的会话都可以触发沉淀;
+│                                                 /code-impact-init 新项目起步可以批量写 [可选]
+│
+
+├── schema-knowledge/   模型知识库目录  /export-table-ddl 批量初始化工程模型, 按工程分目录
+│   ├── xw-inst                      /db-query 自动读文件内的模型, 兜底连接数据库获取数据, 经验回写到对应的 ddl文件
+│   │   ├── INDEX.md                 # 表名 + 表注释,agent 进目录第一件事读
+│   │   ├── pending-comments.sql     # DBA 待执行 COMMENT SQL(action 队列,执行一条删一条)
+│   │   └── ddl/
+│   │       ├── <table>.sql          # 完整 DDL + 末尾 DISCOVERED 块(db-query 探索补充的隐式关系/含义/陷阱)
+│   │       └── <table>.sql
+│   ├── xw-order                     # 结构同 xw-inst
+│   └── xw-so                        # 结构同 xw-inst
+```
+
+> **两个核心目录** —— `docs/features/` 是单次需求工作目录(必须有 spec.md),`docs/knowledge/` 是跨需求共享的业务知识库。**bruno/ 和 schema-knowledge/ 按需出现**,只在跑接口测试 / 查 DB 时产生。
+
+---
+
+cgraphx 使用说明 · 2026-07-16

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

@@ -31,38 +31,39 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 
 ## 流程
 你必须为下列每一项创建一个任务,并按顺序完成:
-1. **探索上下文**
+1. **知识库召回**
+   - 必须问用户是否需要 `knowledge-recall skill`, 用户确认后按 `knowledge-recall skill`流程,派出subagent探索知识库. 用于理解项目内行业俗语和黑话
+
+2. **探索上下文**
    - 按需读项目结构、文档、代码、测试、schema、路由、模型、API、UI、既有约定
    - 项目里有这些工具可作为上下文补充, 对于符合的场景,必须使用:
-     - `code-impact-api skill` — 查 历史决策、业务概念、项目经验时必须使用
      - `db-query skill` — 查数据库、查 DDL 时必须使用
      - `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径时必须使用
-     - `developer-timeline skill` — 查用户最近做了什么(回顾开发历史) 时必须使用
    - 调用前明确告诉用户"我需要先查 X 来理解背景"。收集完简要陈述发现,不要大段贴原文
    - 在假设任务形态之前,先识别当前行为和既有约束
 
-2. **分类任务**
+3. **分类任务**
    - 选一个主任务类型
    - 只在严重影响澄清时加次任务类型
    - 任务类型不清楚时,先问一个简短的分类问题再继续
 
-3. **确认初步理解** ← 循环式复述的核心
+4. **确认初步理解** ← 循环式复述的核心
    - 复述你理解的意图
    - 点出怀疑的目标、受影响的区域、初步范围
    - 用结构化清单复述,然后明确问:"**这是你的意思吗?有什么要补充或纠正的?**"
    - **铁律:用户明确说"没补充/没纠正/理解对了"之前,不进第 4 步。** 这一步的循环是整个 skill 的核心价值——agent 不知道用户脑中还有哪些观点没抛出来;理解偏差是后续所有返工的最大来源
 
-4. **澄清业务边界**
+5. **澄清业务边界**
    - 确认业务目标、参与者、场景、包含范围、排除范围、数据归属、权限、异常、成功标准
    - 对需要领导/业务方拍板的规则、口径、优先级、例外、验收标准明确标记为"业务决策"
 
-5. **澄清技术方案边界**
+6. **澄清技术方案边界**
    - 确认受影响的层和主要技术选择,**不展开成完整设计 spec**
    - **技术方案涉及既有代码改动时,做影响分析**——把 blast radius、直接调用方、受影响流程、风险等级(LOW/MEDIUM/HIGH/CRITICAL)报告给用户。HIGH/CRITICAL 风险必须先警告用户,再决定是否继续
    - 当目标清楚但方案未定时,给 2-3 个可行方案 + 权衡 + 推荐方案;用户确认前不得把推荐方案写成已锁定技术方向
    - 判断哪些技术决策必须在 spec/plan 前锁定,哪些可以留给后续实现做局部工程适配
 
-6. **总结并停止**
+7. **总结并停止**
    - 输出简洁的澄清总结(见「最终输出」)
    - 提一句可能的下一步(写 PRD/spec/plan/实现),作为用户控制的选择,不自动继续
    - 总结指向"实现"时,**根据任务规模推荐 `/implementation` 或 `/subagent-implement`**(见「下游实现 skill 选择」)

package/dist/.claude-template/skills/code-impact-init/SKILL.md

@@ -710,6 +710,7 @@ $CODEGRAPH docs find --q="{name}" --limit=5 --json
 7. source_type 填 ai_session
 8. related_code 填实际探索过的文件路径（cgraphx query / impact 输出已有，直接复制）
 9. 文档正文必须包含：Summary, Context, Findings, Evidence, Impact For Future Changes
+10. **Write 后必须 `cgraphx docs validate <file>` 校验通过**（code-impact-markdown skill 的强制步骤）；非法则修 frontmatter 再 Write 再校验，直到合法
 
 完成后只返回以下 JSON（不要返回文档内容）：
 {
@@ -778,6 +779,8 @@ frontmatter：
 - related_code 填 codegraph_impact MCP 报告里 affected symbols 涉及的高中心性文件
 - concepts 填此核心 concept + 关联 concept
 
+**Write 后必须 `cgraphx docs validate <file>` 校验通过**（同知识文档流程步骤 10）。
+
 完成后返回 JSON：
 {
   "document_path": "docs/knowledge/xxx.md",

package/dist/.claude-template/skills/code-impact-markdown/SKILL.md

@@ -36,8 +36,9 @@ docs/knowledge/
 5. 如果是更新已有的 Markdown 文件,先读取并保留当前 frontmatter。
 6. 编写简洁的 frontmatter,使文档可被图谱解析。
 7. 正文必须包含 `## Summary`(唯一进索引的章节),其他章节按 `document_type` 选模板自由组织。
-8. 检查是否已有文档覆盖了相同主题。当三个合并条件全部满足时(见文档合并检查),提示用户是否合并。
-9. 编辑后询问是否触发扫描。**未经确认不要运行扫描**。
+8. **Write 后立刻 `cgraphx docs validate <file>` 校验**(见下节),非法则修 frontmatter 再 Write 再校验,直到合法。
+9. 检查是否已有文档覆盖了相同主题。当三个合并条件全部满足时(见文档合并检查),提示用户是否合并。
+10. 编辑后询问是否触发扫描。**未经确认不要运行扫描**。
 
 ## 查询已有词汇
 
@@ -62,9 +63,16 @@ cgraphx docs find --concept=Redis   # 按 concept 精确过滤
 grep -rl "concepts:" docs/knowledge/ --include="*.md"
 ```
 
-## 校验 frontmatter(本地自查)
+## 校验 frontmatter(写文件前必跑)
 
-cgraphx 无服务端校验端点。**编辑后自查 7 必填字段是否齐全且合法**:
+cgraphx 提供 `docs validate` 子命令,写文件前**必须**跑一遍校验,通过才保存:
+
+```bash
+cgraphx docs validate <file>        # 文本输出,exit 0 合法 / 2 非法
+cgraphx docs validate <file> --json # JSON 输出 {valid, skipReason, detail}
+```
+
+校验内容(规则与 `cgraphx docs index` 扫描时一致,单一事实源 `src/markdown/validator.ts`):
 
 | 字段 | 校验 |
 |---|---|
@@ -76,7 +84,7 @@ cgraphx 无服务端校验端点。**编辑后自查 7 必填字段是否齐全
 | `source_type` | 7 枚举之一(见下) |
 | `updated` | `YYYY-MM-DD` 格式 |
 
-任一字段缺失或非法 → cgraphx 扫描时**整个文件被跳过**,记入 skip 日志(可用 `cgraphx docs index` 输出查看跳过原因)。
+**流程**:Write 文件 → `cgraphx docs validate <file>` → 非法则**修 frontmatter 再 Write 再校验**,直到合法才告知用户文件已保存。非法文件即使写了,`cgraphx docs index` 扫描时也会整个跳过 —— 所以校验前置不是可选,是必须。
 
 ## 命名规则
 

package/dist/.claude-template/skills/db-query/SKILL.md

@@ -69,13 +69,13 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
    → "你期望这条 SQL 返回什么样的业务实体?"
    → 用户也不知道时,**每一步试错都报告用户**,让用户决定继续还是换思路
 
-4. 探索完成(用户告知或谨慎试错得到结论)后,沉淀到 per-table DDL 文件:
-   a. 定位文件 docs/schema-knowledge/<project>/ddl/<table>.sql(不存在 → 先跑 export-table-ddl 建基线)
-   b. append 到文件末尾的 DISCOVERED 块(格式见下)
-   c. 若是 DB 注释缺失导致的含义不明 → 另生成 COMMENT SQL 提示用户执行(执行后 DB 注释固化,DISCOVERED 块里那条可删)
+4. 探索完成(用户告知或谨慎试错得到结论)后,按"给谁看"分两类落点:
+   - **给 agent 看(知识)** → append 到 `ddl/<table>.sql` 的 DISCOVERED 块(格式见下)。这是 agent 读路径上的必经节点,知识必须留在这。
+   - **给 DBA 执行(action)** → 若 DB 的 COMMENT/字段注释缺失,生成 `ALTER TABLE ... COMMENT '...'`(MySQL)或 `COMMENT ON COLUMN/TABLE ... IS '...'`(PG),append 到 `<project>/pending-comments.sql`。这是 DBA 的任务队列 —— 执行一条删一条,不在 agent 读路径上,所以放独立文件没问题。
+   - 落点口诀:**知识进 DDL 文件,action 进 pending-comments.sql**。两者不混 —— DISCOVERED 块只放"agent 现在要知道的",pending-comments.sql 只放"等 DBA 固化进 DB 的暂存区"。
 ```
 
-**长期目标**:DB 注释逐渐健全(用户/DBA 执行了 COMMENT SQL)后,`schema --mode ddl` 直接返回业务含义,DISCOVERED 块逐渐退役。DB 自带注释是单一事实源,任何工具/任何人查 DDL 都受益。
+**长期目标**:DB 注释逐渐健全(DBA 执行了 pending-comments.sql)后,`schema --mode ddl` 直接返回业务含义,DISCOVERED 块里对应的 `[字段含义]` 行可删(已被 DB 固化),pending-comments.sql 也 drain 完。DB 自带注释是单一事实源,任何工具/任何人查 DDL 都受益。
 
 ## DISCOVERED 块格式(append 到 ddl/<table>.sql 末尾)
 
@@ -104,6 +104,28 @@ agent 的访问路径是 `INDEX.md → ddl/<table>.sql`,**基本不会主动读
 
 工程级 meta(profile 对应哪个服务、整体架构一句话)可以放 `INDEX.md` 顶部(agent 进目录第一件事就是读它),但不要沉淀到表级以下的独立文件。
 
+### pending-comments.sql —— 唯一允许的独立文件(DBA action 队列)
+
+`<project>/pending-comments.sql` 是上述"绝不建独立文件"规则的**唯一例外**,因为它服务的不是 agent 而是 DBA:
+
+- **内容**:待执行的 `ALTER TABLE ... COMMENT '...'`(MySQL) / `COMMENT ON COLUMN/TABLE ... IS '...'`(PG)语句,补 DB 缺失的字段/表注释。
+- **为什么可以独立**:agent 读路径是 `INDEX.md → ddl/<table>.sql`,**不经过 pending-comments.sql** —— 它不在路径上,放独立文件不会"埋"任何 agent 需要的知识。它只是 DBA 的任务队列。
+- **格式**:纯 SQL,按表分组,每组前一行 `-- <table>` 注释。DBA 跑一条删一条(drain 语义)。
+- **和 DISCOVERED 块的分工**:同一个字段含义,DISCOVERED 块写"agent 现在要知道的"(立即生效),pending-comments.sql 写"等 DBA 固化进 DB 的"(异步执行)。DBA 执行后:删 pending-comments.sql 里那条 + 删 DISCOVERED 里对应的 `[字段含义]` 行(DB 已固化,文件副本冗余)。
+- **重 dump 不动它**:`export-table-ddl` 脚本只写 `INDEX.md` 和 `ddl/*.sql`,不碰 pending-comments.sql。
+
+```sql
+-- pending-comments.sql for order-svc
+-- 待执行的 COMMENT SQL — DBA 跑完一条删一条,跑完后对应 DISCOVERED [字段含义] 行也可删
+
+-- work_order (MySQL)
+ALTER TABLE work_order MODIFY COLUMN status TINYINT NOT NULL COMMENT '0=待派单 1=处理中 2=已完成 3=取消';
+ALTER TABLE work_order MODIFY COLUMN assignee_id VARCHAR(64) COMMENT '处理人工号,关联 users.staff_code';
+
+-- users (PG)
+COMMENT ON COLUMN users.tenant_id IS '租户隔离字段,所有查询必须带这个过滤';
+```
+
 ## 何时派子 agent(让上下文更干净)
 
 主 agent **直接调 cgraphx db 工具时,大段原文(DDL 字段列表、SELECT 输出、表关系推断过程)会进自己的上下文**,挤占决策与待办的空间。本 skill 工具适合精确查询,但**模糊意图的重探索型任务**适合派子 agent 在隔离上下文里跑。
@@ -145,14 +167,19 @@ agent 的访问路径是 `INDEX.md → ddl/<table>.sql`,**基本不会主动读
 ```
 docs/schema-knowledge/
   <工程A>/
-    INDEX.md          # 表名 + 表注释,一眼扫完
+    INDEX.md                # 表名 + 表注释,一眼扫完(agent 入口)
+    pending-comments.sql    # DBA 待执行的 COMMENT SQL(action 队列,不在 agent 读路径上)
     ddl/
-      users.sql        # 完整 DDL + 末尾 DISCOVERED 块(db-query 探索补充)
+      users.sql             # 完整 DDL + 末尾 DISCOVERED 块(agent 读路径)
       work_order.sql
   <工程B>/
     ...
 ```
 
+**两类落点,各服务不同对象**:
+- **给 agent 看(知识)** → `ddl/<table>.sql` 的 DISCOVERED 块。agent 读路径必经。
+- **给 DBA 执行(action)** → `pending-comments.sql`。DBA 任务队列,不在 agent 读路径上。
+
 **两张表的 DDL 文件示例**(work_order.sql):
 
 ```sql
@@ -170,10 +197,10 @@ CREATE TABLE `work_order` (
 ```
 
 **闭环工作流**:
-1. `export-table-ddl` 跑一次 → 建基线(DDL + 注释 + 索引,无 DISCOVERED 块)
-2. 日常 `db-query` 查数据踩坑 → 发现隐式关系/含义/陷阱 → append 到对应 `ddl/<table>.sql` 的 DISCOVERED 块
-3. 重跑 `export-table-ddl`(schema 变了)→ DISCOVERED 块保留,新 DDL 接上
-4. DB 注释健全后 → DISCOVERED 块里对应的行可删(DB 已固化)
+1. `export-table-ddl` 跑一次 → 建基线(DDL + 注释 + 索引,无 DISCOVERED 块,无 pending-comments.sql)
+2. 日常 `db-query` 查数据踩坑 → 发现隐式关系/含义/陷阱 → 知识进 `ddl/<table>.sql` 的 DISCOVERED 块;DB 注释缺失则 action 进 `pending-comments.sql`
+3. 重跑 `export-table-ddl`(schema 变了)→ DISCOVERED 块保留,新 DDL 接上;pending-comments.sql 不动
+4. DBA 执行 pending-comments.sql 里的语句 → DB 注释固化 → 删 pending-comments.sql 里那条 + 删 DISCOVERED 里对应的 `[字段含义]` 行(DB 已是单一事实源,文件副本冗余)
 
 ## 期望错误(CLI 退出码语义)
 

package/dist/.claude-template/skills/export-table-ddl/closed-loop.html

@@ -118,17 +118,20 @@
 <h2>1. 共享的目录结构(知识库本体)</h2>
 <div class="tree">docs/schema-knowledge/
 ├── order-svc/
-│   ├── <span class="hl">INDEX.md</span>                  ← agent 进目录第一件事读(表清单+注释)
+│   ├── <span class="hl">INDEX.md</span>                ← agent 进目录第一件事读(表清单+注释)
+│   ├── pending-comments.sql   ← DBA 待执行 COMMENT SQL(action 队列,不在 agent 读路径)
 │   └── ddl/
 │       ├── work_order.sql    ← DDL + <span class="hlo">DISCOVERED 块</span>(积累的隐式关系/含义/陷阱)
 │       ├── users.sql         ← DDL + DISCOVERED 块
 │       └── payment.sql
 └── cust-svc/
     ├── INDEX.md
+    ├── pending-comments.sql
     └── ddl/...</div>
 <p style="font-size:14px;color:var(--gray);">
   <b style="color:var(--green)">绿色</b> = agent 必经节点(INDEX.md 是入口,ddl/&lt;table&gt;.sql 是详情);
-  <b style="color:var(--orange)">橙色</b> = db-query 探索补充的部分,export 重 dump 时会保留。
+  <b style="color:var(--orange)">橙色</b> = db-query 探索补充的部分,export 重 dump 时会保留;
+  <b style="color:var(--gray)">灰色</b> pending-comments.sql = DBA action 队列,不在 agent 读路径上(所以可以独立文件)。
 </p>
 
 <h2>2. 时序:知识怎么积累起来</h2>
@@ -143,11 +146,18 @@
   </div>
   <div class="tl-item write">
     <div class="tl-title">T1 续 · 发现 work_order.assignee_id 实际对应 users.staff_code</div>
-    <div class="tl-body">append 到 <code>ddl/work_order.sql</code> 和 <code>ddl/users.sql</code> 的 DISCOVERED 块(双向)</div>
+    <div class="tl-body">
+      知识 → append 到 <code>ddl/work_order.sql</code> 和 <code>ddl/users.sql</code> 的 DISCOVERED 块(双向)<br>
+      DB 注释缺失 → action 进 <code>pending-comments.sql</code>(DBA 待执行)
+    </div>
   </div>
   <div class="tl-item init">
     <div class="tl-title">T2 · DBA 改了 schema,重跑 export-table-ddl</div>
-    <div class="tl-body">DDL 部分刷新(拿新结构),<b style="color:var(--orange)">DISCOVERED 块自动保留</b>(不覆盖)</div>
+    <div class="tl-body">DDL 部分刷新(拿新结构),<b style="color:var(--orange)">DISCOVERED 块自动保留</b>(不覆盖);pending-comments.sql 不动</div>
+  </div>
+  <div class="tl-item write">
+    <div class="tl-title">T2 续 · DBA 执行 pending-comments.sql 里的 COMMENT</div>
+    <div class="tl-body">DB 注释固化 → 删 pending-comments.sql 里那条 + 删 DISCOVERED 对应的 <code>[字段含义]</code> 行(DB 已是单一事实源)</div>
   </div>
   <div class="tl-item read">
     <div class="tl-title">T3 · 下一次 db-query 读 work_order</div>

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

@@ -123,6 +123,26 @@ description: 用户要求根据已确认的 plan、spec、任务清单、实现
 - 如果存在 plan,最终能说明 `PLAN_FOLLOWED` / `PLAN_ADAPTED` / `PLAN_CONFLICT` 的状态。
 - 最终回复清楚列出变更和验证结果。
 
+## 知识沉淀提示(实现结束后)
+
+汇报完变更和验证结果后,**主动评估本次会话是否产生了值得沉淀的知识**。不是每次都问 —— 只在本次实现中确实出现了下面任一情况时,提示用户:
+
+- 踩了一个非显而易见的坑 / 陷阱(读代码看不出来,下次还会踩)
+- 发现一个隐式约束或业务规则(代码里没写明,但影响实现)
+- 做了一个有取舍的技术决策(存在替代方案,为什么选这个)
+- 跨系统 / 跨文件的依赖关系,单看代码看不出来
+- 历史背景 / 遗留约束解释了代码为什么是现在这样
+
+满足时,在汇报末尾加一句:
+
+```text
+本次实现中 [简述发现],是否需要用 code-impact-markdown skill 沉淀到 docs/knowledge/?
+```
+
+用户同意 → 调 `code-impact-markdown` skill 走它的完整流程(查已有概念 → 写文件 → `docs validate` 校验 → 合并检查 → 询问扫描)。用户拒绝或没有值得沉淀的内容 → 不提,正常结束。
+
+**不要自己造沉淀流程** —— 必须走 `code-impact-markdown` skill,它有 frontmatter 规范、校验、合并检查、命名规则。直接 Write 一个 .md 不校验不查重,等于往知识库灌坏文件。
+
 ## 遇到阻塞
 
 遇到以下情况时暂停并向用户说明:

package/dist/.claude-template/skills/knowledge-recall/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: knowledge-recall
+description: 从项目 markdown 知识库召回业务概念 — 当用户聊业务/遇到不懂的术语/需要对齐项目黑话/提到一个名词想确认项目里有没有沉淀过时,强制派子 agent 在隔离上下文里加载全量 concept 列表做语义匹配,主 agent 只拿命中的概念(名+文档路径+一行说明),不直接看到全量表。Use when 聊业务/不懂这个术语/这个词什么意思/对齐黑话/项目黑话/业务概念/行业术语/这个名词/沉淀过/之前记录过/有没有相关文档/这个业务词.
+---
+
+## 这个 skill 解决什么
+
+用户和 AI 聊业务时,AI 往往不会主动查项目已沉淀的概念,导致:用错行业黑话、重复问已记录过的问题、不知道有相关决策文档。本 skill 强制把"加载全量 concept + 匹配"这件事放进子 agent 的隔离上下文,主 agent 只收命中结果 —— 全量表(几十到几百个概念)不进主上下文,避免挤占决策空间。
+
+## 流程
+
+1. **Agent tool 调用**(专用子 agent,指令已内置在 agent 定义里):
+   ```
+   Agent({
+     subagent_type: "knowledge-recall",
+     prompt: "当前任务: " + <用户原话或你的转述>
+   })
+   ```
+2. **直接采纳** 子 agent 返回的命中概念列表 —— 不要再自己调 `cgraphx docs concepts/find` 重新查(那是浪费,且会把全量表拉进主上下文)
+3. 拿到命中概念后,主 agent 决定下一步:
+   - 概念够清晰,直接回答用户
+   - 需要细节 → `Read` 子 agent 返回的文档 path
+   - 需要精确查某个概念的其他文档 → 调 `code-impact-api` skill
+   - 子 agent 说"没有命中"→ 告诉用户项目里没沉淀这个概念,问要不要记录

package/dist/.claude-template/skills/write-unit-test-code/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: write-unit-test-code
+description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实现代码,填实单元测试代码 + 跑测试 + 出报告。读测试规格派生场景 → 读实现代码定位被测目标(函数/类/模块)→ 产出 .test.ts(断言填实,能真跑)→ 跑测试 → 出 <前缀>-单元测试报告.md。被测代码缺失的场景用 it.skip + TODO 占位。依赖测试规格文档存在 —— 找不到时报错退出,要求先跑 /write-unit-test-spec。Use when 想填实测试代码 / 写单元测试 / 跑单元测试 / write-unit-test-code. 不写业务实现代码、不修实现 bug、不假装通过.
+---
+
+# Write Unit Test Code
+
+## 定位
+
+**测试填实 + 验证 skill**:消费 `write-unit-test-spec` 产出的测试规格文档,基于已有实现代码填实测试代码,跑测试验证,出测试报告。
+
+**和 write-unit-test-spec 的分工**:
+- write-unit-test-spec:产**测试规格文档**(该测哪些场景,基于 spec,零代码依赖)
+- 本 skill(write-unit-test-code):基于测试规格 + 已有实现,填实测试代码 + 跑 + 出报告
+
+两个 skill 顺序依赖:本 skill 找不到测试规格文档时报错退出。
+
+**和 implementation 的关系**:平行线路。implementation 写业务实现代码,本 skill 写测试代码。本 skill 假设被测代码已存在(典型场景:用户跑完 implementation 后回来补测试);代码缺失的场景用 `it.skip` + TODO 占位。
+
+## HARD-GATE
+
+- **不写业务实现代码** —— 本 skill 只写测试代码 + 测试报告,业务实现是 implementation 的事
+- **依赖测试规格文档** —— 当前 feature 没有 `<前缀>-单元测试-spec.md` 时,报错退出:"找不到测试规格,请先跑 /write-unit-test-spec"。不自己现场派生测试场景(那是 write-unit-test-spec 的职责)
+- **不编造被测目标** —— 测试里 import 的函数/类/模块必须**已存在**。不存在 → 对应场景用 `it.skip` + `// TODO: 实现提供后填实` 占位,不自己造签名
+- **不修实现代码** —— 测试失败时如实报告,不替用户改业务代码
+- **不假装通过** —— 测试断言不调到"假绿"。失败就是失败,如实标在报告里
+
+## Trigger
+
+**使用此 skill 当**:
+- 用户跑完 `/write-unit-test-spec`,想填实测试代码
+- 用户跑完 implementation,想基于测试规格补测试
+- 用户明确说"填实测试 / 写单元测试代码 / 跑单元测试 / write-unit-test-code"
+
+**不要使用此 skill 当**:
+- 没有测试规格文档 —— 先跑 `/write-unit-test-spec`
+- 想写业务实现 —— 用 `/implementation`
+- 想产测试规格(不填实)—— 用 `/write-unit-test-spec`
+- 纯文档 / 配置 / 无行为变更的需求 —— 无可测代码
+
+## 流程
+
+### 1. 前置检查
+
+- 确认 `docs/features/<feature-id>/<前缀>-单元测试-spec.md` 存在。**不存在 → 报错退出**:"找不到测试规格,请先跑 /write-unit-test-spec"。不现场派生场景。
+- 复用测试规格的 feature-id 和文件前缀,推导出测试文件路径和报告文件名。
+
+### 2. 读测试规格文档
+
+读 `<前缀>-单元测试-spec.md`,拿到:
+- 必测场景清单(主路径 / 边界 / 异常,每条标 spec 依据)
+- 测试骨架映射(测试文件该放哪、框架、命名)
+
+### 3. 读已有实现代码
+
+根据测试规格描述的被测目标,在代码库定位已有实现(用 `codegraph_explore` MCP / `cgraphx query` CLI / grep / Read):
+- 读函数签名、参数、返回值、抛错行为、依赖关系
+- 如果测试规格里的某个场景**代码里还没实现**:
+  - 对应测试用 `it.skip` + `// TODO: 实现提供后填实` 占位
+  - 记入"实现缺失场景清单",汇报时告诉用户"有 N 个场景因实现缺失跳过"
+  - **不自己造签名**
+- 如果实现和 spec 不一致(测试规格基于 spec,但代码偏离了 spec):
+  - 在测试报告里标注"实现与 spec 偏差:X(spec 说 A,代码实际 B)"
+  - 测试按**代码实际行为**写(要能跑过)
+  - 偏差记录留给用户决定(改代码 / 改 spec / 接受现状)
+
+### 4. 产出测试文件(断言填实)
+
+写到 `<项目测试目录>/<feature-id>.test.ts`(或项目约定的命名/后缀,从测试规格的"骨架映射"节读取)。形态:
+
+- 实现已就绪的场景 → `describe` + `it`(含真实断言,基于读到的签名写,能真跑)
+- 实现缺失的场景 → `it.skip` + `// TODO: 实现提供后填实` 占位
+- import 被目标(已存在的模块直接 import;不存在的标 TODO 注释,不强行 import)
+- 框架(vitest/jest/...)和文件后缀按项目约定
+- 已有同模块测试文件 → 文件名加后缀避免覆盖(如 `<feature-id>.补充.test.ts`),在报告里提示"已有 X,是否合并由用户判断"
+
+**AI 自己发挥的空间**:fixture / mock 怎么组织、describe 嵌套多深、断言写多细,agent 按既有测试风格判断,不强加模板。
+
+### 5. 跑测试验证 + 产出测试报告
+
+跑一次项目的测试命令(如 `npm test`),确认新写的测试能跑(通过或失败都行,失败说明实现有 bug 或测试断言写错)。
+
+**产出单元测试报告**,写到 `docs/features/<feature-id>/<前缀>-单元测试报告.md`。结构轻量,至少包含:
+
+- 测试概况:总数 / 通过 / 失败 / 跳过(it.skip 占位)/ 时长
+- 逐场景结果:每个 `it` 的通过/失败/跳过 + 失败原因(如有)
+- 实现与 spec 偏差小结
+- 待确认项汇总(实现缺失 / spec 不够细等)
+- 下一步建议(失败 → 建议改实现 / 改测试 / 改 spec;跳过多 → 建议先补实现再回来跑)
+
+**报告原则**:
+- 通过 → 报告"测试已就绪,N 个场景覆盖"
+- 失败 → 报告如实标失败 + 原因分类(测试写错 / 实现有 bug / spec 和实现偏差),**不修实现,不假装通过**
+- 全部跳过(实现都没写)→ 报告标"无可跑测试,所有场景待实现",建议用户先跑 implementation
+
+### 6. 汇报 + 不自动继续
+
+告诉用户:
+- 测试文件路径
+- **单元测试报告路径** + 报告里的关键数字(通过/失败/跳过数)
+- 实现与 spec 的偏差(如有)
+- 待确认项(如有)
+
+**不调用 implementation / write-unit-test-spec / run-api-test**,由用户决定下一步。
+
+## 产物
+
+| 产物 | 路径 | 形态 |
+|---|---|---|
+| 测试文件 | `<项目测试目录>/<feature-id>.test.ts` | describe + `it`(断言填实) / `it.skip`(实现待补) |
+| 单元测试报告 | `docs/features/<feature-id>/<前缀>-单元测试报告.md` | 测试概况 + 逐场景结果 + 偏差小结 + 下一步建议 |
+
+## 边界场景
+
+- **找不到测试规格文档** → 报错退出,要求先跑 `/write-unit-test-spec`。不现场派生场景。
+- **实现代码缺失** → 对应场景 `it.skip` + TODO 占位,汇报时告诉用户。不造签名。
+- **已有同模块测试文件** → 文件名加后缀避免覆盖,报告里提示用户。不主动改既有测试。
+- **跨语言项目** → 按测试规格文档里标注的语言约定产出。一次调用不产多语言测试。
+- **实现与 spec 偏差** → 测试按代码实际行为写(要能跑过),偏差记录在报告里,汇报时提示用户。
+- **纯文档/配置需求** → 检测到测试规格无可测场景 → 提示"规格里无可测场景,不建议继续"并退出。
+
+## 不做的事
+
+- 不写业务实现代码(那是 implementation 的事)
+- 不现场派生测试场景(那是 write-unit-test-spec 的事,本 skill 找不到规格就退出)
+- 不修实现代码(失败如实报告)
+- 不假装通过(断言不调到假绿)
+- 不引入硬 gate(precommit hook / 提交拦截)
+- 不假设测试框架(从测试规格的骨架映射读,或运行时探测)
+- 不改 write-unit-test-spec / implementation / write-plan(它们对本 skill 零依赖)
+
+## 和其他 skill 的关系
+
+- **write-unit-test-spec**:上游,提供测试规格文档。本 skill 找不到它就退出。
+- **implementation**:平行线路,写业务实现。本 skill 读它的产物(代码),但不调它。
+- **run-api-test**:不同类型的测试(接口测试 vs 单元测试),互不干涉。