feat(tool-search): expand dynamic group activation

README.md

@@ -17,7 +17,7 @@
 - 本仓库维护的 `pi-notify`：基于 `@smoose/pi-notify@0.1.1`，使用 Kitty OSC 99 在 Pi 完全 settled 后通知，并支持点击精确聚焦来源 Kitty 窗口。
 - `pi-condense@2.9.1`：把已完成的工具调用批次总结为可恢复的短摘要，并通过 `context_tree_query` 按需取回原始输出；组合包首次加载时默认开启。
 - 本仓库维护的 `pi-ask-user`：提供模型主动调用的 `ask_user_question`，用一个顺序 TUI 同时支持单题、多题、选择题、文本题、自定义回答与提交前复核。
-- 本仓库维护的 `pi-tool-search`：从完整工具定义生成并缓存经过校验的工作流分组，以最多 3 个动态组的 LRU 策略按组加载原始完整 schema。
+- 本仓库维护的 `pi-tool-search`：从完整工具定义生成并缓存经过校验的工作流分组，默认以最多 5 个动态组、28 个动态工具的 LRU 策略加载原始完整 schema，并支持原子批量激活。
 - `pi-chrome@0.15.46`：通过显式会话授权接入用户当前已登录的 Chrome Profile，并由 Tool Search 按导航观察、页面交互和调试上传三个工作流按需加载 21 个 `chrome_*` 工具。
 - 本仓库维护的 `pi-permission-auto-review`：作为 `pi-permission-system` authorizer，使用 Codex Guardian 风格策略自动复核 `ask` 请求。
 - 本仓库维护的 `pi-permission-system`：从 `@gotgenes/pi-permission-system@26.2.1` 源码导入，负责工具、路径、MCP、硬拒绝和兜底权限基线。
@@ -87,9 +87,8 @@ Git checkout 在 `fetch` 后比较本地与上游提交，Homebrew 包在刷新
 日志中的“Zsh 插件未安装，升级流程跳过”不是升级失败：升级脚本不会新增用户此前未选择的
 插件。需要补装时重新运行 `./install.sh`，并在对应的逐项询问中明确选择 `Y`。
 
-升级时会优先从 `pi update` 后的已安装组合包目录读取最新 `config/p10k.zsh`，再与受管副本比较，
-只在内容不同时备份并原子同步；`.zshrc` 也只更新已有的 my-pi 受管块，不触碰块外配置。因此安装流程负责补齐缺失项，升级流程只升级
-已安装项并同步已受管配置。
+升级时会优先从 `pi update` 后的已安装组合包目录读取最新配置。对于 Pi agent 目录中的 `settings.json`，只有 `toolSearch` 完整匹配旧组合包生成的 `3` 组 / `20` 工具默认快照时，才会备份并原子迁移到当前 `5` / `28` 默认值；任何字段不同、结构无效或存在自定义工具时都不会被覆盖。Powerlevel10k 受管副本只在内容不同时备份并原子同步；`.zshrc` 也只更新已有的 my-pi 受管块，不触碰块外配置。因此安装流程负责补齐缺失项，升级流程只升级已安装项并同步可明确识别的受管配置。
+首次获得这项迁移能力时需要执行已经包含该逻辑的新版 `update.sh`；旧脚本正在运行时不会因为 `pi update` 替换包内容而自动获得后半段迁移步骤。如果刚通过旧脚本升级到含迁移逻辑的版本，可再运行一次更新后的脚本。
 
 卸载组合包：
 
@@ -152,28 +151,35 @@ CodeGraph 本体不由组合包安装。需要使用 CodeGraph 的机器应自
 
 本地源码直接使用 `@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`；Windows 上额外把内置 `powershell` 与 `bash` 作为同类本地 Shell 核心工具固定启用，非 Windows 平台则从目录中过滤它。组合包在 `pi-tool-search/extensions/bundle-groups.ts` 中为自身暴露的工具预置权威分组，包括本地文件导航、SSH 远端文件/命令、Chrome 导航/交互/调试、用户交互、CodeGraph/LSP、Tavily、Exa、Keenable、Context Mode 执行/知识库/观测/管理、Memory 查询/维护、Skill 和 MCP 管理。不可用或尚未授权而未注册的可选工具会自动从组中滤除，固定工具也不占动态组额度。
+新 session 默认常驻 Pi 核心 `read`、`write`、`edit`、`bash`、`grep`、`find`，以及 `codegraph_explore`、`lsp_diagnostics`、`ctx_execute`、`ctx_execute_file`、`ctx_batch_execute` 和 `tool_search`；Windows 上额外把内置 `powershell` 与 `bash` 作为同类本地 Shell 核心工具固定启用，非 Windows 平台则从目录中过滤它。组合包在 `pi-tool-search/extensions/bundle-groups.ts` 中为自身暴露的工具预置权威分组，包括本地文件导航、SSH 远端文件/命令、Chrome 导航/交互/调试、用户交互、CodeGraph/LSP、Tavily、Exa、Keenable、Context Mode 执行/知识库/观测/管理、Memory 查询/维护、Skill 和 MCP 管理。不可用、已固定或尚未授权而未注册的可选工具会自动从动态组中滤除。
 
