# AstrBot Desktop 全源码审查档案 全源码审计 · 2026-07-26 > 配套修复队列:[fix-queue-2026-07-26.md](./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`(两路审计独立发现,已人工复核确认) - 证据: ```rust // 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 字节/字)被切在字符中间即产生 `�` 且随 delta 入库;断流/取消场景永久保留。这是面向中文用户客户端的高频显性缺陷。修复:以 `Vec` 缓冲,按 `\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` 无 `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` 或切槽清空。 **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:` 可直达 ``** `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 文档要求且整根阻塞) | 补 `` | | 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`——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=` 必须被脱敏"的断言。 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 版本文件,后续提交可能偏移。