database-documentation 是一个用于生成数据库文档的技能，其目标是让文档「本身就是可证实的模式」，而不是看起来合理的猜测。它强调一个原则：所有输出都必须既 grounded（可追溯到具体来源，优先以在线数据库的系统目录内省为准）又 verified（通过重新内省在线数据库并与生成的文档做差异比对来确认）。
用途与定位
该技能解决的问题是：一个模型如果自行阅读 ORM 并写出自信的散文式文档，往往会遗漏检查约束枚举、写错 ON DELETE、漏掉遗留表或凭空编造字段，产出一份不完整且部分幻觉的模式文档。半正确的模式文档比没有更糟，因为人们会信任它并据此写出错误的代码。该技能通过两个机制来应对：以在线数据库为准绳，以及通过独立的对抗性审查来避免单一模型的判断盲区。
适用范围（v1）
仅限关系型/SQL 数据库。目标引擎为 PostgreSQL、MySQL、SQL Server、SQLite。如果检测到文档存储（如 MongoDB）或图数据库，应声明并停止，不为该存储生成关系型文档，并将其标记为超出范围，而不是猜测。
核心工作流
工作流按顺序执行若干阶段，每个阶段都有明确的产出物。所有中间产物（中间抽取结果、工作用 CSM）保留在单一的 .database-documentation/ 临时目录或平台暂存区中；唯一的持久交付物是文档和 schema.json。
阶段 0 — 发现（只读）：识别引擎与版本以及 ORM（如 schema.prisma、.entity.ts + datasource、drizzle.config.、knexfile.* + migrations/、Django models.py、Rails schema.rb、原始 SQL DDL 等）。从 datasource/provider、docker-compose.yml 镜像标签、.env* 中的连接 URL 确定引擎与版本。按优先级查找在线数据库的可达路径：已连接的 DB MCP 服务器 → docker compose exec / docker exec 进入数据库容器 → 本地数据库 CLI（psql/mysql/sqlcmd/sqlite3）连接 .env 中的 host:port。在继续之前用一条简单查询（SELECT 1、列出表）验证连通性。如果数据库未运行但 compose 文件定义了它，可以提议启动它。绝不打印凭据：从 .env/compose 读取的密码/DSN 视为机密，仅保留在执行命令中，在展示或写入文档时脱敏为 password=**。同时盘点其他表面：迁移目录（及数量）、生成的 client/.d.ts、种子/夹具，并 grep 应用中的原始 SQL/查询构建器调用。记录已有的 docs/db/，如果存在则视为刷新：加载它以比对漂移并匹配既有风格。公布达到的可信度等级。
阶段 1 — 抽取每个表面（可并行）：将每个可用表面独立抽取为规范模式模型（CSM）形状。在有子智能体的平台上，每个表面运行一个抽取器并行执行，且不让它们看到彼此的输出，因为独立一致才是真实证据，共享上下文会导致群体思维。对象类清单要求抽取每一类：表、列（类型+可空+默认值+注释）、主键、外键（+ON DELETE/UPDATE）、唯一约束、检查约束、索引（+部分/表达式）、枚举（+值）、序列、触发器、视图（+定义）、例程（函数/过程）。序列、触发器和例程常因不是列而被遗忘，需要显式抽取。视图/触发器/例程体需完整逐字捕获，绝不用省略号缩写或概括。schema.json.enums 仅记录数据库原生枚举类型；带 CHECK (col IN (...)) 的字符串列归入该表的 check_constraints，应用层值集则标注为「app-enforced」。将在线的内省视为权威，自行编写并运行内省查询，不调用任何基准/测试脚本。ORM 模型映射为 CSM（意图+描述）；迁移按时间顺序折叠以重建最终状态；生成的类型/种子/应用查询用于佐证，应用查询扫描可发现 ORM 中缺失但被使用的遗留表和列。
阶段 2 — 统一为一个 CSM（优先级+漂移）：以物理数据库名为主键合并为母版 CSM。优先级规则：存在在线数据库时它全权胜出，任何不一致的表面产生漂移发现（记录在 issues/ 中），绝不静默修改文档。没有在线数据库时，采用迁移 ⊕ ORM 的共识（迁移胜出结构，ORM 胜出意图），并标记冲突。为每个对象标记可信度：verified（在线确认）/ consensus / single-source / conflict。有在线数据库时，用两种方法（如 information_schema 与 pg_catalog）交叉校验它自身，确保准绳在推翻其他表面之前先自洽。
阶段 3 — 生成文档 + schema.json：所有输出写入一个专门的文档目录，默认 docs/db/；如果阶段 0 发现已有数据库文档目录则写入那里以匹配既有风格。按模板渲染 CSM：约 15 张表以下输出单个 docs/db/DATABASE.md（统计头部、一个 mermaid ERD、每表分节、一个 Issues 分节）；更大规模则在 docs/db/ 下输出 README.md（索引+统计）+ ONBOARDING.md + 按域划分的 diagrams/<domain>.md + diagrams/full-erd.md（仅表级）+ tables/entity-reference.md + issues/README.md。schema.json 输出到同一目录。每表分节包含 1–2 句基于证据的描述、一个 Column | Type | Nullable | Default | Description 表格，然后是 Indexes: 和 Foreign Keys:（含 ON DELETE）。按 ORM 模块/文件夹 → 名称前缀 → 外键聚簇划分域，并设 Legacy/Misc 兜底分类。
阶段 4 — 证明一致性（验证的一半）：这不是可选项，也不靠感觉。计数门禁要求对每个对象类在在线数据库中计数并与 schema.json 中的计数比较，计数查询必须选择与抽取和 CSM 定义的完全相同的总体（索引排除主键/唯一约束支撑的那些，例程/对象排除扩展拥有的那些）。打印 class | live | documented | match? 表格。计数匹配是必要但不充分的（相等计数会掩盖类型互换或 ON DELETE 错误）。身份差异比对是真正的证明：重新内省并对每个类的身份和属性做差异比对（表、列、主键、外键+on_delete、唯一、检查、索引+部分/表达式、枚举+值、视图、触发器、例程、序列）。对每个差异要么修复文档，要么给出理由。重复直到计数表匹配且身份差异为空或完全有理由。编写一致性报告，包含各类计数表和明确的「0 undocumented, 0 invented」。只有在身份差异为空时才写「verified」，不能仅凭计数匹配。没有在线数据库时，对共识 CSM 做差异比对，并将每个输出文件标注为「consensus parity (UNVERIFIED against live DB)」。
阶段 5 — 对抗性审查（至少 3 个独立审查者，绝不只有 1 个）：因为评审的智能体本身也是有同样盲区的前沿模型，单一审查会沦为橡皮图章。需要召集至少 3 个上下文隔离的对抗者，各自在独立会话中带着「必须找出错误」的使命和不同视角：遗漏猎手（抽样在线表，检查每个表是否都在且列齐全，遗留表、每个枚举/检查、每个索引和外键是否都有文档）、幻觉猎手（每个文档化的对象/类型/默认值/ON DELETE/描述是否可追溯到真实来源，标记任何编造内容）、正确性猎手（类型、可空性和外键基数是否与在线数据库完全一致）。三者的并集反馈给下一轮生成。凡是需要判断的地方，都由小组决定。
降级阶梯与可信度
技能定义了五个层级：T1 有在线数据库+并行子智能体+对抗者 = verified, provable；T2 有在线数据库、单智能体 = verified, sequential；T3 无在线数据库、有子智能体 = consensus, unverified；T4 无在线数据库、单智能体 = consensus, unverified；T5 仅一个静态表面 = low，需显著标注「UNVERIFIED — no live DB」横幅。子智能体、MCP 和 docker 都只是优化手段，绝非必需，没有它们也能内联运行同样的阶段。绝不编造无法读取的数据：缺失会被标记，而不是猜测。
参考文件
技能附带若干参考文件：references/csm-contract.md 定义 schema.json 形状（可验证的输出契约）；references/introspection-postgres.md 提供各引擎的确切目录查询；references/output-template.md 提供要复现的人类可读文档形状；references/hard-cases.md 覆盖枚举（原生/CHECK/应用）、JSON 列、多态关系、软删除、复合键、部分/表达式索引、视图、多 schema、citext/排序规则、遗留表等难点。