我们内部构建的 AI 工程栈——就跑在我们对外发售的平台上

原文:The AI engineering stack we built internally — on the platform we ship / 2026-04-20 Source: https://blog.cloudflare.com/internal-ai-engineering-stack/

过去 30 天里,Cloudflare 研发组织 93% 的人使用了构建在我们自有平台基础设施上的 AI 编码工具。

11 个月前,我们启动了一项重大工程:把 AI 真正集成进我们的工程栈。我们需要构建内部 MCP server、访问层,以及让 agent 在 Cloudflare 内部真正有用所需的 AI 工具。我们从全公司抽调工程师组成了一支老虎团队,叫做 iMARS(Internal MCP Agent/Server Rollout Squad)。这项持续工作落到了 Dev Productivity 团队,他们也负责我们大多数内部工具,包括 CI/CD、构建系统和自动化。

这是过去 30 天里反映我们自身 agentic AI 使用情况的几个数字:

• 3,683 名内部用户 活跃使用 AI 编码工具(全公司 60%,研发 93%),公司大约共 6,100 名员工

• 4,795 万 AI 请求

• 295 个团队 当前正在使用 agentic AI 工具和编码助手

• 2,018 万 AI Gateway 请求/月

• 2,413.7 亿 token 通过 AI Gateway 路由

• 518.3 亿 token 在 Workers AI 上处理

内部开发者效率的提升是显而易见的:我们从未见过单季度对单季度的合并请求增长达到这种程度。

随着 AI 工具的采用增长,4 周滚动平均从约 5,600/周攀升至超过 8,700。3 月 23 日那一周达到 10,952,几乎是 Q4 基线的两倍。

MCP server 是起点,但团队很快意识到我们需要走得更远:重新思考标准如何被编纂、代码如何被审查、工程师如何上手,以及变更如何在数千个仓库间传播。

本文深入讲述这 11 个月里这件事是什么样的、我们最终走到了哪里。我们选在 Agents Week 收官时发布,因为我们内部构建的这套 AI 工程栈,跑的正是我们这一周对外发售并增强的同一批产品。

整体架构一览

面向工程师的工具层(OpenCode、Windsurf 以及其他 MCP 兼容客户端)既包括开源工具,也包括第三方编码助手。

每一层都对应一个我们使用的 Cloudflare 产品或工具:

这些都不是只供内部使用的基础设施。上面列出的所有内容(除 Backstage 外)都是已发售的产品,其中很多在 Agents Week 期间获得了重大更新。

我们将分为三幕来讲述:

1. 平台层 —— 认证、路由和推理如何工作(AI Gateway、Workers AI、MCP Portal、Code Mode)
2. 知识层 —— agent 如何理解我们的系统(Backstage、AGENTS.md)
3. 执行层 —— 我们如何在规模下保持高质量(AI Code Reviewer、Engineering Codex)

第一幕:平台层

AI Gateway 如何帮我们保持安全并改善开发者体验

当你有 3,600+ 名内部用户每天使用 AI 编码工具时,你需要解决跨多种客户端、用例和角色的访问与可见性问题。

一切都从 Cloudflare Access 开始,它处理所有认证和零信任策略执行。一旦认证通过,每个 LLM 请求都通过 AI Gateway 路由。这给我们一个统一的位置来管理 provider key、成本追踪和数据保留策略。

OpenCode AI Gateway 概览:每天 688.46k 请求,每天 10.57B token,通过一个 endpoint 路由到四个 provider。

AI Gateway 分析展示了月使用量在模型 provider 间的分布。过去一个月,内部请求量分布如下:

前沿模型目前承担了大部分复杂的 agentic 编码工作,但 Workers AI 已经是其中重要的一部分,并且承担着越来越多的 agentic 工程负载。

我们如何越来越多地利用 Workers AI

Workers AI 是 Cloudflare 的无服务器 AI 推理平台,在我们全球网络的 GPU 上运行开源模型。除了相对前沿模型的巨大成本改进外,一个关键优势是推理与你的 Workers、Durable Objects 和存储位于同一网络内。无需处理跨云跳转,从而避免更多延迟、网络抖动以及额外的网络配置。

Workers AI 上月用量:51.47B 输入 token,361.12M 输出 token。

Kimi K2.5 于 2026 年 3 月在 Workers AI 上发布,是一个前沿规模的开源模型,拥有 256k 上下文窗口、工具调用和结构化输出。正如我们在 Kimi K2.5 发布博客 中描述的,我们有一个安全 agent 每天在 Kimi 上处理超过 70 亿 token。在中端专有模型上,这一年估计要花费 240 万美元。但在 Workers AI 上,要便宜 77%。

