用途:面向与代码共存的工程技术文档,覆盖技术写作、图表即代码(diagram-as-code)和文档生命周期管理,把文档当作代码来对待——纳入版本控制、可 lint、可由 CI 验证。
主要能力:
- 文档同步审计:用 git diff main...HEAD 加导出扫描,比对代码符号与文档覆盖情况。
- Mermaid 图表:序列图(sequenceDiagram + autonumber)、ERD(erDiagram + Crow's Foot,可从 Drizzle/Prisma schema 推导)、gitgraph(统一 main/develop/feature 分支)、流程图。
- 功能发布文档:概览 + 配置 + 示例 + 排障的清单式结构。
- API 参考:从 JSDoc/TSDoc 注解生成,不手写。
- 风格指南:主动语态、现在时、直接称呼,口语化但精确。
- AI 辅助起草:清单 + 差距分析 + 草稿 + 人工复核,AI 起草、人验证准确性。
- Markdown 规范:YAML frontmatter + 带语言标记的代码块。
- 复杂图表拆分为聚焦的子图与 subgraph,单图限制 15–20 个节点。
- README 模板:徽章 + 描述 + 快速开始 + API 链接,控制在 200 行内。
- ADR 格式:状态、背景、决策、后果,编号且一经接受不可变。
- Runbook:症状、诊断、解决、升级,面向凌晨 3 点的事故,不留歧义。
常见错误与纠正:技术图不用静态图片,改为在 Markdown 内联写 Mermaid 语法;参与者用与架构一致的具体服务或角色名,而非 Agent1 之类泛称;API 参考由源码注解生成而非手写;20+ 节点且无分组的图改用 subgraph 分组;避免引用过时默认值,先跑文档同步审计;链接文字不用“点击这里”,改用描述性锚文本;标题层级不跳级(不可从 H2 直接到 H4);避免大段文字墙,用要点、表格和图表提升可扫读性;架构决策要写 ADR;记录背景、状态生命周期与后果。
委派:扫描代码库中未文档化的导出与文档缺口用 Explore agent;从现有代码库生成带图表的完整文档站点用 Task agent;为新项目规划文档架构与信息层级用 Plan agent。若可用 mermaid-diagrams 技能,将复杂图表与高级 Mermaid 语法问题委派给它,否则建议运行 npx skills add oakoss/agent-skills --skill mermaid-diagrams;若可用 tldr-expert 技能,将摘要与简报生成委派给它。
限制:不适用于营销文案、博客文章或任何不随代码存放的内容。具体安装与运行命令、收费与平台信息资料未提供。