Files
Agent-Workbench/docs/research/TOOL-LOOP.md
T
2026-10-29 11:23:43 +08:00

119 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Claude Code 2.1.312:工具调度、权限与结果机制
本次已建立工具调用的局部机制:校验输入并分类并发,排队进入执行路径,取得权限决定,通过最后检查后调用工具,再用原始 ID 交付结果。可以提炼成我们自己的本地代理执行器。全部结论来自静态发行工件与复制原文,没有运行 Claude Code 或读取个人会话。
**工件与证据范围**
目标沿用已取得的官方 Windows x64 发行包。EXE 为 `D:\Ai-project\REA逆向\Claude-Code-REA\artifacts\package-extracted\package\claude.exe`,大小 298690208 字节,SHA256 为 `6099672ebe5dcb518b67d1d32dde1e3360bc6bee1dae7f8d28a69c49acc7c865`;本次重新计算散列一致。
Bun 模块表已提取 2,581 个 JavaScript/entry 模块。本次实际选读 5 个原始分块中的 27 个函数/方法,组装成 5 份惰性分析文件。所有选段都与 EXE 原始载体字节逐一核对一致,来源索引保存 UTF-16 范围、UTF-8 字节范围、原始 EXE 范围和散列。
函数原文被保留,const 绑定、注释、exports 和部分 Js 类壳为分析时补入的结构。它们不代表原作者的完整源码,也不建立原应用的运行等价性。原来的 `B:/~BUN/root/...` 虚拟绝对路径、遗漏的依赖与动态关系仍未解析。
| REA 引用 | Evidence ID | 支持范围 |
| --- | --- | --- |
| 主分析 | `ev_78494b2b28703e1547eaa7b660ff70a6a1552991cd3b0e2727954779d74b5434` | 五份惰性文件的完整静态分析记录 |
| 摘要 | `ev_ec39090d21bdfd4352635ed4831e8518aa4703a7ade7ef8b8c9b18e7b580071d` | 选择、解析、覆盖和未知项 |
| 文件事实 | `ev_fa12f2ad8dcb53e765a942233134ead88dd4aabc03b0d6e1479be59a62898835` | 原始观察 ID、源散列和 AST 来源位置 |
REA 解析了 5 个文件,共访问 24,566 个 AST 节点,零解析失败;语义保留未被预算截断。应用图仍是 partial,语义图是 unknown,保留 5,046 个语义未知记录。模块页里的 25 个节点含合成导出角色,不能当作 25 个原始应用模块。视图的 complete-within-view 只表示视图已完整返回。
**调度与结果(C01、C02、C06;T03–T14、T24–T26)**
Js 保留调用 ID、assistant 消息、queued/executing/completed/yielded 状态、进度、桥接事件和结果。getCompletedResults 只把 completed 转为 yielded,输出后移除对应进行中 ID。未知工具以及中断、对话结束和流式回退都有原 ID 的错误结果。
addTool 用 inputSchema.safeParse 的正常成功结果调用 isConcurrencySafe(parsedInput)。解析不成功或并发声明函数抛错时,分类为不适合并发;safeParse 自身的异常并未在这个片段内同样捕获。canExecuteTool 的条件为“没有工具执行”,或者“新工具与所有正在执行的工具都安全”。processQueue 遇到不能启动的非安全排队项就 break,构成独占屏障。
processQueue 虽然 await executeTool,后者只是保存内部异步 promise 后返回,所以不能据此把所有工具解释为串行执行。安全工具的上下文 layers 缓冲到没有工具执行时才应用;非安全工具完成时应用自己的层。层合并 helper 的冲突行为仍未展开。
discardAndAbortInFlight 区分已完成/已交付、排队和执行中调用,但 callStarted 只是生命周期标记。`markToolCallStarted` 位于原分块 UTF-16 3920135,受保护的 `e.call` 位于 3921163;两者之间还有协调器拒绝、参数和工作目录检查。该标记不能证明副作用已发生,completed 也可能对应中止后的合成错误。
ud 通过工具调用 ID 找到对应 assistant 消息。RSo 收集结果 ID,并过滤含任一未配对工具调用的整条 assistant 消息;它不会生成成功结果。ID 配对的语法观察是明确的,真实执行是否完成仍需运行和持久化证据。
**权限与执行(C03、C04;T15–T23)**
选定本地路径在 EU 查找与路由后,经 gYr 进入 bYr。bYr 包含输入转换、schema 校验、可选 validateInput 和 PreToolUse hooks,然后取得 oFr 返回的 decision/input。
bYr 的 `No.behavior !== "allow"` 分支创建原始 ID 的错误结果并 return,早于其主要工具调用。权限处理器改写 updatedInput 后还要重新做 schema 验证,失败也返回错误。oFr 的条件检查可以把 allow 降为 deny;NVr、JP、WKe 等 helper 的完整语义未解析,不能据这一小段概括全部授权模型。
hv 可返回已有决定,也可进入 SDe。$yr 同时出现先行 allow 直接返回、带条件的 dontAsk 拒绝、自动分类和回退提示路径。本报告只读取相关的有限分支,没有审完该大型策略函数。
yF 在先行决定是 allow/deny 时直接返回;其余路径可以调用配置的 MCP 权限提示工具,并竞速等待提示结果、中止或符合条件的 hook outcome。服务器不可用、中止或 schema-invalid 回复返回 deny;非预期文本结果结构会抛错。某些工具类型或用户交互要求还会拒绝提示工具给出的 allow。AV 根据 stdio、直接决定和配置提示工具选择路径。
因此,“所有工具都需要人点确认”不是本次观察到的通用规则。我们产品的终端人工确认、授权有效期和恢复策略需要作为独立设计实现。这里证明的是选定本地主要调用的静态前置拒绝分支,远程执行器、hooks 的其他效果和全部模式没有端到端验证。
**MCP 恢复重试(C05;T27、G08)**
ct 的会话恢复分支只在 Mt < 1 时继续循环,因此最多追加一次恢复重试。它还要求以下一项成立:异常声明工具尚未执行(!mayHaveRun)、工具声明输入可并发、或者 MCP 的 idempotentHint 为 true。其他错误或重试耗尽走失败路径。
并发安全是这个客户端采用的条件,不能普遍等同幂等。BM 如何判断 mayHaveRun、远端如何恢复会话以及重复调用的真实影响未被运行验证。我们的实现应该把并发声明和幂等声明分成两项,并保留结果不确定的写操作。
**可以落入统一产品的六条独立设计原则**
| 原则 | 我们的实现契约 | 可检查结果 |
| --- | --- | --- |
| D01 把调用、启动标记和结果分开记录 | 每个逻辑调用使用稳定 call ID,重试另有 attempt ID;状态记录先于执行,完成结果持久化后才确认完成。预调用标记不能当作副作用提交证明。 | 拒绝、中止、未知工具和成功结果都能配对到原始调用;重启后不会把仅有启动标记的调用显示为成功。 |
| D02 在调度与执行前验证实际输入 | 模型输入、hooks 改写和授权者改写都经过 schema 验证;输入变化后重新评估权限和并发分类。这是我们增加的明确契约。 | 无效输入不会到达执行器;一个改写后的写操作不能继续沿用原读操作的并发分类。 |
| D03 用声明控制并发并保留独占屏障 | 工具显式声明是否适合并发;缺失、分类失败或异常采用独占执行。可并发组完成前阻挡独占写操作,独占队列项阻挡后续调用。 | 两个允许并发的读操作可同时运行;排在其后的独占写操作以及该写操作后的调用按屏障推进。 |
| D04 让授权决定与执行器使用同一份调用 | 保存授权来源、实际输入摘要和决定;执行器只接受仍有效的 allow。我们产品的终端人工确认策略属于独立设计,不能冒充 Claude Code 的通用行为。 | 未解决的 ask、deny、失效授权和不匹配输入不会到达主要工具调用。 |
| D05 中断后保留结果不确定 | 明确区分未启动、已完成和结果不确定的调用;对结果不确定的调用先核对已有结果及外部可观察状态,再决定恢复。 | 运行中崩溃或取消后,界面与日志显示可核对的不确定状态,并保留原调用 ID。 |
| D06 把恢复重试与幂等声明分开 | 恢复重试设次数上限;已知未执行或工具明确承诺幂等时可重试。并发安全和幂等使用不同字段,重试也重新检查授权。 | 可能已经执行的非幂等写操作不会因为网络恢复而自动再执行一次。 |
以上是原创产品设计提案,本次研究没有修改 Agent-Workbench 代码,也没有声明这些契约就是 Claude Code 的全部行为。
**来源定位**
下表的范围是原始派生分块内的半开 UTF-16 区间;T 编号在 `TOOL-LOOP.evidence.json` 中继续连接到 EXE 字节范围、散列、REA 源观察和生成切片位置。
| 选择 | 函数/方法 | 原始分块 | UTF-16 范围 |
| --- | --- | --- | --- |
| T01 | `Js.constructor` | `chunk-3vwg1wzf.js` | [57761,57856) |
| T02 | `Js.discard` | `chunk-3vwg1wzf.js` | [57856,57903) |
| T03 | `Js.discardAndAbortInFlight` | `chunk-3vwg1wzf.js` | [57903,58418) |
| T04 | `Js.addTool` | `chunk-3vwg1wzf.js` | [58575,59912) |
| T05 | `Js.canExecuteTool` | `chunk-3vwg1wzf.js` | [59912,60041) |
| T06 | `Js.processQueue` | `chunk-3vwg1wzf.js` | [60041,60252) |
| T07 | `Js.createSyntheticErrorMessage` | `chunk-3vwg1wzf.js` | [60252,61547) |
| T08 | `Js.getAbortReason` | `chunk-3vwg1wzf.js` | [61547,61729) |
| T09 | `Js.buildSameTurnToolUses` | `chunk-3vwg1wzf.js` | [62246,62559) |
| T10 | `Js.buildSameTurnErroredToolUseIds` | `chunk-3vwg1wzf.js` | [62559,62888) |
| T11 | `Js.executeTool` | `chunk-3vwg1wzf.js` | [62888,65821) |
| T12 | `Js.getCompletedResults` | `chunk-3vwg1wzf.js` | [65821,66402) |
| T13 | `Js.getRemainingResults` | `chunk-3vwg1wzf.js` | [66511,67084) |
| T14 | `Js.applyEndedRunLayers` | `chunk-3vwg1wzf.js` | [67084,67384) |
| T15 | `EU` | `chunk-9hk5qx04.js` | [3891097,3896902) |
| T16 | `gYr` | `chunk-9hk5qx04.js` | [3896902,3899334) |
| T17 | `bYr` | `chunk-9hk5qx04.js` | [3902063,3936718) |
| T18 | `oFr` | `chunk-9hk5qx04.js` | [3860602,3860892) |
| T19 | `hv` | `chunk-9hk5qx04.js` | [2927234,2927304) |
| T20 | `SDe` | `chunk-9hk5qx04.js` | [2927379,2927814) |
| T21 | `$yr` | `chunk-9hk5qx04.js` | [2928029,2967785) |
| T22 | `yF` | `chunk-qey7z5yq.js` | [823883,826935) |
| T23 | `AV` | `chunk-qey7z5yq.js` | [827368,828434) |
| T24 | `dd` | `chunk-gets36qn.js` | [32523,32832) |
| T25 | `ud` | `chunk-gets36qn.js` | [32832,33209) |
| T26 | `RSo` | `chunk-gets36qn.js` | [119632,119984) |
| T27 | `ct` | `chunk-d8k5k6qc.js` | [112235,114722) |
**问题覆盖和剩余未知**
| 问题 | 当前状态 | 边界 |
| --- | --- | --- |
| 生命周期、并发屏障、结果 ID 与取消分类 | 已回答选定静态路径 | 工具实现与运行副作用仍未知 |
| 主要工具调用前的输入验证和权限拒绝 | 本地路径已有明确分支 | 远程执行与 helper 关系只部分回答 |
| 权限模式、规则和 MCP 提示 | 部分回答 | 只读了大型策略中的有限相关分支 |
| 会话恢复重试上限与判定条件 | 已回答选定 ct 路径 | 服务端执行确定性及幂等真实性未知 |
| 原客户端完整运行行为与全程序等价重构 | 未验证 | 没有执行目标,完整跨模块关系未建立 |
本次定位与否定结论都限定在选定文件/函数。合成错误、AbortController 和启动标记提供调度层事实,不能推断外部动作已撤销、底层进程已结束或持久化结果已提交。
**交付文件**
- [证据索引](TOOL-LOOP.evidence.json):27 个完整选段、8 个关键语法锚点、结论和独立设计原则。
- [字节验证](TOOL-LOOP.verification.json):EXE 散列重验、27 处载体文本比较和生成位置。
- [REA 视图原记录](TOOL-LOOP.rea-receipts.json):本次返回的完整摘要与视图 Evidence。
- [完整 REA Bundle](TOOL-LOOP.evidence-bundle.json):26216217 字节,7 个记录;包含完整主图,供后续离线查询。
- [惰性切片来源](tool-evidence/provenance.json):原始字节与分析包装说明。
统一产品可收录报告与证据索引;完整分析图和第三方函数切片保留在研究目录。