除了安全场景,我们在 CI 流水线中用 Workers AI 做文档审查、跨数千个仓库生成 AGENTS.md 上下文文件,以及运行那些“同网络延迟比峰值模型能力更重要“的轻量级推理任务。

随着开源模型不断改进,我们预计 Workers AI 将承担越来越多的内部工作负载。

我们早期做对了一件事:从第一天起就通过单个代理 Worker 路由。我们本可以让客户端直接连接 AI Gateway,初始配置会更简单。但通过 Worker 集中处理意味着我们可以在以后加入按用户归因、模型目录管理和权限执行,而无需碰任何客户端配置。下面 bootstrap 部分描述的每一个能力,都是因为我们有了那个单一的瓶颈点才得以存在。代理模式给你一个直连所没有的控制面;如果以后我们接入更多编码助手工具,同样的 Worker 和发现 endpoint 也能处理它们。

它如何工作:一个 URL 配置一切

整个设置从一条命令开始:

opencode auth login https://opencode.internal.domain

那条命令触发一连串动作,配置 provider、模型、MCP server、agent、command 和 permission,用户无需碰任何配置文件。

Step 1:发现认证要求。 OpenCode 从类似 https://opencode.internal.domain/.well-known/opencode 这样的 URL 拉取 config。

这个发现 endpoint 由一个 Worker 提供,响应包含一个告诉 OpenCode 如何认证的 auth 块,以及一个包含 provider、MCP server、agent、command 和默认 permission 的 config 块:

{
  "auth": {
    "command": ["cloudflared", "access", "login", "..."],
    "env": "TOKEN"
  },
  "config": {
    "provider": { "..." },
    "mcp": { "..." },
    "agent": { "..." },
    "command": { "..." },
    "permission": { "..." }
  }
}

Step 2:通过 Cloudflare Access 认证。 OpenCode 运行 auth 命令,用户通过他们在 Cloudflare 用于一切的同一套 SSO 完成认证。cloudflared 返回一个签名 JWT。OpenCode 在本地存储它,并自动附加到后续每一个 provider 请求。

Step 3:Config 被合并到 OpenCode。 所提供的 config 是整个组织共享的默认值,但本地配置始终优先。用户可以覆盖默认模型、加入自己的 agent,或调整项目和用户级别的 permission,而不影响其他人。

代理 Worker 内部。 这个 Worker 是一个简单的 Hono 应用,做三件事:

1. 提供共享 config。 Config 在部署时由结构化源文件编译生成,包含像 {baseURL} 这样的占位符,指代该 Worker 的 origin。请求时,Worker 替换这些占位符,使所有 provider 请求都通过 Worker 而不是直连模型 provider。每个 provider 都获得一个路径前缀(/anthropic、/openai、/google-ai-studio/v1beta,以及 Workers AI 的 /compat),Worker 把请求转发给对应的 AI Gateway 路由。

2. 将请求代理到 AI Gateway。 当 OpenCode 发送 POST /anthropic/v1/messages 这样的请求时,Worker 校验 Cloudflare Access JWT,然后改写 header 后转发:

    Stripped:   authorization, cf-access-token, host
    Added:      cf-aig-authorization: Bearer <API_KEY>
                cf-aig-metadata: {"userId": "<anonymous-uuid>"}
   

   请求被发送到 AI Gateway,后者将其路由到合适的 provider。响应零缓冲地直通过去。客户端 config 中的 apiKey 字段为空,因为 Worker 在服务端注入真实的 key。用户机器上不存在任何 API key。

3. 保持模型目录新鲜。 一个每小时触发的 cron 从 models.dev 拉取当前 OpenAI 模型列表,缓存进 Workers KV,并对每个模型注入 store: false 以实现零数据保留。新模型自动获得 ZDR,无需重新部署 config。

匿名用户追踪。 在 JWT 校验后,Worker 用 D1 做持久存储、KV 做读缓存,把用户邮箱映射为 UUID。AI Gateway 在 cf-aig-metadata 中只看到匿名 UUID,从不看到邮箱。这样我们既能做到按用户的成本追踪和用量分析,又不向模型 provider 或 Gateway 日志暴露身份。

Config 即代码。 Agent 和 command 用带 YAML frontmatter 的 markdown 文件编写。一个构建脚本将它们编译为单个 JSON config,并按 OpenCode JSON schema 校验。每个新会话自动拿到最新版本。

