lix/mnote

Files

T

lix-2026 2cfeb97763 feat(page-ai): align ACP session runtime

2026-06-10 07:09:04 +08:00

42 KiB

Raw Blame History

7-58 Page AI Reasonix / Hermes 官方会话与响应对齐 v1

创建时间：2026-06-09

当前状态：PROCESS

Owner：07-ai / Page AI / Reasonix ACP / Hermes ACP / mnote-web runtime

参考代码：

Reasonix 官方 main-v2/desktop：https://github.com/esengine/DeepSeek-Reasonix/tree/main-v2/desktop

Hermes 官方仓库：NousResearch/hermes-agent：https://github.com/NousResearch/hermes-agent

本地参考副本：reference-code/DeepSeek-Reasonix-main

MNote 当前链路：rust/crates/mnote-web/src/routes/hermes_client.rs、rust/crates/mnote-web/src/acp_session_manager.rs、rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js、rust/crates/mnote-web/src/ssr/styles.rs

上位依据：

design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md

design/07-ai/done/7-40-page-ai-context-envelope-and-run-receipt-v1.md

design/10-review/reference/13-hermes-vscode-plugin-gap-review-v1.md

design/10-review/done/10-current-mnote-ai-runtime-review-v1.md

1. 第一结论

Page AI 里 Reasonix 不能继续按“每个 run 都可 session/load 恢复旧 ACP session”的模式设计。

Reasonix 官方 main-v2/desktop 的 ACP 模型是：

initialize.agentCapabilities.loadSession=false。
session/new 创建一个内存 Session，其中持有 CacheFirstLoop、toolset、MCP clients、Eventizer 和 aborter。
session/prompt 必须命中同一个内存 Session，然后调用 session.loop.step(text) 继续对话。
上下文主要在 Reasonix 本地 loop / session 对象里延续，而不是靠 MNote 每轮重发完整聊天历史。

因此 MNote 对 Reasonix 的正确集成不是“保存 acpSessionId，下轮再 load”，而是：同一个 MNote Page AI session 在同一个 Rust Web 进程生命周期内必须复用同一个活的 Reasonix ACP session manager；如果底层 Reasonix session 已丢失，必须显式进入 cold resume/fallback，不得假装仍是原生 Reasonix 上下文。

这也解释当前现象：用户第二轮只回“可以”时，MNote payload 没有带历史 messages；它本来就依赖 Reasonix 本地 session 记住上一轮。但实际后端每轮都 fallback 出新的 Reasonix ACP session，Reasonix 当然只能把“可以”当新会话开头。

2. 当前实测问题

2026-06-09 现场证据：同一个 MNote session mnote_current_page-ai-mq6q24d5 连续三轮 run，实际 Reasonix ACP session 发生了三次变化：

轮次	用户输入	前端发送的 acpSessionId	后端实际 session.info.updated acpSessionId
1	看看你现在能不能看到有3个mcp	空	`19dbc6c6-b61e-45d1-8a28-52d0e79a02e3`
2	可以	`19dbc6c6-b61e-45d1-8a28-52d0e79a02e3`	`daa898ff-e985-49da-bbb9-ba3072f130c7`
3	帮我检查一下 LightRAG 服务的启用状态或者帮它启动起来	`daa898ff-e985-49da-bbb9-ba3072f130c7`	`ed358871-5176-4f3c-869c-91578cefa2b3`

并且第二轮 run payload 中没有 messages 字段，只有当前 message="可以"、pageContext、contextRefs、acpSessionId 等。这证明当前 Page AI 并没有 MNote 侧 transcript 注入兜底。

同一轮后端还出现大量：

WARN ACP SSE lagged: N events dropped

这说明 ACP event 转发路径有背压丢事件。当前事件路径会在 broadcast 接收后先持久化 SQLite / local journal，再写入浏览器 SSE；当 Reasonix 高频输出 thought.delta / message.delta 时，256 buffer 很容易落后。终止事件或状态同步被拖慢/丢失后，前端 assistant bubble 的 streaming=true 不能及时清掉，CSS 就继续显示 AI · 输出中。

当前 SQLite ai_runtime_runs.status 仍停在 acp_pending，但同 run 的 ai_runtime_events 已有 run.completed。这会继续污染 active-run 判断、恢复逻辑和前端状态。

3. Reasonix 官方模式摘录

3.1 ACP 能力

Reasonix 官方 src/cli/commands/acp.ts 在 initialize 中返回：

agentCapabilities: {
  loadSession: false,
  promptCapabilities: { image: false, audio: false, embeddedContext: true },
  mcpCapabilities: { http: false, sse: false },
}

含义：MNote 不能把 session/load 当成 Reasonix 的正常恢复入口。对于 Reasonix，acpSessionId 只在当前 ACP 进程内有效。

3.2 session/new

Reasonix session/new 做的事不是只分配一个 id，而是完整构造一个 session：

resolve workspace root。
build code toolset。
load MCP servers，并把 MCP tools bridge 进 tool registry。
构造 ImmutablePrefix。
创建 CacheFirstLoop。
创建 Eventizer。
保存到内存 sessions map。

这就是 Reasonix 的上下文承载点。

3.3 session/prompt

Reasonix session/prompt 通过 params.sessionId 找内存 session，然后：

for await (const ev of session.loop.step(text)) {
  for (const kev of session.eventizer.consume(ev, session.ctx)) {
    dispatchKernelEvent(server, session.id, kev);
  }
}

因此多轮对话是否连续，关键是 MNote 是否一直把后续 prompt 发给同一个 live Reasonix session。

3.4 Desktop UI 终止语义

