lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96e03645f784cebc7b898ae17cb66abc756f2053
mnote/design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md
T
lix-2026 96e03645f7 chore: 收口 review 执行清单与 runtime 验证 
- 补齐 design/10-review 执行清单、验收标准与相关设计治理记录

- 迁移已完成的 tree、mindmap、runtime fallback、AI kernel 等设计和缺陷条目

- 推进 Rust Web runtime、tree/sidebar、page aggregate、mindmap 与 OnlyOffice 路由侧验证支撑

- 增加 task177-task180 smoke/audit 脚本及前端相关测试覆盖
2026-05-14 05:52:08 +08:00

12 KiB
Raw Blame History

7-3 [process] 页面 AI Hermes 面板与 mnote Plugin 主线方案 v1

更新时间：2026-05-13

上位依据：

  • /mnt/Data1T/mnote/ARCHITECTURE.md
  • /mnt/Data1T/mnote/design/01-05-current-priority-overview.md
  • /mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md
  • /mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md
  • /mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md
  • /mnt/Data1T/mnote/design/05-editor-mainline/done/5-10-wolai-page-settings-and-ai-surface-alignment-v1.md
  • /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/hermes-web-ui-0.5.18
  • /mnt/Data1T/mnote/design/07-ai/process/7-2-phase7-structured-artifact-write-chain-v1.md

覆盖关系：

  • 覆盖 /mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md 中“mnote-cli 是唯一长期 agent 执行面”的口径。
  • 保留 v4 中“Web 不应拥有第二套工具注册表、结构化写入必须回到 Rust runtime / kernel”的判断。
  • 保留 7-2 中 summary node / ai_note node / reference edge 的对象模型和写入边界， 但触发方改为 Hermes tool call，而不是页面 AI host 私有按钮或 mnote-cli host。

1. 文档目的

这份稿只回答一个问题：

未来页面 AI 的长期主语到底是谁。

当前冻结答案是：

页面 AI 面板只是 Hermes 的页面内客户端；Hermes session/message/tool event/usage/model 才是会话真相；mnote 通过 Hermes skill/plugin 暴露业务能力。

这不是把 mnote 的业务真相交给 Hermes。长期边界必须分清：

  • Hermes 负责 AI 编排、会话、模型、tool call 调度和聊天历史。
  • mnote 负责页面、树、正文、artifact、edge、projection 和审计事实。
  • 页面 AI 面板只负责在文档页里打开一个 Hermes 客户端。

一句话收口：

AI 会话归 Hermes，mnote 能力归 Rust kernel；页面 AI 面板只连接两者。

2. 为什么要从 CLI-first 改为 Hermes-first

CLI-first 解决了一个真实问题：避免 Web 前端继续拥有私有 AI 编排、私有工具注册表和私有写链。

但它也带来了新的错位：

  • 页面 AI 面板开始伪装成 mnote-cli 图形客户端。
  • Hermes、Codex、openai-agents-python 被统一压成“外置 agent”，但实际用户希望页面 AI 就是 Hermes 面板。
  • 真实会话能力、模型选择、tool event、thinking、usage、历史搜索这些已经是 Hermes 的强项，mnote 自己再做一套会重复。
  • 当前运行态已经出现冲突：页面壳默认发送 provider=hermes，而 /api/ai-agent/run 又按旧退场口径返回 ai_provider_bridge_unavailable。

因此新的主线不是恢复旧的 Web 私有 AI 编排，而是：

把页面 AI 从 mnote-cli host 改成 Hermes client，把 mnote 能力从 Web 私有 tool 改成 Hermes 可发现、可调用的 skill/plugin。

3. 长期分层

3.1 Hermes

Hermes 负责：

  • session 创建、恢复、重命名、删除、搜索
  • message 存储与 conversation history
  • model / provider / profile 选择
  • streaming 事件、thinking / reasoning、usage
  • tool call 调度、排队、取消、恢复
  • skill / plugin 的发现和启停

Hermes 不负责：

  • 直接写 mnote 的 Convex 表
  • 直接构造第二套 page aggregate
  • 直接决定页面树、文件树、artifact、edge 的事实结构

3.2 mnote Rust kernel / runtime

mnote Rust 负责：

  • Page Aggregate
  • page.* command
  • tree.* command
  • kernel.* query / edge
  • summary node / ai_note node / reference edge
  • projection、audit、idempotency、workspace / actor scope

Rust 不负责：

  • 存储 Hermes 聊天历史
  • 维护 Hermes session 列表
  • 重做 Hermes 模型、profile、usage 管理

3.3 页面 AI Leptos 面板

