AstrBot-Desktop/docs/reports/fix-queue-2026-07-26.md
YokiiroBW 03b99efda8
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(astrbot): summarise how stream blocks relate to the final text
The first capture identified the real cause of a reply appearing twice,
and it was neither candidate. All 524 frames carried a message_id and
each reply used exactly one, so the event_id fallback is not involved
and neither is the history session fallback.

AstrBot interleaves two kinds of plain frame in one reply. Frames with
streaming true are incremental deltas whose total matches the complete
frame exactly. Frames with streaming false carry whole finished blocks —
one reply had five of them totalling 915 characters against 173
streamed. map_plain appends both, so the blocks show up inline during
generation, and map_complete then replaces the accumulation with the
streamed text alone, discarding them. That is the reply appearing twice
and then collapsing, and the collapse loses content.

One thing lengths cannot settle: whether a block repeats streamed text
or carries its own. One reply had 133 block characters against 142
streamed, which looks like a repeat; another had 915 against 173, which
cannot be. The two need opposite fixes, so this adds a per-stream
summary reporting how many blocks appear in the final text and in the
streamed text, as counts and lengths only.

Also records that plugin images were never sent: no media or attachment
frame appeared in any capture, and no plain frame carried a message
chain array. The attachment path has still never received data.

Refs: N-9 (new), N-4 (root cause found), N-6 (not a client defect).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 02:08:36 +08:00

38 KiB

AstrBot Desktop 修复队列

基于 2026-07-26 全源码审计 · 共 73 项 · 8 个批次

配套审计档案:full-source-audit-2026-07-26.md。 本文中的 P0-1 / P1-7 等编号均指向该档案中的对应发现。

编号说明:F-69 永久空缺——该编号系一次审查污染中被凭空注入,已于 2026-07-26 撤销 (见 r1-r2-status-2026-07-26.md §5),不得复用。 F-70 – F-74 于 2026-07-26 补编:初版队列遗漏了审计中的 P2-6、P2-7、P2-8、P2-29、P3-7 五条发现,它们此前没有任何批次归属。

执行状态(2026-07-26 更新)

批次 状态 说明
R1 发布阻断批 已完成,门槛已验证 9 项全部实现。2026-07-26 首次跑完整门槛,发现 2 处编译/lint 失败并修复(详见下方「R1 门槛验证结果」),补写 F-05 缺失的单测。现全绿。
R2 传输层批 已完成,门槛已验证 F-10 – F-13 全部实现,新增 9 条 Rust 测试(astrbot-desktop 单元测试 67 → 76)。顺带并入 F-56(P3-4,取消不再置 Disconnected)。全绿。
R3 隔离与状态正确性批 已完成,门槛已验证 F-14 – F-19 全部实现,新增 11 条 Rust 测试(astrbot-desktop 单元测试 76 → 87)与 5 条前端测试(19 → 24,含新建的 ChatPanel.test.tsx)。全绿。详见下方「R3 实现记录」。
R4 – R8 未开始 下一批为 R4 或 R5,两者与 R3 无依赖,可并行分派。

计数订正(2026-07-27 实测):本表此前记为「67 → 73(+6)」,与 r1-r2-status-2026-07-26.md 的「67 → 76(+9)」冲突。实跑 cargo test --workspace 的结果是 astrbot-desktop 单元测试 76 通过,workspace 合计 96 通过 / 2 忽略 (lib 76 + dual_gateway_integration 2 + desktop-protocol 9 + protocol_contract 5 + dual_instance 4; windows_dialog_smoke 与 soak 各 1 项 ignored)。故 76 为准,73 系过期数据。

R1 门槛验证结果(2026-07-26)

首次编译暴露 2 处失败,均为 R1 自身改动的直接后果:

  1. npm run typecheck —— ChatPanel.tsx:707 TS2345。F-06 把 updatedAt 放宽为 .nullish() 后, string | null 传进了 formatSessionTime(value?: string)。已把形参放宽为 string | null (函数原有的 falsy 判断本就覆盖 null)。这正是本文档第 4 条预警的 .nullish() 向下游传播。
  2. npm run lint —— react-refresh/only-export-components。F-05 把 safeLinkHref 作为非组件导出 放进了 MessageContent.tsx;仓库用 --max-warnings 0,warning 即失败。 已移到 src/lib/safeLinkHref.ts。

另:F-05 的验收条件写了 [x](javascript:alert(1)) 单测,但该测试从未写过,已补 src/features/chat/MessageContent.test.tsx(4 例)。

预警清单中的另两项(astrbot.rs 新测试闭包借用、errorMessage() 10 个接入点类型)实测无问题。