Reasonix 官方 desktop controller 在 turn 结束时发送类似 $turn_complete 的终止事件，并在 finally 中清理 running 状态、刷新 sessions/balance。MNote Page AI 当前只靠 run.completed SSE 和前端 streaming=false 清理 UI，这条链路在 SSE lag/drop 下不够稳。

4. 目标架构

4.1 双层 session 模型

MNote 必须区分两层 session：

层	作用	是否持久	对 Reasonix 的含义
MNote Page AI session	UI 历史、SQLite/local JSONL、用户可见会话、run audit	持久	可用于恢复 UI 和构造 fallback context
Reasonix ACP session	Reasonix 内存 `CacheFirstLoop`、MCP toolset、模型上下文	进程内 live	不能假设可 load，丢失后就是 cold

新增/收口一个运行时绑定概念：

PageAiAcpLiveBinding
  mnoteSessionId
  acpRuntime = reasonix
  acpSessionId
  workspaceRoot / cwd
  rootUri / allowedRootsHash
  profile / model
  managerHandle
  status: idle | running | queued | cold | closed
  lastRunId
  lastEventSeq
  createdAt / lastPromptAt

managerHandle 只在 Rust Web 进程内存中存在；SQLite 只保存 acpSessionId 和 metadata，用于 UI 展示、审计和检测 stale，而不是承诺可恢复 Reasonix 原生上下文。

4.2 Reasonix run 启动规则

对于 acpRuntime=reasonix：

先按 mnoteSessionId + acpRuntime 查 live binding。
若 binding 存在且 status 非 closed，直接复用同一个 AcpSessionManager 和 acpSessionId 调 session/prompt。
若 binding 不存在：
- 不调用或不依赖 session/load。
- 调 session/new 创建新 Reasonix session。
- 将新 acpSessionId 写回 MNote session metadata。
- 若该 MNote session 已有历史 transcript，标记为 cold_resume，走 fallback context 注入。
当前 run 完成后，不关闭 manager，不从 live binding 中移除；只把 binding 状态改回 idle。
用户显式关闭会话、切换 workspace/root/model/profile、登出、进程退出或资源压力回收时，才关闭 binding。

这和当前 run_prompt_with_mnote_context(...).await 后直接 mgr_clone.close().await、ACP_ACTIVE_RUNS.remove(...) 的模式相反。对于 Reasonix，turn 完成不等于 Reasonix session 生命周期结束。

4.3 Hermes 与 Reasonix 分歧

不要把 Hermes VSCode 的 session/load 结论机械套到 Reasonix：

Hermes adapter 如果声明支持 loadSession，MNote 应继续优先 session/load。
Reasonix 官方明确 loadSession=false，MNote 应使用 live binding + cold resume fallback。
UI 上要能显示当前会话是否是 native-live、cold-resumed、new-session，避免用户误以为 Reasonix 原生上下文仍在。

4.4 Hermes Desktop / Web UI 对照

Hermes 参考实现反而证明：Hermes 与 Reasonix 的上下文工程必须分开设计，只能共享外层 MNote envelope / audit / UI projection。

Hermes 官方公开文档与本地参考包需要分层理解：

ACP adapter 的 session/load / session/new / session/prompt 属于 adapter 会话合同；host 不能只把旧 sessionId 写回内存后直接 prompt。
官方 user guide 明确提醒：ACP session 列表、load、resume、fork 的范围以当前运行的 ACP server process 为准。也就是说，MNote 不能把 Hermes session/load 永久等同为跨进程必然成功。
Hermes VSCode 插件的 SessionManager.ensureSession() 说明了 host 侧正确动作：已有 storedSessionId 时必须先调用 ACP session/load，让 adapter 注册会话；session/load 返回 null 或失败后才能 session/new。插件注释还指出，跳过 session/load 会形成 phantom session。
Hermes Web / dashboard 路径体现的是 server / DB 级会话资产：state.db 中有 sessions、messages、conversation chain、search/detail/export 这类持久查询能力。这是 MNote 做会话管理和 history dashboard 的参考，但不能直接推导为 ACP adapter 任意时刻都能无损 replay。
本地历史包 hermes-web-ui-0.5.18 的 Socket.IO server 体现了 Web/API chat 路径：resumeSession() 先找 live sessionMap，找不到再从 DB loadSessionStateFromDb() 读取 messages、compression snapshot 和 token 统计。这条路径不是 ACP session/load，应放在 Track W。

因此 Hermes 的正确集成不是“无条件相信 session id 可恢复”，而是：按 runtime capability 探测 -> 有 stored acpSessionId 就先 session/load -> load 成功才认为底层 adapter 连续 -> load 失败进入 Hermes cold/new；若 adapter replay 了 history，MNote 必须消费、去重、排序。

Reasonix 官方 desktop/ACP 与这两者都不同：Reasonix ACP 声明 loadSession=false，上下文在当前进程内的 CacheFirstLoop 上。MNote 如果每轮关闭 AcpSessionManager，就等于每轮丢掉 Reasonix 原生上下文。

因此 MNote 后续应冻结三套 runtime policy：

Runtime	上下文主承载	恢复策略	MNote 责任
Hermes ACP	adapter session；若 adapter 支持并成功 `session/load`，才视为底层连续	stored ACP session id -> `session/load` -> 按 load 结果和 replay evidence 决定连续性 -> `session/prompt`	保存/加载 acpSessionId；消费可能出现的 replay；处理 load 失败 fallback
Hermes Web/API Chat	Hermes server transcript + DB state	DB messages / compression snapshot -> resume socket/run	管理 messages、summary、run status、queue
Reasonix ACP	live `CacheFirstLoop` in ACP process	live binding 复用；丢失后 cold resume packet	维持 live binding，不假装 session/load 可用

