edit | blame | history | raw

MEXP09B 像素 payload

用户目标

以 coder2@mindraw 身份领取统一台账 P-20260701-mexp09b-target-frame-pixel-payload 的 MD-MEXP09B-01，补齐 Mindraw 侧 target Frame 像素输入能力：当用户给 agent 一个 mindraw://localhost?documentId=...&elementId=<frameId> Frame link，目标 Frame 内放真实截图时，Mindraw App API 必须能提供只包含目标 Frame 的真实 PNG / bitmap payload，使后续 m4c / vision-capable agent 能像收到目标 Frame PNG 一样看图。

已完成事项

  • 在 Mindraw read API 新增 targetFramePixelPayload="read" capability。
  • 新增 JSON-RPC 方法 mindraw.app.get_target_frame_pixel_payload。
  • 新增 mindrawGetTargetFramePixelPayload()，输入 documentId、可选 packagePath、sourceFrameId 或 elementId。
  • 输出 target Frame-only PNG payload：MIME、尺寸、byteLength、SHA256、Frame bounds、生成时间、pixelsIncluded=true、bytesIncluded=true。
  • 输出 pixelScopeAudit：targetFrameOnly、source snapshot hash、rasterizer、outside text / image / pixel exclusion、no OCR、no document visual fallback。
  • 如果不能生成 PNG 像素，返回 TARGET_FRAME_PIXEL_PAYLOAD_REQUIRED；非 Frame 返回 TARGET_NOT_FRAME；缺失 target 返回 TARGET_NOT_FOUND。
  • 更新 runtime discovery：Rust transport capability 文件和 supported methods 均声明 mindraw.app.get_target_frame_pixel_payload 与 targetFramePixelPayload="read"。
  • 新增 QA 报告：02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.md 和 .json。
  • 回写 02-P/plan-progress.markdown 的 MD-MEXP09B-01 与 Progress Log。
  • 同步 CHANGELOG.md、CODEGRAPH.md、INDEX.md。

核心事实 / 变更快照

  • 变更对象：Mindraw App API Frame visual read contract。
  • 事实来源：
  • src/lib/mindrawAppReadApi.ts
  • src/lib/mindrawAppApiTransport.ts
  • src-tauri/src/app_api_transport.rs
  • 02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.md
  • 变更前：
  • MEXP09 只有 visualContext.snapshot SVG metadata / dataURL。
  • Gate package 仍出现 bytesIncluded=false、pixelsIncluded=false、auxiliaryOcr.available=false。
  • 不能支撑“vision-capable agent 已收到目标 Frame PNG 像素”。
  • 变更后：
  • Capability：targetFramePixelPayload="read"。
  • JSON-RPC：mindraw.app.get_target_frame_pixel_payload。
  • Success DTO：payload.kind="target-frame-png-pixel-payload"、mimeType="image/png"、pixelsIncluded=true、bytesIncluded=true、width、height、byteLength、sha256、dataURL、pixelScopeAudit。
  • No-Go：TARGET_FRAME_PIXEL_PAYLOAD_REQUIRED，不得退回 OCR-only、文本摘要、SVG metadata only 或 document visual scan。
  • 范围边界：
  • 本轮不改 m4c consumer。
  • 不改 ~/plugins/mindraw。
  • 不打 DMG，不安装或覆盖 /Applications/Mindraw.app。
  • 长期 QA / 台账不保存 raw PNG bytes。
  • 验证证据：
  • npm test -- --run src/lib/mindrawAppReadApi.test.ts src/lib/mindrawAppApiTransport.test.ts PASS，2 files / 19 tests。
  • cargo test --manifest-path src-tauri/Cargo.toml app_api_transport PASS，5 Rust tests。
  • npm run build PASS。
  • git diff --check PASS。

文件变更

  • src/lib/mindrawAppReadApi.ts
  • src/lib/mindrawAppReadApi.test.ts
  • src/lib/mindrawAppApiTransport.ts
  • src/lib/mindrawAppApiTransport.test.ts
  • src-tauri/src/app_api_transport.rs
  • 02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.md
  • 02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.json
  • 02-P/plan-progress.markdown
  • CHANGELOG.md
  • CODEGRAPH.md
  • INDEX.md

可复用命令 / Runbook

用途：复验 Mindraw MEXP09B target Frame pixel payload contract。

前置条件：在 /Users/ar/Projects/ExcalidrawX，源码包含 MD-MEXP09B-01 改动；无需启动 App、无需 DMG、无需 m4c。

设置命令：

cd /Users/ar/Projects/ExcalidrawX
npm test -- --run src/lib/mindrawAppReadApi.test.ts src/lib/mindrawAppApiTransport.test.ts
cargo test --manifest-path src-tauri/Cargo.toml app_api_transport
npm run build
node -e "JSON.parse(require('fs').readFileSync('02-P/qa/mindraw-mexp09b-target-frame-pixel-payload-check.json','utf8')); console.log('QA_JSON_OK')"
git diff --check

验证步骤：上述命令分别应显示 Vitest 2 files / 19 tests PASS、Rust 5 tests PASS、build PASS、QA_JSON_OK、git diff --check 无输出。

清理 / 恢复命令：无临时系统状态；本轮未启动 App、未安装 App、未创建 DMG。

搜索关键词：MD-MEXP09B-01、targetFramePixelPayload、mindraw.app.get_target_frame_pixel_payload、TARGET_FRAME_PIXEL_PAYLOAD_REQUIRED、pixelsIncluded=true、bytesIncluded=true。

未决问题

  • m4c 仍需在 M4C-MEXP09B-01 中消费 PNG payload，并把像素输入交给 vision-capable agent / model。
  • PM Gate 仍需用真实 Frame 内截图验证 agent 能描述 UI 细节，且 Frame 外 sentinel 不进入结果。
  • 当前 PNG 是从 Mindraw controlled target Frame-only visual snapshot 经 browser canvas 栅格化，不是 OS compositor screenshot；复杂 Excalidraw 渲染 fidelity 仍应由后续 m4c consumer QA / PM Gate 覆盖。

后续建议

  • PM 可派发 M4C-MEXP09B-01。
  • 在 MEXP09B Gate 通过前，不恢复 MEXP09 value DMG 或 MEXP10 plugin Gate 的旧视觉价值口径。