R2 实现记录(2026-07-26)

  • F-10 两个 client 拆分落在 astrbot_client.rs 与 gateway_client.rs:REST 保留总时限 (120s / 30s),流式端点改 read_timeout(AstrBot 120s、desktop-v1 90s)+ tcp_keepalive(60s), 不设 .timeout()。已从 vendored reqwest 0.13.4 源码确认 read_timeout 语义为「每次读成功后重置」。
  • F-11 新增 SseLineBuffer(Vec<u8> 缓冲、按 \n 字节分行、逐行解码、1MiB 单行上限)。
  • F-12 should_retry_astrbot 收窄为 reqwest::Error::is_connect() 唯一可重试;新增 AstrBotClientError::StreamInterrupted 变体标记「响应已开始后断流」,并经 astrbot_send_error() 映射为前端可见的 streamInterrupted 错误码。
  • F-13 取消 / chunk 错误 / mapper 错误 / 行溢出四条路径统一走 finish_stream_with() (Cancelled / Error)并 dispatch;协议 crate 新增 AstrBotStreamMapper::finish_stream_with()。 顺带并入 F-56(R8·P3-4):取消不再把连接置 Disconnected 再置回。
  • 测试基建说明:三条传输测试用裸 TcpListener 手写 HTTP/1.1 chunked SSE 假服务端,未引入新依赖。 选它而非 axum 的原因是需要按字节精确控制 chunk 切分点,以及在不发终止块的情况下中途断连—— 这两点用 HTTP 框架无法表达。F-11 的端到端测试已对旧实现验证过确实失败(复现乱码),非同义反复。

R2 审查后并入的三项(都是 R2 自身改动造成的,已在本批修掉):

  • 移除流式总超时后,单条响应失去唯一边界(read_timeout 只测两次读之间的间隔,不能替代)。 已加 64MiB 单响应上限,同时约束 mapper.accumulated。
  • send_slot_message 的 client.take() 独占窗口原被 120s 总超时封顶,F-10 后变成与回复等长—— 期间 sessions / capabilities / upload / download / switch 五个命令全部误报未连接。已改 clone()
    • 以 message_cancellation 串行化发送(即 F-49,因 R2 使其显性化而从 R7 提前)。
  • SseLineBuffer 逐行从头 drain 是平方复杂度(hyper 单个 item 可达数百 KiB)。已改游标。

R2 未覆盖、仍开放:P1-2 描述中的「发送先入库 user 行」属 F-18(R3),本批未动。

工具链教训(务必遵守):本批的对抗式审查让 subagent 直接跑在工作区上,其中两个 agent 做完 「临时改动验证」后没有还原——在 send_chat_stream 的错误分支里注入了一个显式的第二次 POST /api/v1/chat(注释标着 MUTATION (temporary)),并在 astrbot_client.rs、runtime.rs、 src-tauri/tests/ 留下了复现模块。那个注入的 POST 一度被误判为 HTTP 栈的真实缺陷并记为 F-69, 在把它二分到具体注入行之后才定位到真因。F-69 不存在,已撤销。 后续审查必须只读运行,或用独立 worktree 隔离。

R3 实现记录(2026-07-27)

  • F-14 activate_slot 拆成三段:段 0 校验与建 client(无锁),段 1 单个临界区内 bump generation、 当场安装 connection_cancellation、写 Connecting 快照,段 2 锁外 tokio::select!(biased;) 探测,段 3 重新取锁后先 ensure_generation 再回写。监听器收到的是段 1 那个 Arc——若在此新建第二个 token,deactivate_slot 将取消一个无人监听的 token,desktop-v1 的重连循环会比断开活得更久。 顺带修掉一个队列未记的缺陷:原实现把校验放在 Connecting 快照之后,? 早返回会拆掉一个正常 连接并把槽永久留在 Connecting(无 client、无 last_error)。
  • F-17 switch_slot_session 在第一临界区连同 client 捕获 generation,回写抽成 commit_session_id() 并先校验。
  • F-19 三层:activate_slot 段 1 的运行时不变量(覆盖 auto_connect_configured_slots,它直接调 activate_slot)、probe_connection_slot 对 connection_slots 的交叉校验、运维守卫扩展到 probe / disconnect。两条规则都写成否定式(只问「是否绑在另一槽」):auto-connect 依据 profile.auto_connect_slot 激活且从不写 connection_slots,肯定式规则会打死重连。 运维守卫今日仍无生产写入方(F-74),因此附带一条直接翻转守卫的单测,避免复刻死分支。
  • F-18 新增只读预检 ensure_slot_can_send();条件抽成 slot_send_precondition() 供发送路径复用。 message_id 只铸一次,失败且 !server_received(code) 时以 error = true 幂等重写该行。 server_received() 只认 cancelled / streamInterrupted——这两种情况 AstrBot 已收到消息。 配套一条穷举 astrbot_send_error 全部变体的测试,防止 R2 错误码改名而静默破坏分类。 R2 的重试循环与错误映射逐字未动,五条 R2 哨兵测试复跑通过。
  • F-15 四处 listen() 统一改「active 标志 + 迟到 resolve 立即注销 + .catch()」。 测试替身 src/test/tauriEvent.ts 采用延迟 resolve,否则竞态无法表达;setup.ts 每例后重置 注册表(clearMocks 不管普通模块状态)。新建 ChatPanel.test.tsx。
  • F-16 draft / pendingAttachments / 错误全部改 Record<ChatSlot, …>,每个异步动作开头 const slot = selectedSlot; 固定槽位。错误必须拆成两个 state:refresh() 每 500ms 在成功时 setError(null),此前会在半秒内静默抹掉任何发送/上传错误横幅;轮询失败归 runtimeError (描述 IPC 通道),用户动作归 slotError。

