跳转至

Code Mode 维护者说明

实现布局

  • 配置契约:tools.codeMode
  • catalog 构建器:用于精简条目和 id 映射的有效工具
  • 模型表面适配器:用控制/direct 工具替换可见工具
  • 执行器契约:evaluate、continue、dispose
  • Node 执行器:跨 wait 保留 worker 和 VM 上下文
  • QuickJS 执行器:WASM 加载、求值、快照、恢复、dispose
  • worker 监督器:超时、中止、崩溃隔离
  • 桥接适配器:JSON 安全的主机回调和结果投递
  • 延续所有者:TTL、容量、运行/会话作用域、执行器固定
  • 嵌套工具调用的轨迹投影
  • 遥测计数器和诊断

共享 catalog 和工具桥接保留策略所有权。执行器拥有 JavaScript 执行和延续状态。Node 的 node:vm 是受信任的执行环境,而非沙箱安全边界。

重建 before_tool_call 钩子时必须按原始顺序保留周围的执行包装器。调用者权限、取消、活动状态和运行生命周期检查同时包裹准备、结果收尾以及工具主体。执行包装器在复制工具元数据时注册其重建函数;仅 schema 的副本保留该注册。

工具搜索将每个已发布的 catalog 条目数组视为不可变的描述符快照。注册、限制和执行器重新绑定会替换该数组;通过 catalog 所有者发布 schema 或描述变更。搜索文本按快照惰性渲染一次,热搜索复用内容寻址的词汇索引。每次搜索都会检查可见性,包括可变权限集,BM25 统计仅使用该有效清单。缓存的词汇数据不包含任何工具执行器。

验证清单

代码模式覆盖应证明:

  • 未包含启用覆盖的禁用配置保持现有工具暴露不变
  • 省略 enabled(包括设置了其他字段的对象配置)时保持禁用,除非代理或模型覆盖将其启用
  • 逐模型的 true、false 和未设置的值保留外层选项中的激活优先级、回退模型选择和限制
  • 当运行期间工具处于激活状态时,启用配置向模型暴露 exec、wait 以及仅必需的 direct-only 工具
  • 省略 executor 时选择 Node;显式 QuickJS 选择捆绑插件,不可用的执行器直接失败,不进行回退
  • 显式旧版 runtime: "quickjs-wasi" 迁移为 executor: "quickjs"
  • 全局和按代理的执行器选择在每次 wait 中保持固定
  • 原始无工具运行、disableTools 和空允许列表不会触发代码模式载荷强制
  • 每个符合 catalog 条件的有效非 MCP 名称都有唯一的可调用胜出者
  • direct-only 工具保持模型可见,且不会出现在 catalog 中
  • 被拒绝的工具没有全局或 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() 保持原生
  • 工具搜索控制工具在模型表面和隐藏 catalog 中均不可见
  • 嵌套调用保留审批和钩子行为
  • 已捕获和未捕获的嵌套失败仍可恢复,且无需重放先前执行的副作用
  • 由网络控制的失败保留不可信内容包装和清理
  • 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. 使用一个小型 direct tool 集合发送一个代理回合。
  3. 断言模型可见工具保持不变。
  4. 使用 tools.codeMode.enabled: true 重启。
  5. 使用 OpenClaw、插件、MCP 和客户端测试工具发送一个代理回合。
  6. 断言模型可见工具列表为 exec、wait,外加仅配置的 direct-only 工具。
  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