优化面向 AI 代理时代的文档

技术文档的传统标准一直基于人类直觉：如果开发者最终能够弄清楚，则文档被视为'良好'。然而，随着 AI 编码代理成为与软件交互的主要界面，此标准已不再足够。人类可能直觉上弥合的歧义对代理而言是失败点。

dari-docs 是一个 CLI 工具，旨在将文档质量从主观感受转变为可衡量的指标。通过使用模拟开发者代理的 fleet 仅使用提供的文档尝试真实任务，它创建了一个可重复的反馈循环，以创建 'agent-readable' 文档。

面向代理可读文档的转变

当读者是 AI 代理时，歧义的成本会增加。不一致的术语、隐含的假设和缺失的设置步骤不仅仅是小麻烦；它们是导致代理失败任务或浪费上下文窗口以推断缺失信息的阻塞点。

dari-docs 通过将文档视为需要测试的代码来解决此问题。它允许开发者定义一个具体任务——例如“安装 SDK 并进行首次 API 调用”——然后观察模拟代理是否能仅使用提供的文档成功完成该任务。

该工具通过主要的反馈循环运作：测试、检查和优化。

使用 dari-docs check 命令，用户可以将工具指向本地目录或公共 URL。CLI 会将文档打包并提交给测试代理。这些代理将尝试指定的任务，并报告他们确切卡住的位置，以识别缺失的上下文或不明确的设置说明。

而不是进行一般审查，dari-docs 提供针对任务阻塞歧义的具体反馈。这包括：

除了仅仅识别问题之外，该工具还提供一个 optimize 命令。这会触发一个编辑代理，根据测试代理遇到的失败提出具体的文档编辑建议。这些建议的更改将下载到 .dari-docs/updated/ 文件夹中，以供人工审查，确保用户对最终内容保持控制。

为了满足不同需求，dari-docs 提供两种执行路径：

模式	使用场景	需求
托管	最快的设置和托管执行。	`dari-docs auth login`
自管理	在您自己的 dari.dev 组织内运行以获得更多控制。	dari.dev API 密钥和已部署的代理

"我认为一个功能将使 dari-docs 在实际管道中更加实用，那就是一个强大的内置双向 Markdown 和 HTML 转换器"

此外，一些用户对将文档上传到托管服务的敏感性表示担忧，这凸显了自管理模式对具有严格数据隐私要求的企业的重要性。

随着我们迈向一个 AI 代理比人类更可能阅读您文档的世界，目标是让文档“即使是最笨的代理也能交付”。通过将文档视为可测试的资产，dari-docs 提供了一个将歧义转化为可衡量失败的框架，使开发者能够构建真正可访问的 AI 驱动开发生命周期的软件。