# 错题本 ## 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 构建;产品逻辑无改动。