From b546a14dbddb657d676f6d7208b954ccf98cbb05 Mon Sep 17 00:00:00 2001 From: zouyuxuan122 Date: Fri, 25 Sep 2026 19:42:34 +0800 Subject: [PATCH 1/2] =?UTF-8?q?Mount:=20add=20dsh-skin=20sub-protocol=20(D?= =?UTF-8?q?SH=20UI=20=E7=9A=AE=E8=82=A4=E5=8A=A0=E8=BD=BD=E5=85=AC?= =?UTF-8?q?=E7=BA=A6=20v1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scope: one category of change - ecosystem admission of a new sub-protocol (docs/directory-guide.md §4). The mount (gitlink + .gitmodules), the registry entry, and the doc syncs that admission requires are interdependent and each listed below. No verifier rule, no governance rule, and no existing entry is touched. Status: Experimental upstream. The convention repository's own header table (convention.md) declares status Experimental and maintainer DSH-EAC; the index copies that declaration (statusSource: upstream) and invents none. Normative change: none authored here. The mounted covenant text (protocol id dsh.ecosystem.ui-skin-loader/v1) is pinned unmodified; this repository only mounts, indexes and describes it. Pinned revision: dsh-skin (new) 846834963a8ff66f7a949560d3566b8a35e37cf1 DSH-EAC/dsh-ui-skin-loader-convention What the entry says: - id dsh-skin (the path directory-guide.md §7 reserved for this sub-protocol), category sub-protocol, buildsOn dsh-std, mount vendor/sub-protocols/dsh-skin, specEntry convention.md, status Experimental (upstream-declared). It is a weak-constraint covenant: the minimal seam between skin plugins and a loader - what a skin must not occupy, when it is enabled, what it receives, when it must shut down completely. Doc syncs required by docs/directory-guide.md §4 for a new sub-protocol: - docs/overview.md: admission table row, a new §3.1 digest section (what it is, the three mandatory sections §3-§5, the optional add-only slot mechanism, the division of labor vs. the strong-contract manager and the host authoring convention), and the role-boundary table row; - vendor/README.md: directory tree and mount table; - vendor/sub-protocols/README.md: "currently empty" wording updated to the first landed mount, per that file's own instruction to link the first sub-protocol into ../README.md's mount table; - docs/directory-guide.md §7: the reserved row for the skin / UI plugin sub-protocol is fulfilled by this admission and removed from the not-yet-landed list; - README.md: homepage directory tree and mount table mirrored. Dependent CI change (declared per CONTRIBUTING.md §4): the mounts job lists mounts explicitly; vendor/sub-protocols/dsh-skin is added to its shallow-init step and its specEntry (convention.md) to the existence check, so deep verification covers the new pin. No check rule itself changed. Division of labor: this covenant is a cross-host, implementation-agnostic, weak load/start-stop seam. Strong-contract package format, transactions and fault isolation (ADR 0001-0003) stay with DSH-EAC/dsh-ui-skin-manager; EAC desktop host slot topology and capability boundaries stay with DSH-EAC/DSH-Desktop-EAC-UI-Skin-Authoring-Convention, a host implementation convention under this covenant. The three do not overlap and do not compete; this mount fulfils the slot reserved in directory-guide.md §7. Compatibility impact: additive. One new mount, one new index entry, doc syncs only; no existing entry, mount, rule or link changes meaning. vendor/ gains only the mount point (gitlink), so the no-stray-files rule still holds. Evidence: node scripts/verify-structure.mjs passes locally with all four mounts initialized: 16 top-level tracked entries whitelisted, 4 mounts parsed from .gitmodules, 3+1+0 index entries valid, 4 index entries matched bidirectionally to 4 live gitlinks (dsh-skin at mode 160000, gitlink 846834963a8ff66f7a949560d3566b8a35e37cf1, fetchable from the .gitmodules URL), 100/100 relative links resolved across 17 documents, and all specEntries present including vendor/sub-protocols/dsh-skin/convention.md. Fixtures: none - this repository holds no conformance suite. Conformance impact: none. The covenant defines no conformance suite; admission is indexing only, not certification. Migration: none. Consumers tracking this repository should re-init submodules to pick up the new mount. Rollback: drop the gitlink, the .gitmodules entry, the registry entry and the doc syncs; no data or format migration involved. --- .github/workflows/ci.yml | 2 ++ .gitmodules | 3 +++ README.md | 3 ++- docs/directory-guide.md | 1 - docs/overview.md | 40 ++++++++++++++++++++++++++++++---- registry/protocols.json | 17 ++++++++++++++- vendor/README.md | 3 ++- vendor/sub-protocols/README.md | 26 +++++++++++----------- vendor/sub-protocols/dsh-skin | 1 + 9 files changed, 75 insertions(+), 21 deletions(-) create mode 160000 vendor/sub-protocols/dsh-skin 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..8468349 --- /dev/null +++ b/vendor/sub-protocols/dsh-skin @@ -0,0 +1 @@ +Subproject commit 846834963a8ff66f7a949560d3566b8a35e37cf1 From 0c7d68585b104afc456c2fcab3a4e7d6bc74c621 Mon Sep 17 00:00:00 2001 From: zouyuxuan122 Date: Sat, 26 Sep 2026 08:50:26 +0800 Subject: [PATCH 2/2] =?UTF-8?q?Mount:=20bump=20dsh-skin=20submodule=20to?= =?UTF-8?q?=20covenant=20=C2=A79=20API-shape=20fix=20(8468349=20=E2=86=92?= =?UTF-8?q?=20c7fa652)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 公约 §9 示例伪码与 minimal-skin 骨架经实机核对修正为真实 client API 形态 （顶层 exports.inject 服务注入 + exports.apply(ctx) 内经加载器服务对象 registerSkin + ctx.effect 反登记）；§9 伪码性质与自检表不动，§4.2 机制自由 表述不受影响。.gitmodules 不变，仅 gitlink 前进。 --- vendor/sub-protocols/dsh-skin | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vendor/sub-protocols/dsh-skin b/vendor/sub-protocols/dsh-skin index 8468349..c7fa652 160000 --- a/vendor/sub-protocols/dsh-skin +++ b/vendor/sub-protocols/dsh-skin @@ -1 +1 @@ -Subproject commit 846834963a8ff66f7a949560d3566b8a35e37cf1 +Subproject commit c7fa6525e606c7dae36f92c2cae638447e9a384d