页面 AI 面板负责：

  • 右下角入口与右侧抽屉壳层继续服从 Wolai 对齐结果
  • 用 Leptos 实现 Hermes chat 的页面内子集
  • 调用 Hermes session / run / stream API
  • 把当前页面上下文作为 Hermes run 的输入或 session workspace context
  • 展示 Hermes 返回的 message、reasoning、tool event、error、usage

页面 AI 面板不负责：

  • 自己保存聊天真相
  • 自己维护工具注册表
  • 自己执行页面写入
  • 自己 fallback 到 mnote-cli 或旧 sidecar

3.4 mnote Hermes skill/plugin

mnote 需要作为 Hermes skill/plugin 暴露能力。

第一版建议能力分组：

  • mnote.page.get
  • mnote.page.save
  • mnote.page.update_title
  • mnote.page.update_options
  • mnote.tree.create
  • mnote.tree.move
  • mnote.search.documents
  • mnote.artifact.create_summary
  • mnote.artifact.create_ai_note
  • mnote.kernel.attach_reference

这些工具可以由 plugin 内部调用：

  • Rust Web 同源 tool bridge
  • mnote-cli JSON adapter
  • 或后续更稳定的 Rust plugin bridge

但对 Hermes 来说，它们必须表现为一组稳定 Hermes tools，而不是页面前端私有函数。

4. 会话真相

页面 AI 的会话真相固定在 Hermes。

mnote 不保存：

  • 聊天消息列表
  • assistant 文本历史
  • thinking / reasoning 历史
  • tool event 完整展开状态
  • session 标题、分组、usage

mnote 可以保存：

  • 结构化写入产生的 audit
  • artifact node
  • reference edge
  • page/body/title/options 的正式变更
  • 与一次 Hermes tool call 对应的 request / trace / actor / reason

也就是说，mnote 只保存“对 mnote 事实源造成影响的结果”，不复制 Hermes 的聊天数据库。

5. 页面上下文进入 Hermes 的方式

页面 AI 面板打开时，mnote 应提供最小上下文包：

  • workspaceId
  • documentId
  • 页面标题
  • pageAggregate 摘要
  • 当前选区 / blockId / selected text
  • 页面设置
  • 当前用户 actor / capability 摘要

上下文传入 Hermes 有两种可接受方式：

  1. 作为 run input / instructions 的结构化上下文。
  2. 作为 Hermes session workspace context，由 mnote panel 在创建或恢复 session 时设置。

第一版优先采用简单方式：

页面 AI 面板每次发起 run 时附带当前页面上下文摘要；Hermes 如需读取最新正文，再通过 mnote.page.get 工具回读。

这样可以避免把 page aggregate 大对象长期塞进 Hermes session，也避免 stale context 变成事实源。

6. API 与路由边界

6.1 退役 /api/ai-agent/run 主路径

/api/ai-agent/run 不再作为页面 AI 的长期主入口。

允许状态：

  • 暂时保留为 legacy compat，明确返回旧接口退场信息
  • 或只用于旧 smoke / 对照验证

禁止状态：

  • 页面 AI 新实现继续向它发送 provider=hermes
  • /api/ai-agent/run 继续作为 Hermes 面板的主代理
  • 它继续持有 mnote 私有工具注册表或执行编排

6.2 新增 Hermes client proxy

浏览器不应直接暴露 Hermes API key。

建议在 mnote-web 中提供同源薄代理：

  • /api/hermes/client/sessions
  • /api/hermes/client/runs
  • /api/hermes/client/events
  • /api/hermes/client/models
  • /api/hermes/client/tools

这层只做：

  • auth / cookie / token 转发
  • 同源安全边界
  • 页面上下文最小注入
  • 错误码标准化

这层不做：

  • session 真相存储
  • message 真相存储
  • tool 执行编排
  • 旧 provider fallback

6.3 mnote tool bridge

Hermes 调用 mnote 工具时，应进入窄桥：

