diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4d96d94..2a49980 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,6 +64,7 @@ jobs: run: | git submodule update --init --depth 1 vendor/meta-protocols/dsh-std git submodule update --init --depth 1 vendor/meta-protocols/dsh-distribution + git submodule update --init --depth 1 vendor/sub-protocols/dsh-skin git submodule update --init --depth 1 vendor/examples/dsh-dpx - name: 深校验(含挂载内规范入口) @@ -73,4 +74,5 @@ jobs: run: | test -f vendor/meta-protocols/dsh-std/README.md test -f vendor/meta-protocols/dsh-distribution/docs/getting-started.md + test -f vendor/sub-protocols/dsh-skin/convention.md test -f vendor/examples/dsh-dpx/README.md diff --git a/.gitmodules b/.gitmodules index 32670ba..57815d8 100644 --- a/.gitmodules +++ b/.gitmodules @@ -7,3 +7,6 @@ [submodule "dsh-dpx"] path = vendor/examples/dsh-dpx url = https://github.com/T-Auto/dsh-dpx.git +[submodule "dsh-skin"] + path = vendor/sub-protocols/dsh-skin + url = https://github.com/DSH-EAC/dsh-ui-skin-loader-convention.git diff --git a/README.md b/README.md index 3b75a96..69e5e76 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ dsh-ecosystem-spec/ ├── profiles/ 产品准入 Profile(只约束自己声明的生态范围) ├── vendor/ 挂载区(git submodule) │ ├── meta-protocols/ dsh-std、dsh-distribution -│ ├── sub-protocols/ 子协议(预留:皮肤 / UI 插件协议等) +│ ├── sub-protocols/ 子协议(dsh-skin:DSH UI 皮肤加载公约) │ └── examples/ 范例实现(dsh-dpx) ├── scripts/ 本仓库自己的校验脚本 └── .github/ 本仓库自己的 CI @@ -74,6 +74,7 @@ dsh-ecosystem-spec/ | --- | --- | --- | --- | --- | | 元协议 | dsh-std | Draft | [`vendor/meta-protocols/dsh-std`](vendor/meta-protocols/dsh-std) | 插件 / 宿主 / 运行时互操作 | | 元协议 | dsh-distribution | Draft | [`vendor/meta-protocols/dsh-distribution`](vendor/meta-protocols/dsh-distribution) | DSH 环境的身份与可迁移性 | +| 子协议 | dsh-skin | Experimental | [`vendor/sub-protocols/dsh-skin`](vendor/sub-protocols/dsh-skin) | 皮肤插件与加载器之间的加载启停接缝 | | 范例实现 | dsh-dpx | Experimental | [`vendor/examples/dsh-dpx`](vendor/examples/dsh-dpx) | dsh-distribution 的标准管理范例 | - 想知道**以后新协议 / 新范例该放哪**:[`docs/directory-guide.md`](docs/directory-guide.md) diff --git a/docs/directory-guide.md b/docs/directory-guide.md index 561b5d0..2ab2d14 100644 --- a/docs/directory-guide.md +++ b/docs/directory-guide.md @@ -101,7 +101,6 @@ Profile 在协议之上约束自己的生态。任何一层都不得修改上一 | 方向 | 归属层 | 落位 | | --- | --- | --- | -| 皮肤 / UI 插件协议(基于 dsh-std) | 子协议 | `vendor/sub-protocols/dsh-skin` + `registry/protocols.json` | | 皮肤管理器(统一启停、回退) | 范例实现 | `vendor/examples/dsh-skin-manager` + `docs/examples/dsh-skin-manager.md` | | 插件市场 / 推荐列表 | 范例实现 | `vendor/examples/` + `docs/examples/.md` | | TUI 等产品准入 Profile | 产品准入 | `profiles//` + `registry/profiles.json` | diff --git a/docs/overview.md b/docs/overview.md index 2f1af2b..ab358d3 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -27,8 +27,8 @@ - **元协议**(`@dsh-std/core`、`dsh-distribution`)本身不含领域业务字段,它是 “关于协议的协议”与环境身份协议; -- **子协议**建立在元协议之上,独立版本化、独立演进(例如正在酝酿的皮肤 / UI - 插件协议); +- **子协议**建立在元协议之上,独立版本化、独立演进(例如皮肤 / UI 插件子协议 + `dsh-skin`); - **范例实现**用来证明协议可被真实产品按同一套说法描述与管理,它不是标准; - **Profile** 在协议之上加产品准入规则,必须标注适用范围,不倒灌成所有生态的强制要求。 @@ -42,18 +42,50 @@ | 元协议 | `dsh-std` | Draft | [`vendor/meta-protocols/dsh-std`](../vendor/meta-protocols/dsh-std) | | 元协议 | `dsh-distribution` | Draft | [`vendor/meta-protocols/dsh-distribution`](../vendor/meta-protocols/dsh-distribution) | | 范例实现 | `dsh-dpx` | Experimental | [`vendor/examples/dsh-dpx`](../vendor/examples/dsh-dpx) | -| 子协议 | —— 尚未收录 | —— | `vendor/sub-protocols/` | +| 子协议 | `dsh-skin` | Experimental | [`vendor/sub-protocols/dsh-skin`](../vendor/sub-protocols/dsh-skin) | | Profile | —— 尚未收录 | —— | `profiles/` | 机器可读版本见 [`registry/protocols.json`](../registry/protocols.json) 与 [`registry/implementations.json`](../registry/implementations.json)。 +### 3.1 子协议 `dsh-skin`:DSH UI 皮肤加载公约 + +> 本节只是索引性摘要;规范正文以挂载的 +> [`vendor/sub-protocols/dsh-skin/convention.md`](../vendor/sub-protocols/dsh-skin/convention.md) +> 为准,本仓库不复制、不改写。 + +[`dsh-skin`](https://github.com/DSH-EAC/dsh-ui-skin-loader-convention) +(协议 id `dsh.ecosystem.ui-skin-loader/v1`,维护者 DSH-EAC)是生态收录的第一个 +子协议:一份**弱约束**公约,只定义“皮肤插件”(Skin)与“加载器”(Loader)之间的 +最小接缝——皮肤不占用什么、何时被启用、收到什么、何时必须彻底关闭。它建立在 +`dsh-std` 之上(`buildsOn: dsh-std`),落位即目录规范为皮肤 / UI 插件协议预留的 +`vendor/sub-protocols/dsh-skin`。 + +公约的全部强制内容只有三节(公约 §3–§5): + +- **唯一声明**(§3):皮肤在 `package.json` 的 `dsh.skin` 字段声明 `apiVersion` / + `id` 等——这是公约对皮肤唯一的“占用”;声明不等于激活; +- **生命周期**(§4):`skin/activate` / `skin/deactivate` 两个语义事件,同一宿主 + 实例内至多一个皮肤激活,“退出后不可观测”才算彻底关闭; +- **不占用清单**(§5):八条红线 R1–R8——未激活零副作用、不碰加载器保留面、 + 不碰其他皮肤、不碰宿主恢复面、不依赖非 ABI、不自启、不启停他人、退出即净。 + +§6 扩展槽位是纯可选的新增机制(槽位集只增、不改、不删;初始槽位表照录公约), +皮肤可以只声明 `dsh.skin` 而不贡献任何槽位。 + +它刻意不做(公约 §7),并与相邻体系分工:**强契约**的包格式、事务与故障隔离 +(ADR 0001–0003)属于 `dsh-ui-skin-manager`,公约不碰;**EAC 桌面宿主**的槽位 +拓扑与能力边界由 `DSH-Desktop-EAC-UI-Skin-Authoring-Convention` 规定,它是本公约 +之下的一种宿主实现约定。三者互不重叠、不竞争;公约本身是跨宿主、实现无关的 +加载启停弱约束。 + ## 4. 生态角色与边界 | 角色 | 拥有 | 不拥有 | | --- | --- | --- | | `dsh-std` | 公共协议定义、声明/发现/协商机制、参考包 | 不定义产品准入;不自我认证 | | `dsh-distribution` | 环境身份、受控布局、发现与可迁移性协议 | 不是安装器、不是运行时、不是指定管理器 | +| `dsh-skin` | 皮肤插件与加载器之间的加载启停接缝:唯一声明、生命周期、不占用清单 | 不定义包格式;不规定故障隔离细则;不约束皮肤内部实现;不做宿主特化 | | `dsh-ecosystem-spec` | 入口、索引、说明、治理、本仓库 CI | 不重新定义协议语义;不认证实现;不替官方表态 | | 各实现 / 范例 | 实现、conformance 证据、使用经验 | 不能自称官方实现,不能自我认证 | @@ -80,7 +112,7 @@ DSH 生态天然是“多种宿主 / 多种终端 / 多种市场 / 多种实现 ## 7. 当前状态与边界 -- 两个元协议均处于上游自称的 **Draft** 阶段,`dsh-dpx` 为 **Experimental**; +- 两个元协议均处于上游自称的 **Draft** 阶段,`dsh-dpx` 与 `dsh-skin` 为 **Experimental**; - 重构前的 TUI 时代内容(准入规范、conformance、registry contracts、adapters、RFC 等) 已移出工作树,需要时从 git 历史取回,见 [`decisions/0001-remove-legacy-archive.md`](../decisions/0001-remove-legacy-archive.md); diff --git a/registry/protocols.json b/registry/protocols.json index c18b1da..5d9a42e 100644 --- a/registry/protocols.json +++ b/registry/protocols.json @@ -2,7 +2,7 @@ "$schema": "./schema/index.schema.json", "document": "protocols", "version": 1, - "updated": "2026-09-09", + "updated": "2026-09-25", "scope": "本仓库收录的协议索引。索引只登记事实:谁拥有、挂在哪里、上游自称什么状态;不授予状态、不认证实现、不构成安全保证。", "entries": [ { @@ -32,6 +32,21 @@ "specEntry": "docs/getting-started.md", "doc": "docs/overview.md", "notes": "上游 README 自称 Draft(草案),本索引照录为 Draft。" + }, + { + "id": "dsh-skin", + "displayName": "DSH UI 皮肤加载公约", + "category": "sub-protocol", + "scope": "皮肤插件与加载器之间的最小接缝:皮肤不占用什么、何时被启用、收到什么、何时必须彻底关闭;不定义包格式,不约束皮肤内部实现,不做宿主特化。", + "status": "Experimental", + "statusSource": "upstream", + "upstream": "https://github.com/DSH-EAC/dsh-ui-skin-loader-convention.git", + "maintainer": "DSH-EAC", + "mount": "vendor/sub-protocols/dsh-skin", + "specEntry": "convention.md", + "buildsOn": ["dsh-std"], + "doc": "docs/overview.md", + "notes": "弱约束公约:只定义加载启停接缝,包格式、事务与故障隔离留给 dsh-ui-skin-manager 的强契约体系,宿主特化留给 DSH-Desktop-EAC-UI-Skin-Authoring-Convention。上游 convention.md 头表自称 Experimental,本索引照录。" } ] } diff --git a/vendor/README.md b/vendor/README.md index 896c9e5..b289e42 100644 --- a/vendor/README.md +++ b/vendor/README.md @@ -14,7 +14,7 @@ vendor/ │ ├── dsh-std/ → Yan-Zero/dsh-std │ └── dsh-distribution/ → T-Auto/dsh-distribution ├── sub-protocols/ # 子协议:在元协议之上定义具体领域行为 -│ └── (预留) +│ └── dsh-skin/ → DSH-EAC/dsh-ui-skin-loader-convention └── examples/ # 范例实现:证明协议可被真实产品按同一套说法管理 └── dsh-dpx/ → T-Auto/dsh-dpx ``` @@ -28,6 +28,7 @@ vendor/ | --- | --- | --- | --- | --- | | [`meta-protocols/dsh-std`](meta-protocols/dsh-std) | 元协议 | [Yan-Zero/dsh-std](https://github.com/Yan-Zero/dsh-std) | [`registry/protocols.json`](../registry/protocols.json) | [`docs/overview.md`](../docs/overview.md) | | [`meta-protocols/dsh-distribution`](meta-protocols/dsh-distribution) | 元协议 | [T-Auto/dsh-distribution](https://github.com/T-Auto/dsh-distribution) | [`registry/protocols.json`](../registry/protocols.json) | [`docs/overview.md`](../docs/overview.md) | +| [`sub-protocols/dsh-skin`](sub-protocols/dsh-skin) | 子协议 | [DSH-EAC/dsh-ui-skin-loader-convention](https://github.com/DSH-EAC/dsh-ui-skin-loader-convention) | [`registry/protocols.json`](../registry/protocols.json) | [`docs/overview.md`](../docs/overview.md) | | [`examples/dsh-dpx`](examples/dsh-dpx) | 范例实现 | [T-Auto/dsh-dpx](https://github.com/T-Auto/dsh-dpx) | [`registry/implementations.json`](../registry/implementations.json) | [`docs/examples/dsh-dpx.md`](../docs/examples/dsh-dpx.md) | 挂载固定到具体 revision(gitlink 就是唯一事实来源)。本仓库**不复制**上游正文, diff --git a/vendor/sub-protocols/README.md b/vendor/sub-protocols/README.md index 66dea6e..8d82b82 100644 --- a/vendor/sub-protocols/README.md +++ b/vendor/sub-protocols/README.md @@ -1,6 +1,6 @@ -# vendor/sub-protocols —— 子协议挂载区(当前为空) +# vendor/sub-protocols —— 子协议挂载区 -本目录预留给**子协议**:在元协议之上定义具体领域行为的协议仓库。 +本目录存放**子协议**挂载:在元协议之上定义具体领域行为的协议仓库。 元协议只回答“如何声明、发现、协商”;子协议回答“某类东西具体怎么协作”。 子协议不修改元协议语义,独立版本化、独立挂载、独立演进。 @@ -12,19 +12,19 @@ - 它有自己的上游仓库、自己的维护方、自己的版本与状态; - 它**不**把某个产品的实现细节变成对所有生态的强制要求。 -## 2. 已经可以预期的一个例子:皮肤 / UI 插件协议 +## 2. 当前子协议:dsh-skin(DSH UI 皮肤加载公约) -生态正在酝酿一类“皮肤 / UI 插件”协议:基于 `dsh-std` 的呈现(Presentation)与 -清单(manifest)机制,让皮肤、主题、界面插件用统一坐标声明自己,从而可以被 -一个**皮肤管理器**统一发现、安装、启停与回退——而**不约束**任何皮肤的实现自由度: -皮肤仍然可以自己决定用什么渲染技术、什么资源格式、是否依赖某个宿主。 - -它落地时,位置是确定的: +生态收录的第一个子协议已落地:[`dsh-skin/`](dsh-skin)(上游 +[DSH-EAC/dsh-ui-skin-loader-convention](https://github.com/DSH-EAC/dsh-ui-skin-loader-convention), +协议 id `dsh.ecosystem.ui-skin-loader/v1`)。它是一份**弱约束**公约:只定义皮肤 +插件与加载器之间的最小接缝——皮肤不占用什么、何时被启用、收到什么、何时必须 +彻底关闭;不定义包格式,不约束皮肤内部实现,不做宿主特化。它基于 `dsh-std` +(索引条目 `buildsOn`),落位即本目录预留的位置: ```text -vendor/sub-protocols/<子协议 id>/ # 协议本体(submodule,固定 revision) +vendor/sub-protocols/dsh-skin/ # 协议本体(submodule,固定 revision) registry/protocols.json # category = "sub-protocol" 的索引条目 -docs/overview.md # 在生态总览里补一节 +docs/overview.md # 在生态总览里分节说明 ``` 对应的管理器属于**范例实现**,挂到 `vendor/examples/`,并配 @@ -42,5 +42,5 @@ docs/overview.md # 在生态总览里补一节 [`../../docs/directory-guide.md`](../../docs/directory-guide.md) 的清单里同步; 5. `node scripts/verify-structure.mjs` 全绿。 -本目录当前没有挂载,因此只有本说明文件;一旦有第一个子协议,请把它的入口链接补到 -[`../README.md`](../README.md) 的挂载表。 +当前唯一挂载 `dsh-skin` 的入口链接已补入 [`../README.md`](../README.md) 的挂载表; +以后每个新子协议照此办理。 diff --git a/vendor/sub-protocols/dsh-skin b/vendor/sub-protocols/dsh-skin new file mode 160000 index 0000000..c7fa652 --- /dev/null +++ b/vendor/sub-protocols/dsh-skin @@ -0,0 +1 @@ +Subproject commit c7fa6525e606c7dae36f92c2cae638447e9a384d