Code Mode API 参考

Code Mode 提供六个包入口点。从对应入口点导入框架特定 API：

入口点	用途
`@cloudflare/codemode`	运行时、连接器、Workers 执行器及与框架无关的工具
`@cloudflare/codemode/ai`	AI SDK 工具与连接器适配器
`@cloudflare/codemode/mcp`	Model Context Protocol（MCP）服务器包装器
`@cloudflare/codemode/tanstack-ai`	TanStack AI 工具与适配器
`@cloudflare/codemode/browser`	浏览器工具描述符与 iframe 执行器
`@cloudflare/codemode/vite`	用于连接器发现与 Worker 导出的 Vite 插件

`@cloudflare/codemode`

主入口点无需安装可选的 AI SDK、TanStack AI 或 Zod peer 依赖。

运行时构造

`createCodemodeRuntime()`

function createCodemodeRuntime(
	options: CreateCodemodeRuntimeOptions,
): CodemodeRuntimeHandle;

创建命名 Code Mode 运行时的主机侧控制平面。

CreateCodemodeRuntimeOptions 包含以下字段：

字段	类型	必需	描述
`ctx`	`DurableObjectState`	是	托管运行时 facet 的 Durable Object 状态。
`connectors`	`CodemodeConnector[]`	是	作为沙箱全局暴露的连接器。连接器名称必须唯一，`codemode` 为保留名。
`executor`	`Executor`	是	运行生成代码的沙箱。
`name`	`string`	否	持久运行时标识。默认为 `"default"`。有效字符为字母、数字、`_`、`-`、`.`。
`maxExecutions`	`number`	否	新运行开始时保留的终态记录数。默认为 `50`。运行中与已暂停的执行不会被修剪。
`transformResult`	`TransformResult`	否	重塑返回给模型的完成结果。审计轨迹保留未修改结果。

interface CodemodeRuntimeHandle {
	tool(
		options?: CodemodeRuntimeToolOptions,
	): Tool<ProxyToolInput, ProxyToolOutput>;
	execute(input: ProxyToolInput): Promise<ProxyToolOutput>;
	search(query: string): Promise<SearchOutput>;
	describe(target: string): Promise<DescribeOutput>;
	approve(options: CodemodeApproveOptions): Promise<ProxyToolOutput>;
	reject(options: CodemodeRejectOptions): Promise<boolean>;
	rollback(options: CodemodeRollbackOptions): Promise<void>;
	pending(executionId?: string): Promise<PendingAction[]>;
	expirePaused(options?: CodemodeExpireOptions): Promise<string[]>;
	executions(limit?: number): Promise<ExecutionState[]>;
	deleteExecution(id: string): Promise<boolean>;
	pruneExecutions(keep?: number): Promise<number>;
	saveSnippet(name: string, options: SaveSnippetOptions): Promise<Snippet>;
	snippets(): Promise<Snippet[]>;
	deleteSnippet(name: string): Promise<boolean>;
}

句柄方法效果如下：

方法	效果
`tool(options?)`	返回提供给模型的 AI SDK 工具。`description` 替换默认描述。使用默认描述时 `connectorHints` 为每个连接器添加一行提示。
`execute({ code })`	直接运行代码，无需将运行时适配为 AI SDK 工具。结果可完成、暂停待审批或返回错误状态。
`search(query)`	搜索连接器方法与已保存代码片段，不运行沙箱代码。
`describe(target)`	返回连接器、方法或已保存代码片段的按需 TypeScript 文档。
`approve({ executionId })`	通过重放恢复已暂停的执行。结果可完成、再次暂停或返回错误。不会复活非暂停执行。
`reject({ seq, executionId })`	拒绝一个待处理操作并终止执行。若操作不再待处理则返回 `false`。不会回滚更早操作。
`rollback({ executionId })`	按相反调用顺序调用可用 `revert` 函数。缺失连接器与无 `revert` 的方法仍保持已应用。失败后仍尝试后续还原。
`pending(executionId?)`	列出待处理操作。无 ID 时合并所有已暂停执行的操作。
`expirePaused({ maxAgeMs? })`	终止过期的已暂停或运行中执行并返回其 ID。默认期限为 24 小时。
`executions(limit?)`	返回审计记录，最新在前。
`deleteExecution(id)`	删除一条审计记录。对非终态执行也会释放资源。返回记录是否存在。
`pruneExecutions(keep?)`	删除较旧终态记录并返回删除数量。默认保留 `50`。
`saveSnippet(name, options)`	将 `options.executionId` 的代码保存为可复用代码片段。接受任意执行状态，应用应先验证成功完成。同名会替换。
`snippets()`	返回已保存代码片段，按名称排序。
`deleteSnippet(name)`	删除代码片段并返回是否存在。

