PLAN — SAM3 作为 RenderDoc MCP/Skill 的 Perception Layer

目标仓库：/home/hangyu5/Documents/Gitrepo-My/RenderDocSAM（本仓库）消费方：/home/hangyu5/Documents/Gitrepo-AI/renderdoc-skill（skill + MCP + 设计文档）关联设计：renderdoc-perception-agent-design.md（Perception Agent Harness 平移：annotate → generate → verify → recover → report）状态：v3.1（2026-08-24）——v2 首轮自评、v3 二轮 review（SAM3 API 事实更正 + Phase 3–6 重构 + 非目标清单）、 v3.1 模式 C 校准提前到 Phase 1（存在性测试）。历史版本与推翻记录归档于 OUTDATED.md，修订摘要见 §10。

0. 一句话总结

把 SAM3 当作 Perception-Agent 映射里的 Annotator + L2 视觉验证器： LLM 负责"猜哪里不对 / 想验证什么"，SAM3 负责把猜疑落地成像素级 mask / bbox / 质心坐标，再把坐标直接喂给现有 rdc-cli / MCP 的 pick-pixel、pixel history、debug pixel、rt/texture 导出，让"看图说话"变成"结构化、可回查、可自动化"的调试循环。

本质定位：SAM 是 grounding 层，不是 reasoning 层。 它不能判断"画面坏了"，但它能把 "用户/LLM 指的区域"和"before/after 的差异区域"变成 RenderDoc 能消费的精确坐标与 mask。

1. 背景与目标

1.1 现状（已核实的事实）

项	状态
SAM3.1（facebookresearch/sam3 submodule）	✅ 在 `third_party/sam3`，`sam3.1_multiplex_fp16.pt` (1.7GB) 在 `checkpoints/`
SAM3 文本 grounding 验证	✅ `eval_sample_images.py` 已跑通（report.txt 可见 0.58–0.95 分数），mask/box 在原图分辨率输出（代码已确认：processor 会把 mask 插值回 `(img_h, img_w)`、box 乘以原图尺度）
GPU	2× RTX 3090；GPU0 有显示占用，GPU1 空闲 → SAM 常驻 GPU1
torch	2.1.2+cu121 / Python 3.11.8 / CUDA 12.2
rdc-cli	0.5.5 已装（`rdc doctor` 部分通过）
renderdoccmd	1.44（Linux 构建，仅 Vulkan/GL/GLES，无 D3D）
`renderdoc` Python 模块	❌ 未构建（`rdc doctor` FAIL）→ 影响"raw float 数值路径"，Phase 0 需解决
renderdoc-skill	MCP server（13 个工具）+ SKILL.md（66 命令）+ perception-agent-design.md + token 高效指南

1.2 缺口

perception-agent-design.md 的映射表里有一行是空的：

| Annotator 圈出来的"这块不对" | Capture 里的 draw call / pixel / shader 标记 |

也就是说，当前"人眼在渲染图上看 → 凭感觉指位置 → 手动点 RenderDoc"这一段没有自动化。 LLM 虽然能看图（多模态），但：看图费 token（一张 4K PNG ≈ 数千 token）、给不出像素级坐标（会幻觉）、无法跨轮稳定复现同一区域的定位。SAM3 就是来补这一段的。

1.3 目标

让 agent 能从"一个可疑区域/一句话描述"拿到像素级 bbox + mask + 质心，并直接驱动现有 rdc 工具。
让 before/after（shader edit + replay 或两次抓帧）的验证变成"区域感知"的量化判定，而不是整帧 PSNR（整帧被不变像素淹没，灵敏度极差）。
让 LLM 只看 attentional crop（SAM 裁出的可疑区域小图），而不是整张 4K 帧 —— 与 renderdoc-AI-Agent-token高效指南.md 的"漏斗 + 摘要"原则同构，只是这次漏斗发生在空间维度。
严格做加法：不改 renderdoc-skill 现有 13 个 MCP 工具与 SKILL.md 主流程，新增独立的 rdc-sam 服务 + 少量 recipe，两者在 skill 层编排。

1.4 非目标（明确不做）

