278 lines
17 KiB
Markdown
278 lines
17 KiB
Markdown
# 7-7 [process] 页面 AI Mini Hermes 控制面设计与执行 checklist v1
|
||
|
||
> 更新时间：2026-05-14
|
||
>
|
||
> 当前状态：`PROCESS`。当前实现已经可以通过 Hermes 返回回复，并已完成 `7-4` 的 session/run/tool/writeback/audit 主链；本稿只承接下一阶段体验与设置面的收口。
|
||
>
|
||
> 上位依据：
|
||
> - `/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/reference-code/hermes-web-ui-0.5.18`
|
||
> - `/mnt/Data1T/mnote/design/07-ai/done/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md`
|
||
> - `/mnt/Data1T/mnote/design/07-ai/done/7-4-page-ai-hermes-panel-execution-checklist-v1.md`
|
||
> - `/mnt/Data1T/mnote/design/07-ai/done/7-5-hermes-client-proxy-contract-v1.md`
|
||
> - `/mnt/Data1T/mnote/design/07-ai/done/7-6-mnote-hermes-plugin-tool-contract-v1.md`
|
||
|
||
---
|
||
|
||
## 1. 方向判断
|
||
|
||
当前截图和实现状态说明：页面 AI 已经能回复，但它还更像“能发消息的 Hermes run 面板”，缺少用户自然期待的 Hermes 运行态控制与设置入口。
|
||
|
||
下一阶段不要把 mnote 做成第二个 Hermes 管理台，也不要把 Hermes 的 Settings / Profiles / Usage / Logs 全部搬进页面抽屉。正确方向是：
|
||
|
||
> **页面 AI 面板成为 Mini Hermes control surface：只展示和当前 mnote 页面会话直接相关的 session、run、model、profile、tool、context scope 与错误恢复；所有全局配置真相仍归 Hermes。**
|
||
|
||
边界继续保持：
|
||
|
||
- Hermes 持有 session/message/tool event/usage/model/profile 真相。
|
||
- mnote 只持有页面、树、正文、artifact、edge、Page Aggregate 和 audit 真相。
|
||
- 页面 AI 面板只调用 Hermes，不保存聊天历史，不维护 provider/API key，不重建 plugin registry。
|
||
- 需要深层设置时跳转或 deep link 到 Hermes 自己的设置页。
|
||
|
||
---
|
||
|
||
## 2. Hermes Web UI 参考索引
|
||
|
||
参考根目录固定为：
|
||
|
||
```text
|
||
/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/hermes-web-ui-0.5.18
|
||
```
|
||
|
||
只参考下表列出的具体位置。目标是复用 Hermes 的语义与行为边界，仍然用 Leptos 实现 mnote 页面内面板。
|
||
|
||
| mnote 下一步任务 | 参考文件 | 搜索点 / 具体位置 | 参考目的 | 不采用内容 |
|
||
| --- | --- | --- | --- | --- |
|
||
| run 发起、恢复和事件语义 | `packages/client/src/api/hermes/chat.ts` | `StartRunRequest`、`RunEvent`、`registerSessionHandlers`、`resumeSession`、`startRunViaSocket` | 对齐 run 创建、session room 恢复、事件类型和浏览器端分发语义 | 不直接复用 Vue/TS client，不让浏览器绕过 mnote-web proxy |
|
||
| 前端消息归并 | `packages/client/src/stores/hermes/chat.ts` | `mapHermesMessages`、`case 'tool.started'`、`case 'tool.completed'`、`refreshActiveSession`、`switchSession` | 对齐 message/tool event 在前端归并成消息列表的规则 | 不把归并结果保存到 mnote local/session storage 作为真相 |
|
||
| 面板分层 | `packages/client/src/components/hermes/chat/ChatPanel.vue` | `activeSessionTitle`、`showSessions`、`handleNewChat`、`MessageList`、`ChatInput`、`SessionListItem` | 对齐 session list / message list / input 的最小层次 | 不复制 Hermes 全屏布局、Vue 组件结构或 Naive UI |
|
||
| tool 消息展示 | `packages/client/src/components/hermes/chat/MessageItem.vue` | `message.role === 'tool'`、`formatToolPayload`、`tool-preview`、`tool-details`、`tool-error-badge` | 对齐 tool 结果默认折叠、摘要、错误 badge、详情展开 | 不把 tool result 当正文写入，不扩大为审计详情管理台 |
|
||
| session 列表项 | `packages/client/src/components/hermes/chat/SessionListItem.vue` | `session-item-title`、`session.title`、`session-item-model` | 对齐 session 标题、模型和时间的展示语义 | 不把 Hermes session title 同步为 mnote page title |
|
||
| model 选择展示 | `packages/client/src/components/layout/ModelSelector.vue` | `selectedDisplayName`、`handleSelect`、`model-name`、`model-item` | 对齐模型显示名称、选择行为和禁用态 | 不在 mnote 保存 model/provider/API key 真相 |
|
||
| run 生命周期与持久化 | `packages/server/src/services/hermes/chat-run-socket.ts` | `handleRun`、`emit`、`applyResponseStreamEvent`、`flushResponseRunToDb`、`markCompleted` | 对齐 queued/running/tool_calling/completed/failed 与 flush 到 Hermes DB 的时机 | 不在 mnote 里重写 Hermes 编排器 |
|
||
| session 存储真相 | `packages/server/src/db/hermes/session-store.ts` | `HermesSessionRow`、`HermesMessageRow`、`getSessionDetail`、`addMessage`、`renameSession` | 明确 session/message/tool call 真相字段来自 Hermes | 不在 mnote 建第二份 chat/session 表 |
|
||
| plugin/tool 发现 | `packages/server/src/services/hermes/plugins.ts` | `PluginManager`、`providesTools`、`listHermesPlugins`、`requiresEnv` | 对齐 mnote tools 作为 Hermes plugin/tool registry 的一部分被发现 | 不把 mnote-web 私有 route 当成最终 plugin registry |
|
||
| skill/plugin API 外观 | `packages/client/src/api/hermes/plugins.ts`、`packages/client/src/api/hermes/skills.ts` | `list`、`get`、`enable`、`disable` 类方法 | 仅用于面板显示 mnote plugin/tool 可用性和缺失状态 | 不实现完整 Hermes plugin/skill 管理页 |
|
||
| 不进入 mnote 面板第一阶段 | `packages/client/src/views/hermes/SettingsView.vue`、`ProfilesView.vue`、`UsageView.vue`、`LogsView.vue`、`JobsView.vue`、`FilesView.vue`、`ChannelsView.vue`、`TerminalView.vue`、`GroupChatView.vue` | 页面级管理视图入口 | 用来明确边界：这些属于 Hermes 管理台 | 不搬进 mnote 页面 AI 抽屉 |
|
||
|
||
快速定位命令：
|
||
|
||
```bash
|
||
cd /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/hermes-web-ui-0.5.18
|
||
rg -n "StartRunRequest|RunEvent|registerSessionHandlers|resumeSession|startRunViaSocket|mapHermesMessages|tool\\.started|tool\\.completed|activeSessionTitle|formatToolPayload|selectedDisplayName|handleRun|flushResponseRunToDb|PluginManager|providesTools" packages/client/src packages/server/src
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 产品边界
|
||
|
||
### 3.1 必须进入 mnote 页面 AI 面板
|
||
|
||
- 当前 Hermes session 标题、session id、模型名、profile 名和恢复状态。
|
||
- 当前 run 状态：`idle`、`queued`、`running`、`tool_calling`、`completed`、`failed`、`aborted`。
|
||
- 当前页面上下文范围：当前页、当前选区、当前块、全文、页面设置。
|
||
- 当前 mnote tools 可用性：`mnote.page.get`、`mnote.page.save`、`mnote.page.update_title`、`mnote.page.update_options`、`mnote.artifact.create_summary`、`mnote.artifact.create_ai_note`。
|
||
- 最近 tool call 摘要、参数摘要、结果摘要、失败原因和 trace/audit id。
|
||
- 停止、重试、继续、重新读取当前页上下文的最小操作。
|
||
- 跳转 Hermes 设置的入口，说明缺失项应在 Hermes 中配置。
|
||
|
||
### 3.2 不进入 mnote 页面 AI 面板
|
||
|
||
- provider/API key 密钥管理。
|
||
- 全局 profile 创建、删除、复杂编辑。
|
||
- Hermes plugin marketplace / skill marketplace 管理。
|
||
- usage 报表、日志中心、任务中心、文件中心、频道、终端、群聊。
|
||
- Hermes session 数据库迁移、导入导出、conversation 管理台。
|
||
- 独立 mnote 聊天历史存储。
|
||
|
||
### 3.3 可选但不阻塞第一阶段
|
||
|
||
- 当前页面最近 sessions 搜索。
|
||
- session 重命名与删除。
|
||
- profile/model 下拉切换。
|
||
- tool event JSON 详情复制。
|
||
- session deep link 到 Hermes 管理台。
|
||
|
||
---
|
||
|
||
## 4. 目标信息架构
|
||
|
||
页面 AI 抽屉保持 Wolai 对齐后的壳层，内部按四层组织：
|
||
|
||
1. 顶部状态条：session 标题、模型/profile、连接状态、设置跳转。
|
||
2. 消息区：Hermes message list、streaming 回复、tool event 折叠项。
|
||
3. 上下文与工具条：当前 context scope、可用 mnote tools、最近 audit/trace。
|
||
4. 输入区：prompt 输入、发送、停止、重试、继续。
|
||
|
||
验收时不要只看 DOM，应以截图和交互为准：
|
||
|
||
- 顶部状态在窄屏不挤压输入区。
|
||
- tool event 折叠项不会撑破抽屉宽度。
|
||
- 失败态能看到可执行动作，不只是一段错误文本。
|
||
- 设置入口不会暗示 mnote 自己持有 API key。
|
||
|
||
---
|
||
|
||
## 5. 数据与 API 边界
|
||
|
||
### 5.1 mnote-web proxy 需要补齐的读接口
|
||
|
||
- `GET /api/hermes/client/session/current?documentId=...`
|
||
- `GET /api/hermes/client/sessions?documentId=...&limit=...`
|
||
- `GET /api/hermes/client/session/:sessionId`
|
||
- `GET /api/hermes/client/models`
|
||
- `GET /api/hermes/client/tools?scope=mnote`
|
||
- `GET /api/hermes/client/runtime/status`
|
||
|
||
这些接口只透传或规整 Hermes 状态，不在 mnote 保存真相。
|
||
|
||
### 5.2 mnote-web proxy 需要补齐的操作接口
|
||
|
||
- `POST /api/hermes/client/run`
|
||
- `POST /api/hermes/client/run/:runId/stop`
|
||
- `POST /api/hermes/client/run/:runId/retry`
|
||
- `POST /api/hermes/client/session/:sessionId/resume`
|
||
- `POST /api/hermes/client/session/:sessionId/rename`
|
||
- `DELETE /api/hermes/client/session/:sessionId`
|
||
|
||
第一阶段可以只完成 `run/stop/resume`，`retry/rename/delete` 可以排到 P2，但 UI 文案不能让用户误以为已经支持。
|
||
|
||
### 5.3 mnote tool manifest
|
||
|
||
页面 AI 面板展示 tool 可用性时应优先从 Hermes plugin/tool registry 来，而不是硬编码前端列表。允许 mnote-web 在过渡期提供同源聚合：
|
||
|
||
- tool name
|
||
- description
|
||
- read/write 分类
|
||
- required scope
|
||
- permission 状态
|
||
- last call summary
|
||
- last audit id
|
||
- unavailable reason
|
||
|
||
---
|
||
|
||
## 6. 顺序执行 checklist
|
||
|
||
### A. 设计与现状审计
|
||
|
||
- [ ] A1. 打开当前 `3000` 页面 AI 抽屉，记录“能回复但缺设置/运行态控制”的截图到 `tmp/`。
|
||
- 验收标准：截图能看到回复链路、顶部或设置区域缺失点、当前 session/run 状态展示缺口。
|
||
- [ ] A2. 用 `rg` 确认活跃设计稿中页面 AI 主线已经指向 Hermes session/run/events。
|
||
- 验收标准：`design/07-ai/process` 只剩本 `7-7` 作为 AI 活跃稿；`7-2` 到 `7-6` 位于 `done/`。
|
||
- [ ] A3. 对照 Hermes Web UI 参考索引打开精确文件，不整目录通读。
|
||
- 验收标准：实现任务说明中写明参考了哪个 `packages/...` 文件和哪个搜索点。
|
||
|
||
### B. 面板状态模型
|
||
|
||
- [ ] B1. 定义 Leptos 侧 `HermesPanelState`。
|
||
- 验收标准：状态至少包含 `sessionId`、`sessionTitle`、`modelName`、`profileName`、`runStatus`、`connectionStatus`、`contextScope`、`toolAvailability`、`lastAudit`。
|
||
- [ ] B2. 明确哪些字段来自 Hermes，哪些字段来自 mnote。
|
||
- 验收标准：session/message/model/profile/run/tool event 来自 Hermes；page title/context/audit 来自 mnote；没有字段把 Hermes session title 当作页面标题。
|
||
- [ ] B3. 增加空态、连接失败态、tool 不可用态。
|
||
- 验收标准：Hermes 未启动、未配置模型、mnote plugin 缺失、权限不足分别有不同 UI 状态。
|
||
|
||
### C. 顶部 Mini Hermes 状态条
|
||
|
||
- [ ] C1. 展示当前 session 标题和恢复状态。
|
||
- 验收标准：刷新页面后能从 Hermes session detail 恢复标题和消息，不从 mnote 本地 state 恢复聊天真相。
|
||
- [ ] C2. 展示 model/profile 摘要。
|
||
- 验收标准：能看到当前模型与 profile；缺失时显示“去 Hermes 配置”的动作，而不是在 mnote 内要求填写 API key。
|
||
- [ ] C3. 增加设置跳转入口。
|
||
- 验收标准：入口跳到 Hermes 设置或 profile 页面；mnote 页面内不出现 provider/API key 编辑表单。
|
||
|
||
### D. Run 控制与恢复
|
||
|
||
- [ ] D1. 显示 run 状态。
|
||
- 验收标准：发送后能依次看到 running/tool_calling/completed 或 failed；状态来自 Hermes run event。
|
||
- [ ] D2. 支持停止当前 run。
|
||
- 验收标准：点击停止后 Hermes run 进入 aborted/failed 的明确终止态，输入框恢复可用。
|
||
- [ ] D3. 支持失败后重试或继续。
|
||
- 验收标准：失败态有明确按钮；重试不会创建 mnote 本地聊天副本。
|
||
- [ ] D4. 刷新后恢复进行中或已完成 session。
|
||
- 验收标准：刷新页面不丢失 Hermes 消息；若 run 已结束，状态显示 completed/failed 而不是一直 loading。
|
||
|
||
### E. Context Scope
|
||
|
||
- [ ] E1. 增加 context scope 控件。
|
||
- 验收标准：至少支持当前页、当前选区、当前块、页面设置四类；无选区时选区项禁用。
|
||
- [ ] E2. run input 只携带当前 scope 的上下文摘要。
|
||
- 验收标准：正文大对象不长期写进 Hermes session；Hermes 需要最新正文时通过 `mnote.page.get` 回读。
|
||
- [ ] E3. tool call audit 记录 context scope。
|
||
- 验收标准：`mnote.page.save`、artifact 写入等 audit 能看到本次来源是 page/selection/block/options 哪种 scope。
|
||
|
||
### F. Tool 可用性与最近调用
|
||
|
||
- [ ] F1. 展示 mnote tools 清单。
|
||
- 验收标准：清单来源于 Hermes plugin/tool registry 或 mnote-web 过渡聚合，不能只写死在前端。
|
||
- [ ] F2. 区分只读工具和写入工具。
|
||
- 验收标准：`mnote.page.get` 明确为只读；`mnote.page.save`、`mnote.page.update_title`、`mnote.artifact.*` 明确为写入。
|
||
- [ ] F3. tool event 默认折叠，支持展开详情。
|
||
- 验收标准：交互参考 `MessageItem.vue` 的 `tool-preview` / `tool-details`，但使用 Leptos 实现；长 JSON 不撑破布局。
|
||
- [ ] F4. 最近 tool call 关联 audit。
|
||
- 验收标准：能从 UI 或测试输出看到 `sessionId/runId/toolCallId/traceId/auditId` 的串联。
|
||
|
||
### G. Session 列表最小面
|
||
|
||
- [ ] G1. 支持当前页面最近 Hermes sessions 列表。
|
||
- 验收标准：列表来自 Hermes session API；只过滤/标注当前 document context，不复制 session 到 mnote。
|
||
- [ ] G2. 支持切换 session。
|
||
- 验收标准：切换后 message list 从 Hermes detail 恢复；页面正文不因切换 session 被自动修改。
|
||
- [ ] G3. P2 支持 rename/delete/search。
|
||
- 验收标准：若未实现，UI 不出现可点击假按钮；若实现，操作调用 Hermes session API。
|
||
|
||
### H. 错误与权限
|
||
|
||
- [ ] H1. Hermes 未启动或 proxy 502 时显示可诊断状态。
|
||
- 验收标准：错误能区分 upstream unavailable、auth/permission、model missing、tool unavailable。
|
||
- [ ] H2. 写入工具权限失败不泄露正文。
|
||
- 验收标准：tool error 展示摘要、trace/audit id 和恢复动作，不展示不必要的正文 payload。
|
||
- [ ] H3. 旧 `/api/ai-agent/run` 继续保持退场 guard。
|
||
- 验收标准：新页面 AI 主链不会调用旧入口；retirement smoke 继续通过。
|
||
|
||
### I. 自动化验收
|
||
|
||
- [ ] I1. 新增或扩展 browser smoke：session 状态条。
|
||
- 验收标准：断言 session title/model/run status 可见。
|
||
- [ ] I2. 新增或扩展 browser smoke：run stop/retry。
|
||
- 验收标准：至少覆盖 stop；retry 若未实现则断言按钮不存在或禁用。
|
||
- [ ] I3. 新增或扩展 browser smoke：context scope。
|
||
- 验收标准：选区/当前页上下文能进入 run payload 或 tool audit。
|
||
- [ ] I4. 新增或扩展 browser smoke：tool 可用性与 audit。
|
||
- 验收标准：能看到 mnote tool 列表、一次 tool call、对应 audit id。
|
||
- [ ] I5. 移动端 smoke。
|
||
- 验收标准：状态条、tool 折叠、输入区在窄屏不重叠。
|
||
|
||
---
|
||
|
||
## 7. Done Gate
|
||
|
||
本稿移入 `done/` 前必须同时满足：
|
||
|
||
- [ ] 页面 AI 抽屉具备 Mini Hermes 状态条，用户能看见当前 session、model/profile、run 状态。
|
||
- [ ] 页面 AI 抽屉具备 context scope 控件，run input 和 tool audit 能反映 scope。
|
||
- [ ] 页面 AI 抽屉能展示 mnote tool 可用性、最近 tool call 和 audit/trace 串联。
|
||
- [ ] stop 至少可用；retry/rename/delete 若未实现，必须明确标为 P2 且 UI 不出现假可用按钮。
|
||
- [ ] Hermes 未启动、模型缺失、plugin/tool 不可用、权限失败至少四类错误有可区分展示。
|
||
- [ ] 页面刷新后仍以 Hermes session detail/resume 为会话真相。
|
||
- [ ] mnote 不保存聊天消息真相，不保存 provider/API key，不创建第二套 plugin registry。
|
||
- [ ] `git diff --check` 通过。
|
||
- [ ] Rust 侧相关测试通过：`cargo test -p mnote-web hermes_client -- --nocapture`、`cargo test -p mnote-web hermes_tools_ -- --nocapture`。
|
||
- [ ] 正式 `3000` smoke 覆盖 session/run/tool/audit/mobile，且证据写回本文。
|
||
|
||
---
|
||
|
||
## 8. 当前建议的下一步
|
||
|
||
优先顺序：
|
||
|
||
1. 先补顶部 Mini Hermes 状态条和错误态，因为这是当前“能回复但缺 Hermes 设置感”的直接缺口。
|
||
2. 再补 context scope 和 tool 可用性，让用户明确 Hermes 正在调用 mnote 的哪些能力。
|
||
3. 最后补 session 列表、rename/delete/search 等历史管理能力。
|
||
|
||
不要先做 Hermes 全局设置页复刻。API key、provider、全局 profile、usage/logs/jobs/files/channels 仍应留在 Hermes 自己的管理台。
|