共享部分只包括：

MNote Page AI session / run id / trace id。
agentRunEnvelope、target package、allowed roots、capability policy。
SQLite/local JSONL audit。
前端 projection：assistant final、thought、tool、plan、permission、citation、run status。

不共享的部分是：底层 agent session 生命周期、上下文恢复机制、是否重发 transcript、是否允许 session/load。

5. Context 工程设计

5.1 native-live 路径

当 Reasonix live binding 存在时：

MNote 每轮 prompt 只发送当前用户输入、当前页面/selection/target package、allowed roots、MNote capability envelope。
不重发完整 transcript，避免破坏 Reasonix 自己的 prefix/cache/memory 设计。
MNote 仍持久化 user/assistant/tool events，用于 UI 历史、审计、fallback 和 reload。

5.2 cold resume fallback

当 MNote Page AI session 有历史，但 Reasonix live binding 丢失时：

创建新的 Reasonix ACP session。
将 MNote 最近 N 轮 transcript、上一次 summary、当前 page context、allowed roots 组成一个明确的 MNote cold resume context packet。
作为 embedded/context prompt 的前置内容发给 Reasonix。
前端显示轻量状态：Reasonix 原生会话已重建，已用 MNote 历史摘要恢复上下文。
该状态进入 run audit，不能静默伪装成原生连续会话。

fallback packet 必须控制大小：

优先 summary。
再补最近 3-5 轮 user/assistant final。
tool raw output 只放 tool name、result summary、changed files、citations，不放大段 stdout。
thought/reasoning 默认不进入 fallback。

5.3 用户短回复消歧

对“可以”“继续”“按刚才说的”“同意”这类短回复：

native-live：完全交给 Reasonix 原生上下文。
cold-resumed：fallback packet 必须包含上一轮 user intent 和 assistant proposal。
new-session：前端或后端应提示“当前 Reasonix 原生上下文不可用，短回复缺少指代对象”，不要让模型编造。

6. Response / UI 状态设计

6.1 事件分类

Reasonix event 到 MNote UI 的分类应对齐官方 desktop 的 projection 思路：

Reasonix / ACP 事件	MNote 展示
message/model delta	当前 assistant streaming bubble
model final / run completed	关闭 streaming bubble，写入 final
thought delta	折叠的“思考过程”，不混入 final answer
tool intent/result	tool card，带 status、locations、citations、audit id
plan/todo	plan/status panel，不当作 assistant 正文
turn complete	解除 busy / 输出中 / active run snapshot

6.2 终止事件不可丢

run.completed / run.failed / run.aborted / synthetic turn.complete 属于不可丢事件。

即使中间 thought.delta 或 message.delta 被限流/合并，终止事件也必须送达浏览器并持久化。前端 输出中 只能由 active run status 和 streaming flag 共同决定：

收到 terminal event：强制 streaming=false。
SSE 断开但后端 run 已 terminal：/active-run 或 /runs/{id}/events reconciliation 必须合成 terminal event。
SQLite run status terminal 时，active-run 不得再返回该 run。

6.3 状态持久化

当前 ai_runtime_events 已记录 run.completed，但 ai_runtime_runs.status 仍停在 acp_pending，这是 UI 卡 “输出中” 和 active-run 误判的根因之一。

后续必须保证：

register_runtime_from_create_run_response 初始化 run 为 running 或 queued，不要长期停在 acp_pending。
persist_acp_runtime_event(run.completed) 同步更新 SQLite ai_runtime_runs.status=completed。
persist_acp_runtime_event(run.failed) 同步更新 failed。
persist_acp_runtime_event(run.aborted) 同步更新 aborted。
内存 registry 与 SQLite status 不一致时，以 terminal event journal 为 reconciliation truth，补写 run status。

7. SSE / 背压设计

当前 broadcast consumer 同时承担“持久化事件”和“转发浏览器 SSE”，导致高频 Reasonix 输出时 ACP SSE lagged。

目标拆分：

Reasonix ACP event
  -> in-memory run event bus
     -> browser SSE fanout, low latency, terminal priority
     -> persistence worker, async/batched, can lag but不能阻塞 SSE
     -> run status reconciler, terminal immediate

规则：

thought.delta 可合并、降采样或只持久化部分摘要。
message.delta 可按时间片或 token chunk 合并，保证顺序。
tool events、permission events、session.info、plan、terminal events 不降采样。
terminal event 使用独立 high-priority path；即使普通 delta buffer 满，也不能 drop。
persistence worker 失败只产生 audit warning，不应阻塞浏览器终止状态。

8. 后续执行总图

本设计后续不应拆成“先随手修 Reasonix，再顺手修 Hermes”。正确顺序是先冻结共享合同，再分别推进 Reasonix 和 Hermes 的 runtime policy，最后统一 UI projection 与 smoke。

Phase 0: Runtime policy / event store / status reconciliation 共享底座
  -> Track R: Reasonix ACP live binding + cold resume
  -> Track H: Hermes ACP session/load + replay 消费
  -> Track W: Hermes Web/API chat transcript resume 兼容
  -> Track U: Page AI UI / history / debug / smoke 矩阵

8.1 共享底座：Runtime policy

先在 MNote 侧抽象出明确的 runtime policy，而不是在 hermes_client.rs 里靠 if acpRuntime == "reasonix" 散落判断。

建议合同：

AgentRuntimePolicy
  runtime: hermes | reasonix | chat_only | api_chat
  contextCarrier:
    - adapter_loadable_session
    - adapter_live_loop
    - server_transcript
  supportsSessionLoad: bool
  supportsHistoryReplay: bool
  supportsForkListResume: bool
  promptContinuity:
    - native_live_required
    - load_then_prompt
    - transcript_rebuild
  terminalSemantics:
    - run.completed
    - run.failed
    - run.aborted
    - synthetic.turn_complete