SAM3 视频/跨帧跟踪（单帧范围内闭环）
Compute Shader 专属验证体系（perception-agent-design 开放问题 3）
多平台 / 多驱动 baseline 管理（开放问题 1/4）
SAM3 自带 agent 模式（MLLM 中继）——我们已有编排 LLM
harness 编排器本体（属 perception-agent-design 的范围，本计划只做 perception 层 + 接线）

2. 核心洞察：SAM 的准确角色与三种驱动模式

2.1 SAM 能做什么 / 不能做什么

能	不能
文本 prompt → 实例 mask/box/score（多模态 grounding）	判断"画面坏了 / 哪里是 bug"（不是异常检测器）
box/point prompt → 精化 mask（交互式）	直接给 draw call / shader 结论（那是 RenderDoc + LLM 的事）
before/after diff 图 → 把差异 blob 收敛成干净的对象 mask	跨帧语义跟踪（那是 SAM3 视频模式的事，本计划不做）
输出原图分辨率 mask/box → 与 RT 像素一一对应	补偿导出端的分辨率缩放/裁剪（必须由导出契约保证）

2.2 三种驱动模式（按可靠性排序，决定 Phase 顺序）

┌────────────────────────────────────────────────────────────┐
│ 模式 A：Diff-driven（最可靠，先做）                          │
│   before.png / after.png → 逐像素差 → 阈值 → 连通域          │
│   → ROI 列表（bbox/质心/面积）→ 可选 SAM 把 blob 精化成 mask  │
│   不需要任何语义文本，对合成 CG 内容最鲁棒                    │
├────────────────────────────────────────────────────────────┤
│ 模式 B：Interactive-driven（可靠，第二阶段）                  │
│   LLM 用粗略坐标点/框（或复用 diff ROI）→ SAM box/point       │
│   prompt → 精化 mask。解决"整帧 diff 到处都是，但只有某个     │
│   子区域才是人关心的 artifact"的问题                          │
├────────────────────────────────────────────────────────────┤
│ 模式 C：Text-grounded（有风险，集成最后做，但校准最先做）            │
│   "shadow acne" → SAM 文本 grounding。SAM3 训练分布偏自然             │
│   图像，合成渲染目标上的文本 grounding 命中率未知 → 校准测试           │
│   提前到 Phase 1（存在性测试，fail-fast，见 OKR.md §1）             │
└────────────────────────────────────────────────────────────┘

设计决策：Phase 顺序 = A → B → C。文本语义（模式 C）的集成是加分项，不是主线；但模式 C 的校准是存在性前提（反事实分析：没有 grounding，SAM 增量≈0），用半天工作量提到 Phase 1 fail-fast（详见 OKR.md §1）。

2.3 区域选择器层级：SAM 的正确位置（2026-08-25 补充）

"SAM 提升 SNR（注意力）"的直觉对，但调试中存在三个层级的区域选择器，永远先试上层：

层级	机制	精确度	成本	适用
① 因果	draw scope、pixel history、A/B replay（draw on/off）	构造性精确	0（rdc 已有）	有可疑 EID / 验证假设
② 统计	golden diff + 连通域（背景精确抵消）、方差/熵/SSIM 图、时序方差、频域	异常精确	≈0（numpy）	有 baseline；纹理级 artifact（banding/aliasing——SAM 盲区）
③ 语义	SAM3 / Grounding DINO / VLM pointing	近似	模型 + GPU	区域只能用语言/外观定义（无 baseline、无 EID、无 metadata）

三条推论：

SAM 分割"对象"，不判断"异常"——artifact 与对象边界重合时语义选择才等于异常选择；纹理级/细微异常时两者分叉，应走统计选择器。
引擎 metadata（debug markers、资源名、shader 名）是免费的语义通道——先于 SAM 使用。
诊断 SNR > 感知 SNR：一次 A/B replay 的因果比特胜过任何 mask； mask 统计 SNR 增益 ≈ √(面积比)，diff 是背景精确抵消。SAM 是三种机制里最弱的一种——只要前两种可用。 SAM 真正独占的格子：无 baseline + 无 metadata + 纯语义描述 + 需要 mask + 跨轮确定性重定位。