方法选项类型：

type CodemodeRuntimeToolOptions = {
	description?: string;
	connectorHints?: Record<string, string>;
};

type CodemodeApproveOptions = { executionId: string };
type CodemodeRejectOptions = { seq: number; executionId: string };
type CodemodeRollbackOptions = { executionId: string };
type CodemodeExpireOptions = { maxAgeMs?: number };

`CodemodeRuntime`

class CodemodeRuntime extends DurableObject<unknown> {
	constructor(ctx: DurableObjectState, env: unknown);
}

CodemodeRuntime 是运行时句柄背后的持久 facet。Vite 插件从 Worker 入口模块导出此类。应用代码应使用 createCodemodeRuntime()，而非直接构造 facet。

主入口点还导出以下运行时常量：

常量	值	用途
`DEFAULT_MAX_EXECUTIONS`	`50`	默认终态执行保留数量
`DEFAULT_PAUSED_TTL_MS`	`86400000`	默认过期执行期限（毫秒）（24 小时）
`MAX_DURABLE_VALUE_BYTES`	`1000000`	单个持久值可序列化 JavaScript 字符串长度上限

运行时工具输入与输出

type ProxyToolInput = { code: string };

type ProxyToolOutput =
	| {
			status: "completed";
			executionId: string;
			result: unknown;
			logs?: string[];
	  }
	| {
			status: "paused";
			executionId: string;
			pending: PendingAction[];
	  }
	| {
			status: "error";
			executionId: string;
			error: string;
			logs?: string[];
	  };

type TransformResult = (result: unknown) => unknown | Promise<unknown>;

沙箱与重放错误使用 error 输出变体。它们不会通过模型工具调用抛出。

Execution 记录

type ExecutionStatus =
	| "running"
	| "paused"
	| "completed"
	| "error"
	| "rejected"
	| "rolled_back";

type ExecutionState = {
	id: string;
	code: string;
	status: ExecutionStatus;
	log: ToolLogEntry[];
	result?: unknown;
	error?: string;
	logs?: string[];
	connectors?: string[];
	createdAt: number;
	updatedAt: number;
};

type ToolLogEntry = {
	seq: number;
	connector: string;
	method: string;
	args: unknown;
	result?: unknown;
	requiresApproval: boolean;
	ephemeral?: boolean;
	state: "executing" | "applied" | "pending" | "reverted" | "error";
};

type PendingAction = {
	executionId: string;
	seq: number;
	connector: string;
	method: string;
	args: unknown;
};

createdAt 与 updatedAt 为纪元毫秒。瞬时日志条目来自 replay: "reexecute" 的连接器工具。其结果不存储，恢复时重新执行该调用。

Runtime 决策类型：

type ToolDecision =
	| { kind: "replay"; result: unknown }
	| { kind: "execute"; seq: number }
	| { kind: "pause"; seq: number };

沙箱 `codemode` API

runtime.tool() 向生成的沙箱代码注入 codemode 全局。

declare const codemode: {
	search(query: string): Promise<SearchOutput>;
	describe(target: string): Promise<DescribeOutput>;
	step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
	run(name: string, input?: unknown): Promise<unknown>;
};