整体架构简单,在我们的开发者平台上任何人都能轻松部署:一个代理 Worker、Cloudflare Access、AI Gateway 和一个客户端可访问的、自动配置一切的发现 endpoint。用户运行一条命令就完成了。他们无需手动配置任何东西,笔记本上不存在 API key,也没有需要手动设置的 MCP server 连接。修改我们的 agentic 工具、更新 3,000+ 人在编码环境中拿到的内容,只需要 wrangler deploy 一下。

MCP Server Portal:一次 OAuth、多个 MCP 工具

我们在 另一篇文章 中描述了我们在企业规模治理 MCP 的完整方法,包括我们如何把 MCP Server Portals、Cloudflare Access 和 Code Mode 一起使用。下面是我们内部构建的简短版本。

我们的内部 portal 聚合了 13 个生产 MCP server,跨 Backstage、GitLab、Jira、Sentry、Elasticsearch、Prometheus、Google Workspace、我们的内部 Release Manager 等暴露了 182+ 工具。这统一了访问、简化了一切——一个 endpoint、一个 Cloudflare Access 流程,治理对每个工具的访问。

每个 MCP server 都构建在同一基础上:Agents SDK 的 McpAgent、用于 OAuth 的 workers-oauth-provider,以及作为身份的 Cloudflare Access。整个东西放在一个 monorepo 里,共享 auth 基础设施、Bazel 构建、CI/CD 流水线,以及用于 Backstage 注册的 catalog-info.yaml。新增一个 server 大多就是复制一个现有的、改一下它包装的 API。更多关于这如何工作以及背后的安全架构,请参见 我们的企业 MCP 参考架构。

Portal 层的 Code Mode

MCP 是把 AI agent 接入工具的正确协议,但它有一个实际问题:每个工具定义在模型开始工作前就先消耗上下文窗口的 token。随着 MCP server 和工具数量增长,token 开销也在增长,在规模下,这成为真实的成本。Code Mode 是新兴的解法:模型不再预先加载每个工具 schema,而是通过代码发现并调用工具。

我们的 GitLab MCP server 最初暴露了 34 个独立工具(get_merge_request、list_pipelines、get_file_content 等等)。那 34 个工具 schema 每次请求大约消耗 15,000 token 上下文窗口。在 200K 上下文窗口里,问问题前已经用掉 7.5%。乘上每个请求、每个工程师、每天,加起来就很可观。

MCP Server Portal 现在支持 Code Mode 代理,让我们能集中解决这个问题,而不是一个 server 一个 server 地解决。Portal 不再向客户端暴露每个上游工具定义,而是把它们坍缩为两个 portal 级工具:portal_codemode_search 和 portal_codemode_execute。

在 portal 层做这件事的好处是它能干净地扩展。没有 Code Mode 时,每新增一个 MCP server 都给每次请求添加更多 schema 开销。有了 portal 级 Code Mode,即便我们把更多 server 接入 portal 后端,客户端始终只看到两个工具。这意味着更少的上下文膨胀、更低的 token 成本和整体上更干净的架构。

第二幕:知识层

Backstage:支撑这一切的知识图谱

在 iMARS 团队能够构建真正有用的 MCP server 之前,我们需要解决一个更基础的问题:关于我们服务和基础设施的结构化数据。我们需要 agent 理解代码库之外的上下文,比如谁拥有什么、服务之间如何依赖、文档在哪里、一个服务和哪些数据库通信。

我们运行 Backstage 作为我们的服务目录——这是一个最初由 Spotify 构建的开源内部开发者门户。它是自托管的(顺便一说,不在 Cloudflare 产品上),它跟踪诸如:

• 2,055 个服务、167 个库、122 个包

• 228 个带有 schema 定义的 API

• 跨 45 个领域的 544 个系统(产品)

• 1,302 个数据库、277 张 ClickHouse 表、173 个集群

• 375 个团队和 6,389 名用户的所属关系

• 把服务连接到它依赖的数据库、Kafka topic 和云资源的依赖图

我们的 Backstage MCP server(13 个工具)通过我们的 MCP Portal 提供,agent 可以查询某个服务的所有者、检查它依赖什么、找到相关的 API 规范、拉取 Tech Insights 评分,所有这些都不必离开编码会话。

没有这些结构化数据,agent 就在盲飞。它们能读眼前的代码,但看不到周围的系统。目录把单个仓库变成了工程组织的连通地图。