① ② 两层的具体 RenderDoc 命令与代码（per-draw diff、pixel history、A/B replay、golden diff、方差/熵/频域、rdc script raw float 捷径）：见 SELECTORS.md （命令签名已核实；numpy 代码已在合成数据上跑通；rdc 命令的真实行为未验证，见该文档 §0）。

3. 目标调试场景（S1–S5）与价值

场景	用户一句话	现有 rdc 工具	新增 sam 工具	产出
S1 可见 artifact 溯源	"地面上有块黑斑，是谁画的？"	`rdc_export(rt)`；得到坐标后 `rdc_pixel(pixel history)`、`rdc_pipeline`、`rdc_shader`	`sam_segment(image, text/box)` → bbox + 质心	artifact 区域 → draw call → shader 链条
S2 shader 修复验证	"我改了 PS，画面修好了吗？只影响了该影响的区域吗？"	`rdc_shader_edit`（replace + replay）、`rdc_export(rt)` after	`sam_verify(before, after, box?)`	区域感知量化判定 + 区域外回归守卫
S3 两次抓帧找差异	"这个版本和上个版本比，画面哪里变了？"	`rdc_diff --framebuffer --diff-output`	`sam_diff(before, after)` → ROI 列表 + overlay	差异区域的像素坐标 → 继续用 `rdc_pixel` 反查 draw
S4 token 高效查看	"把出问题的地方裁给我看"	`rdc_export`	`sam_crop(image, box, size=512)` → 内联小图	LLM 只看 512px 可疑区域，不看 4K 全帧
S5 语义区域 ↔ draw 关联	"角色脸部的光照是哪个 pass 算的？"	`rdc_pixel` 历史、`rdc_draws --pass`	`sam_segment(image, "face")`	语义区域 → 像素历史 → 反查 pass/draw

所有场景的共同模式：sam 工具输出坐标/区域，rdc 工具消费坐标/区域。SAM 不直接连 RenderDoc，只做"图像空间 ↔ 结构化 ROI"的翻译。

4. 系统架构

4.1 组件图

┌────────────────── renderdoc-skill（消费方，只做加法）──────────────────┐
│  SKILL.md 新增 recipe（S1–S5）                                         │
│  MCP client 同时注册：                                                  │
│    • rdc-tools（现有 13 工具，不改）                                    │
│    • rdc-sam-tools（新增 4 工具）                                       │
└───────────────┬──────────────────────────────────┬────────────────────┘
                │ MCP(JSON-RPC)                     │ MCP(JSON-RPC)
                ▼                                  ▼
┌───────────────────────┐   ┌──────────────────────────────────────────┐
│ rdc-cli daemon        │   │ rdc-sam-tools MCP server（新增，薄封装）    │
│ (open/draws/rt/pixel/ │   │   └── rdc_sam 核心库（本仓库）              │
│  shader-edit/diff…)   │   │       ├── engine.py   SAM3 常驻服务         │
└───────────┬───────────┘   │       ├── regions.py  Region dataclass     │
            │ .rdc          │       ├── coords.py  坐标契约校验          │
            ▼               │       ├── diffing.py 模式 A（连通域）       │
┌──────────────┐            │       └── metrics.py 区域感知 L2 指标      │
│ *.rdc 抓帧   │            └──────────────────────┬───────────────────┘
└──────────────┘                                   │ GPU1（空闲 3090）
      │ rdc rt/texture 导出                          ▼
      ▼                                        SAM3.1 fp16 常驻
┌─────────────────────────────────────────────────────────────┐
│ RT 原始数据（raw float，经 GetTextureData，数值路径）           │
│ RT PNG 导出（视觉路径，SAM 输入；需满足 §4.3 坐标契约）          │
└─────────────────────────────────────────────────────────────┘

4.2 两条数据路径（重要设计）

路径	数据	用途	代价/限制
视觉路径	PNG 导出（`rdc rt/texture` 或自写导出器）	SAM 分割/裁切/overlay	PNG 是 LDR（HDR 被 clamp），坐标必须与 RT 一致
数值路径	`GetTextureData` 原始 float	L2 区域感知指标（mask 加权 PSNR/MAE）、HDR 下才可见的 artifact	需要 `renderdoc` Python 模块（Phase 0 要装）；mask 从视觉路径复用

