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>
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 同临界区或文档注明 |
三、代码优化建议
性能热点(按收益排序)
- 前端渲染管线:
ChatPanel每 500ms 全量轮询connection_runtime_status且setStatus恒新引用 → 整面板重渲染;activeMessages的useMemo依赖整只status对象每轮失效;MessageContent无React.memo,每轮全量重新解析 Markdown;applyRuntimeEvents对每个 delta 全量浅克隆消息数组;messages跨会话驻留从不修剪。修法集中且低风险:依赖改标量(activeSessionId)、React.memo、命中才克隆、轮询改事件驱动或放宽。 - 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)。 - 附件二进制走 JSON IPC:前端
Array.from(new Uint8Array(...))+ RustVec<u8>——16MiB 文件变 ~1670 万元素数字数组(膨胀 3–4 倍、主线程长任务、Rust 侧再bytes.clone()一份)。Tauri 2 原生支持 raw body /tauri::ipc::Response二进制通道,上传下载双向改造。 - 轮询叠加:StatusBubble 每 1s 发 3 个 invoke、托盘 1s 轮询、ProfileManager 2s 轮询——统一改为订阅
connection-runtime-event+ 低频兜底。 - 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,全绿。全绿与带病并存的原因是关键路径系统性缺位:
- astrbot 传输零集成测试——没有任何测试起假
/api/v1/chatSSE 服务端跑AstrBotClient。P0-1、P1-2/3、P2-2 全在盲区。最小补法:同一 client 连续两次send_chat_stream的单测即可暴露 P0-1。 - 契约测试缺 null 样本——
types.test.ts恰好没测sessionId:null/displayName:null/name:null;一条"用 Rust 真实序列化输出回放"的测试可拦下全部 P1-7。建议以 serde_json 快照做双端共享夹具。 - ChatPanel 零测试(最重组件):delta 归并、切槽隔离、未读清零、重试/停止边界、附件上限。
- 脱敏测试用 known-secret 做 canary,掩盖了正则不认裸 token 的事实(P1-18);需要"无 known_secrets 下
token=<jwt>必须被脱敏"的断言。 DualSlotRuntime仅 2 个参数校验测试:无 activate/send/cancel/switch 竞态、无"激活期间另一槽命令阻塞"回归(P1-4、P2-1)。- 未知事件类型/附加字段的客户端行为无测试(P1-5、P2-15);Last-Event-ID 断点续传虽有 mock 支持但客户端请求头未被断言;重连退避行为(P2-8)无测试。
listen的 mock 同步返回 cleanup,掩盖注销竞态(P1-10)——改为延迟 resolve 并断言注销次数。petPackManifestSchema.parse(内置 manifest.json)一条测试即可抓住 P1-12;MessageContent 的javascript:链接、未闭合代码块也应有用例。- 长会话(>200 条)分页顺序无测试(P1-6);缺 message_id 的流式帧无测试(P2-13)。
- 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 版本文件,后续提交可能偏移。