MNote Page AI 每次 run 必须先解析 policy，再决定：

是否允许 session/load。
是否应复用 live manager。
是否需要从 SQLite/local JSONL 构造 cold resume packet。
是否要接收 adapter replay history。
terminal event 如何更新 SQLite run status 和前端 active-run snapshot。

8.2 共享底座：Session 身份

统一命名并避免当前概念混用：

字段	含义	生命周期
`mnoteSessionId`	MNote Page AI 会话 id，UI/history/audit 主键	持久
`mnoteRunId`	MNote 一次 run id，events/status/audit 主键	持久
`acpSessionId`	adapter 返回的底层 session id	runtime 相关
`runtimeBindingId`	MNote 内存 runtime binding id	进程内
`providerConversationId`	ChatOnly 网页 provider 远端会话 id	provider 相关

SQLite ai_runtime_runs 必须保存这些字段的快照，但只有 mnoteSessionId / mnoteRunId 是 MNote 自己的长期真相。acpSessionId 对 Hermes 是可 load 引用，对 Reasonix 只是 live binding 标识，不代表可恢复。

8.3 共享底座：Event store / terminal reconciliation

先修这个底座，否则 Reasonix 和 Hermes 都会继续被 输出中、active-run stale、历史恢复误判影响。

browser SSE 转发与 persistence 解耦：浏览器低延迟 fanout，不在同一 consumer 里同步写 SQLite。
terminal event 高优先级：run.completed / run.failed / run.aborted / synthetic turn.complete 不可被 delta 洪峰挤掉。
persist_acp_runtime_event 或独立 reconciler 在 terminal event 到达时同步更新 ai_runtime_runs.status。
/api/page-ai/sessions/{id}/active-run 不得返回已有 terminal event 的 run。
/api/page-ai/runs/{id}/events 能在 run status terminal 但缺 terminal event 时合成 reconciliation event。
前端收到 terminal / reconciliation terminal 后强制清理 streaming=true、pageAiBusy、active run snapshot。

8.4 共享底座：Response projection

所有 runtime 的可见输出投影统一，但事件来源不统一：

assistant final：只来自 message/model delta + final output。
thought：只进折叠思考过程，默认不展开，不混入 final。
tool：独立 tool card，保留 status、toolCallId、locations、citations、auditId。
plan/todo：独立 plan/status panel，不当作 assistant 正文。
permission：独立权限卡，用户决策必须回写 adapter。
citation：优先 tool 返回的 citationMarkdown / citationUrl，不让模型手拼。
busy/输出中：只由 active run + streaming bubble 共同决定，terminal 后立即清除。

9. Track R：Reasonix ACP

R0：官方模式冻结

fake Reasonix ACP fixture：initialize.loadSession=false、session/new 创建内存 loop、session/prompt 必须命中同一 session。
在测试中证明：如果 MNote 每轮新建 session，短回复“可以”无法关联上一轮；如果复用 live binding，可以关联。
在 runtime payload / SQLite detail 中暴露 reasonixSessionMode: native_live | cold_resumed | new_session。

R1：Live binding pool

AcpRuntimeManager / hermes_client 增加按 mnoteSessionId + acpRuntime 复用的 Reasonix live binding pool。
Reasonix run 完成后不关闭 manager，不移除 binding，只从 running 改 idle。
同一 binding 内 run 串行执行；第二条输入进入 binding queue，不另开 session。
Stop/abort 只取消当前 prompt，不默认销毁 binding。
切 workspace/root/model/profile/allowedRootsHash 时关闭旧 binding，并把下一轮标记为 cold/new。

R2：Cold resume fallback

从 SQLite/local JSONL 构造 bounded transcript summary。
cold resume 首轮 prompt 注入 MNote cold resume context packet。
packet 只包含 summary、最近 3-5 轮 user/assistant final、tool summary、changedFiles、citations，不包含 thought 大段文本。
UI 显示 cold resume 状态，不误导为 Reasonix 原生会话。
new_session 且用户只发短回复时提示缺上下文，不让模型编造。

R3：Reasonix 工具与 MCP 能力

确认 mnoteCapabilities / runtime manifest 进入 Reasonix 模型可见 prompt，而不只是 Rust payload。
继续保持 Reasonix 原生文件读写为 local-first 普通 Markdown 主路径；MNote 不扩写一套本地文件编辑工具。
MCP 状态作为 Reasonix 工具可见事实进入 tool/status card，而不是让模型只凭自然语言猜测。
LightRAG / MNote bridge MCP 失败时返回结构化 tool failed，不污染 assistant final。

10. Track H：Hermes ACP

H0：官方 load 合同冻结

fake Hermes ACP fixture：initialize.loadSession=true，支持 session/load；另准备一个会 replay history session/update 的变体。
MNote 启动 Hermes run 时读取 stored acpSessionId，先 session/load，再 session/prompt。
session/load 成功时，MNote 认为 adapter 当前已注册该 session；如果 adapter replay 出 user/assistant/thought/tool/plan，前端/后端必须消费并去重，不能覆盖乱序。
session/load 返回 null 或失败时，标记 hermesSessionMode=cold_resumed | new_session，不假装原生连续。

H1：Hermes session store 对齐

Hermes Web / dashboard 和部分本地服务有 state.db 级 session store。MNote 不应复制 Hermes DB，也不能把 Web DB 语义直接套到 ACP adapter；但要保存映射与审计：

