feat: vendor grouped tool search

README.md

@@ -15,6 +15,7 @@
 - `@ogulcancelik/pi-codex-compaction@0.1.3`：为 `openai-codex` 提供原生远程压缩。
 - `@ogulcancelik/pi-minimal-footer@0.1.10`：用紧凑的上下文仪表和订阅用量条替换默认 footer。
 - `pi-condense@2.9.1`：把已完成的工具调用批次总结为可恢复的短摘要，并通过 `context_tree_query` 按需取回原始输出；组合包首次加载时默认开启。
+- 本仓库维护的 `pi-tool-search`：从完整工具定义生成并缓存经过校验的工作流分组，以最多 3 个动态组的 LRU 策略按组加载原始完整 schema。
 - 本仓库维护的 `pi-permission-auto-review`：作为 `pi-permission-system` authorizer，使用 Codex Guardian 风格策略自动复核 `ask` 请求。
 - 本仓库维护的 `pi-permission-system`：从 `@gotgenes/pi-permission-system@26.2.1` 源码导入，负责工具、路径、MCP、硬拒绝和兜底权限基线。
 - `extensions/tool-routing.ts`：保留 Pi 默认系统提示词，并按当前激活工具追加简短的工具与搜索路由规则；提供 `/dump-system-prompt` 导出当前有效提示词。
@@ -101,8 +102,7 @@ PI_PACKAGE_SOURCE="$PWD" ./install.sh
 PI_PACKAGE_SOURCE="git:git@bitbucket.org:siakitem/my-pi.git" ./update.sh
 ```
 
-根 `package.json` 使用精确版本，`package-lock.json` 固定完整依赖树。不要再用项目级
-`.pi/settings.json` 重复安装这些扩展，否则同一扩展可能被加载两次。
+根 `package.json` 对外部依赖使用精确版本，对本仓库维护的包使用 `file:` 路径；`package-lock.json` 固定完整依赖树。不要再用项目级 `.pi/settings.json` 重复安装这些扩展，否则同一扩展可能被加载两次。
 
 Hermes Memory 的 SQLite search 依赖 `better-sqlite3` 原生模块；根包只在 `allowScripts` 中
 精确放行当前锁定版本的构建脚本。若升级 Hermes 或 `better-sqlite3`，必须同步核对并更新该精确
@@ -127,6 +127,35 @@ CodeGraph 本体不由组合包安装。需要使用 CodeGraph 的机器应自
 
 使用 `/dump-system-prompt` 可将当前扩展所见的有效提示词写入当前项目的 `.pi-debug/effective-system-prompt.md`。`.pi-debug/` 属于本地诊断输出，默认不提交。
 
+### 按需加载工具 schema
+
+`pi-tool-search/` 从上游 <https://github.com/tuansondinh/pi-tool-search> 的 `v0.3.6`、commit `ddfb23646fd3957b791214de278e23aa393c9b13` 导入，并像 `pi-rtk-optimizer/` 一样由本仓库直接维护；它不是 submodule，不加载 npm 预编译入口，也不保留嵌套 `.git`、上游 `.pi` 状态或构建产物。来源、许可证说明和本地差异记录在 `pi-tool-search/UPSTREAM.md`。
+
+本地源码直接使用 `@earendil-works/pi-coding-agent`、当前 `typebox`、`ModelRegistry.complete()` 与 `setActiveTools()`，不安装、别名映射或加载旧 `@mariozechner` runtime，也不使用 provider payload 改写、代理执行或隐藏 `sendMessage` 循环。
+
+新 session 默认常驻 Pi 核心 `read`、`write`、`edit`、`bash`、`grep`、`find`，以及 `codegraph_explore`、`lsp_diagnostics` 和 `tool_search`。组合包在 `pi-tool-search/extensions/bundle-groups.ts` 中为自身暴露的工具预置权威分组，包括文件导航、CodeGraph/LSP、Tavily、Exa、Keenable、Context Mode 执行/知识库/观测/管理、Memory 查询/维护、Skill 和 MCP 管理。不可用的可选工具会自动从组中滤除，固定工具也不占动态组额度。
+
+标准组合包的全部隐藏工具都能命中预置目录，因此首次使用不调用模型、不生成用户缓存，也不把完整隐藏 schema 发送给 provider。只有用户另外安装了未识别工具时，才先为新增工具提供确定性分组，并可在第一次 `tool_search` 时使用当前已认证模型补充目录；模型结果必须保留组合包预置分组，否则直接拒绝。有效增强缓存以 `0600` 写到 agent 目录的 `tool-search/catalog-v1.json`，调用用量计入工具结果。用户 `groupOverrides` 的优先级高于预置目录；`/tool-search-rebuild` 会立即恢复预置目录，只有仍存在额外工具时才可能在下次搜索惰性增强。
+
+动态组默认最多同时加载 3 个、每个模型生成组最多 8 个工具、全部动态组最多 20 个工具。加载或调用组内工具会更新 LRU；加载第 4 组或超出工具总量时先卸载最久未使用的非固定组。首次纯增加载继续使用 Pi 原生增量传播；发生卸载和加载的替换不是纯增量，Pi 会自动走安全 fallback。
+
+首次加载仅在 `settings.json` 缺少对应字段时写入：
+
+```json
+{
+  "toolSearch": {
+    "alwaysEnabled": ["codegraph_explore", "lsp_diagnostics"],
+    "showToolSearchFooterStatus": false,
+    "maxActiveGroups": 3,
+    "maxToolsPerGroup": 8,
+    "maxDynamicTools": 20,
+    "groupOverrides": {}
+  }
+}
+```
+
+用户已有配置不会被覆盖；结构无效时也不会重写原文件。`alwaysEnabled` 中的精确工具名属于固定工具，不占动态组额度；`groupOverrides` 可把指定工具强制归入命名组。默认关闭状态行，避免与 minimal footer 叠加。
+
 ### 精确读写归 Hashline
 
 组合包固定加载 `pi-hashline-edit@0.8.3`，以带 `LINE#HASH` 行锚点的实现覆盖 Pi 内置 `read` 和 `edit`。`extensions/hashline.ts` 在加载扩展前把 `config/pi-hashline-edit.json` 同步到 `~/.pi/agent/hashline.json`：`hashLength` 保持最小的 `2`，`grep` 强制关闭以避免与 FFF 冲突，`replaceText` 关闭以要求修改使用可验证锚点。