仅需三行代码，即可将您的 AI 代理从笨拙的工具调用者转变为高效的代码执行者。

为什么这会彻底改变一切

大语言模型擅长编写代码，但在工具调用方面却表现不佳。与其直接暴露数百种工具，不如为它们提供一个能够执行 TypeScript 代码并访问您整个工具集的单一工具。

Apple、Cloudflare 和 Anthropic 都认为，与传统的先传递函数信息再提取 JSON 进行调用的方式相比，Code-Mode 是一种更高效的工具调用方法。

基准测试

独立的 Python 基准研究 证实了其性能优势，在每天 1,000 个场景下可节省 $9,536/年：

场景复杂度	传统方式	Code Mode	提升幅度
简单（2-3 个工具）	3 次迭代	1 次执行	快 67%
中等（4-7 个工具）	8 次迭代	1 次执行	快 75%
复杂（8 个以上工具）	16 次迭代	1 次执行	快 88%

为什么 Code Mode 占据主导地位：

批处理优势 - 单一代码块取代多次 API 调用
认知效率 - 大语言模型擅长代码生成而非工具编排
计算效率 - 无需在每次操作之间重新处理上下文

开始使用

三步快速入门

import { CodeModeUtcpClient } from '@utcp/code-mode';

const client = await CodeModeUtcpClient.create();                    // 1. 初始化
await client.registerManual({ name: 'github', /* MCP 配置 */ });  // 2. 添加工具  
const { result } = await client.callToolChain(`/* TypeScript */`);   // 3. 执行代码

就这么简单。您的 AI 代理现在只需一次请求就能执行复杂的流程，而不再需要发出数十次请求。

您将获得的内容

渐进式工具发现

// 代理动态发现工具，只加载所需内容
const tools = await client.searchTools('github pull request');
// 从 500 种工具定义变为仅需 3 种相关工具

自然的代码执行

const { result, logs } = await client.callToolChain(`
  // 在一次请求中串联多个操作
  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const reviews = await github.get_pull_request_reviews({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  
  // 在沙盒环境中高效处理数据
  return {
    title: pr.title,
    commentCount: comments.length,
    approvals: reviews.filter(r => r.state === 'APPROVED').length
  };
`);
// 一次 API 调用即可替代 15 次以上的传统工具调用

自动生成的 TypeScript 接口

namespace github {
  interface get_pull_requestInput {
    /** 仓库所有者 */
    owner: string;
    /** 仓库名称 */ 
    repo: string;
    /** 拉取请求编号 */
    pull_number: number;
  }
}

企业级就绪

• 安全的 VM 沙箱 – Node.js 隔离机制防止未经授权的访问
• 超时保护 – 可配置的执行限制防止失控代码运行
• 全面可观性 – 完整的控制台输出捕获和错误处理
• 零外部依赖 – 工具仅可通过注册的 UTCP/MCP 服务器访问
• 运行时内省 – 动态接口发现支持自适应工作流

如果您在企业工作并需要支持，请在此预约咨询 这里。

通用协议支持

适用于 任何工具生态系统：

协议	描述	使用方式
MCP	模型上下文协议服务器	call_template_type: 'mcp'
HTTP	具有自动发现功能的 REST API	call_template_type: 'http'
文件	本地 JSON/YAML 配置	call_template_type: 'file'
CLI	命令行工具执行	call_template_type: 'cli'

安装

npm install @utcp/code-mode

更轻松：开箱即用的 MCP 服务器

想无需任何设置就使用 Code Mode 吗？ 使用我们的即插即用 MCP 服务器，配合 Claude Desktop 或任何 MCP 客户端：

{
  "mcpServers": {
    "code-mode": {
      "command": "npx",
      "args": ["@utcp/code-mode-mcp"],
      "env": {
        "UTCP_CONFIG_FILE": "/path/to/your/.utcp_config.json"
      }
    }
  }
}

就这么简单！ 无需安装，也不需要掌握 Node.js 知识。Code Mode MCP 服务器 会自动：

