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

[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。