沙箱方法行为如下：

方法	描述
`search(query)`	搜索连接器方法与已保存代码片段。结果排序并限制为 `50`。
`describe(target)`	返回连接器、`connector.method` 或代码片段名称的生成 TypeScript。
`step(name, fn)`	运行闭包一次并记录结果。重放返回记录结果而不再次运行闭包。
`run(name, input?)`	运行已保存代码片段。缺失代码片段或记录的连接器解析为带 `error` 属性的对象。

对不通过连接器的非确定性或有副作用沙箱工作使用 step()。执行可能暂停时连接器调用应顺序执行。并发调用可能以不同顺序到达重放游标。

发现输出类型如下：

type SearchResult = {
	path: string;
	connector: string;
	method: string;
	description?: string;
	requiresApproval?: boolean;
	kind: "method" | "snippet";
	score: number;
};

type SearchOutput = {
	results: SearchResult[];
	total: number;
	truncated: boolean;
};

type DescribeOutput = {
	path: string;
	description?: string;
	requiresApproval?: boolean;
	types: string;
	kind: "connector" | "method" | "snippet";
};

当连接器方法在执行前暂停时，requiresApproval 为 true。对于不需要审批的方法以及代码片段，该字段会被省略。

代码片段类型

interface SaveSnippetOptions {
	description?: string;
	inputSchema?: unknown;
	executionId: string;
}

interface Snippet {
	name: string;
	description: string;
	code: string;
	savedAt: number;
	inputSchema?: unknown;
	connectors?: string[];
}

connectors 记录源执行启动时配置的每个命名空间。savedAt 包含纪元毫秒时间戳。调用 saveSnippet() 前，请确认源 ExecutionState.status 为 completed。

Executor API

`Executor`

interface Executor {
	execute(
		code: string,
		providersOrFns:
			| ResolvedProvider[]
			| Record<string, (...args: unknown[]) => Promise<unknown>>,
		options?: ExecuteOptions,
	): Promise<ExecuteResult>;
}

自定义执行器应在 ExecuteResult.error 中报告失败，而非抛出异常。

interface ExecuteResult {
	result: unknown;
	error?: string;
	logs?: string[];
}

interface ResolvedProvider {
	name: string;
	fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
	prelude?: string;
}

interface ConnectorBinding {
	name: string;
	binding: {
		callTool(method: string, args: unknown): Promise<unknown>;
	};
}

interface ExecuteOptions {
	connectors?: ConnectorBinding[];
}

传入函数记录而非 ResolvedProvider[] 已弃用。会创建一个名为 codemode 的提供方。

`DynamicWorkerExecutor`

class DynamicWorkerExecutor implements Executor {
	constructor(options: DynamicWorkerExecutorOptions);
	execute(
		code: string,
		providersOrFns:
			| ResolvedProvider[]
			| Record<string, (...args: unknown[]) => Promise<unknown>>,
		options?: ExecuteOptions,
	): Promise<ExecuteResult>;
}

DynamicWorkerExecutorOptions 包含以下字段：

字段	类型	必需	默认值	描述
`loader`	`WorkerLoader`	是	—	用于创建隔离 Worker 的 Worker Loader 绑定。
`timeout`	`number`	否	`60000`	执行超时时间（毫秒）。
`globalOutbound`	`Fetcher \| null`	否	`null`	出站网络策略。`null` 阻止访问。`Fetcher` 接收所有出站请求。
`modules`	`Record<string, string>`	否	`{}`	按 import specifier 索引的模块源码。保留键 `executor.js` 会被忽略。
`bindings`	`Record<string, unknown>`	否	`{}`	注入每个沙箱 Worker 的额外环境绑定。

执行器会验证提供方与连接器命名空间。名称必须是有效的 JavaScript 标识符、唯一，且不得遮蔽执行器全局变量。

