工具面分档 jonah791/dsh-agent-toolface

dsh-agent-toolface

一句话：把「模型可见的工具集合」按证据化的 deny 集收窄，并提供一键恢复——toolface(action="lean"|"full")。

为什么值得用：一次请求的工具 schema 是固定上下文成本——压缩回收不掉，且工具越多、选择越被稀释。实测（2026-09-13，本机）：

| 指标 | 值 |
| 工具面总量 | 274 个工具 / 122,076 字符 ≈ 30,519 tok |
| 其中被默认收窄 | 67 个工具 / 30,830 字符 ≈ 7,708 tok（25.3%） |
| 这 67 个工具近 14 天调用 | 29 次（同期总调用 11,600 次 = 0.25%） |

它不删除能力：被收窄的工具仍在注册表中，toolface(action="full") 一行恢复。

能力

| 工具 | 用途 |
| toolface | 工具面分档：查看或切换本会话可见工具的收窄档位（lean=按 deny 收窄，full=全量可见）。收窄只作用于本会话（agent 作用域），不影响其他会话或子代理；档位不持久化，重启回到预设默认。返回 { ok, mode, applied, deniedCount, globalTools, savedChars, savedTokens, unmatched[], reason? } |

| 参数 | 说明 |
| action | status=查看当前档位与省下的体量；lean=按 deny 收窄；full=恢复全量可见 |
| deny | 可选，lean 时覆盖配置的 deny 模式（精确工具名或尾随 的前缀），仅本次会话有效 |

默认 deny 族：sec_ red_ blue_ otw_ xp_ clyan_ video_ download_。

globalTools 是全局面工具数（preset 作用域读到的 schemas() 是全局视图，含其他预设挂载的工具），不是本会话的模型可见数——后者由请求头 tools 实测（本机：收窄前 274 → 收窄后 208）。

快速开始

1) 装依赖（profile 的 node_modules 里需能解析到本插件，与其它自研插件同款 link）：

"dsh-agent-toolface": "link:<工作区>/self-plugins/dsh-agent-toolface"

2) 挂组合——挂在 agent preset（不是宿主组合）：宿主 ctx.tools.restrict() 只接受有作用域的 ctx（拒绝进程级收窄，理由是会掩蔽所有 agent），而 preset 行天然是 agent 作用域。放在所有工具行之后：

.agent-presets/<id>/agent.cordis.yml —— 放在所有工具行之后
- id: toolface
name: dsh-agent-toolface
config:
mode: lean # lean | full（非法值加载即抛错） deny:
- 'sec_'
- 'red_'

3) 30 秒验证：调 toolface { action: "status" } → 应返回 mode:"lean"、applied:true、deniedCount>0、savedTokens>0；再调 action: "full" → deniedCount: 0，工具面恢复全量。

配置

| 项 | 默认 | 说明 |
| mode | lean | 启动档位；非法值（非 lean/full）加载即抛错（不静默降级） |
| deny | [] | 收窄模式列表：精确工具名，或尾随 的前缀通配（如 sec_） |

落盘与自证（出问题时先看这里）

每次「加载 / 切换 / 补挂」追加一行 JSON 到 <DSH_HOME>/toolface-events.log（单行 JSON，无阶段枚举——一个动作一行）：

| 字段 | 含义 |
| at | ISO 时间戳 |
| action | load（预设默认档生效）/ lean / full |
| mode | 切换后的档位 |
| applied | 是否真的调用了 restrict（false = 未命中或 restrict 抛错，配合 reason 看） |
| deniedCount | 被 deny 的工具数 |
| globalTools | 全局面工具数（收窄前基线） |
| savedTokens | 按宿主口径（4 字符/token）估算省下的 token |
| unmatched | 未命中任何工具的 deny 模式（不静默：全未命中时不调用 restrict） |

一条命令答五问：