测试有效性:F-14、F-15、F-16 的新测试都做过变异检验——分别注入「探测期间持锁」「旧的无条件 赋值 unlisten」「按固定槽位读取」三种回退,对应测试全部失败,确认非同义反复。

门槛结果(2026-07-27):cargo fmt / clippy -D warnings 通过;cargo test --workspace 107 通过 / 0 失败 / 2 ignored(astrbot-desktop 单元 76 → 87);npm run typecheck / lint 通过;npm run test 19 → 24 通过 / 5 文件;npm run build、npm run test:e2e(5/5)、 npm run tauri:build(NSIS)通过。

R3 未覆盖、仍开放:auto_connect_configured_slots 仍串行(commands.rs),一个死 profile 会把 第二个 profile 延迟至多 120s——但不再冻结 UI。属遗留限制,本批不修。

R1 已改动的文件

新增:src/lib/errorMessage.ts、src/features/pet/types.test.ts

修改:crates/desktop-protocol/src/astrbot.rs、src-tauri/src/networking/astrbot_client.rs、 src-tauri/capabilities/default.json、src-tauri/tauri.conf.json、src/App.tsx、 src/pages/SettingsPages.tsx、src/features/chat/{types.ts,types.test.ts,MessageContent.tsx,ChatPanel.tsx}、 src/features/pet/{types.ts,DesktopPetView.tsx}、src/features/profiles/ProfileManager.tsx

接手 R2 前必须先做的事

  1. 跑完整门槛验证 R1,任何一项失败都先修 R1 再进 R2:

    cargo fmt --all -- --check
    cargo clippy --workspace --all-targets -- -D warnings
    cargo test --workspace
    npm run typecheck && npm run lint && npm run test -- --run && npm run build
    

    R1 预期新增 3 组测试:Rust 侧 consecutive_streams_do_not_reuse_event_ids, 前端侧 chat/types.test.ts 的三条 null 契约用例与新建的 pet/types.test.ts。

  2. F-01 的实现方式已定为方案 A:AstrBotStreamMapper::new(server_instance_id, stream_id), event_id 形如 astrbot-{sid}-{stream}-{seq},调用方每次请求传 Uuid::new_v4()。 队列正文中 F-01 行描述的方案 B / C 不再考虑。

  3. 注意 src/features/profiles/ProfileManager.tsx 是 CRLF 为主的混合换行文件, 编辑时务必逐字节保留原有行尾,否则会产生整文件换行 diff。

  4. R1 的改动全部经人工逐行核对,但没有编译器验证过。优先怀疑对象: astrbot.rs 的新测试闭包借用、errorMessage() 的 10 个接入点类型、 .nullish() 造成的 string | null | undefined 类型向下游传播。


队列按执行顺序编排,不是按严重度排序:同文件相邻改动合并进同一批以避免冲突,有依赖的项显式标注。每项给出位置、动作、验证方式与建议提交名(遵循 AGENTS.md §10 Conventional Commits)。

排期约束(必须遵守的三条串行链)

  1. F-01 必须先于 R2 全批 —— 两者都改 astrbot_client.rs:440-510 的流循环与 dispatch。
  2. R2 内部四项串行(同一函数体),建议同一分支连续提交,不要并行分派。
  3. F-06(zod)→ F-08(errorMessage)→ R3 的前端项,都动 ChatPanel.tsx / chat/types.ts,按序落地。

其余批次之间可并行分派给不同分支。


R1 · 发布阻断批

目标:恢复真实 AstrBot 聊天闭环与桌宠功能。9 项全部是小改动(多数一行到一函数),建议 1–2 天内合并,合并后重新走一遍 Q9 门槛。