`ToolDispatcher`

class ToolDispatcher extends RpcTarget {
	constructor(fns: Record<string, (...args: unknown[]) => Promise<unknown>>);
	call(name: string, argsJson?: string): Promise<string>;
}

ToolDispatcher 是 DynamicWorkerExecutor 使用的 Workers RPC 桥接。call() 接受序列化的位置参数，并返回序列化的结果或错误信封。

`runCode()`

function runCode(options: {
	code: string;
	executor: Executor;
	providers: ResolvedProvider[];
	connectors?: ConnectorBinding[];
}): Promise<{ result: unknown; logs?: string[] }>;

规范化并执行代码。若存在 ExecuteResult.error，runCode() 会抛出包含已捕获 console 输出的 Error。

工具提供方

interface ToolProvider {
	name?: string;
	tools: ToolDescriptors | ToolSet | SimpleToolRecord;
	types?: string;
}

工具提供方包含以下字段：

字段	描述
`name`	沙箱命名空间。默认为 `codemode`。
`tools`	工具描述符、AI SDK `ToolSet`，或包含 `execute` 的记录。
`types`	展示给模型的 TypeScript 声明。省略时由 Code Mode 生成。

function resolveProvider(provider: ToolProvider): ResolvedProvider;

主入口点实现不会按 schema 验证输入。会排除 needsApproval 为 true 或函数的工具。持久化审批流程请使用运行时连接器。

Connector 基类

`CodemodeConnector`

abstract class CodemodeConnector<
	Env = unknown,
	Props = unknown,
> extends WorkerEntrypoint<Env, Props> {
	constructor(ctx: DurableObjectState | ExecutionContext, env: Env);

	abstract name(): string;
	protected instructions(): string | undefined;
	protected abstract tools(): ConnectorTools | Promise<ConnectorTools>;
	protected tool(name: string, tool: ConnectorTool): ConnectorTool;

	describe(): Promise<ConnectorDescription>;
	executeTool(
		method: string,
		args: unknown,
		ctx?: ToolExecuteContext,
	): Promise<unknown>;
	revertAction(
		method: string,
		args: unknown,
		result: unknown,
		ctx?: ToolExecuteContext,
	): Promise<boolean>;
	onPassEnd(executionId: string, status: PassEndStatus): Promise<void>;
	disposeExecution(
		executionId: string,
		status: ExecutionEndStatus,
	): Promise<void>;
	getTypeScriptTypes(): Promise<string>;
}

连接器作者需实现或覆盖以下钩子：

钩子	必需	描述
`name()`	是	返回唯一的沙箱命名空间。
`instructions()`	否	返回 `describe()` 包含的连接器指引。
`tools()`	是	返回连接器工具记录。派生连接器需实现此钩子。
`tool(name, tool)`	否	装饰已解析的工具。用于为派生工具添加审批、重放或还原行为。
`onPassEnd(executionId, status)`	否	释放每次执行趟的资源。每次执行趟后运行，包括已暂停的执行趟。
`disposeExecution(executionId, status)`	否	在终态转换后释放执行资源。暂停时不会运行。

生命周期钩子应幂等、不依赖实例内存，且不应抛出异常。在终态执行趟上，onPassEnd() 在 disposeExecution() 之前运行。

基类从工具记录派生 describe()、executeTool()、revertAction() 与 getTypeScriptTypes()。连接器作者无需实现这些方法。

连接器工具类型

type ConnectorTool = {
	description?: string;
	inputSchema?: JSONSchema7;
	outputSchema?: JSONSchema7;
	requiresApproval?: boolean;
	replay?: "log" | "reexecute";
	execute: (
		args: unknown,
		ctx?: ToolExecuteContext,
	) => Promise<unknown> | unknown;
	revert?: (
		args: unknown,
		result: unknown,
		ctx?: ToolExecuteContext,
	) => Promise<void> | void;
};

