AstrBot-Desktop/docs/reports/full-source-audit-2026-07-26.md
YokiiroBW 58a98d3c94 docs(reports): record the source audit, fix queue, and R1/R2 results
Adds the 2026-07-26 full-source audit and the execution-ordered fix queue, and
records what actually happened when R1 and R2 were verified:

- R1 had never been compiled. The gate found a type error introduced by its own
  `.nullish()` widening and a lint failure from a non-component export, plus one
  acceptance test that was specified but never written.
- R2 landed F-10 through F-13, and an adversarial review of it surfaced three
  defects the batch had itself introduced, all fixed in the same batch.
- The review subagents ran against the live working tree and left mutations
  behind, including a deliberate duplicate POST inside the stream error path.
  That injected code was briefly mistaken for a real HTTP-stack defect. It has
  been removed and the process note recorded so review runs are isolated next
  time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-26 23:12:57 +08:00

41 KiB

AstrBot Desktop 全源码审查档案

全源码审计 · 2026-07-26

配套修复队列:fix-queue-2026-07-26.md(68 项,8 个批次,含排期依赖与验证方式)。

项目 值
代码基线 分支 feat/p02-dual-connections · v0.1.0-alpha.2 · 本地快照 2026-07-21/22
所处阶段 本地 Q9 门槛已过;Q10–Q15 聊天体验增量与 AstrBot OpenAPI 适配器刚完成
审计范围 src/、src-tauri/、crates/、tests/、根配置、docs/(契约与阶段文档)共 146 个文件、约 2.4 万行
审计方法 4 路并行深度静审(Rust 网络运行时 / Rust 数据安全 / 协议与网关 / 前端与工程)+ 逐条人工复核高危发现(关键结论均回读源码验证,宠物 manifest 正则经 node 实测)
发现统计 P0 × 1 · P1 × 18 · P2 × 31 · P3 × 18;另剔除误报 2 项、降级 2 项(见附录 A)

严重度定义:P0 = 核心功能不可用 / 数据丢失 / 安全越界;P1 = 明确 BUG 或隔离违规,特定场景必现;P2 = 边界缺陷 / 健壮性 / 一致性;P3 = 小优化。


一、总体评估

架构骨架是健康的:双槽位隔离在数据层做得扎实(chat_messages 主键含 profile_id + slot + server_instance_id + session_id + message_id,超出规范要求);凭据边界(Windows Credential Manager + Zeroizing + 引用入库)、文件事务(plan→dry-run→复制→哈希→原子提交、保源不覆盖)、路径策略(双层防御,覆盖 UNC / .. / 保留名 / 尾随点空格)、全库无任何 shell 执行入口——这些安全铁律主线成立,质量高于同阶段项目平均水平。

但最近两周的高速增量(AstrBot 适配器 + Q10–Q15 前端)留下了一条贯穿性的裂缝:契约失配。三类契约各自漂移——Rust 序列化 ↔ 前端 zod(null vs optional 三连)、Rust 类型 ↔ JSON Schema 文档(remoteDisplayName 漂移且无 CI 拦截)、客户端实现 ↔ 真实 AstrBot 线上行为(附件字段、事件 ID 语义)。叠加一个 P0(去重器吞掉第二条消息的流式回复)和两个传输层缺陷(30s/120s 全局超时杀长连接、UTF-8 跨 chunk 乱码),当前基线对真实 AstrBot 的核心聊天闭环与对 Mock 网关的事件链路都处于"带病运行"状态——本地门槛全绿是因为测试恰好全部避开了这些路径(单流单发、恒带 message_id、mock 不过前端)。

结论:不建议在修复第一批(见第六节路线图)之前打 v0.1.0-alpha.3(文字聊天完成)标签。


二、BUG 档案

P0:致命

P0-1[后端·协议]同一连接第二条消息起,流式回复被去重器整体吞掉

  • 位置:crates/desktop-protocol/src/astrbot.rs:454-455 + src-tauri/src/networking/astrbot_client.rs:440, 505-508(两路审计独立发现,已人工复核确认)
  • 证据:
// astrbot.rs — 每次流从 1 重新计数
self.sequence = self.sequence.saturating_add(1);
let event_id = format!("astrbot-{}-{}", self.server_instance_id, self.sequence);
// astrbot_client.rs — 去重器却挂在 client 上跨请求存活
let mut mapper = AstrBotStreamMapper::new(server_instance_id.clone());  // 每次 send 新建
if !seen.insert(event_id.clone()) { continue; }                         // seen 构造于 client 创建时
  • 问题:AstrBotStreamMapper 每次 send_chat_stream 新建、sequence 归零,事件 ID 仅由 server_instance_id + 序号 构成;而 seen_event_ids(容量 4096)随 AstrBotClient 存活,runtime 发送后把同一 client 放回复用。第 1 条消息占用 astrbot-X-1..N;第 2 条消息的事件重新从 astrbot-X-1 开始 → 全部命中去重 → continue 静默丢弃,不进前端、不进数据库。同一连接从第二条消息起,助手回复整体丢失(除非新流事件数超过历史最大值,只透出错位尾部)。发送失败重试(attempts < 2)同样重建 mapper,连第一条消息的重试流也会被部分吞掉。所有现有测试均为"单 mapper 单流",故 Q9 门槛未拦截。
  • 修复:事件 ID 掺入每次请求的唯一盐(UUID / message_id),或把 sequence 提升为 client 级 AtomicU64;更干净的做法是对 astrbot 传输取消 event_id 去重(请求级 SSE 不存在重放,去重语义只对 desktop-v1 的 Last-Event-ID 成立)。必须补"同一 client 连发两条"回归测试。