ID 来源 位置 动作 验证
F-01 P0-1 crates/desktop-protocol/src/astrbot.rs:453-455;src-tauri/src/networking/astrbot_client.rs:440 推荐方案 A:AstrBotStreamMapper::new(server_instance_id, stream_id) 增加流级种子(调用方传 Uuid::new_v4()),event_id 改为 astrbot-{sid}-{stream}-{seq}。保留同流内去重语义,事件 ID 全局唯一。(方案 B:sequence 提到 client 级 AtomicU64 —— 会让协议 crate 依赖 client 生命周期,不推荐;方案 C:astrbot 路径取消去重 —— 最省事但丢掉同流重复防护) 新增单测:同一 AstrBotClient 连续两次 send_chat_stream,第二条流的 delta 与 completed 全部到达 sender。真机:同一连接连发 3 条,每条回复完整显示
F-02 P1-12 src/features/pet/types.ts:47 正则 \\. → \. expect(petPackManifestSchema.parse(内置 manifest.json)) 通过
F-03 P1-13 src-tauri/capabilities/default.json:5 windows 数组加 "desktop-pet" 桌宠窗口能收到 connection-runtime-event;拖动与右键菜单生效
F-04 P1-14 src-tauri/tauri.conf.json → app.security.csp img-src 追加 blob: release 构建下发送带图消息,图片正常渲染(dev 不注入 CSP,必须用 release 验)
F-05 P1-15 src/features/chat/MessageContent.tsx:66-72 new URL(href, base) 解析后仅放行 http/https(可选 mailto),非法协议降级为纯文本;rel 补 noopener 单测:[x](javascript:alert(1)) 渲染为文本而非 <a>
F-06 P1-7a src/features/chat/types.ts:35,36,63,64,156 五处 .optional() → .nullish()(sessionId/messageId/displayName/updatedAt/name) 契约测试:用 Rust serde_json 真实输出(含 null)回放,boundRuntimeEventSchema / remoteChatSessionSchema / astrbotModelOptionSchema 全部通过
F-07 P1-7b crates/desktop-protocol/src/astrbot.rs:84-91 AstrBotModelOption 补 #[serde(rename_all = "camelCase")](该类型不入库,无迁移风险) 前端 isDefault 不再恒 undefined;模型下拉默认项正确
F-08 P1-16 新建 src/lib/errorMessage.ts;接入 ChatPanel.tsx:423 等 6 处、SettingsPages.tsx:119 抽出共享 errorMessage(),识别 {code,message} 形状(复用 ProfileManager.tsx:689-702 的既有实现) 断开连接后发送,错误条显示 Rust 的 message 而非 [object Object]
F-09 P1-17 DesktopPetView.tsx:92,173,191,198;App.tsx:451,554 恢复中文原文("精灵图加载失败"/"无法获取 Canvas 上下文"/"桌宠"/"加载中…");&#x...; 实体改明文 CI 加 grep -nP '\?{3,}' 与非 ASCII 实体扫描

批次验收:cargo test(+3 条新测试)、Vitest、typecheck、lint、release 构建、真机连发 3 条消息 + 桌宠事件联动 + 附件图渲染。

建议提交:fix(astrbot): scope stream event ids per request / fix(pet): correct manifest image pattern / fix(tauri): grant desktop-pet capability / fix(tauri): allow blob images in production csp / fix(chat): restrict markdown link protocols / fix(chat): accept null in runtime event contracts / fix(protocol): serialize model options in camelCase / refactor(ui): share ipc error formatting / fix(ui): restore corrupted localized strings


R2 · 传输层批(串行,同一分支)

目标:让长连接与长回复真正可用。四项都在 astrbot_client.rs / gateway_client.rs 的流循环,必须串行。

ID 来源 位置 动作 验证
F-10 P1-1 gateway_client.rs:100-101;astrbot_client.rs:147-148 拆分两个 reqwest Client:REST 保留总时限,流式端点不设 .timeout(),改用 connect_timeout + 心跳看门狗 / read_timeout 做空闲检测 desktop SSE 连续保持 >5 分钟不断;AstrBot 生成 >120s 的长回复完整到达
F-11 P1-3 astrbot_client.rs:462-463 buffer 改 Vec<u8>,按 \n 在字节层分行,逐行 String::from_utf8(保留不完整尾字节到下一 chunk) 单测:把一条中文 SSE 帧在 UTF-8 字符中间切成两个 chunk 喂入,输出无 U+FFFD
F-12 P1-2 runtime.rs:647-653、:723-731 should_retry_astrbot 收窄:仅"连接建立失败"可重试;一旦收到响应头/首字节即不再自动重发,改返回可手动重试的错误码 单测:mock 在响应体中途断流 → 不产生第二次 POST
F-13 P2-2 astrbot_client.rs:456-459 及 next? 错误路径 取消与错误两条 return 路径统一调 mapper.finish_stream()(FinishReason::Cancelled / Error)并 dispatch 停止生成后重启应用,该消息不再显示为"生成中";DB 无 streaming=1 残留

批次验收:新增 3 条单测;真机断网/恢复、长回复、中途停止三场景。

建议提交:fix(net): stop total timeouts from killing streams / fix(astrbot): decode sse bytes on line boundaries / fix(astrbot): do not resend messages after response start / fix(astrbot): finalize streams on cancel and error


R3 · 隔离与状态正确性批

ID 来源 位置 动作 验证
F-14 P1-4 runtime.rs:197-325 探测移出锁:先置 Connecting 快照并 drop(guard),health()/probe() 在锁外执行,按 generation 回写;激活伊始即安装 connection_cancellation 并在 probe 内 select 一个槽连接不可达地址期间,另一槽的 status()/发送/断开全部正常;激活中可被 disconnect 打断
F-15 P1-10 ChatPanel.tsx:144-155;App.tsx:391-399;DesktopPetView.tsx:46-82;src/test/setup.ts 三处改 let active=true; listen().then(fn => active ? unlisten=fn : fn()); return () => {active=false; unlisten?.()};测试 mock 改为延迟 resolve 并断言注销次数 StrictMode 下 delta 不再翻倍;新测试断言 unmount 后注销被调用
F-16 P1-11 ChatPanel.tsx:80-82,384-412 pendingAttachments、draft、error 改 Record<ChatSlot, …> 陪伴槽上传附件 → 切运维 → 发送,附件不跟随;运维错误横幅不出现在陪伴槽
F-17 P2-1 runtime.rs:453-477 switch_slot_session 首锁捕获 generation,二次锁写入前比较,不一致返回 cancelled 单测:切换会话期间 deactivate,旧 session 不写入新代快照
F-18 P2-3 commands.rs:632-656 校验通过且确认 client 存在后再 upsert_chat_message;失败路径按 message_id 回删或标记 error 未连接状态下发送,历史里不留 user 行
F-19 P2-4 commands.rs:412-461 probe_connection_slot 激活前校验 connection_slots 分配,拒绝同一 profile 占用两个运行时槽;operations 切换守卫覆盖 probe/disconnect 同一 profile 依次 probe 双槽 → 第二次被 profileAlreadyAssigned 拒绝

