数据库数据字典：DDL 解析与业务语境反哺

表结构有了，含义没有

连上祖传系统的数据库，系统表里躺着几百张表。表结构是完整的：字段名、类型、约束俱全，建表脚本随时能导。缺的是含义：注释栏一半是空的，另一半写着「字段」「描述」、几个拼音缩写，或者干脆是乱码。

没有含义的表结构只有两种人能读：写它的人（通常已离职）和愿意花一周对照代码推断的人（通常没时间）。而数据字典恰恰是需求之外被查询最多的资产——写报表要对字段，改接口要对字段，数据治理更要对字段。

数据字典生成（skill5，database-dictionary）在这一步进场。它在流水线里的位置很特殊：不依赖任何上一步的产物，可以和前面七步并行跑；但它产出的注释质量，依赖前面步骤攒下的业务语境。这个特性使它成为全流水线里「复利」最明显的一步。

四种方言的注释指纹

真实的存量系统很少只是一种数据库。这一步要先认方言，再动手，四种主流方言的注释机制各不相同：

方言差异决定两件事：读取时从哪里拿列信息，回写时生成什么语法的注释脚本。给 MySQL 库生成一串 COMMENT ON 语句，脚本看着工整，执行全错。识别不靠猜，连接信息、系统表结构、建表 DDL 特征三路信号对齐了才定方言——和功能点提取的认栈逻辑同源。

五步法：从连接到回写

以 PostgreSQL 为例，标准流程五步：

flowchart TD
    A[第1步 连接库 读系统表生成 00_数据库表清单.md] --> B[第2步 表分类 - 框架表/备份表/业务表]
    B --> C[第3步 批量读取列信息 生成数据字典初稿 标记缺注释列]
    C --> D[第4步 subagent 按业务上下文精修注释]
    D --> E[第5步 生成增量注释 SQL 落 doc/sql/]

第 1 步连接 PostgreSQL，读取全部 schema 的表清单，连同表注释和表大小写进 doc/sql/00_数据库表清单.md——这份清单本身就是第一份交付物，几百张表第一次有了完整的目录。

第 2 步做表分类。框架表（sys_、gen_、qrtz_ 前缀）是底座自带的，业务价值低；备份表（_bak、_copy、带年月日后缀）是历次维护留下的快照，基本不用精修；剩下的业务表才是主战场。分类的价值是聚焦——精修的子弹不多，要打在业务表上。

第 3 步批量读取列信息，生成字典初稿，凡是缺注释的列全部打上标记。初稿是机械产物，不掺任何推断。

第 4 步是灵魂：调用子代理，把初稿和业务上下文一起给它，逐表精修注释。第 5 步把精修结果生成增量注释 SQL，供 DBA 审核后回写数据库。

注释优先级：业务语境反哺

第 4 步的精修不是让模型自由发挥，注释来源有严格的三级优先级：

业务产物排第一，这是全流水线复利的兑现时刻。前面几步辛苦攒下的资产——业务需求文档里的字段说明、链路图里的 SELECT 别名、业务规则里的约束描述——在这一步全部变成注释的依据。pbk_page 表的 ht_bh 列，命名直译只能给出「编号」，但业务需求文档里写着「合同编号，台账关联采购合同的唯一标识」，一句话让这个字段从此可读。

反过来，三级优先级也规定了不许越权：业务产物和 COMMENT 都没有的字段，不许编一个看起来合理的注释。这正是下一节的主题。

占位注释与诚实兜底

存量库里有种更迷惑的情况：注释栏不是空的，但内容是「字段」「描述」「id」「1」这类占位符。它们在语法上是合法注释，在语义上是零信息，而且会骗过简单的完整性统计——脚本一查「注释覆盖率 92%」，实际上有效覆盖率不到一半。

规则把占位注释一律视为无效，等同空白处理。真正的考验在有效来源全部落空之后：模型面前是一个谁也说不清含义的字段，写点什么好？

流水线的回答是宁缺毋假：确定不了的注释标记「待确认」，所有待确认项汇总成一份人工核实清单，随字典一起交付。虚构一个说得通的注释是零成本的，但它是负资产——下一个读者会信以为真，错误从此固化在几百份下游文档里。待确认标记看起来是缺陷，实际上是最有价值的输出之一：它把「我们不知道什么」第一次列成了清单。

注释回写：增量脚本而非直接改库

精修结果不直接 UPDATE 数据库，而是生成一份增量注释脚本，落进 doc/sql/ 目录：

-- 02_数据字典_comment.sql（增量，仅含需要修正的注释）
COMMENT ON COLUMN pbk_page.ht_bh IS '合同编号：台账关联采购合同的唯一标识';
COMMENT ON COLUMN pbk_page.ht_je IS '合同金额：含税，单位元，保留两位小数';
COMMENT ON COLUMN pbk_page.status IS '状态：0草稿/1已提交/2已审批/3已作废（待确认，来源为命名推断）';

三个设计点。增量：脚本只包含需要新增或修正的注释，已有且正确的跳过，几百张表的库里通常只有业务表的少数列需要动。方言匹配：脚本语法与第 2 步识别的方言严格对应。人工闸门：脚本交由 DBA 审核执行，AI 只负责生成，不碰生产库。

回写之后形成一个正向循环：数据库里的注释从零散变完整，下一个新来的开发者打开表结构就能读懂，而不再需要跑一遍逆向流水线。逆向的成果沉淀回了逆向的起点。

几百张表的并行精修

单库几百张表、每张几十个字段，第 4 步的精修量轻松超过十万字段描述，串行跑不完。实际执行用的是一套分组并行的流水线：

flowchart TD
    A[自定义规则分类 - 排除框架表备份表] --> B[按表名前缀分组 每组约 50 张表]
    B --> C[分批调用 subagent 每批多组并行]
    C --> D[每组输出独立 _result_组名.md 文件]
    D --> E[主代理完整性核对 - 结果文件数与分组数比对]
    E -->|缺组| F[重新分派缺失的组]
    E -->|齐全| G[合并生成最终数据字典]

四个细节决定了这套方案的稳定性。分组粒度取每组约 50 张表，子代理单次任务的上下文和输出长度都落在安全区。每组输出独立的 _result_<组名>.md 文件，多个子代理绝不写同一个文件，从物理上消灭写冲突。主代理做完整性核对，结果文件数必须等于分组数，缺哪组补哪组。最后由主代理合并，合并时逐组检查格式一致性，任何一组格式漂移都会污染整本字典。

这套分治结构不是数据字典独有的，子代理并行一篇把它作为通用模式完整展开。

数据库资产的复利

数据字典是整条流水线里受益最晚、收益最持久的一步。它起步时并行于所有步骤，结束时却消费了全部前序产物；它产出的注释回写数据库后，又成为后续一切开发工作的基础设施。逆向流水线在数据库这一层完成了闭环：业务语境从代码流向数据结构，数据结构从此带着业务含义服务下一代开发者。

到这里，七个逆向 skill 全部讲完。下一步是把它们串起来的那套协议：AI Agent 流水线的编排协议设计——互不相识的 skill 靠什么协作。