数据库1600张表的文档，我让AI自动维护了

上周接手一个老项目，打开数据库一看——1613张表，42380个字段，1765个索引。

我看了一眼那个旧版Excel文档，最后更新日期停在两年前。里面少了一百多张表，字段注释大面积缺失，有些表的列名跟数据库里根本对不上。

长痛不如短痛，于是我决定对这文档下手了。把旧文档中表的字段、类型、注释重新整理，方便自己也方便同事。

程序员都懂这种活：写代码的时候意气风发，改完表结构顺手就把文档给忘了。不是不想写，是真的顾不上。需求一个接一个，谁能记得每次改完表还要去同步Excel？

一、1600张表，手动整理？

先算笔账。1613张表，每张表平均26个字段，手动复制粘贴到Excel，一张表至少3分钟。1600张表就是80个小时——整整两周不干别的，光整理文档。

而且这只是第一次。以后每次数据库变更，都要手动对比哪里改了、更新文档、标注新增字段。这件事只要靠人，就一定会遗漏。

我决定写一个脚本，连库自动提取元数据，直接生成格式化的Excel文档。后来发现这个需求太通用了——每个接手老项目的程序员都遇到过。干脆做成一个Skill，以后任何数据库都能一键生成。

二、自动生成Excel文档

核心思路很简单：连数据库 → 提取表结构元数据 → 生成格式化Excel。

但真做起来，细节不少。

四种模板风格

不同团队审美不一样，做了四种模板：经典商务蓝、极简线条、深灰紧凑、清新绿白。模板用JSON配置，想加新风格丢个文件进去就行。

① 模板A

②模板B

③模板C

④ 模板D

30秒，1613张表全部生成。标题行、表信息、字段明细、列宽、边框、冻结行——全自动。

对比旧文档，自动标注新增

这个功能是真正解决痛点的。传入旧文档路径，脚本会自动对比：

• 新增的表：蓝色标注，归入"未分类"组
• 新增的字段：蓝色高亮该行
• 类型变更的字段：橙色标注类型列
• 旧文档中的中文注释：自动合并保留

这样每次数据库变更后，跑一次命令就能看到哪些是新增的，哪些改了类型。不用肉眼对比。

核心痛点解决：从"手动整理80小时"变成"一条命令30秒"。而且每次变更都有视觉标注，不会再遗漏。

三、同步到飞书：电子表格方案

Excel生成好了，但团队协作场景下，Excel文件传来传去太低效。需求方提出：能不能同步到飞书，在线查看？

最终采用了飞书电子表格（Sheets）方案：每张表一个独立 Sheet，完全复刻 Excel 的格式和样式。

目录Sheet里每张表的名称是超链接，点击直接跳转到对应Sheet。Sheet底部标签显示中文表名（优先用数据库注释，没有注释才用英文表名）。

每张表的Sheet格式跟Excel一模一样：标题行、表信息、描述、数据组成、字段表头、字段数据，冻结前7行，列宽已调整。数量超过单个电子表格上限时，自动拆分创建新的电子表格。

协作痛点解决：从"Excel文件传来传去"变成"飞书在线查看，点击跳转"。目录Sheet带超链接，中文标签一目了然。

四、定时自动化：凌晨两点自动同步

文档生成好了，飞书也同步了。但还有一个问题：每次数据库变更都要手动跑命令。

如果忘了跑呢？文档又过时了。

所以用 WorkBuddy 的自动化任务配置了一条定时流程：每天凌晨 2:00 自动检测数据库变更，有变更则重建飞书电子表格，同步成功才更新基线；失败则保留旧基线，下次自动重试。

当然了其他的AI Agent也是一样的设置自动化任务就行

差异报告包含：新增表、删除表、新增字段、删除字段、类型变更、索引变更、注释变更。

关键设计：基线只在同步成功后才更新。这样即使同步失败，变更也不会丢失，下次运行会重新检测到。

维护痛点解决：从"每次变更手动跑命令"变成"每天凌晨自动检测+同步"。失败了自动重试，基线不会丢。

五、这个 Skill 怎么用

在 WorkBuddy 中安装 db-doc-generator Skill 后，核心就是三条命令：

# 1. 生成 Excel 表结构文档
python generate_doc.py \
    --conn "oracle://user/pass@host:1521/service" \
    -o 表结构文档.xlsx

# 2. 对比旧文档，自动标注变更
python generate_doc.py \
    --conn "oracle://user/pass@host:1521/service" \
    -d 旧版文档.xlsx \
    -o 新版文档.xlsx

# 3. 同步到飞书电子表格
python sync_sheet_to_feishu.py --initial

然后配置一个 WorkBuddy 、Claude code、Codex 自动化任务：

• 频率：每天 02:00
• 流程：检测变更 → 重建飞书电子表格 → 更新基线
• 兜底：同步失败不更新基线，下次自动重试

之后就可以每天自动同步，人工只需要处理变更内容本身，文档永远是最新的。

六、总结

整个流程做下来，其实就解决了三个问题：

痛点	之前	之后
文档生成	手动整理，80小时	一条命令，30秒
协作查看	Excel文件传来传去	飞书在线，点击跳转
持续维护	靠人记得更新	每天凌晨自动同步

程序员不是不想写文档，是手动维护文档的成本太高。当你把这个成本降到接近零，文档更新就变成一件自然而然的事。

这个Skill支持Oracle、MySQL、PostgreSQL、SQLite四种数据库，内置4种Excel模板，支持飞书电子表格同步和定时自动化。以后接手任何老项目，连上数据库，一条命令搞定。

skill地址：

• GitHub: https://github.com/xiezhr/xiaofan-skills
• Gitee: https://gitee.com/xiezhr/xiaofan-skills