SQLite ai_runtime_runs/session metadata 保存 acpSessionId、Hermes profile、cwd/rootUri、lastLoadedAt、lastReplaySeq。
MNote session detail 能展示底层 Hermes session id 和 load/replay 状态。
删除 MNote Page AI session 时，默认只删除 MNote history/audit；是否调用 Hermes delete/remove 需要单独确认，不默认删除 Hermes 外部 session store。
恢复历史会话时，区分“只恢复 MNote UI 历史”和“恢复 Hermes 底层 ACP session”。

H2：Hermes replay 消费

部分 Hermes adapter 或 Web/API resume 路径可能 replay 历史。MNote 当前已有自己的 UI history，因此只要收到 replay，就必须做去重和排序：

replay event 带 source=adapter_replay，不能当作新的当前 run 输出。
replay user/assistant/tool 与 MNote 已有消息按 content/run/time 去重。
replay tool start/completed 能恢复 tool card 状态，但不触发新的写入刷新。
replay plan/todo 恢复 plan panel，但不混入 assistant final。
replay 完成后再允许当前 prompt streaming bubble 开始。

H3：Hermes 功能面

支持 Hermes ACP session/list / session/resume / session/fork 的能力探测，先展示为 debug/高级入口，不默认替代 MNote session list。
权限请求沿 Hermes ACP decision loop 回传，不做前端假 allow。
tool locations[] 保留并能打开 MNote resource tab。
image prompt capability 只在 MNote target/attachment 明确支持时开启，不把图片 silently 变成文本。

11. Track W：Hermes Web/API Chat

Hermes 官方 Web UI 是 dashboard，不是 MNote Page AI 的直接聊天实现。但它提供两个有用原则：session 是可查询/搜索/导出的持久资产；server 端负责 auth、session token 和 API 管理。

W0：ChatOnly / API Chat 边界

ChatOnly / API Chat 继续走 provider conversation 或 MNote server transcript，不复用 ACP session/load 设计。
providerConversationId 只属于网页 provider，不与 acpSessionId 混用。
API Chat 不写网页 provider conversation binding。
MNote UI history 和 provider 远端历史删除语义分开。

W1：Session dashboard 能力

参考 Hermes Web UI 的 sessions dashboard，MNote Page AI 可补以下管理能力：

session list 展示 runtime、profile、message count、tool count、active/cold/new 状态。
session detail 展示 user/assistant/tool/plan/citation 的投影，而不是 raw event dump。
session search 支持按用户问题、assistant final、tool name、citation file 搜索。
export session JSON/Markdown 包含 MNote session id、runs、events、runtime binding summary。
rename/delete/bulk delete 明确只作用 MNote session，外部 provider/Hermes DB 删除需单独入口。

12. Track U：UI 与浏览器验证

U0：可见状态

Page AI header/debug surface 显示 runtime、profile、MNote session id、acpSessionId、sessionMode、active run status。
native_live、cold_resumed、new_session 用小状态标签表示，不占用 assistant 正文。
输出中 只在 run active 且 assistant bubble streaming 时显示；terminal 后必须消失。

U1：Smoke 脚本

task558-page-ai-reasonix-live-session-context-smoke.js：两轮 Reasonix，同一 acpSessionId，第二轮“可以”能引用上一轮。
task559-page-ai-terminal-status-reconciliation-smoke.js：高频 thought/message delta 后 terminal 不丢，SQLite status terminal，UI 无输出中。
task560-page-ai-hermes-load-replay-smoke.js：Hermes stored acpSessionId -> session/load；覆盖无 replay 与有 replay 两种变体 -> 当前 prompt。
task561-page-ai-session-dashboard-smoke.js：session list/detail/search/export/rename/delete 的最小可见验证。

U2：回归矩阵

Reasonix live binding 不破坏 Hermes session/load。
Hermes replay 不污染 Reasonix live transcript。
ChatOnly provider conversation binding 不受 ACP binding pool 影响。
local-folder allowed roots / readonly guard / agent audit 对所有 runtime 生效。
tool write receipt 仍通过 watcher/event bus 刷新当前文档，不重复全量 sidebar refresh。

13. 建议执行顺序

13.1 第一批：先修共性底座

Event store / terminal reconciliation。
Runtime policy 表和 session 身份字段梳理。
前端 输出中 / active-run 清理。

这批完成后，Reasonix 和 Hermes 后续调试不会继续被 stale status 干扰。

13.2 第二批：Reasonix 原生连续会话

Reasonix fake ACP fixture。
Reasonix live binding pool。
Reasonix 两轮“可以” browser smoke。
Cold resume fallback。

这批完成后，解决当前用户可见的上下文断裂。

13.3 第三批：Hermes 官方 load/replay

Hermes fake ACP fixture。
session/load replay 消费与去重。
Hermes session metadata/debug。
Hermes load/replay browser smoke。

这批完成后，Hermes 与 Reasonix 的上下文机制真正分开。

13.4 第四批：会话管理与其它功能

Page AI session dashboard：list/detail/search/export/rename/delete。
Tool locations/citations/open action 统一。
permission decision loop 复核。
model/profile/skills/MCP 状态面板对齐。

14. 验收矩阵

14.1 单元 / 集成测试

fake Reasonix ACP：loadSession=false，同一 MNote session 连续两轮只调用一次 session/new，第二轮仍用同一 acpSessionId。
fake Reasonix ACP：第二轮输入“可以”，adapter 可读到上一轮 loop 历史，回答能引用上一轮提议。
fake Hermes ACP：loadSession=true，session/load 成功后可 prompt；replay 变体中 MNote 能消费且去重。
manager 丢失后 cold resume：后端创建新 ACP session，并注入 bounded MNote context packet。
SQLite status reconciliation：有 run.completed event 后，ai_runtime_runs.status 必为 completed。
高频 delta：3000 条 thought.delta + terminal，不丢 terminal，前端最终无 data-page-ai-streaming="true"。

