# 跨预设工具覆盖 版本 `0.3.1`,目标运行时 DeepSeek Harness `>=0.2.2-rc.1 <=0.2.2-rc.5`。工具覆盖是独立 Host 插件,行 id 为 `codex-tool-policy`,默认 `rules: []`,不会自动改变任何预设。 ## 改什么,不改什么 为选中的预设创建 Agent 时,插件在该 Agent 的子作用域中限制继承工具,并按配置注册 Codex 执行、计划与可选补丁工具。原预设的 Persona 和插件声明保持不变,不编辑其它预设的 YAML。调用继续走宿主的工具执行器、审批、沙箱和日志机制,真实失败仍保留。 默认及可选替换规则: | 原能力 | 替换后 | | --- | --- | | 存在且允许调用的原生 `bash` / `pwsh` | `exec_command` + `write_stdin`(默认启用) | | 存在且允许调用的原生 `todo_write` | `update_plan`(默认启用) | | 存在且允许调用的原生 `edit` / `write` | 可选共用 `apply_patch`(`codex-patch`,`replacePatch` 默认 `false`) | | 任意无条件源工具 | `defer`(按需延迟加载:第 1 步隐藏并注入 `activate_tools`,激活后于下一步通过 DSH `tool-addition` + `deferLoading: true` 生效) | | `read` / `read_image` / `apply_patch` / `glob` / `grep` | 保留原定义 | 不存在的源能力不会凭空补上;同名目标工具冲突和无法安全保留激活条件的源工具明确拒绝,不用无条件包装掩盖问题。此适配针对当前版本原生执行与计划工具;第三方同名工具或按工具名实施的额外策略,需要单独审计。 `update_plan` 采用至多一个 `in_progress` 的计划语义,不等同于允许多个任务并行的 `todo_write`。需要并行任务列表的预设可以关闭计划替换。 执行替换复用宿主的单次审批与沙箱策略;仅沙箱执行器展示 `sandbox_permissions` / `justification`,授权只覆盖本次原命令。拒绝、取消或缺少审批通道时不启动命令。沙箱执行器下 `tty=true` 因无法承载单次策略而明确拒绝;交互终端需求应保留原终端工具或关闭执行替换。`write_stdin` 不能给已经启动的进程升级权限。底层执行器失败和沙箱拒绝标记不会被当成成功吞掉。 ## 设置 打开 **设置 → 内置插件 → Codex Harness**: 1. 在“工具方案”页选择预设;目录来自该预设,不拿当前聊天的 Agent 工具表冒充。 2. 按命令、计划、文件及其它分组选择具体工具的“不改动”“隐藏”或已支持的替代方案。分组不提供联动总开关。 3. 检查变更摘要,点击“保存此预设”;新建或重载 Agent 后生效。 `exec_command + write_stdin` 是启动与续读的一组配套能力,作为同一个适配方案提供;其它工具没有适配器时只提供不改动/隐藏。 切换预设会保留各自草稿,但保存只把当前预设合并入已接受的服务器规则,不顺便提交其它草稿。自己的成功提交仅在完整接受值与预期一致、其它目标基线未变时更新其它草稿版本;外部并发修改仍拒绝并保留草稿。 “运行偏好”页没有预设选择器,只管理本环境共享的请求和显示选项,没有另一组执行/计划/文件工具总闸。 “高级”提供逐工具详情、当前预设提示词和原始定义;共用所选预设,原始定义仍只读。诊断模式、入口、专用修复/旧名单编辑代码与文案已删除,不迁移到其它位置;后台仍读取旧格式,并保持正常保存校验。插件详情只保留摘要和设置路径,不再复制完整编辑器。运行组件清单保持真实,不需要逐个打开后台卡片。 - 不启用 allowlist:不增加 allow 限制。 - 启用 allowlist 且留空:显式禁止全部继承工具,不等同于省略。 - deny:额外移除名单中的继承工具。 - 合并明确的逐工具选择后,先应用有效 allow / deny,再替换仍被允许的源能力。没有单项覆盖时,仅允许 `read` 不会又补出命令或计划工具。 - 名单使用源工具名;本覆盖层新注册的工具成组出现,不能用同一条继承掩码裁掉自身新工具。未知名称、保留名称和不可裁的自身工具会报错,不静默忽略拼写问题。 - 文件工具默认原样保留,但用户显式写入 allow / deny 时仍可裁剪。工具掩码不是文件系统或进程权限隔离:允许命令工具时,不能把隐藏 `write` 当作禁止所有文件写入。 需要独立配置 bundle 时,可覆盖已存在的插件行;以下只是配置示例,不应直接写入活动 profile 文件: ```yaml - id: codex-tool-policy name: '@shuind/dsh-codex-harness/tool-policy' config: rules: - preset: standard replaceShell: false replacePlan: false tools: - name: pwsh action: codex-exec - name: todo_write action: keep ``` `tools` 中每个 `{ name, action }` 是明确的逐工具选择,优先于本规则的旧 allow / deny 和大类默认;它不能解除其它插件的限制。动作包括 `keep`、`hide`、`defer`、`codex-exec`、`codex-plan`、`codex-patch`。执行适配仅接受 `bash/pwsh`,计划适配仅接受 `todo_write`,补丁适配仅接受 `edit/write`(任一或两者均映射到同一个 `apply_patch` 注册);`defer` 接受任意非条件、非 `activate_tools` 的继承源工具,并在第 1 步通过 `when` 准入与 `activate_tools` 实现与 DSH `0.2.2` `tool-addition` / `deferLoading: true` 兼容的渐进激活;未知工具、重复名称和不匹配的适配会拒绝。`replacePatch` 默认为 `false`以保留原生文件工具,如需通过大类开关替换可显式设为 `true`。 在实验性的 `codex-hybrid` 预设中,`hybrid-executor` 默认将 `create_goal`、`get_goal`、`ralph`、`subagent_fork`、`todo_write`、`update_goal`、`workflow` 设为 `defaultDeferred`;若未显式覆写,策略层与设置界面都会将其默认显示为 `defer`,且可随时按需改为 `keep` 或 `hide`。已激活的延迟工具会在压缩完成(`compaction/end`,包含本地摘要压缩与远程加密压缩)时结算压缩前轮次热度:若连续超过 `2` 轮(`DEFERRED_RECENT_TURN_WINDOW`)未再激活或实际执行,则在压缩完成后自动收起以节省下半场 Token(压缩进行期间保持原工具集以复用前缀缓存,静态目录 `codex:deferred-tools` 保持不变)。 新界面创建规则时显式设置两个旧类别开关为 `false`,只记录被编辑工具的选择。旧规则没有迁移,未编辑部分仍保留旧默认语义;手写逐工具规则时也应像示例一样关闭旧类别默认。示例中的工具名必须确实在所选预设的目录中。 目录是注册快照,不是某个 Agent/model step 的准入结果。读取会暂借预设 revision 并建立只读子作用域,完成后释放;不创建 Agent,不运行工具、条件函数或模型请求。条件工具标记为条件项,禁止自动替换;会话后续动态加入的工具可能不在该快照中。 ## 当前预设的提示词 同一预设规则可保存 `promptOverrides`,每项只包含 `{ name, text }`。目标白名单为 `deployment:persona-prefix`、`deployment:persona-suffix` 和 `codex:base`;只有当前预设实际注册且语义可核验的段才允许编辑。目录不为非 Codex 预设伪造 Codex 操作指南,也不把动态表达式当正文。 提示词与工具属于同一预设草稿,“保存此预设”一起提交当前目标,不改其它预设或旧共享模板。移除某条覆盖恢复该段原始内容;显式空字符串与移除覆盖不同。原始声明仍只读。 加载通过 Agent 上下文的同名提示词段注册完成,保留原段的完整模式、插值和位置。Host 卸载与 Agent 清理都拥有 disposer;不通过全局 presentation 重写抢其它插件的内容,不替换工具 schema 或宿主运行约束。无覆盖时不增加模型文本。 ## 统一作用范围与旧数据 普通界面不再暴露共享执行/计划/patch 可用性开关。旧字段仅作为内部兼容基线读取,不自动写回 profile:旧关闭默认保持;明确的逐预设选择可覆盖该旧基线,但不能突破原预设局部禁用、其它插件限制、沙箱或审批。 Codex 自有工具通过内部元数据辨认,不把第三方同名工具误当作 Codex 能力。旧局部预设配置显式 `true` 原先优先于共享关闭,这种既有有效行为也保留。策略与旧基线一起在新 Agent 创建时抓取,后续旧共享字段变化不会突然击穿已加载的替换。 “不改动”描述本方案不改变原能力,不保证某个条件工具在所有模型和会话中均可调用。目录提供原预设启用状态及兼容上下文,界面与 Host 使用同一策略解析;未满足依赖的替换不能留下半套原生/替代状态。供应商 wire 格式仍保留旧选择,不用协议偏好二次控制工具准入。 ## 生效与撤销 Config 使用 live / volatile 更新。每个新创建的 Agent 捕获当时的规则快照;保存规则不重启插件,不改已经加载的 Agent。空白会话在开始第一轮前切换预设时,按该 Agent 捕获的快照同步撤销旧覆盖并匹配新预设。 这里的边界是 Agent,而不只是会话文件:重启应用、恢复或重新载入会话会创建新的 Agent,因此会使用当时已保存的规则。安装插件前已经运行的 Agent 不会被追溯改造。 禁用、卸载或实际重载插件会清理它拥有的覆盖,恢复原工具。请先让相关会话停止执行或退出,再进行此类操作;不能保证已准备但未开始的工具调用在中途卸载后继续有效。 ## 为什么不用 UI Slot 代替 当前页面有 `tool.call.toolview`(按工具名)和 `conversation.chat.node`(整条消息)等 Slot,可以换工具卡片。它们不改变模型可见 schema、参数验证或实际执行,隐藏红色卡片也不等于修复失败。 真正裁剪由作用域中的 `tools.restrict()` 完成,替换由工具注册完成;不篡改 `system-prompt/assemble` 中已由工具提供者管理的列表,也不在失败后静默执行另一工具。当前层的 own 注册不受继承掩码限制;对预设祖先层的裁剪必须放在 Agent 子作用域,不能把规则塞进被裁剪预设自身。 截图里的猜错文件路径、查询未注册 Service、Client 超时以及外层测试沙箱限制,也不会因换个工具名自动消失。应分别检查路径发现、接口目录、连接状态与权限,不抹去原错误。 ## 性能测量 运行: ```sh pnpm run build pnpm run bench:tools ``` [基准脚本](../scripts/benchmark-tool-policy.mjs) 使用当前 Cordis 作用域、工具注册表、标准 Native 执行器、官方文件/搜索/PowerShell/Todo 工具和真实覆盖插件;不发送模型请求,不执行 OS 命令,不进行文件修改。Agent owner 与预设身份表是轻量测试装配,不是完整 AgentLoop。 基线保留 `read/write/edit/apply_patch/glob/grep/pwsh/todo_write` 八项,比较直接叠加、保留文件工具的执行/计划替换,以及仅供对照的极简方案。所有其它 Harness 工具不在这个受影响子集内,不能把该子集的节省比例当成整次请求节省比例。 指标包括 registry schema 的 JSON 字节和 `o200k_base` 参考编码 token、带 16 对历史补丁调用的 Responses 示例 wire、提示词段,以及 `resolve + schemas`、提示词组装、无 I/O Native 调度和新 Agent 监听器的中位数 / P95。示例 wire 使用真实重写函数,但不是远端 provider 实际请求或计费记录。 [机器可读结果](tool-policy-benchmark.json) 由脚本产生。离线微基准不能证明模型首 token 延迟、任务成功率、缓存命中率或真实读写/命令速度改善。裁剪不卸载底层服务,也不等于减少整个 Host 的内存或冷启动成本。 ### 本次实测结果 以下表格保留 `0.2.24` 的历史基准;`0.2.25`–`0.2.26` 仅调整界面,`0.2.27` 新增逐工具规则与目录,`0.2.28` 统一预设策略与界面保存范围。未重测浏览器渲染或真实模型任务,不把旧微基准直接当作新版端到端提速证据。 2026-11-10,Windows x64,Node `v24.21.0`,Ryzen 9 5900HX;每项 1,200 次交错采样,组装 600 次,Agent 监听器 50 次,均有预热。统计仅限上述受影响工具子集,参考编码为 `o200k_base`,不是当前模型的计费 token。 | 方案 | 工具数 | schema 字节 | schema 参考 token | 工具说明段 token | 两项合计 | | --- | ---: | ---: | ---: | ---: | ---: | | 原生基线 | 8 | 9,234 | 1,971 | 261 | 2,232 | | 两套直接叠加 | 11 | 12,378 | 2,632 | 261 | 2,893 | | 保留文件工具、替换执行/计划 | 9 | 8,234 | 1,733 | 331 | 2,064 | | 极简对照,不推荐 | 4 | 4,330 | 911 | 228 | 1,139 | 推荐方案的 schema token 比原生基线少 **12.1%**,但加上必要的新工具说明后,净减少是该子集的 **7.5%**;相对两套直接叠加,净减少 **28.7%**。这不是整次模型请求减少的比例,未计入的其它工具、对话历史和运行时上下文仍会占用 token。工具数从 8 变 9 也能降低 schema 成本,因此不能只比较工具数量。 | 本地操作 | 原生中位数 / P95 | 推荐方案中位数 / P95 | | --- | ---: | ---: | | 本步准入解析 + schema | 0.128 / 0.151 ms | 0.224 / 0.257 ms | | 提示词组装 | 0.304 / 0.372 ms | 0.314 / 0.372 ms | | 无 I/O Native 调度 | 0.134 / 0.282 ms | 0.135 / 0.281 ms | | 新 Agent 监听器 | 0.082 / 0.151 ms | 1.239 / 2.199 ms | 推荐方案比基线多约 **0.096 ms / step** 的准入与 schema 开销,一次 Agent 覆盖约增加 **1.16 ms**;无 I/O 调度中位数只差约 1 微秒,本次结果不足以推断有意义的执行速度变化。现阶段主要价值是工具协议适配和上下文预算,不是本地调度提速。 带 16 对历史补丁调用、双方使用相同 Responses 重写条件的示例 wire,基线 2,932、推荐方案 2,698 参考 token;这是确定性重写样本,不是在线请求计费或首 token 延迟。只换同名实现但 schema 不变的对照,schema 仍为 1,971 token,也未观察到明显调度差异。 极简方案虽然更短,却失去结构化读取、搜索和直接文件编辑能力,更依赖 shell 引用、平台语法及输出处理;本插件没有默认选择它。真实模型效果仍需在相同模型、任务、缓存与权限设置下对照工具选择错误、参数错误、重试轮数、总 token 和任务成功率。