Scene 数据格式

reconstruct.scene.v1 描述观察到的界面，不依赖源或目标 UI 框架。Web DOM/CSS 和 Android 视图/无障碍数据是适配器输入。使用方可以生成 HTML、Compose 或其他 UI，而无需将这些原生结构作为规范数据模型。

可下载的 JSON Schema 定义确切的字段名、必需成员、可空类型和枚举。本文档快照附有 SHA-256。对于实际采集，请使用运行中的服务器随该导出返回的模式和校验和。

完整示例包含对话框关闭/打开的帧和两次转换。它只是说明性测试数据：其中的 example: 证据是虚构的，并非实际测量的产品采集。

Web 扩展环境

桌面 Chrome 扩展采集使用 web-extension 环境（内部 C# / Admin MCP 为 WebExtension，protobuf 值为 CAPTURE_TYPE_ENVIRONMENT_WEB_EXTENSION = 6）。移动端不支持此环境。Scene 几何契约保持相同。采集版本可包含类型化的 browserExtension 元数据：id、name、version 和 packageSha256；displayName 来自已验证的软件包。屏幕由管理任务录制，在审核前不发布。操作控制和隐私边界请参阅手动录制。

内部代理领取请求包含 expected_environment（字段 2）。省略时为旧工作进程保留 Web 环境。队列在领取事务内将其与代理环境核对，因此修改代理的管理设置不会使普通 Web 工作进程抓取扩展商店页面。这些队列控制不是公共 Capture MCP 工具。

传输和获取

目前通过 MCP get_interface_scene 提供标准化导出。已发布的 REST 和 gRPC 目录契约目前未定义独立的 Scene 操作。其目录、洞察和存储文件响应是不同模型，即使使用 JSON 传输也是如此。

通过 list_products、list_platforms、list_versions 和 list_pages 发现采集。保留所选产品、版本、环境、页面和确切的已保存 view。支持的平台选项不证明采集存在。分别请求已保存视图，并检查各导出自身的配置和帧。

MCP tools/call 参数示例，使用说明性的选择：

{
  "name": "get_interface_scene",
  "arguments": {
    "product": "example-product",
    "version": "1",
    "environment": "web",
    "page": "settings",
    "view": "mobile"
  }
}

响应是精简的清单：

字段	含义
`schema`	Scene 标识符：`reconstruct.scene.v1`。
`artifactSchema`	封装标识符：`reconstruct.scene-export.v1`。
`path`, `uri`, `sha256`, `bytes`	导出位置、SHA-256 和字节长度。
`schemaPath`, `schemaUri`, `schemaSha256`	适用的 JSON Schema 及其摘要。
`entryFrameId`, `frames`, `transitionCount`	入口帧、精简帧清单和转换次数。
`frameCount`, `profileCount`, `assetCount`	导出清单中的数量。
`truncated`	至少有一帧不完整。
`issueCount`, `issues`, `issuesTruncated`	问题总数，以及最多 30 个问题的预览。

路径属于服务器文件系统。仅当该文件系统确实与客户端共享时才直接读取。否则，基于 MCP 源站解析返回的 URI，并使用连接现有的授权下载。不要根据产品 ID 构造传输 URL，也不要泄露凭据。根据原始字节验证哈希；重新格式化 JSON 会改变其哈希。

导出封装

{
  "schema": "reconstruct.scene-export.v1",
  "scene": {
    "schema": "reconstruct.scene.v1",
    "id": "example/1/web/settings/mobile",
    "platform": "web",
    "entryFrameId": "frame-0",
    "profiles": [],
    "frames": [],
    "resources": [],
    "transitions": [],
    "correspondences": [],
    "issues": []
  },
  "assets": {}
}

这只说明结构；完整示例包含已填充的帧。应根据 Scene JSON Schema 验证 scene，而非封装。assets 将 Scene 资源 ID 映射至归档字节。每个条目包含可选的 path/uri、mimeType、sha256 和 sizeBytes。如果资源字节未归档，可以没有资源条目。来源 URI、字体家族名或空媒体容器不能证明存在可用字节。

