mnote/design/old/08-legacy-rust-kernel/process/ai-frontend-simplification-plan-v1.md

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