R3.5 · 真机反馈批(2026-07-27 追加)

2026-07-27 首次真机使用暴露 5 个问题,编号 N-*(新发现,不在 2026-07-26 审计中)。 其中 3 项根因确凿并已修复;2 项的根因取决于服务端实际发的帧,不猜,待抓帧后再定。

已完成

ID 位置 根因 状态
N-1 styles.css:2183/2456/2655/2735/3134;ChatPanel.tsx:822,834,846 .message-action-label(clip-rect 屏幕阅读器类)定义了却从未被任何组件使用,组件用的是裸 <span>;同时按钮被 5 处重复定义中的 3 处当作胶囊按钮,与最终块冲突。文字塞进 2rem 方框后竖排折行 已修
N-2 styles.css:509 + :3106 .chat-message-row{align-items:flex-end} 把头像对齐到 .chat-message-content 底边,而该盒子因操作条占位比气泡高一行 → 头像掉到气泡下方 已修
F-40 styles.css:3113 顺带关闭:visibility:hidden 把按钮移出 tab 序,:focus-within 永远无法触发。改为仅 opacity 已修(原属 R6)
N-3 DesktopPetView.tsx:222-225 右键处理是裸 void invoke(...),无 .catch,Rust 侧任何失败都不可见,与「原生菜单赢了」无法区分 已让错误可见;根因待定

验证:在真实样式表下用浏览器实测——头像与气泡顶部差 0px,按钮 34×34 / border-width: 0px, 标签盒 1×1(已裁剪),聚焦后操作条 opacity 由 0 变 1。

2026-07-27 抓帧结果:N-4 / N-6 定论,两个候选销案

首轮 524 帧(4 轮对话)已捕获并解析。结论如下,此前记录的两个候选均不成立。

N-6 插件图片:根本没发出来。 524 帧中 image / record / file / video / attachment_saved 数量为 0,且 plain 帧的 data 从未是数组(消息链)——全部是纯字符串。 所以不是客户端渲染失败,是 AstrBot 侧压根没投递媒体帧。我们的附件链路至今零数据, F-33 / N-6 / N-7 全部无法验证,需先让服务端真的发出图片。

N-4 双气泡:F-34 排除,historySessionId 回退排除。

  • 全部 plain 帧均携带 message_id(77 / 136 / 172 / 112 条,无一缺失)→ 候选 A(messageId || eventId 回退产生每事件唯一 id)不成立。
  • 每轮对话只有一个 message_id,全程不变 → 也不是服务端分成了多条消息。
  • 因此候选 B(historySessionId 回退到 storedSessions[0])也不是本症状的原因。 该回退仍是缺陷,但降级为独立项 N-5,不再与双气泡绑定。

真因:streaming: false 的整段 plain 帧被当作增量拼接,随后被 complete 替换丢弃。

AstrBot 在一次回复中交错投递两类 plain 帧:

类型 语义 实测
streaming: true 逐字增量,累计等于 complete 的内容 第2轮 173 字 = complete 173;第3轮 209 = 209;第4轮 142 = 142
streaming: false 整段已完成的消息 第2轮 5 段共 915 字;第3轮 2 段共 469 字;第4轮 1 段 133 字

实测帧序(第2轮):[增量×14] → 整段217 → 整段192 → [增量×23] → 整段201 → 整段192 → [增量×94] → 整段113 → complete(173)。

map_plain(astrbot.rs:379)对两类帧一视同仁,全部 emit_delta 追加。于是:

  1. 生成过程中气泡里先出现整段内容,再继续逐字追加流式内容 → 用户看到的「两个回复」
  2. map_complete(astrbot.rs:405)用 complete 的内容替换 accumulated → 整段那部分被丢弃 → 「结束后恢复成一个」,且最终显示的内容比 AstrBot 实际发出的少

尚未定论的一点:整段内容与流式内容是否重复。第4轮的 133 字 vs 142 字非常接近(疑似重复), 而第2/3轮的 915 vs 173、469 vs 209 明显是额外内容。两者需要相反的处理——重复则单独开气泡会显示两遍, 额外则丢弃会少内容。仅凭长度无法区分,已加 astrbot stream summary 探针 (blocks_repeated_in_final / blocks_repeated_in_stream,只输出布尔与长度,不输出正文), 待下一次复现后定论。

