阿拉丁技术文档工坊

先承认问题：文档总是最后一个没人管的环节

你可能已经用 aladin-code-pilot 审完了函数、用 api-pilot 验过了接口、用 diagram-forge 画完了结构图、用 cicd-forge 把服务推上了线——然后对着仓库里那个永远停在 # TODO 的 README 发呆。API 只有写代码的人自己看得懂，架构图只存在于脑子里，CHANGELOG 全靠回忆。skillhub 上能找到的文档类技能全是单点：要么只写前端编码规范，要么只给某个产品做导航文档，要么干脆是办公标书生成器，没有一条工具链能把“代码 → 可执行技术文档”这件事工程化地走完。

它怎么工作：从代码到文档的收口

这个技能把整套流程做成零依赖的纯本地脚本，核心思路是先归一、再生成、最后校验：

• 仓库扫描归一：doc_ingest.py 扫描代码目录（py/js/ts/go/java/rust），抽取语言、包结构、导出符号、类继承、函数签名、路由装饰器，产出统一的中间表示 code_ir.json
• 四类文档生成：从 IR 填充 README（结构/模块/注释状态）、从 OpenAPI 规格或路由装饰器生成 API 文档、联动 diagram-forge 产物生成架构说明、基于 git log 生成 Keep-a-Changelog 格式的 CHANGELOG
• docstring 补全建议：基于语义为缺注释的符号生成补全草案清单，只给建议、不碰源码
• 文档质量校验：提交前先跑一遍注释覆盖率、TODO/FIXME 残留和 Markdown 死链检查，产出 quality.json 报告
• 多格式导出：Markdown、自包含 HTML 文档站、reStructuredText、DocFX，全部是纯文本产物，可进版控、可二次编辑

整个工作流只需要 3 步：扫描归一 → 生成文档 → 校验导出。所有产物都是本地文件，不发起任何网络请求。

适用边界与注意点

能用的前提和它明确不做的事同样重要：

• 只处理本地仓库或 IR，不实时抓取外部文档站，也不出网
• 只产文档不改码：docstring 只是建议清单，绝不自动覆写你的源码
• 校验是静态结构级（覆盖率/死链/关键字），不评估文档“写得好不好”
• 不替代 Swagger UI、ReadTheDocs 这类托管平台，只产静态文件
• 文档严格基于扫描出的真实结构，没有代码依据的内容不会臆造

它适合想在提交前把技术文档这件事一次性做扎实的工程师，而不是需要写 PRD 或标书的人。