Hermes tool call
  -> mnote Hermes plugin
  -> mnote-web /api/hermes/tools/mnote/*
  -> Rust runtime / kernel command/query
  -> Hermes tool result

第一版不要求一次性冻结最终 URL，但要求协议字段稳定：

  • toolName
  • arguments
  • workspaceId
  • documentId
  • actor
  • sessionId
  • traceId
  • idempotencyKey
  • dryRun
  • capabilityScope

7. Leptos 面板参考范围

参考 hermes-web-ui-0.5.18，但只采用页面内必要子集。

第一版采用：

  • Chat session list
  • Message list
  • Chat input
  • streaming delta
  • thinking / reasoning 展开
  • tool started / tool completed 展开
  • model selector
  • error / retry / abort
  • session search 可后置

第一版不采用：

  • 平台 Channels 管理
  • Jobs / Cron 管理
  • Profiles 管理全页面
  • Logs 全页面
  • Files 全浏览器
  • Terminal
  • Group Chat
  • Hermes 全局 Settings

这些能力属于 Hermes 管理台，不属于 mnote 页面 AI 抽屉。

实现要求：

  • 使用 Leptos island 实现，不引入 Vue / Naive UI。
  • 保留 Wolai 对齐的右下角入口和右侧 drawer 容器。
  • 文案和视觉以 mnote 文档页密度为准，不照搬 Hermes Web UI 的整站导航。

8. 结构化 Artifact 写链

7-2 的对象模型继续成立：

  • summary node
  • ai_note node
  • reference edge
  • AI Artifacts projection-only 分组

但触发方改为 Hermes tool call：

  • 用户可以在 Hermes 面板中自然语言要求总结当前页。
  • Hermes 决定调用 mnote.artifact.create_summary。
  • 或页面面板提供快捷按钮，但按钮本质也是向 Hermes 发送意图，不是绕过 Hermes 直接写 mnote。

第一版允许两个快捷入口：

  • 创建 Summary
  • 创建 AI Note

但它们必须走：

Leptos panel -> Hermes session/run -> mnote plugin tool call -> Rust kernel

不得走：

Leptos panel -> /api/documents/* 直接写 artifact

9. 权限与安全

Hermes 可以调度工具，但 mnote 必须做最终授权。

每个 mnote tool call 至少校验：

  • 当前 actor 是否登录
  • actor 是否属于 workspace
  • 当前页面是否允许 AI 读取
  • 当前页面是否允许 AI 写入
  • 当前工具是否允许写入页面 / 树 / artifact
  • 是否需要 dryRun 或确认

默认第一版：

  • 读当前页：允许
  • 写当前页：按页面 capability
  • 创建 summary / ai_note：按当前页 artifact capability
  • 跨页写入：默认禁止
  • 跨 workspace：禁止

10. 迁移步骤

Phase A：设计口径统一

  • 新增本稿作为 07-ai 当前主线。
  • 将 7-v4 CLI-first 移入 design/old/07-ai/process/ 并标记 [recycle]。
  • 更新仍引用 mnote-cli 唯一长期 agent 执行面的活跃设计稿。

Phase B：薄 Hermes client proxy

  • 在 mnote-web 补 Hermes client proxy。
  • 页面 AI 面板不再调用 /api/ai-agent/run。
  • 浏览器不直接持有 Hermes API key。

Phase C：Leptos Hermes 面板最小子集

  • 实现 session 创建 / 恢复。
  • 实现 run / stream / abort。
  • 实现 message / reasoning / tool event 展示。
  • 保留 Wolai 右侧抽屉壳。

Phase D：mnote Hermes plugin

  • 暴露 mnote tool manifest。
  • 先接 mnote.page.get、mnote.page.save、mnote.artifact.create_summary、mnote.artifact.create_ai_note。
  • 工具结果回到 Hermes tool event。

Phase E：退役旧面板执行链

  • /api/ai-agent/run 从主路径移除。
  • 旧 React DocumentAiAgentPanel.runtime 降为历史参考或 compat。
  • provider=hermes/codex/claudecode 502 不再出现在新页面 AI 主链。

11. 验收标准

第一版完成时必须满足：

  • 页面 AI 抽屉打开后可创建或恢复 Hermes session。
  • Hermes session 存储中能看到页面 AI 的消息历史。
  • mnote 本地不复制聊天消息真相。
  • 发送消息后，事件流来自 Hermes run。
  • tool call 展示使用 Hermes tool event。
  • Hermes 可调用至少一个只读 mnote 工具读取当前页面。
  • Hermes 可调用至少一个写入工具，经 Rust runtime 写回当前页或创建 artifact。
  • 页面刷新后，AI 会话从 Hermes 恢复，而不是从 mnote 本地 state 恢复。
  • 结构化写入产生的 artifact / edge 能在 mnote projection 中验证。

12. 禁止项

  • 不再新增 Web 私有 AI tool registry。
  • 不再把 mnote-cli 写成页面 AI 唯一长期执行面。
  • 不把 Hermes 聊天历史复制进 mnote page aggregate。
  • 不让 Hermes plugin 直接写 Convex。
  • 不在 Leptos 面板里重做 Hermes 后台管理台。
  • 不把 AI Artifacts 做成真实 kernel node。
  • 不绕过 Rust runtime 创建 artifact / edge。

13. 最终冻结口径

页面 AI 是 Hermes 面板，不是 mnote-cli 面板。

Hermes 持有 AI 会话真相，mnote 持有业务对象真相。

mnote 通过 Hermes skill/plugin 暴露工具，工具最终回到 Rust runtime / kernel。

Leptos 负责页面内 Hermes 客户端体验，不负责 AI 编排。

Reference in New Issue View Git Blame Copy Permalink