规则：SAM 只在视觉路径上跑；指标尽可能在数值路径上跑。PNG 负责"定位"，float 负责"判定"。两种路径共用同一套 Region（mask 在 RT 分辨率上），Region 是两者之间唯一的接缝。

4.3 坐标契约（整个方案的正确性基石）

导出必须为 RT 原生分辨率，禁止缩放/居中/裁剪。导出器校验 img.size == (rt_width, rt_height)，不一致立即报错（coords.py 里做断言）。
SAM3 processor 输出已经是原图分辨率的 mask/box（代码已确认：interpolate(masks, (img_h, img_w))、 boxes * [img_w, img_h, img_w, img_h]）。因此 bbox_xyxy / centroid 可直接作为 RT 像素坐标喂给 rdc pixel X Y / rdc pick-pixel X Y / rdc debug pixel EID X Y。
mask 坐标系 = RT 坐标系（数值路径 GetTextureData 数组形状 = (H, W, C)，与 mask 同构）。
对齐验证（Phase 1 spike）：合成一张已知色块布局的 RT（红块/绿块/渐变），走 导出 → SAM → 坐标 → pick-pixel → 断言颜色 全链路，允许误差 ±2px。

4.4 复用的骨架（不要重新发明）

已有	本计划直接消费
`renderdoc-perception-agent-design.md`	annotator/L2/loop 的词汇与决策树
SKILL.md §6 Visual Inspection	`rdc rt/texture → PNG → Read` 的既有模式（换成 `sam_*` 产出 ROI 后接 `rdc_pixel`）
SKILL.md §8 Shader Edit-Replay	S2 循环的 before/after 来源
SKILL.md §9 Frame Comparison	S3 的 diff 来源（`--diff-output`）
`eval_sample_images.py`	Phase 2 的 SAM 冒烟测试模板（沿用 segment→score→report 模式）

5. `rdc-sam` 服务设计

5.1 核心库 `rdc_sam/`（本仓库新增包，依赖 `third_party/sam3`）

@dataclass
class Region:
    mask: np.ndarray      # bool, shape (H, W)，RT 原生分辨率
    bbox: tuple[int,int,int,int]  # x0,y0,x1,y1（原图坐标）
    centroid: tuple[int,int]      # 质心（喂 pick-pixel / debug pixel）
    area: int
    score: float
    prompt: str

class SamPerceptionEngine:
    def __init__(self, ckpt, device="cuda:1", resolution=1008): ...  # 加载一次，常驻
    # 实现说明（已对 third_party/sam3 源码核实）：
    #  - 模式 C（text）：Sam3Processor.set_text_prompt(prompt, state)
    #    ⚠ 它会覆盖上一个 text prompt（源码注释 "will erase the previous text prompt"）
    #    → 不同 text query 之间需 reset_all_prompts() 或重新 set_image
    #  - 模式 B（point/box 交互精化）：SAM3InteractiveImagePredictor.predict(
    #      point_coords=[(x,y)] 像素, point_labels=[1/0], box=[x0,y0,x1,y1] 像素,
    #      mask_input=上一轮 mask, multimask_output=True)
    #    Sam3Processor 没有 point API；point 只能走 interactive predictor
    #  - Sam3Processor.add_geometric_prompt(box) 也可做 box grounding，但 box 是
    #    [cx, cy, w, h] 归一化 [0,1] → 引擎对外统一 xyxy 像素签名，内部做转换
    def set_image(self, pil) -> State                                    # backbone 只算一次
    def segment_text(self, state, prompt, conf=0.5) -> list[Region]      # 模式 C
    def segment_box(self, state, box_xyxy_px) -> list[Region]            # 模式 B（interactive predictor）
    def segment_point(self, state, pts_xy_px, labels) -> list[Region]    # 模式 B（interactive predictor）
    def crop(self, pil, region, size=512) -> PIL.Image                   # 模式 S4
    def overlay(self, pil, regions) -> PIL.Image                         # 报告可视化