• 通过 npx 下载并运行最新版本
• 从 JSON 文件加载您的工具配置
• 为 Claude Desktop 提供代码执行能力
• 为您提供用于 TypeScript 执行的 call_tool_chain MCP 工具

非常适合希望在 Claude Desktop 中使用 Code Mode 功能的非开发者！

直接使用 TypeScript

1. MCP 服务器集成

连接到任何模型上下文协议服务器：

import { CodeModeUtcpClient } from '@utcp/code-mode';

const client = await CodeModeUtcpClient.create();

// 连接到 GitHub 的 MCP 服务器
await client.registerManual({
  name: 'github',
  call_template_type: 'mcp',
  config: {
    mcpServers: {
      github: {
        command: 'docker',
        args: ['run', '-i', '--rm', '-e', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'mcp/github'],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN }
      }
    }
  }
});

2. 执行多步骤工作流

用一次代码执行替代15次以上的工具调用：

const { result, logs } = await client.callToolChain(`
  // 传统方式：4次独立的API往返 → 代码模式：1次执行
  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const reviews = await github.get_pull_request_reviews({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const files = await github.get_pull_request_files({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  
  // 在沙箱中处理数据（无需额外的令牌开销）
  const summary = {
    title: pr.title,
    state: pr.state,
    author: pr.user.login,
    stats: {
      comments: comments.length,
      reviews: reviews.length, 
      filesChanged: files.length,
      approvals: reviews.filter(r => r.state === 'APPROVED').length
    },
    topDiscussion: comments.slice(0, 3).map(c => ({
      author: c.user.login,
      preview: c.body.substring(0, 100) + '...'
    }))
  };
  
  console.log(\`PR "\${pr.title}" analysis complete\`);
  return summary;
`);

console.log('分析结果:', result);
// 控制台输出：'PR "修复hooks中的内存泄漏" 分析完成'

---

高级功能

多协议工具链

在一次执行中混合使用不同的工具生态系统：

// 注册多个工具源
await client.registerManual({ name: 'github', call_template_type: 'mcp', /* 配置 */ });
await client.registerManual({ name: 'slack', call_template_type: 'http', /* 配置 */ });
await client.registerManual({ name: 'db', call_template_type: 'file', file_path: './db-tools.json' }); // 从JSON文件加载UTCP手册

const result = await client.callToolChain(`
  // 从GitHub获取PR数据（MCP）
  const pr = await github.get_pull_request({ owner: 'company', repo: 'api', pull_number: 42 });
  
  // 从数据库查询部署状态（File）
  const deployment = await db.get_deployment_status({ pr_id: pr.id });
  
  // 向Slack发送通知（HTTP）
  await slack.post_message({
    channel: '#releases',
    text: \`PR #42 "\${pr.title}" 已部署到 \${deployment.environment}\`
  });
  
  return { pr: pr.title, environment: deployment.environment };
`);

运行时接口自省

工具可以动态发现并适应可用的接口：

const result = await client.callToolChain(`
  // 运行时发现可用工具
  console.log('可用接口:', __interfaces);
  
  // 获取特定工具接口进行验证
  const prInterface = __getToolInterface('github.get_pull_request');
  console.log('PR工具期望的接口:', prInterface);
  
  // 使用接口信息构建动态工作流
  const hasSlackTools = __interfaces.includes('namespace slack');
  if (hasSlackTools) {
    await slack.post_message({ channel: '#dev', text: '分析完成' });
  }
  
  return { toolsAvailable: hasSlackTools };
`);

上下文高效的数据处理

在不增加模型上下文负担的情况下处理大型数据集：