AGENTS.md:让数千个仓库为 AI 准备好

铺开早期,我们一直看到同一种失败模式:编码 agent 产出的变更看起来像那么回事,但对那个仓库就是错的。问题通常是局部上下文:模型不知道正确的测试命令、团队当前的约定,或代码库哪些部分是禁区。这把我们推向了 AGENTS.md:每个仓库里一个简短、结构化的文件,告诉编码 agent 这个代码库实际是怎么工作的,并迫使团队把这种上下文显式化。

AGENTS.md 长什么样

我们构建了一个系统,跨 GitLab 实例生成 AGENTS.md 文件。因为这些文件直接放在模型的上下文窗口里,我们希望它们短而高信号。一个典型文件长这样:

# AGENTS.md

## Repository
- Runtime: cloudflare workers
- Test command: `pnpm test`
- Lint command: `pnpm lint`

## How to navigate this codebase
- All cloudflare workers  are in src/workers/, one file per worker
- MCP server definitions are in src/mcp/, each tool in a separate file
- Tests mirror source: src/foo.ts -> tests/foo.test.ts

## Conventions
- Testing: use Vitest with `@cloudflare/vitest-pool-workers` (Codex: RFC 021, RFC 042)
- API patterns: Follow internal REST conventions (Codex: API-REST-01)

## Boundaries
- Do not edit generated files in `gen/`
- Do not introduce new background jobs without updating `config/`

## Dependencies
- Depends on: auth-service, config-service
- Depended on by: api-gateway, dashboard

当 agent 读到这个文件,就不必从头去推断这个仓库。它知道代码库如何组织、要遵循哪些约定,以及哪些 Engineering Codex 规则适用。

我们如何在规模下生成它们

生成器流水线从我们的 Backstage 服务目录拉取实体元数据(所属、依赖、系统关系),分析仓库结构以检测语言、构建系统、测试框架和目录布局,然后把检测到的栈映射到相关的 Engineering Codex 标准。一个有能力的模型生成结构化文档,系统打开一个合并请求,以便所属团队审查并完善它。

我们用这种方式处理了大约 3,900 个仓库。第一遍并不总是完美,尤其对多语言仓库或不寻常的构建设置,但即便如此,这个基线也比让 agent 从零推断好得多。

最初的合并请求解决了 bootstrap 问题,但保持这些文件常新同样重要。一个过时的 AGENTS.md 比没有这个文件更糟。我们用 AI Code Reviewer 闭环了这件事,它能在仓库变更暗示 AGENTS.md 应该被更新时发出标记。

第三幕:执行层

AI Code Reviewer

Cloudflare 的每一个合并请求都会获得一次 AI 代码审查。集成很直接:团队在他们的流水线中加入一个 CI 组件,从那一刻起每个 MR 都会被自动审查。

我们使用自托管的 GitLab 作为 CI/CD 平台。审查器实现为一个 GitLab CI 组件,团队把它包含进自己的流水线。当一个 MR 被打开或更新,CI job 用一个多 agent 的审查协调器跑 OpenCode。协调器按风险等级(trivial、lite 或 full)对 MR 分类,并委派给专项审查 agent:代码质量、安全、codex 合规、文档、性能和发布影响。每个 agent 通过 AI Gateway 接入模型、从中央仓库拉 Engineering Codex 规则,并读取仓库的 AGENTS.md 作为代码库上下文。结果以结构化的 MR 评论回贴。

一个独立的、基于 Workers 的 config 服务负责按审查 agent 集中选择模型,所以我们可以切换模型而不必改 CI 模板。审查过程本身在 CI runner 中运行,每次执行都是无状态的。

输出格式

我们花了时间把输出格式做对。审查按类别(Security、Code Quality、Performance)分块,这样工程师可以扫标题而不是读大段文字。每个发现都有一个严重性级别(Critical、Important、Suggestion 或 Optional Nits),让人立刻明白什么需要关注、什么只是参考。

审查器在迭代之间保留上下文。如果它在上一轮审查里标记的某个问题已被修复,它会承认这一点而不是再提一次。当一个发现映射到某条 Engineering Codex 规则时,它会引用具体的规则 ID,把一个 AI 建议变成对组织标准的引用。

Workers AI 处理审查器约 15% 的流量,主要用于文档审查任务——Kimi K2.5 在这里表现良好,成本只是前沿模型的一小部分。Opus 4.6 和 GPT 5.4 这类模型则处理推理能力最重要的安全敏感和架构复杂的审查。

