cgraphx 1.3.1 → 1.4.0

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,54 @@ 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. 探索完成(用户告知或谨慎试错得到结论)后,沉淀到 per-table DDL 文件:
+   a. 定位文件 docs/schema-knowledge/<project>/ddl/<table>.sql(不存在 → 先跑 export-table-ddl 建基线)
+   b. append 到文件末尾的 DISCOVERED 块(格式见下)
+   c. 若是 DB 注释缺失导致的含义不明 → 另生成 COMMENT SQL 提示用户执行(执行后 DB 注释固化,DISCOVERED 块里那条可删)
 ```
 
-**长期目标**:DB 注释逐渐健全(用户/DBA 执行了 COMMENT SQL)后,`schema --mode ddl` 直接返回业务含义,**schema-knowledge 退役**。DB 自带注释是单一事实源,任何工具/任何人查 DDL 都受益。
+**长期目标**:DB 注释逐渐健全(用户/DBA 执行了 COMMENT SQL)后,`schema --mode ddl` 直接返回业务含义,DISCOVERED 块逐渐退役。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 进目录第一件事就是读它),但不要沉淀到表级以下的独立文件。
 
 ## 何时派子 agent(让上下文更干净)
 
@@ -88,7 +116,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 +140,40 @@ profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数
 - **派的代价**:子 agent 本身耗 token,简单查询派反而更贵
 - **R4 是平衡点**:只在"模糊意图 + 主 agent 无法精确判断目标"时派
 
-## schema-knowledge 文件结构
-
-每个 profile 一个 markdown 文件:`docs/schema-knowledge/<profile>.md`(项目业务数据目录,跨工具版本保留,不会被 cgraphx 升级覆盖)
-
-```markdown
-# <profile> schema knowledge
-
-## 表关系(DB 未定义 FK 的隐式关联)
-- `work_order.assignee_id` → `users.staff_code`(处理人)
-- `payment.order_id` → `work_order.id`(订单的支付记录)
+## schema-knowledge 目录结构(由 export-table-ddl 建基线,db-query 探索补充)
 
