OpenRouter 平台功能

Apply Patch

4 分钟阅读

Apply Patch（应用补丁）

让模型通过 V4A diff 提出文件变更

Beta

测试版（Beta）

服务端工具目前处于测试阶段。API 与行为可能会变更。

仅支持 Responses API

Apply Patch 服务端工具仅可通过 Responses API 使用。Chat Completions API 不支持该工具。

流式行为

只有 OpenAI 模型会通过 response.apply_patch_call_operation_diff.delta 事件增量流式返回 Apply Patch 结果。所有其他模型将完整补丁作为单次工具输出返回。

openrouter:apply_patch 服务端工具让模型能够使用 V4A diff 补丁提出文件变更。这是编码智能体的基础能力——模型生成描述文件创建、更新或删除的补丁，OpenRouter 校验 diff 语法，再由你的应用执行应用。

工作原理

调用 Responses API 时，在 tools 数组中加入 { "type": "openrouter:apply_patch" }。
模型根据对话判断需要创建、更新或删除某个文件，并生成 V4A diff 补丁。
OpenRouter 校验补丁语法（正确的行前缀、有效标记、非空路径）。
若校验通过，工具调用会作为 apply_patch_call 输出项返回给你的应用——由你的应用将补丁应用到文件系统，并在下一轮把结果作为 apply_patch_call_output 回传。
若校验失败，错误会返回给模型，以便其自行纠正。

这是一个**人工介入循环（human-in-the-loop，HITL）**工具：OpenRouter 只校验 diff，从不实际应用。文件操作由你的应用负责执行。

快速开始

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/codex-mini',
    input: '创建一个会打印 "Hello, world!" 的 hello.py 文件',
    tools: [
      { type: 'openrouter:apply_patch' }
    ]
  }),
});

const data = await response.json();
// 响应中包含 apply_patch_call 输出项
// 以及操作类型（create_file、update_file 或 delete_file）
console.log(data.output);

补丁操作

该工具支持三种操作类型，每种都作为 apply_patch_call 输出项上的 operation 字段传递：

`create_file`

创建新文件。diff 中的每一行内容都必须以 + 开头：

{
  "type": "apply_patch_call",
  "call_id": "call_abc123",
  "status": "completed",
  "operation": {
    "type": "create_file",
    "path": "/src/hello.py",
    "diff": "+print(\"Hello, world!\")\n"
  }
}

`update_file`

使用带上下文行（前缀）、新增（+）和删除（-）的 V4A diff 更新已有文件：

{
  "type": "apply_patch_call",
  "call_id": "call_def456",
  "status": "completed",
  "operation": {
    "type": "update_file",
    "path": "/src/main.ts",
    "diff": "@@ function main() {\n-  console.log(\"old\");\n+  console.log(\"new\");\n }"
  }
}

`delete_file`

删除文件。不需要 diff——只需文件路径：

{
  "type": "apply_patch_call",
  "call_id": "call_ghi789",
  "status": "completed",
  "operation": {
    "type": "delete_file",
    "path": "/src/deprecated.ts"
  }
}

回传结果

你的应用应用（或拒绝）补丁后，在下一轮将结果作为 apply_patch_call_output 输入项发回：

{
  "model": "openai/codex-mini",
  "input": [
    {
      "type": "apply_patch_call_output",
      "call_id": "call_abc123",
      "status": "completed",
      "output": "已将补丁应用到 /src/hello.py"
    }
  ],
  "tools": [
    { "type": "openrouter:apply_patch" }
  ]
}

字段	类型	说明
`call_id`	string	必须与 `apply_patch_call` 中的 `call_id` 匹配
`status`	`"completed"` 或 `"failed"`	补丁是否成功应用
`output`	string（可选）	人类可读的操作日志

配置

Apply Patch 工具接受可选的 engine 参数：

{
  "type": "openrouter:apply_patch",
  "parameters": {
    "engine": "auto"
  }
}

参数	类型	默认值	说明
`engine`	string	`auto`	`auto` — 当端点支持增量 diff 流式传输时使用原生透传，否则回退到 OpenRouter 的 HITL 校验器。`native` — 强制使用原生透传（不支持时回退到 HITL）。`openrouter` — 始终使用 HITL 校验器，即使端点具备原生支持。

引擎行为

原生透传通过 response.apply_patch_call_operation_diff.delta 事件增量流式传输 diff，与 OpenAI 的流式格式一致。目前支持 OpenAI 端点。
**HITL（人工介入循环）**会缓冲完整 diff，并将其作为单个原子的 apply_patch_call 输出项交付。

定价

Apply Patch 工具除标准 Token 用量外不产生额外费用。

后续步骤

服务端工具概览 — 了解服务端工具
Web 搜索（Web Search） — 搜索网络以获取实时信息
Datetime — 获取当前日期和时间
工具调用 — 了解用户自定义工具调用

上一页图像生成（服务端）下一页 Shell