离屏 UGUI 截图工具：不依赖窗口可见性的截图通道（技术验证已通过）

[RoyougiShiki]

背景

当前 game_view_pixels 截图依赖窗口帧缓冲（GrabPixels），窗口被遮挡/后台/最小化时不可靠（截图可能读到其他窗口画面或空白帧）。需要一条不依赖窗口可见性的 UGUI 截图通道（对标 Tuanjie 进程内 AI 的能力）。

技术验证（已完成 ✅）

隔离工程 + Unity 2020.3.24f1 实测：

• 方法：临时把 Overlay Canvas 切到 ScreenSpaceCamera + 临时正交相机 targetTexture=RenderTexture → 主动 camera.Render()（不依赖播放循环/窗口呈现）→ 读 RT 像素
• 前台：RT 红色占比 100%（全屏 UGUI 完整渲染）
• 窗口最小化后：RT 红色占比 100% —— 证明离屏 UGUI 渲染完全不依赖窗口可见性
• 临时验证脚本已清理（临时项目已删除）

目标

把离屏渲染做成正式 MCP 工具，让 UGUI 截图在窗口遮挡/无人值守时可靠。

方案（推荐）

• 扩展 manage_camera screenshot 的 capture_source（新增值如 game_view_offscreen），与现有截图体系一致，不新增大工具
• C# 侧：临时切 Canvas.renderMode → ScreenSpaceCamera + 临时相机 targetTexture → camera.Render() → ReadPixels 读回 → try/finally 恢复原 renderMode
• 仅处理 Screen Space Overlay 的 Canvas（已在 Camera/WorldSpace 模式的走现有相机渲染路径）
• 分辨率：与 GameView 当前分辨率一致

验收标准

1. 窗口最小化/遮挡时，离屏截图包含 UGUI（像素断言）
2. Canvas 原状态完整恢复（renderMode/worldCamera/planeDistance）
3. pytest 全量通过 + Unity 2020.3 编译验证（UNITY_EXIT=0）
4. 新参数按仓库约定登记 test_tool_annotations.py

待决策点（附推荐，实现时可按推荐执行）

1. 入口形态：扩展 capture_source vs 新工具 → 推荐扩展 capture_source（与现有体系一致）
2. 副作用容忍：切换 renderMode 有瞬时闪动 → 推荐可接受（try/finally 保证恢复）
3. Canvas 范围：只 Overlay，Camera/WorldSpace 走相机渲染 → 推荐
4. 分支：在 feat/wait-for-idle 上迭代（默认分支）→ 推荐

参考

• 协作约定与背景：docs/DEVELOPMENT.md、CLAUDE.md（Collaboration & Git Workflow）
• 已知环境坑：编辑器后台渲染/截图不可靠、runInBackground 语义