Agent Board
b798f628ee
Persist PageTree expand state via control-plane view-state and align chevron/DOM with restored expansion; keep Sidex-style shallow page-tree scan and drop the unused recursive scanner that only added cargo noise. Add password vault workbench routes/runtime/skill/CLI, split page_ai_pi into a module package, and retire Hermes/ACP/OpenHub recycle + root harness evidence from the index while gitignoring recycle and local diag dumps. Archive superseded design/bugs docs under old/, point architecture at ARCHITECTURE.md, and refresh smokes for Pi S1–S7, vault, and editor regressions so the working tree can stay clean.
429 lines
12 KiB
Markdown
429 lines
12 KiB
Markdown
# [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 编排。**
|