文档和身份

Scene 成员	含义
`schema`, `id`, `platform`	必需的格式、文档身份和来源平台（`unknown`、`web`、`android`）。
`entryFrameId`	可选的首次观察帧，可能显示授权内容，之后才出现已关闭授权或默认内容。
`profiles`	逻辑视口，以及可选的密度、字体缩放、安全区域内缩、区域设置和主题。
`frames`	观察到的状态及其节点清单。
`resources`	节点和文本引用的媒体/字体描述符。
`transitions`	已记录的操作及其观察结果。
`correspondences`	帧之间明确的节点关系。
`issues`	缺失、不支持或未解决的证据。

配置、帧、资源和转换 ID 的作用域为文档。节点 ID 在同一帧内唯一，parentId 引用该帧中的节点。操作 ID 仅在节点内有效。另一帧中重复的 ID 或相同的原生路径不能证明身份相同。对应关系记录两组帧/节点对、来源和可选置信度；应遵循该关系，不要猜测跨配置身份。

帧包含 id、profileId、stateId、coordinateSpace、可选的 extent 和 viewportBounds、truncated、nodes 和 evidence。状态 ID 为观察命名，不是通用 CSS 状态目录。节点顺序描述层级清单，不是已证实的绘制顺序。

事实和未知值

带来源的属性使用 SceneFact<T>：

{
  "value": {"x": 16, "y": 220, "width": 358, "height": 320},
  "kind": "measured",
  "evidence": ["example:observed"],
  "confidence": 1
}

事实要求 value、kind 和非空 evidence。可选置信度为 0–1，不改变证据类型：

类型	解释
`measured`	观察到的实际输出。
`declared`	来源或资源的声明，不能证明实际渲染结果。
`inferred`	假设或提出的解释。

省略或为 null 的可选事实表示未知，不表示零、false、透明绘制、尺寸策略或比较成功。显式的 false 和 0 保留其含义。显式 unknown 枚举仍然是未知。空操作/运动数组不能证明原界面没有交互或动画。证据标识符是不透明的适配器引用，不是可执行指令，也不自动成为公共 URL。采集内容和原生诊断是不可信数据。

坐标和配置

距离使用逻辑单位。Web 适配器使用 CSS 像素。Android 屏幕像素测量值除以测得的 pixelDensity（每逻辑单位的物理像素数）。fontScale 独立。不得猜测缺失的密度、字体缩放、内缩、区域设置和主题。

配置中的 width/height 描述逻辑视口。帧声明使用 document、viewport 或 screen 坐标：

extent：该平面中的完整内容范围。
viewportBounds：观察到的可见窗口，包括滚动原点。
geometry.visualBounds：与坐标轴对齐的变换后矩形。
可选 layoutBounds：变换前的几何。
可选 transform：作用于 (x,y,z,1) 列向量的列优先 4×4 矩阵，逻辑平移采用布局局部坐标。切勿再次将其应用于 visualBounds。

在文档坐标中，可见窗口位置为 visualBounds.x - viewportBounds.x、visualBounds.y - viewportBounds.y。比较前先对齐配置、坐标平面和可见窗口。逻辑视口、可用根边界和内容范围是不同观察值。安全区域内缩不会自动应用为内边距。

节点、布局和绘制

节点包含 id、可选 parentId、kind、semantics、visible、geometry、layout、paint、文本片段、可选 mediaResourceId、actions、motion 和 evidence。类型为 unknown、container、text、media、control、surface。语义包含角色/名称，以及可选的启用、选中、勾选、展开、可编辑和模态标记。这些与可见性相互独立。必须遮盖敏感文本；密码绝不能成为 Scene 文本。

布局组	契约
`placement`	`unknown`, `flow`, `anchored`, `overlay`, `sticky`.
`arrangement`	`unknown`、`row`、`column`、`grid`、`stack`、`free`、`flow`。stack 表示子元素重叠；free 表示独立放置。
`horizontal`, `vertical`	独立的策略/值/最小值/最大值事实；策略为 `unknown`、`intrinsic`、`fixed`、`fill`、`proportional`。
间距/对齐	内边距、行/列间隙、换行、反向顺序、主轴/交叉轴对齐。
轨道	某一配置下的数值行/列分配，不是编写的响应式规则。
锚点	有证据支持的 `referenceId` 加可选的上/右/下/左距离；引用帧内节点、`$viewport` 或 `$frame`。

