chore: 保存当前架构收口与 bug 修复快照

归档本轮 P0/P1 bug 修复、设计审查迁移、AI selection scope 收口与 stream contract 调整，并保留当前 05 主线迁移起点。
2026-05-18 17:01:35 +08:00
parent 61ee4a38a2
commit a2cb1338c8
953 changed files with 14383 additions and 211845 deletions
@@ -0,0 +1,47 @@
+# 3-16 [done][bug] tree realtime WS 主链口径与前端 SSE 实现不一致 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web`
+
+## 1. 问题定义
+
+当前架构口径已描述 `/api/realtime/ws` 是树实时 push 主链，`/api/tree/events` 是 SSE fallback。但前端真实代码仍只发现 `EventSource('/api/tree/events')` 消费链路，没有发现 `/api/realtime/ws` 或 `new WebSocket` 主 consumer。
+
+## 2. 证据
+
+- [routes/mod.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/mod.rs:170) 注册 `/api/tree/events`。
+- [routes/mod.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/mod.rs:172) 注册 `/api/realtime/ws`。
+- [use-sidebar-tree-stream.ts](/mnt/Data1T/mnote/wolai-frontend/src/lib/tree-stream/use-sidebar-tree-stream.ts:137) 实际创建 `EventSource`。
+- [protocol.ts](/mnt/Data1T/mnote/wolai-frontend/src/lib/tree-stream/protocol.ts:72) 固定构造 `/api/tree/events`。
+
+## 3. 影响
+
+- 架构文档与前端运行路径不一致。
+- live cache 收口时无法判断真实主链。
+- 回归测试如果只检查后端 WS route 存在，会误判前端已切换完成。
+
+## 4. 建议修复
+
+- 明确当前阶段：要么更新架构口径为“前端仍 SSE，WS route 已准备”，要么实现前端 WS consumer。
+- 增加浏览器 smoke，断言网络中实际使用的是 WS 主链还是 SSE fallback。
+- 文档与测试必须以真实前端消费路径为准。
+
+## 5. 修复
+
+已修复 / 已收口：
+
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7127) Rust SSR 主壳内置 `startWithWebSocket`，实际创建 `/api/realtime/ws` WebSocket consumer。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7176) WebSocket 断开后调用 `startWithSseFallback`，`/api/tree/events` 明确成为 fallback。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7301) SSR tree live bootstrap 默认 `transport` 已是 `convex-command-log-ws`，不再默认走 SSE。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7593) 增强回归测试，断言 controller 同时包含 WS 主链与 SSE fallback。
+
+## 6. 验证
+
+```bash
+cargo test --manifest-path rust/Cargo.toml -p mnote-web tree_live_controller_marks_transport_and_closes_source_on_pagehide -- --nocapture
+```
+
+结果：1 个测试通过。
@@ -0,0 +1,45 @@
+# 3-17 [done][bug] SSE push 模式跳过 polling safety net v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web`
+
+## 1. 问题定义
+
+SSE route 注释和架构口径暗示 polling 可作为 safety net，但实现中只要 `stream_delta_rx.is_some()`，循环就进入 push/heartbeat 分支并跳过 polling。
+
+## 2. 证据
+
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:35) 附近说明 SSE 事件路径。
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:116) 附近在 `stream_delta_rx` 存在时走 heartbeat / push 分支。
+
+## 3. 影响
+
+- broadcast 丢失、进程重启、跨进程实例不共享 channel 时，SSE 连接可能无法靠 Convex bridgeLogs 追上。
+- fallback 名义存在，但实际恢复能力不足。
+- 客户端可能长期停在旧 snapshot。
+
+## 4. 建议修复
+
+- push 模式也应按 cursor 周期性检查 bridgeLogs，或在 heartbeat 周期中合并轻量 polling。
+- 增加测试：模拟 `stream_delta_rx` 无消息但 bridgeLogs 有新事件，SSE 应产出 delta/resync。
+- 明确 `pollMs` 与 push channel 同时存在时的优先级。
+
+## 5. 修复
+
+已修复：
+
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:117) push 模式在 broadcast 静默时不再只发 heartbeat，而是按 `pollMs/maxPolls` 执行 bridgeLogs polling safety net。
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:135) polling 检测到 `Delta` 时构建标准 stream delta payload 并发送 `delta`。
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:157) polling 检测到 `Resync` 时回读 snapshot 并发送 `resync`。
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:402) 增加回归测试，断言 push 模式下 `maxPolls=1` 会触发 safety-net polling 并正常结束。
+
+## 6. 验证
+
+```bash
+cargo test --manifest-path rust/Cargo.toml -p mnote-web routes::sse::tests -- --nocapture
+```
+
+结果：5 个 SSE route 测试通过。
@@ -0,0 +1,47 @@
+# 3-18 [done][bug] WS 与 SSE delta 载荷合同分裂 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web`
+
+## 1. 问题定义
+
+SSE polling 可以从 bridgeLogs / domainEvents 解析 `streamDelta` 并附带 snapshot / resync 信息；WS 当前广播的是 `command_committed` 外壳，两者不是同一套 delta 合同。
+
+## 2. 证据
+
+- [stream_support.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/stream_support.rs:577) 附近解析 `streamDelta`。
+- [command_support.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/command_support.rs:102) 附近广播 command committed 事件。
+- [ws.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/ws.rs:40) 处理 WS socket。
+
+## 3. 影响
+
+- 同一 tree command 在 WS 与 SSE 下可能给客户端不同结构。
+- 前端 live cache 需要维护两套 reducer，增加状态分裂风险。
+- WS 切主时，SSE 已覆盖的 snapshot/resync 语义可能丢失。
+
+## 4. 建议修复
+
+- 抽出统一的 tree realtime envelope，WS 与 SSE 只作为 transport。
+- 对同一命令分别跑 WS / SSE 合同测试，断言事件 kind、cursor、snapshot、resync 语义一致。
+- 前端 reducer 只消费统一 envelope，不感知 transport 差异。
+
+## 5. 修复
+
+已修复：
+
+- [stream_support.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/stream_support.rs:577) 新增 `build_stream_push_delta_hint`，统一 command committed broadcast 的 tree realtime hint envelope。
+- [sse.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/sse.rs:97) SSE push 分支改为复用统一 hint envelope。
+- [ws.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/ws.rs:43) WS broadcast 分支改为发送同一 hint envelope，不再输出嵌套 `data.kind=command_committed` 的专有结构。
+- [ws.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/ws.rs:190) 增加 WS delta serializer 合同测试，断言输出为 `kind=delta`、`hint=command_committed`，并且没有额外 `data` 外壳。
+
+## 6. 验证
+
+```bash
+cargo test --manifest-path rust/Cargo.toml -p mnote-web routes::ws::tests -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web routes::sse::tests -- --nocapture
+```
+
+结果：WS 3 个测试通过，SSE 5 个测试通过。
@@ -0,0 +1,49 @@
+# 3-19 [done][bug] Reasonix ACP wrapper 调 mnote tool 缺少身份与幂等字段 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web`
+
+## 1. 问题定义
+
+Reasonix ACP wrapper 调用 mnote tool 时只发送 `toolName`、`args`、`workspaceId`，没有传递 `actorId`、`sessionId`、`runId`、`toolCallId`、`traceId`、`dryRun`、`idempotencyKey` 等工具合同字段。
+
+## 2. 证据
+
+- [reasonix-acp-wrapper.mjs](/mnt/Data1T/mnote/scripts/reasonix-acp-wrapper.mjs:230) 附近构造 `callMnoteTool` 请求体。
+
+## 3. 影响
+
+- Rust tool executor 难以稳定进行鉴权、审计、追踪和幂等。
+- 写工具可能被拒绝，或在缺少幂等键时产生重复写入风险。
+- Reasonix 与 Hermes 对同一 tool 的调用合同不一致。
+
+## 4. 建议修复
+
+- wrapper 必须从 ACP run/session 中透传 actor、session、run、toolCall、trace、dryRun、idempotency 字段。
+- 写工具缺失必要字段时应 fail fast。
+- 增加 Reasonix 端到端 smoke，断言请求字段完整。
+
+## 5. 修复
+
+已修复：
+
+- [reasonix-acp-wrapper.mjs](/mnt/Data1T/mnote/scripts/reasonix-acp-wrapper.mjs:34) 新增 `buildMnoteToolPayload`，统一构造 mnote tool 请求体。
+- [reasonix-acp-wrapper.mjs](/mnt/Data1T/mnote/scripts/reasonix-acp-wrapper.mjs:43) tool payload 现在包含 `actorId`、`sessionId`、`runId`、`toolCallId`、`traceId`、`dryRun`、`idempotencyKey`、`workspaceId`、`documentId`。
+- [reasonix-acp-wrapper.mjs](/mnt/Data1T/mnote/scripts/reasonix-acp-wrapper.mjs:303) HTTP 请求头同步携带 `x-mnote-actor-id` 与 `x-mnote-workspace-id`。
+- [reasonix-acp-wrapper.mjs](/mnt/Data1T/mnote/scripts/reasonix-acp-wrapper.mjs:379) ACP `session/prompt` 期间通过 `AsyncLocalStorage` 保存 mnote tool context，tool 调用继承 run/session/actor/trace。
+- [acp_types.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_types.rs:163) `SessionPromptParams` 扩展可选 mnote 上下文字段。
+- [acp_session_manager.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_session_manager.rs:193) 增加 `run_prompt_with_mnote_context`。
+- [hermes_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes_client.rs:754) ACP Reasonix prompt 启动时透传 mnote session/run/actor/trace/workspace/document 上下文。
+
+## 6. 验证
+
+```bash
+node --check scripts/reasonix-acp-wrapper.mjs
+MNOTE_REASONIX_ACP_SELFTEST=1 node scripts/reasonix-acp-wrapper.mjs
+cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_session_manager -- --nocapture
+```
+
+结果：JS 语法检查通过，wrapper selftest 通过，ACP session manager 5 个测试通过。
@@ -0,0 +1,40 @@
+# 3-20 [done][bug] ACP incoming request 只记录日志不响应 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web`
+
+## 1. 问题定义
+
+ACP client 收到 `session/request_permission` 等 incoming request 时当前只记录日志，没有返回协议响应。
+
+## 2. 证据
+
+- [acp_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_client.rs:347) 附近处理 incoming request。
+
+## 3. 影响
+
+- ACP agent 侧可能等待到超时。
+- 权限请求无法进入用户确认或自动拒绝流程。
+- run 状态可能卡在进行中，SSE 输出也无法表达真实阻塞原因。
+
+## 4. 建议修复
+
+- 为已知 request type 实现明确响应：允许、拒绝或要求人工确认。
+- 未支持的 request type 也应返回结构化 error，而不是只日志。
+- 增加 ACP request/response 协议测试。
+
+## 5. 修复
+
+- [acp_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_client.rs:157) 将 ACP 子进程 stdin writer 作为共享 `Arc<Mutex<BufWriter<_>>>` 传入后台 reader loop。
+- [acp_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_client.rs:335) 对带 `id + method` 的 incoming request 写回 JSON-RPC error 响应，当前无权限确认 UI 时明确拒绝，避免 agent 等待超时。
+- [acp_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_client.rs:551) 增加 mock ACP server 测试，覆盖 `session/request_permission` 主动请求必须收到响应。
+
+## 6. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web test_incoming_permission_request_gets_response -- --nocapture`
+  - 结果：1 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_client -- --nocapture`
+  - 结果：6 passed
@@ -0,0 +1,38 @@
+# 3-21 [done][bug] ACP run payload 被第一次 stream_events 消费后移除 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web`
+
+## 1. 问题定义
+
+ACP run 的 payload 在 `stream_events` 路径被消费后从内存表移除。刷新页面、多个 SSE 订阅、断线重连时，后续订阅可能无法再取到同一个 run 的 payload。
+
+## 2. 证据
+
+- [hermes_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes_client.rs:789) 进入 `stream_events`。
+- ACP 分支中存在 `ACP_RUN_PAYLOADS.remove` 语义，payload 生命周期与第一次 stream 订阅绑定。
+
+## 3. 影响
+
+- 浏览器刷新或 SSE 重连可能导致同一 run 无法恢复。
+- 多个客户端观察同一 run 时只有第一个订阅者成功。
+- abort / retry / reconnect 语义不可靠。
+
+## 4. 建议修复
+
+- payload 应有 run 级持久生命周期，至少保留到 run completed / failed / aborted 后短 TTL。
+- stream subscription 不应拥有 payload 的删除权。
+- 增加 SSE 断线重连与重复订阅测试。
+
+## 5. 修复
+
+- [hermes_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes_client.rs:2051) `acp_run_payload_for_stream` 使用 `ACP_RUN_PAYLOADS.get(run_id).cloned()`，stream subscription 只读取 payload，不再拥有删除权。
+- [hermes_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes_client.rs:4116) 增加重复读取测试，锁定刷新、重连、多个观察者不会因为第一次读取而丢失 run payload。
+
+## 6. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_client_acp_stream_payload_lookup_keeps_payload_for_reconnect -- --nocapture`
+  - 结果：1 passed
@@ -0,0 +1,50 @@
+# 3-22 [done][bug] ACP permission 自动拒绝后 UI 仍展示审批动作
+
+> 发现时间：2026-05-18
+>
+> 状态：`[done]`
+>
+> 关联主线：`03-rust-web` / ACP runtime 与页面 AI 事件映射
+
+## 1. 问题定义
+
+当前 ACP client 收到 `session/request_permission` 后会立即返回 JSON-RPC error，并把事件转换为 `permission.denied`。这是为了避免 agent 等待权限响应直到超时。
+
+但页面 AI UI 仍在权限卡片和权限弹窗里展示“允许 / 拒绝”按钮。即使这些按钮在 `permission.denied` 下会被禁用，用户仍会看到审批入口，误以为可以把真实协议结果改成允许。
+
+## 2. 证据
+
+- [acp_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_client.rs:350) 对 incoming `id + method` request 直接返回 JSON-RPC error。
+- [acp_session_manager.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_session_manager.rs:121) 对 `session/request_permission` 生成 `decision="denied"`。
+- [acp_bridge.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_bridge.rs:237) 将 decision 映射为 `permission.denied`。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:4060) 权限弹窗仍渲染“允许 / 拒绝”按钮。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:5805) 权限消息卡片仍渲染“允许 / 拒绝”按钮。
+
+## 3. 影响
+
+- 用户看到的“允许”动作与 ACP wire contract 不一致。
+- 点击动作只修改本地 UI 状态，不会回写 ACP JSON-RPC response。
+- 对已经自动拒绝的权限请求展示审批按钮，会掩盖真实失败原因。
+
+## 4. 修复
+
+- [acp_client.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/acp_client.rs:350) 维持 `session/request_permission` 自动拒绝协议响应，避免 agent 等待超时。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:4003) `pageAiApplyPermissionEvent()` 对 `permission.denied` / `permission.allowed` 只保留结果态，不再展示可点击审批弹窗。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:4048) `pageAiShowPermissionDialog()` 对已决权限事件直接隐藏对话框。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:5797) 权限消息卡片对已决事件只展示结果，不再渲染审批按钮。
+
+## 5. 验证
+
+```bash
+cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_uses_backend_acp_session_runtime_store -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_permission_request_emits_frontend_decision_event -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web ssr::pages::layout::tests -- --nocapture
+cargo fmt --manifest-path rust/Cargo.toml --all -- --check
+git diff --check -- rust/crates/mnote-web/src/ssr/pages/layout.rs bugs/03-rust-web/done/3-22-acp-permission-auto-deny-ui-shows-approval-actions-v1.md
+```
+
+结果：
+
+- `page_ai_uses_backend_acp_session_runtime_store`：`1 passed`。
+- `acp_permission_request_emits_frontend_decision_event`：`1 passed`。
+- 版面相关静态测试继续通过，权限消息代码路径未破坏。