14.2 浏览器 smoke

Reasonix：打开 Page AI，发送“我下一条只说可以，你要根据这条消息继续检查 LightRAG 服务”。
Reasonix：第二轮发送“可以”。
Reasonix：捕获 /api/hermes/client/runs 和 session.info.updated，两轮实际 acpSessionId 相同。
Reasonix：第二轮可见回答能理解“可以”指上一轮提议，不要求用户重新说明任务。
Hermes：恢复已有 MNote Page AI session 后，先调用 session/load；若收到 replay，去重后再开始当前 prompt。
通用：回答完成后页面不显示 AI · 输出中。
通用：SQLite ai_runtime_runs 对所有 terminal run 都进入 terminal status。

14.3 回归边界

Hermes runtime 仍可走 session/load，不被 Reasonix special case 破坏。
Reasonix runtime 不调用或不依赖 session/load。
ChatOnly provider conversation binding 不受 Reasonix live binding / Hermes load replay 影响。
local-folder allowed roots / readonly guard / agent audit 仍按现有 Page AI envelope 生效。
Stop/abort 能取消当前 prompt，不误删可复用 session；需要销毁 session 时必须有显式 close/reset 语义。

15. 不做事项

不让 MNote 为 Reasonix 重写一套长期 agent memory。
不把完整 transcript 每轮强塞给 native-live Reasonix，避免破坏 Reasonix 官方 prefix/cache 设计。
不把 mnote.doc.* 工具扩成 local-first 普通 Markdown 主路径。
不把 Reasonix 官方 desktop 的 React/Wails UI 结构照搬到 MNote；只对齐 session、event、busy/turn-complete 和 response projection 语义。
不继续把 session/load 失败当成普通 fallback 成功；对 Reasonix 这是上下文断裂事件，必须可见、可审计。

16. 当前建议优先级

优先做 13.1 第一批：共性底座，再做 13.2 Reasonix 原生连续会话。

原因：

共性底座直接修复 ACP SSE lagged、SQLite status stale、active-run stale 和 输出中 卡住；不先修它，Reasonix/Hermes 的会话验证会继续被假状态干扰。
Reasonix live binding 直接修复“回复可以不理解上一轮”的根因。
Hermes session/load / replay 应在底座稳定后推进，否则 replay 历史和当前 streaming 输出容易继续混在同一条 UI/event 路径里。
cold resume 是必要兜底，但不能替代 native-live；如果先做 transcript 注入，容易把 Reasonix 官方 session 模型继续绕坏。

17. 文件级实施映射

本节用于把上面的架构拆到真实 owner，避免后续实现继续在单个 route 中临时判断。

17.1 后端 owner

文件	当前职责	后续改动边界
`rust/crates/mnote-web/src/routes/hermes_client.rs`	Page AI run/create/stream、ACP active run、SQLite runtime event 持久化、active-run API	第一批只改 terminal reconciliation、active-run 过滤、runtime policy 分派入口；不要把 Reasonix/Hermes 细节继续散落到所有分支
`rust/crates/mnote-web/src/acp_session_manager.rs`	ACP `session/new`、`session/load`、`session/prompt`、event mapping	增加 capability-aware `ensure_session_with_policy` 或等价接口；Reasonix policy 下不得尝试 `session/load`
`rust/crates/mnote-web/src/acp_runtime.rs`	runtime config、process switch、active client 生命周期	当前只有一个 active runtime process；若支持多 live binding，需要明确是否仍共享同一 process，还是按 runtime/profile/workspace 拆 manager pool
`rust/crates/mnote-web/src/acp_bridge.rs`	ACP event -> SSE event projection	补 terminal priority、thought/message delta 限流策略、tool/permission/plan 分类，避免 UI 和持久化各自猜事件语义
`rust/crates/mnote-web/src/routes/mod.rs`	Page AI route 注册	只在新增 debug/session dashboard API 时扩展，不放业务逻辑

17.2 前端 owner

文件	当前职责	后续改动边界
`rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js`	Page AI 输入、run streaming、event 消费、active run snapshot	terminal event 后强制清理 streaming/busy；显示 sessionMode/debug；不要把 thought/tool/plan 拼进 final
`rust/crates/mnote-web/browser/sidebar-page-ai-session-runtime.js`	session list/history/active-run 恢复	active-run API 返回 stale 时要忽略 terminal run；后续接 session dashboard/detail/search/export
`rust/crates/mnote-web/browser/sidebar-page-ai-render-runtime.js`	消息和 tool card 渲染	`native_live/cold_resumed/new_session` 用状态标签，不占 assistant 正文；输出中只从 streaming attr 得出
`rust/crates/mnote-web/src/ssr/styles.rs`	`AI · 输出中` 等可见样式	只保留样式，不承担状态判断；状态必须来自 JS runtime 和后端 terminal truth

17.3 测试 / fixture owner

文件或建议文件	目的
`rust/crates/mnote-web/src/acp_session_manager.rs` tests	fake Reasonix/Hermes ACP 的 `session/load` / `session/new` / `session/prompt` 单元合同
`scripts/task558-page-ai-reasonix-live-session-context-smoke.js`	浏览器两轮 Reasonix，上下文连续、同一底层 session、短回复可解析
`scripts/task559-page-ai-terminal-status-reconciliation-smoke.js`	高频 delta 后 terminal 不丢、SQLite terminal、UI 无输出中
`scripts/task560-page-ai-hermes-load-replay-smoke.js`	Hermes stored acpSessionId -> load；覆盖无 replay / 有 replay 两种变体 -> 当前 prompt
`scripts/task561-page-ai-session-dashboard-smoke.js`	session list/detail/search/export/rename/delete 可见闭环

