Claude Code 公开技术原理与 2.1.235 验证矩阵¶

本页回答一个经常被忽略的问题：网上或官方文档描述的是“Claude Code 当前应该怎么工作”，而这个仓库归档的是一个确定的旧发布物。公开资料可以帮助我们提出正确问题，但只有在 2.1.235 bundle 中找到可达分支，或用同一版本二进制触发出结果，才能把结论写成本版本事实。

调研刷新：2026-08-24。公开网页会继续更新。本次不再只保存 URL：31 个响应的 HTTP 状态、字节数、原始响应 SHA-256、去噪正文 SHA-256、40 条逐摘录 SHA-256、逐句正文命中状态和固定摘录分别保存在 public-sources/manifest.json 与 public-source-excerpts.md。刷新脚本会拒绝任何不能在当次可见正文逐句找到的“引用”。这些哈希证明“当时读到的响应”和“可读语义是否变化”，不把当前文档发布日期倒推成本版本发布日期。

证据标签¶

精确探针二进制的 SHA-256 为 83b8f806f6f2eea316cfe246628e6c23374711d868f1fd0409db551b877b7748，与 version.json 中的发布物记录一致。系统 PATH 中另一个 claude 版本不是目标，因此所有探针都显式使用版本目录中的 2.1.235 文件。

官方资料清单¶

产品与 Agent SDK 文档¶

• How Claude Code works
• Agent loop
• Context window
• Prompt caching
• Sessions
• Checkpointing
• Memory
• Permissions
• Sandboxing
• Hooks
• MCP
• Subagents
• Agent teams
• Monitoring usage
• Settings
• Model configuration
• Authentication
• Enterprise network configuration
• Remote Control
• IDE integrations
• Setup
• Troubleshooting
• Data usage

Anthropic Engineering¶

• Building effective agents
• Effective context engineering for AI agents
• Writing effective tools for agents
• How we built our multi-agent research system
• Prompt caching is everything
• How we built Claude Code auto mode
• Advanced tool use
• Claude Code sandboxing

总体验证矩阵¶

Agent Loop：从公开四步到客户端状态机¶

公开文档常把循环总结为：gather context、take action、verify work、repeat。这个模型有教学价值，但不足以解释 CLI 为什么不会在每个 HTTP retry 时耗掉一个 maxTurns，也解释不了工具在流式响应尚未结束时为什么已经开始执行。

2.1.235 中实际多了至少六层状态：

1. 请求前吸收用户 queue、passive command 和后台停止信号。
2. 根据 context、cache 和 compact 状态重建本轮消息视图。
3. 模型流逐 block 解析，完整 tool_use block 立即进入 executor。
4. scheduler 根据工具与 input 的 concurrency-safe 判定建立重叠或屏障。
5. 工具结果、PostToolBatch 和新用户消息合并到消息图。
6. 根据 Stop hook、maxTurns、fallback、malformed tool use 和 terminal reason 选择继续方式。

所以“Agent Loop 已证实”的含义不是 bundle 中出现 agent_loop 字符串，而是这些状态与转换可以连成从输入到下一次 API call 的可达调用链。完整拆解见 Agent Loop。

Context Engineering：公开原则如何落到本地机制¶

Engineering 文章强调，context engineering 管理的是 system instructions、tools、MCP、外部数据和 message history 的整体，而不是只改 system prompt。2.1.235 的实现与这条原则有清晰对应：

公开文章的“最小高信号 token 集”是设计目标；具体的 20k 清理提示、最近 5 个 tool result、200k 窗口阈值和 5m/1h cache 价格分支才是本版本静态事实。详见 上下文治理与多层缓存。

Tool Design：为什么 schema 和返回值是执行质量的一部分¶

Anthropic 的工具文章把工具描述为确定性系统与非确定性 Agent 之间的接口，并强调 namespacing、明确描述、有效返回上下文和 token efficiency。2.1.235 的工具管线说明这些建议不只是 prompt 写法：

