AstrBot-Desktop/docs/错题本.md
YokiiroBW dfc26aa37e
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(awareness): probe WGC capture targets
2026-07-27 14:46:27 +08:00

8.3 KiB

错题本

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 均成功。