开发组件与作者SDK

作者 SDK

sdk/是JS、TypeScript声明及机器可读协议的唯一维护来源，当前版本0.1.2。宿主将widget-host.js编译为自身资源，在包主文档创建时、业务脚本执行前提供window.widgetHost，等待注册完成后才导航；重载和版本切换同样自动提供。组件包不携带widget-host.js、widget-host.d.ts或protocol.json，不添加SDK脚本标签。类型声明供编辑器和构建工具从宿主随附sdk目录引用，不进入发布包；protocol.json由宿主和开发工具使用。SDK变化同步宿主、开发工具及许可证。Worker没有直接宿主桥接。组件可通过 widgetHost.context.language 和 language.changed 无权限读取并跟随宿主实际语言，定义见宿主语言。强调色、文字缩放及组件原生菜单见宿主接口，均无需Capability；菜单按实例文档注册，重载后由作者重新设置。协议版本及兼容范围遵循格式版本规则（宿主文档：../development.md#格式版本兼容与迁移）。

ready提供context/features/limits；事件先更新context，on返回解除函数，离开取消调用并释放订阅。compatibility分开报告宿主支持、浏览器API存在、实际探测和未实测设备，不能从存在性推定可用性。Capability可拒绝，安装获准后直接调用；外链不逐次确认，实际系统选择/覆盖和本人账号同意保留。

TypeScript使用ES2020、DOM、strict及noEmit，不启用skipLibCheck。HTTP头的明文value与秘密绑定互斥，target.open固定绑定与目录相对路径互斥；类型与运行拒绝一致。验证编译器由环境显式提供，不自动下载或分发。新建模板在pagehide取消配置读取并解除订阅，迟到握手、错误和可见性回调不改旧DOM。

作者 SDK 版本管理

作者 SDK 不锁定，当前为 0.1.2，采用独立的 major.minor.patch 三段版本。sdk/protocol.json 的 sdkVersion 是当前版本来源，widget-host.js 标头、类型声明、宿主分发及作者指南必须同步；SDK 版本不是宿主最低版本或权限授予依据。组件的接口代际、必需特性及不兼容处理统一见运行兼容性。

阶段/变更	递增规则
0.x 开发阶段	日常增量调整和修正递增 patch，包括标签目录等有限范围的协议调整；仅用户明确决定进入新的 SDK 功能阶段时递增 minor 并将 patch 归零。破坏性变化须明确列出受影响方法、类型、事件和作者需修改的内容
1.0.0 起	不兼容公开接口/行为变更递增 major，兼容新增递增 minor，修复递增 patch；递增后右侧段归零
各阶段的修复	不改变公开契约的 SDK 实现或声明修正递增 patch；改变约定行为或调用方式按破坏性变更处理
无 SDK 变化	仅改宿主界面、内部重构、打包、文档措辞或组件业务时保持 SDK 版本

同一次交付按最高影响递增一次，不按 Build 次数、应用版本或 Steam BuildID 自动递增。已分发的不同 SDK 内容不得复用同一 SDK 版本；纯注释和排版不触发递增。SDK 变更须先改唯一来源及权威协议，再同步 JS、TypeScript、机器协议、相关示例、宿主输出及中英作者指南，完成受影响验证后分发。

hostApiMajor/apiMajor 表示宿主接口兼容代际，protocolVersion 表示桥接信封/握手格式代际，包/布局/存档 schemaVersion 和内部状态格式分别管理；它们不跟随 SDK 数字自动递增。仅各自契约的代际变化才更新相关值并同步双方校验；兼容与迁移遵循格式版本规则（宿主文档：../development.md#格式版本兼容与迁移），仍须按上表递增 SDK 并说明作者影响。当前各格式均以 v1 为基线，分别管理。组件及布局 manifest.version 仍使用自己的三段版本，不改成应用四段版本。

身份与目录

开发页仅包含用户显式新建或添加已有项目得到的开发组件；普通本地导入、内置及工坊组件不会自动归入开发。宿主记录 development:<widgetId> 安装身份，新增遵循全局widgetId去重（宿主文档：../architecture.md#身份与数据归属），不因更换目录或来源绕过；包声明不能自行指定来源。

