cgraphx 1.3.1 → 1.4.1

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

@@ -1,6 +1,6 @@
 ---
 name: code-impact-api
-description: 项目文档知识库查询入口 — 通过 cgraphx docs CLI 查询 docs/knowledge/ 下的业务决策、概念定义、历史教训。Use when 任务开始时 / 查业务概念 / 查历史决策 / 对齐术语 / 找相关文档 / 探索既有知识。
+description: 项目文档知识库查询入口 , 查询知识库概念 — 通过 cgraphx docs CLI 查询 docs/knowledge/ 下的业务决策、概念定义、历史教训。Use when 任务开始时 / 查业务概念 / 查历史决策 / 对齐术语 / 找相关文档 / 探索既有知识。
 ---
 
 ## 这个 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

@@ -20,7 +20,7 @@ cgraphx db <subcommand> [options]
 
 输出格式:所有命令支持 `--format json|table|csv`(schema 命令固定 json)。
 
-**`ddl` 模式输出字段**:每字段一行,含 `field_name` / `data_type` / `nullable` / `default_value` / `key_type`(PRI/UNI/MUL) / `comment`(字段业务注释) / `fk_table`+`fk_column`(外键关联,如有)。**这是判断表关系的首选信息源** —— 数据库本身定义的外键 + 业务专家写的注释都在这。
+**`ddl` 模式输出**:直接打印该表真实的 `CREATE TABLE ...` DDL 文本到 stdout(非 JSON)。MySQL 走 `SHOW CREATE TABLE`(含 ENGINE/CHARSET/外键/二级索引/列注释/表注释);PostgreSQL 由 `pg_get_constraintdef` + `pg_get_indexdef` + 列/表注释拼装(含 `COMMENT ON COLUMN` / `COMMENT ON TABLE` / `CREATE INDEX`)。**这是判断表关系 + 字段语义的首选信息源** —— 数据库外键 + 业务专家写的注释 + 索引都在这,输出可直接回灌给同方言 DB。
 
 ## 配置位置
 
@@ -36,7 +36,7 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
 1. **必须先确定目标库避免连错** — 先 `cgraphx db profiles` 列出,确认目标 profile
 2. **所有查询只读**(铁律,不可破) — 子系统内置禁止 DELETE/UPDATE/INSERT/DROP/ALTER,只读永不改变数据库
 3. **必须带 LIMIT** — `cgraphx db query` 自动 LIMIT,但自定义 SQL 仍建议显式 `LIMIT N`
-4. **先看表结构再写 SQL** — 用 `schema --mode ddl` 看字段、注释、外键,避免字段名拼写错误或类型不匹配
+4. **表结构优先读本地知识库,不主动连库** — 先 `Read docs/schema-knowledge/<project>/ddl/<table>.sql`(含 DDL + DISCOVERED 块,比 DB 多团队沉淀的隐式关系/含义/陷阱);文件不存在才 `cgraphx db schema --mode ddl` 兜底。DB 留给"查数据"和"知识库没有的表"
 5. **陌生 schema 探索"先问后试"** — 不确定表关系或字段含义时,**先问业务专家**,不要埋头反复试错(试错既浪费 token,也可能拿错数据误导后续判断)
 6. **复用 DAO 时验证参数** — 修改 Mapper XML 中的查询条件前,先用真实数据确认字段值分布
 
@@ -44,8 +44,9 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
 
 ```
 0. cgraphx db profiles                                  → 确认连接哪个库哪个 profile
-1. cgraphx db schema --mode ddl --table work_order      → 看字段、注释、外键
-2. cgraphx db query --sql "SELECT * FROM ... LIMIT 5"   → 用 LIMIT 查样本数据
+1. Read docs/schema-knowledge/<project>/ddl/work_order.sql  → 看字段、注释、外键 + DISCOVERED 块(本地,首选)
+   (文件不存在 → cgraphx db schema --mode ddl --table work_order 兜底)
+2. cgraphx db query --sql "SELECT * FROM ... LIMIT 5"   → 用 LIMIT 查样本数据(只有查数据才连库)
 3. 确认字段值分布                                          → 编写/修改代码
 ```
 
