03.1 三个硬前提
第一，Node 要 24+。Cloudflare Agents 的 dev 工具链认新版本。
第二，wrangler 是命令行核心。它负责本地开发、配置校验、部署上线。
第三，装饰器。Agent 用 @callable() 这类 TC39 标准装饰器。别开 experimentalDecorators，会静默破坏它。
03.2 tsconfig 与 vite 必配项
Starter 已经配好。手动建项目时，这两段不能少：
// tsconfig.json —— 继承 agents 的推荐配置
{ "extends": "agents/tsconfig" }
// vite.config.ts —— agents() 插件处理装饰器转译
import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";
import agents from "agents/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [agents(), react(), cloudflare()]
});
注意
如果看到@callable()方法调不动、报Method X is not callable，九成是装饰器没转译对。检查agents()插件在不在、tsconfig 有没有继承agents/tsconfig。
03.3 本地配置与密钥
本地开发，wrangler dev 读 .env。生产密钥用：
wrangler secret put OPENAI_API_KEY
非敏感变量放 wrangler.jsonc 的 vars，值必须是字符串，代码里自己 parseInt。
核心建议
.env一定加进.gitignore。密钥进了 Git 历史，比 Agent 崩了还难收拾。
环境配齐了。下一章进核心能力——先讲模型怎么接。