design: 7-59 move to done, add 7-60 settings IA cleanup done

This commit is contained in:
lix-2026
2026-06-13 22:19:44 +08:00
parent 2cfeb97763
commit 50fc92a715
2 changed files with 608 additions and 42 deletions
@@ -0,0 +1,622 @@
# 7-59 Page AI Reasonix Desktop / Hermes Web 控制面借鉴设计 v1
> 创建时间:2026-06-10
>
> 当前状态:`DONE`
>
> Owner07-ai / Page AI / ACP runtime / Session dashboard / Runtime control surface
>
> 前置完成项:`design/07-ai/done/7-58-page-ai-reasonix-official-desktop-session-alignment-v1.md`
>
> 参考代码:
> - Reasonix 官方 desktop`reference-code/DeepSeek-Reasonix-main/desktop/`
> - Reasonix desktop runtime`reference-code/DeepSeek-Reasonix-main/desktop/src/App.tsx`、`desktop/src/protocol.ts`、`desktop/src/ui/*`
> - Hermes Web UI`reference-code/hermes-web-ui-0.5.18/README.md`、`packages/client/src/api/hermes/*`、`packages/client/src/stores/hermes/*`、`packages/server/src/routes/hermes/*`
> - Hermes VSCode ACP host`reference-code/hermes-vscode-main/src/sessionManager.ts`
> - MNote 当前 Page AI`rust/crates/mnote-web/src/routes/hermes_client.rs`、`rust/crates/mnote-web/browser/sidebar-page-ai-*.js`
## 1. 第一结论
`7-58` 已经解决了 Reasonix / Hermes 的底层会话连续性分歧:Reasonix 走 live bindingHermes ACP 走 `session/load`
本稿继续处理下一层问题:**Page AI 不应该只是一个聊天抽屉,而应该收敛成“对话 + agent 运行态 + 会话资产 + 配置/权限/工具状态”的轻量控制面。**
Reasonix Desktop 和 Hermes Web 各自值得借鉴的部分不同:
| 参考 | 值得借鉴 | 不应照搬 |
| --- | --- | --- |
| Reasonix Desktop | 运行态事件 reducer、busy/turn complete、queued send、plan/checkpoint/path permission/job/MCP/statusbar | Tauri/Wails 壳、完整桌面布局、Reasonix 专用设置结构 |
| Hermes Web UI | session dashboard、usage/cost、profiles/models/providers、gateway/jobs/logs/config/status、search/export/delete 资产面 | 独立 Web UI IA、Hermes DB 真相、平台 channel 全量管理 |
MNote 的正确方向是:
```text
Page AI drawer = 当前页上下文里的工作面
Page AI session dashboard = MNote 自己的会话资产面
Runtime control surface = Hermes/Reasonix/ChatOnly/API Chat 的统一状态面
External provider/Hermes DB/Reasonix live loop = 外部或进程内 runtime,不是 MNote 长期真相
```
## 2. Reasonix Desktop 对 MNote 的启发
### 2.1 事件不是纯文本流,而是 UI reducer 输入
Reasonix desktop `App.tsx` 将 incoming event 映射为明确状态:
- `$turn_complete`:解除 busy、清 active skill、驱动 queued send。
- `$path_access_required` / `$confirm_required` / `$choice_required`:进入前端待决策队列。
- `$plan_required` / `$checkpoint_required` / `$revision_required` / `$step_completed`:进入 plan/checkpoint UI。
- `$mcp_specs`:显示 MCP 配置/握手/连接/失败/工具数。
- `$jobs`:显示后台 job 列表、运行/退出状态、stop/stop all。
- `$ctx_breakdown` / `$balance` / usage:进入 statusbar / context panel。
- `$session_loaded`:恢复消息、清队列、恢复 carryover usage。
MNote 当前 Page AI 已有 message/tool/permission/session/run 的事件基础,但仍偏“聊天消息优先”。后续应把 Page AI event projection 正式拆成:
| Projection | UI owner | 事件来源 |
| --- | --- | --- |
| final assistant | chat transcript | `message.delta` / final output |
| thought/reasoning | folded reasoning panel | `thought.delta` |
| tool card | tool timeline | `tool.started/completed/failed` |
| permission queue | permission panel/dialog | `permission.*` / ACP decision request |
| plan/checkpoint | plan panel | `plan.updated` / future `checkpoint.*` |
| runtime status | header/statusbar | `session.info.updated` / `run.*` / `usage.updated` |
| MCP/status | runtime control panel | runtime manifest / MCP bridge health |
| background jobs | jobs popover/panel | future `job.*` / tool long-running receipt |
### 2.2 busy 后输入应排队,而不是丢弃或再开 session
Reasonix Desktop 有 `queuedSends`:busy 时用户继续发送,不直接开新底层 sessionturn complete 后 FIFO 自动发送。
MNote 对 Reasonix 尤其需要这个模型,因为同一 live binding 内必须串行 prompt。当前 `7-58` 对 busy binding 会返回 `acp_reasonix_session_busy`。后续应该升级为:
```text
Reasonix binding running
-> 新输入进入 MNote Page AI session queue
-> UI 显示 queued count / 可取消
-> 当前 run terminal 后自动启动下一条 run
-> 仍复用同一 live binding / acpSessionId
```
验收不应只是“不报 busy”,而是验证两条快速输入仍同一 `acpSessionId` 且顺序正确。
### 2.3 Stop 语义必须拆三层
Reasonix Desktop 的 stop 更接近“停止当前 turn/job”,不是删除 session。MNote 后续 UI 应明确三个按钮/动作:
| 动作 | 含义 | 默认影响 |
| --- | --- | --- |
| Stop turn | 取消当前 prompt | 保留 MNote session 与 live binding |
| Reset runtime | 关闭 Reasonix live binding / Hermes ACP manager | 保留 MNote history,下一轮 cold/new |
| Delete session | 删除 MNote session history/audit | 不默认删除外部 Hermes DB / provider 会话 |
这能避免用户点击“停止”后误以为历史或底层 session 被删。
### 2.4 MCP / jobs / usage 要进状态条,不进 assistant 正文
Reasonix Desktop 把 MCP specs、jobs、usage、balance 放到 sidebar/statusbar/settings,而不是让模型自然语言解释。
MNote 后续应在 Page AI header 下增加 compact status strip
```text
runtime: Reasonix native-live | Hermes loadable | ChatOnly provider
session: mnoteSessionId / acpSessionId / mode
model/profile: profile id + resolved model
roots: write/read-only grant count
MCP: connected/failed/tool count
tools: enabled/disabled count
jobs: running count
usage: last run tokens/cost/cache if available
```
## 3. Hermes Web 对 MNote 的启发
Hermes Web UI 的 README 将能力分成 Chat、Platform Channels、Usage、Jobs、Model Management、Multi-Profile/Gateway、File Browser、Group Chat、Skills/Memory、Logs、Auth、Settings、Web Terminal。
MNote 不能照搬完整 dashboard,但可以抽取控制面能力:
### 3.1 Session asset dashboard
Hermes Web 的 session 管理包含:多会话、rename/delete/switch、SQLite session DB、按来源分组、active session pin、搜索、模型 badge、context token usage。
MNote 已有最小 list/detail/search/export/rename/delete。后续应补:
- active session pin:正在 run 的 session 固定到历史列表顶部。
- runtime groupingReasonix / Hermes ACP / ChatOnly / API Chat 分组。
- status filtersactive / completed / failed / cold_resumed / native_live / replay_seen。
- search fieldsuser question、assistant final、tool name、citation path、changed file、error code。
- export profileJSON / Markdown / audit JSONL 三种导出。
- delete semantics badge:仅删 MNote history,外部 provider/Hermes DB 不默认删除。
### 3.2 Usage / cost / context panel
Hermes Web 有 usage analyticstoken breakdown、daily trend、model distribution、cost/cache。
MNote 不需要先做全局财务面板,但 Page AI 应先做 session/run 级 usage
- 当前 runprompt/completion/reasoning/cache tokens。
- 当前 session:累计 tokens/cost/cache hit。
- 当前 runtimereserved tool/system/context tokens。
- fallback/cold resume:显示 packet 大小和截断原因。
Reasonix Desktop 的 `ctx_breakdown` 与 Hermes Web 的 usage store 可以合并成 MNote 的 `page_ai_usage_projection.v1`
### 3.3 Profiles / models / providers
Hermes Web 将 providers/models/profiles 拆成独立设置面,并支持 credential pool、provider presets、default model switching。
MNote 当前 Page AI profile selector 已可用,但缺少“解析后的真实模型与凭据状态”。后续应显示:
| 字段 | 示例 |
| --- | --- |
| profileId | `mnoteai` / `shared_api_deepseek_flash_chat` |
| providerKind | `hermes-acp` / `api-chat` / `web-provider` |
| resolvedModel | `deepseek-v4-flash` / `gpt-5.5` |
| credentialStatus | configured / missing / inherited / masked |
| runtimeBinary | `hermes` / `node scripts/reasonix-acp-wrapper.mjs` |
| configSource | control-plane / env / profile file |
### 3.4 Gateway / logs / jobs
Hermes Web 把 gateway、logs、jobs 作为运维一等公民。MNote 后续应只引入轻量版:
- Runtime healthHermes ACP process、Reasonix wrapper、MNote MCP bridge、LightRAG MCP/HTTP。
- Logs tail:最近 N 条 ACP stderr、tool failed、permission denied、MCP failed。
- Jobs:长任务工具的 running/completed/failed,不把后台进度塞进 assistant final。
### 3.5 Skills / memory
Hermes Web 有 skills/memory 浏览。Reasonix Desktop 也有 skills、memory、MCP specs。
MNote Page AI 后续应把 skill/memory 作为 runtime capability,而不是继续分散在设置页:
- 当前 runtime 可用 skills。
- enabled/disabled user preference。
- inline/subagent 模式。
- project/global/builtin scope。
- memory sourceReasonix native memory / Hermes memory / MNote profile note。
- 对 Reasonix native-live,不把 MNote memory 强塞到每轮 prompt;只作为 capability manifest 或 cold resume fallback 输入。
## 4. 目标信息架构
### 4.1 Page AI drawer 分区
```text
Header
runtime badge / profile / model / session mode / active-run status
Chat
user / assistant final
folded thought
tool cards
citations
changed files receipt
Runtime
live binding / acpSessionId / load/replay / cold resume
MCP status
allowed roots
tool enablement
permission queue
jobs
usage/context
History
list / search / filters / export / rename / delete
Settings
profile/model/provider
skills/memory
runtime health/logs
```
### 4.2 不同 runtime 的展示差异
| Runtime | Header mode | Runtime panel 必显 | 不显示/禁用 |
| --- | --- | --- | --- |
| Reasonix ACP | `native-live` / `cold-resumed` / `new-session` | live binding、MCP specs、jobs、allowed roots、queued sends | `session/load` 成功率、provider conversation |
| Hermes ACP | `loaded` / `load-failed-new` / `replay-seen` | acpSessionId、load/replay、profile/model、tool locations | Reasonix live binding status |
| ChatOnly Web | `provider-conversation` | providerConversationId、remote delete status | ACP session/load/live binding |
| API Chat | `server-transcript` | model/provider/usage、MNote transcript | provider web conversation binding |
## 5. 后端合同
### 5.1 Runtime status snapshot
新增或收口一个 Page AI runtime status API
```text
GET /api/page-ai/runtime/status?sessionId=...&workspaceId=...&documentId=...
```
返回:
```json
{
"schema": "mnote.page_ai_runtime_status.v1",
"mnoteSessionId": "...",
"runtime": "reasonix",
"profile": "reasonix",
"mode": "native_live",
"activeRun": { "runId": "...", "status": "running" },
"acp": {
"acpSessionId": "...",
"supportsSessionLoad": false,
"replaySeen": false,
"liveBinding": { "status": "idle", "workspaceKey": "file://..." }
},
"model": { "resolvedModel": "...", "providerKind": "..." },
"roots": { "write": 1, "readOnly": 0 },
"mcp": { "status": "connected", "toolCount": 8, "failed": [] },
"tools": { "enabled": 12, "disabled": 2 },
"jobs": { "running": 0 },
"usage": { "sessionTokens": 0, "lastRunTokens": 0 }
}
```
规则:
- `acpSessionId` 只作为 runtime reference,不是 MNote 长期真相。
- Reasonix `supportsSessionLoad=false` 必须明确展示。
- Hermes replay 只能影响 `replaySeen/replaySeq`,不能当当前 answer。
- ChatOnly/API Chat 不返回 ACP binding。
### 5.2 Session search/export 升级
现有 `/api/hermes/client/sessions/search``/export` 后续收口为 Page AI 命名:
```text
GET /api/page-ai/sessions
GET /api/page-ai/sessions/search?q=...
GET /api/page-ai/sessions/{id}
GET /api/page-ai/sessions/{id}/export?format=json|markdown|jsonl
POST /api/page-ai/sessions/{id}/rename
DELETE /api/page-ai/sessions/{id}
```
`/api/hermes/client/sessions/*` 保留 compat,但前端新代码优先走 `/api/page-ai/*`
### 5.3 Queued sends
新增队列表:
```text
page_ai_queued_runs
id
user_id
workspace_id
document_id
session_id
run_id
runtime
profile
payload_json
status: queued | started | cancelled | failed
created_at / updated_at
```
Reasonix live binding busy 时不返回 failed,而是入队。
## 6. 前端实现边界
### 6.1 文件 owner
| 文件 | 改动边界 |
| --- | --- |
| `sidebar-page-ai-runtime.js` | 只保留 orchestration;不要继续塞 dashboard 渲染细节 |
| `sidebar-page-ai-session-runtime.js` | session list/detail/search/export/rename/delete/filters |
| `sidebar-page-ai-render-runtime.js` | Page AI 面板渲染,新增 Runtime / Dashboard 分区 |
| `sidebar-page-ai-profile-runtime.js` | profile/model/provider 解析展示 |
| `sidebar-page-ai-skill-runtime.js` | skill/memory/MCP capability 偏好 |
| `sidebar-page-ai-permission-runtime.js` | permission decision queue |
| 新建议:`sidebar-page-ai-runtime-status-runtime.js` | runtime status polling/event apply,不和 chat streaming 混写 |
### 6.2 UI 原则
- Runtime 状态只做 compact status strip + detail panel,不占 assistant 正文。
- thought/tool/plan/permission/citation 分区渲染,不拼进 final answer。
- history action 永远可点击,不靠 hover 才能完成核心操作。
- stop/reset/delete 三类危险程度不同,按钮必须分开。
- 短回复“可以/继续”在 `new-session` 且无 history 时显示缺上下文提示。
## 7. 执行顺序
### Phase ARuntime status surface
- [x] 后端新增 `/api/page-ai/runtime/status`,返回 runtime/profile/model/session/acp/mcp/tools/jobs/usage。
- [x] 前端 header 显示 runtime badge、session mode、active-run status。
- [x] Runtime panel 展示 `acpSessionId`、Reasonix live binding、Hermes load/replay、allowed roots。
- [x] 浏览器 smokeReasonix / Hermes / API Chat 三种 runtime 切换时 status 不串线。
### Phase BReasonix Desktop 运行态对齐
- [x] Reasonix busy binding 改为 queued send,不再直接 failed。
- [x] 队列 UI 显示 queued count、queued text preview、cancel。
- [x] 当前 run terminal 后自动启动下一条 queued run,仍复用同一 live binding。
- [x] Stop turn 不关闭 bindingReset runtime 才关闭 binding。
- [x] MCP specs/status/toolCount 进入 runtime panel。
- [x] Jobs popover 支持 long-running tool receipt / stop all。(当前无真实后台 job registry 时展示空态和 no-op stop-all,后续长任务接入只需填充 `jobs.items`。)
- [x] Smoke:快速发送两条消息,验证 FIFO、同一 `acpSessionId`、无输出中残留。
### Phase CHermes Web 控制面最小引入
- [x] Page AI session API 命名从 `/api/hermes/client/sessions` 收口到 `/api/page-ai/sessions`
- [x] session list 支持 runtime grouping、active pin、status filters。
- [x] search 支持 message/tool/citation/changed file/error code。
- [x] export 支持 json/markdown/jsonl 三格式。
- [x] usage panel 展示 session/run/model/cache/cost。
- [x] profile/model/provider panel 展示 resolved model、credential status、config source。
- [x] Smokesearch/filter/export/usage/profile status 在真实浏览器可见。
### Phase D:权限/配置/外部删除边界
- [x] permission decision loop 做成持久 pending queue,刷新后不丢。
- [x] delete session 明确只删除 MNote history;外部 Hermes/provider 删除必须二次确认。
- [x] reset runtime 只关闭 live binding/ACP manager,不删除 MNote history。
- [x] logs tail 显示 ACP stderr、tool failed、MCP failed 最近 N 条。
- [x] Smokedelete/reset/stop 三类动作互不误伤。
## 8. 验收矩阵
### 8.1 Reasonix
- [x] `native-live` 状态清晰可见。
- [x] busy 时第二条输入进入 queue,不开新 session。
- [x] queued send 自动执行后仍同一 `acpSessionId`
- [x] Stop turn 后下一轮仍可 native-live。
- [x] Reset runtime 后下一轮显示 `cold_resumed``new_session`
- [x] MCP failed 显示为 status/tool card,不污染 assistant final。
### 8.2 Hermes ACP
- [x] stored `acpSessionId``session/load`
- [x] replay 显示为 replay evidence / history restore,不混入当前回答。
- [x] load failed 明确显示 `load-failed-new`
- [x] session dashboard 可按 Hermes profile/model 过滤。
### 8.3 ChatOnly / API Chat
- [x] providerConversationId 与 acpSessionId 不混用。
- [x] API Chat 不写 web provider binding。
- [x] session dashboard 仍可展示/search/export。
- [x] delete MNote history 不默认删除远端 provider 会话。
### 8.4 通用 UI
- [x] 回答完成后无 `AI · 输出中`
- [x] history actions 在桌面/移动都可点击。
- [x] runtime status 与当前 session 一致,切 session 后不显示旧 acpSessionId。
- [x] tool/citation/permission/plan/job 不进入 assistant final。
## 9. 不做事项
- 不把 Reasonix Desktop 的 Tauri shell 或完整布局搬进 MNote。
- 不把 Hermes Web UI 作为 MNote 的独立 dashboard 复刻。
- 不把 Hermes DB 当成 MNote session 真相。
- 不把 Reasonix native memory 改造成 MNote 每轮 transcript 注入。
- 不自动删除外部 Hermes/provider session store。
- 不在 Page AI 主路径继续叠加无界轮询;runtime status 优先事件/command result 驱动,短期 fallback 必须有退出条件。
## 10. 首批可执行切片
### 10.1 Slice A1runtime status 后端只读快照
目标:先让 Page AI 能回答“当前 agent 是谁、是否还在运行、底层 session 是否连续、MCP/工具是否可用”。
范围:
- 新增 `/api/page-ai/runtime/status` 只读 route。
- 数据先从现有 `PageAiSessionStore` / `AcpSessionManager` / profile resolver / tool registry 组合,不新增长期表。
- Reasonix 返回 `mode=native_live|cold_resumed|new_session`Hermes 返回 `mode=loaded|load_failed_new|replay_seen|new_session`ChatOnly/API Chat 返回非 ACP mode。
- active run 状态必须来自 event store / terminal reconciliation 后的最终状态,不能只看前端 streaming flag。
验收:
```bash
cargo test -p mnote-web page_ai_runtime_status
```
若 Rust route 暂时没有专名测试,至少补一个 fake store/unit test 覆盖 Reasonix、Hermes、API Chat 三类 snapshot。
### 10.2 Slice A2Page AI header/status strip
目标:把 runtime status 放到聊天抽屉顶部,而不是让 assistant 正文解释。
范围:
- `sidebar-page-ai-render-runtime.js` 增加 compact status strip。
- `sidebar-page-ai-runtime.js` 只负责加载/应用 status,不塞具体 DOM 细节。
- 回答终止后 status strip 必须同步清理 active-run,避免 `AI · 输出中` 残留。
- 切换 session/document 后先清空旧 status,再加载新 status,避免旧 `acpSessionId` 短暂串线。
验收:
```bash
node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
```
并补一条真实浏览器 smokeReasonix/Hermes/API Chat 切换后 header badge 与当前 profile 一致。
### 10.3 Slice B1Reasonix queued send 最小版
目标:busy binding 不再直接失败,先支持同一 Page AI session 内 FIFO 串行发送。
范围:
- 先实现内存队列或 event-store backed queue;如果实现跨刷新不稳定,再升级 `page_ai_queued_runs` 表。
- queue item 必须记录 `sessionId``runId``runtime``profile``acpSessionId`、原始 prompt payload。
- 当前 run terminal 后自动 dequeue 下一条,仍复用 Reasonix live binding。
- cancel queued item 只取消队列项,不 stop 当前 run。
验收:
```bash
node scripts/task558-page-ai-reasonix-live-session-context-smoke.js
```
新增/扩展浏览器断言:
- 快速发送两条消息。
- 第二条先显示 queued。
- 两轮完成后 `acpSessionId` 一致。
- 第二轮短回复能引用第一轮上下文。
- 最终无 `AI · 输出中`
### 10.4 Slice C1Page AI sessions 命名兼容层
目标:前端新主路径不再把 Page AI session dashboard 命名成 Hermes client。
范围:
- 新增 `/api/page-ai/sessions/*` wrapper。
- 复用现有 `/api/hermes/client/sessions/*` handler 或 store,不重复实现。
- 老路由继续保留 compat;测试必须证明老路由仍可用。
- 前端 session runtime 优先请求 `/api/page-ai/sessions/*`
验收:
```bash
cargo test -p mnote-web page_ai_sessions
node scripts/task561-page-ai-session-dashboard-smoke.js
```
### 10.5 Slice C2Hermes load/replay 可见化
目标:把 Hermes ACP `session/load` 与 replay 作为 runtime evidence 展示,而不是混入当前回答。
范围:
- status snapshot 增加 `loadAttempted``loadStatus``replaySeen``replaySeq``replayMessageCount`
- UI 显示为 runtime panel evidence。
- 当前 assistant final 只来自当前 run final,不消费 replay 作为回答。
验收:
```bash
node scripts/task560-page-ai-hermes-load-replay-smoke.js
```
覆盖无 replay / 有 replay 两种 fake Hermes ACP fixture。
## 11. Event projection 合同
Page AI 后续统一把 runtime events 规整成下面几类 projection。前端只能消费 projection,不直接按 provider 原始事件猜 UI 状态。
| Projection | 关键字段 | terminal 规则 |
| --- | --- | --- |
| `runProjection` | `runId/status/startedAt/endedAt/errorCode` | `completed/failed/cancelled` 必须清 active-run |
| `messageProjection` | `role/final/thought/toolCalls/citations` | final 与 thought 分离 |
| `sessionProjection` | `mnoteSessionId/runtime/acpSessionId/mode` | 切 session 后旧 projection 不可复用 |
| `runtimeProjection` | `profile/model/provider/binary/configSource` | profile 切换后立即 invalidated |
| `capabilityProjection` | `mcp/tools/skills/memory/roots` | failed capability 不污染 assistant final |
| `decisionProjection` | `permission/choice/confirm/pathAccess` | pending 决策可刷新恢复 |
| `queueProjection` | `queuedCount/items/cancellable` | current terminal 后 FIFO dequeue |
| `usageProjection` | `tokens/cost/cache/contextBreakdown` | usage 缺失时显示 unknown,不伪造 0 |
最低要求:
- `AI · 输出中` 只能绑定 `runProjection.status=running|streaming`
- `acpSessionId` 只能来自 `sessionProjection`
- replay、load、MCP、job、permission 都不能写进 assistant final。
- provider 原始 event 增加新字段时,未识别字段进入 `rawEvidence`,不直接影响 UI。
## 12. 风险与边界
### 12.1 上下文连续性的误判风险
短回复“可以/继续”天然依赖历史。UI 必须区分:
| 状态 | 用户提示 |
| --- | --- |
| `native_live` / `loaded` | 显示连续会话 |
| `cold_resumed` | 显示已用 MNote history fallback 恢复 |
| `new_session` 且 history 为空 | 提示当前没有可用上下文 |
| `load_failed_new` | 提示底层 ACP load 失败,已新建 runtime session |
这比单纯把 transcript 拼进 prompt 更重要,因为 Reasonix native-live 与 Hermes load/replay 的真实连续机制不同。
### 12.2 删除与重置边界
删除、重置、停止必须保持三套语义:
- `Stop turn`:只影响当前 run。
- `Reset runtime`:只影响 Reasonix live binding / Hermes ACP process 或 manager。
- `Delete session`:只影响 MNote session history;外部 Hermes DB / provider 会话删除必须另设显式二次确认。
### 12.3 轮询边界
runtime status 首选 event apply / command result refresh。短期允许有界 fallback,但必须满足:
- 仅在 Page AI drawer 可见且当前 session active 时启用。
- interval 有最大时长和 stop 条件。
- run terminal、session switch、drawer close 都必须停止。
- 后续进入 done 前,要记录是否已替换为 event-driven。
## 13. 设计归档规则
本稿进入 `done/` 前必须满足:
- Phase A-D checklist 至少按 slice 完成,并记录每个 slice 的测试命令。
- 浏览器 smoke 证明 Reasonix、Hermes ACP、ChatOnly/API Chat 不串状态。
- 用户最初两个问题已有可见验收:短回复能继承上下文,回答完成不残留 `AI · 输出中`
- 若某项因为外部 provider 权限、Hermes DB 删除策略或 Reasonix 官方行为无法完成,必须在本稿末尾追加“归档说明”,不能只留 unchecked TODO。
## 14. 本稿完成条件
- Phase A-D checklist 有真实代码、单测或 browser smoke。
- Reasonix queued send / stop / reset 语义明确可见。
- Hermes-style session dashboard 不再挂在 `/api/hermes/client/*` 命名主路径上。
- Runtime status 能解释用户最关心的四件事:当前 agent 是谁、上下文是否连续、工具/MCP 是否可用、为什么还在输出中或已经结束。
- ChatOnly / API Chat 回归不受 ACP runtime status 改动影响。
## 15. 实施记录
### 2026-06-10 Slice A-D 完成记录
已完成:
- 后端新增 `/api/page-ai/runtime/status`,返回 `runtime/profile/model/session/acp/mcp/tools/jobs/usage/logs`
- 前端 Page AI header 增加 runtime status stripruntime panel 增加 status detail。
- `AI · 输出中` / active-run 清理继续走 terminal reconciliation`session.created` 不再被判定为 active run。
- Reasonix 前端 busy/queued/running 发送改为 client FIFO queue:当前 run 结束后自动发送下一条,仍复用当前 MNote session 和已保存的 `acpSessionId`
- Reasonix live binding 的 direct busy fallback 不再立即返回 `acp_reasonix_session_busy` failedstream 侧等待 binding idle 后继续同一 live binding。
- 队列 UI 显示 queued count、preview、cancelclient queued item 可本地取消。
- 新增 `/api/page-ai/sessions/*` 主命名 route,旧 `/api/hermes/client/sessions/*` 保留 compat。
- 前端 session runtime 已切到 `/api/page-ai/sessions/*`
- Hermes replay 继续作为 `adapter_replay` evidenceruntime status 展示 `replaySeen/replaySeq/replayMessageCount`
- permission pending queue 增加 localStorage 恢复,刷新后可恢复未决 permission。
- 新增 `/api/page-ai/runtime/reset`,只关闭 Reasonix live binding / runtime binding,不删除 MNote history 或外部 provider session。
- session delete 默认只删除 MNote history / 本地 provider binding 标记;外部 provider 远端删除需要 `deleteExternalProviderSession=1`
- session dashboard 增加 runtime/status filter、active pin、可见 action,前端主路径使用 `/api/page-ai/sessions/*`
- session export 增加 `json/markdown/jsonl` 三格式。
- runtime panel 增加 jobs/logs tail;当前无真实长任务 registry 时显示空态,`Stop all` 不删除 history / runtime,只在无 job 时提示无可停止项。
验证:
```bash
cargo test -p mnote-web page_ai_runtime_status -- --nocapture
cargo test -p mnote-web page_ai_session_active_run -- --nocapture
cargo test -p mnote-web delete_session -- --nocapture
cargo test -p mnote-web hermes_client -- --nocapture
node --check rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-render-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-session-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-permission-runtime.js
node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
node scripts/task558-page-ai-reasonix-live-session-context-smoke.js
node scripts/task560-page-ai-hermes-load-replay-smoke.js
node scripts/task561-page-ai-session-dashboard-smoke.js
```
最新验证输出:
- `cargo test -p mnote-web hermes_client -- --nocapture`87 passed。
- `node scripts/task558-page-ai-reasonix-live-session-context-smoke.js`:通过,验证快速连续发送、queued preview、同一 `acpSessionId`、第二轮“可以”继承上下文、无输出中残留。
- `node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js`:通过,验证 terminal reconciliation、runtime strip、runtime panel jobs/logs/status 可见。
- `node scripts/task560-page-ai-hermes-load-replay-smoke.js`:通过,覆盖 no replay / with replay。
- `node scripts/task561-page-ai-session-dashboard-smoke.js`:通过,验证 `/api/page-ai/sessions/*`、search、status filter、export `json/markdown/jsonl`、rename/delete。
归档说明:
- 当前 jobs 面板已经有 `jobs.running/items` 合同、空态和 Stop all 控件;由于 Page AI 还没有真实 long-running job registry,本稿不伪造 job receipt,不接外部 provider job 删除。后续长任务工具接入时只扩充 `jobs.items` 和 stop handler。
- 外部 Hermes/provider 远端删除仍不提供默认 UI 动作;后端只接受显式 `deleteExternalProviderSession=1`,前端普通 Delete session 只删 MNote history。
@@ -0,0 +1,514 @@
# 7-60 Page AI 设置 IA 整理 v1
> 创建时间:2026-06-10
>
> 当前状态:`DONE`
>
> Owner07-ai / Page AI / Settings IA / Runtime status
>
> 前置完成项:
> - `design/07-ai/done/7-58-page-ai-reasonix-official-desktop-session-alignment-v1.md`
> - `design/07-ai/done/7-59-page-ai-reasonix-desktop-hermes-web-control-surface-alignment-v1.md`
>
> 当前问题来源:7-59 后 Page AI 已有 runtime status、queue、jobs、logs、sessions dashboard,但 UI 仍沿用旧的 `Common / Hermes / Reasonix / Chat-only / 高级 / Runtime` 分层,导致“设置”和“运行态”混在一起。
## 1. 第一结论
Page AI 设置需要按 owner 分三层:
```text
MNote = MNote 如何给 AI 上下文、权限、工具、会话历史和审计
Reasonix = Reasonix ACP/native-live/queue/MCP/memory 的专属运行配置
Hermes = Hermes gateway/profile/model/provider/session-load/replay/skills 的专属运行配置
```
同时必须把“运行态状态”从“设置”里拆出去:
```text
设置 = 可持久保存或影响后续 run 的配置
状态 = 当前这一轮/当前 session 的 live snapshot
```
当前截图里的混乱点不是单个控件坏了,而是抽象层级混用:
- 顶部显示 `Reasonix`runtime strip 却显示 `hermes · new-session`,用户会误以为当前 agent 与 runtime 不一致。
- `Common` 实际是 MNote 自身配置,但名字没有表达 owner。
- `高级``Runtime` 既有设置项,又有只读状态项。
- Runtime panel 里出现“打开 Hermes 设置”,但当前用户可能正在使用 Reasonix。
- `Chat-only` 被放成一级设置页,但它本质是 MNote/API Chat/Hermes provider 的一种 runtime/profile 类型,不应和 Reasonix/Hermes 并列为 provider owner。
## 2. 新信息架构
### 2.1 Page AI 顶层导航
Page AI 抽屉保留五个一级工作区:
| 一级区 | 含义 | 当前入口 |
| --- | --- | --- |
| 聊天 | 当前页对话、工具卡、引用、权限决策 | 默认页 |
| 状态 | 当前 runtime/session/run live snapshot | 由 runtime strip 或状态图标打开 |
| 设置 | MNote / Reasonix / Hermes 三层配置 | 齿轮 |
| 能力 | 当前 runtime 可用 tools/skills/memory 清单与开关 | sparkle/能力图标 |
| 历史 | MNote session dashboard | 搜索/历史图标 |
原则:
- “状态”不承载长期配置。
- “设置”不展示 transient logs/job/active-run。
- “能力”可以按 runtime 过滤,但 capability owner 仍归 MNote / Reasonix / Hermes。
- “历史”展示 MNote session asset,不等于 Hermes DB 或 Reasonix native session。
### 2.2 设置页三层结构
设置页只保留三个主 tab
```text
MNote | Reasonix | Hermes
```
不再显示:
```text
Common | Chat-only | 高级
```
旧 tab 映射:
| 旧 tab / 控件 | 新归属 |
| --- | --- |
| `Common` | `MNote` |
| `Chat-only` | `MNote > API Chat / Chat-only profile` |
| `高级` 里的 context scope | `MNote > 默认上下文` |
| `高级` 里的 runtime status | `状态` |
| `Runtime` panel | `状态` |
| `打开 Hermes 设置` | `Hermes` tab 内 |
| Reasonix memory / skill filter | `Reasonix` |
| Hermes profile / builtin skill filter | `Hermes` |
## 3. MNote 设置
MNote tab 只放 MNote 自己拥有的控制面:
### 3.1 授权区域
来源:SQLite `directory_grants` / current workspace grants。
展示:
- 当前 workspace/root。
- allowed roots 数量。
- read/write 权限。
- 授权来源:manual / smoke / share / system。
- 权限缺失时的修复入口。
不展示:
- Hermes API key。
- Reasonix ACP binary。
- providerConversationId。
### 3.2 默认上下文
来源:Page AI context refs。
控件:
- 当前页。
- 打开资源。
- 选中文本。
- 页面子树。
- 附件/资源 tab。
保存语义:
- 这是 MNote 的默认 run envelope 规则。
- 不直接改 Reasonix/Hermes 的 native memory。
### 3.3 MNote 工具
范围:
- LightRAG。
- citation/open reference。
- page context。
- local file audit。
- changed files receipt。
- MNote MCP/tool facade。
展示:
- enabled/disabled。
- tool count。
- last failed tool。
- capability source。
### 3.4 会话与审计
范围:
- MNote history。
- export `json/markdown/jsonl`
- delete MNote history。
- changed files audit。
- permission pending queue。
删除文案必须固定:
```text
删除只影响 MNote 历史,不删除外部 Hermes/provider/Reasonix session。
```
外部删除只能出现在 Hermes tab 的危险区,并需要二次确认。
## 4. Reasonix 设置
Reasonix tab 只放 Reasonix 专属配置与能力:
### 4.1 Runtime
展示:
- ACP runtime name`reasonix`
- binary/wrapper`scripts/reasonix-acp-wrapper.mjs` 或配置来源。
- workspace key 规则。
- native-live 支持状态。
- supports session/loadfalse。
- supports replayfalse。
### 4.2 Native-live session
只展示配置和策略,不展示当前 active-run 日志。当前 live binding 细节在“状态”页。
设置项:
- native-live 开关或策略说明。
- cold resume fallback 是否启用。
- short reply without context 的提示策略。
### 4.3 Queue
设置项:
- busy send 行为:enqueue。
- cancel queued item 策略。
- queue max length。
- queue timeout。
当前 queued count / preview 属于“状态”页。
### 4.4 MCP / tools / memory
范围:
- Reasonix MCP specs。
- Reasonix tool count。
- Reasonix memory 开关。
- Reasonix skill filter。
不放:
- Hermes profile。
- MNote LightRAG provider 设置。
- Chat-only provider 配置。
## 5. Hermes 设置
Hermes tab 只放 Hermes 相关配置:
### 5.1 Gateway
展示:
- `MNOTE_WEB_HERMES_UPSTREAM_URL`
- gateway health。
- config source。
- logs link / settings link。
当前“未配置 Hermes 设置入口”错误只应出现在 Hermes tab,不应污染 Reasonix 设置或状态。
### 5.2 Profile / model / provider
展示:
- profile id。
- resolved model。
- provider kind。
- credential status。
- config source。
- API key masked/missing/configured。
### 5.3 ACP session load / replay
展示:
- supports session/loadtrue。
- stored `acpSessionId`
- load statusloaded / load-failed-new。
- replaySeen / replaySeq / replayMessageCount。
注意:
- replay 是 history restore/evidence,不进入 assistant final。
- load failed 只影响 runtime continuity,不删除 MNote history。
### 5.4 Skills / memory
范围:
- Hermes skills。
- hide builtin skills。
- Hermes memory sectionssoul/user/memory。
- profile-local skills。
### 5.5 外部删除危险区
默认隐藏在 Hermes tab 底部。
动作:
- 删除 MNote history:跳回 MNote 会话与审计。
- 删除外部 Hermes/provider 会话:必须二次确认,且需要显式参数 `deleteExternalProviderSession=1`
## 6. 状态页
状态页是 7-59 runtime panel 的重排版,不是设置页。
入口:
- 点击顶部 runtime strip。
- 或 header 增加状态图标。
内容:
| 区块 | 字段 |
| --- | --- |
| Current runtime | runtime / mode / profile / model |
| Session | mnoteSessionId / acpSessionId / providerConversationId |
| Run | active run / status / queue |
| Context | allowed roots / context scope |
| MCP & tools | mcp status / tool count / failed |
| Jobs | running/completed/failed / stop all |
| Logs tail | ACP stderr / tool failed / MCP failed |
| Usage | last run / session total / cache/cost if available |
状态页允许两个操作:
| 操作 | 语义 |
| --- | --- |
| Stop turn | 只停止当前 run,不删除 session,不关闭 live binding |
| Reset current runtime | 关闭当前 runtime binding/manager,不删除 MNote history,不删除外部 provider |
状态页不允许:
- 删除 session history。
- 删除外部 provider/Hermes 会话。
- 改 Hermes API key。
- 改 Reasonix memory。
## 7. UI 文案规则
### 7.1 Runtime badge
顶部 badge 应按 owner 明确表达:
```text
Reasonix · native-live
Reasonix · cold-resumed
Hermes · loaded
Hermes · replay-seen
API Chat · server-transcript
Chat-only · provider-conversation
```
禁止出现“header 是 Reasonix,但 badge 是 hermes new-session”的短暂串线。切换 agent/profile 时必须先清空旧 runtime status,再加载新 status。
### 7.2 设置 tab 文案
使用:
```text
MNote
Reasonix
Hermes
```
不用:
```text
Common
高级
Chat-only
Runtime
```
### 7.3 危险动作文案
Stop turn
```text
停止当前输出,不关闭 runtime,不删除历史。
```
Reset runtime
```text
重置当前 runtime。MNote 历史保留,外部 provider 会话不删除。
```
Delete session
```text
删除 MNote 历史。外部 Hermes/provider 会话不会删除。
```
External delete
```text
这会请求删除外部 provider/Hermes 会话,可能不可恢复。需要二次确认。
```
## 8. 实施顺序
### Phase AIA rename / no behavior change
- [x] 将设置主 tab 收口为 `MNote / Reasonix / Hermes`
- [x] `Common` 改名 `MNote`
- [x] 移除一级 `Chat-only` tabChat-only 配置迁入 `MNote > API Chat / Chat-only profile`
- [x] `高级`/`Runtime` 不再作为设置 tab 名称。
- [x] 保持现有 DOM action 与后端合同不变,先只做布局与文案重排。
验证:
```bash
node --check rust/crates/mnote-web/browser/sidebar-page-ai-render-runtime.js
node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
```
### Phase B:状态页从设置页拆出
- [x] 新增或重排 `status` panel。
- [x] runtime strip 点击打开状态页。
- [x] runtime status、queue、jobs、logs、usage 移到状态页。
- [x] MNote/Reasonix/Hermes 设置页不再显示 transient active-run logs。
- [x] Stop turn / Reset current runtime 只在状态页显示。
验证:
```bash
node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
node scripts/task558-page-ai-reasonix-live-session-context-smoke.js
```
### Phase CMNote 设置 owner 收口
- [x] 授权区域、默认上下文、MNote 工具、会话与审计进入 MNote tab。
- [x] Chat-only/API Chat profile 的入口进入 MNote tab。
- [x] delete session 文案固定为只删 MNote history。
- [x] permission pending queue 刷新恢复仍可见。
验证:
```bash
node scripts/task561-page-ai-session-dashboard-smoke.js
cargo test -p mnote-web api_chat -- --nocapture
```
### Phase DReasonix / Hermes 设置 owner 收口
- [x] Reasonix tab 只展示 Reasonix runtime/native-live/queue/MCP/memory。
- [x] Hermes tab 只展示 Hermes gateway/profile/model/provider/load/replay/skills。
- [x] Hermes gateway 未配置错误只出现在 Hermes tab。
- [x] Reasonix 页面不出现 Hermes upstream/API key 错误。
- [x] Hermes 页面不出现 Reasonix native-live queue 当前状态。
验证:
```bash
node scripts/task558-page-ai-reasonix-live-session-context-smoke.js
node scripts/task560-page-ai-hermes-load-replay-smoke.js
```
### Phase E:截图与移动端收口
- [x] 桌面宽度下设置 tab 不换行、不挤压。
- [x] 移动宽度下三 tab 可点击,状态页内容可滚动。
- [x] Runtime strip 不遮挡 header action。
- [x] history actions 在移动宽度仍可点击。
验证:
```bash
node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
node scripts/task561-page-ai-session-dashboard-smoke.js
```
需要补截图断言:
- `MNote / Reasonix / Hermes` 三 tab 可见。
- 状态页打开后可见 `Current runtime / Session / Queue / Logs tail`
- Reasonix 设置页无 Hermes API key 错误。
- Hermes 设置页显示 gateway/profile/model/provider。
## 9. 不做事项
- 不改变 7-59 的后端 runtime/session API 合同。
- 不新增第二套 runtime truth。
- 不把 Hermes Web UI 作为完整 dashboard 搬进 MNote。
- 不把 Reasonix Desktop settings 全量复制进 MNote。
- 不自动删除外部 Hermes/provider/Reasonix session。
- 不把 runtime logs/job/tool status 拼进 assistant final。
## 10. 完成条件
- 设置页只剩 `MNote / Reasonix / Hermes` 三个 owner tab。
- Runtime status 从设置页拆出为独立状态页或 runtime strip popover。
- MNote tab 不出现 Hermes API key / Reasonix binary 这类外部 runtime 配置。
- Reasonix tab 不出现 Hermes upstream 未配置错误。
- Hermes tab 不出现 Reasonix native-live 当前 queue。
- Stop turn / Reset runtime / Delete session 三类动作仍语义分离。
- Reasonix queued send、Hermes load/replay、API Chat、ChatOnly 现有 smoke 全部通过。
- 移动截图中 tab、按钮、状态卡不重叠。
## 11. 实施记录
### 2026-06-10 Phase A-E
已完成:
- 设置页 tab 收口为 `MNote / Reasonix / Hermes`
- 移除一级 `Common / Chat-only / 高级 / Runtime` 设置 tab。
- runtime strip 改为可点击入口,点击打开独立 `status` panel。
- `status` panel 展示 `Current runtime / Session / Queue / Jobs / Logs tail / Usage`,并保留 `Stop turn` / `Reset current runtime`
- MNote tab 展示授权区域、默认上下文、会话与审计、API Chat / Chat-only profile、MNote 工具。
- Reasonix tab 只保留 ACP runtime、Reasonix descriptor、Reasonix memory 等专属内容。
- Hermes tab 展示 Hermes gateway、profile/model/provider、Hermes skills/memory,并承载 Hermes gateway 未配置提示。
- 扩展浏览器 smoke,增加设置 IA、状态页、移动宽度 tab 可点性、Hermes/Reasonix owner 边界断言。
验证:
```bash
node --check rust/crates/mnote-web/browser/sidebar-page-ai-render-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-profile-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-session-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-ai-permission-runtime.js
node --check scripts/task558-page-ai-reasonix-live-session-context-smoke.js
node --check scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
node --check scripts/task561-page-ai-session-dashboard-smoke.js
cargo test -p mnote-web hermes_client -- --nocapture
node scripts/task558-page-ai-reasonix-live-session-context-smoke.js
node scripts/task559-page-ai-terminal-status-reconciliation-smoke.js
node scripts/task560-page-ai-hermes-load-replay-smoke.js
node scripts/task561-page-ai-session-dashboard-smoke.js
```
浏览器截图证据:
- `tmp/task559-terminal-status-fpUZi3/task559-runtime-panel.png`:状态页展示 Current runtime、Queue、Jobs、Logs tail、Usage。
- `tmp/task559-terminal-status-fpUZi3/task559-settings-mobile.png`:移动宽度下 MNote / Reasonix / Hermes 三 tab 可点击且不重叠。
- `tmp/task561-session-dashboard-ttJKyq/task561-settings-ia.png`Hermes tab 展示 Hermes gateway/profile/skills,不显示 Reasonix queue。
归档说明:
- 本稿只重排 Page AI 设置 IA 与状态页,不改变 7-59 后端 runtime/session API 合同。
- 外部 Hermes/provider 删除仍需显式二次确认;本稿没有新增默认外部删除入口。