产品决定(2026-07-27):分段按每段一个气泡呈现,忠实还原 AstrBot 的分段节奏。

新增项

ID 问题 位置 状态
N-9 分段消息被拼接进流式消息,并被 complete 替换丢弃 astrbot.rs:379(map_plain)、astrbot.rs:405(map_complete) 真因已定位,待重复性探针结果后实施
F-44 发送后不滚动到底部,流式生成发生在视口外 ChatPanel.tsx 全文件无 scroll 代码 已归档于 R6,用户 2026-07-27 反馈确认
N-8 消息进入列表无过渡动画,生硬出现 ChatPanel.tsx 消息列表渲染 新记录,用户要求类 TG 的淡入过渡

待抓帧定论

已加 trace_frame_shape()(astrbot_client.rs,RUST_LOG=astrbot_desktop=debug 开启,只记结构不记内容)。

ID 问题 候选根因 判据
N-4 生成中概率出现两个回复气泡,结束后恢复成一个 候选 A = F-34(P2-13):ChatPanel.tsx:976 与 commands.rs:412 同用 messageId || eventId 回退,event_id 每事件唯一,任一 delta 缺 message_id 即自成一条消息。候选 B:ChatPanel.tsx:74-75 的 historySessionId 回退到 storedSessions[0],会加载另一个会话的历史并合并 日志中 plain 帧的 has_message_id 是否恒为 true
N-5 「恢复成一个」不是自愈 activeMessages(ChatPanel.tsx:116)按 sessionId 过滤,只是遮住孤儿气泡;React state 与 SQLite 中它仍在 需随 N-4 一并清理
N-6 插件发的图片不显示 map_media()(astrbot.rs:339)只记 pending_media 不产出事件,必须等后续 attachment_saved 配对;若插件的 image 帧自带 id/URL 且无该后续帧,图片被静默丢弃。另:非图片媒体全丢(F-33)、pending_media 单槽位(F-33)、id 字符集限 [A-Za-z0-9._-] 挡掉 URL 形态 日志中 image 帧的 data_keys,以及其后是否出现 attachment_saved
N-7 图片即便拿到也可能被 CSP 拦 tauri.conf.json:45 的 img-src 'self' asset: http://asset.localhost data: blob: 不含任意 http 源 若插件走 URL,倾向代理下载转 blob,不放宽 img-src——放宽等于让渲染层直连任意外部主机

R4 · 数据与凭据安全批

ID 来源 位置 动作 验证
F-20 P1-6 database/mod.rs:319-320 改 SELECT * FROM (… ORDER BY updated_at DESC LIMIT ?) ORDER BY updated_at ASC;补 before/after 游标参数 单测:插入 250 条,加载返回最新 100 条
F-21 P1-18 diagnostics/redaction.rs:91 key_value_regex 候选加入裸 token、auth[_-]?token、id[_-]?token、session[_-]?token;新增 JWT 形态正则 eyJ[\w-]+\.[\w-]+\.[\w-]+ 新测试不使用 known_secrets:token=eyJ…、?token=…、YAML token: eyJ… 均须被脱敏(现有测试用 canary 掩盖了缺口,需一并重写)
F-22 P2-11 diagnostics/config.rs:213,232,259 YAML/INI/.env 增加按 key 的行级结构化脱敏(对齐 JSON/TOML 的 is_sensitive_key 路径) .env 内 AUTH_TOKEN=… 经诊断返回时为 [REDACTED]
F-23 P2-9 profiles.rs:213-218 删除 profile 前读取 credential_reference 并 store.delete;可选:启动时孤儿凭据对账 删除 profile 后 Credential Manager 中对应条目消失
F-24 P2-10 auth.rs:13-20;credentials/mod.rs:11-20 两个请求结构体手写 Debug(敏感字段输出 [REDACTED])或改 secrecy::SecretString 单测断言 format!("{:?}", req) 不含明文(对齐 SecretCredential 既有测试)
F-25 P2-12 database/mod.rs:524,556 及相关读写 统一 account_id 键模型:两表都含并全部读写带上,或彻底移除该列 —— 二选一,写进 ADR 迁移测试 + 隔离测试

R5 · 协议健壮与契约治理批

