SuperAPI AI 工具集

diataxis

通用与其它

查看项目

更新于 10-15 23:24

技能介绍

用途:帮助按 Diataxis 框架组织与维护项目技术文档,把内容按用户需求分为四类:教程(学习导向,带领初学者动手)、操作指南(任务导向,解决具体目标)、解释(理解导向,讨论背景与取舍)、参考(信息导向,精确描述 API、配置、CLI 等)。

主要能力:发现并读取 docs/、doc/、documentation/ 目录及 README.md、CONTRIBUTING.md、CHANGELOG.md 等文件,识别 mkdocs.yml、docusaurus.config.js、conf.py、antora.yml、hugo.toml 等文档配置;用“行动/认知”“获取/应用”两轴对页面分类,输出文件—当前分类—建议分类—备注的表格;检查 git 历史中是否有刻意重分类的提交,避免覆盖既有决定;识别混合内容并建议拆分;提出符合 Diataxis 的目录结构(tutorials、how-to、explanation、reference)并适配现有工具与命名惯例;列出文档缺口;在用户批准后移动文件、更新内部链接与导航配置,或按四类模板创建新页面。

使用方式:先扫描现有文档,若不存在则提示从零搭建;再分类现有页面并展示结果;然后提出结构与缺口;任何改动前必须征求用户同意,获批后才执行移动、创建或修改。分类不确定时用两轴问题判断,格式而非主题决定分类,例如排查步骤表属于参考,诊断流程属于操作指南。

限制:Diataxis 只促进质量,不保证准确性、完整性与写作水平;不强制套用该框架,小型项目若单 README 已足够可维持现状;重构时不删除内容,只移动重组;需尊重用户对分类与结构的最终决定。具体命令与配置细节以资料为准,未提供的信息暂未说明。