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 测试计划¶
更改运行时,请对两个执行器运行以下测试:
- 使用
tools.codeMode.enabled: false启动一个 Gateway。 - 使用一个小型 direct tool 集合发送一个代理回合。
- 断言模型可见工具保持不变。
- 使用
tools.codeMode.enabled: true重启。 - 使用 OpenClaw、插件、MCP 和客户端测试工具发送一个代理回合。
- 断言模型可见工具列表为
exec、wait,外加仅配置的 direct-only 工具。 - 在
exec中调用安全的裸全局变量,并断言规范化、保留和冲突名称与快速索引匹配。 - 搜索
catalog,检查句柄元数据/describe(),并调用 OpenClaw/插件/客户端句柄,而无需观察精确 id。 - 在
exec中调用API.list("mcp")和API.read("mcp/<server>.d.ts"),并断言声明文件描述了可见的 MCP 工具。 - 在
exec中按任务意图跨原生和 MCP 工具搜索,检查 MCP 句柄的声明并调用它。验证规范化名称冲突、精确命名空间查找、受限的远程元数据以及不可信输出包装。直接MCP.<server>.<tool>({ ...input })调用必须一致,且搜索后catalog.all()必须保持原生。 - 断言被拒绝的工具不存在,且无法通过猜测的 id 调用。
- 启动一个嵌套工具调用,该调用在
exec返回waiting后完成解析。 - 调用
wait并断言延续上下文收到工具结果。 - 断言最终答案包含恢复后产生的输出,且没有重放。
- 断言超时、中止和延续过期会清理运行时状态。
- 导出轨迹,并断言嵌套调用在父级代码模式调用下可见。
仅文档更改此页面时,仍应运行 pnpm check:docs。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw