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

2026-04-30 16:18:54 +08:00
parent 8c895b3dc0
commit afb2a5b8a0
89 changed files with 23188 additions and 84 deletions
@@ -0,0 +1,629 @@
+# [recycle] AI 前端精简方案 v1
+
+> 更新时间：2026-04-15
+>
+> 关联文档：
+> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-final-closure-checklist.md`
+> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/ai-tool-cutover-matrix.md`
+> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md`
+
+## 1. 目标
+
+这份方案只回答一个问题：
+
+> **当前网页前端中，AI 相关部分应该如何精简，才能真正降低加载负担，并把前端 AI 收口为“轻桥接层”。**
+
+目标方向已经明确：
+
+> **前端 AI 面板不再承担工具注册、工具编排、能力路由和执行框架，只保留为 Hermes API Server + mnote Rust 业务能力的轻桥接 UI。**
+
+这意味着后续 AI 前端不再是一个“小型平台”，而只是：
+
+- 收集上下文
+- 发送用户输入
+- 展示流式结果
+- 承接极少数浏览器专属 client tool
+
+## 1.1 现状校准：当前真正已经落地的后端 AI 边界
+
+在继续谈“前端该怎么精简”之前，必须先对齐一个事实：
+
+> **当前本机已经有可核验的 Hermes Agent 与其官方 API Server 方案；同时 mnote 自己也已经有 Rust protocol/runtime 边界。后续前端 AI 应该桥接这两层，而不是自己继续承担平台层。**
+
+当前已确认的 Hermes 事实：
+
+- 本机 Hermes 安装目录：`/home/lix/.hermes`
+- Hermes 本体仓：`/home/lix/.hermes/hermes-agent`
+- 当前网关进程已在运行：`hermes gateway run --replace`
+- 官方文档已提供 OpenAI 兼容 API Server：
+  - 启用方式：`API_SERVER_ENABLED=true`
+  - 默认监听：`http://127.0.0.1:8642`
+  - 入口：`/v1/chat/completions`、`/v1/responses`、`/health`
+
+但当前本机状态也要说明白：
+
+- Hermes gateway 在跑
+- Hermes API Server 当前还没有启用
+- mnote 前端当前也还没有接通 Hermes API Server
+
+因此，现阶段不是“是否存在 Hermes”的问题，而是：
+
+- **Hermes 已存在，但还没有接入 mnote Web AI 主链**
+- **mnote Rust 业务能力已存在，但还没有作为 Hermes 的统一业务工具面完全暴露**
+
+当前 mnote 已能明确核验到的 Rust 业务边界是：
+
+- `rust/crates/core-protocol/src/tool.rs`
+  已定义 `ToolSpec`、`ToolSetSpec`、`ToolRegistry`，并冻结了 `toolset.readonly`、`toolset.media_read`、`toolset.doc_read`、`toolset.doc_write`、`toolset.mindmap_read`、`toolset.mindmap_write`、`toolset.onlyoffice_service`、`toolset.slash_write` 等基础集合。
+- `rust/crates/bridge-runtime/src/lib.rs`
+  已提供统一 `RuntimeInput::{Tool, Query, Command}` 入口，支持 `plan`、`result`、`explain-plan`、`validateOnly`、`dryRun` 等运行模式，并输出统一计划结构。
+- `rust/crates/mnote-cli/README.md`
+  已冻结 `tool run` 的 JSON 契约，说明 CLI 化目标已经开始按稳定协议推进。
+- `wolai-frontend/src/lib/documents/rust-runtime.ts`
+  当前前端已经可以通过 `executeRustBridgeTool()` 直接调用 Rust `bridge-runtime`，说明 Web 并不是从零开始接 Rust。
+
+结合 `ai-tool-cutover-matrix.md` 与 `run/route.ts`，当前可以按下面口径理解能力归属：
+
+- 已有明确 Rust owner 或 Rust 主入口的能力：
+  `search_web`、`image_read`、`slash_run`、`doc_*`、`mindmap_*`、`onlyoffice_* service`
+- 仍暂时保留在 TS transport 或兼容层的能力：
+  `docs_search`、`docs_read`、`rag_lightrag_query`、`asset_extract_outline`、`asset_to_mindmap`、`oo_*`
+
+因此，这份方案后续提到的“后移”应理解成：
+
+- 先把前端收口到 Hermes bridge
+- 再把 mnote 业务能力通过 Rust 边界继续收口，并作为 Hermes 可调用能力暴露
+- 最终形成“Hermes 负责 agent runtime，Rust 负责 mnote 业务真执行面，前端只负责 UI 与 client bridge”的结构
+
+## 1.2 推荐的最终分工
+
+基于当前仓库和 Hermes 官方能力，推荐的长期结构不是单中心，而是双层分工：
+
+### A. Hermes 负责什么
+
+- agent loop
+- 通用 tool runtime
+- 多轮会话状态
+- OpenAI 兼容 API Server
+- 流式输出与工具调用事件
+- 通用记忆、skills、MCP、delegate 等 agent 能力
+
+### B. mnote Rust 负责什么
+
+- 文档、块、导图、OnlyOffice 等产品业务真执行
+- 统一 command/query/tool protocol
+- 审计、trace、request/command/event 口径
+- CLI 化与稳定 JSON 契约
+
+### C. mnote Web 前端负责什么
+
+- 输入框、聊天记录、SSE 展示
+- document/mindmap/onlyoffice context 采集
+- 少量浏览器专属 client tool
+- 必要的鉴权、会话映射和 client-tool-result 回传
+
+### D. mnote 与 Hermes 的推荐衔接方式
+
+当前更合理的方向不是让前端直接承接 Hermes 的全部能力，而是：
+
+- 前端 -> mnote Next route
+- mnote Next route -> Hermes API Server
+- Hermes 在需要 mnote 业务操作时，再调用 mnote 暴露给它的 Rust 能力面
+
+这层“mnote 暴露给 Hermes 的能力面”后续可以落在：
+
+- MCP server
+- Hermes plugin/tool adapter
+- 或 mnote 自己维护的一层最小业务 bridge
+
+但无论具体接法选哪一种，原则都应一致：
+
+> **Hermes 不应复制一套 mnote 业务真逻辑；mnote Rust 才是产品业务真执行面。**
+
+## 1.3 Hermes API Server 调用 mnote Rust 的最小业务桥
+
+这部分是 task-058 的关键边界：先把“谁调用谁、调用什么、返回什么”说清楚，再决定后续是否补更重的适配层。
+
+### 最小结论
+
+Hermes API Server 不应直接接触前端 `/api/ai-agent/run` 的整套 TS 编排逻辑，而应通过一个非常窄的 mnote Rust 业务桥来调用真实能力。
+
+这个桥只做三件事：
+
+1. 接收 Hermes 的标准化 tool 调用请求
+2. 转换成 mnote Rust 的 `RuntimeInput`
+3. 返回 Rust 的 `plan` 或 `result`
+
+### 推荐的桥接层级
+
+- Hermes API Server
+  负责 agent loop、tool 调度、流式输出与会话状态。
+- mnote Rust bridge
+  负责把 Hermes 的 tool 调用映射到 `core-protocol` / `bridge-runtime`。
+- mnote 业务执行面
+  负责文档、块、导图、OnlyOffice 等产品能力的真实读写。
+
+### 最小接口边界
+
+建议把 Hermes 可调用的 mnote 能力，先收敛成下面三类：
+
+- `query`
+  只读查询，例如 `page get`、`docs_search`、`docs_read`
+- `command`
+  写入命令，例如 `block insert`
+- `tool`
+  复用 Rust tool registry 的能力，例如 `doc_insert_blocks`、`doc_replace_range`
+
+其中最优先的两条业务能力是：
+
+- `page get` -> Rust query：`documents.content.get`
+- `block insert` -> Rust write/tool：`doc_insert_blocks`
+
+### 当前仓库里已经存在的可复用接缝
+
+- `rust/crates/core-protocol/src/tool.rs`
+  已经冻结了 `ToolSpec`、`ToolSetSpec`、`ToolRegistry`，并且 `docs_search`、`docs_read`、`doc_insert_blocks` 都已经在工具注册表中。
+- `rust/crates/bridge-runtime/src/lib.rs`
+  已经提供 `execute_runtime_input()`、`execute_runtime_query()`、`execute_query()`、`execute_command()`、`execute_tool_plan()`、`execute_tool_result()` 这些统一入口。
+- `rust/crates/core-protocol/src/query.rs`
+  已经有 `GetPageContent`、`SearchDocuments`、`GetBlock` 等查询载体。
+- `rust/crates/core-protocol/src/command.rs`
+  已经有 `CommandEnvelope` 和 `CommandResult`，说明命令执行结果口径是存在的。
+- `wolai-frontend/src/lib/documents/rust-runtime.ts`
+  当前前端已经能把 JSON 输入交给 Rust bridge 进程，说明“进程级 Rust bridge”这条路是可复用的。
+
+### 最小业务桥的推荐形态
+
+建议 Hermes 侧只认识一个很窄的桥协议，避免再次长成一套前端平台层：
+
+```text
+Hermes tool call
+  -> mnote rust bridge input
+  -> Rust plan/result
+  -> Hermes tool result
+```
+
+其中输入字段建议至少包含：
+
+- `toolName`
+- `invocationKind`
+- `executionMode`
+- `args`
+- `workspaceId`
+- `target`
+- `actor`
+- `source`
+
+输出字段建议至少包含：
+
+- `ok`
+- `kind`
+- `plan` 或 `result`
+- `error`（失败时）
+
+### 最小桥的落地原则
+
+- 先支持只读桥接，再补写入桥接
+- 先接 `page get`，再接 `block insert`
+- 先复用现有 `bridge-runtime`，不要先重写新执行器
+- 不要让 Hermes 直接依赖前端 `run/route.ts` 的 builtin registry
+- 不要把能力定义重新散落到多个前端面板里
+
+### 对当前前端的影响
+
+前端后续只应保留：
+
+- 场景上下文采集
+- SSE/UI 展示
+- 少量浏览器专属 client tool
+
+前端不应继续承担：
+
+- tool registry
+- tool policy
+- builtin 装配
+- provider 编排
+- Rust 能力路由
+
+这意味着后续如果要继续减重，应该优先把 `Hermes API Server -> mnote Rust bridge` 这条线做清楚，而不是继续在 Web 里扩充 AI 平台逻辑。
+
+---
+
+## 2. 当前问题
+
+## 2.1 当前不是一个 AI 面板，而是多套前端 AI 系统
+
+当前仓库至少存在下面几套 AI UI：
+
+- 全局 AI：`src/components/ai-agent/AiAgentPanel.tsx`
+- 全局 Host：`src/components/ai-agent/GlobalAiAgentHost.tsx`
+- 页面 AI：`src/components/editor/DocumentAiAgentPanel.tsx`
+- Mindmap AI：`src/components/editor/blocks/MindmapAiAgentPanel.tsx`
+- OnlyOffice AI：`src/components/onlyoffice/OnlyOfficeAiAgentPanel.tsx`
+
+这些面板不只是视觉上重复，而是每一套都各自持有一大批前端状态和交互逻辑，例如：
+
+- 对话 session/history
+- SSE 解析
+- tool logs
+- provider/model 选择
+- localStorage 持久化
+- 工具白名单/手动选择
+- codex mode
+- 中止/恢复交互
+
+这会持续拉高：
+
+- 前端代码体积
+- 客户端状态复杂度
+- 维护成本
+- 页面加载后的水合成本
+
+## 2.2 `/api/ai-agent/run` 当前仍是前端侧 AI 编排中心
+
+当前 `src/app/api/ai-agent/run/route.ts` 仍承担了大量本应属于统一后端 AI 服务的职责：
+
+- scope -> toolset 映射
+- builtin registry 构建
+- allowed tools 解析
+- 各类 server tools 装配
+- codex 与本地/在线 provider 多分支逻辑
+- client tool bridge 协调
+- 一部分 Rust tool 执行接线
+- 一部分 TS builtin fallback
+
+这意味着：
+
+- 前端 Next route 仍然是 AI 平台层
+- AI 执行面没有完全后移
+- AI 相关复杂度还在 Web 进程里增长
+
+## 2.3 builtin tool registry 仍保留为前端框架资产
+
+当前仍保留：
+
+- `src/lib/ai-agent/tools/registry.ts`
+- `src/lib/ai-agent/tools/builtins/registryBuiltins.ts`
+- `src/lib/ai-agent/runtime/runAgent.ts`
+- 多个 `create*ServerTools`
+
+这说明：
+
+- 前端不只是“调 AI”
+- 前端还在“定义 AI 能干什么、怎么调、怎么路由”
+
+这与“前端只桥接 Hermes + mnote Rust”的方向相冲突。
+
+## 2.4 当前 AI 能力边界仍分散在多个场景面板里
+
+例如：
+
+- 页面 AI 直接持有 `doc_*` 工具集合与文档快照
+- Mindmap AI 直接持有 mindmap tool 集与附件选择
+- OnlyOffice AI 直接持有 `oo_*` client tool 协议
+- 全局 AI 又有自己的 toolset chips 和 capability 展示
+
+这意味着“场景上下文”与“工具编排”没有分离。
+
+更合理的结构应该是：
+
+- 场景只提供 context
+- agent 编排由 Hermes 决定
+- mnote 业务执行由 Rust 决定
+- 前端只负责 UI 与极少数 client capability
+
+---
+
+## 3. 精简总原则
+
+## 3.1 前端 AI 只保留三类职责
+
+后续前端 AI 只应保留：
+
+### A. 轻 UI
+
+- 输入框
+- 聊天记录
+- 流式输出
+- 打断/继续
+- 极少量面板开关
+
+### B. 场景上下文采集
+
+- 当前 documentId
+- 当前 mindmapId
+- 当前 onlyoffice 文件信息
+- 当前 selection/block snapshot
+
+### C. 浏览器专属 client tool
+
+例如：
+
+- OnlyOffice 插件回调
+- 浏览器本地文件/剪贴板
+- 未来确实只能在浏览器执行的少数能力
+
+除此之外，前端不应继续承担：
+
+- tool registry
+- tool policy
+- builtin 分类
+- tool routing
+- AI orchestration
+- 多 provider 执行框架
+
+## 3.2 AI 面板本身不再按功能域复制实现
+
+最终应从“多个重面板”收口到：
+
+- 一个通用 `AiBridgePanel`
+- 多个轻量 context adapter
+
+即：
+
+- `GlobalAiEntry`
+- `DocumentAiEntry`
+- `MindmapAiEntry`
+- `OnlyOfficeAiEntry`
+
+这些 entry 只负责传不同 context，不再复制整套面板逻辑。
+
+## 3.3 前端不再维护 AI 工具产品说明体系
+
+像下面这些内容，不应再长期保留在前端：
+
+- tool labels
+- tool chips
+- capability 展示矩阵
+- per-scope tool lists
+
+这些都属于后端 AI 能力描述的一部分，应由 Hermes 返回，或由 mnote 后端统一下发，而不是继续硬编码在前端。
+
+---
+
+## 4. 建议的精简方案
+
+## Phase A：后移 AI 编排层到 Hermes，并给 mnote Rust 留清晰业务边界
+
+第一步不是删 UI，而是把重逻辑后移。
+
+### 需要后移的内容
+
+- `createToolRegistry`
+- `resolveAllowedToolIds`
+- `builtinTools`
+- `builtinToolSets`
+- `runAiAgent`
+- 各类 `create*ServerTools`
+- scope -> toolset 的静态映射逻辑
+
+### 目标结构
+
+前端 `/api/ai-agent/run` 只保留：
+
+- 鉴权
+- 规范化 `scope/messages/context/attachments/clientCapabilities`
+- 把请求转发给 Hermes API Server
+- 把 Hermes 的 SSE / `tool_call` / `tool_result` 回流给前端面板
+- 转发 client tool call/result
+- 在 Hermes 需要调用 mnote 业务能力时，转给 mnote Rust 暴露出来的业务能力面
+- 对少数短期无法迁走的 `TS_TRANSPORT_KEEP` 能力保留最小兼容壳
+
+换句话说：
+
+> `/api/ai-agent/run` 从“AI 编排器”降级为“AI 网关”。`
+
+### 收益
+
+- 显著降低 Next route 的 AI 编排复杂度
+- agent runtime 与 mnote 业务执行面彻底分层
+- 前端后续不必再继续长 builtins、registry 和 provider 编排
+- 后续若继续 CLI 化，也能直接复用 Hermes API Server 与 mnote Rust 协议边界
+
+### Phase A 的现实限制
+
+这一阶段不能简单理解为“删除所有 TS builtins 就结束”。
+
+因为当前还有两类事情没有完全打通：
+
+- Hermes API Server 还没在本机正式启用并接入 mnote
+- mnote Rust 业务能力还没全部以 Hermes 可调用的方式暴露
+
+所以 Phase A 的实际目标应是：
+
+- 先让 `/api/ai-agent/run` 从“自己编排”变成“转发 + 桥接”
+- 再逐步清理遗留 builtin
+- 不是一刀切直接删除所有中间层
+
+## Phase B：统一 AI 面板实现
+
+在后移编排层之后，再收 UI。
+
+### 当前问题
+
+四套 AI 面板都在重复维护：
+
+- 对话
+- 工具日志
+- provider/model
+- localStorage
+- 中断/恢复
+
+### 目标结构
+
+新增统一通用面板，例如：
+
+- `AiBridgePanel`
+
+再由不同场景只提供轻量包装：
+
+- `DocumentAiEntry`
+- `MindmapAiEntry`
+- `OnlyOfficeAiEntry`
+- `GlobalAiEntry`
+
+这些 entry 只负责：
+
+- 是否显示
+- 传入 context
+- 传入 clientCapabilities
+- 传入 UI 文案
+
+### 收益
+
+- 删除四套重复状态机
+- 降低包体与维护成本
+- 后续新场景不再复制面板
+
+## Phase C：弱化或下线全局 AI
+
+当前全局 AI 被直接挂在：
+
+- `src/app/(app)/layout.tsx`
+
+它带来的问题不是“首屏一定特别重”，而是：
+
+- 全局产品心智更复杂
+- 持续占用一套入口与状态
+- 会诱导继续扩展“全局工具平台”
+
+建议策略：
+
+- 第一阶段：保留代码，但默认隐藏/弱化入口
+- 第二阶段：若页面 AI 已覆盖主场景，则把全局 AI 下线为开发页或实验开关
+
+### 为什么优先保页面 AI 而不是全局 AI
+
+因为页面 AI 更接近核心使用场景：
+
+- 对页面正文直接读写
+- 与编辑器桥接紧密
+- 用户心智最清晰
+
+全局 AI 更像附加层，不值得优先保留完整前端壳。
+
+## Phase D：明确保留的少数浏览器专属能力
+
+有一些能力确实不能完全后移，应明确留在前端：
+
+- `oo_*` 这类 OnlyOffice 客户端工具
+- `/api/ai-agent/client-tool-result`
+- 少数必须读浏览器本地态的能力
+
+这些能力的处理原则是：
+
+- 保留
+- 但只能作为 `client capability bridge`
+- 不得重新长成新的前端 AI 平台层
+
+---
+
+## 5. 推荐优先级
+
+如果只按收益排序，我建议这样做：
+
+### P0：先做
+
+- 启用并验证 Hermes API Server
+- 把 `/api/ai-agent/run` 收口成 Hermes bridge
+- 冻结前端新增 builtin tool / toolset / provider 编排逻辑
+- 明确 mnote Rust 能力如何暴露给 Hermes 调用
+
+### P1：接着做
+
+- 把多套 AI 面板收口为一个通用 `AiBridgePanel`
+- 页面 / Mindmap / OnlyOffice 改成 context adapter
+
+### P2：再做
+
+- 弱化或隐藏全局 AI Host
+- 让全局 AI 退到实验入口或开发入口
+
+### P3：最后做
+
+- 清理旧的 builtins、registry、重复 localStorage/session 管理
+- 删除历史兼容面板实现
+
+---
+
+## 6. 除 AI 之外，还有哪些可以精简
+
+这部分先只记录，不进入当前 harness 任务。
+
+## 6.1 文档页加载链可以继续减重
+
+当前文档页存在：
+
+- `DocumentShell` 的 `mounted + dynamic + ssr:false`
+- `DocumentContent` 再 `dynamic` 到 `BlockNoteEditor`
+- `meta` 与 `content` 的两阶段加载
+
+这些都可能造成刷新时的“空一下再出现”的体感。
+
+建议后续单独评估：
+
+- 去掉 `DocumentShell` 这层多余壳
+- 减少文档页串行加载层级
+- 优先把首屏必需数据前移
+
+## 6.2 SearchPalette 目前是全局常驻挂载
+
+当前：
+
+- `SearchPalette` 直接挂在 `app/(app)/layout.tsx`
+
+如果它本身比较重，后续可考虑：
+
+- 改为按需挂载
+- 或在首次打开时再加载
+
+## 6.3 Sidebar 职责仍然非常重
+
+`Sidebar` 当前承担了太多：
+
+- 页面树
+- 文件树
+- 资产操作
+- 拖拽复制
+- 删除恢复
+- 批处理
+- mindmap/table/media 入口
+
+这会让 Sidebar 成为高复杂度常驻组件。
+
+后续可以考虑：
+
+- 按功能拆分
+- 降低初始挂载职责
+- 把非首屏必要的动作延后
+
+## 6.4 文档页周边抽屉与面板可以按需加载
+
+当前文档页同时带着：
+
+- `PageOptionsSidebar`
+- `PageBacklinksPanel`
+- `DocumentHistoryDrawer`
+- `DocumentCommentsDrawer`
+- `DocumentAiAgentPanel`
+
+后续可评估哪些可以从“默认挂载”改成“首次打开再加载”。
+
+---
+
+## 7. 最终建议
+
+如果你的目标是：
+
+> **先精简能精简的东西来改善网页前端加载与复杂度**
+
+那么最值得优先推进的不是重写 Web，也不是先重做编辑器，而是：
+
+> **把前端 AI 从“平台层”收缩成“Hermes + mnote Rust 的桥接层”。**
+
+一句话版结论：
+
+- **该砍的不是 AI 按钮本身，而是前端 AI 编排框架。**
+- **该保留的是轻面板、Hermes bridge、mnote Rust 业务执行面和浏览器专属 client bridge。**
+- **全局 AI 可以弱化，页面 AI 保留为主入口。**
+- **除 AI 外，文档页加载链、全局 SearchPalette、巨型 Sidebar 也是后续值得继续精简的方向，但先不进入当前 harness。**