# [recycle] AI Tool Cutover Matrix

> 更新时间：2026-04-16
>
> 目标：建立 `builtins` 到 Rust Tool registry 的一一对应矩阵，并明确每个工具当前的割接状态。

## 1. 结论

- 本文覆盖 `docsServerTools`、`mediaServerTools`、`mindmapServerTools`、`onlyofficeServerTools`、`registryBuiltins` 与 `ai-agent/run` 的一一对应关系。
- `docs_search`、`docs_read` 已进入 Rust tool runtime；`ai-agent/run` 在 Convex 模式下直接通过 `executeRustBridgeTool(...)` 执行，`docsServerTools` 仅保留非 Convex / 兼容 fallback。
- `search_web`、`image_read`、`slash_run` 已进入 Rust tool registry，TS 仅保留最小 transport 壳或数据加载壳。
- `asset_extract_outline`、`asset_to_mindmap`、`oo_*` 继续保留 TS transport / 产品编排边界，但 `asset_to_mindmap` 的真正导图写入已收口到 Rust `mindmap_apply_ops`。
- AI 工具链的运行态证据已经补齐：`wolai-frontend/src/lib/ai-agent/runtime/runAgent.test.ts` 已验证 `docs_search -> docs_read` 的 runtime 调用顺序与事件流。

## 2. 一一对应矩阵

| builtin tool | Rust toolset | Rust tool name | 当前状态 | 说明 |
| --- | --- | --- | --- | --- |
| `search_web` | `toolset.readonly` | `search_web` | `RUST_OWNER` | 联网检索已完全切到 Rust runtime，TS route 只保留 transport 壳。 |
| `image_read` | `toolset.media_read` | `image_read` | `RUST_OWNER` | 图片/附件 OCR 结果已由 Rust runtime 统一归一化，TS 仅负责最小 transport 取数。 |
| `slash_run` | `toolset.slash_write` | `slash_run` | `RUST_OWNER` | Rust 负责命令解析与结果标准化，TS 只保留创建/重命名 transport 写壳。 |
| `docs_search` | `toolset.docs_read` | `docs_search` | `RUST_OWNER` | Convex 主链已改为 Rust runtime 执行搜索与结果归一化，TS 仅负责拉取搜索数据集 transport。 |
| `docs_read` | `toolset.docs_read` | `docs_read` | `RUST_OWNER` | Convex 主链已改为 Rust runtime 执行裁剪与结果归一化，TS 仅负责读取目标文档 transport。 |
| `rag_lightrag_query` | `toolset.rag_read` | `rag_lightrag_query` | `TS_TRANSPORT_KEEP` | 依赖外部 LightRAG 服务，不在本轮切换主线。 |
| `asset_extract_outline` | `toolset.onlyoffice_read` | `asset_extract_outline` | `TS_TRANSPORT_KEEP` | 仍需附件下载和 MinerU 解析，长期保留 TS transport / 外部服务编排。 |
| `asset_to_mindmap` | `toolset.onlyoffice_write` | `asset_to_mindmap` | `TS_TRANSPORT_KEEP` | 附件大纲提取仍依赖 TS/MinerU，但真正的导图写入已经改走 Rust `mindmap_apply_ops`。 |
| `oo_get_selection` | `toolset.onlyoffice_editor` | `oo_get_selection` | `TS_TRANSPORT_KEEP` | 客户端插件内执行，Web 侧只做回传。 |
| `oo_replace_selection` | `toolset.onlyoffice_editor` | `oo_replace_selection` | `TS_TRANSPORT_KEEP` | 客户端插件内执行，Web 侧只做回传。 |
| `oo_insert_text` | `toolset.onlyoffice_editor` | `oo_insert_text` | `TS_TRANSPORT_KEEP` | 客户端插件内执行，Web 侧只做回传。 |
| `oo_insert_html` | `toolset.onlyoffice_editor` | `oo_insert_html` | `TS_TRANSPORT_KEEP` | 客户端插件内执行，Web 侧只做回传。 |
| `oo_insert_image` | `toolset.onlyoffice_editor` | `oo_insert_image` | `TS_TRANSPORT_KEEP` | 客户端插件内执行，Web 侧只做回传。 |

## 3. Rust registry 对照

- `toolset.readonly`：`search_web`
- `toolset.media_read`：`image_read`
- `toolset.slash_write`：`slash_run`
- `toolset.docs_read`：`docs_search`、`docs_read`
- `toolset.rag_read`：`rag_lightrag_query`
- `toolset.onlyoffice_read`：`asset_extract_outline`
- `toolset.onlyoffice_write`：`asset_to_mindmap`
- `toolset.onlyoffice_editor`：`oo_*`

## 4. 本轮 cutover 结果

本轮已完成：

- 以 `ai-agent/run` 为统一入口，对齐 `registryBuiltins` 与服务端 builtin 实现，避免再长出第二套工具分发表。
- 把 `docs_search`、`docs_read`、`search_web`、`image_read`、`slash_run` 接到 Rust tool runtime，并在代码侧绑定里冻结为 Rust owner。
- 把 `asset_to_mindmap` 收口为“TS 提纲提取 + Rust 导图写入”的明确边界，不再保留模糊的 `TS_COMPAT_PENDING` 口径。
- 保留 `oo_*`、`client-tool-result`、`asset_extract_outline` 这类长期 `TS_TRANSPORT_KEEP` / 产品编排壳。

## 5. 后续维护边界

- `docsServerTools` 继续只服务于非 Convex / fallback 模式，不再承担 Convex 主链真执行。
- `asset_extract_outline` 若未来要继续 Rust 化，应只处理解析链迁移，不涉及当前 Rust tool runtime 的 owner 边界回退。
- `asset_to_mindmap` 若未来继续下沉，可进一步把“大纲转导图 ops”的编排逻辑迁入 Rust；在此之前，它已经是明确的 `TS_TRANSPORT_KEEP`。
- `oo_*` 继续保持客户端插件边界，只通过 `/api/ai-agent/client-tool-result` 回传结果。

## 6. 第一批 TS_LEGACY_DELETE 清单

以下旧面已经满足“先停写、再切调用方、最后删除”的文档准备条件，应纳入第一批 `TS_LEGACY_DELETE`：

- `documents/create-child`
- `documents/embed`
- `documents/empty-trash`
- `documents/purge`
- `documents/template`
- `mindmap-trash/empty`
- `builtins/**`

删除原则：

- `documents/create-child`、`documents/embed`、`documents/empty-trash`、`documents/purge`、`documents/template` 仅允许保留 route transport 壳，不再保留 route 内私有业务逻辑。
- `mindmap-trash/empty` 需要在确认 Rust tool/runtime 与统一失败落账稳定后，删除 TS 旧实现。
- `builtins/**` 中已经被 Rust tool runtime 接管的服务端真入口，应先收口到 `ai-agent/run` 或 Rust runtime，再物理删除 legacy helper。