配置协议

配置模式属于组件包，配置值只属于显示器的当前布局条目，运行时按 (installationId, displayId) 投影为实例配置。授权与资源绑定归安装组件，不能通过修改配置值扩大授权。

字段模型

所有字段必有 key、label、type；key 为英文标识符（字母开头，随后为字母、数字或下划线），同一模式中不得重复。可选 description 用于说明并作为编辑器的可访问帮助文本，最长 1024 个 UTF-16 单元。可选 group 是 1–80 个 UTF-16 单元的分组名称；分组按首次出现排序，组内按字段声明顺序，无 group 的字段作为无标题组参与排序。普通字段必须给出合法 default；资源和秘密字段默认为 null，禁止携带作者提供的本机路径、绑定或凭据。

type	数据与约束	管理控件
boolean	JSON 布尔值	复选框或开关
string	字符串；可设 maxLength	文本框
integer	安全范围内的 JSON 整数；可设 minimum/maximum	数值输入
number	有限 JSON 数值；可设 minimum/maximum	数值输入
enum	字符串；options 为 {value,label} 数组	单选下拉
multiEnum	不重复的字符串数组，值属于 options	多选列表
color	#RRGGBB 格式的不透明颜色	颜色选择器
directory	宿主创建的目录 bindingId 或 null	宿主目录选择器
launchTarget	宿主创建的启动目标 bindingId 或 null	宿主应用/文件选择器
secret	秘密 bindingId 或 null	宿主掩码输入，支持替换与清除

字符串选项值不能为空、不得重复。数值下界不得大于上界，默认值必须符合约束。

{
  "key": "categories",
  "label": "显示分类",
  "type": "multiEnum",
  "default": ["documents"],
  "options": [
    {"value": "documents", "label": "文档"},
    {"value": "pictures", "label": "图片"}
  ],
  "shareable": true
}

配置显示文案的翻译引用见包内多语言，配置key、枚举value、默认值及用户输入不翻译；group按原引用标识分组，翻译仅用于标题显示。

配置编辑与作用域

普通字段的初始值直接写在configuration字段声明的default中。

用户在显示页选定显示器后，通过组件详情抽屉编辑配置；保存前完整验证，成功后原子保存该屏当前布局并发送 config.changed，失败保留原值。普通值变化无需重载；不另存实例配置文件，也不自动改写布局库副本。组件通过 config.get 读取，通过 config.set 修改自身普通字段；修改仍经过同一验证，不得修改其他实例、绑定或授权。

界面重设计采用普通字段统一草稿与整体保存，独立资源绑定操作明确即时生效；离开处理、外部变更冲突和作用域提示以 管理界面的保存规则（宿主文档：../modules/ui.md#52-保存规则） 为准。产品工程已接入该保存方式，不改变公开字段格式、权限或绑定所有权。服务在提交时合并用户编辑字段并检查这些字段的外部变更，未编辑字段与即时绑定保留最新值；保存失败不提交任何普通字段。

首次创建实例采用默认值；停用后保留；复制布局不复制浏览数据或 KV 存储。秘密字段运行时返回引用，不经 config.get 返回秘密正文。宿主设置页可替换秘密但不回显原文。

秘密引用不代表只能离线使用：组件可以直接联网，绑定凭据可用于宿主网络请求。相关行为由本协议说明，不在权限及秘密输入区域重复提示；重定向的敏感头处理以宿主网络边界为准。

目录、目标和秘密绑定由宿主可信 UI 创建，绑定只属于本安装组件。跨屏可选择复用绑定，但配置中选择哪个绑定仍独立。删除绑定立即使所有引用它的实例失效，返回 RESOURCE_UNAVAILABLE，不能自动绑定到同名资源。

选择目录或目标需要明确用户操作；网页不能自行弹出选择器循环索取权限。选择具体资源与Capability分开：目录读取和绑定目标打开只需有效绑定，目录写入还需directory.write授权。未选择字段返回 null，不阻止启用。

分享与隐私

普通字段的 shareable 默认 false；本地导出布局自动包含保存记录中全部有效且作者显式设为 true 的普通字段。发布到工坊时仍由用户在发布预览确认分享字段。资源绑定、秘密和权限始终不进入导出文件。

directory、launchTarget、secret 永远不可分享，其 shareable 必须为 false 或省略，不能通过作者声明覆盖。布局永不导出授权、绑定 ID、秘密、机器路径。工坊发布预览显示即将分享的每个普通值，提示用户检查可能手填于普通文本中的个人信息；程序不能保证识别任意文本中的秘密。

本地恢复快照可以保存普通配置和有效绑定引用，不保存秘密本体或授权。绑定已删除时恢复为 null；取消订阅清理须移除快照内该组件的配置与绑定引用，保留缺失组件的排布引用即可。

更新兼容

宿主按 key 迁移：相同 key/type 且值仍合法则保留；新字段用默认；删除字段从激活配置移除；类型变化、枚举值消失或越界时重置为新默认并记录非敏感诊断。秘密类型不能自动转成普通字符串，绑定不能自动改指向。

激活和包回退都只校验当前显示器布局中的配置，不保存或恢复独立历史配置。激活前生成候选布局配置，成功提交后统一通知各实例；准备失败保留原版本和当前布局。恢复不重建已撤销的权限或已清理的绑定。

组件自行完成登录后保存的凭据使用credentials接口，不写secret配置字段，不回显或替换用户手动输入的秘密绑定。目录写入复用directory引用并单独授予directory.write，不能从目录读取权限推导。