SuperAPI AI 工具集

doc-diagnostic

通用与其它

查看项目

更新于 10-15 23:41

技能介绍

用途:在推荐任何文档前先做四问诊断——Purpose(为一句话说明为已知系统存在的读者回答什么问题)、Audience(具体情境下的具体读者)、Owner(对内容真实性负责的具名人类)、Update trigger(触发重访或替代的具体事件)。任一回答为“否/不明确”,就不应写该文档。

主要能力:一是替代方案目录,当用户冲动不适用 ADR 时,映射到正确文档形式(含 Diátaxis 四类:教程/操作指南/参考/解释;ADR 不等同于 Diátaxis 的解释)。二是 ADR 规范:模板选择(Nygard/MADR light、MADR full、Y-statement、arc42/Tyree-Akerman/业务案例),每个项目选一种,不混用;状态生命周期为 proposed → accepted,可至 superseded 或 deprecated,状态值须为小写 proposed、accepted、deprecated、superseded,不得塞入 rfc、rejected 等。

关键规则:Accepted 后正文仅可追加——修正错别字、加 superseded by 说明、在 Amendments 标题下加日期条目;变更决策需新建 ADR 并在 supersedes 列出旧编号,旧 ADR 加 superseded by 读者提示。编号单调递增、零填充、永不复用,编号即身份;文件名如 0007-use-postgres-for-primary-store.md。必需字段含标题、YAML frontmatter(至少 title、status、date、deciders)、正文 Relationships 镜像,二者必须一致。ADR 存放于源码仓库中,如 docs/adr/ 等位置,并在 README.md 提供索引。默认 MADR 4.0.0 + frontmatter + 正文 Relationships 镜像。

使用方式:触发于路由文档请求、选择模板、命名状态、审计现有文档集时;/doc-audit 使用八步文件夹级审计,输出 KEEP/MERGE/REWRITE/DELETE/MOVE/BACKFILL-ADR 清单,BACKFILL-ADR 仅为候选,须证据出现在两个独立位置。可用 offline 校验脚本 plugins/doc-master/scripts/validate_adrs.py 作为 CI 门禁。

限制:不得修改 Accepted ADR 正文、不得批量重编号、不得自动生成 Owner、未经批准不得删除;文档是成本,数量应保持系统可理解、可操作、可决策的最小值。收费、价格、平台与效果信息暂未提供。