type ConnectorTools = Record<string, ConnectorTool>;
type ToolExecuteContext = { executionId: string };

inputSchema 默认为开放对象。requiresApproval: true 会在执行前暂停。replay: "reexecute" 跳过持久结果存储，每次恢复时重新执行调用。这两个选项不能组合使用。

revert 为 runtime.rollback() 提供补偿。可应用于任意工具，无论是否需要审批。

`McpConnector`

abstract class McpConnector<
	Env = unknown,
	Props = unknown,
> extends CodemodeConnector<Env, Props> {
	protected abstract createConnection():
		| McpConnectionLike
		| Promise<McpConnectionLike>;
	protected toolName(tool: McpTool): string;
}

McpConnector 将每个 MCP 工具转换为连接器方法。toolName() 默认为 sanitizeToolName(tool.name)。可覆盖以解决命名冲突。

interface McpConnectionLike {
	name?: string;
	client: Pick<Client, "callTool">;
	instructions?: string;
	tools?: McpTool[];
	fetchTools?: () => Promise<McpTool[]>;
}

当 tools 数组非空时使用该数组。否则在提供时调用 fetchTools()。MCP 错误结果会变为抛出的连接器错误。结构化内容优先于文本内容返回。

`OpenApiConnector`

abstract class OpenApiConnector<
	Env = unknown,
	Props = unknown,
> extends CodemodeConnector<Env, Props> {
	protected abstract spec():
		| Record<string, unknown>
		| Promise<Record<string, unknown>>;
	protected abstract request(options: OpenApiRequestOptions): Promise<unknown>;
	protected exposeSpec(): boolean;
}

OpenApiConnector 为每个 OpenAPI 操作创建一个方法。存在时会使用已清理的 operationId，否则回退到基于 HTTP 方法与路径的名称。重复操作以及为 request 或 spec 保留的名称会被跳过。

每个 OpenAPI 连接器都暴露底层 request 方法。exposeSpec() 默认为 false。返回 true 可同时暴露 spec。

type OpenApiRequestOptions = {
	path: string;
	method?: string;
	params?: Record<string, unknown>;
	body?: unknown;
	headers?: Record<string, string>;
};

派生操作工具会替换路径参数。查询值作为 params 传递，标头值作为 headers 传递，JSON 请求数据作为 body 传递。

Connector 生命周期与描述类型

type ExecutionEndStatus = "completed" | "error" | "rejected" | "rolled_back";

type PassEndStatus = ExecutionEndStatus | "paused";

type ToolAnnotations = {
	requiresApproval?: boolean;
	replay?: "log" | "reexecute";
};

type ConnectorDescription = {
	name: string;
	instructions?: string;
	descriptors: JsonSchemaToolDescriptors;
	annotations?: Record<string, ToolAnnotations>;
};

JSON Schema 工具函数

interface JsonSchemaToolDescriptor {
	description?: string;
	inputSchema: JSONSchema7;
	outputSchema?: JSONSchema7;
}

type JsonSchemaToolDescriptors = Record<string, JsonSchemaToolDescriptor>;

function generateTypesFromJsonSchema(tools: JsonSchemaToolDescriptors): string;

function jsonSchemaToType(schema: JSONSchema7, typeName: string): string;

generateTypesFromJsonSchema() 返回 codemode 命名空间的声明。生成声明前会清理工具名称。不支持的 schema 会降级为 unknown，而不会导致生成失败。

代码与输出工具函数

主入口点提供以下代码与结果工具函数：

函数	签名	行为
`sanitizeToolName`	`(name: string) => string`	替换常见分隔符、移除无效字符、为数字开头名称加前缀，并为 JavaScript 保留字加后缀。
`normalizeCode`	`(code: string) => string`	将常见模型输出形式转换为 async 箭头函数。还会移除支持的 Markdown 围栏。
`truncateResponse`	`(text: string, options?: TruncateOptions) => string`	将文本截断到字符预算并附加大小标记。
`truncateResult`	`(value: unknown, options?: TruncateOptions) => unknown`	保留小型结构化值。过大的可序列化值会变成截断后的 JSON 文本。