@@ -54,27 +55,76 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
 按以下优先级链尝试,**每步失败才进入下一步**:
 
 ```
-1. cgraphx db schema --mode ddl --table A
-   cgraphx db schema --mode ddl --table B
-   → 看 fk_table/fk_column(数据库外键)+ comment(业务注释)
-   → 大多数情况能直接看出关联
+1. Read docs/schema-knowledge/<project>/ddl/<table>.sql
+   → export-table-ddl skill 导出的 DDL + 团队补充的 DISCOVERED 块(隐式关系/字段含义/陷阱/流程)
+   → 找 <project> 目录:在 docs/schema-knowledge/*/ddl/ 下找 <table>.sql;唯一命中直接读,多个问用户
+   → 这是首选:比 DB 多 DISCOVERED 块,且不连库
 
-2. Read docs/schema-knowledge/<profile>.md
-   → 团队沉淀的表关系 + 字段含义 + 已知陷阱
-   → 含待执行的 COMMENT SQL(用户执行后从这里删除)
+2. 知识库没有 → cgraphx db schema --mode ddl --table A(再 B)
+   → 看 DDL 里的外键(MySQL: SHOW CREATE TABLE 内联 / PG: FOREIGN KEY ... REFERENCES)+ 列注释
+   → 兜底,且拿到后应沉淀回知识库(见步骤 4)
 
 3. 都没有 → 问用户(不要试错)
    → "这两个表你想通过哪个字段关联?"
    → "你期望这条 SQL 返回什么样的业务实体?"
    → 用户也不知道时,**每一步试错都报告用户**,让用户决定继续还是换思路
 
-4. 探索完成(用户告知或谨慎试错得到结论)后:
-   a. append 关系/含义到 docs/schema-knowledge/<profile>.md
-   b. 生成 COMMENT SQL(按 profile 的 db type 选语法)append 到 schema-knowledge 的"待执行 COMMENT SQL"段
-   c. 提示用户:执行后从文件删除(DB 注释已固化,不需要文件重复)
+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` 直接返回业务含义,**schema-knowledge 退役**。DB 自带注释是单一事实源,任何工具/任何人查 DDL 都受益。
+**长期目标**:DB 注释逐渐健全(DBA 执行了 pending-comments.sql)后,`schema --mode ddl` 直接返回业务含义,DISCOVERED 块里对应的 `[字段含义]` 行可删(已被 DB 固化),pending-comments.sql 也 drain 完。DB 自带注释是单一事实源,任何工具/任何人查 DDL 都受益。
+
+## DISCOVERED 块格式(append 到 ddl/<table>.sql 末尾)
+
+```sql
+-- === DISCOVERED (db-query 探索补充,非 DB 原生) ===
+-- [关系] assignee_id → users.staff_code (处理人工号,业务语义非 DB 外键)
+-- [关系] region_id → region.id (地域)
+-- [字段含义] status: 0=待派单 1=处理中 2=已完成 3=已取消
+-- [陷阱] email 不唯一(同 email 多账号),用 phone 关联更稳
+-- === END DISCOVERED ===
+```
+
+- 每行 `-- [类别] 内容`,类别:`关系` / `字段含义` / `陷阱` / `流程`(跨表业务流程)。
+- 块在 `-- === DISCOVERED` 和 `-- === END DISCOVERED ===` 之间 —— `export-table-ddl` 重 dump 时会保留这个块(不会覆盖)。
+- 一张表可多次 append;重复的行不重复加。
+- 这是 SQL 注释,不影响 DDL 可执行性。
+
+### 跨表知识往哪张表写 —— 枢纽表原则(重要)
+
+agent 的访问路径是 `INDEX.md → ddl/<table>.sql`,**基本不会主动读独立的 NOTES.md / 项目级笔记文件**。所以跨表知识不能单独建文件,必须塞进 agent 必然落地的表的 DISCOVERED 块:
+
+- **关系(`[关系]`)双向标注**:`A.x → B.y` 在 `A.sql` 和 `B.sql` 的 DISCOVERED 块各写一行。agent 无论从哪头查表,都能看到这条关联。
+- **跨表业务流程(`[流程]`)**:塞进该流程的**枢纽表** —— 即流程中心、agent 落地概率最高的那张表。例如"派单→处理→回单"流程,枢纽是 `work_order`(流程主表),写进 `work_order.sql`;不要散到 `dispatch_log`/`receipt` 各一份,更不要建 `派单流程.md`。
+- **枢纽表判断**:流程主表 / 被外键指向最多的表 / agent 问"X 业务"时最先被点名的表。多个候选时选那个,其余表用 `[关系]` 双向指回枢纽。
+- **绝不建** `NOTES.md` / `<project>-notes.md` / `跨表知识.md` 这类独立文件 —— 那等于把知识埋了,agent 不会主动读。
+
+工程级 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(让上下文更干净)
 