# 模式 A（diff-driven，纯 numpy，无需 SAM 也行）
def diff_regions(before_np, after_np, threshold=0.05, min_area=64) -> list[Region]
def region_metrics(before_np, after_np, mask) -> dict       # 见 §6
def mask_stats(img_np, mask) -> dict                        # 结构化颜色统计

性能设计：set_image 只跑一次 backbone；同一张图多个 prompt 只花解码器开销。常驻 daemon + GPU1（device="cuda:1" 可配），避免每轮重载 1.7GB 权重。

5.2 CLI（与 rdc-cli 风格对齐）

rdc-sam segment  --image rt.png --text "face" [--box x0,y0,x1,y1] [--json] [--overlay out.png]
rdc-sam diff     --before a.png --after b.png [--threshold .05] [--min-area 64] [--json] [--out diff.png]
rdc-sam crop     --image rt.png --box x0,y0,x1,y1 --size 512 -o crop.png
rdc-sam verify   --before a.png --after b.png [--box ...] [--metric masked-psnr] --json
rdc-sam serve    # JSON-RPC daemon（供 MCP 复用，避免每工具调用冷启动）

输入说明：diff/verify 同时接受 PNG（视觉路径）与 .npy float 数组（数值路径，来自 GetTextureData 导出器）；指标计算优先走数值路径，PNG 仅作兜底与可视化。

5.3 MCP server `rdc-sam-tools`（薄封装，4 个工具）

工具	参数	返回
`sam_segment`	`image, prompt?, box?, point?, conf?`	JSON regions（默认只给 bbox/centroid/area/score，mask 默认不外传；`overlay` 可选内联小 PNG）
`sam_diff`	`before, after, threshold?, min_area?, max_regions?, overlay?`	JSON regions + 可选 diff overlay 内联图
`sam_crop`	`image, box, size=512`	内联小图（token 高效查看）
`sam_verify`	`before, after, box?, metric?, threshold?`	结构化判定：masked-psnr / inside_mae / outside_mae / diff_ratio / verdict

注册示例：claude mcp add rdc-sam-tools -- python .../rdc_sam/mcp_server.py 与 rdc-tools 平级，互不修改。

5.4 与 rdc-tools 的接线矩阵（skill 层编排，伪代码）

S1 artifact 溯源：
  png = rdc_export(action="rt", eid=E)                    # 视觉路径
  regions = sam_segment(image=png, prompt="dark spot")    # SAM 定位
  for r in top_regions:
      hist = rdc_pixel(action="pixel", args=f"{cx} {cy} {E} --json")
      # hist 里出现过的 draw → rdc_pipeline / rdc_shader → 结论

S2 shader 修复验证：
  before = rdc_export(rt)                                  # 改前
  rdc_shader_edit(action="shader-replace", ...)            # 注入
  rdc_export(rt) → after                                   # 改后（replay 后）
  verdict = sam_verify(before, after, box=region)          # 区域感知判定
  # 若 outside_mae 高 → "修好了但波及其他区域" → 回滚/继续

S3 帧间差异：
  rdc_diff(capture_a, capture_b, flags="--framebuffer --diff-output diff.png")
  regions = sam_diff(before, after)                        # ROI（可再叠加 sam_segment 精化）
  for r in regions: 继续 S1 式反查 draw

6. Region-aware L2 验证指标（S2 核心）

整帧 PSNR 会被不变的背景淹没。改为 mask 加权：

masked_psnr   = psnr( before[mask], after[mask] )     # 只看 artifact 区域
inside_mae    = mean|after-before| within mask        # 区域内变化量
outside_mae   = mean|after-before| outside mask       # 回归守卫：不该动的地方动了没
diff_ratio    = (|after-before|>eps 在 mask 内占比)
verdict       = pass/fail（阈值由 Phase 4 校准）

判定语义：

inside_mae 大 + masked_psnr 升 → 修复生效；
outside_mae 超阈值 → "fix 波及其他区域" → 拒绝该 patch；
配合模式 C 时：修复后再跑一次 sam_segment(text)，看 artifact 是否转移到别处（"修好了但长到旁边去了"）。