type TruncateOptions = {
	maxChars?: number;
	maxTokens?: number;
};

默认预算为 6000 个估算 token（按每 token 四字符计算）。maxChars 会覆盖推导出的字符预算。

`@cloudflare/codemode/ai`

此入口点需要 ai 与 zod peer 依赖。

`createCodeTool()`

function createCodeTool(
	options: CreateCodeToolOptions,
): Tool<CodeInput, CodeOutput>;

interface CreateCodeToolOptions {
	tools: ToolProviderTools | ToolProvider[];
	executor: Executor;
	description?: string;
}

type CodeInput = { code: string };
type CodeOutput = { result: unknown; logs?: string[] };

description 可包含 {{types}}。Code Mode 会用生成的声明替换该 token。原始工具记录会成为一个名为 codemode 的提供方。数组形式可接受多个提供方命名空间。

needsApproval 为 true 或函数的工具会被排除。此 API 不会暂停。持久化审批处理请使用 createCodemodeRuntime() 与连接器。

AI SDK 提供方工具函数

AI SDK 入口点提供以下工具提供方工具函数：

导出	签名	描述
`aiTools`	`(tools: ToolDescriptors \| ToolSet) => ToolProvider`	将 AI SDK 工具包装为默认提供方。
`generateTypes`	`(tools: ToolDescriptors \| ToolSet, namespace?: string) => string`	从 AI SDK 或 Zod schema 生成声明。命名空间默认为 `codemode`。
`resolveProvider`	`(provider: ToolProvider) => ResolvedProvider`	过滤需审批的工具，在可用时用 AI SDK `asSchema()` 验证输入，并提取可执行函数。

interface ToolDescriptor {
	description?: string;
	inputSchema: ZodType;
	outputSchema?: ZodType;
	execute?: (args: unknown) => Promise<unknown>;
}

type ToolDescriptors = Record<string, ToolDescriptor>;

`ToolSetConnector`

class ToolSetConnector extends CodemodeConnector {
	constructor(
		ctx: DurableObjectState | ExecutionContext,
		options: ToolSetConnectorOptions,
	);
}

function toolSetConnector(
	ctx: DurableObjectState | ExecutionContext,
	options: ToolSetConnectorOptions,
): ToolSetConnector;

interface ToolSetConnectorOptions {
	name?: string;
	instructions?: string;
	tools: ToolSet;
}

命名空间默认为 tools。连接器会排除没有 execute 函数的工具。needsApproval: true 与函数形式的 needsApproval 映射为持久连接器审批。needsApproval: false 无需审批即可执行。AI SDK schema 会在执行前验证输入。

`@cloudflare/codemode/mcp`

此入口点需要 MCP SDK 与 Zod peer 依赖。

`codeMcpServer()`

interface CodeMcpServerOptions {
	server: McpServer;
	executor: Executor;
	description?: string;
}

function codeMcpServer(options: CodeMcpServerOptions): Promise<McpServer>;

用单个 code 工具包装现有 MCP 服务器。包装器通过内存传输连接源服务器，发现其工具，并在执行器内将这些工具暴露为 codemode 上的方法。

自定义描述可包含 {{types}}，包装器会用生成的 TypeScript 声明替换它。也可包含 {{example}}，包装器会基于第一个上游 MCP 工具替换为示例调用。返回的 MCP 值按以下顺序解包：兼容 toolResult、MCP 错误、structuredContent、纯文本内容，然后是原始混合内容结果。

`openApiMcpServer()`

interface OpenApiMcpServerOptions {
	spec: Record<string, unknown>;
	executor: Executor;
	request: (options: RequestOptions) => Promise<unknown>;
	name?: string;
	version?: string;
	description?: string;
}