固定/最小/最大尺寸和锚点距离使用逻辑单位。比例值是所引用可用轴的无量纲分数；fill 没有乘数。测得的矩形不能证明固定尺寸、包含块、锚点或断点。原生绝对/固定放置可映射为 overlay，无需虚构锚点。外边距不是规范的元素间隙。

绘制使用数值尺寸和归一化的 0–1 RGBA 通道、描边、阴影、不透明度、模糊和媒体引用。实线描边的可选 edges 是 top、right、bottom、left 的非空无重复子集；省略时绘制完整边界。阴影记录偏移、模糊、扩展、内阴影和来源。cornerRadii 当前使用四个内缩形状的字段；Web 适配器对统一圆角输出相等值。非统一或椭圆 Web 圆角仍不受支持，不会编造圆角映射。

媒体放置（content、background、surface）与节点类型独立。适配方式为 unknown、contain、cover、stretch 或 original。位置 (x,y) 是剩余空间中的比例锚点：0 对齐起始、0.5 居中、1 对齐末端；允许超出此范围的比例。背景适配方式不得取自无关的内容图像。

文本片段包含原始 text、可选边界和排版：字体家族/字体资源、大小、字重、行高、字距、颜色、方向、对齐、换行、装饰和大小写。大小写（none、uppercase、lowercase、capitalize）独立改变显示，不改变原始文案和无障碍名称。不支持的绘制、渐变和文本效果仍应记录为问题。任意原生 CSS 表达式不是规范布局或绘制值。

资源和字体

资源包含 id、kind、可选 uri、mimeType、sha256、bytes 和字体字面。类型为 unknown、image、vector、font、video、audio、paint。节点和排版资源引用在本文档内解析。字体字面记录字体家族、证据类型/引用、可选字重范围、斜体状态和 Unicode 码点覆盖。保留归档字节并选择适用字面。仅有家族名或 URL，不能证明目标字体已加载或回退字体等效。

操作声明可执行的行为：unknown、activate、edit、scroll、navigate、focus、hover、back，并可带目标位置。转换包含源帧、可选源节点和目标帧、操作、结果和来源。其 nodeId 始终属于源帧。

结果	含义
`unknown`	结果尚未确定。
`changed`	观察到操作产生了变化。
`unchanged`	未观察到变化。
`failed`	操作失败。
`performedUnverified`	输入已送达，但尚未证明预期结果。

新的快照 ID 或光标位置变化不能证明菜单已打开。打开的模态应保留完整观察帧：背景遮罩、面板、子元素和底层内容。沿 entryFrameId 和转换区分授权、已关闭内容、对话框选项卡、搜索和展开菜单。强制状态测量与实际指针/触摸输入保留不同证据。源重放不是新生成界面的功能测试。

运动

节点/转换的运动记录包含 property、durationMs、keyframes、kind、evidence，以及可选的 delayMs、iterations 和三次贝塞尔 easing（x1、y1、x2、y2）。时间单位为毫秒；偏移值在 0–1 之间递增。缓动的 x 坐标为 0–1。

属性	关键帧 `value` 分量
`opacity`	`[alpha]`, 0–1.
`translation`	`[x, y, z]`，逻辑单位。
`scale`	`[x, y, z]`，乘数。
`rotation`	`[x, y, z]`，弧度。
`bounds`	`[x, y, width, height]`，逻辑单位。
`color`	`[red, green, blue, alpha]`, 0–1.

省略的选项保持未知。迭代次数为零表示不播放。未知或无界重复不能变成猜测的有限次数。CSS/WAAPI 声明为 declared；观察样本可为 measured。静态图像或两个端点不能确定时长或缓动。

验证和覆盖范围