P1:高危

A 组 · Rust 网络与运行时

P1-1 reqwest 全局 timeout 作用于流式响应:Desktop SSE 每 30 秒必断,AstrBot 长回复 120 秒被截 gateway_client.rs:100-101(.timeout(30s))、astrbot_client.rs:147-148(.timeout(120s))。Client::timeout 是"请求开始到响应体读完"的总时限,对 bytes_stream() 持续生效:desktop-v1 长连接永远处于 30 秒一断的重连循环(心跳无法续命);AstrBot 超过 120 秒的生成在中途被杀,并触发 P1-2 的整条重发。修复:流式端点使用不设总时限的专用 Client(空闲检测用 read_timeout / 心跳看门狗),仅普通 REST 保留总时限。

P1-2 流中途断开被当作"未送达"整条重发:服务端出现重复用户消息,前端流内容错乱 runtime.rs:647-653 + runtime.rs:724-725。should_retry_astrbot 把 Request(_) 一律判可重试,但该类错误既含"POST 未发出"也含"响应流读取中断"(网络抖动、P1-1 的 120s 超时)。后者重试= 同一条消息再次 POST /api/v1/chat(无幂等键),会话里出现重复提问与重复回答;两次尝试的 delta 交错,再叠加 P0-1 被部分吞掉。且首次尝试失败不调 finish_stream,前端残留半截流式气泡。修复:收到响应头/首字节后不再自动重发,改报可手动重试错误。

P1-3 SSE 字节流按网络 chunk 调 String::from_utf8_lossy:中文跨 chunk 必成 U+FFFD 乱码 astrbot_client.rs:462-463(buffer.push_str(&String::from_utf8_lossy(&chunk)))。TCP chunk 边界可落在任意字节,中文(3 字节/字)被切在字符中间即产生 <EFBFBD> 且随 delta 入库;断流/取消场景永久保留。这是面向中文用户客户端的高频显性缺陷。修复:以 Vec<u8> 缓冲,按 \n 字节分行后再做 UTF-8 解码(保留不完整尾字节)。

P1-4 activate_slot 持全局锁跨网络探测:一个槽激活会冻结两个槽的全部运行时命令,且激活不可取消 runtime.rs:197(加锁)→ :243 health().await / :298 probe().await(持锁 await)→ :325 drop(guard)。inner 是覆盖双槽的单一 tokio::Mutex,探测最坏耗时 = 120 秒;期间 status()(托盘 1s 轮询)、发送、断开、取消对两个槽全部阻塞——与"槽位隔离"目标直接冲突。connection_cancellation 在探测成功后才安装,激活过程无法被打断;启动自动连接串行走同一路径,一个坏 Profile 拖住整个 UI。修复:先置 Connecting 快照并释放锁,探测完按 generation 回写;激活伊始即安装取消令牌。

P1-5 未知事件类型被判终态 Incompatible,与协议文档"安全跳过"承诺相反 envelope.rs:227(UnsupportedEventType 报错)+ gateway_client.rs:282-284(Protocol(_) → Incompatible,停止重连)。docs/protocol/v1/README.md:28 承诺 "Unknown event types are … safely skipped"。网关新增任意事件类型(正常向后兼容演进)→ 槽位永久离线。同族问题见 P2-15(信封 deny_unknown_fields + Last-Event-ID 重放同一坏事件 → 重连永久卡死)。修复:对 UnsupportedEventType/InvalidPayload 做事件级跳过并推进 last_event_id,仅版本/身份不匹配保持终态。

P1-6 长会话历史加载取"最旧 N 条":超过 200 条后最新消息永远不可见 database/mod.rs:320:ORDER BY updated_at ASC LIMIT ?5(命令层默认 100、上限 200,无游标)。升序 + LIMIT 取的是最早的 N 条,长会话重启后只显示开头。修复:子查询取最新 N 条再正序返回,并补 before/after 游标分页。

B 组 · 契约失配(本次审计最大缺陷簇)

P1-7 zod .optional() ≠ Rust null 三连:事件、远端会话、能力三条链路静默失效 Rust 侧 Option<String> 无 skip_serializing_if → 序列化为 null;zod .optional() 只接受 undefined。三处失配(同文件上方 slotRuntimeSnapshotSchema 已全用 .nullish(),说明是"去信封化"后漏改):

失配点 位置 后果
boundRuntimeEventSchema.sessionId/messageId types.ts:35-36 vs gateway_client.rs:37-38 safeParse 失败 → 事件整条丢弃:desktop-v1/mock 事件(不带 session_id)100% 全丢;AstrBot 的 error/heartbeat/无 message_id 帧被丢 → 聊天错误不显示
remoteChatSessionSchema.displayName/updatedAt types.ts:62-65 vs commands.rs:542-548 任一会话字段为 None → 整个数组解析抛错被 .catch 吞掉 → 远端会话列表恒空(Q3.2 断裂)
astrbotModelOptionSchema types.ts:154-158 vs astrbot.rs:84-91 name:null → capabilities 解析失败 → 文件上传按钮永久禁用;且 Rust 无 rename_all,输出 is_default,前端期望 isDefault 恒丢

修复:前端三处改 .nullish() + Rust AstrBotModelOption 补 rename_all="camelCase"(或统一加 skip_serializing_if);safeParse 失败至少在 DEV 打 console.warn;用 Rust 真实序列化样本(含 null)做双端契约测试。