@@ -88,7 +138,7 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
 
 | 场景 | 不派(直接调工具) | 派(派子 agent) |
 |---|---|---|
-| 看表结构 | "work_order 表结构" → `cgraphx db schema --mode ddl --table work_order` | "梳理这个库的所有表关系" |
+| 看表结构 | "work_order 表结构" → `Read docs/schema-knowledge/*/ddl/work_order.sql`(没有再 `cgraphx db schema --mode ddl`) | "梳理这个库的所有表关系" |
 | 看索引 | "users 表的索引" → `cgraphx db schema --mode indexes --table users` | "系统理解 X 业务的数据模型" |
 | 查数据 | "查 work_order 里 status=1 的前 5 条" → `cgraphx db query --sql "SELECT ... LIMIT 5"` | "调研 work_order / payment / users 这套流程涉及的表关系" |
 
@@ -112,35 +162,45 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
 - **派的代价**:子 agent 本身耗 token,简单查询派反而更贵
 - **R4 是平衡点**:只在"模糊意图 + 主 agent 无法精确判断目标"时派
 
-## schema-knowledge 文件结构
-
-每个 profile 一个 markdown 文件:`docs/schema-knowledge/<profile>.md`(项目业务数据目录,跨工具版本保留,不会被 cgraphx 升级覆盖)
-
-```markdown
-# <profile> schema knowledge
+## schema-knowledge 目录结构(由 export-table-ddl 建基线,db-query 探索补充)
 
-## 表关系(DB 未定义 FK 的隐式关联)
-- `work_order.assignee_id` → `users.staff_code`(处理人)
-- `payment.order_id` → `work_order.id`(订单的支付记录)
-
-## 关键字段业务含义(DB 注释未覆盖的)
-- `work_order.status`: 0=待派单 1=处理中 2=已完成 3=已取消
-- `users.tenant_id`: 租户隔离字段,所有查询必须带这个过滤
-
-## 待执行的 COMMENT SQL(用户执行后从此处删除)
-ALTER TABLE work_order MODIFY COLUMN assignee_id VARCHAR(64) COMMENT '处理人工号,关联 users.staff_code';
-COMMENT ON COLUMN work_order.status IS '0=待派单 1=处理中 2=已完成 3=已取消';  -- PG
-ALTER TABLE work_order MODIFY COLUMN status TINYINT NOT NULL COMMENT '0=待派单 1=处理中 2=已完成 3=已取消';  -- MySQL
+```
+docs/schema-knowledge/
+  <工程A>/
+    INDEX.md                # 表名 + 表注释,一眼扫完(agent 入口)
+    pending-comments.sql    # DBA 待执行的 COMMENT SQL(action 队列,不在 agent 读路径上)
+    ddl/
+      users.sql             # 完整 DDL + 末尾 DISCOVERED 块(agent 读路径)
+      work_order.sql
+  <工程B>/
+    ...
+```
 
-## 已知陷阱
-- `users.email` 不是唯一(同 email 多账号)—— 用 `users.phone` 关联更稳
-- 跨 schema 查询时 schema 前缀必须显式(如 `tenant.users`)
+**两类落点,各服务不同对象**:
+- **给 agent 看(知识)** → `ddl/<table>.sql` 的 DISCOVERED 块。agent 读路径必经。
+- **给 DBA 执行(action)** → `pending-comments.sql`。DBA 任务队列,不在 agent 读路径上。
+
+**两张表的 DDL 文件示例**(work_order.sql):
+
+```sql
+CREATE TABLE `work_order` (
+  `id` bigint NOT NULL AUTO_INCREMENT,
+  `assignee_id` varchar(64) NOT NULL COMMENT '处理人工号',
+  `status` tinyint NOT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+-- === DISCOVERED (db-query 探索补充,非 DB 原生) ===
+-- [关系] assignee_id → users.staff_code (处理人工号,关联 users.staff_code)
+-- [字段含义] status: 0=待派单 1=处理中 2=已完成 3=已取消
+-- [陷阱] 跨 schema 查询时 schema 前缀必须显式
+-- === END DISCOVERED ===
 ```
 
-**用户工作流**:
-- 看 schema-knowledge 找现成知识 → 直接用
-- 找不到 → AI 探索(按上面优先级链)→ 写入
-- 看"待执行的 COMMENT SQL" → 复制执行到 DB → 删除已执行的部分(因为 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/db-query/agent-prompt.md

@@ -12,22 +12,21 @@
 
 | 工具 | 用途 |
 |---|---|
+| `Read docs/schema-knowledge/*/ddl/<table>.sql` | **首选**:本地知识库,含 DDL + DISCOVERED 块(团队沉淀的隐式关系/含义/陷阱/流程) |
+| `Read docs/schema-knowledge/*/INDEX.md` | 工程级表清单 + 注释,定位要读哪些表 |
 | `cgraphx db profiles` | 列已配置 profiles,确认连哪个库 |
-| `cgraphx db schema --mode tables [--profile <name>]` | 列所有表 |
-| `cgraphx db schema --mode ddl --table <name> [--profile <name>]` | 看字段、注释、外键(判断表关系的首选信息源) |
-| `cgraphx db schema --mode indexes --table <name>` | 看索引 |
-| `cgraphx db schema --mode table-comment --table <name>` | 看表注释 |
-| `cgraphx db query --sql "SELECT ... LIMIT N" [--profile <name>]` | 查样本数据(自动 LIMIT) |
-| `Read` | 读 `docs/schema-knowledge/<profile>.md` 找团队沉淀 |
+| `cgraphx db schema --mode ddl --table <name> [--profile <name>]` | **兜底**:知识库没有该表时,看字段、注释、外键 |
+| `cgraphx db schema --mode indexes --table <name>` | 看索引(知识库的 DDL 通常已含) |
+| `cgraphx db query --sql "SELECT ... LIMIT N" [--profile <name>]` | 查样本数据(只有查数据才连库) |
 
 ## 探索策略(对齐主 SKILL.md 的"陌生 schema 探索流程")
 
-1. **`cgraphx db profiles`** 确认 profile(避免连错库)
-2. 对涉及的表逐个 **`cgraphx db schema --mode ddl --table <name>`** 看字段、`comment`、`fk_table/fk_column`
-3. 看外键 + comment **推断表关系** —— 大多数情况直接能看出
-4. 不够 → `Read docs/schema-knowledge/<profile>.md` 找团队沉淀的隐式关联和业务含义
-5. **`cgraphx db query`** 只在需要看样本数据确认字段值分布时用,**LIMIT 5 够用**(大数据量让主 agent 决定)
-6. 还不够(数据库没外键、schema-knowledge 没沉淀、样本数据看不出关系)→ **在返回结论里明确告诉主 agent**:"这些表关系不明,建议问用户 X / Y",**不要反复试错查 SQL**
+1. **`Read docs/schema-knowledge/*/INDEX.md`** 找目标表所在工程目录(唯一命中直接进,多个问主 agent)
+2. 对涉及的表逐个 **`Read docs/schema-knowledge/<project>/ddl/<table>.sql`** —— DDL + DISCOVERED 块,这是首选信息源(比 DB 多团队沉淀,且不连库)
+3. 知识库没有该表文件 → **`cgraphx db schema --mode ddl --table <name>`** 兜底,看外键 + 列注释
+4. **`cgraphx db query`** 只在需要看样本数据确认字段值分布时用,**LIMIT 5 够用**(大数据量让主 agent 决定)
+5. 还不够(知识库没沉淀、DB 没外键、样本数据看不出关系)→ **在返回结论里明确告诉主 agent**:"这些表关系不明,建议问用户 X / Y",**不要反复试错查 SQL**
+6. 探索到的新关系/含义 → 在返回里建议主 agent append 到对应表的 DISCOVERED 块(格式见主 SKILL.md;**不要自己写文件**)
 
 ## 输出格式
 
@@ -50,6 +49,6 @@
 - **只读铁律,不可破** —— `cgraphx db` 子系统内置禁止 DELETE/UPDATE/INSERT/DROP/ALTER,**你也不要尝试绕过**(即使主 agent 让你写,你也拒绝)
 - **必须带 LIMIT** —— 自定义 SQL 显式 `LIMIT N`,默认 100,上限 1000
 - **陌生 schema 探索"先问后试"** —— 不确定表关系时,**在返回里建议主 agent 问用户**,**不要埋头反复试错**(试错既浪费 token,也可能拿错数据误导主 agent 判断)
-- **不要修改任何文件** —— 特别**不要修改 docs/schema-knowledge/*.md 或 .cgraphx/db-profiles.json**(变更由主 agent 决定后再走)
+- **不要修改任何文件** —— 特别**不要修改 docs/schema-knowledge/ 下任何文件 或 .cgraphx/db-profiles.json**(DISCOVERED 块的 append 由主 agent 决定后再走;你只在返回里建议)
 - **不要假设主 agent 知道你的中间步骤** —— 你的 final message 就是它看到的全部
 - **不要建议主 agent 派第二次子 agent** —— 一次没答完整就再探索几次,超出能力直接说

package/dist/.claude-template/skills/export-table-ddl/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: export-table-ddl
+description: 导出项目用到的全部数据库表的 DDL 到可检索目录(按工程分目录,每工程一个 INDEX.md 列表名+注释,details 目录放完整建表语句)。Use when 导出表结构/导出DDL/导出建表语句/拉表结构/批量查DDL/项目表清单/数据库表导出/dump schema/导出全部表.
+---
+
+## 目标
+
+把一个项目(或多个工程)用到的所有表的 `CREATE TABLE ...` DDL 拉下来,存成 AI 可检索的目录:
+
+```
+<out-dir>/
+  <工程A>/
+    INDEX.md          # 表名 + 表注释,一眼扫完
+    ddl/
+      users.sql        # 完整 DDL(含列注释/索引/外键)
+      orders.sql
+  <工程B>/
+    INDEX.md
+    ddl/
+      ...
+```
+
+AI 后续要理解某张表 → 直接 `Read ddl/<table>.sql`;要扫一个工程有哪些表 → `Read INDEX.md`。不用每次重新连库查。
+
+## 前置
+
+- `cgraphx` CLI 已装(`cgraphx db` 可用),目标项目已配 `.cgraphx/db-profiles.json` 或 `~/.cgraphx/db-profiles.json`。
+- 目标 DB profile 可连。先 `cgraphx db profiles` 确认。
+
+## 流程
+
+### 1. 确认 profile
+
+```bash
+cgraphx db profiles
+```
+
+跟用户确认连哪个 profile(避免连错库)。记下 profile 名。
+
+### 2. 识别项目用到的表名
+
+三种来源,按用户意图选:
+
+**(a) 从代码里 grep 出来**(默认,最贴"项目用到的表"):
+
+按项目主语言/框架选 grep 模式,目标是抽出所有被引用的表名,dedup 后给用户过目。
+
+通用 SQL 引用(任何语言,SQL 字符串里):
+```bash
+grep -rhoE '\b(FROM|JOIN|INTO|UPDATE|DELETE\s+FROM)\s+`?[a-zA-Z_][a-zA-Z0-9_]*`?' --include='*.sql' --include='*.xml' --include='*.java' --include='*.ts' --include='*.py' --include='*.go' \
+  | sed -E 's/^(FROM|JOIN|INTO|UPDATE|DELETE\s+FROM)\s+`?([^` ]+)`?$/\2/' \
+  | tr '[:upper:]' '[:lower:]' | sort -u
+```
+
+ORM 装饰器(按框架补):
+- JPA/Hibernate:`@Table(name\s*=\s*"([^"]+)")` / `@Entity`
+- MyBatis-Plus:`@TableName\("([^"]+)"\)`
+- SQLAlchemy:`__tablename__\s*=\s*['"]([^'"]+)['"]`
+- Django:`db_table\s*=\s*['"]([^'"]+)['"]`
+- TypeORM:`@Entity\({?\s*name:\s*['"]([^'"]+)['"]`
+
+把 SQL 引用 + ORM 声明的表名合并、dedup、过滤掉明显非真实表的(subquery 别名、`information_schema.*`、`pg_*`、`dual`、`t`/`t1`/`tmp` 这种短别名 —— 命名太短且不在 DB 表清单里的丢掉)。
+
+**(b) 用户给清单文件**(每行一个表名,或 JSON 数组)—— 用户已有列表时最省事。
+
+**(c) 全库导出**(`--tables all`)—— 不区分项目用没用,把 profile 里所有表都拉下来。适合建知识基线。
+
+把最终表清单写到一个临时文件(如 `/tmp/tables-<project>.txt`),给用户看一眼确认再进下一步。**确认前不要连库批量拉** —— 表清单错了会浪费 N 次查询。
+
+### 3. 按工程分目录(多工程项目)
+
+如果项目有多个工程(微服务 / monorepo / Maven 多模块),每个工程单独跑一次脚本,`--project <工程名>` 区分目录。
+
+工程划分来源(按可靠度排序):
+1. 用户显式指定(最可靠)—— 问用户"这些表哪些归工程 A,哪些归工程 B",或用户给每个工程的表清单文件。
+2. 代码目录结构推断 —— `packages/*/`、`services/*/`、`apps/*/` 下每个子目录一个工程;Maven 看 `*/pom.xml`;Go workspace 看 `go.work` member。推断后**给用户确认**。
+3. 不分 —— 单工程直接 `--project <项目名>` 一个目录。
+
+### 4. 批量拉 DDL
+
+对每个工程跑一次 bundled 脚本:
+
+```bash
+node <skill-dir>/scripts/export-ddl.mjs \
+  --profile <profile名> \
+  --tables <表清单文件|all> \
+  --out <输出根目录> \
+  --project <工程名>
+```
+
+脚本流程:
+1. 一次 `cgraphx db schema --mode=tables` 拿全表 + 表注释(用于 INDEX.md + 校验表是否存在)。
+2. 对清单里每张表 `cgraphx db schema --mode=ddl --table=X` 拿 DDL 文本,写到 `<out>/<project>/ddl/<table>.sql`。
+3. 生成 `<out>/<project>/INDEX.md`:markdown 表格,每行 `| 表名 | 注释 | DDL链接 | 状态 |`。
+4. stderr 报告成功/缺失/失败计数。
+
+表清单里某张表在 DB 中不存在 → INDEX.md 标"缺失",不中断其余表导出。
+
+### 5. 报告
+
+跟用户报告:
+- 每个工程导出了多少张表、输出目录路径。
+- 缺失的表(清单里有、DB 里没有)—— 可能是表名拼错、或属于另一个库,让用户决定。
+- 失败的表(连接/超时)—— 列出来,建议重跑或单独查。
+
+## INDEX.md 格式(脚本自动生成)
+
+```markdown
+# customer-svc 表清单
+
+共 42 张表(成功 40 / 缺失 2 / 失败 0),DDL 见 `ddl/` 目录。
+
+| 表名 | 注释  | 状态 |
+|---|---|---|
+| `users` | 用户资料表  | ✓ |
+| `orders` | 订单主表 | ✓ |
+| `tmp_x` | (表中不存在) | missing |
+```
+
+## 输出目录放哪
+
+放 `docs/schema-knowledge/`
+
+## 何时不该用这个 skill
+
+- 只查一两张表 → 直接 `cgraphx db schema --mode=ddl --table=X`,不用批量导出。
+- 查数据(不是结构)→ 用 `db-query` skill。
+- 表关系探索(不是导出)→ 用 `db-query` skill 的子 agent 流程。
+
+## 代价意识
+
+每张表一次 DB 连接(dbquery 子系统无连接池)。100 张表 ≈ 101 次连接(`--mode=tables` 1 次 + DDL 100 次),远程库可能几十秒。表清单越大越慢,所以**先确认表清单再批量拉**,避免拉了一堆没用的。
+
+## 闭环:和 db-query skill 配合
+
+本 skill 建**基线**(DDL + 列注释 + 表注释 + 索引,来自 DB),`db-query` skill 在日常查数据时**补充**探索发现:
+
+```
+export-table-ddl  →  docs/schema-knowledge/<project>/ddl/<table>.sql  (基线 DDL)
+       ↑                          ↑ 重 dump 保留
+       │                          │
+       └──── schema 变了重跑 ────┘
+                                  │
+db-query 探索踩坑 → append DISCOVERED 块(隐式关系/字段含义/陷阱/流程)
+```
+
+DISCOVERED 块格式(`ddl/<table>.sql` 末尾):
+
+```sql
+-- === DISCOVERED (db-query 探索补充,非 DB 原生) ===
+-- [关系] assignee_id → users.staff_code (处理人工号)
+-- [字段含义] status: 0=待派单 1=处理中 2=已完成 3=已取消
+-- [陷阱] email 不唯一,用 phone 关联更稳
+-- [流程] 派单→处理→回单:work_order.status 驱动,见 dispatch_log/receipt
+-- === END DISCOVERED ===
+```
+
+重跑本 skill 时,脚本自动保留每张表已有的 DISCOVERED 块(不会覆盖)。所以可以放心重 dump —— DB schema 变了拿新 DDL,探索积累的知识不丢。详见 `db-query` skill 的"陌生 schema 探索流程"。
+
+### 知识落在哪 —— 顺着 agent 的访问路径
+
+agent 进这个目录的访问路径固定是 `INDEX.md → ddl/<table>.sql`,**不会主动读独立笔记文件**。所以知识只能落在两个地方:
+
+- **`INDEX.md`**:工程级 meta(profile 对应哪个服务、架构一句话)。agent 进目录第一件事就是读它。
+- **`ddl/<table>.sql` 的 DISCOVERED 块**:一切表级 + 跨表知识。
+
+跨表知识塞**枢纽表**(流程主表 / 被指向最多的表 / agent 最先点名的表),关系 `A.x → B.y` 双向标注(写进 `A.sql` 和 `B.sql` 各一行)。**绝不建** `NOTES.md` / `跨表知识.md` 这类独立文件 —— 那等于把知识埋了,agent 不会主动读。详见 `db-query` skill 的"枢纽表原则"。