• 工具名/alias 决定能否解析到真实实现。
• JSON schema 和自定义 validator 决定模型生成的 input 是否可执行。
• updatedInput 允许 hook/permission 层修正参数，但修正后必须再次验证。
• output schema 决定工具实现是否履行对 Agent 的返回契约。
• error tool_result 仍需保留原 ID 和可解释错误，否则下一轮无法修正策略。
• Tool Search 是否 defer 决定描述/schema 在什么时候消耗上下文。

因此，工具质量问题可能表现成“模型笨”，实际根因却是 description 不清、schema 太宽、错误结果无上下文、输出过大或权限语义与动作不匹配。

Multi-Agent：独立上下文不是免费并行¶

公开多 Agent 文章强调 orchestrator-worker 模式、独立 context window、并行搜索和结果压缩，同时明确指出协调复杂度和 token 成本会快速增长。2.1.235 的客户端结构支持这个判断：

• 子 Agent 拿到独立的 messages、tools、model/effort、maxTurns、permission context 和 abort controller。
• model: inherit 只表示默认继承模型选择，不表示共享同一个模型调用或上下文窗口。
• permissionMode: bubble 允许子 Agent 的关键审批上浮，而不是默认绕过主会话控制。
• team/task/mailbox 需要显式 task claim、消息投递和生命周期状态；并行本身不能防止重复研究和任务缝隙。
• 子 Agent 最终要把压缩后的发现返回主 Agent；把完整轨迹无节制复制回主上下文会抵消隔离收益。

这解释了为什么编码任务不应机械地“多开 Agent”：任务存在强顺序依赖或共享文件写冲突时，协调成本可能高于并行收益。详见 MCP、Agents 与后台协作。

精确版本运行探针¶

以下命令中的 $CLAUDE_TARGET 指向 SHA-256 已核对的精确发布二进制。

版本身份¶

Command: $CLAUDE_TARGET --version
Input: none
Literal output: 2.1.235 (Claude Code)
Exit status: 0
Result: 探针执行对象与目标版本一致

Agent Loop、真实 Read、tool_result 回灌与成功 resume¶

探针脚本：probe_agent_loop.mjs。固化报告：agent-loop-tool-result-resume.json。它在隔离 HOME/config/workspace 中启动本地 Messages server，不访问真实模型服务。

Command: $CLAUDE_TARGET --print AGENT_LOOP_INITIAL_MARKER --output-format stream-json --verbose --model claude-sonnet-4-5 --tools Read --permission-mode bypassPermissions --dangerously-skip-permissions --session-id $SESSION_ID
Input: 模型返回 tool_use {id:"toolu_agent_loop_probe", name:"Read", file:"$WORKSPACE/probe-fixture.txt"}；文件 literal 内容为 AGENT_LOOP_FILE_MARKER
Literal output: TOOL_EXECUTION_OK
Exit status: 0
Observed request result: 第一次请求声明 Read；第二次请求同时包含同 ID 的 tool_use 和 tool_result，tool_result 内容包含 AGENT_LOOP_FILE_MARKER
Result: 精确二进制的模型流 -> 工具执行 -> 结果回灌 -> 下一次模型决策闭环已正向证实

Command: $CLAUDE_TARGET --print AGENT_LOOP_RESUME_MARKER --output-format stream-json --verbose --model claude-sonnet-4-5 --tools Read --permission-mode bypassPermissions --dangerously-skip-permissions --resume $SESSION_ID
Input: 上一命令创建并持久化的真实 session
Literal output: RESUME_OK
Exit status: 0
Observed request result: resume 请求包含 AGENT_LOOP_INITIAL_MARKER、TOOL_EXECUTION_OK 和 AGENT_LOOP_RESUME_MARKER
Result: 本版成功 resume 会恢复已持久化历史并加入当前输入

报告中的 25 个布尔检查全部为 true；初始工具闭环加 resume 的 Messages 请求数为 3，后续同一脚本还验证 manual compact 与 fork。该探针证明客户端实际行为，不依赖“存在某个字符串”或“错误路径能打印提示”。

补强探针矩阵¶

完整命令、受控输入、字段解释和 30 条 Claim ID 见 精确二进制运行证据指南。这里列出影响公开主张判定的 literal result，避免把当前官网文字直接倒灌进旧版本。

