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 聊天 Agent |
packages/hono-agents/ | Hono 框架集成 |
packages/codemode/ | @cloudflare/codemode，实验性代码生成运行时 |
examples/ | 自包含演示应用，约 20 个（约定见 examples/AGENTS.md） |
examples/playground/ | 主展示应用，在单一 UI 中集成全部 SDK 能力（使用 Kumo 设计系统） |
experimental/ | 进行中的实验，不发布、无稳定性保证 |
site/ | 已部署站点，如 agents.cloudflare.com（Astro） |
guides/ | 带叙事性 README 的深度模式教程（约定见 guides/AGENTS.md） |
openai-sdk/ | 使用@openai/agentsSDK 的示例（basic、chess-app、handoffs 等） |
docs/ | 面向 developers.cloudflare.com 的 Markdown 文档（写作规范见 docs/AGENTS.md） |
design/ | 架构与设计决策记录（RFC 格式与流程见 design/AGENTS.md） |
scripts/ | 仓库级工具脚本（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: pnpm@11.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 typecheck |
pnpm run test | 通过 Nx 运行全部测试（nx run-many -t test，缓存） |
pnpm run test:react | 运行 agents 包基于 Playwright 的 React Hook 测试 |
pnpm run typecheck | 全仓库 TypeScript 类型检查（自定义脚本 scripts/typecheck.ts） |
pnpm run format | Oxfmt 格式化全部文件 |
pnpm run check:exports | 校验各包package.json的 exports 与实际构建产物一致（scripts/check-exports.ts） |
pnpm 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 <tsconfig>（TypeScript 原生预览编译器），单项目失败最多重试 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.json：
target: 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: "error"，varsIgnorePattern/argsIgnorePattern/caughtErrorsIgnorePattern均为^_，即以下划线开头的变量/参数/捕获错误可豁免；categories.correctness: "error"——正确性类目全部升为错误级；react-hooks/exhaustive-deps: "warn"——Hook 依赖缺失仅告警；ignorePatterns排除**/env.d.ts（wrangler 生成物，见下文"生成文件"一节）与**/routeTree.gen.ts。
Oxlint 不做格式化，格式化由 Oxfmt 负责，职责分离清晰。
格式化：Oxfmt
- 全量格式化：
pnpm run format（即oxfmt --write .），CI 侧对应format:check（oxfmt --check .）； - 配置在 .oxfmtrc.json：
trailingComma: "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-react） |
packages/ai-chat/src/tests/ | AI Chat 包测试 |
packages/agents/src/tests-d/ | 类型级测试（.test-d.ts） |
每个测试目录各自持有独立的vitest.config.ts，Workers 测试目录还配有独立wrangler.jsonc，以便按包定制 D1/KV/Durable Objects 等资源。此外，AGENTS.md指向 design/test-coverage-matrix.md——一份仓库级"测试证据矩阵"，记录"某功能 X 由哪一层的测试证明、哪条 CI 流水线守护"以及被跟踪的 skip/quarantine 技术债，是理解测试分层设计的良好入口。
贡献流程：Changesets 与 CI
Changesets 版本化
对packages/下影响公共 API 或修复缺陷的改动必须附 changeset：
pnpm exec changeset # 交互式：选择包、semver 提升级别、填写描述命令会在.changeset/下生成一个 Markdown 文件，发布时被消费。示例、指南与站点不需要 changeset。实际配置见 .changeset/config.json：changelog 生成器使用@changesets/changelog-github，access: "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 浏览器 →CI=true pnpm exec nx affected -t test→ 用pkg-pr-new publish --peerDeps ./packages/*发预发布包供评审验证。这与AGENTS.md描述的"CI 在每次 PR 上运行 install + build + check + affected test"完全一致，且nx affected依赖 PR 分支与main（defaultBase）的差异来裁剪测试范围。
推送到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 原生 API（KV、D1、R2、Durable Objects 等）而非第三方等价物；示例中的 LLM 调用一律使用 Workers AI，不用第三方 API； - Ask first：给
packages/新增依赖（会随包发布给用户）、跨仓库变更 wranglercompatibility_date、修改 CI 工作流； - Never：硬编码密钥；引入 native/FFI/C 绑定依赖；使用
any（Oxlint 会拒绝）；使用 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），仅供参考