P1-8 connection-profile.schema.json 已漂移(缺 remoteDisplayName),且 schema 漂移检查未接入任何自动化 connection.rs:85 有 remote_display_name;schema 文件 0 处 remoteDisplayName 且顶层 additionalProperties:false ——按文档校验合法 profile 必失败。export_schemas 示例存在但无 CI/测试调用(全仓无 workflow 引用)。修复:重新 --write 导出;在 protocol_contract.rs 加"生成 schema ↔ 磁盘文件"比对断言,使 cargo test 即可拦截。

P1-9 附件字段不在已探明的真实 OpenApiChatRequest 契约内,可能被服务端静默忽略(置信度:中,需真机验证) astrbot.rs:75-76:顶层 attachments(元素还是 camelCase);而 docs/reports/astrbot-real-protocol-review.md:76-88 探明的请求模型无此字段,附件正道是 message 段数组内的 attachment_id(snake_case)段。FastAPI 默认忽略未知字段 → 上传成功但模型看不到文件,Q3.1 多模态闭环虚假成立(探针报告自己也注明"end-to-end image rendering… still require a real chat send")。修复:含附件时把 message 构造成段数组,用真实容器验证一次模型可见性。

C 组 · 前端

P1-10 listen() 注销竞态:StrictMode 下必现双监听 → 每个 delta 被应用两次 ChatPanel.tsx:144-155(同模式 App.tsx:391-399、DesktopPetView.tsx:46-82):cleanup 执行时 unlisten 仍是 undefined,promise 解析出的注销函数无人调用 → 首个监听器永久泄漏。main.tsx 确认启用 StrictMode(挂载即 mount→cleanup→mount):delta 逐字翻倍、消息重复;生产环境快速切页同样触发。修复:let active=true; listen().then(fn => active ? (unlisten=fn) : fn()); return () => { active=false; unlisten?.(); }。测试 setup 把 listen mock 成同步返回,恰好掩盖此竞态,需一并改为延迟 resolve。

P1-11 附件/草稿/错误状态不随槽位切换隔离:陪伴槽上传的附件会被发进运维槽 ChatPanel.tsx:80-82, 384-412:pendingAttachments 单一 state、切槽不清空,发送时按当前 selectedSlot 提交——附件却是按上传时槽位落到对端实例的。操作序列:陪伴上传 → 切运维 → 发送 → 串槽。draft、error 同样全局单串(运维报错横幅在陪伴槽仍显示)。与"双槽 UI 层隔离"边界直接冲突。修复:三者改 Record<ChatSlot, …> 或切槽清空。

