Cloudflare Agents 单体仓库的 AGENTS.md从目录结构到代码规范与 CI 流程的工程实践全解【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents本文围绕 Cloudflare Agents 仓库构建并部署于 Cloudflare Workers 上的有状态 AI Agent 框架根目录的 AGENTS.md 展开系统讲解这个 monorepo 的目录组织、环境搭建、常用命令、TypeScript/Oxlint/Oxfmt/Workers 编码规范、测试体系以及 Changesets 发布流程。读完本文你能够独立克隆并跑通该仓库的任意 example理解每个 CI 检查项背后的实现并掌握向packages/贡献代码时必须遵循的版本化与边界约束。仓库定位与目录结构Cloudflare Agents 是一个 monorepo核心 SDK 包、示例应用、指南、官网与文档全部集中管理。根目录AGENTS.md给出了如下结构总览路径均以仓库根目录为起点目录职责packages/发布到 npm 的包改动需 Changesets 配合packages/agents/核心 SDK另有 packages/agents/AGENTS.md 讲解导出、源码布局、构建与架构packages/ai-chat/cloudflare/ai-chat更高层的 AI 聊天 Agentpackages/hono-agents/Hono 框架集成packages/codemode/cloudflare/codemode实验性代码生成运行时examples/自包含演示应用约 20 个约定见 examples/AGENTS.mdexamples/playground/主展示应用在单一 UI 中集成全部 SDK 能力使用 Kumo 设计系统experimental/进行中的实验不发布、无稳定性保证site/已部署站点如 agents.cloudflare.comAstroguides/带叙事性 README 的深度模式教程约定见 guides/AGENTS.mdopenai-sdk/使用openai/agentsSDK 的示例basic、chess-app、handoffs 等docs/面向 developers.cloudflare.com 的 Markdown 文档写作规范见 docs/AGENTS.mddesign/架构与设计决策记录RFC 格式与流程见 design/AGENTS.mdscripts/仓库级工具脚本typecheck、导出检查、更新检查实际工作区定义在 pnpm-workspace.yaml 中可确认的包范围包括packages/*、examples/*排除examples/next主包、按子目录纳入examples/next/*、voice-providers/*、guides/*、experimental/*、openai-sdk/*、site/*等其中还通过patchedDependencies对chonkiejs/chunk与vitest-browser-react打了本地补丁对应patches/目录并用allowBuilds精确控制了哪些依赖允许执行安装脚本如workerd、esbuild允许google/genai、msw禁止。嵌套 AGENTS.md 文件体系该仓库的一个显著工程实践是AGENTS.md 分级根文件负责全局约束子目录文件负责局部细节。AGENTS.md中列出的五份嵌套文件均确实存在文件作用域packages/agents/AGENTS.md核心 SDK 内部——导出、源码布局、构建、测试、架构examples/AGENTS.md示例约定——必需结构、一致性规则、已知问题guides/AGENTS.md指南约定——guide 与 example 的差异、README 期望docs/AGENTS.md面向用户的文档写作——Diátaxis 框架、上游同步、风格design/AGENTS.md设计记录与 RFC——格式、流程、与 docs 的关系对 LLM 编码 Agent 与人类协作者来说这套分层文档相当于把在哪个目录该守什么规矩写进了目录本身是仓库级 Agent 提示词agent prompt组织方式的典型范例。环境搭建pnpm install # 安装所有 workspace前置条件是Node 24。仓库使用 pnpm workspaces 组织多包并用 Nx 做任务编排、缓存与 affected 检测——这一点可从 nx.json 得到印证build目标声明了dependsOn: [^build]先构建上游依赖包与outputs: [{projectRoot}/dist]、cache: true产物缓存test依赖build且同样开启缓存test:e2e不缓存。namedInputs.production中还显式排除了测试与评测目录src/tests/**、src/react-tests/**、evals/**、vitest.config.*等保证构建缓存键只由生产代码驱动。根 package.json 锁定了packageManager: pnpm11.9.0并声明了仓库级关键依赖nx、oxfmt、oxlint、sherif、cloudflare/vite-plugin、cloudflare/vitest-pool-workers、wrangler、typescript等——这些正是下文各命令背后实际执行的引擎。常用命令总览以下命令均在仓库根目录执行与 package.json 中scripts字段一一对应命令作用pnpm run build通过 Nx 构建所有包nx run-many -t build缓存、按依赖顺序pnpm run check完整 CI 检查sherif pnpm run check:exports oxfmt --check . oxlint . pnpm run typecheckpnpm run test通过 Nx 运行全部测试nx run-many -t test缓存pnpm run test:react运行 agents 包基于 Playwright 的 React Hook 测试pnpm run typecheck全仓库 TypeScript 类型检查自定义脚本 scripts/typecheck.tspnpm run formatOxfmt 格式化全部文件pnpm run check:exports校验各包package.json的 exports 与实际构建产物一致scripts/check-exports.tspnpm exec nx affected -t build只构建受当前变更影响的包pnpm exec nx affected -t test只测试受当前变更影响的包pnpm exec nx run project:build构建单个项目及其依赖两个值得注意的实现细节typecheck并非直接跑tsc而是 scripts/typecheck.ts 这个自定义脚本它用fast-glob递归收集所有tsconfig.json按 CPU 核数并发地对每个项目执行tsgo -p tsconfigTypeScript 原生预览编译器单项目失败最多重试 3 次并支持传入路径过滤参数。check是 CI 的总闸其中sherif用于检查包导入边界check:exports防止声明的导出面与dist/实际产物脱节。本地运行示例应用cd examples/playground # 或任意 example pnpm dev # 启动 Vite 开发服务器 经 cloudflare/vite-plugin 接入的 Workers 运行时pnpm dev背后是cloudflare/vite-plugin根package.json中声明为^1.48.0它把 Vite 开发服务器与本地 Workers 运行时workerd打通使示例可以在真实 Workers 环境中热重载。AGENTS.md特别提示dev server 运行期间改动packages/下的包后要重新执行pnpm run build让运行中的应用看到新构建的产物。这与nx.json中build的缓存行为一致——示例应用消费的是packages/*/dist而非包源码。代码规范TypeScript 基线仓库统一使用严格模式共享配置为agents/tsconfig其实际内容见 packages/agents/agents.tsconfig.jsontarget: ES2021、module: ES2022、moduleResolution: bundlerstrict: true、isolatedModules: trueverbatimModuleSyntax: true——类型导入必须写import typejsx: react-jsxtypes固定为node、cloudflare/workers-types、vite/client静态检查Oxlint配置位于 .oxlintrc.json启用react、jsx-a11y、typescript三个插件关键规则no-explicit-any: error——禁止any应使用unknown再收窄no-unused-vars: errorvarsIgnorePattern/argsIgnorePattern/caughtErrorsIgnorePattern均为^_即以下划线开头的变量/参数/捕获错误可豁免categories.correctness: error——正确性类目全部升为错误级react-hooks/exhaustive-deps: warn——Hook 依赖缺失仅告警ignorePatterns排除**/env.d.tswrangler 生成物见下文生成文件一节与**/routeTree.gen.ts。Oxlint 不做格式化格式化由 Oxfmt 负责职责分离清晰。格式化Oxfmt全量格式化pnpm run format即oxfmt --write .CI 侧对应format:checkoxfmt --check .配置在 .oxfmtrc.jsontrailingComma: none、printWidth: 80并显式忽略packages/agents/CHANGELOG.md由 Changesets 生成、site/agents/.astro等目录。Workers 工程约定AGENTS.md对运行在 Workers 运行时代码约定了四条硬性规范始终 TypeScript、始终 ES Modules——仓库边界一节也明确Never: Use CommonJS or Service Worker format配置文件用wrangler.jsonc而非.toml抽查 examples/playground/wrangler.jsonc 可确认全仓库统一compatibility_date: 2026-06-11所有 wrangler 配置使用compatibility_date: 2026-06-11与compatibility_flags: [nodejs_compat]绝不硬编码密钥——用wrangler secret put或.env且不得引入 native/FFI 依赖必须能在 Workers 运行时执行。测试体系测试采用vitest cloudflare/vitest-pool-workers即测试代码直接运行在真实的 Workers 运行时workerd内而非普通 Node 环境pnpm run test # agents ai-chat 的单元/集成测试 pnpm run test:react # agents 包基于 Playwright 的 React Hook 测试测试位置与职责划分以下目录均已确认存在目录内容packages/agents/src/tests/核心 SDK 测试packages/agents/src/react-tests/React Hook 测试Playwright vitest-browser-reactpackages/ai-chat/src/tests/AI Chat 包测试packages/agents/src/tests-d/类型级测试.test-d.ts每个测试目录各自持有独立的vitest.config.tsWorkers 测试目录还配有独立wrangler.jsonc以便按包定制 D1/KV/Durable Objects 等资源。此外AGENTS.md指向 design/test-coverage-matrix.md——一份仓库级测试证据矩阵记录某功能 X 由哪一层的测试证明、哪条 CI 流水线守护以及被跟踪的 skip/quarantine 技术债是理解测试分层设计的良好入口。贡献流程Changesets 与 CIChangesets 版本化对packages/下影响公共 API 或修复缺陷的改动必须附 changesetpnpm exec changeset # 交互式选择包、semver 提升级别、填写描述命令会在.changeset/下生成一个 Markdown 文件发布时被消费。示例、指南与站点不需要 changeset。实际配置见 .changeset/config.jsonchangelog 生成器使用changesets/changelog-githubaccess: public、baseBranch: main并且ignore了cloudflare/agents-*非 SDK 的附属包。CI 与发布流水线PR 流水线定义在 .github/workflows/pullrequest.yml对仅改动design/**、*.md、.changeset/**的 PR 直接跳过paths-ignore对代码 PR 依次执行安装 →pnpm run build→pnpm run check→ 安装 Playwright 浏览器 →CItrue pnpm exec nx affected -t test→ 用pkg-pr-new publish --peerDeps ./packages/*发预发布包供评审验证。这与AGENTS.md描述的CI 在每次 PR 上运行 install build check affected test完全一致且nx affected依赖 PR 分支与maindefaultBase的差异来裁剪测试范围。推送到main时由 Release 流水线.github/workflows/release.yml接管执行同样的检查步骤但用nx run-many -t test作为安全网防止 affected 计算漏报项目最后通过 changesets 完成正式发布。所有检查必须通过才可合并。生成文件以下文件属于生成物禁止手工编辑env.d.ts——由wrangler types生成需在相应 example/package 内执行pnpm exec wrangler types重新生成这也是.oxlintrc.json与.oxfmtrc.json均忽略**/env.d.ts的原因pnpm-lock.yaml——由pnpm install重新生成。工作区已知事实与行为边界AGENTS.md末尾沉淀了两类对后续协作者含 AI Agent至关重要的记忆。Learned Workspace Facts工作区事实packages/shell/以cloudflare/shell发布——一个面向 Agent 的实验性沙箱 JS 执行与文件系统运行时与cloudflare/codemode共用同一套动态 Worker 加载机制要在Workspace上执行代码的接线方式是从cloudflare/shell/workers导入stateTools从cloudflare/codemode导入DynamicWorkerExecutor/resolveProvider然后调用executor.execute(code, [resolveProvider(stateTools(workspace))])。边界Boundaries按强制级别分三层Always收工前必须跑pnpm run check类型导入一律import type示例保持简单自包含它们是面向用户的学习材料优先使用 Workers 原生 APIKV、D1、R2、Durable Objects 等而非第三方等价物示例中的 LLM 调用一律使用 Workers AI不用第三方 APIAsk first给packages/新增依赖会随包发布给用户、跨仓库变更 wranglercompatibility_date、修改 CI 工作流Never硬编码密钥引入 native/FFI/C 绑定依赖使用anyOxlint 会拒绝使用 CommonJS 或 Service Worker 格式仅 ES Modules修改node_modules/或dist/向 main 强推。这些Always/Ask first/Never条款与上文各检查工具形成闭环any被 Oxlint 拦截、CommonJS 被 Workers 运行时与module: ES2022配置拦截、导出面漂移被check:exports拦截、未跑检查就被check流水线拦截——仓库把规范条文与自动执法机制一一对应这正是该 monorepo 工程规范最值得借鉴之处。小结根目录 AGENTS.md 用不到两百行完成了四件事给出与 pnpm-workspace.yaml、nx.json 相互印证的可执行目录地图定义了从pnpm install到pnpm dev的完整本地回路以 agents.tsconfig.json、.oxlintrc.json、.oxfmtrc.json 为依据固化了 TypeScript、静态检查与格式化基线并以 Changesets 双工作流pullrequest.yml / release.yml约束了从 PR 到 npm 发布的每一步。对希望在该仓库贡献代码或想在自己的 monorepo 中落地Agent 友好工程规范的团队这份文件与它背后每个可验证的配置、脚本、工作流构成了一个完整的参考实现。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考