ID 来源 位置 动作 验证
F-26 P1-5 gateway_client.rs:179-184,282-284 UnsupportedEventType / InvalidPayload 降级为事件级跳过(记日志、推进 last_event_id),仅版本/身份不匹配保持终态 单测:mock 推未知事件类型 → 槽位保持 Connected,后续事件正常
F-27 P2-15 envelope.rs:171 及各 payload 信封与只读 payload 移除 deny_unknown_fields(ToolProposal/ToolResult 保留);或解析失败跳过并推进游标 单测:信封带附加字段仍能解析;不再出现重放死循环
F-28 P1-8 docs/protocol/v1/schemas/;tests/protocol_contract.rs 重跑 export_schemas --write;新增测试比对 generated_schemas() 与磁盘文件 cargo test 即可发现漂移;connection-profile.schema.json 含 remoteDisplayName
F-29 P2-16 astrbot.rs:17-43;src/features/chat/types.ts:13;ChatPanel.tsx:240;README TransportKind 加 #[serde(rename = "astrbot-openapi")] 统一两套拼写,前端 enum 与文档同步(跨端原子改动,一次落地;DB 值不变,无迁移) 全库 grep 无 astr-bot-open-api 残留
F-30 P2-5 astrbot_client.rs:128-133,431-438 删除恒 false 的身份自比较,或改为探测可观测特征后再比对;文档明示 AstrBot 身份为 URL 派生 代码无死分支;docs/decisions/ 记录该限制
F-31 P2-19 mock-gateway/src/routes.rs:196-206、state.rs:161-173、config.rs:29-31 Lagged 改 break(迫使走重连重放);cursor 未命中先发 gap 事件;server_instance_id 掺端口 soak 增加 sequence 单调无缺口断言
F-32 P2-17 astrbot.rs:381-444 complete 后记录 per-message 完成标记,同 id 的后续 plain/complete 需显式重新开窗或忽略 单测覆盖"重复 complete"与"complete 后迟到 plain"
F-33 P2-18 astrbot.rs:336-353 非图片媒体输出通用占位标记;pending_media 改 FIFO 队列 单测:record + attachment_saved 产出可见标记;双图交错不丢
F-34 P2-13 commands.rs:341;ChatPanel.tsx:916-917 mapper 为无 message_id 的流合成稳定流内 id(如 synthetic-{stream}),前后端同步取消 event_id 回退 单测:省略 message_id 的多帧流合并为一条消息
F-70 P2-6 astrbot_client.rs:383-388 download_attachment 先查 Content-Length,改流式累读并在超过 16MiB 时立即中断,不再整体读入内存后才校验 单测:mock 返回超限 body,客户端在读满前返回超限错误且内存占用有界
F-71 P2-7 gateway_client.rs:121-126 health() 与 SSE 一致附带 bearer 单测:mock 对无 bearer 的 health 返回 401,激活仍成功即失败
F-72 P2-8 gateway_client.rs:237-238 仅在「连接存活超阈值且收到过事件」时重置退避,避免服务端接受即优雅关流时进入约 10 次/秒热重连 单测:mock 接受连接后立即关闭,断言重连间隔单调增长
F-73 P2-29 astrbot_client.rs:554-565 JWT exp 判定改 exp <= now + 30s;不可解析的 token 打 debug 日志 单测:exp 落在 30 秒内的 token 被判为过期

上列四项系 2026-07-27 补编。它们与 F-26、F-30 同处 gateway_client.rs / astrbot_client.rs,按本队列 「同文件相邻改动合并进同一批」的编排原则归入 R5;放入 R4 会让两个可并行分支争夺同一文件。 R5 因此由 9 项增至 13 项,与 R3、R4 仍无依赖关系。


R6 · 体验、无障碍与产品红线批

ID 来源 位置 动作
F-35 P2-30 DesktopPetView.tsx:139-148;tauri.conf.json 产品红线:alwaysOnTop 默认改 false(隔离基线要求气泡/桌宠不默认置顶);embedded 模式跳过偏好写入;非 embedded 先读既有偏好再增量提交
F-36 P2-20 ChatPanel.tsx:73-74,181-187,264-293 mark-read 完成后再重取会话列表;仅存在真实 activeSessionId 时标已读;非选中槽位监听事件递增未读
F-37 P2-21 ChatPanel.tsx:468-475 retryMessage 增加 sessionId === activeSessionId 过滤;messageOverride 与 draft 回退解耦
F-38 P2-22 ChatPanel.tsx:435-457 按 code === "cancelled" 区分取消与真错误;停止时保留已收内容为正常消息,不标 error、不弹横幅
F-39 P2-23 ChatPanel.tsx:920-925;chat/types.ts ChatMessage 补 profileId/serverInstanceId 并纳入所有 find/filter/去重键(对齐四元组规范)
F-40 P2-24 styles.css:3116-3139 去掉 visibility:hidden,仅用 opacity + pointer-events,解开键盘 focus-within 死锁
F-41 P2-25 ChatPanel.tsx:607-620,711-717 箭头切换时 focus() 目标 tab;两个 panel id 常驻或动态 aria-controls;aria-busy 与 aria-live 分离
F-42 P2-26 CredentialEnrollmentCard.tsx:34-80 finally 中清空 secret/password/totp;两处 invoke 返回值补 zod schema
F-43 P2-27 ChatPanel.tsx:343-354 首次 refresh 失败也建立退避轮询;snapshot schema strict 失败给可见告警而非静默离线
F-44 P2-28 ChatPanel.tsx 消息列表底部锚点 +"接近底部才跟随";unmount 调 recognition.stop() / speechSynthesis.cancel();朗读前 Markdown 转纯文本

R7 · 性能与工程化批

