mupt-ai/dari-docs

来源：https://github.com/mupt-ai/dari-docs

dari-docs

让你的文档优秀到连最笨的智能体都能用它交付。

dari-docs 是一个 CLI 工具，用于测试你的文档是否足够清晰，能够让智能体顺利使用。它会将你的文档发送给模拟的开发者智能体，要求它们完成实际任务，报告它们在哪些地方卡住了，并可以根据这些反馈生成建议的文档修改。

用它来把文档质量从“似乎能看懂”提升到“智能体确实能完成任务”。

为什么用 dari-docs？

过去好的文档意味着“开发者最终能弄明白”。但这已经不够了。

当阅读者是智能体时，歧义变得可量化。不一致的术语、隐藏的假设、分散的上下文以及缺失的配置步骤，都会增加智能体失败或浪费上下文来推断文档意图的可能性。

dari-docs 为智能体可读的文档提供了一个可重复的反馈循环：定义任务、运行模拟用户、检查失败点，并可选地拉回修改后的文档。

它能做什么

• 用模拟开发者测试文档——智能体仅使用你提供的文档来尝试完成具体任务。
• 发现阻碍任务的歧义——报告缺失的上下文、不清晰的配置、不一致的术语，以及代理不得不猜测的地方。
• 生成建议的修复——optimize 命令将测试者的反馈转化为修改后的文档，你可以在本地查看。
• 支持托管或自主管理——使用托管的 dari.dev Docs 服务，或者在你自己的 dari.dev 组织中运行智能体。
• 使用普通的智能体项目——测试者和编辑者只是提示词、技能、配置脚本和 dari.yml 清单的文件夹。

安装

使用安装脚本安装最新的 dari-docs 二进制文件，然后验证 CLI 可用：

curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-docs/main/install.sh | bash
dari-docs --help

快速开始

托管模式使用托管的 dari.dev Docs 服务和单独的 dari.dev Docs 信用额度。新账户初始拥有价值五美元的免费信用。

从你的文档仓库中运行：

dari-docs auth login

运行文档检查：

dari-docs check . \
  --managed \
  --task "安装 SDK 并进行第一次 API 调用"

该命令提交一个托管运行并打印运行 ID。要在同一命令中等待完成，请添加 --wait。

生成建议的文档修改：

dari-docs optimize . \
  --managed \
  --wait \
  --task "安装 SDK 并进行第一次 API 调用"

使用 --wait 时，修改后的文件会下载到 .dari-docs/updated/ 目录中，不会修改你的仓库。查看该文件夹，并在准备好后将更改复制到仓库中。

工作原理

1. 你将 dari-docs 指向一个文档目录或公开文档 URL，并提供一个或多个任务。
2. CLI 打包你的本地文档，或者将公开文档 URL 传递给检查智能体（带有互联网访问权限），然后向托管的 Dari Docs 智能体提交运行。
3. 测试智能体尝试完成任务，并报告文档在哪些地方阻碍了进度。
4. 使用 dari-docs runs wait、dari-docs runs download 或 --wait 来收集本地运行产物。
5. 如果运行 optimize，编辑智能体会提出文档更改建议。
6. 建议的修改可以下载到 .dari-docs/updated/ 目录中进行审查。

模拟用户是普通的 dari.dev 智能体。托管模式自动使用托管的 Dari Docs 测试者和编辑智能体。如果你想自定义智能体提示词、技能、配置脚本或 dari.yml，请使用自主管理模式。

托管模式 vs 自主管理

大多数用户应从托管模式开始。

文档

• 托管模式与计费
• GitHub Actions
• 任务文件和重复检查
• 包选择
• 实时验证密钥
• 智能体自定义
• 自主管理用法
• 本地开发