主代理工具过滤 Kiol-V/dsh-agent-tool-filter

dsh-agent-tool-filter

英文版见 README.en.md。

为 DeepSeek Harness 提供主智能体（负责任务调度的那个）的按智能体工具过滤器。

目标是让工具集互相独立：选中的预设只拿到裁剪过的工具集（每个请求里的工具 schema 都省了开销），子代理保留完整工具集，包括 web。DSH 本身没有针对主智能体的按智能体过滤器。

安装前必读

01. 插件能力可能和 DSH 的更新撞车。 按智能体过滤的功能以后可能直接做进平台本身。装插件之前，先看当前 DSH 版本和它的更新列表：如果需要的功能已经原生支持，就不用再装单独的插件了。
02. 过滤只对主智能体生效。 它身上被隐藏的工具会关掉；子代理那边照样能用——插件不会自动把限制带过去。想让限制贯穿全局：
- 给每个子代理配一个自己的预设，带上合适的工具集。比如做网页搜索，就给子代理只留 web 工具和 read；其他场景挑各自合适的组合；
- 给主智能体写清工作流：任务需要被隐藏的工具时，不要直接去调，而是把任务交给有这个工具的子代理。
不做这些配置，智能体会一头撞在已关闭的工具上，而不是去委派——过滤是生效了，工作流却断了。

用预设限制工具集不适合这个任务：它在创建会话时就固定下来，还会被子代理继承，把子代理和主智能体一起限制住。插件的掩码只作用于主智能体，改动时不受这些约束。

机制

01. 在 agent/created 事件上（listeners 在第一次组装提示词之前就跑完了），插件确定智能体的预设（agentPresets.composedPreset(agent.ctx)），再按「预设 → 配置档」的配置矩阵选出过滤配置档。
02. 限制加在智能体自己的 scope 上：agent.ctx.tools.restrict(...)。只过滤根智能体：in-process 子代理会挂到父级的预设上（composeFrom），显示的是同一个预设——不检查 roots() 的话，过滤器会误伤子代理。SDK 子代理跑在独立进程里，完全不受影响。
03. restrict() 的掩码会叠加，所以改配置时旧限制会先撤掉（disposers），再重新加上新的。状态存在智能体自己身上，插件热重载后依然保留。
04. scope 自己的 registrations（structured-output 之类）restrict() 不会掩码。

配置

包通过 Plugin Manager 以 bundle 形式安装，自身提供插件行。
在 UI 卡片里配置矩阵和配置档；改动即时生效（HMR）。下面是配置值示例：

~~~yaml
- insert:
- id: agent-tool-filter
name: dsh-agent-tool-filter
config:
enabled: true
presets: # 矩阵「预设 id → 配置档名」；留空 = 哪里都不过滤 cordis: cordis-trim standard: minimal-orchestrator profiles: # 自定义配置档与默认配置档的修改（按名称覆盖） my-profile: mode: deny # deny — 移除列出的项；allow — 只保留它们
tools: [web_search, web_fetch]

| 字段 | 默认值 | 含义 |
| enabled | true | false — 插件不生效 |
| presets | 空 | 矩阵「预设 → 配置档」；留空 = 不过滤任何东西（安装不改变预设行为） |
| profiles | 内置（见下文） | 自定义配置档；名称相同会覆盖内置配置档 |
| language | auto | 插件 UI 语言：auto — 跟随应用，或 ru / en |

过滤配置档与模板

默认只装一个通用配置档；其余配置档通过从 UI 卡片直接导入模板包来添加。

| 配置档/包 | 内容（deny） | 思路 |
| balanced（内置） | 管理类：plugin_manager、security_audit、test_drive、drive_report、create_skill、subagent_fork | 适用于任何预设的基础裁剪 |
| 包 gradient | strict（管理 + web）、soft（web） | 围绕 balanced 的逐级限制 |
| 包 roles | focus、no-web、no-admin、minimal | 按用途划分的配置档 |
| 包 layers | no-web、no-admin、no-dev-skills | 一个类别 = 一个配置档，用副本组合 |

任何配置档都能复制后按需修改（自己的 tools 列表、deny/allow 模式）；内置的 balanced 可按名称覆盖，但不能删除。