const result = await client.callToolChain(`
  // 获取大型数据集
  const allIssues = await github.list_repository_issues({ owner: 'facebook', repo: 'react' });
  console.log('已获取', allIssues.length, '个问题');
  
  // 在沙箱中高效处理
  const criticalBugs = allIssues
    .filter(issue => issue.labels.some(l => l.name === 'bug'))
    .filter(issue => issue.labels.some(l => l.name === '高优先级'))
    .map(issue => ({
      number: issue.number,
      title: issue.title,
      author: issue.user.login,
      年龄: Math.floor((Date.now() - new Date(issue.created_at)) / (1000 * 60 * 60 * 24))
    }))
    .sort((a, b) => b.年龄 - a.年龄);
  
  // 只返回处理后的摘要，而非1万条原始问题
  return {
    totalIssues: allIssues.length,
    criticalBugs: criticalBugs.slice(0, 10), // 最古老的10个严重问题
    summary: \`发现了 \${criticalBugs.length} 个严重问题，最老的已有 \${criticalBugs[0]?.年龄} 天\`
  };
`);

错误处理与可观ility

内置错误处理机制，提供完整的执行透明度：

const { result, logs } = await client.callToolChain(`
  try {
    console.log('开始多步工作流程...');
    
    const data = await external_api.fetch_data({ id: 'user-123' });
    console.log('数据获取成功');
    
    const processed = await data_processor.transform(data);
    console.warn('处理完成，共遇到', processed.warnings.length, '条警告');
    
    return processed;
  } catch (error) {
    console.error('工作流程失败:', error.message);
    throw error; // 将错误传递给外部错误处理机制
  }
`, 30000); // 30秒超时

// 完整的可观ility
console.log('结果:', result);
console.log('执行日志:', logs);
// ['开始多步工作流程...', '数据获取成功', '[WARN] 处理完成，共遇到2条警告']

自定义超时

为不同类型的负载配置执行限制：

// 快速操作（5秒）
const quickResult = await client.callToolChain(`return await ping.check();`, 5000);

// 重型数据处理（2分钟） 
const heavyResult = await client.callToolChain(`
  const bigData = await database.export_full_dataset();
  return await analytics.process_dataset(bigData);
`, 120000);

---

AI代理集成

可与任何AI框架即插即用。内置提示模板处理所有复杂性：

import { CodeModeUtcpClient } from '@utcp/code-mode';

const systemPrompt = `
你是一个拥有通过UTCP CodeMode访问工具能力的AI助手。
${CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE}
其他指令...
`;

// 适用于任何AI库
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: '分析microsoft/vscode中的最新PR' }
  ]
});

该模板提供了全面的指导：

• 工具发现工作流程（searchTools → __interfaces → callToolChain）
• 层次化访问模式（manual.tool()语法）
• 接口自省（__getToolInterface()）
• 错误处理和最佳实践

---

API参考

核心方法

callToolChain(code: string, timeout?: number)

以完整的工具访问权限和可观ability执行 TypeScript 代码。

• 返回值：包含执行结果和捕获的控制台输出的 {result: any, logs: string[]}
• 默认超时时间：30秒

getAllToolsTypeScriptInterfaces()

生成用于 IDE 集成的完整 TypeScript 接口。

• 返回值：包含所有命名空间接口定义的字符串

searchTools(query: string) (来自 UtcpClient)

通过自然语言查询发现工具。

• 返回值：包含描述和接口的相关工具数组

静态方法

CodeModeUtcpClient.create(root_dir?, config?)

创建新的客户端实例，可选配置。

CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE

适用于 AI 代理的生产就绪提示模板。

---

安全与性能

设计安全

• Node.js VM 沙箱 – 隔离的执行上下文
• 无文件系统访问权限 – 工具仅通过注册的服务端访问
• 超时保护 – 可配置的执行限制
• 零网络访问 – 不暴露外部依赖或 API 密钥

性能优化

• 最小内存占用 – VM 上下文轻量级
• 高效的工具缓存 – TypeScript 接口自动缓存
• 流式控制台输出 – 实时日志捕获，无需缓冲
• 标识符净化 – 能够优雅地处理无效的 TypeScript 标识符

---

开发体验

IDE 集成

生成 TypeScript 定义以实现完整的 IntelliSense 支持：

# 生成工具接口  
const interfaces = await client.getAllToolsTypeScriptInterfaces();
await fs.writeFile('generated-tools.d.ts', interfaces);