7. 分阶段落地（每阶段含验收标准）

编号说明：本计划的 Phase 0–6 与 perception-agent-design.md 的 Phase 1–5（最小骨架的五阶段） 无对应关系，别混淆。本计划是 perception 层的落地阶段。

Phase 0 — 环境收敛（0.5–1 天）

pip install -e third_party/sam3（本仓库根目录可 import sam3）
构建 renderdoc Python 模块：rdc setup-renderdoc 或按 renderdoc 文档 build（Linux 1.44）
rdc doctor 全绿；跑通 eval_sample_images.py 作为 SAM 侧回归基线
验收：python -c "import sam3, renderdoc" 通过；rdc doctor 无 FAIL

Phase 1 — 坐标契约 spike + 模式 A（1–2 天）

合成已知色块 RT（脚本生成，不依赖引擎），rdc capture 或构造 .rdc
导出 → SAM（box prompt）→ pick-pixel → 断言颜色，误差 ≤2px
rdc_sam/diffing.py：diff_regions（阈值 + 连通域），在合成图上自测（此件直接支撑 S3：模式 A 就绪后 S3 边际成本≈0）
模式 C 快速校准（半天，与坐标 spike 并行）：收集 10–20 张真实 RT 导出/截图，用 ≥8 词词汇表跑 segment_text，统计命中率（阈值 60%）。这是项目的存在性测试 （OKR.md §1 KR1）：<40% → SAM 退出主线；40–60% → 模式 C 限词表。
验收：坐标对齐自动化测试通过（这是整个方案成立的前提，不过不进入 Phase 2）；模式 C 校准有结论（命中率高≠继续，低≠放弃——是形态决策）

Phase 2 — SAM 服务化（1–2 天）

rdc_sam 核心库 + segment_text/box/point + crop + overlay
CLI + serve daemon（GPU1 常驻，backbone 缓存）
用真实 RT 导出图跑通 S4（crop 内联小图）
验收：rdc-sam segment --image <真实RT导出> --text "..." 输出合法 ROI；单 prompt < 2s

Phase 3 — S1 全链路打通（2–3 天）

S1 接线：sam_segment ROI → rdc pixel X Y EID（pixel history 拿 draw 列表） → rdc pipeline EID → rdc shader EID ps --source/--constants → 汇总结构化报告
在 ≥3 个真实/合成 .rdc bug 样本上跑通 S1（OKR.md §3.1 KR1 的预演）
验收：demo_s1.py 从 .rdc 一键跑到报告（对应 OKR.md §3.1 M3）

Phase 4 — S2 shader 修复验证闭环（2–3 天）

rdc_sam/metrics.py：mask 加权指标
端到端：导出 before → rdc_shader_edit replace → replay → 导出 after → sam_verify
阈值校准（用已知 bug + 已知修复样本）
验收：S2 场景在至少 2 个真实/合成 bug 上给出正确 verdict

Phase 5 — skill/MCP 集成（1 天）

rdc-sam-tools MCP server（4 工具）
renderdoc-skill 新增 recipes：S1–S5，写进 SKILL.md 或 references
token 收益实测：全帧 4K 图 vs sam_crop 512px 小图，记录 token 差
验收：同一 bug 用新流程跑通，LLM 输入 token 显著下降（目标 ≥ 5×）

Phase 6 — 报告 + 全链路（后续）

before/after overlay（mask 上色）+ 指标 JSON 合成一份"给工程师拍板"的报告
（可选）SAM3 agent 模式不引入 —— 我们已有编排 LLM，直接用自己的 prompt 驱动 SAM3，无需 MLLM 中继
（可选）golden artifact 测试集 + 回归脚本（沿用 eval 模式）

8. 风险与缓解