-标准组合包的全部隐藏工具都能命中预置目录，因此首次使用不调用模型、不生成用户缓存，也不把完整隐藏 schema 发送给 provider。只有用户另外安装了未识别工具，并且当前调用不是精确加载已有分组时，才可使用当前已认证模型补充目录；精确已有分组始终立即按当前确定性目录激活，不等待无关未知工具的模型增强。模型结果必须保留组合包预置分组，否则直接拒绝。有效增强缓存以 `0600` 写到 agent 目录的 `tool-search/catalog-v1.json`，调用用量计入工具结果。用户 `groupOverrides` 的优先级高于预置目录；`/tool-search-rebuild` 会立即恢复预置目录，只有仍存在额外工具时才可能在后续未知分组或 query 搜索中惰性增强。
+标准组合包的全部隐藏工具都能命中预置目录，因此首次使用不调用模型、不生成用户缓存，也不把完整隐藏 schema 发送给 provider。只有用户另外安装了未识别工具，并且当前调用不是精确加载已有分组时，才可使用当前已认证模型补充目录；精确已有分组始终立即按当前确定性目录激活，不等待无关未知工具的模型增强。模型结果必须保留组合包预置分组，否则直接拒绝。有效增强缓存以 `0600` 写到 agent 目录的 `tool-search/catalog-v1.json`，调用用量计入工具结果。用户 `groupOverrides` 的优先级高于预置目录；`/tool-search-rebuild` 会恢复预置目录，`/tool-search-status` 显示目录来源、容量、LRU 顺序和最近淘汰原因。
 
-动态组默认最多同时加载 3 个、每个模型生成组最多 8 个工具、全部动态组最多 20 个工具。加载或调用组内工具会更新 LRU；加载第 4 组或超出工具总量时先卸载最久未使用的非固定组。首次纯增加载继续使用 Pi 原生增量传播；发生卸载和加载的替换不是纯增量，Pi 会自动走安全 fallback。
+动态组默认最多同时加载 5 个、每个模型生成组最多 8 个工具、全部动态组最多 28 个工具。`tool_search.groups` 可在一次调用中原子加载最多 5 个精确组；完整请求本身超限时保持原状态。加载或调用组内工具会更新 LRU，超限时先卸载最久未使用且不在本次请求内的组。自然语言 query 对精确工具名和已提交 workflow alias 加权，弱匹配或近似同分只返回候选。首次纯增加载继续使用 Pi 原生增量传播；发生卸载和加载的替换由 Pi 自动走安全 fallback。
 
-首次加载仅在 `settings.json` 缺少对应字段时写入：
+Pi 的用户级配置文件通常是 `~/.pi/agent/settings.json`（准确位置为 Pi agent dir 下的 `settings.json`）。组合包首次加载仅在其中缺少对应字段时写入：
 
 ```json
 {
   "toolSearch": {
-    "alwaysEnabled": ["codegraph_explore", "lsp_diagnostics"],
+    "alwaysEnabled": [
+      "codegraph_explore",
+      "lsp_diagnostics",
+      "ctx_execute",
+      "ctx_execute_file",
+      "ctx_batch_execute"
+    ],
     "showToolSearchFooterStatus": false,
-    "maxActiveGroups": 3,
+    "maxActiveGroups": 5,
     "maxToolsPerGroup": 8,
-    "maxDynamicTools": 20,
-    "groupOverrides": {}
+    "maxDynamicTools": 28,
+    "groupOverrides": {},
+    "bundleDefaultsVersion": 2
   }
 }
 ```
 
-用户已有配置不会被覆盖；结构无效时也不会重写原文件。`alwaysEnabled` 中的精确工具名属于固定工具，不占动态组额度；`groupOverrides` 可把指定工具强制归入命名组。默认关闭状态行，避免与 minimal footer 叠加。
+扩展正常加载只补充缺失字段，不覆盖用户已有配置；首次创建完整 Tool Search 默认段时也写入 `bundleDefaultsVersion: 2`。用户显式运行新版 `update.sh` 时，脚本会在 `pi update` 成功后使用更新后组合包中的 Node helper 检查完整旧默认快照：只有精确匹配旧版 `3`/`20` 默认值才会创建权限 `600` 的时间戳备份并原子替换为当前配置；任何自定义或无效配置都会保留，提交前检测到文件内容变化也会中止。`alwaysEnabled` 中的精确工具名属于固定工具，不占动态组额度；`groupOverrides` 可把指定工具强制归入命名组。默认关闭状态行，避免与 minimal footer 叠加。
 
 ### 精确读写归 Hashline