# 错题本 ## 2026-07-27 — 屏幕感知规划阶段复盘 - 阶段:陪伴体验页面拆分与屏幕感知规划 - 类型:API契约 / 功能行为 - 现象:用户需求中的“随机捕捉屏幕”若直接理解为任意全屏抓取,会绕过当前只允许单窗口显式授权的架构边界,并可能把随机目标、随机时机和游戏捕获混为同一能力。 - 根因:产品词汇未区分“随机何时触发”与“允许捕获什么范围”;现有 GDI 捕获也不能代表硬件加速游戏画面。 - 修复或规避:建立 PD-0014;规划中将随机限定为时间判定,V1 仅使用已授权前台窗口;全屏范围与 WGC 游戏捕获分别设置为独立 Spike/决策门。 - 预防规则:涉及屏幕、音频、输入或跨设备数据时,先写清捕获范围、授权生命周期、可见指示、存储边界、发送目标和失败降级,再排入实现队列。 - 验证证据:docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md、docs/decisions/pending-decisions.md 的 PD-0014;本次未写产品代码。 ## 2026-07-27 — 全桌面方向的实施闸门 - 阶段:屏幕感知产品决策 - 类型:功能行为 / 安全边界 - 现象:产品所有者选择了全桌面方向(PD-0014 方案 B),若把选择误当作立即扩大捕获权限,会绕开对多显示器、锁屏、受保护内容、敏感应用和硬件加速画面的验证。 - 根因:产品范围决策与技术可行性/安全验收是两个独立闸门;全桌面与游戏窗口都不能由现有 GDI PrintWindow 可靠覆盖。 - 修复或规避:将方案 B 记录为设计方向,而非实现放行;队列要求 WGC、范围专属授权、可见指示/停止、Companion-only 和真实 AstrBot 图片验收全部通过后才开发捕获或调度。 - 预防规则:用户选择扩大范围时,记录为“方向已定 + 闸门未过”,并把每个闸门写入队列和验收证据,不能用产品批准替代安全/可行性验证。 - 验证证据:PD-0014、docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md、docs/implementation-queue.md;本次未写产品代码。 ## 2026-07-27 — 临时参考源码不应进入项目 lint 范围 - 阶段:C1 陪伴入口页面壳验证 - 类型:测试 / 环境 - 现象:全仓 lint 扫描到项目 .tmp/refs 下为调研而浅克隆的第三方插件 JavaScript,产生 322 个与本项目无关的 no-undef 等错误。 - 根因:.tmp 目录未被 ESLint 忽略;调研副本保留在工作区时会被全仓规则当作产品源码处理。 - 修复或规避:在参考提取完成后,验证路径位于项目 .tmp/refs 内并删除该临时克隆;随后 lint 通过。 - 预防规则:外部临时参考应放在 lint 排除目录或在运行全仓检查前清理;不得为了第三方源码而放宽项目 ESLint 规则。 - 验证证据:删除 D:\CODEX\projects\AstrBot-Desktop\.tmp\refs\astrbot_plugin_screen_companion 后,npm.cmd run lint 通过。 ## 2026-07-27 — 导航图标必须是装饰性内容 - 阶段:C1 陪伴入口页面壳 - 类型:功能行为 / 可访问性 - 现象:主导航图标与文字共同组成按钮可访问名称,测试和读屏依赖图标字符;更换图标会同时破坏语义和测试选择器。 - 根因:图标 span 未声明 aria-hidden,导致装饰性字符进入无障碍名称计算。 - 修复或规避:将导航图标设为 aria-hidden,并把测试定位改为文字标签;新增语音聊天和游戏陪玩导航回归测试。 - 预防规则:纯装饰图标一律 aria-hidden;交互元素用可读文字或显式 aria-label 提供稳定名称,测试不得依赖视觉符号。 - 验证证据:src/App.test.tsx 通过;npm.cmd run test 为 60/60 通过。 ## 2026-07-27 — 把“定时截图”误当作“活动理解” - 阶段:屏幕感知方案 B 规划复核 - 类型:功能行为 / API契约 - 现象:仅有截图上传、HTTP 成功或附件上传成功时,容易误称 Bot 已经理解用户当前活动;GDI `PrintWindow` 对硬件加速游戏还可能产出黑帧。 - 根因:没有将范围授权、帧质量、最小上下文、视觉模型能力、场景去重和主动回应拆成独立可验证的门。 - 修复或规避:新增 `docs/reports/screen-awareness-understanding-framework-2026-07-27.md`,把 WGC Spike 和真实 AstrBot 视觉验收设为全桌面/游戏功能的前置停止条件。 - 预防规则:后续不得以请求成功、上传成功或单张图片测试替代“模型看图并理解”的真实验收;任何自动观察先通过本地策略与质量门。 - 验证证据:框架定义 S0-S5 阶段、附件段契约、Companion-only 约束、黑帧拒绝和真实服务端视觉验收。 ## 2026-07-27 — 懒加载页面的启动集成测试不能依赖默认五秒 - 阶段:C1 陪伴入口页面壳提交前验证 - 类型:测试 / 功能行为 - 现象:新增独立懒加载页面后,既有的“Rust 启动状态”集成测试在受限 Windows 环境中稳定略过 Vitest 默认五秒;它点击诊断页后也没有等待目标页面就绪。 - 根因:测试把页面切换、懒加载和异步 bootstrap IPC 都压在默认预算内,并以未等待的导航操作开始后续断言。 - 修复或规避:诊断页 helper 改为等待目标标题,调用方显式等待;仅该启动集成测试预算设为十秒,不调整全局测试配置或产品代码。 - 预防规则:涉及懒加载页面切换的集成测试必须等待可见的页面就绪信号;单条跨异步边界测试应声明与其真实链路匹配的局部预算。 - 验证证据:修复后运行完整 Vitest、ESLint、TypeScript 和生产 Web 构建;产品逻辑无改动。 ## 2026-07-27 — 不能把“当前前台窗口”当成长期授权范围 - 阶段:屏幕感知三档范围规划 - 类型:功能行为 / 安全边界 - 现象:若自动观察始终读取当前前台窗口,用户切换到聊天、浏览器或敏感工具时,实际捕获目标会在没有新授权的情况下变化。 - 根因:把“识别当前窗口”误用为“自动跟随当前窗口”,没有将用户选择的捕获范围绑定为稳定授权令牌。 - 修复或规避:将范围明确为指定窗口、指定显示器、全部显示器三档;窗口身份或显示器拓扑变化时撤销会话,调度器只复用已授权范围。 - 预防规则:任何自动观察不得根据前台变化自行更换目标;范围变更必须先停止、再显示专属同意、再重新授权。 - 验证证据:PD-0014、screen-awareness-understanding-framework、实施队列 S0/C2/C4 均更新为三档范围验收。 ## 2026-07-27 — WGC interop types are not the Win32 aliases - 阶段:S0.1 WGC 目标绑定预检 - 类型:编码 / Windows API 契约 - 现象:首次编译 WGC 显示器预检时,`BOOL` 从 `Win32::Foundation` 导入失败,`GraphicsCaptureItem::Size` 也不能直接传给内部尺寸检查。 - 根因:windows-rs 将此回调的 `BOOL` 暴露在 `windows::core`,而 WinRT `SizeInt32` 与内部 `WgcSize` 是不同类型,不能依赖隐式转换。 - 修复或规避:改用 `windows::core::BOOL`,并对窗口和显示器的 `Size()` 结果显式 `.into()`。 - 预防规则:新增 WinRT/WGC 调用先以隔离 `cargo check` 验证每个特征门和跨命名空间类型;相同 API 的两个分支必须保持相同的显式转换。 - 验证证据:`cargo check -p astrbot-desktop --lib` 通过;`cargo test -p astrbot-desktop --lib` 117 passed。 ## 2026-07-27 — 隔离 Cargo 目标的冷启动不能按短超时判失败 - 阶段:S0.1 WGC 目标绑定预检 - 类型:测试 / 环境 - 现象:首次在新的 `src-tauri/.tmp/wgc-check` 目标目录运行 Rust 测试超过两分钟而被调用超时。 - 根因:隔离目标目录需要重新编译完整 Tauri 依赖图;这不是测试失败,且默认目标目录仍受 UNC 生成权限文件的访问拒绝影响。 - 修复或规避:保留项目内隔离目标缓存并以足够时限重跑;最终 117 个库测试全部通过。 - 预防规则:默认目标触发 UNC `os error 5` 时,使用已验证的项目内 `CARGO_TARGET_DIR`;首次冷启动须看退出码和最终测试结果,不能把工具超时当作断言失败。 - 验证证据:隔离 `cargo check` 和后续 `cargo test -p astrbot-desktop --lib` 均成功。 ## 2026-07-27 — WGC frame availability must have an explicit bounded timeout - 阶段:S0.2 WGC 单帧 D3D11 质量诊断 - 类型:功能行为 / Windows API 契约 - 现象:`TryGetNextFrame()` 在第一帧尚未到达时会返回失败,不能把首次失败当作捕获不可用,也不能无限轮询。 - 根因:free-threaded frame pool 启动后,帧到达与调用时刻异步;无帧与永久等待都是正常风险。 - 修复或规避:注册 `FrameArrived` 事件并只等待 2 秒,到期返回明确的 `FrameTimedOut`;每次退出移除事件并关闭 frame/session/pool,避免留存捕获资源。 - 预防规则:所有主动捕获路径必须有帧、尺寸、内存和生命周期上限;超时是可解释拒绝,不得重试成后台观察。 - 验证证据:Rust 121 个库测试通过,Clippy 通过;真实 Windows 场景证据仍待人工验收。 ## 2026-07-27 — Metadata result and global notice can intentionally repeat safety copy - 阶段:S0.3 手动 WGC 验收入口 - 类型:测试 / 功能行为 - 现象:首版组件回归用唯一文本查询 `未保存、未发送`,但结果卡和全局通知都故意说明同一隐私保证,测试失败。 - 根因:断言把可访问的重复安全文案误判为重复渲染;两个位置承担不同作用,前者解释帧结果,后者提供操作反馈。 - 修复或规避:改为断言结果卡独有的尺寸元数据,并继续断言没有调用上传或消息发送命令。 - 预防规则:涉及隐私/安全说明时,允许局部结果和全局反馈重复关键保证;测试应定位结构化状态或唯一业务数据,而不是假设文案唯一。 - 验证证据:前端 61 项测试、类型检查和生产构建通过。