新建收集名称、作者、描述、标签和父目录，在其中创建以组件名命名的新目录，生成 manifest.json、index.html、style.css、main.js，校验安装后打开详情。名称须可作为单个 Windows 目录名，不接受路径、控制字符或末尾空格/句点；名称不合法或目标已存在时提示失败，不覆盖现有文件。安装身份仍使用独立 UUID。模板文件使用两空格缩进、正常换行及末尾换行，CSS 每个声明独占一行；默认版本号为 0.0.1，默认不启用、不授权。已有项目选择可运行组件包目录，使用构建工具时选择构建输出目录，宿主不执行构建命令。一个开发身份绑定一个目录；重复添加相同或其他目录均提示已添加，不覆盖原绑定，更新使用重载；移动目录后需移除开发安装并从新目录重新添加。

源码目录不能与宿主数据目录重叠，避免更新反馈循环。源码目录仅作为用户选择的输入；运行仍使用宿主复制校验后的不可变版本。源码路径仅保存在本机安装记录和开发详情，不写入日志、布局或分享包。移除开发组件清理安装专属数据而不删除源码。目录缺失保留最后成功版本；恢复原目录或移除开发安装后重新添加。

目录名校验包含 Windows 保留设备名及带扩展名的变体，按 Windows 文件命名规则 处理，不能仅依赖底层目录创建是否成功。

“调整配置”读取当前源码，修改名称、作者、描述及标签，保留目录、UUID、版本、配置和能力声明。多语言项目修改默认语言中的名称和描述，保留其他翻译与引用。保存前检查当前身份、目录及编辑修订，源码已被其他编辑器修改时拒绝覆盖；文件更新后走现有开发重载与统一激活流程，激活失败保留可用版本。

更新与失败

开发者模式开启时，默认自动检测绑定目录变化，连续变动合并并等待至少一秒稳定后重新复制校验。每个项目可关闭自动重载，并保留手动重载按钮。手动重载立即检查源码，内容相同时也重启运行实例；自动检测无变化时不重启。

开发内容以哈希作为内部修订，允许声明版本不变或降低；正式本地导入及工坊更新仍执行原版本规则。校验失败保留当前版本；复制过程中再次变化则放弃该次候选，等待稳定后重试。一次激活影响该安装全部屏幕，隐藏实例更新，停用实例保持停用，断屏实例回接时运行当前版本。配置、授权及版本恢复沿用安装事务，新增能力不自动授权。

存在该组件未保存配置草稿时暂缓自动激活，显示等待保存提示；手动更新使用已有保存/放弃/继续编辑流程。校验与激活失败保留原版本；脚本业务错误仍属于运行故障，提供手动重载，不提供手动恢复上一版本入口。

关闭开发者模式停止检测和新调试操作，开发组件继续运行最后成功版本，仍在组件与显示页出现。重新开启后重新检查源码。已打开调试窗口沿用原行为，停用实例时关闭。

页面与操作

开发页按安装组件展示同款卡片网格，每个开发组件一张卡片，包括未运行者；搜索名称或作者，右上角并排显示“新建组件”“添加组件”和“检查组件包”按钮，后者直接选择已有项目目录，不设置“更多”菜单。卡片和三个页面的详情均显示来源“开发”；组件页来源筛选增加开发。

开发抽屉依次为预览、名称、作者及版本、来源、非空描述（空描述不占位）、项目目录操作、自动重载开关和维护栏，不自动启用组件。项目目录下同一行依次为“打开目录”“重载”“发布”和更新状态文案；状态紧邻项目目录操作右侧，长反馈在剩余宽度内换行。维护栏的“移除”和“调整配置”按钮并排。点击“移除”显示确认窗口，标明组件名称并描述“组件目录不会被清理”；取消保持安装及运行状态，确认后移除安装，保留作者目录。

