11 KiB
11 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,而 WinRTSizeInt32与内部WgcSize是不同类型,不能依赖隐式转换。 - 修复或规避:改用
windows::core::BOOL,并对窗口和显示器的Size()结果显式.into()。 - 预防规则:新增 WinRT/WGC 调用先以隔离
cargo check验证每个特征门和跨命名空间类型;相同 API 的两个分支必须保持相同的显式转换。 - 验证证据:
cargo check -p astrbot-desktop --lib通过;cargo test -p astrbot-desktop --lib117 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 项测试、类型检查和生产构建通过。
2026-07-27 — One usable WGC window is not game-support evidence
- 阶段:S0.4 WGC 人工窗口验收
- 类型:功能行为 / 验收边界
- 现象:用户对 ChatGPT 普通窗口的手动验收返回
usable非空帧(3490×1889,4311 KB)。 - 根因:该结果只覆盖当前普通窗口和当前 Windows 会话;它不代表 DirectX/Vulkan、最小化、锁屏、受保护内容或显示器路径具有相同行为。
- 修复或规避:将证据记录为普通窗口单项通过,保留其余 S0 场景为独立阻塞门;界面不因这次成功改变游戏陪玩状态。
- 预防规则:不得将单一窗口成功泛化为全桌面或游戏支持;每个捕获范围和失败条件都需要可复核的单独证据。
- 验证证据:用户提供的任务截图显示 WGC 非空帧结果,且 UI 明确提示未保存、未发送。