跳转至

Code Mode 维护者说明

实现布局

  • 配置契约：tools.codeMode
  • 目录构建器：将有效工具转换为紧凑条目和 id 映射
  • 模型表面适配器：将可见工具替换为控制/直接工具
  • 执行器契约：求值、继续、释放
  • Node 执行器：工作线程和 VM 上下文在等待期间保留
  • QuickJS 执行器：WASM 加载、求值、快照、恢复、释放
  • 工作线程监督器：超时、中止、崩溃隔离
  • 桥接适配器：JSON 安全的主机回调和结果传递
  • 延续所有者：TTL、容量、运行/会话作用域、执行器固定
  • 嵌套工具调用的轨迹投影
  • 遥测计数器和诊断

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

重建 before_tool_call 钩子时，必须按原始顺序保留周围的执行包装器。调用方权限、取消、活动以及运行生命周期检查同时包围准备阶段、结果最终化以及工具主体。执行包装器在复制工具元数据时注册其重建函数；仅 schema 的副本会保留该注册。

验证清单

代码模式覆盖应证明：

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

E2E 测试计划

更改运行时时，针对两个执行器运行这些测试：

  1. 使用 tools.codeMode.enabled: false 启动 Gateway。
  2. 发送带有小型直接工具集的代理回合。
  3. 断言模型可见工具未改变。
  4. 使用 tools.codeMode.enabled: true 重启。
  5. 发送带有 OpenClaw、插件、MCP 和客户端测试工具的代理回合。
  6. 断言模型可见工具列表为 exec、wait，以及仅配置的仅限直接工具。
  7. 在 exec 中，调用安全的裸全局变量，并断言规范化、保留和冲突名称与快速索引匹配。
  8. 搜索 catalog，检查句柄元数据/describe()，并调用 OpenClaw/插件/客户端句柄，而不观察精确 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. 断言超时、中止和延续过期清理运行时状态。
  16. 导出轨迹，并断言嵌套调用在父级代码模式调用下可见。

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw