English | 简体中文
**状态：**实验性草案。JSON Schema 和参考验证器共同定义了已实现的子集。本文中的 MUST（必须）和 SHOULD（应当）表示本项目的要求，不表示任何标准组织已经采纳本规范。
通用 UDI 框架描述跨领域的可复用应用体验。Core 0.1 是已实现的研究工作空间配置，其数据、组件与操作词汇封闭。JSON 是运行时契约，普通人通过预览、控件及分享链接使用，无需编辑该格式。当前没有音乐契约或通用工作流语言。
桌面版 Studio 与手机版 Pocket 同属应用 v0.4.0，实现同一份 Core 0.1 契约。手机端将表格定义呈现为卡片；安装清单和离线缓存属于宿主功能，不是界面包字段。参见手机行为与存储说明。
宿主可将经过严格校验的包编码为 #udi=v1.p.<base64url>（原始 UTF-8 字节），或 #udi=v1.z.<base64url>（deflate 压缩后的 UTF-8 字节）。创建时仅保留当前入口路径和支持的语言参数，移除 URL 凭据及其他查询状态，完整 URL 上限为 16,000 字符。解码限制片段为 16,000 字符，校验规范 base64url，将解压结果限制在 65,536 字节，拒绝无效 UTF-8，并通过同一严格导入器校验。仅在浏览器同时支持压缩和解压时选用压缩；不支持解压的接收浏览器会明确拒绝压缩链接。
片段只携带界面包。打开时必须从地址栏移除输入片段并显示示例数据预览，不得安装、授权或执行操作。使用这个界面会再次校验定义，保留个人记录与笔记，清除全部本地实例授权，并打开数据选择。此封装是项目自己的分享机制，不是互操作传输标准。分享链接不会提交公开社区帖子。参见社区行为。
一个包是一个 UTF-8 编码的 JSON 文档，通常命名为 name.udi.json。当前 specVersion 必须为 "0.1"。metadata.version 是独立的包发布版本字符串，形式遵循语义化版本。实例本地的修订计数器用于编辑，不作为包的发布版本导出。
导入必须拒绝超过 65,536 个 UTF-8 字节的文档、未知格式版本、未知字段、格式错误的 JSON，以及不符合 udi.schema.json 的文档。参考实现不迁移旧格式。集合大小和文本长度的上限由 Schema 定义。
| 字段 | 契约 |
|---|---|
specVersion |
固定值 0.1 |
metadata |
包 ID、标题、描述、发布版本 |
capabilities |
不重复的能力请求；不包含授权或凭据 |
sources |
逻辑 ID、实体类型和所需的读取能力 |
views |
组件目录中的组件 ID、数据源引用、可见性和有界设置 |
actions |
对宿主固定处理器的引用及其所需能力 |
layout |
balanced 或 focus |
研究工作台包是规范性的完整示例。{ "id": "experiments", "entity": "experiment", "capability": "experiments.read" } 这样的数据源表示逻辑需求，不是路径、OAuth 凭据、HTTP URL，也不是与某个具体项目的连接。
数据源、视图和动作的 ID 必须在各自集合中保持唯一。视图的数据源引用必须能解析。每个数据源的能力必须与其实体类型匹配，并在包中声明。动作所需的能力也必须声明。除 JSON Schema 检查外，validateSpec 还实现了这些语义约束。
| 视图类型 | 数据源实体 | 行为 |
|---|---|---|
metrics |
experiment |
全部运行的计数，以及状态为 passed 的运行中的最佳 PSNR |
table |
experiment |
filter、groupBy 和 highlightBelow |
bar-chart |
experiment |
每个模型在状态为 passed 的运行中的最佳 PSNR，使用 0–40 dB 标尺 |
timeline |
deadline |
按日期排序的事件 |
collection |
paper |
本地文献库卡片 |
filter 为 all 或 failed。groupBy 为 none 或 model；参考渲染器会对模型分组排序，并标记每组的起点。highlightBelow 是 −10 至 0 dB 之间的阈值。非表格组件必须拒绝这些设置。
balanced 显示所有可见视图。focus 显示指标和表格，同时隐藏次要的图表、时间线和文献库面板，但不删除其定义。显式设置 visible: false 会在任一布局中隐藏该视图。
标准化的演示记录定义在 types.ts 中。实验通过 commitId 引用提交；详情视图按记录中的精确 ID 进行关联。契约不包含因果推断或语义相似性。真实连接器需要在信任边界验证数据结构；演示记录具有类型定义，并不意味着已经提供这一保证。
参考实现中的 Instance 包含 ID、数据集绑定、已授予的能力和本地笔记。编辑状态还保存当前包、修订计数器、历史定义和活动记录。这些状态均保存在浏览器本地。
数据源解析在返回数据前，必须检查实例与数据集是否匹配，并同时检查能力声明和授权。记录在读取时会被克隆。能力授权限定于某个数据集实例，包括个人导入实例。初始读取授权仅为虚构的平台示例预先配置；个人导入实例初始不具有授权。安装界面包会清除所有本地实例的授权。
集成真实资源的实现必须在不受信任的客户端代码之外执行范围限制。UDI Core 0.1 不规定连接器凭据、传输方式、身份联合或服务端授权。
参考提案包含 baseRevision、基准定义的稳定序列化结果（baseFingerprint）、摘要、操作和计算得到的新增能力。该指纹用于精确比较状态，不是密码学哈希或签名。
支持的操作为 filter、group、layout、visibility、highlight、add-papers 和 add-action。模型输出结构见 planner-output.schema.json。宿主计算基准状态字段和能力差异；模型提供的授权无效。
智能体对话与设置式控件还提供经过审核的宿主操作，用于切换数据绑定和调整能力授权。这些操作修改本地实例状态，而非可移植界面包，不属于新增的 Core 提案操作。模型输出本身不能授予访问权限。
应用提案时必须同时比较基准修订号与定义，在副本上应用操作，并在替换前验证完整候选定义。失败时保留原定义。新的能力请求不得修改已有授权。撤销会在一个递增的新本地修订号下恢复先前定义；它不会回滚数据、笔记或权限决定。
界面最多保留 20 个历史定义。包的 metadata.version 不会随每次编辑自动变化；发布版本由维护者决定。
v0.1 唯一的动作处理器是 create-review-note，需要 notes.write，以及对其声明的实验数据源的访问权限。它为绑定数据集中的所有失败实验生成确定性的摘要，与表格当前显示的筛选条件无关。
准备阶段必须记录动作 ID、实例 ID、本地修订号、精确的包定义及载荷。执行必须要求宿主确认，拒绝修订号、实例或定义已变化的请求，根据当前数据和授权重新计算载荷，并且只追加重新计算的结果。不接受生成的代码或任意动作端点。
参考实现的确认是单个浏览器应用中由可信界面传入的布尔值。它不具备防重放能力，不是签名批准、身份验证原语，也不是恰好执行一次的协议。重复的已授权调用可以追加重复笔记。生产环境中的副作用需要更强的授权与幂等契约。
exportPackage 仅接受有效的规范对象。未知的结构化字段，包括绑定、记录、授权和历史，都会导致验证失败。它不得接收整个应用状态后再通过启发式规则剔除字段。
导入在展示包请求的能力之前验证包。安装替换定义，保留本地数据集选择和笔记，并清除本地授权。派生包会修改包元数据，同时保留逻辑定义。这两个操作都不会复制其他人的实例。
标题和描述是包中的公开字符串，可能包含私人信息。参考导出器提供检查提示，但不扫描内容；不得将结构化排除描述为完整的隐私保证。
v0.1 支持一个参考运行时和四种实体类型。它不支持自定义组件执行、表达式语言、事件工作流引擎、包签名、市场、多用户同步，也没有 A2UI、AG-UI 或 MCP 适配器。未知扩展会验证失败。未来版本应明确标注适配器版本并进行测试，不能因术语相同而暗示线协议兼容。