全部作者开发入口集中于开发页。页头标题右侧提供 GitHub 图标按钮，打开固定的 https://github.com/wangdiandao/widget-workshop-dev 作者指南仓库；按钮具有悬停提示、键盘焦点和可访问名称，图标继承主题与禁用状态。页头操作提供新建、添加和检查组件包；已有项目抽屉提供源码目录、重定位、重载、自动重载、包检查、按显示器选择实例后打开调试工具，以及恢复/移除。只读包检查复用可信服务与CLI同一报告，显示有效性、文件数/字节数或错误阶段；不安装或执行作者内容。Python工具提供补充静态引用诊断。调试选择器仅列出该组件已启用实例所属的显示器；没有启用实例时列表为空且按钮禁用，不自动启用。调试显示器选择器与显示/布局页共用在线状态项，友好名前绿点表示在线、红点表示断开，并提供完整名称与连接状态的可访问描述；仅保留该组件仍有启用意图的断开显示器，断开项及尚未就绪的实例不能打开调试工具。

开发页重载读取源码并更新全部屏幕；组件页重载重新加载该安装的全部启用实例。开发抽屉中的操作反馈位于目录操作组旁，宽度不足或文字较长时放到下一行；不能与滚动条、按钮重叠。自动更新沿用该状态位置，不弹成功对话框。新建或添加尚未建立组件身份时，失败仍在创建流程或页面反馈。抽屉关闭、调宽、焦点和草稿规则沿用管理界面（宿主文档：ui.md）。

计算画布

examples/worker-canvas使用包内Worker完成1–10000个有限数字的统计，输入最多200000字符，空白和中英文逗号只作为分隔符，不产生隐式零值。一次只有一个计算任务，绘制状态只有一条在途与一份最新待发，响应目标期限五秒；错误/超时终止Worker，明确重试而非无限重启。

OffscreenCanvas绘制遵循页面/宿主显隐及独立锁屏/挂起状态；减少动画静态一帧，节能最多10fps。暂停绘制不妨碍工具计算。用户取消重建画布供重试；页面关闭只释放任务、计时器、Worker和监听，不替换画布或覆盖结果，计算/取消/试听/报告按钮禁用并解除处理器。

兼容报告独立单槽并支持取消，迟到结果不回填。试听等待最多两秒、同一时刻一个操作，离开/失败释放节点和AudioContext。持久提醒有八个命名位置与秒/分/小时/天输入，独立单槽，修改成功后列表读取失败或取消仍保留已确认反馈。具体规则见提醒和音频。

本地开发功能验证组件

examples中的组件仅供仓库本地导入/开发验证，不进入应用输出或导出；作者新建项目生成的基础模板与这些验证组件分开。随应用分发的内置组件见内置效率组件（宿主文档：builtin-widgets.md）。

验证组件	行为定义
permission-lab	声明全部Capability并展示实时授权状态；目录、启动目标和秘密字段用于查看绑定编辑器，不主动执行系统能力
transparent-pet	透明桌宠与输入
stardust	装饰绘制、背压及降级
edge-garden	边缘游戏与存档
file-tool	统计、PNG、目录及剪贴板
github-tasks	只读账号任务
media-remote	当前媒体会话
system-card	先读取合法非负安全整数再保存计数，单次提交；指标单槽，撤权清空，晚结果拒绝，计数不是离线秒表
wasm-card	先编译包内固定小模块，确认页面有效后实例化并执行；离开取消读取并丢弃迟到编译结果，不宣称停止引擎编译

布局与发布

开发组件可进入布局，依赖仅记录组件 UUID 和宿主API主版本，不保存来源或源码路径；工坊发布使用相同引用，不要求重绑定。布局schemaVersion=1，格式规则见布局。

开发页对应组件抽屉提供“发布”，校验当前项目源码并创建清洁上传副本，不要求先激活源码，也不改变当前运行版本。源码widgetId须仍与所选开发组件一致，身份变化拒绝发布。对应草稿、上传状态、编辑/提交及移除入口均在该组件抽屉内；新发布默认公开和默认不分享配置等发布规则见工坊模块。