lix/mnote

Files

T

lix-2026 afb2a5b8a0 对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00

18 KiB

Raw Blame History

[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 业务桥来调用真实能力。

这个桥只做三件事：

接收 Hermes 的标准化 tool 调用请求
转换成 mnote Rust 的 RuntimeInput
返回 Rust 的 plan 或 result

最小接口边界

建议把 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 侧只认识一个很窄的桥协议，避免再次长成一套前端平台层：

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。

18 KiB Raw Blame History Unescape Escape

[recycle] AI 前端精简方案 v1

1. 目标

1.1 现状校准：当前真正已经落地的后端 AI 边界

1.2 推荐的最终分工

A. Hermes 负责什么

B. mnote Rust 负责什么

C. mnote Web 前端负责什么

D. mnote 与 Hermes 的推荐衔接方式

1.3 Hermes API Server 调用 mnote Rust 的最小业务桥

最小结论

推荐的桥接层级

最小接口边界

当前仓库里已经存在的可复用接缝

最小业务桥的推荐形态

最小桥的落地原则

对当前前端的影响

2. 当前问题

2.1 当前不是一个 AI 面板，而是多套前端 AI 系统

2.2 /api/ai-agent/run 当前仍是前端侧 AI 编排中心

2.3 builtin tool registry 仍保留为前端框架资产

2.4 当前 AI 能力边界仍分散在多个场景面板里

3. 精简总原则

3.1 前端 AI 只保留三类职责

A. 轻 UI

B. 场景上下文采集

C. 浏览器专属 client tool

3.2 AI 面板本身不再按功能域复制实现

3.3 前端不再维护 AI 工具产品说明体系

4. 建议的精简方案

Phase A：后移 AI 编排层到 Hermes，并给 mnote Rust 留清晰业务边界

需要后移的内容

目标结构

收益

Phase A 的现实限制

Phase B：统一 AI 面板实现

当前问题

目标结构

收益

Phase C：弱化或下线全局 AI

为什么优先保页面 AI 而不是全局 AI

Phase D：明确保留的少数浏览器专属能力

5. 推荐优先级

P0：先做

P1：接着做

P2：再做

P3：最后做

6. 除 AI 之外，还有哪些可以精简

6.1 文档页加载链可以继续减重

6.2 SearchPalette 目前是全局常驻挂载

6.3 Sidebar 职责仍然非常重

6.4 文档页周边抽屉与面板可以按需加载

7. 最终建议

18 KiB

Raw Blame History

2.2 `/api/ai-agent/run` 当前仍是前端侧 AI 编排中心