代码模式维护者注释

实现布局

• 配置契约：tools.codeMode
• 目录构建器：有效工具，用于压缩条目和 id 映射
• 模型表面适配器：用control/direct工具替换可见工具
• 执行合约：评估、继续、处置
• Node 执行器：工作线程和 VM 上下文在等待期间保留
• QuickJS 执行者：WASM 加载、评估、快照、恢复、处置
• 工作线程监管器：超时、终止、崩溃隔离
• bridge 适配器：JSON-safe 主机回调和结果传递
• 延续所有者：TTL、容量、run/session 范围、执行器固定
• 嵌套工具调用的轨迹投影
• 遥测计数器和诊断

共享目录和工具桥保留策略所有权。执行器拥有 JavaScript 执行和延续状态。 Node的node:vm是可信执行，不是沙箱安全边界。

重建 before_tool_call 挂钩必须按其原始顺序保留周围的执行包装器。调用者权限、取消、活动和运行生命周期检查包含准备和结果最终确定以及工具主体。执行包装器在复制工具元数据时注册其重建功能；仅模式副本保留该注册。

工具搜索将每个已发布的目录条目数组视为不可变的描述符快照。注册、限制和执行器重新绑定替换该数组；通过目录所有者发布架构或描述更改。每个快照都会延迟渲染搜索文本一次，而热搜索会重用内容寻址的词汇索引。每次搜索都会检查可见性，包括可变权限集，并且 BM25 统计数据仅使用该有效库存。缓存的词汇数据不包含工具执行器。

验证清单

代码模式覆盖应证明：

• 没有启用覆盖的禁用配置使现有工具暴露保持不变
• omited enabled，包括设置其他字段的对象配置，保持禁用状态，除非代理或模型覆盖启用它
• per-model true、false 和未设置值保留激活优先级、后备模型选择和封闭选项的限制
• 启用的配置在运行期间工具处于激活状态时，会向模型暴露 exec、wait，以及仅必需的 direct-only 工具
• omited执行者选择Node；显式 QuickJS 选择捆绑的插件，并且不可用的执行器会失败而不会回退
• 显式旧版 runtime: "quickjs-wasi" 迁移到 executor: "quickjs"
• 全局和每个代理执行器选择在每个 wait 中保持固定
• 原始无工具运行、disableTools 和空允许列表不会触发代码模式载荷强制
• 每个符合目录资格的有效非 MCP 名称都有一名可调用的获胜者
• direct-only 工具保持模型可见，并且不会出现在 catalog 中
• denied 工具没有全局或目录句柄
• 裸全局变量、可调用 catalog.search 结果、catalog.all 以及处理 OpenClaw 和客户端工具的 describe() 工作，而无需暴露确切的 ID
• API.list("mcp") 和 API.read("mcp/<server>.d.ts") 公开 TypeScript-style MCP 声明，无需 bridge/tool 调用
• MCP 命名空间 $api() 作为架构的内联回退仍然可用
• MCP 命名空间调用适用于具有一个对象输入的可见 MCP 工具，而搜索句柄使用相同的命名空间调度程序，并且 catalog.all() 保持本机
• Tool Search 控制工具对模型表面和隐藏目录都不可见
• 嵌套调用会保留审批和钩子行为
• 捕获和未捕获的嵌套故障仍然可以恢复，而不会重播之前执行的副作用
• 网络控制的故障保留不受信任的内容包装和清理
• shell exec 对模型隐藏，但在允许时可作为来宾全局调用
• 递归的代码模式 exec 和 wait 不能从 guest 代码中调用
• 可执行单元接受普通 JavaScript，而类型化发现仍然可用
• TypeScript-only 语法和已停用的 language/typecheck 参数在任何嵌套工具分派之前失败
• 预期的访客 API 省略了 import、require、文件系统、网络和环境访问； QuickJS 隔离与 Node 的编程约束分开进行测试
• 无限循环会超时，且不能阻塞 Gateway
• 执行器内存故障终止执行
• 输出上限适用于两个执行器；序列化快照上限适用于 QuickJS
• wait 恢复执行器继续并返回最终值
• 过期、已中止、错误会话和未知的 runId 值会失败
• 转录回放和持久化会保留代码模式控制调用
• 转录和遥测会清晰显示嵌套工具调用

E2E 测试计划

更改运行时时对两个执行器运行这些：

1. 启动一个 tools.codeMode.enabled: false 的 Gateway。
2. 使用一个小型直接工具集发送一次 agent turn。
3. 断言模型可见的工具未发生变化。
4. 以 tools.codeMode.enabled: true 重启。
5. 使用 OpenClaw、plugin、MCP 和 client 测试工具发送一次 agent turn。
6. 断言模型可见的工具列表为 exec、wait，外加仅配置的 direct-only 工具。
7. 在exec中，调用安全裸全局变量并断言规范化名称、保留名称和冲突名称与快速索引匹配。
8. 搜索catalog，检查句柄metadata/describe()，并调用OpenClaw/plugin/client句柄而不观察确切的id。
9. 在 exec 中，调用 API.list("mcp") 和 API.read("mcp/<server>.d.ts")， 并断言声明文件描述了可见的 MCP 工具。
10. 在exec中，在本机和MCP工具中按任务意图搜索，检查MCP句柄的声明，并调用它。验证规范化名称冲突、精确的命名空间查找、有界远程元数据和不受信任的输出包装器。直接 MCP.<server>.<tool>({ ...input }) 调用必须同意，并且 catalog.all() 搜索后必须保持本机。
11. 断言被拒绝的工具不存在，并且无法通过猜测 id 来调用。
12. 启动一个嵌套工具调用，该调用在 exec 返回 waiting 后才解析完成。
13. 调用 wait 并断言持续上下文接收工具结果。
14. 断言最终答案包含恢复后生成的输出，无需重播。
15. Assert 超时、中止和继续到期清理运行时状态。
16. 导出轨迹，并断言嵌套调用在父级代码模式调用下可见。

仅限文档的对此页面的更改仍应运行 pnpm check:docs。