dsh-agent-toolface

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

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

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

能力

默认 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，工具面恢复全量。

配置

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

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

一条命令答五问：

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 漂移。

相关文档

License

MIT © jonah791

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