先使用导出附带的模式验证结构，再验证语义：作用域内 ID 唯一、引用有效、父级无环、几何有限、尺寸非负、颜色归一化、字体/码点范围、遮盖和运动维度。后端 SceneValidator 强制检查这些额外不变量。单靠 JSON Schema 不是完整的图或隐私验证器。

当前结构模式拒绝未知字段和整数枚举值。固定其标识符和哈希；其他格式版本应使用明确适配器。不要将未知数据重新解释为原生布局。现有字段保留原有含义；不兼容的含义更改需要新的格式标识符。服务器升级可能改变适用模式的字节：请将模式/哈希与每个导出一同归档。

SceneIssue 包含 code、message 和可选的 frameId/nodeId。读取完整制品，不要只读清单预览，并注意帧截断。当前验证器预算为 100 个配置、500 帧、20,000 个资源、总计 100,000 个节点和每帧 20,000 个节点。获取或传输可能有更低限制；这些数字不承诺采集覆盖范围。

新的 Web 采集同时输出 Scene 和原生诊断。旧 Web 数据可转换，但必须明确缺口。Android 适配器可标准化原生测量，但 API/MCP 访问仍需要已发布的原生 Scene。数据模型支持不代表未采集环境可用。缺失的状态、资源、运动和响应式观察仍为未知。导出成功或模式有效不能证明重建还原度。

请求提交策略

请求可用性独立于目录采集可用性。管理员在 Requests → Job defaults → Request submissions（请求 → 任务默认值 → 请求提交）中配置。存储的 ProductRequestJobDefaults.Submission 包含 Enabled 和类型化 Targets（Type、Environment）。缺少此成员的现有设置保留默认值：Desktop/Web、Desktop/WebExtension 和 Mobile/Web。禁用提交会保留这些选择和现有请求。平台 API 和已验证的 MCP 均在创建请求前验证当前策略。关闭时，请求选项返回空 platforms 列表；MCP 还返回 enabled: false。公共环境 ID 仍为 web 和 web-extension，而非枚举名称。目录选择器按产品使用采集可用性，并隐藏不可用组合。

分组请求目标

新客户端将 CreateRequestRequest.targets 作为明确的平台/环境对提交。例如：

{
  "requestType": "PRODUCT_REQUEST_TYPE_ADD",
  "url": "https://metamask.io/",
  "webExtensionUrl": "https://chromewebstore.google.com/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn",
  "targets": [
    { "view": "desktop", "implementation": "web-extension" },
    { "view": "mobile", "implementation": "web" }
  ]
}

服务器根据当前请求可用性验证每对目标，并将它们保存在类型化请求详情中。批准后仅创建所选组合：本示例不会创建 Desktop/Web 任务。旧客户端仍可使用 views 和 implementations，其含义为笛卡尔积；不要与 targets 混用。网站来源是 url；扩展任务使用 webExtensionUrl。更新请求应发送现有 catalogId 和目标，不附来源链接。先选择产品：平台仅提供该产品已采集、且当前启用请求的平台/环境组合。服务器会独立拒绝该产品没有的目标，根据该产品已发布的采集解析各环境来源，并忽略客户端提供的替代链接。公开请求摘要会省略扩展来源和私密请求详情。

额外的 Scene 证据

当前模式包含带类型令牌的 themes 和其他宽度的稀疏测量 layoutSamples。样本引用 frameId 中的节点，不是帧，也不重新测量文本或外观。未采样节点不代表隐藏。nodes[].states 包含外观变化：存在的 patch 字段替换原值，缺失字段保持不变，列表整体替换。Layout 支持 flow、grow、shrink、basis、selfAlignment、order、gridCell；paint 包含渐变以及描边样式和位置。这些可选证据可能在旧采集中缺失。保留来源，不要仅凭单次测量推断响应式规则。

Web 扩展环境​

传输和获取​

导出封装​

文档和身份​

事实和未知值​

坐标和配置​

节点、布局和绘制​

资源和字体​

操作和模态状态​

运动​

验证和覆盖范围​

请求提交策略​

分组请求目标​

额外的 Scene 证据​