diff --git a/README.md b/README.md index 8d12286..89f9563 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ For local use, run `claude --plugin-dir .`, or register the repository with `cod | skills | Shared Codex / Claude Code Skills | | tools | Repository tooling | -The host provides SDK 0.1.0 with `hostApiMajor` and `protocolVersion` set to 1. Use the declarations for development, but do not bundle SDK files into a component. See the [reference](docs/en/reference/index.md) and [third-party notices](THIRD_PARTY_NOTICES.md). +The host provides SDK 0.1.2 with `hostApiMajor` and `protocolVersion` set to 1. Use the declarations for development, but do not bundle SDK files into a component. See the [reference](docs/en/reference/index.md) and [third-party notices](THIRD_PARTY_NOTICES.md). ## Feedback diff --git a/docs/en/guide/data.md b/docs/en/guide/data.md index 8089411..44ca6d9 100644 --- a/docs/en/guide/data.md +++ b/docs/en/guide/data.md @@ -45,3 +45,5 @@ Here, `signal` belongs to the current operation. Validate the loaded business va `SAVE_CONFLICT` requires reloading and a business merge or explicit conflict UI. Do not overwrite using the latest revision blindly or retry forever. A lost response requires a load before another write. Cancellation does not undo a published commit. KV allows 256 KiB per value and 16 MiB per instance. Saves have separate budgets and keep the previous successful revision. Save at checkpoints and coalesce updates rather than writing every frame. Neither layouts nor package rollback restore persistent progress. See [saves](../reference/contracts/saves.md). + +The host component page offers installation-wide Clear after every instance is disabled and the user confirms. Authors initialize empty progress after clearing. The host provides neither save export nor backup import. Author-controlled `saves.restore` only restores the internal previous successful snapshot. Keep list visibility separate from editor selection: resume shared-data refresh when leaving editing without a draft, and preserve input when saving fails. diff --git a/docs/en/guide/lessons.md b/docs/en/guide/lessons.md index 3bb8f28..15234ed 100644 --- a/docs/en/guide/lessons.md +++ b/docs/en/guide/lessons.md @@ -32,6 +32,8 @@ Do not release a mutation slot as soon as the cancel button is pressed. The unde Reminder operations retain their slot until the original request ends; compatibility reports have one `reportController`. Sources: reminders contract and worker-canvas/`main.js`. Rapid start/cancel must keep outstanding work bounded. Replaceable reads still need generations and host pending-request limits. +Host queues cap running and queued work per installation and globally. Saturation returns `QUOTA_EXCEEDED`, and cancellation promptly removes queued work. Authors must still coalesce replaceable work and bound retries; repeated cancellation is not a way around backpressure, and an active native call may still be finishing. + ## 6. Worker drawing needs acknowledgements Stardust gives each state a sequence and sends the next latest state only after the matching applied acknowledgement. The computation canvas uses `presentationInFlight`/`pendingPresentation` and a five-second response deadline. Posting at a fixed interval does not establish backpressure. diff --git a/docs/en/guide/publishing.md b/docs/en/guide/publishing.md index e23dcd9..6fc3ebf 100644 --- a/docs/en/guide/publishing.md +++ b/docs/en/guide/publishing.md @@ -21,4 +21,6 @@ New publications start public. Review metadata, preview, tags and actual content Publish in a layout detail drawer opens the same dialog directly, with a Publish/Update selector. Layout dialogs list included component names and UUIDs instead of a preview image, upload file list, or raw layout JSON. Select and review shareable configuration values in that same dialog: none are selected for a new draft, and saved drafts retain the selection. Sharing choices remain available when updating and use only the configuration snapshot validated by the host when preparing the draft. +The host manages layout work versions on save, overwrite and rename. Before upload it checks the remote version and freezes a higher version; retries after failure or uncertainty keep that version and content. Changing shared configuration after freezing requires a new draft. Importing a layout with an existing identity creates a separate local copy and preserves the original. Layout details show dependency and compatibility checks without an arrangement diagram. + Shared layouts replace one display, require existing dependencies and do not subscribe automatically. Layouts identify dependencies by component UUID, regardless of local, development or Workshop source. Publishing does not require Workshop component references or rebinding. Never include author source paths or grants. Read [Workshop behavior](../reference/modules/workshop.md) and [layouts](../reference/contracts/layout.md). diff --git a/docs/en/reference/contracts/host-api.md b/docs/en/reference/contracts/host-api.md index 9d5d384..8de0cbd 100644 --- a/docs/en/reference/contracts/host-api.md +++ b/docs/en/reference/contracts/host-api.md @@ -1,6 +1,6 @@ # Host API, authorization and errors -SDK 0.1.1 uses `apiMajor`/`hostApiMajor`=1 and `protocolVersion`=1. The host injects `widgetHost` before business scripts. Wait for ready, use call(method, params, {signal}) and retain unsubscribe functions returned by on. Workers have no direct bridge. +SDK 0.1.2 uses `apiMajor`/`hostApiMajor`=1 and `protocolVersion`=1. The host injects `widgetHost` before business scripts. Wait for ready, use call(method, params, {signal}) and retain unsubscribe functions returned by on. Workers have no direct bridge. ## Capabilities and base interfaces @@ -22,6 +22,8 @@ Public failures include `INVALID_ARGUMENT`, `PROTOCOL_UNSUPPORTED`, `METHOD_NOT_ Requests and final delivery validate the original instance/document, cancellation, grants and dependencies. Timeouts, navigation, disablement and revocation invalidate work; cancelling cannot undo already committed side effects. Public errors omit secrets, stack traces and personal paths. +Host request queues are bounded per installation as well as globally, counting both running and queued work. Saturation returns `QUOTA_EXCEEDED`. Cancellation removes queued work promptly; active native operations retain their capacity until they finish safely. `config.set` and `window.setSize` check validity after acquiring the transaction lock and before publishing state. A cancellation that arrives after publication does not undo it. + features indicate host support, not authorization or successful device execution. compatibility separates API existence, actual probes and untested devices. Read [complete method/event declarations and machine budgets](../types.md), [saves](saves.md) and the specific desktop contracts before implementation. ## Source and related declarations diff --git a/docs/en/reference/contracts/layout.md b/docs/en/reference/contracts/layout.md index da878b6..ee00b70 100644 --- a/docs/en/reference/contracts/layout.md +++ b/docs/en/reference/contracts/layout.md @@ -12,6 +12,8 @@ The current reader and writer use canonical `schemaVersion: 1`. Historical varia Display IDs are stable internal identities, not connection order or display numbers. Disconnection preserves intent without silently migrating content. Global language/theme/autostart and local display aliases are not shared layout settings. +Layout details show dependencies, compatibility and configuration fallback results without an arrangement diagram. Preflight uses a published snapshot; preparation and final commit revalidate state. Importing a file whose `layoutId` already exists creates a separate local copy with a new UUID, preserving the original record and bindings. New local layouts start at `1.0.0`; overwrite and actual rename advance the work version. Publication negotiates and freezes a version above the remote version; retries retain the same content and version. + ## Source and related declarations Exact method signatures and complete machine budgets are shared in [SDK declarations](../types.md). diff --git a/docs/en/reference/contracts/saves.md b/docs/en/reference/contracts/saves.md index beb4963..c09cb55 100644 --- a/docs/en/reference/contracts/saves.md +++ b/docs/en/reference/contracts/saves.md @@ -22,6 +22,10 @@ The host serializes atomic publication. Authors reload/merge or present a confli Use elapsedSince with a business `maxMs` for offline calculation, handling `clockMovedBack` and capped. Local timestamps are not anti-cheat evidence. onClosing provides one bounded normal-shutdown opportunity per document, with no veto; regular checkpoints remain necessary. See [the game recipe](../../recipes/game.md). +## Host save management + +The component drawer provides Clear for the entire installation after all its instances are disabled. Confirmation defaults to Cancel. Clearing removes save slots and their recovery copies while retaining configuration, KV, cache and browser data. The host does not provide a save export or backup import action. Author-controlled `saves.restore` still publishes the previous successful slot snapshot as a new revision. + ## Source and related declarations Exact method signatures and complete machine budgets are shared in [SDK declarations](../types.md). diff --git a/docs/en/reference/modules/workshop.md b/docs/en/reference/modules/workshop.md index 79f084e..be22c65 100644 --- a/docs/en/reference/modules/workshop.md +++ b/docs/en/reference/modules/workshop.md @@ -1,6 +1,8 @@ # Workshop and publication -A subscription is not the installed runtime directory. The host validates/copies complete content into owned versions. Only reliable service results establish unsubscription; network failure alone never removes content. Removing the last account association disables affected instances and cleans owned data under the host rules. Layout subscriptions are not auto-applied and missing dependencies do not trigger auto-subscription. Development publication validates current matching-identity source into a clean upload copy, initially private, without replacing the running version. Steam availability and actual client acceptance need separate verification. +A subscription is not the installed runtime directory. The host validates/copies complete content into owned versions. Only reliable service results establish unsubscription; network failure alone never removes content. Removing the last account association disables affected instances and cleans owned data under the host rules. Layout subscriptions are not auto-applied and missing dependencies do not trigger auto-subscription. Development publication validates current matching-identity source into a clean upload copy, initially public, without replacing the running version. Steam availability and actual client acceptance need separate verification. + +Layout publication freezes its content and version before upload, advancing beyond the remote version and locally frozen drafts of the same work. Retrying an uncertain or failed upload reuses that frozen content; changing shared configuration requires a new draft. A newer remote version blocks an older frozen draft. ## Sources and author guidance diff --git a/docs/guide/data.md b/docs/guide/data.md index e9fc56c..57c97a1 100644 --- a/docs/guide/data.md +++ b/docs/guide/data.md @@ -41,3 +41,5 @@ const saved = await widgetHost.call('saves.commit', { 代码展示调用形状,`signal` 由当前业务任务提供。作者须验证 loaded.current.value 的业务结构;不能直接将不可信 JSON 当作自己的模型。SAVE_CONFLICT 时重读并按业务合并或提示选择,不盲目改成最新修订覆盖,也不无限重试。响应丢失时先 load 确认;取消不撤回已经提交的副作用。 实例 KV 单值 256 KiB、总量 16 MiB;共享存档的独立额度见[存档协议](../reference/contracts/saves.md)。不按每帧保存;按检查点、合并变更和有界退出机会保存。布局和组件包回退不会回退这些持久进度。 + +宿主组件页提供安装级“清除”,要求全部实例停用并确认;清除后作者按空存档初始化。宿主不提供存档导出或备份导入。作者的 `saves.restore` 仍只恢复内部上一成功快照,不能读取用户备份文件。列表与编辑器应分开维护状态:退出编辑且无草稿时恢复共享数据刷新,保存失败时保留编辑内容。 diff --git a/docs/guide/lessons.md b/docs/guide/lessons.md index 325b97c..cd3deea 100644 --- a/docs/guide/lessons.md +++ b/docs/guide/lessons.md @@ -32,6 +32,8 @@ 提醒工具保持操作槽直到原调用结束;计算画布的兼容报告也只有一个 controller。来源:提醒协议、examples/worker-canvas/main.js 的 reportController。测试连续开始/取消时同时存活操作数仍有上限。对可立即替换的纯读取任务,也要用代次阻止旧结果并遵守宿主在途额度。 +宿主队列按安装和全局限制执行及排队总数,满载返回 `QUOTA_EXCEEDED`,取消会及时剔除尚未执行的任务。业务侧仍须合并替换操作并限制重试,不能用连续取消规避背压;已经开始的原生调用可能尚在退出。 + ## 6. Worker 绘制需要确认,不只是节流 星河微光为状态消息加 sequence,收到匹配 applied 后才发下一份 latest。计算画布同样有 presentationInFlight/pendingPresentation 和五秒响应期限。仅按固定 interval postMessage 不能保证慢 Worker 不积压。 diff --git a/docs/guide/publishing.md b/docs/guide/publishing.md index d6ca94d..bdbb43a 100644 --- a/docs/guide/publishing.md +++ b/docs/guide/publishing.md @@ -21,4 +21,6 @@ 布局从布局抽屉的“发布”直接进入同一弹窗,也可切换为更新。布局弹窗以组件名称与 UUID 列表代替预览图、实际上传文件和原始布局 JSON;可分享配置直接在同一弹窗中勾选并核对值,新草稿默认不选,保存后保留选择。更新时同样可调整分享选择,只会使用准备草稿时服务筛选的配置快照。 +布局保存、覆盖与重命名由宿主管理作品版本。上传前核对远端并冻结更高版本;失败或结果未知后重试保持同一内容和版本,冻结后改变分享配置须新建草稿。导入同身份布局会创建新的本地副本并保留原布局。布局详情展示依赖与兼容性检查,不显示排布示意图。 + 布局分享只替换目标显示器,缺依赖不能应用,不自动订阅。布局依赖只按组件 UUID 匹配,不保存组件来源,工坊发布无需填写引用或重绑定;不能包含作者源码路径、授权或秘密。规则见[工坊模块](../reference/modules/workshop.md)和[布局协议](../reference/contracts/layout.md)。 diff --git a/docs/reference/contracts/host-api.md b/docs/reference/contracts/host-api.md index dd7a444..f18a17f 100644 --- a/docs/reference/contracts/host-api.md +++ b/docs/reference/contracts/host-api.md @@ -2,12 +2,14 @@ # 宿主接口与Capability -当前SDK0.1.0,hostApiMajor/apiMajor=1、protocolVersion=1。类型声明与机器可读字段以sdk唯一来源同步。 +当前SDK0.1.2,hostApiMajor/apiMajor=1、protocolVersion=1。类型声明与机器可读字段以sdk唯一来源同步。 组件自行通过直接联网或通用network接口完成登录、令牌和服务请求;参见[组件登录验证](../modules/github.md)。 ## 参数与关联协议 +组件请求使用按安装计额的有界队列,额度包含执行中与排队任务,满载明确返回QUOTA_EXCEEDED。取消、超时和文档失效及时释放尚未执行的任务;已经执行的原生调用仍在安全边界结束,不因取消立即释放其活动额度。配置和尺寸修改在取得事务锁后及状态指针发布前检查有效性;已经提交的状态不由迟到取消回滚。 + HTTP头与目标参数规则:HTTP 头必须在明文 `{name,value}` 与秘密 `{name,secretBindingId,prefix?}` 中二选一,明文形式不得携带 prefix。`target.open` 也必须在 `{bindingId}` 与 `{directoryBindingId,relativePath}` 中二选一,不接受混合字段或固定绑定附加 relativePath;捕获票据和执行复用同一选择器检查,非法形式返回 INVALID_ARGUMENT。此处拒绝歧义输入,不扩张已有目标范围或权限。 可回收实例二进制缓存的额度、未命中、取消与授权失效见[缓存协议](cache.md),与存档分离,不提供本机路径或新增系统读取权限。 diff --git a/docs/reference/contracts/layout.md b/docs/reference/contracts/layout.md index 2ce3aa5..fc7f5b2 100644 --- a/docs/reference/contracts/layout.md +++ b/docs/reference/contracts/layout.md @@ -6,11 +6,11 @@ 每个显示器的当前状态直接使用布局格式持久化,配置不独立保存。布局库保存/覆盖复制当前屏布局,应用或恢复覆盖该屏当前布局;存档属于安装组件,不进入布局。实例身份由安装内部身份与显示器身份稳定派生,不携带配置。 -当前schemaVersion=1,每个条目必须提供zOrder;muted可省略,默认为false,组件依赖仅记录 UUID,不记录组件来源。当前只接受下述规范 v1,不接受带来源字段的基线前变体,不自动转换历史格式;后续范围及迁移遵循格式版本规则(宿主文档:`../development.md#格式版本兼容与迁移`)。allowMultipleInstances=false且其他屏已有启用实例时,预览提示冲突并禁止应用或恢复;事务提交再次校验,不自动停用其他屏。 +当前schemaVersion=1,每个条目必须提供zOrder;muted可省略,默认为false,组件依赖仅记录 UUID,不记录组件来源。当前只接受下述规范 v1,不接受带来源字段的基线前变体,不自动转换历史格式;后续范围及迁移遵循格式版本规则(宿主文档:`../development.md#格式版本兼容与迁移`)。allowMultipleInstances=false且其他屏已有启用实例时,预检提示冲突并禁止应用或恢复;事务提交再次校验,不自动停用其他屏。 ## 文件格式 -本地导出为 UTF-8 JSON 文件;工坊布局内容目录包含 `layout.json` 与可选 `preview.png`,条目标签区分 layout/widget。preview 可采用宿主排布示意图;若用户主动选择截图,上传前必须展示图像以避免意外分享组件内容。 +本地导出为 UTF-8 JSON 文件;工坊布局内容目录包含 `layout.json` 与可选 `preview.png`,条目标签区分 layout/widget。preview 可采用作品封面;若用户主动选择截图,上传前必须展示图像以避免意外分享组件内容。 ```json { @@ -42,11 +42,11 @@ 组件引用形式为 `{widgetId:"...",hostApiMajor:1}`,不保存 source、appId 或 publishedFileId。依赖仅按 UUID 匹配已安装组件,与本地、开发或工坊来源无关;同 UUID 多个安装时拒绝歧义,不任意选择。宿主API版本必须为1,不支持的引用禁止应用。工坊发布保留相同引用,不要求组件来自工坊,也不提供引用重绑定。 -schemaVersion、kind、layoutId、version、name、sourceResolution、sourceWorkArea、items 必填;sourceResolution 为保存时完整显示区域的物理像素正整数宽高(不是工作区或 DIP),每项 componentName 为非空名称快照。组件不可重复身份仅由 component.widgetId 确定,名称不参与匹配。其余规则:version 格式与组件包一致。items 可为空,表示清空目标屏当前布局;同一组件 UUID 最多一次。enabled/visible 必须为布尔值,layer 必须为 top/bottom。sourceWorkArea 宽高必须为正;bounds 为有限 DIP 数值,宽高为正。未知字段、重复 JSON 键、重复组件引用和不支持的协议均拒绝导入。已保存的当前屏布局允许读取结构有效但运行代际不兼容的安装引用,以保留启用意图;应用/恢复仍检查引用代际与激活版本一致且为宿主所支持。 +schemaVersion、kind、layoutId、version、name、sourceResolution、sourceWorkArea、items 必填;sourceResolution 为保存时完整显示区域的物理像素正整数宽高(不是工作区或 DIP),每项 componentName 为非空名称快照。组件不可重复身份仅由 component.widgetId 确定,名称不参与匹配。其余规则:version 格式与组件包一致。本机新保存的布局从1.0.0开始,覆盖与实际重命名递增补丁版本;发布时由Services核对远端版本并冻结新的上传版本,重试复用冻结内容。导入遇到已有layoutId时为导入副本分配新UUID,保留原布局及其本地绑定,源文件不改写。items 可为空,表示清空目标屏当前布局;同一组件 UUID 最多一次。enabled/visible 必须为布尔值,layer 必须为 top/bottom。sourceWorkArea 宽高必须为正;bounds 为有限 DIP 数值,宽高为正。未知字段、重复 JSON 键、重复组件引用和不支持的协议均拒绝导入。已保存的当前屏布局允许读取结构有效但运行代际不兼容的安装引用,以保留启用意图;应用/恢复仍检查引用代际与激活版本一致且为宿主所支持。 -zOrder 为 0 到 2147483647 的整数,同一 layer 内不得重复,越大越靠前;不同层可重复,top 始终位于 bottom 之上。隐藏条目同样保留顺序。预览与实际应用使用同一排列。 +zOrder 为 0 到 2147483647 的整数,同一 layer 内不得重复,越大越靠前;不同层可重复,top 始终位于 bottom 之上。隐藏条目同样保留顺序。预检与实际应用使用同一排列;界面展示依赖、配置回落及兼容性结果。 -对外布局文件不保存目标显示器的本机 ID、真实设备路径、权限、绑定、秘密、浏览数据或安装包内容。当前布局和本地布局库保存完整配置及有效绑定引用,以configurationTypes记录字段类型;类型变化时采用当前默认值,避免将资源引用转换为普通文本。对外导出只含通过 [分享规则](configuration.md) 的普通字段。组件版本不强制精确锁定;要求 hostApiMajor 匹配,运行当前激活的本地版本。预览按当前配置模式验证配置,不合法项标明将回落的默认值。 +对外布局文件不保存目标显示器的本机 ID、真实设备路径、权限、绑定、秘密、浏览数据或安装包内容。当前布局和本地布局库保存完整配置及有效绑定引用,以configurationTypes记录字段类型;类型变化时采用当前默认值,避免将资源引用转换为普通文本。对外导出只含通过 [分享规则](configuration.md) 的普通字段。组件版本不强制精确锁定;要求 hostApiMajor 匹配,运行当前激活的本地版本。预检按当前配置模式验证配置,不合法项标明将回落的默认值。 应用布局从默认值构造条目,再用布局中的合法配置覆盖,不合并当前配置;缺失字段采用默认值或 null。未列出的条目从当前布局移除,实例资源停止;独立存档、KV与浏览数据不随布局覆盖删除。同机本地布局的绑定引用只在仍属于当前安装且有效时恢复;外部导入仍拒绝绑定。 @@ -55,7 +55,7 @@ zOrder 为 0 到 2147483647 的整数,同一 layer 内不得重复,越大越 ## 应用与恢复 1. 选择目标显示器,确认已连接且物理像素宽高与 sourceResolution 一致,否则禁止应用或覆盖。解析布局并校验引用;逐项检查是否存在已完整安装、兼容、未待清理的本地激活版本。列出缺失项及[运行不兼容](component.md#运行兼容性)的组件和原因,任一依赖不可用即禁用应用按钮,不自动订阅或下载。 -2. 在数据层计算适配与配置变化,显示新增、替换、停用及默认值回落。预览不运行新组件、不修改状态,也不检查用户是否授予 Capability。 +2. 基于已发布的只读状态快照及其修订计算适配与配置变化,显示新增、替换、停用及默认值回落。预检不运行新组件、不修改状态,也不检查用户是否授予 Capability。 3. 用户确认后取得目标屏布局操作锁,重新检查显示器、依赖、版本和配置模式,保存原状态快照,再准备候选状态与窗口。新窗口准备期间不启动作者脚本;失败保留原状态。 4. 原子提交候选状态;目标屏中未列出的条目移除,其既有配置不在当前布局中保留,列出的组件按布局的 enabled/visible/layer/zOrder 排布。不复制到其他屏,不改变安装级授权。 5. 完成窗口切换后开始新实例运行,保留应用前快照。资源创建或切换失败回滚原布局;提交后作者脚本失败按运行故障处理,可手动恢复,不把任意脚本业务逻辑成功作为事务条件。 @@ -69,9 +69,9 @@ zOrder 为 0 到 2147483647 的整数,同一 layer 内不得重复,越大越 坐标相对显示器工作区左上角,单位 DIP,工作区不包含任务栏保留区域。保存和导出同时记录工作区 DIP 宽高与完整显示区域的物理像素分辨率。布局跨屏通用,但应用和覆盖必须匹配物理分辨率;DPI 和任务栏差异继续适配。物理像素到 DIP 由目标显示器 DPI 换算,不能用主屏缩放统一换算。 -位置按 `x' = x × targetWidth/sourceWidth`、`y' = y × targetHeight/sourceHeight` 映射。尺寸使用目标实例最后的作者请求值,新实例使用包默认尺寸,布局 bounds.width/height 仅记录保存时作者尺寸供预览,不能覆盖作者尺寸;恢复同样不回滚作者当前尺寸。宿主不因小屏缩小组件,仅将位置夹紧到工作区;尺寸超过工作区时左上位置约束到工作区边界,允许部分内容超出。 +位置按 `x' = x × targetWidth/sourceWidth`、`y' = y × targetHeight/sourceHeight` 映射。尺寸使用目标实例最后的作者请求值,新实例使用包默认尺寸,布局 bounds.width/height 仅记录保存时作者尺寸供预检,不能覆盖作者尺寸;恢复同样不回滚作者当前尺寸。宿主不因小屏缩小组件,仅将位置夹紧到工作区;尺寸超过工作区时左上位置约束到工作区边界,允许部分内容超出。 -允许组件重叠,不自动重新排列;预览明确实际结果,只可调整位置,尺寸由作者决定。任务栏、DPI 或分辨率变化时按同样规则约束位置,不改变尺寸与组件身份。处理规则应有确定性测试,而非依赖窗口创建顺序。 +允许组件重叠,不自动重新排列;预检明确实际结果,只可调整位置,尺寸由作者决定。任务栏、DPI 或分辨率变化时按同样规则约束位置,不改变尺寸与组件身份。处理规则应有确定性测试,而非依赖窗口创建顺序。 ## 本地保存与分享 diff --git a/docs/reference/contracts/saves.md b/docs/reference/contracts/saves.md index a7897c4..025fd8a 100644 --- a/docs/reference/contracts/saves.md +++ b/docs/reference/contracts/saves.md @@ -28,13 +28,11 @@ SDK `widgetHost.elapsedSince(savedAt,{now?,maxMs?})` 返回 `{elapsedMs,clockMov ## 可信存档管理 -组件页抽屉在组件操作行下方展示“存档”栏,标题下同排放置“导出存档”和“清除”两个按钮,作用于整份安装存档,不依赖显示器或实例是否存在。安装全部实例停用后可操作,隐藏和断屏启用意图仍阻止管理。不展示槽位、修订、时间或恢复历史;无存档或存在损坏槽位时禁用导出,清除可重复执行。点击“清除”弹出包含组件名称及全部存档不可恢复提示的确认框,提供“清除存档”和“取消”,默认选择取消;取消或Esc关闭不清除,确认后才执行。 - -导出一次包含该安装全部槽位的当前有效正文,JSON为`{widgetId,slots:{slot:value}}`,不附加宿主修订、时间、配置、绑定、权限或本机路径。复用既有有界exports暂存、可信系统保存选择、覆盖确认及同目录原子发布。读取中遇到不可恢复的损坏时拒绝导出并保留原文件;清除仍可用。导出文件属于用户,不随清除或卸载删除;用户取消或票据失效保留已有输出。 +组件页抽屉在组件操作行下方展示“存档”栏及“清除”按钮,作用于整份安装存档,不依赖显示器或实例是否存在。安装全部实例停用后可操作,隐藏和断屏启用意图仍阻止管理。清除可重复执行。点击“清除”弹出包含组件名称及全部存档不可恢复提示的确认框,提供“清除存档”和“取消”,默认选择取消;取消或Esc关闭不清除,确认后才执行。 清除针对该安装的全部存档槽和内部恢复副本,不清除配置、实例KV、缓存、浏览数据或其他安装数据。Services取得安装存储锁,复核停用、取消及安装身份后,将存档目录原子移至固定清理目录作为提交点;提交前失败保留原存档,提交后不会恢复旧目录。随后回收清理目录,若回收失败明确提示存档已清除但残留待清理,后续访问尝试回收,清理目录不作为可读存档。不创建无限清理历史,重启也不读取已清除目录。 -重新启用任一实例、卸载或清除存档会使在途管理导出失效。执行与最终文件投递均检查有效性,UI仅调用应用服务,不在窗口线程读写存档。清除后下次启用由作者按空存档初始化,宿主不执行作者迁移代码。 +重新启用任一实例或卸载使在途管理操作失效。UI仅调用应用服务,不在窗口线程读写存档。清除后下次启用由作者按空存档初始化,宿主不执行作者迁移代码。 ContentDialog的按钮与Esc返回行为依据[Windows App SDK官方文档](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog);关闭不触发清除。 @@ -52,6 +50,6 @@ ContentDialog的按钮与Esc返回行为依据[Windows App SDK官方文档](http 所有同安装实例都能直接读写,宿主不设主副角色或自动接管。所有写入仍带 expectedRevision,安装锁串行原子提交,过期修订返回 SAVE_CONFLICT;重读、合并和业务协调由作者处理,不自动覆盖。 -布局只保存各显示器的排布和配置。保存、覆盖、应用或恢复布局不复制、切换、回退或清空存档;组件包版本回退同样不回退存档。管理导出和清除要求该安装全部实例停用,重新启用任一实例即使在途管理操作失效。 +布局只保存各显示器的排布和配置。保存、覆盖、应用或恢复布局不复制、切换、回退或清空存档;组件包版本回退同样不回退存档。管理清除要求该安装全部实例停用,重新启用任一实例即使在途管理操作失效。 共享的是 saves.* 数据;配置、实例 KV、权限、缓存与浏览数据保持各自归属。协作消息仅是可丢失的变更提示,不能代替成功存档。 diff --git a/docs/reference/modules/workshop.md b/docs/reference/modules/workshop.md index 1bd40cb..3225526 100644 --- a/docs/reference/modules/workshop.md +++ b/docs/reference/modules/workshop.md @@ -72,10 +72,12 @@ Steam 适配器负责 SDK 初始化、回调泵和退出,与组件恢复独立 新发布默认公开,可明确选择其他可见范围;已有草稿保留所选范围。未填写更新条目 ID 时不能提交或保存;保存更新草稿同时保存条目 ID 和更新说明。已关联条目的草稿固定为更新,目标只读;创建结果未知时只能选择更新并找回原条目 ID,避免重复创建。草稿卡片在作品名右侧显示清洁上传副本的版本,上传成功只显示“上传成功”;仍需处理的错误、协议和创建结果未知状态保持明确。 -组件发布显示预览图和实际上传文件清单。布局从布局抽屉直接进入同一个发布/更新弹窗,不再先弹出“发布布局内容”;布局弹窗不显示预览图、实际上传文件清单或原始布局JSON,改为列出包含的组件名称与UUID。可分享普通配置在同一弹窗中逐项显示名称和值并供勾选,新草稿默认不选,保存后保留选择;发布和更新使用相同的分享选择。配置候选和值在准备草稿时由服务筛选并冻结,后续只接受候选中的UUID/字段键,不接受界面传入任意配置值。保存只提交草稿,实际上传前由草稿生成并校验布局文件;失败保留可重试草稿。缺少 preview 时使用产品占位图或布局排布示意,不自动截图用户桌面。 +组件发布显示预览图和实际上传文件清单。布局从布局抽屉直接进入同一个发布/更新弹窗,不再先弹出“发布布局内容”;布局弹窗不显示预览图、实际上传文件清单或原始布局JSON,改为列出包含的组件名称与UUID。可分享普通配置在同一弹窗中逐项显示名称和值并供勾选,新草稿默认不选,保存后保留选择;发布和更新使用相同的分享选择。配置候选和值在准备草稿时由服务筛选并冻结,后续只接受候选中的UUID/字段键,不接受界面传入任意配置值。保存只提交草稿,实际上传前由草稿生成并校验布局文件;失败保留可重试草稿。缺少 preview 时使用产品占位图,不自动截图用户桌面。 创建条目得到 PublishedFileId 后保存发布草稿,更新同一作品时复用身份,不能因重试自动创建多个条目。上传目录为清洁副本,只含作者内容和所选元数据;组件来源记录、运行数据、绑定、日志和秘密不得进入。 检查 SDK 初始化、当前用户、条目所有权、App ID、内容类型和校验结果。确认 Steam 返回成功后才能报告上传成功;需要接受协议、审核或可见性生效时显示真实后续状态,不声称立即公开。失败保留可重试草稿,不自动更换目标或可见范围。 +布局发布版本由Services管理,核对条目后取高于远端及同作品已冻结草稿的版本,再持久化冻结布局和版本。上传失败、超时或结果未知后的重试使用相同冻结内容;改变分享配置需要新建草稿。其他更新已超过冻结版本时拒绝旧草稿,避免版本倒退;作品身份保持不变。 + 布局发布沿用[布局协议](../contracts/layout.md)的 UUID 依赖,不检查组件来源或要求填写工坊组件引用。布局的“安装组件齐全才应用”不改变 Steam 自己的订阅机制。 diff --git a/host-snapshot.json b/host-snapshot.json index 542efcf..37f3fd3 100644 --- a/host-snapshot.json +++ b/host-snapshot.json @@ -40,14 +40,14 @@ { "source": "docs/contracts/host-api.md", "destination": "docs/reference/contracts/host-api.md", - "sourceSha256": "226ae778e369f34b2d23e2e1a6fd94e45264b2b70ad28820b19f9697eef17367", - "sha256": "f628be738175c15cfd7aa1c1bbef69dfc2d95a2738221666f9c6c053b7f50675" + "sourceSha256": "33dd48bfadcdfc5b3849f6299afb266e7770bb4114eb441534684693474248e6", + "sha256": "6fc092164ac641b3152abac7db0cc0968a72424543e4f2c9771c4687499456c7" }, { "source": "docs/contracts/layout.md", "destination": "docs/reference/contracts/layout.md", - "sourceSha256": "de3c5b88af8cac2938f2cc2ad49e6013e223112f2764ec3d393f9c7b6cb3adc0", - "sha256": "f83013f72233b4230a13b50293c74a041f93bfcbb4cf4b7631c6c9bb7b28487f" + "sourceSha256": "a5f9d13f0da8ac59361c2acf01f03240f79815666ade4dd8b2c52fbee118951e", + "sha256": "1efa294cf50b8bd66df0082595453ae4af138d5e0f85faa169f67d6c0087b3f8" }, { "source": "docs/contracts/reminders.md", @@ -58,8 +58,8 @@ { "source": "docs/contracts/saves.md", "destination": "docs/reference/contracts/saves.md", - "sourceSha256": "b27a2f9eb711a9a2e937f681cfb3022ca7de356f0ed559b78a392a0e467b6ef2", - "sha256": "361de4729b61e95d2c3c35520a39542c0ec128488d2a81a21efe7c7ab3868087" + "sourceSha256": "e907d4d51ab921b11de75fda1b085f42273bae0b666ee1add2981d2bb5dd0c0a", + "sha256": "9b8a8df7447260afaa42ff05ebc4d9eb10d15b5e82373c420bc3323f831bf473" }, { "source": "docs/contracts/system-integration.md", @@ -118,8 +118,8 @@ { "source": "docs/modules/workshop.md", "destination": "docs/reference/modules/workshop.md", - "sourceSha256": "cd4f4fe2a07085b443a1f6785da5c5814eb3956546680815e803d28118553305", - "sha256": "2ced55578ceeebbe3d6220bf1dfca98734058ccaa77a52bedadda214cde21199" + "sourceSha256": "8ae8e49d86bf37a34a242bbf6159a9e4fccefe7def4e679f48a2553c44d5d99f", + "sha256": "eab7891fabf1deda6412f7a21517aade25597ebea605c130491a1f93e183a74c" }, { "source": "examples/edge-garden/audio.js",