Cloudflare Agents SDK 文档编写与治理规范docs/ 目录的 Diátaxis 实践【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents本篇技术指南以本仓库 docs/AGENTS.md 为骨架系统讲解 Cloudflare Agents SDK 单仓库monorepo中用户文档的组织方式、Diátaxis 文档分类框架、与上游cloudflare-docs的手动同步流程、写作风格约束以及新增文档的标准流程。读完本文你将掌握一套可直接复用的 SDK 文档治理方法论理解如何在docs/面向用户的用法文档与design/面向贡献者的设计记录之间正确分工并能够按照仓库规范为任意包编写、分类和同步高质量用户文档。docs/ 目录的定位与文档归属docs/是 Cloudflare Agents SDK monorepo 面向最终用户的 Markdown 文档集合。根据仓库根目录 AGENTS.md 中的结构定义docs/对应的是 Markdown docs for developers.cloudflare.com即这些文件中的适用部分会手动同步到 developers.cloudflare.com/agents/。其核心组织原则是按包归属每个 npm 包拥有docs/下与其无作用域包名unscoped package name对应的子目录。总索引 docs/index.md 清晰地列出了各包与目录的对应关系包目录内容范围agents核心 SDKdocs/agents/Durable Object 代理、状态、路由、调度、会话、MCP、Voice、Channels 及共享原语cloudflare/thinkdocs/think/基于 Agents、Codemode、Shell 构建的定制化 Agent 运行时cloudflare/codemodedocs/codemode/沙箱代码执行、工具提供方、连接器、审批与片段cloudflare/shelldocs/shell/持久化工作区与文件系统工具cloudflare/voicedocs/voice/已废弃包的兼容与迁移指引其余已发布的包则以各自包内的 README 作为文档入口。例如 docs/agents/index.md 中的 Related package documentation 一节就指向cloudflare/codemode/docs/index.md与cloudflare/ai-chat/README.md体现了每个包都有自己的文档入口这一约束。Diátaxis 框架四象限文档分类docs/AGENTS.md采用 Diátaxis 框架来约束文档类型要求每篇文档必须有且只有一个明确的主要类型。仓库内的实际文档严格遵循了这一表格类型目的读者的需求本仓库中的示例Tutorial教程跟着做并学习学习getting-started.md、adding-to-existing-project.mdHow-to操作指南解决特定任务一个目标email.md、webhooks.md、human-in-the-loop.md、cross-domain-authentication.md、迁移指南Reference参考查阅 API信息agent-class.md、callable-methods.md、client-sdk.md、state.md、configuration.mdDiátaxis 的第四种类型——explanation解释理解为什么——不放在docs/而是放在design/目录。这是整个仓库文档体系的关键分工如果你在写为什么某样东西这样设计 → 放入design/如果你在写如何使用某样东西 → 放入docs/。这种分工在 design/AGENTS.md 中得到了印证/docs是面向用户的如何使用 SDK/design是面向贡献者的SDK 为什么这样工作如果设计决策影响用户与 SDK 的交互方式就把对用户有影响的部分提炼成docs/中的文档并链接回design/获取完整论证。设计文档目录中的state.md、mcp.md、visuals.md等属于 design doc描述当前实现而rfc-前缀的文件属于 RFC特定时间点的决策记录两类文档各有明确的格式与工作流。如何选择正确的文档类型docs/AGENTS.md给出了三条可操作的选择准则新增 API 或功能从reference开始签名、参数、返回类型、行为附带一个简洁示例多步骤工作流写how-to指南以目标为导向的步骤假定读者已理解基础新手上手流程写tutorial以学习为导向、一步一步读者跟着做。同时要避免文档类型混用Dont hybridise一篇 reference 文档中可以包含一个简短示例但如果你在 reference 文档里写了一份 20 步的完整演练那就应该拆出来单独作为 how-to。以 docs/think/index.md 为例它作为cloudflare/think包的入口文档主体是 reference 风格的 API 表格如 Configuration Overrides 表、Package Exports 表而把一步步的上手流程拆给了独立的 getting-started.md。上游同步与 cloudflare-docs 的手动协作docs/AGENTS.md明确指出仓库内没有自动化的同步工作流。docs/中的变更必须手动移植到cloudflare/cloudflare-docs仓库的src/content/docs/agents/目录。实际操作要求是在本仓库更新某篇文档时同时更新 cloudflare-docs 中对应的.mdx文件。这意味着文档维护者需要跨仓库工作任何对 SDK 行为的修改、新增的 API 说明或修订的示例都需要在两边保持一致以免公开发布文档与仓库内文档出现偏差。写作风格规范docs/AGENTS.md对文档写作风格提出了明确要求这些规范直接决定了文档的可读性与专业性面向 SDK 用户而非贡献者假设读者正在用 Agents SDK 构建应用而不是维护 SDK 本身具体优于抽象多用代码片段而非大段文字多用真实示例而非抽象描述不使用缩略词contractions这是 Cloudflare 风格指南的硬性要求——必须写 do not 而不是 dont所有代码示例使用 TypeScript与仓库 Always TypeScript 的整体约定一致见根 AGENTS.md 的 Workers conventions 一节包目录内使用相对路径链接如./state.md跨包目录链接使用仓库绝对 URL并在行文中注明安装的包路径。以 docs/agents/getting-started.md 为实际范本整篇文档从创建项目、编写第一个 Counter Agent、连接 React 前端到部署全程以 TypeScript 代码示例和 JSON 配置示例为主体风格完全符合具体优于抽象的要求。新增一篇文档的标准流程当需要为某个包新增文档时docs/AGENTS.md给出了三步流程在所属包的目录下编写 Markdown 文件将该文件添加到该包的index.md中如果文档涉及设计决策考虑是否需要在design/中配套一篇设计记录。这里有一个实际的仓库佐证docs/index.md 本身就是包的索引入口docs/agents/index.md 则是agents包的完整导航按 Getting Started、Core Concepts、Client SDK、Communication Channels、Background Processing、AI Integration、MCP、Authentication Security 等分类组织。新增文档时只需照此模式补充条目。TODO backlog 机制docs/AGENTS.md还描述了一种文档欠账管理机制agents/index.md中带有TODO标记的条目是已知的文档缺口。当你填补其中一项时需要移除 TODO 标记并按照上述新增文档流程操作。这个机制在 docs/agents/index.md 中得到了充分体现其中可见大量 TODO 条目例如TODO: SMS - Text message integration (Twilio, etc.)TODO: AI SDK Integration - Using Vercel AI SDK with agentsTODO: API Reference - Complete API documentationTODO: [Testing](https://link.gitcode.com/i/6b01d3576e5167201dcd984790abd38b)、TODO: Evals、TODO: Securing your Agents等这些 TODO 条目公开记录了文档覆盖的空白让贡献者可以按图索骥地认领并补齐。从源码看文档系统的实际运作docs/AGENTS.md描述了治理规范而仓库源码进一步揭示了这套文档体系如何与构建流程结合。包构建时自动复制文档scripts/copy-package-docs.ts 展示了文档如何在构建时进入各包copyPackageDocs函数接收构建脚本的 URL 与文档子目录名将仓库根docs/下的对应子目录递归复制到包根目录的docs/文件夹先清空目标再复制。这意味着 docs/think/ 等目录会在构建时被打包进对应的 npm 包与docs/AGENTS.md中每个包拥有docs/下对应目录的组织原则互相印证。文档即导航索引文件的组织模式从 docs/index.md 到各包的 index.md索引文件的写法高度一致先用一句话说明包的功能定位如agents的定位是 Build stateful AI agents on Cloudflare Workers再用 Choose your path 式的对比表帮读者选择正确的基类Agent、AIChatAgent、Think、Voice mixins、Workflows最后按主题分组列出全部文档链接。这种模式正是 Diátaxis reference 象限在导航层面的落地也是新增文档时参照的模板。多套 AGENTS.md 的分层治理docs/AGENTS.md并不是孤立的治理文件。仓库根 AGENTS.md 明确列出了五套嵌套 AGENTS.md 的分工文件职责范围packages/agents/AGENTS.md核心 SDK 内部导出、源码布局、构建、测试、架构examples/AGENTS.md示例约定必需结构、一致性规则、已知问题guides/AGENTS.md指南约定指南与示例的区别、README 期望docs/AGENTS.md编写用户文档Diátaxis 框架、上游同步、风格design/AGENTS.md设计记录与 RFC格式、工作流、与文档的关系examples/AGENTS.md 就是一个很好的对照样本——它约束的是每个示例聚焦一个特性、必需的文件结构、脚本约定与docs/AGENTS.md约束的文档类型与风格互补而不重叠。这套分层治理让每个目录的贡献者都能在最近的 AGENTS.md 中找到针对该目录的规则。实践建议遵循这套规范编写文档综合docs/AGENTS.md与仓库实际实践为 Cloudflare Agents SDK 仓库贡献文档时的操作清单如下先判断类型是教人上手tutorial、解决任务how-to、查 APIreference还是解释设计explanation前三种放docs/最后一种放design/写入正确目录根据文档描述的包写入 docs/agents/、docs/think/、docs/codemode/、docs/shell/ 或 docs/voice/ 之一更新索引把新文档加入对应包的index.md注意移除被填补的 TODO 条目遵守风格面向 SDK 用户、用 TypeScript 写代码示例、不用缩略词、包内用相对链接、跨包用绝对 URL同步上游同时更新 cloudflare-docs 中对应的.mdx文件保持公开发布文档与仓库内文档一致。这套流程不仅适用于本仓库其按包分目录 Diátaxis 四象限 TODO 缺口跟踪 双仓库手动同步的组合也是大型 SDK 单仓库项目在文档治理上的一种成熟范式可以迁移到其他多包项目中使用。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考