pi-tool-gate

按需工具开关 pi 扩展。 把重 schema 工具默认 inactive，需要时再激活，降低每轮请求 tools[] 的固定 token 占用（subagent schema 一项就 5-8k tokens）。

提供两套入口：

• gate_tools loader 工具（常驻 active）—— 模型自己判断需要某工具时调用，按 query 激活匹配的工具（additive，激活后跨轮保留）。
• /tool-gate 命令（用户手动管）—— status / list / on / off / all / profile / reset / stats，以及无参交互菜单。

工作机制

激活集单源真相

A = (全部工具中 不在 disabled∪userDisabled 或 在 protected∪HARDCODED_PROTECTED 的) ∪ sessionGranted

• disabled：默认 disabled 名单（reset 写回 DEFAULT_DISABLED）
• userDisabled：用户显式 /tool-gate off 的工具（loader 不可激活）
• protected：配置的受保护工具
• HARDCODED_PROTECTED = [read, write, edit, bash]：硬底线，不可被 config 编辑绕过
• sessionGranted：loader 运行时授予的工具集（会话级，session_start 清空）

四道闸（幂等应用）

| 事件 | 动作 | |---|---| | session_start | 清空 sessionGranted，首次应用 | | before_agent_start | 重应用（比对实际 active 与 target，相同则跳过保 cache） | | model_select | 换模型后 active 可能被重置，重应用（sessionGranted 保留） | | session_compact | compaction 后同上 |

防抖比对 pi.getActiveTools() 而非内存签名，外部 reset 后能正确重应用。

不变式

1. P ⊆ A：protected 工具即使写进 disabled 也会被捞回
2. HARDCODED_PROTECTED 不可移除（即使手编 config）
3. off all 永远跳过 P ∪ HARDCODED_PROTECTED
4. A 为空 → 回退全开
5. loader 不可激活 userDisabled 的工具
6. sessionGranted 不可绕过 userDisabled（用户显式 off 后 loader 授予的工具也会被关闭）

默认配置

配置文件：~/.pi/agent/config/tool-gate.json（首次运行自动生成）

默认 disabled 名单（重 schema / 低频工具）：

subagent, subagent_wait, image_gen, image_review, tg_attach,
process_thought, generate_summary, clear_history, export_session,
import_session, get_thinking_history, get_thinking_status, sequential_think,
advisor, memory_search, session_search, skill_manage

默认 protected（永不关闭）：

read, write, edit, bash, grep, find, ffgrep, fffind,
ls, gate_tools, tool-gate, get_goal, create_goal, update_goal, memory

注意：memory / memory_search / session_search / recall 等 proactive 认知工具不在默认 disabled 名单中 —— 它们是模型跨会话记忆的基础，模型不会主动调 loader 找它们，默认关会破坏记忆连续性。

命令

/tool-gate                 交互菜单（切换单个工具开关）
/tool-gate status          当前状态摘要
/tool-gate list            列出全部工具及开关状态
/tool-gate on <name>       开启某工具
/tool-gate off <name>      关闭某工具（写入 userDisabled，loader 不可恢复）
/tool-gate on all          开启全部
/tool-gate off all         关闭全部（跳过 protected ∪ HARDCODED_PROTECTED）
/tool-gate profile <name>  应用预设 profile
/tool-gate reset           重置为默认 disabled 名单（清空 userDisabled）
/tool-gate stats           使用统计

gate_tools loader

模型可调用的参数化工具，常驻 active：

• query（string）：描述需要什么能力（如 "生成图片"、"搜索网页"）
• activate（string[]）：明确指定要激活的工具名
• limit（number，默认 10，最大 50）：最多激活几个匹配工具

loader 候选 = 全部工具 − 当前 active − protected − userDisabled。激活是 additive（setActiveTools([...current, ...toAdd])），且激活的工具加入 sessionGranted，下轮 before_agent_start 保留。

安装

本包是 wuyaos/pi-packages monorepo 的子包。

随整个 monorepo 安装

pi install git:github.com/wuyaos/pi-packages

只加载本子包（filter）

在 ~/.pi/agent/settings.json：

{
  "packages": [
    {
      "source": "git:github.com/wuyaos/pi-packages",
      "extensions": ["pi-tool-gate/index.ts"],
      "themes": [],
      "skills": []
    }
  ]
}

安装后需重启 pi 生效。本扩展会在 session_start 自动应用默认 gate，把重 schema 工具移出 tools[]，可观察到首轮 context token 显著下降（约 20k → 8-10k）。

与 pi-skill-gate 的关系

• pi-skill-gate 管 skills（prompt 扩展层）
• pi-tool-gate 管 tools（pi.getAllTools() / setActiveTools() 层）

两者无冲突，可同时使用。

开发

源码 index.ts 单文件，pi 运行时经 jiti 编译，无需预构建。类型检查：

cd pi-tool-gate
npx tsc --noEmit --skipLibCheck index.ts

（@earendil-works/pi-ai / @earendil-works/pi-coding-agent 模块解析错误在隔离目录下是预期的，pi 运行时环境可正常解析。）

License

MIT