18. Runtime 状态机与不变量

18.1 Run 状态机

created
  -> queued
  -> running
  -> tool_calling
  -> running
  -> completed | failed | aborted

terminal = completed | failed | aborted

不变量：

ai_runtime_events 中出现 terminal event 后，ai_runtime_runs.status 必须在同一事务或 reconciliation pass 中进入 terminal。
/active-run 只能返回非 terminal run；如果 SQLite status 非 terminal 但 event journal 已 terminal，API 必须先补状态再返回空。
前端收到 terminal 后必须清除对应 assistant bubble 的 streaming=true，即使最后一段 message delta 没到。
acp_pending 只能是创建到 SSE 建立前的短暂状态，不得作为完成后残留状态。

18.2 Reasonix binding 状态机

19. 完成记录（2026-06-10）

本稿已按 13.1 到 13.4 的顺序完成可执行闭环，代码与验证证据如下：

第一批共性底座：已实现 runtime policy、session 身份字段、terminal reconciliation、active-run 终态过滤、/runs/{id}/events synthetic terminal、前端 streaming / 输出中 强制清理。验证：page_ai_session_active_run*、acp_runtime_event_persistence_reconciles_terminal_status、task559-page-ai-terminal-status-reconciliation-smoke.js。
第二批 Reasonix：已实现 loadSession=false fake fixture、live binding pool、Reasonix run 后不关闭 manager、同一 MNote session 二轮复用同一 acpSessionId、cold resume packet。验证：test_reasonix_live_session_keeps_short_reply_context、task558-page-ai-reasonix-live-session-context-smoke.js、page-ai-browser-verify Reasonix clean reply。
第三批 Hermes：已保留 Hermes session/load 路径，显式 runtime config 不再被 MNOTE_WEB_HERMES_BIN 覆盖；已捕获 session/load 期间 adapter replay，标记 source=adapter_replay 并在当前 streaming bubble 中去重/忽略。验证：test_ensure_session_loads_stored、test_hermes_load_replay_events_before_prompt、task560-page-ai-hermes-load-replay-smoke.js 覆盖 no replay / replay。
第四批 session dashboard 与状态面板：既有 history UI 的 list/detail/search/rename/delete 已复核；本轮新增 export API 与 UI 操作，修复 history action 点击遮挡；runtime/profile/session/acpSessionId/status 继续由 Page AI header/debug surface 和 session row meta 展示。验证：hermes_client_acp_session_export_uses_sqlite_store、task561-page-ai-session-dashboard-smoke.js。
ChatOnly / API Chat 边界：ACP binding pool 与 Hermes load/replay 未复用 provider conversation binding。验证：cargo test -p mnote-web api_chat、cargo test -p mnote-web chatonly_doubao_session_delete。

逐项归档说明：

session/list / session/resume / session/fork 的 Hermes ACP 高级入口保持为 debug/future 能力探测，不替代 MNote session list；本轮完成的是 stored acpSessionId -> session/load -> prompt 的官方必需路径。
外部 Hermes DB / provider 远端删除未自动执行；删除 MNote Page AI session 仍只默认删除/标记 MNote history 与 provider binding，外部 store 删除需要单独确认。
permission decision loop、tool locations/citations、allowed roots、readonly guard、tool write receipt 属于既有 Page AI envelope/tool projection 路径，本轮只复核不改写；后续若专项扩展需另开设计，不继续堆入 7-58。
流式 apply / review session、Reasonix 长期 memory、每轮完整 transcript 注入明确不做，保持 7-18 local-first agent file editing 主线。

状态：DONE。本文件可移入 design/07-ai/done/。

missing
  -> new_session
  -> native_live.idle
  -> native_live.running
  -> native_live.idle
  -> cold_required | closed

不变量：

同一 mnoteSessionId + runtime + profile + workspaceKey + allowedRootsHash 同时最多一个 running prompt。
prompt 完成只释放 run，不销毁 Reasonix ACP session manager。
abort 只取消当前 prompt；reset/close 才销毁 binding。
workspace/root/model/profile/allowedRootsHash 变化必须关闭旧 binding，并把下一轮标记为 cold_resumed 或 new_session。

18.3 Hermes ACP 状态机

missing
  -> has_stored_acp_session_id
  -> load_attempted
  -> adapter_loaded | load_failed
  -> prompt_running
  -> completed | failed | aborted

不变量：

有 stored acpSessionId 时必须先 session/load，不能跳过 load 直接 prompt。
session/load 成功只表示 adapter 当前承认该 session；是否 replay history 由事件流证据确认。
replay event 必须标记 source=adapter_replay 或等价来源，不能当作当前 run 的新输出。
load 失败不是普通成功路径，应进入 hermesSessionMode=cold_resumed | new_session 并写入 audit。

18.4 Hermes Web/API Chat 状态机

providerConversationId | serverSessionId
  -> load server transcript / compression snapshot
  -> append current user message
  -> stream provider response
  -> flush messages/status

不变量：

Web/API Chat 不复用 ACP session/load。
providerConversationId 不得写入 acpSessionId 字段。
删除 MNote UI session 不默认删除 provider 或 Hermes 官方 DB 中的会话资产。

19. 风险登记

