mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-10-26 10:45:22 +00:00
云服务部-叶林立andDevin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
dae1a01f23
真实会话中模型仍用 bash grep -o | sort -u 做抽取，被拒后直接放弃核对； 原提示词只说"不要"，没告诉它抽取/计数、给程序传文件清单、过滤命令输出时该用什么。 - routing：按已知信息选 grep/find（多变体用 grep 正则 alternation）， codemode + tools.grep 做聚合，bash 文件清单用 git ls-files， overflow_query 过滤输出，被拒后改用替代方案继续 - 权限策略：rg/grep/git grep/find/fd 的 deny 附带指向替代工具的 reason - tools.jsonc：grep/find 新 snippet，补上 codegraph_explore snippet - FFF 上游标注 multi_grep 有害：wrapper 删除 PI_FFF_MULTIGREP，清理全部引用 - JSONC 测试改用字符串感知的注释剥离（reason 中含 'src/**/*.ts'） Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
141 lines
8.5 KiB
Markdown
141 lines
8.5 KiB
Markdown
# pi-tool-search
|
|
|
|
Bounded, model-assisted tool-group loading for Pi. This source is maintained directly in the `my-pi` bundle from upstream `v0.3.6`; see [UPSTREAM.md](./UPSTREAM.md).
|
|
|
|
## Why
|
|
|
|
A name plus a truncated first sentence can misrepresent a tool, while an add-only active set eventually restores every full schema in a long session. This maintained version instead builds validated retrieval metadata from complete tool definitions, presents compact group cards, activates whole workflow groups, and caps the dynamic active set with LRU eviction.
|
|
|
|
Generated metadata never replaces executable schemas. Exact names, parameter types, required fields, and source definitions remain authoritative in Pi. The repository provides curated metadata for its own tools; a model may generate only summaries, usage guidance, keywords, and assignments for additional unrecognized tools.
|
|
|
|
## Catalog lifecycle
|
|
|
|
1. `session_start` keeps `tool_search`, Pi core tools, and configured `alwaysEnabled` names active. PowerShell is filtered out on non-Windows hosts; on Windows it is pinned beside Bash as the same local-shell capability class. Tools whose exposure is `hidden` or `codemode` (script-only, unreachable by the model directly) are excluded entirely; `model-only` tools such as the built-in `codemode` stay reachable and can be pinned.
|
|
2. Hidden tool definitions are hashed with the grouping constraints.
|
|
3. Every tool exposed by the standard `my-pi` bundle is matched against the checked-in catalog in `extensions/bundle-groups.ts`. If all tools are recognized, no model call and no user cache are needed.
|
|
4. User `groupOverrides` take priority over checked-in assignments. Optional or unavailable bundle tools are simply filtered out of their predefined groups.
|
|
5. Additional user or third-party tools receive deterministic prefix/source groups immediately. A matching private model-enriched cache at `<agent-dir>/my-pi/tool-search/catalog-v1.json` is reused when present.
|
|
6. Only when unrecognized tools exist and the call does not name an exact existing group may `tool_search` ask the current authenticated model to enrich the complete catalog. Exact group activation always uses the current deterministic catalog immediately. Validation requires all checked-in bundle tools to remain in their predefined groups before a `0600` cache is accepted.
|
|
7. Missing authentication, invalid JSON, timeout, cancellation, changed bundle assignments, or cache errors leave the checked-in plus deterministic hybrid catalog usable.
|
|
|
|
A standard bundle installation therefore sends no tool definitions to a model during catalog setup. Complete definitions are sent to the selected provider only when extra unrecognized tools require enrichment during an unknown-group or query lookup; exact existing group loads never wait for that nested call. Any nested-call usage is attached to the `tool_search` result.
|
|
|
|
Run `/tool-search-status` to inspect the current catalog source, pinned count, dynamic capacity, LRU order, and latest eviction reason. Run `/tool-search-rebuild` to remove model enrichment; standard bundle tools immediately return to the checked-in catalog and extra tools can be enriched lazily on the next search.
|
|
|
|
## Precomputed my-pi groups
|
|
|
|
| Group | Bundle tools |
|
|
|---|---|
|
|
| `filesystem-navigation` | `ls` |
|
|
| `ssh-connection` | `ssh_connect` |
|
|
| `ssh-remote-files` | `ssh_read`, `ssh_write`, `ssh_edit` |
|
|
| `ssh-remote-search` | `ssh_find`, `ssh_grep` |
|
|
| `ssh-remote-shell` | `ssh_cd`, `ssh_bash` |
|
|
| `code-intelligence` | CodeGraph and all LSP tools |
|
|
| `web-search` | `web_search`, `web_fetch` (pi-web-search unified tools) |
|
|
| `memory-recall` | Hermes memory/session search and condensed-output recovery |
|
|
| `memory-management` | Hermes memory writes and procedural skill management |
|
|
| `subagents` | Launch agents, collect background results, and steer running agents |
|
|
| `user-interaction` | `ask_user_question` model-initiated TUI/RPC questions |
|
|
| `chrome-navigation` | Chrome bridge setup, tabs, navigation, snapshots/find/inspect, waits, and screenshots |
|
|
| `chrome-interaction` | Chrome click/type/fill/key/hover/drag/tap/scroll input |
|
|
| `chrome-debugging` | Chrome page evaluation, console/network diagnostics, response retrieval, and file upload |
|
|
|
|
Pinned tools are removed from these dynamic groups at runtime. The defaults pin `codegraph_explore`, `lsp_diagnostics`, all six Hermes memory tools, `context_tree_query`, `overflow_query`, and `codemode`, so none of them consume dynamic group or tool capacity.
|
|
|
|
## Loading and eviction
|
|
|
|
Call `tool_search` with an exact catalog group id when possible:
|
|
|
|
```json
|
|
{ "group": "web-search" }
|
|
```
|
|
|
|
A workflow can atomically activate up to five exact groups in one call. The complete request must fit the configured group and tool limits; otherwise no active state is changed:
|
|
|
|
```json
|
|
{
|
|
"groups": ["ssh-connection", "ssh-remote-shell", "ssh-remote-files", "ssh-remote-search"]
|
|
}
|
|
```
|
|
|
|
A natural-language `query` uses weighted group, alias, and exact-tool-name metadata when the group is unclear. Weak or closely tied matches return ranked candidates without activating an arbitrary group. Loading exposes the original full schemas on Pi's next model request.
|
|
|
|
Pinned tools do not consume the dynamic budget. Dynamic groups update their recency when loaded or when a member starts executing. Loading beyond `maxActiveGroups` or `maxDynamicTools` atomically evicts least-recently-used non-requested groups before activation.
|
|
|
|
The first loads are purely additive and retain Pi's native deferred-loading propagation. An eviction necessarily removes and adds schemas in one transition, so Pi uses its safe fallback rather than treating that transition as purely additive.
|
|
|
|
## Configuration
|
|
|
|
Pi reads this configuration directly from the installed bundle's `config/tool-search.json` — the single source of truth, refreshed by `pi update`. A missing, unreadable, or invalid file falls back to the built-in `BUNDLE_TOOL_SEARCH_DEFAULTS`; the extension never writes the file:
|
|
|
|
```json
|
|
{
|
|
"alwaysEnabled": [
|
|
"codegraph_explore",
|
|
"lsp_diagnostics",
|
|
"memory_search",
|
|
"session_search",
|
|
"memory_add",
|
|
"memory_replace",
|
|
"memory_remove",
|
|
"skill_manage",
|
|
"context_tree_query",
|
|
"overflow_query",
|
|
"codemode"
|
|
],
|
|
"showToolSearchFooterStatus": false,
|
|
"maxActiveGroups": 5,
|
|
"maxToolsPerGroup": 8,
|
|
"maxDynamicTools": 28,
|
|
"groupOverrides": {}
|
|
}
|
|
```
|
|
|
|
| Key | Bundle default | Description |
|
|
|---|---|---|
|
|
| `alwaysEnabled` | CodeGraph explore, LSP diagnostics, all six Hermes memory tools, `context_tree_query`, `overflow_query`, `codemode` | Exact names pinned alongside Pi core tools |
|
|
| `showToolSearchFooterStatus` | `false` | Show active tool/group counts |
|
|
| `maxActiveGroups` | `5` | Maximum simultaneously active dynamic groups |
|
|
| `maxToolsPerGroup` | `8` | Maximum size accepted from model-generated groups |
|
|
| `maxDynamicTools` | `28` | Hard cap across active dynamic group tools |
|
|
| `groupOverrides` | `{}` | Exact tool lists that override checked-in, generated, or fallback assignments |
|
|
|
|
Example override:
|
|
|
|
```json
|
|
{
|
|
"groupOverrides": {
|
|
"web-search": ["web_search", "web_fetch"],
|
|
"lsp": ["lsp_definition", "lsp_references", "lsp_hover", "lsp_symbols", "lsp_diagnostics"]
|
|
}
|
|
}
|
|
```
|
|
|
|
An explicit override larger than `maxDynamicTools` remains visible but cannot be activated until the limit or override is corrected. To customize, edit `config/tool-search.json` in the bundle repository and update the bundle — `pi update` refreshes the installed copy.
|
|
|
|
## Current host integration
|
|
|
|
This version directly targets `@earendil-works/pi-coding-agent`, current `typebox`, `ModelRegistry.complete()`, and `ExtensionAPI.setActiveTools()`. It does not load or alias `@mariozechner/pi-coding-agent`, install another Pi runtime, rewrite provider payloads, proxy tool execution, or enqueue hidden `sendMessage` loops.
|
|
|
|
## Repository layout
|
|
|
|
- `extensions/index.ts` — Pi lifecycle, model call, activation, and group LRU
|
|
- `extensions/catalog.ts` — hashing, strict catalog validation, fallback grouping, cache, and ranking
|
|
- `extensions/bundle-groups.ts` — checked-in authoritative groups for tools exposed by `my-pi`
|
|
- `extensions/config.ts` — bundle-deployed config path and config parsing
|
|
- `test/` — catalog, config, model-generation, and active-set tests
|
|
- `docs/dynamic-tool-loading.md` — current Pi propagation and replacement behavior
|
|
- `UPSTREAM.md` — imported snapshot and local divergence
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm install
|
|
npm run typecheck
|
|
npm run test
|
|
npm run build
|
|
```
|
|
|
|
The root bundle loads `./pi-tool-search/extensions/index.ts` directly and references this package through `file:./pi-tool-search`.
|