对齐 Wolai 侧栏体验并收拢设计入库

design/old/08-legacy-rust-kernel/done/ai-tool-cutover-matrix.md

@@ -0,0 +1,76 @@
+# [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。