高级 API 模式 + Edit 内部 + 会话持久化

本文基于 Florian BRUNIAUX 的英文原版改编，原文地址：https://cc.bruniaux.com/guide/architecture 许可：CC BY-SA 4.0

这篇你能拿走什么

如果你只用 Claude Code CLI，前 5 篇就够了；这一篇是给"在 Anthropic API 或 Agent SDK 上自己造 agent"的人写的——4 项 GA 级别的高级工具用法（PTC、Dynamic Filtering、Tool Search Tool、Tool Use Examples）告诉你怎么把上下文成本砍一大半。同时把 Edit 工具的 fuzzy 匹配内部和会话持久化也讲清楚，方便你做调试。

前置条件

• 已完成本系列前面的章节
• 看 API 部分需要至少用过一次 Anthropic SDK 或 Agent SDK；只看 Edit / 会话部分不需要

4 项 API 高级用法（2026-02-18 GA）

可信度：90%（Tier 1 - Anthropic 官方工程资料）

这 4 项功能与使用 Anthropic API 或 Agent SDK 构建 agent 的开发者相关，不能直接在 Claude Code CLI 中使用。它们配合 Opus / Sonnet 4.6 GA。

功能	解决的问题	可用性
Programmatic Tool Calling（PTC）	agent 循环在来回调用上消耗 token	API + Foundry
Dynamic Filtering	Web search 用噪声撑爆上下文	API + Foundry
Tool Search Tool	工具定义太多导致上下文膨胀	API + Foundry
Tool Use Examples	仅靠 schema 无法表达使用模式	API + Foundry

战略性分层 - 先解决最大的瓶颈：

• 上下文被工具定义撑大 → Tool Search Tool
• 中间结果很大 → Programmatic Tool Calling
• Web research 返回噪声 → Dynamic Filtering
• schema 正确但参数仍出错 → Tool Use Examples

Programmatic Tool Calling（PTC）

范式转变：Claude 不再一次调用一个工具、每次都做完整模型往返，而是写 Python 代码在内部编排所有工具调用。只有最终 stdout 进入上下文窗口。

text
Traditional:
  prompt → Claude → tool 1 → response 1 → Claude → tool 2 → response 2 → Claude → answer
  (3 tools = 3 inference passes, 3× intermediate results in context)

PTC:
  prompt → Claude → writes Python → code calls tool 1, 2, 3 → stdout → Claude → answer
  (3 tools = 1 inference pass, only final output in context)

配置——用 allowed_callers 标记可由代码执行沙箱调用的工具：

json
{
  "tools": [
    { "type": "code_execution_20250825", "name": "code_execution" },
    {
      "name": "query_database",
      "description": "Execute SQL. Returns rows as JSON: id (str), name (str), revenue (float).",
      "input_schema": {
        "type": "object",
        "properties": { "sql": { "type": "string" } },
        "required": ["sql"]
      },
      "allowed_callers": ["code_execution_20250825"]
    }
  ]
}

allowed_callers 值	行为
省略 / ["direct"]	仅传统调用
["code_execution_20250825"]	仅可从 Python sandbox 调用
["direct", "code_execution_20250825"]	两种模式都可用（不推荐，会让 Claude 困惑）

典型模式（全部在 1 次 inference pass 中运行）：批处理、早停、条件性工具选择、数据过滤。

Token 效率：programmatic call 的工具结果永远不会进入 Claude 上下文——只有最终 stdout 会。10 次 programmatic call 大约只消耗 10 次 direct call 的 1/10 上下文 tokens。

限制：仅 API 和 Foundry 支持（不支持 Bedrock / Vertex）。不支持 MCP tools，不支持 web search / fetch，不支持 strict: true 工具。容器生命周期约 4.5 分钟。不受 Zero Data Retention 覆盖。

Dynamic Filtering（用于 Web Search / Fetch）

Web search 和 fetch 工具会把完整 HTML 倒入上下文——包括导航、广告、样板内容。Dynamic Filtering 让 Claude 先写 Python 预处理和过滤结果，再让结果进入自己的上下文窗口。

配置——使用带 beta header 的新工具类型版本：

json
{
  "tools": [
    { "type": "web_search_20260209", "name": "web_search" },
    { "type": "web_fetch_20260209", "name": "web_fetch" }
  ]
}

需要 header：anthropic-beta: code-execution-web-tools-2026-02-09。当使用这些工具类型版本以及 Sonnet 4.6 或 Opus 4.6 时，过滤默认启用。

官方 benchmark（BrowseComp dataset）

模型	不使用 Filtering	使用 Filtering	提升
Sonnet 4.6	33.3%	46.6%	+13.3 pp
Opus 4.6	45.3%	61.6%	+16.3 pp

平均输入 token 减少约 24%。最适合多步研究、引用验证、从大型页面抽取特定数据点。

Tool Use Examples

JSON schema 可以定义结构，但表达不了"什么时候包含可选参数"、"哪些组合有意义"、"格式惯例"。给工具定义加 input_examples：

json
{
  "name": "create_ticket",
  "input_schema": { "...": "..." },
  "input_examples": [
    { "title": "Login page 500 error", "priority": "critical", "assignee": "oncall-team", "labels": ["bug", "auth"] },
    { "title": "Add dark mode", "priority": "low", "labels": ["feature-request"] },
    { "title": "Update API docs for v2" }
  ]
}

Anthropic benchmark：复杂参数处理准确率从 72% 提升到 90%。每个工具用 1-5 个真实示例，覆盖最小、部分和完整规格。

与 Claude Code CLI 的关系