# 添加到 tsconfig.json
{
  "compilerOptions": {
    "typeRoots": ["./generated-tools.d.ts"]
  }
}

调试与监控

内置可观ability，适用于生产部署：

const { result, logs } = await client.callToolChain(userCode);

// 将日志发送到你的监控系统
logs.forEach(log => {
  if (log.startsWith('[ERROR]')) 监控.error(log);
  if (log.startsWith('[WARN]')) 监控.warn(log);
});

---

基准测试方法

全面的 Python 研究 测试了 16 个真实场景，涵盖：

• 金融工作流（开票、费用跟踪）
• DevOps 运维（部署、监控）
• 数据处理（分析、报告）
• 业务自动化（CRM、通知）

测试模型：Claude Haiku、Gemini Flash
定价依据：输入 0.25 美元/100 万 token，输出 1.25 美元/100 万 token
规模：每天 1,000 个场景，使用 Code Mode 每年可节省 9,536 美元

了解更多

• Cloudflare Research – 原始 Code Mode 白皮书
• Anthropic 研究 – MCP 代码执行的优势
• Python 基准研究 – 全面的性能分析
• UTCP 规范 – 官方 TypeScript 实现
• 提交问题 – Bug 报告和功能请求

许可证

MPL-2.0 – 开源且对商业友好。

Code-Mode 快速上手指南

Code-Mode 是一个通过代码执行来实现工具调用的开源库。它允许 AI Agent 将复杂的工具调用逻辑转化为一段 TypeScript 代码一次性执行，从而显著减少 API 交互次数，提升效率并降低成本。

环境准备

• Node.js: 建议安装最新 LTS 版本（支持 TypeScript 运行环境）。
• 包管理器: npm、yarn 或 pnpm。
• 前置知识: 基本的 TypeScript/JavaScript 编程能力。

安装步骤

在项目根目录下运行以下命令安装核心库：

npm install @utcp/code-mode

提示：如果你希望直接在 Claude Desktop 等 MCP 客户端中使用而无需编写代码，可以使用现成的 MCP Server（无需安装 Node.js 依赖）：

{
  "mcpServers": {
    "code-mode": {
      "command": "npx",
      "args": ["@utcp/code-mode-mcp"],
      "env": {
        "UTCP_CONFIG_FILE": "/path/to/your/.utcp_config.json"
      }
    }
  }
}

基本使用

只需三步即可让 AI Agent 具备通过代码执行复杂工作流的能力。

1. 初始化客户端与注册工具

首先创建客户端实例，并注册你需要使用的工具源（例如 MCP 服务器、HTTP API 等）。以下以连接 GitHub MCP 服务器为例：

import { CodeModeUtcpClient } from '@utcp/code-mode';

// 1. 初始化客户端
const client = await CodeModeUtcpClient.create();

// 2. 注册工具（此处以 MCP 协议为例）
await client.registerManual({
  name: 'github',
  call_template_type: 'mcp',
  config: {
    mcpServers: {
      github: {
        command: 'docker',
        args: ['run', '-i', '--rm', '-e', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'mcp/github'],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN }
      }
    }
  }
});

2. 执行代码链 (Call Tool Chain)

使用 callToolChain 方法传入一段 TypeScript 代码。Agent 将在沙箱环境中执行这段代码，自动调用已注册的工具，并返回结果。

// 3. 执行代码
const { result, logs } = await client.callToolChain(`
  // 在单次请求中串联多个操作
  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });
  
  // 在沙箱内高效处理数据，避免上下文膨胀
  return {
    title: pr.title,
    commentCount: comments.length,
    author: pr.user.login
  };
`);

console.log('执行结果:', result);
console.log('运行日志:', logs);

核心优势

• 批量执行：单个代码块替代多次 API 往返，简单场景速度提升 67%，复杂场景提升 88%。
• 动态发现：支持运行时接口自省（__interfaces），Agent 可动态感知可用工具。
• 安全沙箱：基于 Node.js 隔离环境，提供超时保护和完整的错误捕获。