过去 30 天里:

• 100% AI 代码审查覆盖标准 CI 流水线上的所有仓库

• 547 万 AI Gateway 请求

• 247.7 亿 token 处理

我们和这篇一起发布了一篇 详细的技术博客,涵盖审查器的内部架构,包括我们如何在模型间路由、多 agent 编排,以及我们开发出的成本优化策略。

Engineering Codex:把工程标准做成 agent skill

Engineering Codex 是 Cloudflare 新的内部标准系统,我们的核心工程标准存放于此。我们有一个多阶段的 AI 蒸馏流程,产出一组 codex 规则(“如果你需要 X,使用 Y。如果你在做 X 或 Z,你必须做 X。”),以及一个使用渐进式披露和嵌套层级信息目录、跨 markdown 文件链接的 agent skill。

工程师在本地构建时可以用这个 skill,提示词比如“我应该如何在 Rust 服务中处理错误?“或“审查这段 TypeScript 代码的合规性”。我们的 Network Firewall 团队用一个多 agent 共识流程审计了 rampartd,每个需求都被打分为 COMPLIANT、PARTIAL 或 NON-COMPLIANT,并附具体违规细节和修复步骤,把过去需要数周手工劳动的工作变成了一个结构化、可重复的流程。

在审查时,AI Code Reviewer 在反馈中引用具体的 Codex 规则。

AI 代码审查:展示分类发现(此处为 Codex Compliance),指出 codex RFC 违规。

这些组成部分本身都不算特别新颖。很多公司都在跑服务目录、发审查机器人、发布工程标准。差别在于接线方式。当 agent 能从 Backstage 拉取上下文、为它正在编辑的仓库读取 AGENTS.md,并由同一套工具链按 Codex 规则审查时,初稿通常已经接近可发布。六个月前还做不到这一点。

计分板

从启动这项工作到 93% 研发采用,用时不到一年。

全公司采用情况(2026-02-05 – 2026-04-15):

AI Gateway(过去 30 天合计):

Workers AI(过去 30 天):

下一步:后台 agent

我们内部工程栈的下一阶段演进将包括后台 agent:可按需拉起、与本地相同工具(MCP portal、git、test runner)可用,但完全在云端运行的 agent。架构使用 Durable Objects 和 Agents SDK 进行编排,在任务需要完整开发环境(如克隆仓库、安装依赖或运行测试)时委派给 Sandbox 容器。Sandbox SDK 在 Agents Week 期间 GA。

在 Agents Week 期间原生发布到 Agents SDK 的 长时运行 agent,解决了之前需要绕开方案才能解决的可靠会话问题。SDK 现在支持长时间不被驱逐的会话,足以让一个 agent 在一个会话中克隆一个大仓库、运行整个测试套件、迭代失败用例并打开一个 MR。

这代表了一项 11 个月的努力,不仅重新思考代码如何写,还重新思考它如何被审查、标准如何被强制执行,以及变更如何在数千个仓库间安全发布。每一层都跑在我们客户使用的同一批产品上。

开始构建

Agents Week 刚刚 发布了 你需要的一切。平台已经就绪。

npx create-cloudflare@latest --template cloudflare/agents-starter

这个 agents starter 让你跑起来。下面的图是当你准备扩展时的完整架构:你的工具层在最上面(chatbot、Web UI、CLI、浏览器扩展),Agents SDK 在中间处理会话状态和编排,你从中调用的 Cloudflare 服务在下面。

文档: Agents SDK · Sandbox SDK · AI Gateway · Workers AI · Workflows · Code Mode · MCP on Cloudflare

仓库: cloudflare/agents · cloudflare/sandbox-sdk · cloudflare/mcp-server-cloudflare · cloudflare/skills

更多关于我们如何在 Cloudflare 使用 AI 的内容,请阅读关于 我们的 AI 代码审查流程。也请查看 我们 Agents Week 期间发布的一切。

我们很想听听你构建了什么。在 Discord、X 和 Bluesky 上找到我们。

Ayush Thakur 构建了 AGENTS.md 系统以及 OpenCode 基础设施的 AI Gateway 集成,Scott Roemeschke 是 Cloudflare 开发者效率团队的工程经理,Rajesh Bhatia 领导 Cloudflare 的 Productivity Platform 部门。本文是 Devtools 团队的协作成果,并通过 iMARS(Internal MCP Agent/Server Rollout Squad)老虎团队获得了来自全公司志愿者的帮助。

– 原文译于 2026-04-30