风险	影响	控制方式
把 Reasonix 做成 transcript replay	破坏 Reasonix `CacheFirstLoop` / prefix / cache 语义，短期看似恢复，长期上下文和成本异常	native-live 优先；cold resume 必须显式标记且 bounded
把 Hermes `session/load` 写成必然成功	进程重启、adapter 清理或 profile 变化后产生 phantom continuity	capability + load result + replay evidence 三重判断
terminal event 与 delta 共用可丢 buffer	UI 卡 `输出中`、active-run stale、历史恢复错判	terminal high-priority path + status reconciler
replay history 与 MNote history 重复	用户看到重复消息、tool card 重复执行感	replay source 标记、content/run/time 去重、replay 完成后再开当前 bubble
多 runtime 共用一个 active process manager	切 profile/runtime 时杀掉别的 live session	明确 process pool 设计；Reasonix binding 与 Hermes load 不共用生命周期假设
删除语义混淆	删除 MNote session 时误删 Hermes DB 或 provider 远端历史	UI 和 API 分开 MNote-only delete 与 external delete
代码中已有未完成 scaffold	后续实现误以为 live binding 已完成，或产生重复 static / 不可编译	第一批实现前先跑 `cargo test -p mnote-web`，清点当前未提交改动归属，不回滚用户改动

20. 第一批落地切片

第一批只处理共享底座，不碰 Reasonix live binding 的完整生命周期，也不做 Hermes replay UI。目标是让 run 状态可信。

20.1 后端切片 A：terminal reconciliation

输入：任意 runtime 的 run.completed / run.failed / run.aborted event。
输出：ai_runtime_runs.status 同步进入 terminal，status_reason 写入 terminal event 名称或 error code。
改动点：persist_acp_runtime_event、update_runtime_by_run_id、/active-run 查询路径。
验收：构造 ai_runtime_events 已 terminal 但 ai_runtime_runs.status=acp_pending 的 fixture，active-run 返回空并补写 status。

20.2 后端切片 B：SSE terminal priority

输入：高频 thought.delta / message.delta + terminal。
输出：普通 delta 可合并或丢摘要，terminal 必达浏览器和 event store。
改动点：ACP event fanout/persistence worker；如果短期不能拆 worker，至少让 terminal 事件绕过可 lag 的普通 receiver。
验收：3000 条 delta 后仍收到 terminal，日志不再出现 terminal 丢失导致的 stale run。

20.3 前端切片 C：输出中清理

输入：terminal SSE、reconciliation terminal、active-run 空结果。
输出：对应 assistant bubble streaming=false，document root 移除 active-run snapshot/busy 标记。
改动点：sidebar-page-ai-runtime.js、sidebar-page-ai-session-runtime.js。
验收：回答完成后 DOM 不存在 data-page-ai-streaming="true"，.wolai-page-ai-message-role::after 不再显示 AI · 输出中。

20.4 文档归档条件

本设计留在 process/，直到至少完成：

第一批共性底座 smoke 通过。
Reasonix 两轮短回复 smoke 通过。
Hermes load 与 replay 变体最小 smoke 通过。
Page AI session dashboard 的范围已拆成新设计或在本设计中完成验收。

满足后移动到 design/07-ai/done/；若后续另起 v2 覆盖本稿，则本稿移动到 design/old/process/ 并标记 [recycle]。

42 KiB Raw Blame History Unescape Escape

7-58 Page AI Reasonix / Hermes 官方会话与响应对齐 v1

1. 第一结论

2. 当前实测问题

3. Reasonix 官方模式摘录

3.1 ACP 能力

3.2 session/new

3.3 session/prompt

3.4 Desktop UI 终止语义

4. 目标架构

4.1 双层 session 模型

4.2 Reasonix run 启动规则

4.3 Hermes 与 Reasonix 分歧

4.4 Hermes Desktop / Web UI 对照

5. Context 工程设计

5.1 native-live 路径

5.2 cold resume fallback

5.3 用户短回复消歧

6. Response / UI 状态设计

6.1 事件分类

6.2 终止事件不可丢

6.3 状态持久化

7. SSE / 背压设计

8. 后续执行总图

8.1 共享底座：Runtime policy

8.2 共享底座：Session 身份

8.3 共享底座：Event store / terminal reconciliation

8.4 共享底座：Response projection

9. Track R：Reasonix ACP

R0：官方模式冻结

R1：Live binding pool

R2：Cold resume fallback

R3：Reasonix 工具与 MCP 能力

10. Track H：Hermes ACP

H0：官方 load 合同冻结

H1：Hermes session store 对齐

H2：Hermes replay 消费

H3：Hermes 功能面

11. Track W：Hermes Web/API Chat

W0：ChatOnly / API Chat 边界

W1：Session dashboard 能力

12. Track U：UI 与浏览器验证

U0：可见状态

U1：Smoke 脚本

U2：回归矩阵

13. 建议执行顺序

13.1 第一批：先修共性底座

13.2 第二批：Reasonix 原生连续会话

13.3 第三批：Hermes 官方 load/replay

13.4 第四批：会话管理与其它功能

14. 验收矩阵

14.1 单元 / 集成测试

14.2 浏览器 smoke

14.3 回归边界

15. 不做事项

16. 当前建议优先级

17. 文件级实施映射

17.1 后端 owner

17.2 前端 owner

17.3 测试 / fixture owner

18. Runtime 状态机与不变量

18.1 Run 状态机

18.2 Reasonix binding 状态机

19. 完成记录（2026-06-10）

18.3 Hermes ACP 状态机

18.4 Hermes Web/API Chat 状态机

19. 风险登记

20. 第一批落地切片

20.1 后端切片 A：terminal reconciliation

20.2 后端切片 B：SSE terminal priority

20.3 前端切片 C：输出中清理

20.4 文档归档条件

42 KiB

Raw Blame History