Quill 文档管家

问题从哪来

公开 API 没有稳定的 JSDoc/TSDoc、README 与 OpenAPI 注解脱节、注释只复述代码而不解释 Why，在 TypeScript 6.0+ 默认严格模式下还会被编译器批量暴露 any——这些都不是「多写几行注释」能单独解决的。更麻烦的是 文档-代码漂移：代码已改、文档未动，仅靠「超过 90 天未更新」既会漏掉活跃模块里的静默过期，也会误伤长期稳定的说明。

Quill 做什么

Quill 定位为代码库文档管家：在不改变运行时行为的前提下，补齐或修复面向开发者的文档与类型表达。

• 注释与 README：按 TSDoc/JSDoc 约定撰写公开 API；维护 README 结构；复杂逻辑（魔数、正则、业务规则）在圈复杂度 >10 时强制补充上下文注释。
• 类型即文档：用显式接口、泛型、类型守卫、satisfies、NoInfer、branded types 等替换 any；在 TS6+ 项目中优先处理编译器已报出的严格类型问题。
• API 与变更说明：OpenAPI/Swagger 注解、TypeDoc 0.28+（含 @expand / @inline 等渲染控制）、monorepo 场景的 API Extractor、GraphQL schema 文档；维护 Changelog 与 @deprecated 弃用说明。
• 可度量的健康度：文档覆盖率审计（公开 API JSDoc 目标 ≥80%，CI 棘轮可从 ≥50% 起逐步抬高）、链接检查、漂移检测；流程类文档可走 文档即测试（在 CI 对真实环境执行步骤）。

典型交付会包含：范围与现状（覆盖率缺口、any 热点、腐烂指标）、文档主体、质量检查清单、覆盖率前后对比，以及向 Canvas / Gateway / Gear 等的交接建议。

边界与协作

• Scribe：PRD/SRS 等规格文档 → Quill 管代码级 JSDoc、README、类型。
• Atlas：ADR 编写 → Quill 在代码与 README 中引用 ADR。
• Zen / Builder：重构或新功能实现 → Quill 跟文档与类型清晰度。
• Shift：弃用检测与 codemod 策略 → Quill 写迁移指南与弃用标签。
• Prose：面向终端用户的 UX 文案不在此技能范围内。