安装做了什么

包不添加预设、工具和别人的配置——只添加插件文件和一行 bundle，带安全的默认配置。首次激活时，插件扫描已安装的 DSH（真实 tools 和预设），拿裁剪配置档与你的集合比对；报告写入日志。在你把预设和配置档关联起来（presets 矩阵）之前，过滤是关闭的。详细说明见 docs/filtering-guide.md。

UI

UI 卡片（v1.0.0）从 Plugin Manager 打开：dsh-agent-tool-filter 行 → Configure。卡片里：

- 「过滤已启用」开关和状态（带掩码的智能体、隐藏的 schema 数）；
- 「预设 → 配置档」矩阵，用卡片分两块展示（默认和自定义）：关联/替换/解除配置档，复制预设（带描述预览），删除自定义项；
- 配置档：在弹窗里创建/编辑/复制，三组 tools（已启用、
- 受管 / 不受管、导入模板包；
- 扫描工具 —— 按 DSH 调色板给出汇总（「✅ N 个工具可关闭 / ⚠ M 个工具不可关闭」），并给出带原因的警告；
- 诊断 —— 折叠区块，含技术数据（remote、locale、版本、计数器）；
- 界面支持俄语和英语（语言切换、「跟随应用」模式）；Plugin Manager 里也提供俄语和英语元数据，以及插件原始图标。

名称校验与诊断

- 启动时以及调用 scanTools() 时，插件会把配置档名称与全局工具列表比对。未知名称和不可过滤名称（own-layer registrations：team_task_、spawn_teammate、wait_agent）会进入警告（日志和 UI 卡片），而不是被静默跳过。
- restrict() 在应用时还会额外校验名称：未知名称不会阻塞其余名称（deny 按名称逐个应用），错误会连同被跳过名称的清单写入日志。
- 诊断：「当前过滤器隐藏了多少个 schema」—— 见日志（应用行）和 agentToolFilter.status().agents[].hidden。
- 文件诊断由开关 debugLog 控制（默认关闭），ATF_DEBUG_LOG 可强制开启并指定文件路径。

与服务商的兼容性

插件自动选择工作模式 —— 没有单独设置项。

- 严格服务商会把对话历史里的工具调用与当前工具列表比对：如果工具 schema 被隐藏，而历史里又有它的调用，请求会以服务商错误结束（「服务商返回了错误的工具调用」）。宽松服务商接受这类历史。
- 如果智能体历史里已经含有被隐藏工具的调用，插件会暂时不隐藏 schema，而是拦截被隐藏工具的调用，并提示把任务委派给子代理 —— 这样无论严格还是宽松服务商，历史与工具列表都不会对不上。
- 历史压缩后，聊天切换到常规 schema 隐藏 —— 上下文节省自动生效（已验证：压缩后隐藏的 schema 会从模型请求中消失）。
- 如果被隐藏工具在聊天里从未被调用过，schema 隐藏会立即生效，即使是旧聊天（已验证：聊天无错误运行）。

可逆性（备忘）

- 关闭（enabled: false）和配置修改对新智能体生效（创建 / resume / clear）。对活动会话，可靠做法是重启 DSH 或重建智能体（clear / resume）：智能体 scope 会重建，过滤器重新应用。
- 插件还会尝试立即把改动应用到活动智能体（app-boot/config-reload 时 hot-apply），但不要把它当作唯一途径。
- 不重启就移除某个智能体的过滤器：从 presets 矩阵里删除预设并重建智能体；dispose 时限制会自动从智能体 scope 移除。
- restrict() —— 限制模型可见性（并节省 schema），不是 sandbox，也不保证安全。

安装

在 Plugin Manager 中通过 plugin_manager → install_bundle 安装包，指定发布版 .tgz 的路径，或解压后包目录的路径。对于 npm 包，先把它获取到环境可访问的目录，再把包目录的路径传给 install_bundle。管理器会安装并接入 bundle；无需手动修改配置档里的 cordis.patch.yml，也无需把包解压到配置档中。首次激活如有需要，重启 DSH 即可完成。这个包没有依赖；@deepseek-ai/ 模块由宿主提供。