P1-12 宠物素材包 manifest 校验正则写错:一切合法素材包被拒(含仓库自带示例) src/features/pet/types.ts:47:/^[^\\/:*?"<>|]+\\.(png|webp)$/i —— \\. 在正则字面量中= 「字面反斜杠+任意字符」,而字符类又排除反斜杠。node 实测:"aemeath-spritesheet.png" → false。PetPackImporter 功能整体不可用。修复:\\. 改 \.,并补一条 parse(内置 manifest.json) 单测。

P1-13 desktop-pet 窗口不在 capability 清单:桌宠全部 IPC 与事件监听被 Tauri ACL 拒绝 capabilities/default.json:5(windows: ["main","quick-chat","status-bubble"])vs tauri.conf.json(desktop-pet 随启动 create:true)+ lib.rs:35。桌宠的运行状态联动(文档声称已接入双槽状态)、拖动、右键菜单、偏好设置全部静默失败(void listen/invoke 吞掉 rejection)。修复:windows 数组加入 "desktop-pet"。

P1-14 生产 CSP img-src 缺 blob::发行版聊天附件图片全部被拦 tauri.conf.json CSP:img-src 'self' asset: http://asset.localhost data:;而 MessageContent.tsx:117 用 URL.createObjectURL 生成 blob: URL。dev 不注入 CSP,故本地开发发现不了。修复:img-src 补 blob:。

P1-15[安全]Markdown 链接 href 未做协议白名单:javascript:/data: 可直达 <a> MessageContent.tsx:66-72:href={link[2]} 原样透传,助手消息属不可信远端输入,本 webview 内 JS 可直达全部 Tauri IPC。渲染器其余部分全走 React 文本节点(无 dangerouslySetInnerHTML、正则无灾难回溯),唯一缺口是 href。实际可利用性取决于 WebView2 对 _blank+javascript: 的处理(纵深防御必修)。修复:new URL() 解析后仅放行 http/https,非法协议渲染为纯文本;rel 补 noopener。

P1-16 Tauri 结构化错误全部显示为 [object Object] ChatPanel.tsx:423-424 等 6 处 + SettingsPages.tsx:119-120:reason instanceof Error ? reason.message : String(reason),而 Rust RuntimeCommandError {code,message} 以普通对象 reject。任何发送/重连/停止失败,用户看到的都是 [object Object]。ProfileManager.tsx:689-702 已有正确的 errorMessage() 兜底——抽出共享即可。

P1-17 用户可见乱码文案与乱码无障碍名(历史 UTF-8 损坏残留) DesktopPetView.tsx:92/173/191(setSpriteError("????????") 等)、:198(aria-label="AstrBot ??")、App.tsx:451(Loading?)、:554(用 HTML 实体硬编码"桌面浮动")。与 docs/implementation-queue.md:104/171-182 的既有乱码同源。修复:恢复中文原文;CI 加 \?{2,} 扫描防回归。

D 组 · 安全

P1-18 脱敏正则漏"裸 token/JWT":诊断功能可把 JWT 原文回传 UI redaction.rs:91:自由文本正则候选只有 access_token/refresh_token/api_key/...,没有裸 token(结构化 is_sensitive_key 反而认 token,redaction.rs:68-85);bearer_regex 需 Bearer 前缀,无 JWT 形态兜底。生产日志 sink(logging.rs:18,known_secrets 为空)与 log_tail/config 诊断全靠此正则。实测路径:log-tail 一行 token=eyJ...、config 解析 .env/.yaml 里的 token: → JWT 原样回传前端,违反脱敏铁律。而 auth.rs 恰从响应 data.token 取 JWT,此 key 名正是高频形态。现有脱敏测试用 known-secret 做 canary,恰好掩盖了正则缺口。修复:候选加入裸 token(及 auth/id/session[_-]?token)+ JWT 形态正则 eyJ[\w-]+\.[\w-]+\.[\w-]+;YAML/INI/.env 增加结构化 key 脱敏(见 P2-11)。

P2:中危(31 项)

# 位置 问题(触发 → 后果) 修复方向
1 runtime.rs:469-477 switch_slot_session 二次加锁不校验 generation:期间槽被重置/重激活,旧 session 写入新代快照并回写 sticky_session_id(generation guard 声明的漏网点,send 路径有检查此处没有) 首锁捕获 generation,写前比较
2 astrbot_client.rs:456-459 取消/断流路径不调 finish_stream():DB 残留 streaming=1 半截消息,重启后重新显示"生成中",未读逻辑误判新未读 取消/错误路径统一 finish(Cancelled/Error)
3 commands.rs:643-647 + runtime.rs:568-588 发送先入库 user 行再校验/取 client:槽位忙、未连接等失败后消息仍留历史且无失败标记,重试成功再插新行成重复 校验通过、确认 client 后再持久化;失败回删或标记 error
4 commands.rs:459-461 vs slots.rs:44-47 probe_connection_slot 不查槽位分配表:同一 Profile 可同时激活双槽,ProfileAlreadyAssigned 策略被绕过,双向覆写同一 sticky_session_id;operations 切换守卫也管不到 probe 激活前校验槽表分配
5 astrbot_client.rs:128-133, 431-438 expected_server_instance_id 校验是死代码:Mutex 初始化为期望值后无任何写入点,比较恒 false —— 服务器身份校验呈"有校验"假象(AstrBot 无身份端点是客观限制) 删除死校验或接入可观测特征;文档明示身份为 URL 派生
6 astrbot_client.rs:383-388 download_attachment 先整体读入内存再查 16MiB 上限:异常/恶意服务端(尤其 allow_insecure_http 链路)可内存放大到 GB 级 先查 Content-Length,流式累读超限即断
7 gateway_client.rs:121-126 health() 不带 bearer(SSE 带):health 需鉴权则合法 token 恒 401;health 免鉴权则坏 token 激活照样成功,激活期 AuthExpired 分支形同虚设 health 与 SSE 一致附带 token
8 gateway_client.rs:237-238 run_reconnecting Ok 分支把退避重置回 100ms:服务端"接受即优雅关流"(LB 摘除/维护)时进入 ~10 次/秒热重连;与 P1-1 的 30s 超时叠加成周期性风暴 仅在"连接存活超阈值且收到过事件"时重置退避
9 profiles.rs:213-218 删除 Profile 不清理 Credential Manager:凭据引用(随机 UUID target)永久孤儿,应用内再无途径删除 删除前读取引用并 store.delete;启动时孤儿对账
10 auth.rs:13-20、credentials/mod.rs:11-20 承载明文 password/secret/totp 的 IPC 结构体裸 derive(Debug),与注释"never logged"矛盾;当前无 {:?} 调用点,属一步之遥的泄露隐患(SecretCredential 有手写红act Debug,标准不一致) 手写 Debug 或改 secrecy::SecretString
11 diagnostics/config.rs:213/232/259 YAML/INI/.env 只做正则脱敏(无结构化 key 脱敏,JSON/TOML 有):叠加 P1-18 正则缺口,token: 值可泄露 三格式补按 key 的行级结构化脱敏
12 database/mod.rs:524 vs 556 键模型不一致:chat_sessions 主键含 account_id(查询却不带),chat_messages 主键不含——account_id 处处硬编码 local-default,未来引入多账号即破隔离 统一键模型(都含或都删)
13 commands.rs:341 服务端省略 message_id 时 delta 落库以逐事件唯一的 event_id 兜底:一条回复被拆成 N 行消息(测试恒带 message_id 掩盖此路径;前端同款回退 ChatPanel.tsx:916-917) mapper 为无 id 流合成稳定流内 id
14 lib.rs:544-556 + commands.rs:267-278 事件通道双合法消费者(转发循环 vs drain 命令)互相抢事件,且 drain 路径不落库;双槽共享一条 256 深度队列,一槽洪峰背压另一槽(前端当前未调 drain,属暴露的 footgun) 移除 drain 或改广播;每槽独立通道
15 envelope.rs:171 + gateway_client.rs:177 信封及全部只读 payload deny_unknown_fields + Json 错误非终态:网关加一个附加字段 → 解析失败 → 以旧 Last-Event-ID 重连 → 服务端重放同一坏事件 → 永久卡死循环 非安全 payload 移除 deny(ToolProposal/Result 保留)或解析失败跳过并推进游标
16 astrbot.rs:17-43 vs DB/文档 TransportKind 两套线上拼写:serde/前端/schema 用 astr-bot-open-api,as_str()/parse()/SQLite/README 用 astrbot-openapi——两条通道暂各自闭环,任何交叉即断 统一 #[serde(rename)] 为 astrbot-openapi,同步前端 enum 与 schema
17 astrbot.rs:381-410, 429-444 mapper 边界:重复 complete 帧产生第二条 completed 事件;complete 后迟到 plain 会以尾块覆盖全文(丢字)——需服务端乱序才触发 complete 后记录 per-message 完成标记
18 astrbot.rs:336-353 非图片媒体(record/file/video)的 attachment_saved 被静默丢弃,机器人发的语音/文件用户完全不可见;pending_media 仅存一个,双图交错丢第一张 非图片输出通用占位标记;pending 改 FIFO
19 mock-gateway routes.rs:196-206、state.rs:161-173、config.rs:29-31 mock 三缺陷:broadcast Lagged 直接 continue(静默丢事件不断流,soak"无丢失"结论不可信);Last-Event-ID 未命中静默零重放(无 gap 信号);同类双实例 server_instance_id 恒等(身份校验失去分辨力) Lagged 改断流;未命中发 gap 事件;instance_id 掺端口
20 ChatPanel.tsx:73-74, 181-187, 264-293 未读三连:list 与 mark-read 竞态使徽标回弹不清;无活动会话时回退 storedSessions[0] 把从未打开的会话误标已读;他槽未读不随事件实时更新 mark-read 后再取列表;仅真实 activeSessionId 才标读;事件驱动他槽未读
21 ChatPanel.tsx:468-475 retryMessage 只滤 slot 不滤 session:切换会话后重试可把 A 会话的内容重发进 B 会话 加 sessionId === activeSessionId 过滤
22 ChatPanel.tsx:435-457 + runtime.rs:626-633 停止生成:已收半截内容被标 error:true 按失败样式渲染;Rust 取消返回 Err{code:"cancelled"} → 乐观用户消息也被标失败并弹横幅(叠加 P1-16 显示 [object Object]) 按 code 区分 cancelled;保留已收内容为正常消息
23 ChatPanel.tsx:920-925, 77 事件→消息归并键只用 slot+sessionId+id,丢弃事件自带的 profileId/serverInstanceId,与"四元组本地键"规范不符;同槽换绑 Profile 后迟到事件可并入新 Profile 消息流 归并键与 ChatMessage 补全二元组
24 styles.css:3116-3139 消息操作按钮 visibility:hidden + 依赖 :focus-within 显示 = 键盘死锁(不可聚焦 → 永不显示);触屏有兜底,桌面键盘没有 去掉 visibility,仅用 opacity/pointer-events
25 ChatPanel.tsx:607-620, 711-717 tablist:箭头切换不移动焦点(roving tabindex 失效);未选中 tab 的 aria-controls 指向不存在的 panel;aria-busy 挂在 aria-live 容器上,发送期间压制读屏播报 切换即 focus 目标 tab;panel 常驻;busy/live 分离
26 CredentialEnrollmentCard.tsx:34-80 登记/登录失败路径不清空 secret/password(明文留在 state 与受控 input DOM);invoke 返回值为全库唯二未过 zod 的裸类型断言 finally 清空;返回值补 schema
27 ChatPanel.tsx:343-354 首次 refresh() 失败即永不建立轮询("状态不可用"直到重挂载);且 snapshot schema .strict()——Rust 加任一字段即触发此永久离线路径 失败也建(退避)轮询;strict 失败要有兜底与告警
28 ChatPanel.tsx(全文件无 scroll 代码)、540-585 无自动滚动:流式生成发生在视口外;语音识别/朗读无卸载清理:切页后麦克风继续、onresult 向已卸载组件 setState、朗读不 cancel 底部锚点+接近底部才跟随;unmount 停止 recognition/synthesis
29 astrbot_client.rs:554-565 JWT exp 无时钟裕度(临期 token 过检后立即 401);缺 exp/解析失败一律 fail-open(有 401 兜底,可用性取向合理但窗口偏乐观) exp <= now+30s;不可解析打 debug 日志
30 DesktopPetView.tsx:139-148 + tauri.conf.json 桌宠挂载即以硬编码覆写窗口偏好(positionMode:"edge", monitorIndex:0, alwaysOnTop:true),应用内叠层模式也触发——用户设置被持续踩掉;且 alwaysOnTop:true(含 tauri.conf 默认)违反"气泡/桌宠不默认置顶"的产品红线(implementation-queue 隔离基线) embedded 跳过;读取既有偏好增量提交;默认置顶改 false
31 tauri.conf.json build 段 vs package.json 工程口径漂移:Tauri CLI 回调 npm run dev/build 而工程锁 pnpm@11.9.0(双包管理器混跑);engines 钉死 node >=24.17 <25 但 @types/node 是 24.13;文档口径 React 18 而实际 React 19.2.7 tauri.conf 改 pnpm;engines 对齐;文档更新

P3:低危与小缺陷(18 项)

# 位置 问题 建议
1 astrbot.rs:495-499, 449 所有 astrbot 事件 timestamp 恒为 1970-01-01T00:00:00Z,心跳 interval 硬编码 1000 调用方注入时钟
2 astrbot.rs:502-508 server_instance_id 用 DefaultHasher 派生并持久化,std 明示跨版本无稳定承诺——换工具链后同 URL 新旧键空间分裂(仓库已依赖 sha2) 改 sha2 截断 + 一次性兼容映射
3 astrbot_client.rs:544-552 urlencoding_username 对非 ASCII ch as u8 截断编码(潜在缺陷:当前被 profiles.rs:250-256 的 ASCII 校验挡住;一旦放宽用户名规则即升 P1,文档恰有"最终确定命名规则"待办) 改逐字节百分号编码
4 astrbot_client.rs:456-458 取消消息把连接状态置 Disconnected 再改回 Connected,托盘/前端可见闪烁 取消不动连接状态
5 tauri.conf.json + lib.rs:378-389 CSP connect-src 放行 http://127.0.0.1:*(渲染层可直连本地端口);check_network_target 向所有窗口暴露限速 TCP 探测——能力面收敛问题 生产移除 127.0.0.1:*;诊断目标限已存 profile host
6 auth.rs:179-198 凭据轮换顺序:先删旧、后写 DB——DB 更新失败时引用悬空需重新登录 写新→落库→删旧,失败回滚
7 runtime_guards.rs:28-51 operations 切换守卫无生产调用方(仅测试引用),connection_policy_status 上报一个永远解锁的守卫 工具管线落地时接线;先在状态中标注未激活
8 lib.rs:270-276 退出走 std::process::exit(0):跳过 Drop,遗留 -wal/-shm、可能丢最后一段日志 退出前 deactivate 双槽并 flush
9 astrbot.rs:267-269, 469-477 session_id 帧 data 为对象时会把整个 JSON 转储当会话 ID 持久化(现网帧形态未触发) Object 分支提取 session_id/id 键
10 App.tsx:129 独立桌宠窗口渲染 lazy 组件无 Suspense 边界(React 18+ 根级挂起容错=首帧空白而非白屏,但违反 React 文档要求且整根阻塞) 补 <Suspense fallback>
11 App.tsx:171 + 两套测试 导航图标未 aria-hidden,读屏播报"◎ 连接";e2e/单测硬编码含图标的可及名,换图标即双杀 图标 aria-hidden;选择器用语义文本
12 DesktopPetView.tsx:150-160 + styles.css:3086-3090 reduced-motion 未约束 JS 帧循环(setInterval 驱动,CSS animation:none 是死规则);image.onerror 未清理;canvas 未按 DPR 放大 matchMedia 停帧;补清理
13 ChatPanel.tsx:447/482/513 等 用户可见文案中英文混杂("Generation stopped." / "image loading" / 英文 aria-label 混在中文 UI 中) 统一文案表
14 App.tsx:562-567、SettingsPages.tsx:165-192、ProfileManager.tsx:570-575 死控件与标签错误:活动策略下拉无 onChange;jwt 认证显示为"设备 Token 引用";槽位状态裸英文枚举(ChatPanel 有中文映射未复用);诊断输入 Number() 产 NaN 直发后端 逐项补齐
15 soak.rs:101-103、dual_instance.rs:264 测试 SSE 助手只认 "data: "(带空格)且 .unwrap():axum 换排版即全挂成超时;acknowledged_event_ids 无界增长 strip_prefix("data:")+trim;ack 加上限
16 App.test.tsx:148-172 所有用例的 mock 缺 close_pet_window → 全局错误横幅由旁路触发,"IPC 不可用"断言存在假阳性通道 mock 补齐;断言具体文案
17 tsconfig.app.json、eslint.config.js、vite.config.ts 缺 noUnusedLocals/noUncheckedIndexedAccess;关闭 react-hooks/set-state-in-effect 且无 jsx-a11y;usePolling:true 白耗 CPU;vitest 无 coverage 配置 逐项收紧
18 mock routes.rs:178-188 订阅与重放快照的间隙内事件双下发(at-least-once);并发 publish 广播顺序可与 sequence 倒置——mock 内部竞态,单线程测试不触发 push+send 同临界区或文档注明

三、代码优化建议

性能热点(按收益排序)

  1. 前端渲染管线:ChatPanel 每 500ms 全量轮询 connection_runtime_status 且 setStatus 恒新引用 → 整面板重渲染;activeMessages 的 useMemo 依赖整只 status 对象每轮失效;MessageContent 无 React.memo,每轮全量重新解析 Markdown;applyRuntimeEvents 对每个 delta 全量浅克隆消息数组;messages 跨会话驻留从不修剪。修法集中且低风险:依赖改标量(activeSessionId)、React.memo、命中才克隆、轮询改事件驱动或放宽。
  2. spritesheet 内联:DesktopPetView.tsx:10 以 ?inline 把 1536×3120 PNG(磁盘 3.9MB,base64 后 ~5.2MB)内联进 lazy chunk;同目录已有 573KB 的 WebP 却未使用(manifest 与 import 都指 PNG)。改普通资源引用 + WebP,chunk 直降 ~90%,"代码分割"收益才真正成立(app-ui 模式主窗口默认也会加载该 chunk)。
  3. 附件二进制走 JSON IPC:前端 Array.from(new Uint8Array(...)) + Rust Vec<u8>——16MiB 文件变 ~1670 万元素数字数组(膨胀 3–4 倍、主线程长任务、Rust 侧再 bytes.clone() 一份)。Tauri 2 原生支持 raw body / tauri::ipc::Response 二进制通道,上传下载双向改造。
  4. 轮询叠加:StatusBubble 每 1s 发 3 个 invoke、托盘 1s 轮询、ProfileManager 2s 轮询——统一改为订阅 connection-runtime-event + 低频兜底。
  5. styles.css 分层腐化:3388 行按五代叠写(基础层→OS 亮色媒体查询→data-theme 手工枚举→--ui-* token→触控层),约 40% 是被覆盖的死层;.chat-error 定义 5 次;--muted-text/--ink/--accent 等幽灵 token 全库无定义永走 fallback(暗色气泡里链接恒亮色)。建议以 --ui-* 为唯一 token 源做一次合并,删除 OS 亮色块,引入 stylelint 防回归。

结构与架构

  • 事件出口:单条 256 深度 mpsc + 双消费者设计(见 P2-14)改为"每槽独立通道 + 唯一持久化点 + 广播 emit",同时消除背压串扰与丢事件 footgun。
  • 发送期客户端独占:send 用 client.take() 令并发的 sessions/capabilities/upload/download 在长流期间全部误报"未连接"(AstrBotClient 本身可 Clone)。改 clone + 以 message_cancellation 存在性串行化发送。
  • 错误展示层:抽出共享 errorMessage()(识别 {code,message}),ChatPanel/SettingsPages/CredentialEnrollmentCard 统一接入(P1-16 的治本)。
  • 契约治理(本次教训的制度化):Rust 序列化输出 → JSON 样本夹具 → 前端 zod 契约测试三点一线;export_schemas 比对进 cargo test;TransportKind 拼写统一后在 CI 加 grep 断言。

四、功能实现完整度

4.1 对照 13 项 roadmap 声明(implementation-queue.md 2026-07-21)

# 声明 代码现状 判定
1 启动自动连接 已实现(逐 profile 独立 try、日志只记类别);但串行 + 全局锁使"逐槽独立"在时间上不成立(P1-4),无前端提示(文档已自认) ⚠️ 基本成立
2 凭据轮换 + JWT 主线成立(Credential Manager、一次性 secret、JWT 登录/过期识别/重登录提示);隐患:Debug 派生(P2-10)、孤儿凭据(P2-9)、轮换顺序(P3-6) ⚠️ 基本成立
3 服务器身份保护 desktop-v1 侧成立(bind 强校验);AstrBot 侧是死代码(P2-5),身份仅 URL 哈希派生 ❌ 部分虚假
4 快速聊天窗口 单实例、几何持久化、夹取、共享 runtime 均在,质量好 ✅
5 托盘与状态气泡 成立;气泡走 1s 轮询(优化项) ✅
6 桌宠状态与素材 三处断裂:capability 缺失致事件联动全哑(P1-13)、素材导入正则全拒(P1-12)、偏好被硬编码覆写且默认置顶违反产品红线(P2-30) ❌ 名存实亡
7 多显示器/游戏策略 几何、安全边、受限前台/进程检测在;游戏模式切换依赖的 pet 窗口 IPC 因 P1-13 失效 ⚠️
8 语音交互(Web Speech MVP) 可用;无卸载清理(P2-28)、朗读读原始 Markdown ⚠️
9 主动消息 事件类型与未读持久化在;AstrBot 传输无后台事件流,proactive 实际仅 mock 可达——对真实服务器该功能不可用 ❌ 仅 mock 成立
10 聊天可靠性 会话隔离持久化与切换去重在;但 P0-1、P1-2/3/6、P2-2/3/13 直接命中此项 ❌ 与声明差距最大
11 日志/诊断脱敏 机制健全;裸 token/JWT 缺口(P1-18)、YAML/env 弱脱敏(P2-11) ⚠️
12 Release 构建 成立(unsigned NSIS) ✅
13 验收覆盖 门槛存在但关键路径全在盲区(见第五节) ⚠️

4.2 安全铁律符合性

铁律 判定 备注
凭据只进 Credential Manager,不入 DB/日志/前端 ⚠️ 主线成立 缺口:P1-18、P2-10、P2-9
日志必须脱敏 ❌ 有实洞 裸 token=/JWT 可原文透出(P1-18)
不暴露任意 Shell ✅ 全仓 0 处 Command/ShellExecute
文件事务 plan→dry-run→确认→复制→校验→原子提交、保源不覆盖 ✅ 名副其实;暂停残留 .part 为小疵
本地键 ≥ profile_id+server_instance_id+conversation_id ✅ 数据层 / ⚠️ UI 层 DB 主键超额达标;前端归并键丢二元组(P2-23)
companion 默认无本机工具权限;operations 六道闸门 ➖ 工具执行管线未开始(与"暂不进入实现"一致);闸门零代码,实现前不得放开能力面;guard 空转(P3-7)
气泡/桌宠不默认置顶 ❌ desktop-pet 窗口与偏好硬编码 alwaysOnTop:true(P2-30)

4.3 "名存实亡"清单(有 UI/字段/命令,无实际效果)

证书指纹绑定(录入校验齐全、TLS 验证零接入,用户获得虚假安全感——文档列为外部前置,但录入通道已开放,建议标注"暂不生效");AstrBot 服务器身份校验(P2-5);operations 切换守卫(P3-7);drain_connection_runtime_events 命令(前端不用,用则丢事件+丢持久化);远端会话列表与模型能力(被 P1-7 契约失配掐断);桌宠事件联动与素材导入(P1-12/13);"活动策略"下拉(P3-14)。


五、测试覆盖缺口

现状:Rust 工作区 67 测试(DB 迁移/未读/delta 合并/槽隔离、profile/slot/credential IPC、redaction、mapper 单流 8 例、mock 双实例集成)+ Vitest 9 + Playwright 5,全绿。全绿与带病并存的原因是关键路径系统性缺位:

  1. astrbot 传输零集成测试——没有任何测试起假 /api/v1/chat SSE 服务端跑 AstrBotClient。P0-1、P1-2/3、P2-2 全在盲区。最小补法:同一 client 连续两次 send_chat_stream 的单测即可暴露 P0-1。
  2. 契约测试缺 null 样本——types.test.ts 恰好没测 sessionId:null/displayName:null/name:null;一条"用 Rust 真实序列化输出回放"的测试可拦下全部 P1-7。建议以 serde_json 快照做双端共享夹具。
  3. ChatPanel 零测试(最重组件):delta 归并、切槽隔离、未读清零、重试/停止边界、附件上限。
  4. 脱敏测试用 known-secret 做 canary,掩盖了正则不认裸 token 的事实(P1-18);需要"无 known_secrets 下 token=<jwt> 必须被脱敏"的断言。
  5. DualSlotRuntime 仅 2 个参数校验测试:无 activate/send/cancel/switch 竞态、无"激活期间另一槽命令阻塞"回归(P1-4、P2-1)。
  6. 未知事件类型/附加字段的客户端行为无测试(P1-5、P2-15);Last-Event-ID 断点续传虽有 mock 支持但客户端请求头未被断言;重连退避行为(P2-8)无测试。
  7. listen 的 mock 同步返回 cleanup,掩盖注销竞态(P1-10)——改为延迟 resolve 并断言注销次数。
  8. petPackManifestSchema.parse(内置 manifest.json) 一条测试即可抓住 P1-12;MessageContent 的 javascript: 链接、未闭合代码块也应有用例。
  9. 长会话(>200 条)分页顺序无测试(P1-6);缺 message_id 的流式帧无测试(P2-13)。
  10. soak 断言只有计数+身份,不校验 sequence 单调无缺口——mock 的 Lagged 静默丢失(P2-19)不会使其失败,"30 分钟无丢失"结论目前不可信。

六、修复路线图

第一批 · 发布阻断(建议本周内,全部为小改动) P0-1(事件 ID 加盐/去重下沉)→ P1-7 三连 .nullish() + rename_all → P1-1 流式专用 Client → P1-12 正则一字符 → P1-13 capability 加一行 → P1-14 CSP 加 blob: → P1-15 href 白名单 → P1-16 errorMessage 共享 → P1-17 乱码文案。同批补三条回归测试:同 client 连发两条、null 契约回放、manifest 自解析。

第二批 · 正确性与安全(进入 alpha.3 前) P1-2 重试语义收窄、P1-3 UTF-8 字节缓冲、P1-4 探测出锁+可取消、P1-5/P2-15 未知事件跳过、P1-6 历史取最新 N、P1-10 listen 竞态、P1-11 附件/错误按槽隔离、P1-18+P2-11 脱敏补洞、P2-2 finish_stream、P2-3 先校验后入库、P2-20/21/22 未读与重试/停止链路、P2-30 置顶红线。

第三批 · 健壮性与工程化 其余 P2/P3、性能五热点、契约治理制度化(schema 比对进 cargo test、TransportKind 统一、双端夹具)、mock 网关三缺陷、测试缺口按第五节补齐。


附录 A · 已剔除的误报与降级说明

原始发现 处理 理由
"aemeath-spritesheet.png / src-tauri/icons 缺失,构建必败" 剔除 审计快照未包含二进制资源;设备上文件实际存在(PNG 3.9MB、WebP 573KB、icons 全套)。保留的是 ?inline 体积问题(优化 §2)
"桌宠窗口无 Suspense → 白屏"(P0) 降级为 P3-10 React 18+/createRoot 对初次挂载的根级挂起会延迟提交(短暂空白后正常渲染),非崩溃;仍建议按 React 文档补边界
"username 百分号编码截断 → 会话串线"(P1) 降级为 P3-3 profiles.rs:250-256 强制 remote_username 为 ASCII 字母数字 3–32 位,非 ASCII 分支当前不可达;属纵深缺陷,放宽命名规则前必须先修
"AstrBot 附件字段被服务端忽略" 保留为 P1-9,置信度中 依据为仓库内真实协议探针文档的字段清单,静态审计无法接触真实服务器终证;已注明需真机验证

附录 B · astrbot SSE 映射器边界推演摘要

对 astrbot.rs 状态机手工推演 14 组输入序列的结论:纯 complete、纯 delta+finish、delta+complete reconcile、空 complete、跨消息切换、error 携带部分文本——均正确;重复 complete(事件层重复)、complete 后迟到 plain(尾块覆盖全文)、缺 message_id(每 delta 一气泡)、多行 data / 坏 JSON 行(整流中止且无 completed)、同 client 二次发送(P0-1)——均有缺陷,已分列 P0-1、P2-13/17、P1 组。取消与解析错误两条路径不调 finish_stream 是悬挂 streaming 状态的共同根因。

附录 C · Mock 网关与真实 AstrBot 的关键差异(影响测试可信度)

流模型(长连+重放+ack vs 请求级 SSE 无重放——基于 mock 验证的重连/续传/去重对 astrbot 传输完全不适用,P0-1 因此漏网);事件 ID(服务端单调分配 vs 客户端合成每请求复位);消息形态(mock 永不出现纯 complete/无终止帧/error/attachment_saved);认证(双 token+refresh vs 静态 Key/7 天 JWT,refresh 代码对真实后端是死路径);身份(/server-info 权威 vs URL 哈希自证);会话(无列表 vs username+session 双键有列表);工具流(mock 周期推 tool.proposal,现网不存在)。结论:凡只被 mock 集成测试覆盖的行为,对真实 AstrBot 都应视为未验证。

附录 D · 审计方法与覆盖率

设备快照(2026-07-26 拉取)→ 云端工作区重建目录树 → 4 路并行深度静审(每路独立通读职责文件全文并给出逐字证据)→ 主审对全部 P0/P1 与关键 P2 回读源码逐条复核(含 1 项 node 运行时实测、2 项跨路交叉印证)→ 按"宁缺毋滥"原则合并去重。因目标平台为 Windows,本环境未执行编译与测试套件;windows-rs unsafe 调用(credential_manager/capture/uia/event_log)为人工推演,结论为"未见泄漏/越权,质量高",建议在 Windows CI 补运行时验证。行号基于 2026-07-21/22 版本文件,后续提交可能偏移。