tail -3 "$DSH_HOME/toolface-events.log"
① 跑的是哪个构建 → 本插件轨迹不含 build 戳（见「生效判据」用 plugin_boot_status / lib mtime 判定） ② 谁发起 → action（load 即插件装载时的默认档） ③ 断在哪一段 → applied + reason（false 且 reason 非空 = 收窄没落地） ④ 结果质量 → deniedCount / globalTools / savedTokens ⑤ 耗时与预算 → 本插件不含 durationMs（收窄是同步内存操作，无预算概念）

写盘失败不影响收窄本身（审计是旁路）。

生效判据与回退

生效判据（三选一，按可靠性排序）：
1. toolface { action: "status" } 返回 applied:true + deniedCount>0 ⇒ 收窄已落地（行为级，最快）；
2. tail -1 "$DSH_HOME/toolface-events.log" 最新一行的 mode/deniedCount 与你的切换一致 ⇒ 审计层确认；
3. 生态级：plugin_boot_status（dsh-plugin-bootreport）返回 liveNow 含本插件 ⇒ 当前进程跑的是当前构建。

注意：重新构建 ≠ 生效——产物 mtime 新只证明「构建过」，进程启动时间晚于产物 mtime 才算「在跑它」。本插件的收窄是 preset 装载期动作，改代码后必须重启或重挂 preset 才生效。

回退（三档）：
- 源码级：git -C self-plugins/dsh-agent-toolface revert <commit> → 重新构建 → 预检 → 重启；
- 组合级：preset 里给 toolface 行加 disabled: true（或把 mode 改回 full）→ 哨兵重启；
- 运行期：toolface { action: "full" } 立即恢复全量（本会话），不持久化——重启即回预设默认档，一次临时放开不会变成长期默认。

测试

npm test # = node --test "tests/.test.mjs"

20 例离线测试（跑 tests/，纯逻辑层，不依赖宿主运行时）：
- tests/logic.test.mjs — 模式解析（expandPatterns）、体量估算（faceCost）、档位决策（denyFor）、审计行（auditLine，含「reason 存在时才写该字段」）
- tests/apply.test.mjs — apply 路径：非法 mode 抛错、全未命中时不调用 restrict、restrict 抛错时插件仍加载并报 applied=false

无网络、无外部依赖（ctx.tools 以桩替代）。

设计要点

- 必须挂 agent preset，不能挂宿主组合：ctx.tools.restrict() 拒绝进程级收窄（会掩蔽所有 agent）；preset 行天然 agent 作用域，收窄只影响挂载该预设的会话。
- 不静默：模式全部未命中时不调用 restrict（宿主对未知工具名抛错）并记入 unmatched；restrict 抛错时插件仍加载，status 报 applied=false + 原因。
- 可见性而非安全边界：被 deny 的工具对模型不可见，但进程仍有该能力——需要真隔离请用沙箱，不要用 deny 当防线。
- 同预设多会话共享档位：宿主把过滤在「呈现/查找/执行」三处保持一致，同一 preset 的多个会话共享 standing mount，一处切换处处一致。
- savedTokens 是估算：宿主口径 4 字符/token 的单工具之和，与整份 header 计价存在数个百分点差异。
- 零副本：本插件 node_modules 以 junction 指向宿主 store，避免 @deepseek-ai/* 本地副本造成的版本滞后与运行期 class 漂移。

相关文档

| 文档 | 内容 |
| docs/semantic.md | 权威契约：定位与反定位、术语、概念模型与不变量、契约（含调用点清单）、边界与信任、可证伪验收清单、实践修订记录、未决问题 |
| alice-digital-life | 本插件所属生态的中心索引（全部自研插件） |
| 技能 context-stewardship | 上下文管理：把工具 schema 固定成本纳入「主动管理」的判据 |
| 技能 plugin-maintainability | 插件可维护性工程（审计留痕 / 五问可取 / 观测不反噬） |
| 技能 dsh-plugin-pitfalls | scoped 包名键名、模块双实例、schema 严格校验等踩坑规避 |

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。