ID 来源 动作 预期收益
F-45 优化 §2 DesktopPetView.tsx:10 去掉 ?inline 改普通资源引用,manifest 与 import 同时切到已有的 WebP lazy chunk 从 ~5.2MB 降到 ~0.6MB
F-46 优化 §1 activeMessages memo 依赖改标量 activeSessionId;MessageContent 套 React.memo;applyRuntimeEvents 只克隆命中项;messages 按会话修剪 消除 500ms 全表重渲染与重复 Markdown 解析
F-47 优化 §3 附件上传/下载改 Tauri 2 raw body / tauri::ipc::Response 二进制通道;Rust 侧去掉 bytes.clone() 16MiB 附件不再膨胀成 1670 万元素数组
F-48 P2-14 事件通道改"每槽独立 mpsc + 唯一持久化点 + 广播 emit",移除 drain_connection_runtime_events 消除双消费者抢事件与跨槽背压
F-49 优化 §2 send_slot_message 的 client.take() 改 clone(),以 message_cancellation 存在性串行化发送 长流期间 sessions/capabilities/upload 不再误报"未连接"
F-50 优化 §5 styles.css 以 --ui-* 为唯一 token 源合并,删除 OS 亮色媒体查询块与幽灵 token,引入 stylelint 减约 40% 死样式;修复暗色下链接对比度
F-51 P2-31 tauri.conf.json 的 beforeDevCommand/beforeBuildCommand 改 pnpm run;engines 与 @types/node 对齐;文档 React 版本更正为 19 消除双包管理器混跑
F-52 P3-17 tsconfig 补 noUnusedLocals/noUncheckedIndexedAccess;eslint 接 jsx-a11y、重开 set-state-in-effect;vitest 加 coverage;关掉无谓的 usePolling 编译期即可暴露索引假设类缺陷

R8 · 剩余 P3 与外部依赖

可随手带入相邻批次的 P3:F-53 事件 timestamp 注入真实时钟(P3-1)· F-54 server_instance_id 改 sha2 派生 + 兼容映射(P3-2)· F-55 username 逐字节百分号编码(P3-3,放宽用户名规则前必须先修)· F-56 取消消息不再置 Disconnected(P3-4)· F-57 生产 CSP 移除 127.0.0.1:*(P3-5)· F-58 凭据轮换改「写新→落库→删旧」(P3-6)· F-59 退出前 deactivate 双槽并 flush 日志(P3-8)· F-60 session_id 对象分支取键(P3-9)· F-61 桌宠窗口补 Suspense 边界(P3-10)· F-62 导航图标 aria-hidden + 测试选择器改语义文本(P3-11)· F-63 reduced-motion 停帧 + onerror 清理 + DPR(P3-12)· F-64 文案统一中文(P3-13)· F-65 死控件与标签错误四处(P3-14)· F-66 测试 SSE 助手容错(P3-15)· F-67 App.test mock 补 close_pet_window(P3-16)· F-68 mock 订阅重放竞态(P3-18)· F-74 operations 切换守卫无生产写入方(P3-7)

F-74 补充说明(2026-07-27 补编):该守卫的读侧已全线接通——slots.rs:97,108 → policy.rs:18-22 → ProfileManager.tsx:276 会依据 operationsSwitchLocked 禁用运维槽控件;但 begin_operations_task / end_operations_task(runtime_guards.rs:28,45)的调用方只有 #[cfg(test)](slots.rs:256,285),因此 connection_policy_status 把一个永为 false 的标志 当作已激活的守卫上报。R3 的 F-19 只是把读侧扩展到 probe/disconnect,不含写侧,因此不覆盖本项。 审计给出的近期动作是先在状态载荷中如实标注守卫未激活,写侧接线待工具管线落地——这与下节 「工具提案六道闸门」条目联动。

需要真机/外部条件,不进本轮编码:

  • P1-9 附件契约验证(置信度中):用真实容器发一条带图消息,确认模型是否真的看到附件。若确认被忽略,改为 message 段数组承载 attachment_id(snake_case),这会是一个 P1 级改动。
  • 证书指纹绑定:在实现 TLS 校验前,建议在录入层标注"暂不生效",避免虚假安全感。
  • 工具提案六道闸门:未开始实现属阶段合理;在闸门落地前不得放开任何工具执行入口,connection_policy_status 应如实上报 guard 未激活。
  • 签名更新、双服务器 soak:维持现状,不在本地伪造。

附录 · 批次依赖图与建议分支

批次 依赖 建议分支 可并行
R1 无 fix/p02-release-blockers 内部 9 项可并行(除 F-06→F-08)
R2 R1 的 F-01 fix/astrbot-stream-transport 内部串行
R3 R1 的 F-06 fix/slot-isolation-and-state Rust 项与前端项可分两人
R4 无 fix/data-and-secret-boundaries 与 R2/R3 并行
R5 无 fix/protocol-contract-hardening 与 R2/R3/R4 并行
R6 R3 fix/chat-ux-and-a11y —
R7 R6 perf/frontend-and-ipc —
R8 — 随批携带 —

按 AGENTS.md §11,每批合并前须走完:fmt → lint → typecheck → clippy(-D warnings) → 单元测试 → 适用集成测试 → 生产构建 → 更新 docs/progress.md 与 CHANGELOG.md。R1 与 R2 合并后建议同时刷新 docs/q9-local-acceptance.md 的验证记录。