pi-tbox

为你的 Pi 扩展所安装的所有工具提供统一的操作界面。

## 问题所在 你安装的每一个 Pi 扩展都会引入工具。安装一个浏览器、一个搜索索引、一个代码透镜，再加几个 MCP 桥接器——突然之间，模型就同时激活了数十个工具，每一个都在消耗你的 context 预算，无论你是否正在使用它们。Pi 没有提供统一的方式来查看或调整这些工具集合：每个插件都是一座孤岛，关闭工具意味着必须逐一深入每个插件进行设置。 **pi-tbox** 正是横跨在所有插件之上的统一界面。它列出了来自每个扩展的所有工具，允许你在作者声明的层级上切换整个工具集，策划命名的分组，并将模型聚焦于仅完成任务所需的工具——这些设置会在重载和恢复会话时保持不变。 ## 它能带给你什么 一个自然的渐进过程——每一步都是你在拥有了前一步之后自然会想要的下一步： 1. **查看它们。** `/tbox list` 枚举了每个已安装扩展中的所有工具，并按其所属的工具集进行分组。未被任何工具集收录的工具会按来源分组，因此一个只注册工具的插件会像一个声明了工具集的插件一样，作为一个可聚焦的整体显示出来。 2. **切换它们。** `/tbox + on` / `off` 可以在作者声明的层级上翻转整个工具集——这是最自然的寻址边界，而不是单个工具。`/tbox all on|off` 可以一次性翻转所有状态。 3. **对它们进行分组。** `/tbox group edit` 会打开一个由键盘驱动的选择器，用于策划一个命名的工具集集合，该集合会全局保存，因此可以在任何目录下使用。依赖（`requires`）闭包会在两个方向上自动维护——一个分组始终是一个连贯的闭合集合，因此 `/tbox research on` 只会启用可见的内容，没有任何隐藏的级联效应。 4. **聚焦于子集。** `/tbox focus `（或 `focus +`）将模型限制为 Pi 的内建工具加上这一个单元，并且该选择会*持久化保存在聊天状态中*——它能在重载和恢复会话时保留，并且即使安装了新扩展也不会产生偏移。`focus off` 可恢复默认设置。 5. **查看开销。** 状态栏插槽可一目了然地显示掩码和聚焦状态；`/tbox status` 会报告序列化后的字符计数，并将其划分为 `core` 基准线（内建工具——不可变的开销）和 `extension` 预算（你实际可以通过 `/tbox` 调整的部分），从而使这个数字成为决策工具，而不是一条无用的信息。 ## 快速开始 ``` pi install npm:pi-tbox ``` 然后在任何 Pi 会话中： ``` /tbox # show current state + brief help /tbox list # every tool, grouped by toolset /tbox status # toolsets, groups, focus, and char-count split ``` 状态插槽会自动出现在你的状态栏中，并随着你的切换实时更新。它有四种状态： | 符号 | 状态 | 含义 | |---|---|---| | `○ tbox` | 初始状态 | 全部默认设置——没有进行任何切换或掩码 | | `● tbox n masked` | 计数 | 排除模式，`n` 个扩展工具已关闭 | | `● focus: (n)` | 聚焦 | 特意限制在一个分组/工具集；`n` 个扩展工具处于活跃状态 | | `● focus:∅` | 聚焦-空 | 聚焦已开启，但白名单中没有任何活跃项——状态损坏 | ## 命令 所有命令都在 `/tbox` 快捷方式之下。两条寻址规则确保了界面的清晰：**`+` 前缀代表工具集**，**纯名称代表分组**，因此 `+find` 始终是工具集，而 `find` 始终是分组，即使它们同名也是如此。保留字（`status`、`focus`、`all`、`list`、`group`、`on`、`off`、`edit`、`remove`、`chars`）在创建分组时会被拒绝，因此纯粹的 `/tbox on|off` 命令始终有效。 | 命令 | 效果 | |---|---| | `/tbox` | 当前状态（插槽镜像 + 简短帮助） | | `/tbox list [view] [filter]` | 枚举工具（参见下方的视图和过滤器） | | `/tbox chars` | 预算视图：工具集按 +chars 降序排列 | | `/tbox on` / `off` | 启用 / 禁用一个分组中的所有工具集 | | `/tbox + on` / `off` | 直接启用 / 禁用单个工具集 | | `/tbox +` | 描述该工具集（成员、状态） | | `/tbox group edit` | 在键盘驱动的选择器中策划分组 | | `/tbox group remove` | 删除该分组 | | `/tbox group ` | 描述单个分组 | | `/tbox group list` | 列出每个分组及其包含的工具集 | | `/tbox focus ` / `focus +` | 对一个分组或工具集进入聚焦状态 | | `/tbox focus off` | 退出聚焦 → 恢复默认设置 | | `/tbox all on` / `off` | 启用所有 / 禁用所有非内建工具集 | | `/tbox status` | 完整状态：工具集、分组、聚焦状态、字符计数划分 | ### `/tbox list` 视图和过滤器 ``` /tbox list [--flat] [--active|--inactive] --flat one row per tool, no grouping --active show only active tools --inactive show only inactive tools ``` 默认的分组视图通过“最小工具集优先”原则来解决重叠工具集的问题：每个工具仅在其最具体的包含工具集下显示一次，没有重复。`--active` / `--inactive` 允许你仅关注已启用或已禁用的工具。 ### `/tbox chars` — 预算视图 ``` /tbox chars ``` 这是一个按序列化字符计数降序排列（开销最大的排在最前）的工具集平铺排序列表。内建工具被排除在外——它们是不可切换的基准。没有活跃成员的工具集（消耗 +0 字符）会被省略——它们并没有消耗预算，因此没有可以节省的空间。 没有附加标志。每一行都会报告该工具集的活跃/非活跃划分情况及其 +chars 开销。 ## 概念 **工具集** 是扩展声明的单元（或者由 tbox 为仅注册工具的插件自动注册的单元）。工具集是寻址边界——tbox 切换的是整个工具集，而不是单个成员，因为这是状态持久化保存的粒度。任何已安装扩展中的工具集都会自动对 tbox 可见。 **分组** 是*你*命名的工具集集合，存储在 tbox 自己的配置（`{ toolsets: string[] }` ——仅包含完整的工具集）中。核心库完全不知道分组是什么概念；tbox 在执行时会将分组解析为其包含的工具集。在选择器中策划分组时，会自动在两个方向上维护 `requires` 闭包，因此一个分组在依赖图中始终是一个闭合的集合。分组是全局/用户作用域的——只需定义一次，即可在任何目录下使用。 **聚焦** 是一种比切换更强的约束：它将底层库切换为包含模式，使得只有被聚焦单元的白名单（加上 Pi 的内建工具）处于活跃状态，并且*未知的工具集默认为关闭状态*。这意味着聚焦快照在新扩展安装后依然有效，无需重新应用。当聚焦处于活跃状态时，执行命令（`all on|off`、` on|off`、`+ on|off`）会被拒绝——状态栏宣告了一个已知的有效集合，而在其底层进行切换会使这一承诺成为谎言。请先使用 `focus off`。 **关于偏移，坦诚相告。** `/tbox on|off` 在其运行时写入每个工具集的状态，因此稍后编辑分组不会追溯改变过去的会话——只有生成的按工具集划分的状态被存储了，你可以使用 `/tbox` 命令重新调整。**聚焦是个例外：** 包含模式使其在设计上实现了“零偏移”。如果你希望某个选择保持不变，请使用聚焦；如果你只想进行一次性的切换，请使用 `on`/`off`。 **tbox 不会触碰的内容。** Pi 的内建工具始终处于开启状态，且不在 tbox 的管辖范围内——它们从未被注册到任何工具集中，因此任何分组、聚焦或 `all off` 命令都无法影响到它们。同样，通过 `customTools`（`sdk` 源）嵌入 Pi 的宿主环境注入的工具也不在管辖范围内：它们的存在是由宿主控制的，而不是由扩展系统控制的，因此为它们持久化切换状态在语义上是行不通的。它们会作为只读行出现在 `/tbox list --flat` 中，以便你了解它们的存在。 ### 选择器键盘快捷键 `/tbox group edit` 需要交互式（`tui`）模式。所有按键都可以通过你的用户按键绑定进行重新映射： | 按键 | 操作 | |---|---| | `↑` / `↓` | 导航 | | `Enter` | 切换当前聚焦行的状态 | | `Ctrl+A` | 全部启用（如果搜索处于活跃状态，则应用于过滤后的集合） | | `Ctrl+X` | 全部清除（如果搜索处于活跃状态，则应用于过滤后的集合） | | `Ctrl+S` | 保存到配置 | | `Esc` / `Ctrl+C` | 取消（如果过滤器处于活跃状态，则首先清除搜索） | 该列表采用分页窗口显示（8行），并配有模糊搜索输入框，因此无论存在多少个工具集，它都不会超出可视区域。内嵌的页脚提示会在你切换状态时报告自动勾选的依赖项（`auto-checked: portal.web (required by selection)`）和自动取消勾选的依赖项。 ## 状态如何持久化 tbox 是面向用户的表层；持久化机制存在于其依赖项 [`pi-tool-masking`](https://www.npmjs.com/package/pi-tool-masking) 中，它负责管理按工具集划分的开/关记忆、`requires` 级联，以及使聚焦实现零偏移的包含/排除默认解析模式。 tbox 完全通过该库的事件进行操作，因此它叠加在任何已安装的扩展之上，都不会破坏那些扩展已经依赖的事件流——切换状态能在重载和恢复会话时保留，聚焦能免受新安装的影响，并且不会深入干预扩展的内部机制。 ## 配置 分组作为用户数据存储在 `~/.pi/agent/pi-tbox/groups.json` 中——直接是分组表，没有外层的包装键。在一个目录中定义的分组可以在任何其他目录中使用。（基于项目的*执行默认设置*——即在特定代码库中自动开启哪些分组——是未来的考量点，并且需要在 `.pi/settings.json` 中引用全局分组，而不是重新声明它们。） ## 许可证 AGPL-3.0-or-later。

标签：AI插件, MITM代理, SOC Prime, 上下文管理, 工具管理, 开发工具, 扩展管理, 效率工具, 暗色界面, 自动化攻击