附录 B:2026 Q2 推荐栈(v2)

这本书所有依赖、版本、镜像的快照。写于 2026 年 4 月。BLUEPRINT v2 命名为 agent-coder,主线全程跑在 Cloudflare 自家 primitives 上。技术栈每季度都在变,如果你在这之后读到,先确认下面每一项的最新稳定版,再决定是否升级。

选型理由(一句话版)

类别	选择	一句话理由
Agent 基类	`@cloudflare/think`	把 AIChatAgent + Session + 工具循环 + sub-agent + sandbox 折成一个 base,只写 3 个钩子
底层 Agent SDK	`agents`	`routeAgentRequest`、Email 路由、`AgentWorkflow`、Facets sub-agent 都在这里
Sandbox	`@cloudflare/sandbox`	GA(2026-04);Container + DO + 文件系统 / shell / PTY / port 暴露 / squashfs 备份
Code Mode	`@cloudflare/codemode`	LLM 写 JS 在 Dynamic Worker 沙盒里执行;`codeMcpServer` 把工具折成 search+execute 两个,token 节省 99%
LLM 抽象	`ai`(Vercel AI SDK v6)	provider-agnostic、流式、tool calling;Think 内部就用它驱动 LLM
Workers AI provider	`workers-ai-provider`	让 `getModel()` 返的对象认得 Workers AI 模型
chat 客户端	`@cloudflare/ai-chat`	`useAgentChat` React hook,与 Think 的协议层兼容
Schema	`zod`	tool inputSchema、Workflows 参数都用它
GitHub	`@octokit/core` + `@octokit/auth-app`	App + installation token,比 PAT 安全
鉴权辅助	`jose`	校验 Cloudflare Access 签的 JWT
测试	`vitest` + `@cloudflare/vitest-pool-workers`	在真 Workers runtime 跑单测,DO/KV/R2 都能 mock
部署 CLI	`wrangler` v4	secret / 多 env / versions / Browser Run 一把抓

不引入(避免膨胀):

@ai-sdk/anthropic / @ai-sdk/openai 等 provider 包 —— 用 AI Platform env.AI.run("anthropic/...") 替代
单独的 @cloudflare/containers —— Sandbox 已经全包
Hono / Itty Router —— routeAgentRequest + 几个 if-else 够了
ORM(Drizzle / Prisma)—— this.sql 写起来直观
第三方 vector DB —— 用 Vectorize
前端框架完整集 —— 示例代码用原生 useAgent + useAgentChat,不绑 React app

版本快照

// package.json(全书结束时的依赖)
{
  "name": "agent-coder",
  "version": "0.10.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "deploy:staging": "wrangler deploy --env staging",
    "deploy:prod": "wrangler deploy --env production",
    "tail": "wrangler tail",
    "types": "wrangler types env.d.ts --include-runtime false",
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "dependencies": {
    "@cloudflare/think": "^0.4",
    "@cloudflare/sandbox": "^0.9",
    "@cloudflare/codemode": "^0.3",
    "@cloudflare/ai-chat": "^0.5",
    "agents": "^0.11",

    "ai": "^6",
    "workers-ai-provider": "^3",
    "zod": "^3",

    "@octokit/core": "^6",
    "@octokit/auth-app": "^7",

    "jose": "^5"
  },
  "devDependencies": {
    "wrangler": "^4",
    "@cloudflare/workers-types": "^4.20260401.0",
    "@cloudflare/vitest-pool-workers": "latest",
    "vitest": "^2.1.0",
    "typescript": "^5.6.0"
  }
}

@cloudflare/think 在 2026-04 是 experimental preview,API 已稳定但还会演进;锁 ^0.4 让 patch 自由升,避免被 0.5 的破坏性改动打到。agents 跟着 Workers runtime 同步,锁 ^0.11。ai 主版本 6 已是新 streamText 协议,不要混 v4。

tsconfig.json 快照

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2024",
    "module": "ES2024",
    "moduleResolution": "bundler",
    "lib": ["ES2024", "WebWorker"],
    "types": ["@cloudflare/workers-types"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "noEmit": true
  },
  "include": ["src/**/*", "worker-configuration.d.ts"],
  "exclude": ["node_modules", "dist"]
}

要点:不要开 experimentalDecorators(Agents / Think 用 TC39 标准装饰器);moduleResolution: "bundler" 让 @cloudflare/think/tools/workspace 这种 subpath import 能解;types: ["@cloudflare/workers-types"] 让 Ai / DurableObjectNamespace 等全局类型生效。

沙箱镜像

第 6 章起 Sandbox 用的基础镜像。@cloudflare/sandbox 已经把 shell / 文件系统 / Python 解释器 / PTY 都封好,镜像里只装语言级别的工具:

# container/Dockerfile
FROM node:20-bookworm

RUN apt-get update && apt-get install -y --no-install-recommends \
      git python3 python3-pip python3-venv \
      curl ca-certificates build-essential \
    && rm -rf /var/lib/apt/lists/*

RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
    && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
      > /etc/apt/sources.list.d/github-cli.list \
    && apt-get update && apt-get install -y gh \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace
CMD ["bash", "-l"]

选 node:20-bookworm 而非 alpine:musl libc 兼容性问题坑过太多次,bookworm 多 ~50 MB 但稳。

监控建议

你想知道	用什么
谁在用、用得多深、怎么流失	PostHog(订阅 `agents:message` channel,转 PostHog)
错误率、p95 latency、worker CPU 时间	Cloudflare dashboard 自带 Analytics
一条 LLM 请求的 prompt / response / 成本	AI Gateway dashboard(走 `env.AI.run(..., { gateway })` 自动落表)+ Langfuse / Helicone(可选,深度 trace)
历史回查、合规留档	Logpush → R2(成本最低,SQL on R2 / DuckDB 查)
告警	Cloudflare 内置 alerts,接 Slack / PagerDuty

不要一次接四个,从 PostHog + AI Gateway + Logpush 开始,LLM trace 等真痛了再加。

升级建议

按这个顺序检查变更:

@cloudflare/think:目前 0.x,升 minor 必看 CHANGELOG —— 钩子签名仍可能变。
@cloudflare/sandbox:GA 后 d.ts 行号会稳;升级看 outboundByHost / interceptOutboundHttp 的官方落地状态。
@cloudflare/codemode:跟 Think 的 peerDeps 绑死(>=0.3.4 <1.0.0),一起升。
agents:看 Agent / AIChatAgent / AgentWorkflow 的钩子签名;Facets sub-agent 的字段 v0.11 起稳定。
ai:v5 → v6 已经过渡完;若你在 v5,先升 ai@6 并测 streamText。
wrangler:compatibility_date 不要漂太久,某些 binding 行为会被 frozen 在老语义。

升级动作就一条:npm outdated → 改 package.json → 在 staging 跑 24 小时 → 没事再上 prod。

Keyboard shortcuts