diff --git a/docs/en/guide/package.md b/docs/en/guide/package.md index 2b65ce8..92ffa95 100644 --- a/docs/en/guide/package.md +++ b/docs/en/guide/package.md @@ -14,7 +14,7 @@ Component `version` identifies the work release. SDK release versions identify d Declare mandatory host features in the manifest, for example `"requiredFeatures": ["saves.load", "saves.commit"]`. The default is an empty array. Identifiers match handshake features exactly: at most 256 unique entries, each containing 1–128 ASCII letters, digits, dots, underscores or hyphens. Require only features without which the component cannot run; probe optional features after ready and provide fallbacks. Supporting an interface does not grant permission. Handle denied capabilities independently. -Missing mandatory features or an unsupported API generation cause package checks and installation to return PROTOCOL_UNSUPPORTED. Failed updates preserve the active version. If an installed component becomes incompatible with the host, execution stops while personal data and enabled intent are preserved. Compatibility recovery automatically restores enabled components; components explicitly disabled during the block remain disabled. Incompatible layout dependencies prevent applying or restoring the layout. Bundling an older SDK cannot bypass the checks: the host provides the SDK. +Missing mandatory features or an unsupported API generation cause package checks and installation to return PROTOCOL_UNSUPPORTED. Failed updates preserve the active version. If an installed component becomes incompatible with the host, the UI shows an Incompatible badge and a plain-language notice, and disables the enable switch. Execution stops while personal data and enabled intent are preserved. Compatibility recovery automatically restores enabled components; components explicitly disabled during the block remain disabled. Incompatible layout dependencies prevent applying or restoring the layout. Bundling an older SDK cannot bypass the checks: the host provides the SDK. See [runtime compatibility](../reference/contracts/component.md#runtime-compatibility) for the contract. diff --git a/docs/en/reference/contracts/component.md b/docs/en/reference/contracts/component.md index e9c4779..80a9afd 100644 --- a/docs/en/reference/contracts/component.md +++ b/docs/en/reference/contracts/component.md @@ -12,7 +12,7 @@ For example, `"hostApiMajor": 1, "requiredFeatures": ["saves.load", "saves.commi Package checking, import, Workshop downloads and development reloads reject incompatible inputs with PROTOCOL_UNSUPPORTED and the required generation or missing features. First-install failure creates no installation; Workshop subscriptions and the failure reason remain. Failed updates preserve the active version, data and grants. Activation, layout apply/restore and final transaction commit recheck compatibility. -An installed manifest with readable, valid structure is retained even if it cannot run. The host preserves installation, configuration, saves, KV, grants, bindings and enabled intent, displays the reason and creates no runtime for it. Other compatible components can recover normally. Users may disable or remove a blocked component, but cannot newly enable it. Compatibility is derived from the current host rather than persisted as another switch. Restart or an installation update reevaluates it; enabled components resume automatically when compatible, while explicitly disabled components remain disabled and disconnected displays wait for reconnection. Unknown schemas and corrupt data follow the format rules rather than being guessed or silently cleared. +An installed manifest with readable, valid structure is retained even if it cannot run. The host preserves installation, configuration, saves, KV, grants, bindings and enabled intent, shows a plain-language incompatibility notice and status badges, and creates no runtime for it. Other compatible components can recover normally. The management enable switch is disabled while incompatible, including when enabled intent is already on. Removing the component and trusted disable commands (including Disable all) remain available; disabling still cancels enabled intent. User-facing status does not expose API names, feature identifiers or API-generation diagnostics; author package checks retain these details. Compatibility is derived from the current host rather than persisted as another switch. Restart or an installation update reevaluates it; enabled components resume automatically when compatible, while explicitly disabled components remain disabled and disconnected displays wait for reconnection. Unknown schemas and corrupt data follow the format rules rather than being guessed or silently cleared. Any incompatible layout dependency blocks applying or restoring the whole layout and leaves the current layout intact. Rollback does not restore earlier saves, KV or permissions; authors own compatibility of their business data. diff --git a/docs/guide/package.md b/docs/guide/package.md index 6c7378f..1f272d9 100644 --- a/docs/guide/package.md +++ b/docs/guide/package.md @@ -14,7 +14,7 @@ window 声明初始/最小尺寸、初始层级以及 surface。默认不透明 在 manifest 中用 `"requiredFeatures": ["saves.load", "saves.commit"]` 声明不可缺少的宿主功能。缺省为空数组;标识精确匹配握手 features,最多256项,每项1–128个ASCII字母、数字、点、下划线或连字符,不可重复。只有无法降级的功能才列入必需项;可选接口继续在 ready 后通过 features 探测。权限被拒绝仍应有明确降级或错误处理,不能把支持接口当作已授权。 -缺少必需功能或接口代际不受支持时,包检查和安装返回 PROTOCOL_UNSUPPORTED。更新失败保留旧版;已安装组件遇到宿主不兼容时暂停运行并保留个人数据及启用意图,恢复兼容后自动恢复,期间主动停用者不会自动启用。布局中有不兼容依赖时不能应用或恢复。SDK 由宿主提供,无法通过随包附带旧 SDK 绕过检查。 +缺少必需功能或接口代际不受支持时,包检查和安装返回 PROTOCOL_UNSUPPORTED。更新失败保留旧版;已安装组件遇到宿主不兼容时显示“不兼容”标记和简明提示,启用开关置灰,暂停运行并保留个人数据及启用意图,恢复兼容后自动恢复,期间主动停用者不会自动启用。布局中有不兼容依赖时不能应用或恢复。SDK 由宿主提供,无法通过随包附带旧 SDK 绕过检查。 完整规则见[运行兼容性](../reference/contracts/component.md#运行兼容性)。 diff --git a/docs/reference/contracts/component.md b/docs/reference/contracts/component.md index 29c7854..363dd52 100644 --- a/docs/reference/contracts/component.md +++ b/docs/reference/contracts/component.md @@ -14,7 +14,7 @@ Services 区分结构校验与运行兼容性。新导入、工坊下载、开发重载及候选版本先验证结构与当前支持;不兼容报 PROTOCOL_UNSUPPORTED,列出所需接口代际或缺少的功能。首次安装失败不创建安装;工坊保留订阅及失败原因。更新失败保留已有激活版本、数据和授权,不自动降级,不把下载成功当作安装成功。候选激活、布局应用/恢复及最终提交重新检查兼容性。 -已安装且结构可读取的组件即使运行不兼容,仍保留安装、配置、存档、KV、授权、绑定和启用意图;管理界面显示原因,不创建运行窗口或执行脚本,不影响其他兼容组件恢复。不兼容组件仍可停用或移除;不能新启用。宿主重启或安装更新后重新计算兼容性,恢复兼容时按保留的启用意图自动恢复,期间主动停用者保持停用,断屏者等待回接。兼容状态是当前宿主的派生结果,不持久化为新的启用开关。未知清单结构及损坏数据仍按格式版本规则保留原文件并报错,不能假装已理解未知结构。 +已安装且结构可读取的组件即使运行不兼容,仍保留安装、配置、存档、KV、授权、绑定和启用意图;管理界面按不兼容状态(宿主文档:`../modules/ui.md`)显示用户提示与标记,不创建运行窗口或执行脚本,不影响其他兼容组件恢复。不兼容时管理界面的启用开关置灰,仍可移除;可信停用(包括全部停用)仍取消启用意图。宿主重启或安装更新后重新计算兼容性,恢复兼容时按保留的启用意图自动恢复,期间主动停用者保持停用,断屏者等待回接。兼容状态是当前宿主的派生结果,不持久化为新的启用开关。未知清单结构及损坏数据仍按格式版本规则保留原文件并报错,不能假装已理解未知结构。 布局中的任一依赖不兼容时禁止整屏应用或恢复,预览列出组件及原因,保持原布局。包回退不回退用户存档、KV或权限,当前数据与旧组件业务格式的兼容性由作者负责。 diff --git a/host-snapshot.json b/host-snapshot.json index dd818e6..8caad39 100644 --- a/host-snapshot.json +++ b/host-snapshot.json @@ -22,8 +22,8 @@ { "source": "docs/contracts/component.md", "destination": "docs/reference/contracts/component.md", - "sourceSha256": "6e0983cb87cadce8106fab768a5e5ccb13cde9b865d4c986cd048bc17f7fc7bd", - "sha256": "82387add17a69cf38c6f55c547f4f6a3e3422cf01f0993e66d2e592bf0a00f9e" + "sourceSha256": "b53da2e32d741165b3861d4385f4d6557e51ac2fe6a683d0692cb33c8177f387", + "sha256": "3a6d65327fcb90a26398e4fd6ffcbe49ed862a62fb317f0f7cd5e15d166d4da0" }, { "source": "docs/contracts/configuration.md",