interface RequestOptions {
	method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
	path: string;
	query?: Record<string, string | number | boolean | undefined>;
	body?: unknown;
	contentType?: string;
	rawBody?: boolean;
}

function openApiMcpServer(options: OpenApiMcpServerOptions): McpServer;

创建包含两个工具的 MCP 服务器：

MCP 工具	沙箱 API	用途
`search`	`codemode.spec()`	针对 OpenAPI 文档运行代码。代码接收文档前会解析本地 `$ref`。
`execute`	`codemode.spec()` 与 `codemode.request(options)`	运行可检查文档并调用宿主提供的 request 函数的代码。

name 默认为 openapi。version 默认为 1.0.0。宿主 request 函数将凭据保留在沙箱外。文本响应限制约为 6,000 token，截断时会包含截断标记。

search 与 execute 工具描述使用固定示例片段。与 codeMcpServer() 不同，此函数不支持 {{types}} 或 {{example}} 占位符。可选 description 会追加到 execute 工具描述末尾。

`@cloudflare/codemode/tanstack-ai`

此入口点需要 @tanstack/ai 与 zod peer 依赖。

`createCodeTool()`

function createCodeTool(options: CreateCodeToolOptions): ServerTool;

选项、CodeInput 与 CodeOutput 与 /ai 入口点一致。返回的 ServerTool 可传给 TanStack AI chat()。

TanStack AI 提供方工具函数

TanStack AI 入口点提供以下工具提供方工具函数：

导出	签名	描述
`tanstackTools`	`(tools: TanStackTool[], name?: string) => ToolProvider`	将 TanStack AI 工具包装为提供方。仅带 `execute` 函数的工具可调用。命名空间默认为 `codemode`。
`generateTypes`	`(tools: TanStackTool[], namespace?: string) => string`	将支持的 TanStack AI schema 转换为 JSON Schema，再生成声明。
`resolveProvider`	`(provider: ToolProvider) => ResolvedProvider`	解析与框架无关的提供方，不进行 schema 验证。
`normalizeProviders`	`(tools: ToolProviderTools \| ToolProvider[]) => ToolProvider[]`	将原始工具转换为单元素提供方数组。

此入口点还导出 DEFAULT_DESCRIPTION。tanstackTools() 会排除 needsApproval: true 或函数形式 needsApproval 的工具。needsApproval: false 的工具仍可调用。

`@cloudflare/codemode/browser`

浏览器入口点使用浏览器 API 与纯 JSON Schema。不需要 AI SDK 或 Zod。

`createBrowserCodeTool()`

function createBrowserCodeTool(
	options: CreateBrowserCodeToolOptions,
): BrowserCodeToolDescriptor;

interface CreateBrowserCodeToolOptions {
	tools:
		| JsonSchemaExecutableToolDescriptor[]
		| JsonSchemaExecutableToolDescriptors;
	executor?: Executor;
	description?: string;
}

数组形式的工具必须包含 name。对象形式的工具以每条记录键作为名称。执行器默认为新的 IframeSandboxExecutor。

tools 选项也接受带 needsApproval?: boolean | ((...args: unknown[]) => unknown) 的描述符。needsApproval: true 或函数形式 needsApproval 的工具会被排除。needsApproval: false 的工具仍可调用。JSON Schema 提供面向模型的声明，但不执行运行时验证。

interface JsonSchemaExecutableToolDescriptor extends JsonSchemaToolDescriptor {
	name?: string;
	execute: (args: Record<string, unknown>) => Promise<unknown>;
}

type JsonSchemaExecutableToolDescriptors = Record<
	string,
	JsonSchemaExecutableToolDescriptor
>;

返回的描述符形状如下：

interface BrowserCodeToolDescriptor {
	name: string;
	description: string;
	inputSchema: {
		type: "object";
		properties: {
			code: { type: "string"; description: string };
		};
		required: ["code"];
	};
	outputSchema: {
		type: "object";
		properties: {
			result: { description: string };
			logs: {
				type: "array";
				items: { type: "string" };
				description: string;
			};
		};
		required: ["result"];
	};
	execute(args: CodeInput): Promise<CodeOutput>;
}

