mnote/design/old/07-ai/done/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md

# [recycle] 7-3 [done] 页面 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/reference/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/done/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/done/7-2-phase7-structured-artifact-write-chain-v1.md`
> - `/mnt/Data1T/mnote/design/07-ai/done/7-4-page-ai-hermes-panel-execution-checklist-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 工具时，应进入窄桥：

```text
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`

但它们必须走：

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

不得走：

```text
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 编排。**