SuperAPI AI 工具集

absolute-docs

写作与研究

查看项目

更新于 10-26 16:21

技能介绍

Absolute Documentations 是一个基于 Diátaxis 框架的文档写作技能,旨在帮助 AI 编程智能体产出读者真正可用的文档。其核心理念是:每篇文档只服务一种读者需求,需先分类再写作,且文档中的事实必须经过代码验证。

主要能力包括三种模式:WRITE(撰写新文档)、IMPROVE(改进现有文档)、AUDIT(审计整个文档站点)。在 WRITE 模式下,流程分为五步:侦察代码库与现有文档、明确文档类型/受众/目标/范围、提出大纲并等待批准(硬性门槛)、按象限写作文档、自评并修正。IMPROVE 模式会先分类页面所属象限,再对照标准列出具体问题并重写,保留准确且项目特有的内容。AUDIT 模式会盘点所有文档页面、分类并标记混合/错放/重复/孤立页面、构建四象限差距图、输出报告与操作建议,经批准后执行重构。

该技能内置 Diátaxis 四象限分类:教程(Tutorial)、操作指南(How-to guide)、参考(Reference)、解释(Explanation)。每个象限都有明确的必须遵守和禁止事项,例如教程必须保证首次尝试成功、不提供选择;参考必须完整准确中立、不提供建议。此外,还提供开发者文档的象限组合指南,覆盖 README、CONTRIBUTING、ARCHITECTURE、ADR、CHANGELOG、Runbook、API 参考等。

使用方式上,技能会根据用户请求自动识别模式,并按照内置的指南文件(如 references/ 下的各象限手册、风格指南、文档栈检测等)执行。它支持检测常见的文档栈(Fumadocs、Docusaurus、Starlight、MkDocs、VitePress、Mintlify),并遵循对应栈的语法和组件。写作时强调准确性协议:代码片段来自代码库而非记忆、名称精确、默认值和版本从代码和清单文件读取、不文档化不存在的内容、链接可解析、输出真实。风格核心要求每句一个想法、每段一个目的、每页一个象限,使用主动语态、祈使语气,避免居高临下的词汇,标题是可扫描的声明,警告放在危险步骤之前。

适用场景包括:为项目编写新文档、修复质量不佳的 README 或页面、审计和重构整个文档站点、编写开发者文档等。限制方面:不写营销文案、博客文章或发布公告;不写内联代码注释或文档字符串;不编造功能;不执行提交,只写文件并报告,由用户审查后提交。