功能	Claude Code CLI	CLI 用户的动作
Tool Search（MCP 懒加载）	自 v2.1.7 起内置	调 ENABLE_TOOL_SEARCH=auto:N（详见 MCP 篇）
Tool Use Examples	无法从 CLI 配置	与自定义 MCP server 作者相关——给工具 schema 加 input_examples
Programmatic Tool Calling	不可用	与构建自定义 agent 的 Agent SDK 开发者相关
Dynamic Filtering	不可用	与 Agent SDK 上做 web research pipeline 的开发者相关

Edit 工具：它实际怎么工作

可信度：90%（Tier 2 - 通过行为验证）

Edit 工具比表面看起来更复杂：

text
┌─────────────────────────────────────────────────────────────┐
│ EDIT TOOL FLOW                                              │
├─────────────────────────────────────────────────────────────┤
│ Input: old_string, new_string, file_path                    │
│                                                             │
│ Step 1: EXACT MATCH                                         │
│   Search for literal old_string                             │
│                                                             │
│   Found?       → REPLACE                                    │
│   Not found?   → Step 2: FUZZY MATCH                        │
│                                                             │
│   Fuzzy found? → REPLACE + WARN                             │
│   Still not found? → ERROR (mismatch)                       │
└─────────────────────────────────────────────────────────────┘

模糊匹配做了什么

精确匹配失败时，Edit 工具会尝试：

1. 空白归一化：忽略行尾空格，归一化缩进
2. 换行归一化：处理 CRLF 与 LF 差异
3. 上下文扩展：使用周围行定位正确位置

如果模糊匹配仍然失败，工具返回错误，要求 Claude 验证 old_string。

验证逻辑

应用修改前，Edit 工具会检查：

检查	目的
文件存在	防止通过 Edit 创建文件
找到 old_string	确保编辑正确位置
单一匹配	old_string 必须唯一（否则用 replace_all）
新内容不同	防止 no-op 编辑

失败诊断速查表

错误	原因	Claude 的响应
"old_string not found"	内容自上次读取后变化	重新读取文件再尝试
"Multiple matches"	old_string 不唯一	使用更多上下文行
"File not found"	路径错误	搜索正确路径

会话持久化

可信度：100%（Tier 1）。来源：code.claude.com/docs。

会话可以跨终端会话恢复：

命令	行为
claude --continue / claude -c	恢复最近一次会话
claude --resume / claude -r	通过 ID 恢复指定会话

会持久化什么

会持久化	不会持久化
对话历史	实时工具状态
工具调用结果	待处理操作
Session ID	文件锁
工作目录上下文	环境变量

存储格式

可信度：50%（Tier 3 - 推断）

会话似乎以 JSON / JSONL 文件形式存储在 ~/.claude/，但：

• 格式没有公开文档
• 不打算作为稳定 API
• 可能在版本之间变化

不要依赖会话文件格式来做外部工具。如果你需要可靠的会话外部访问，走 Anthropic API + 自己持久化对话历史。

实战注解

PTC 这个东西第一次看会觉得"魔法"，但你只要做过一次"agent 跑了 8 步、每步都把 50K HTML 塞进上下文、最后用 token 量是任务本身的 20 倍"的项目，就会立刻明白它的价值。它不是优化，是范式重置——不再"模型想一步、执行一步、再想一步"，而是"模型想清楚，写一段 Python，一次跑完，只把结论拿回来"。

我自己写 agent 的判断顺序：

1. 先看工具定义占了多少 token，如果 >20K 就上 Tool Search Tool
2. 看是不是有大量"中间数据没人看"的工具调用，是就上 PTC
3. 看 web 工具占比，>30% 就上 Dynamic Filtering
4. 最后给所有复杂参数的工具补 input_examples

至于 CLI 用户：现在 v2.1.7+ 自动用 Tool Search，剩下 3 个等 Anthropic 把 PTC 移植到 CLI 那天再说。会话持久化倒是值得每天用——claude -c 是我每天早上的第一个命令。

可信度回顾

• Tier 1（官方 100%）：4 项 API 功能存在性、benchmark 数字、配置参数、会话恢复命令
• Tier 2（70-90%）：Edit 工具内部算法（通过行为验证）
• Tier 3（推断）：会话存储文件格式

PTC 的 token 节省 37% 那个数字来自社区报告（Shayan Tabe 的分析），尚未被 Anthropic 官方确认；Anthropic 官方说法是"~10× 减少 programmatic call 的工具结果上下文消耗"。

常见问题

Q：PTC 容器生命周期 4.5 分钟够用吗？ A：单次 PTC 调用 4.5 分钟够多数批处理；超过的任务请拆分。容器是有状态的，但跨 inference pass 重置。

Q：Edit 失败后 Claude 重读文件再编辑会不会撞 race？ A：会。如果文件被外部进程修改，Edit 会一直失败。建议在长任务里显式 Read 一次再 Edit，或者用 hook 锁定文件。

Q：claude --resume 能跨机器恢复吗？ A：会话文件存本地 ~/.claude/，跨机器没有官方同步。如果要跨机器，自己用 syncthing / rsync 同步该目录，但格式可能在版本之间变化（不推荐依赖）。

---

来源与许可

• 原作者：Florian BRUNIAUX；Claude（Anthropic）参与贡献
• 英文原版地址：https://cc.bruniaux.com/guide/architecture
• 源文件：FlorianBruniaux/claude-code-ultimate-guide / guide/core/architecture.md
• 本文基于 CC BY-SA 4.0 改编：保留署名、来源链接，衍生作品同样以 CC BY-SA 4.0 公开
• 内容版本：原作 v1.1.0 / Claude Code v2.1.34（2026-02）