这些 Probe 使用本地协议对端的原因，是把变量限制在客户端。它们没有把本地 mock 返回成功写成“Anthropic 服务端也已成功”，也没有把 doctor 的不可用诊断写成真实 Remote Control 成功连接。

MCP 空配置状态¶

Command: $CLAUDE_TARGET mcp list
Input: 隔离 HOME，无 MCP 配置
Literal output: No MCP servers configured. Use `claude mcp add` to add a server.
Exit status: 0
Result: 空配置是正常可观察状态，证明 `mcp list` 命令 surface 与空状态输出；不证明动态 `tools/list_changed` 已运行

Agent 枚举¶

Command: $CLAUDE_TARGET agents --json
Input: 隔离 HOME，无自定义 agent
Literal output: []
Exit status: 0
Result: 命令面和 JSON 输出协议在本版可达；不证明任何子 Agent 已获得独立上下文并完成任务

非法 session ID¶

Command: $CLAUDE_TARGET --resume not-a-valid-session-id
Input: 非法 session ID
Literal output: Error: --resume requires a valid session ID or session title when used with --print. Usage: claude -p --resume <session-id|title>. Provided value "not-a-valid-session-id" is not a UUID and does not match any session title.
Exit status: 1
Result: resume 参数校验不接受任意字符串；不证明成功恢复路径

不存在的合法 UUID¶

Command: $CLAUDE_TARGET --resume 00000000-0000-4000-8000-000000000000
Input: 结构合法但不存在的 UUID
Literal output: No conversation found with session ID: 00000000-0000-4000-8000-000000000000
Exit status: 1
Result: 本版区分“ID 合法”与“本地存在可恢复 transcript”；成功恢复由上面的三请求正向探针证明

--max-turns 0 的尝试进入了后续执行路径，未在参数解析阶段立即拒绝，随后被人工中断。它不能证明 0 的最终运行语义，因此不列为成功探针，也不据此推断“无限制”或“禁止执行”。

尚未由 2.1.235 证实的边界¶

以下内容即使出现在当前官方文档，也不能仅凭文档写成 2.1.235 客户端事实：

• 后续版本新增的命令、hook event、settings key、权限模式或 Agent Teams UI。
• 远端 feature flag 在某账户、组织、地区和订阅上的实时返回值。
• Anthropic 服务端的 abuse/risk score、模型路由、缓存命中判定和限流策略内部实现。
• 客户端 schema 中声明但目标平台、provider 或 feature gate 未启用的分支。
• source map、原始 TypeScript 文件名、注释、被 tree-shaking 删除的代码。
• 操作系统 sandbox 在所有 macOS/Linux 版本上的等价强制效果。

这些边界不是“没有能力”，而是证据层不同。版本归档必须把“当前产品文档说有”与“目标二进制已证实”分开，否则下一次版本 diff 会把文档更新误判成代码变化。

长期验证规则¶

以后每个版本都按同一顺序处理公开资料：

1. 保存调研日期、官方 URL、HTTP 状态、响应字节、原始响应 SHA-256、去噪正文 SHA-256 和逐摘录 SHA-256。
2. 把每条主张拆成可搜索对象：稳定 key、CLI surface、状态字段、默认值、阈值、错误文本和调用顺序。
3. 在 canonical bundle 中证明分支可达，不用单个字符串命中代替调用链。
4. 对 CLI surface、session、MCP、agent、permission 等可隔离路径运行精确版本探针。
5. 把结果标成 Public、Static、Probe 或 Boundary。
6. 版本比较先比较实现证据，再用官方 release notes/当前文档解释动机；不能反过来用宣传文案填补代码证据。

校验器还会扫描所有 Markdown 中的 Anthropic 官方 URL；只要文章引用了一个未进入 manifest 的页面，快照验证就失败。这样能避免“正文链接已经拿来下结论，但机器清单没有记录”的不一致。

这样，“上网搜原理”才真正转化为逆向工作的输入：公开资料负责告诉我们应该验证哪些机制，发布物和探针负责决定哪些结论可以落在这个版本名下。