`IframeSandboxExecutor`

class IframeSandboxExecutor implements Executor {
	constructor(options?: IframeSandboxExecutorOptions);
	execute(
		code: string,
		providersOrFns:
			| ResolvedProvider[]
			| Record<string, (...args: unknown[]) => Promise<unknown>>,
	): Promise<ExecuteResult>;
}

interface IframeSandboxExecutorOptions {
	timeout?: number;
	csp?: string;
}

iframe 执行器接受以下选项：

字段	默认值	描述
`timeout`	`30000`	最大执行时间（毫秒）。无法抢占阻塞浏览器事件循环的同步循环。
`csp`	`default-src 'none'; script-src 'unsafe-inline' 'unsafe-eval';`	应用于沙箱 iframe 文档的内容安全策略（CSP）。

每次执行会创建带 sandbox="allow-scripts" 的隐藏 iframe。工具调用通过 nonce 作用域的 postMessage 消息跨越 iframe 边界。成功、错误或超时后会移除 iframe。

此入口点还导出与框架无关的 Executor、ExecuteResult 与 ResolvedProvider 类型。并重新导出 JsonSchemaToolDescriptor 与 JsonSchemaToolDescriptors。

`@cloudflare/codemode/vite`

Vite 入口点有一个默认导出：

function codemodeVitePlugin(): Plugin;

插件会将 export { CodemodeRuntime } from "@cloudflare/codemode" 追加到 Worker 入口模块（src/server.ts、src/index.ts 或 src/worker.ts）。这使运行时 facet 可作为 ctx.exports.CodemodeRuntime 使用，createCodemodeRuntime() 需要此导出。

若入口模块已导出 CodemodeRuntime，插件不会修改该模块。连接器类无需特殊文件名或导入语法——正常导入并将实例传给运行时即可。

不使用插件时，请手动添加导出：

export { CodemodeRuntime } from "@cloudflare/codemode";

连接器导入可指向单个连接器文件或目录。目录导入会重新导出该目录下所有匹配的连接器文件。

Code Mode API 参考

@cloudflare/codemode

运行时构造

createCodemodeRuntime()

CodemodeRuntime

运行时工具输入与输出

Execution 记录

沙箱 codemode API

代码片段类型

Executor API

Executor

DynamicWorkerExecutor

ToolDispatcher

runCode()

工具提供方

Connector 基类

CodemodeConnector

连接器工具类型

McpConnector

OpenApiConnector

Connector 生命周期与描述类型

JSON Schema 工具函数

代码与输出工具函数

@cloudflare/codemode/ai

createCodeTool()

AI SDK 提供方工具函数

ToolSetConnector

@cloudflare/codemode/mcp

codeMcpServer()

openApiMcpServer()

@cloudflare/codemode/tanstack-ai

createCodeTool()

TanStack AI 提供方工具函数

@cloudflare/codemode/browser

createBrowserCodeTool()

IframeSandboxExecutor

@cloudflare/codemode/vite

`@cloudflare/codemode`

`createCodemodeRuntime()`

`CodemodeRuntime`

沙箱 `codemode` API

`Executor`

`DynamicWorkerExecutor`

`ToolDispatcher`

`runCode()`

`CodemodeConnector`

`McpConnector`

`OpenApiConnector`

`@cloudflare/codemode/ai`

`createCodeTool()`

`ToolSetConnector`

`@cloudflare/codemode/mcp`

`codeMcpServer()`

`openApiMcpServer()`

`@cloudflare/codemode/tanstack-ai`

`createCodeTool()`

`@cloudflare/codemode/browser`

`createBrowserCodeTool()`

`IframeSandboxExecutor`

`@cloudflare/codemode/vite`