#	风险	等级	缓解
R1	坐标错位（导出缩放/裁剪导致 pick-pixel 打偏）	高	§4.3 契约 + Phase 1 合成图 spike 先行；导出器断言尺寸；robust 路径自写 GetTextureData 导出
R2	SAM3 文本 grounding 对 CG 内容命中差	中高	模式 A/B 优先；模式 C 有 Phase 3 命中率门槛，不达标降级
R3	`renderdoc` Python 模块构建失败（Linux）	中	数值路径是增强项；视觉路径 + rdc-cli 已有 `pick-pixel`/`pixel` 可先闭环；rdc setup-renderdoc 兜底
R4	迭代循环延迟：每轮多 0.5–2s	中	backbone 缓存 + 常驻 daemon；diff 模式在降采样图上跑；只在最终判定用全分辨率
R5	PNG LDR clamp 掩盖 HDR artifact	中	指标走数值路径；SAM 只负责定位；必要时对 RT 做 log/局部 tonemap 再喂 SAM（文档化）
R6	范围膨胀（把 perception-agent harness 全做掉）	高	本计划只做"perception 层 + 接线"，harness 编排保持在外层文档；S1 单条链路先垂直打通
R7	mask 传输体积（4K mask base64 数 MB）	中	MCP 默认只传 bbox/centroid/area/score；mask 留在服务端做指标；需要时 RLE
R8	双 GPU 抢占	低	SAM 固定 GPU1；`RDC_SAM_DEVICE` 环境变量可配

9. 验证与评估

坐标对齐测试（Phase 1，最关键）：合成色块 RT → 导出 → SAM box → pick-pixel → 断言颜色，全自动。
SAM 冒烟回归：复用 eval_sample_images.py 模式，但输入换成 RT 导出图 + overlay 图，输出 report.txt 风格。
S2 verdict 金样本：记录"已知 bug / 已知修复"样本对的 inside_mae / outside_mae / masked_psnr，校准阈值，写进 metrics 单测。
token 对比：S4 前后各跑一次，记录 LLM 输入 token（验收 ≥ 5× 下降）。
端到端演示：一份真实（或最接近真实的合成）bug 的 S1→S3→S2 全流程，产物 = before/after overlay + 指标 JSON + draw/shader 链条结论。

10. 修订历史

v1→v2 自评记录（7 处缺陷）、v2 事实错误更正（SAM3 API 误述等 7 项）、 OKR 排序推翻记录（模式 C 从"加分项"升格为"存在性前提"）已归档至 OUTDATED.md （仅作历史追溯，禁止据此实现）。当前版本：v3.1（2026-08-24）。

11. 开放问题（留给实现期回答）

rdc-cli 的 rt 导出在 Linux/Vulkan 上是否严格保真（尺寸/坐标）？→ Phase 1 spike 第一问；若不保真，切自写 GetTextureData 导出器（+1 周）。
RT 常见格式（RGBA8/float16/R10G10B10A2）导出成 PNG 时，SAM 视觉路径需要怎样的 tonemap？→ 收集真实 RT 样本后定。
S2 指标阈值体系：按 RT 格式分桶还是全局一份？→ Phase 4 校准；Phase 4 之前无法给出具体数值，以"校准任务"而非"预定值"呈现。
多 pass 污染（pass A 输出错 → pass B 连锁错）：SAM 只在最终 RT 上定位，能否反推到第一个出错的 pass？→ 依赖像素历史，作为 S5 延伸。
是否需要 sam_segment 支持多帧（同一视角不同帧）以过滤时序噪声？→ 当前单帧范围，留待 Phase 6 之后。
模式 C 若命中率不达标（OKR.md §1 KR1 决策树），S5 退化为"box 指哪打哪"——价值仍在但不如文本语义惊艳，已接受该降级路径。

12. 参考

renderdoc-perception-agent-design.md（Perception Agent Harness 平移设计）
renderdoc-AI-Agent-token高效指南.md（漏斗化 token 原则，本计划的"空间漏斗"与之同构）
SKILL.md（rdc-cli 66 命令；§6 导出-查看、§8 shader edit-replay、§9 diff）
mcp_server/server.py（现有 13 工具，作为 rdc-sam-tools 的封装范式）
SAM3：third_party/sam3（facebookresearch/sam3），Sam3Processor 输出原图分辨率 mask/box（代码确认）
本仓库 eval_sample_images.py / outputs/report.txt（SAM 冒烟基线）

FilesExpand file tree

PLAN.md

Latest commit

History