-## 关键字段业务含义(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          # 表名 + 表注释,一眼扫完
+    ddl/
+      users.sql        # 完整 DDL + 末尾 DISCOVERED 块(db-query 探索补充)
+      work_order.sql
+  <工程B>/
+    ...
+```
 
-## 已知陷阱
-- `users.email` 不是唯一(同 email 多账号)—— 用 `users.phone` 关联更稳
-- 跨 schema 查询时 schema 前缀必须显式(如 `tenant.users`)
+**两张表的 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 块)
+2. 日常 `db-query` 查数据踩坑 → 发现隐式关系/含义/陷阱 → append 到对应 `ddl/<table>.sql` 的 DISCOVERED 块
+3. 重跑 `export-table-ddl`(schema 变了)→ DISCOVERED 块保留,新 DDL 接上
+4. DB 注释健全后 → 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 的"枢纽表原则"。

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

@@ -0,0 +1,163 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<title>db schema skills 闭环</title>
+<style>
+  :root {
+    --green: #16a34a;  /* 本地知识库(便宜) */
+    --green-bg: #dcfce7;
+    --blue: #2563eb;   /* DB 连接(贵) */
+    --blue-bg: #dbeafe;
+    --orange: #ea580c; /* 探索补充 */
+    --orange-bg: #ffedd5;
+    --red: #dc2626;
+    --gray: #6b7280;
+    --gray-bg: #f3f4f6;
+    --border: #d1d5db;
+  }
+  * { box-sizing: border-box; }
+  body {
+    font-family: -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif;
+    max-width: 1100px; margin: 0 auto; padding: 32px 24px 80px;
+    color: #111827; line-height: 1.6;
+  }
+  h1 { font-size: 28px; margin: 0 0 8px; }
+  h2 { font-size: 20px; margin: 40px 0 12px; border-bottom: 2px solid var(--border); padding-bottom: 6px; }
+  h3 { font-size: 15px; margin: 20px 0 8px; color: var(--gray); font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; }
+  .subtitle { color: var(--gray); font-size: 15px; margin-bottom: 32px; }
+  .tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 12px; font-weight: 600; margin-right: 6px; }
+  .tag-green { background: var(--green-bg); color: var(--green); }
+  .tag-blue { background: var(--blue-bg); color: var(--blue); }
+  .tag-orange { background: var(--orange-bg); color: var(--orange); }
+
+  /* 角色卡 */
+  .roles { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin: 16px 0; }
+  .role-card { border: 1px solid var(--border); border-radius: 8px; padding: 16px 20px; }
+  .role-card.init { border-left: 4px solid var(--blue); background: var(--blue-bg); }
+  .role-card.daily { border-left: 4px solid var(--green); background: var(--green-bg); }
+  .role-card h3 { margin: 0 0 8px; color: inherit; text-transform: none; letter-spacing: 0; font-size: 16px; }
+  .role-card .when { font-size: 13px; color: var(--gray); margin-top: 8px; }
+
+  /* 目录树 */
+  .tree {
+    background: var(--gray-bg); border: 1px solid var(--border); border-radius: 8px;
+    padding: 16px 20px; font-family: "SF Mono", Menlo, monospace; font-size: 13px; line-height: 1.8;
+    margin: 12px 0; white-space: pre;
+  }
+  .tree .hl { background: var(--green-bg); padding: 1px 4px; border-radius: 3px; color: var(--green); font-weight: 600; }
+  .tree .hlo { background: var(--orange-bg); padding: 1px 4px; border-radius: 3px; color: var(--orange); font-weight: 600; }
+
+  /* 数据流图 */
+  .flow {
+    display: grid; grid-template-columns: 1fr auto 1fr; gap: 12px 8px; align-items: center;
+    margin: 16px 0;
+  }
+  .box {
+    border: 2px solid var(--border); border-radius: 8px; padding: 12px 16px; text-align: center;
+    background: white;
+  }
+  .box.db { border-color: var(--blue); background: var(--blue-bg); }
+  .box.kb { border-color: var(--green); background: var(--green-bg); }
+  .box.agent { border-color: var(--gray); background: var(--gray-bg); }
+  .box .label { font-weight: 600; font-size: 14px; }
+  .box .sub { font-size: 12px; color: var(--gray); margin-top: 4px; }
+  .arrow {
+    text-align: center; font-size: 24px; color: var(--gray); font-weight: bold;
+    position: relative;
+  }
+  .arrow .a-label {
+    position: absolute; top: -8px; left: 50%; transform: translateX(-50%);
+    font-size: 11px; white-space: nowrap; background: white; padding: 0 4px; color: var(--gray);
+  }
+  .arrow.green { color: var(--green); }
+  .arrow.blue { color: var(--blue); }
+  .arrow.orange { color: var(--orange); }
+  .arrow-row { display: contents; }
+
+  /* 时序 */
+  .timeline { position: relative; padding-left: 24px; margin: 16px 0; }
+  .timeline::before { content: ''; position: absolute; left: 8px; top: 8px; bottom: 8px; width: 2px; background: var(--border); }
+  .tl-item { position: relative; padding: 8px 0 16px 24px; }
+  .tl-item::before {
+    content: ''; position: absolute; left: -20px; top: 14px; width: 12px; height: 12px;
+    border-radius: 50%; background: white; border: 2px solid var(--gray);
+  }
+  .tl-item.init::before { border-color: var(--blue); background: var(--blue); }
+  .tl-item.read::before { border-color: var(--green); background: var(--green); }
+  .tl-item.write::before { border-color: var(--orange); background: var(--orange); }
+  .tl-item .tl-title { font-weight: 600; }
+  .tl-item .tl-body { font-size: 14px; color: var(--gray); margin-top: 2px; }
+  .tl-item code { background: var(--gray-bg); padding: 1px 5px; border-radius: 3px; font-size: 12px; }
+
+  /* 枢纽表对比 */
+  .compare { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin: 16px 0; }
+  .compare-card { border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
+  .compare-card.bad { border-color: var(--red); background: #fef2f2; }
+  .compare-card.good { border-color: var(--green); background: var(--green-bg); }
+  .compare-card .head { font-weight: 600; margin-bottom: 8px; }
+  .compare-card.bad .head::before { content: "✗ "; color: var(--red); font-weight: bold; }
+  .compare-card.good .head::before { content: "✓ "; color: var(--green); font-weight: bold; }
+
+  /* 规则卡 */
+  .rules { display: grid; gap: 10px; margin: 16px 0; }
+  .rule { display: flex; gap: 12px; padding: 12px 16px; border-left: 3px solid var(--green); background: var(--gray-bg); border-radius: 4px; }
+  .rule .num { font-weight: 700; color: var(--green); font-size: 18px; flex-shrink: 0; }
+  .rule .body { font-size: 14px; }
+  .rule .body b { color: #111827; }
+
+  code { font-family: "SF Mono", Menlo, monospace; }
+  .footer { margin-top: 60px; padding-top: 16px; border-top: 1px solid var(--border); color: var(--gray); font-size: 12px; }
+</style>
+</head>
+<body>
+
+<h1>db schema skills 闭环</h1>
+<p class="subtitle">两个 skill + 一个共享知识库,让 agent 越用越懂业务数据</p>
+
+<h2>1. 共享的目录结构(知识库本体)</h2>
+<div class="tree">docs/schema-knowledge/
+├── order-svc/
+│   ├── <span class="hl">INDEX.md</span>                  ← agent 进目录第一件事读(表清单+注释)
+│   └── ddl/
+│       ├── work_order.sql    ← DDL + <span class="hlo">DISCOVERED 块</span>(积累的隐式关系/含义/陷阱)
+│       ├── users.sql         ← DDL + DISCOVERED 块
+│       └── payment.sql
+└── cust-svc/
+    ├── INDEX.md
+    └── 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 时会保留。
+</p>
+
+<h2>2. 时序:知识怎么积累起来</h2>
+<div class="timeline">
+  <div class="tl-item init">
+    <div class="tl-title">T0 · 跑 export-table-ddl</div>
+    <div class="tl-body">建基线 → <code>ddl/work_order.sql</code> 只有 DDL,无 DISCOVERED 块</div>
+  </div>
+  <div class="tl-item read">
+    <div class="tl-title">T1 · db-query 任务:"查 work_order 待派单的数据"</div>
+    <div class="tl-body"><code>Read ddl/work_order.sql</code>(首选)→ <code>cgraphx db query --sql "SELECT ... LIMIT 5"</code>(查数据)</div>
+  </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>
+  <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>
+  <div class="tl-item read">
+    <div class="tl-title">T3 · 下一次 db-query 读 work_order</div>
+    <div class="tl-body"><code>Read ddl/work_order.sql</code> → 看到 DDL + DISCOVERED 块(<b>积累生效,不用重新踩坑</b>)</div>
+  </div>
+</div>
+
+<div class="footer">
+  闭环核心:知识库是 <b style="color:var(--green)">便宜 + 丰富</b> 的首选信息源(本地读 + DISCOVERED 块),DB 是 <b style="color:var(--blue)">昂贵 + 不可替代</b> 的兜底(连库 + 只读铁律)。agent 默认走知识库,只在"知识库没有"或"要实际数据"时连库 —— 这样新沉淀的知识才会被读到,闭环才转得起来。
+</div>
+
+</body>
+</html>

package/dist/.claude-template/skills/export-table-ddl/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "skill_name": "export-table-ddl",
+  "evals": [
+    {
+      "id": 1,
+      "name": "single-project-from-code",
+      "prompt": "我在做一个客户管理服务的代码理解,项目根目录在 ~/work/customer-svc,用 zqassis 这个 pg profile。帮我把这个项目用到的所有表的 DDL 导出来,放到 docs/schema-dump/ 下,工程名就叫 customer-svc。表名从代码里 grep 出来就行,导出前先给我看一眼表清单确认。",
+      "expected_output": "docs/schema-dump/customer-svc/INDEX.md + ddl/*.sql;INDEX.md 列出所有表名+注释;导出前用户确认过表清单",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "multi-project-monorepo",
+      "prompt": "我们的 monorepo 在 ~/work/platform,下面 services/order-svc 和 services/cust-svc 两个工程,各自有自己的表。用 xw-order 和 xw-cust 两个 mysql profile 分别导出(每个工程对应一个 profile),放到 docs/schema-dump/ 下按工程分目录。表清单用全库导出(--tables all)。",
+      "expected_output": "docs/schema-dump/order-svc/ + docs/schema-dump/cust-svc/,各自 INDEX.md + ddl/,两个工程用了各自的 profile",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "user-provided-table-list",
+      "prompt": "我有一个表清单文件 /tmp/核心表.txt,每行一个表名,大概 30 张表。用 zqassis profile 导出到 docs/schema-dump/core/ 下,工程名 core。直接导出不用让我确认表清单了。",
+      "expected_output": "docs/schema-dump/core/INDEX.md + ddl/*.sql;跳过表清单确认步骤直接导出;清单里不存在于 DB 的表在 INDEX 里标 missing",
+      "files": []
+    }
+  ]
+}