生态互操作规范 T-Auto/dsh-ecosystem-spec

dsh-ecosystem-spec

DSH Community Ecosystem Interoperability Specification
社区插件互操作规范实验库

这是什么项目？

这是由 dsh-TUI 团队和 DSH-Desktop-EAC 团队联合发起的社区协议，提供一套可选、可验证的互操作共识。有详细文档、验证自动化流程及开包即用的 skill，力求：

- 遵循此协议完全不影响任何功能开发自由度
- dsh 上游更新时，插件需要变更的代码更少
- 插件之间的兼容性更好，不再相互创死对方
- 插件之间可以更好的互相对话
- 多个整合包/独立 dsh 运行时可以统一管理、互相通讯并相互隔离

dsh-ecosystem-spec 收录了插件元协议 dsh-std、运行环境元协议 dsh-distribution 及相关子协议，前者面向插件作者，后者面向 dsh 发行版/整合包开发者。在元协议的框架下，「协议本身」也变成了可拔插的插件——这和 dsh 本体的理念不谋而合。

本规范并非官方标准，但我们希望为碎片化的 dsh 生态，接起插件对话的桥梁。

如果你没看懂，那可以理解为：

这套协议完全不干扰你实现任何想要的功能

如果你做插件，希望你的插件和其他插件一起装的时候兼容性更好，本项目里有你的插件【告诉其他插件你的版本号，你适配了什么版本的 dsh，你有什么兼容性需求/怎么被其他插件操作/怎么操作其他插件】的标准格式

如果你做 dsh 整合包，本项目也提供了【像 python 安装时勾选的「add to path」那样的标准路径格式】，向系统和其他整合包管理器告知你的 .dsh 用户文件存哪了，以及你的功能是什么，有什么需要注意的，为一个电脑可以多个 dsh 整合包共存奠定基础

以及一些代码工程规范、工程纪律或者解耦性要求。规范的，解耦的代码互相兼容当然更容易；和 dsh 上游 api 做了解耦的代码，适配版本变动当然也更容易更轻松；以及其他的兼容性和工程红利

关于解耦性要求，成熟的项目一定不会在代码里到处 import 上游包，这样上游更新的时候一大堆文件都得翻找并重写，解耦的做法是找个地方集中管理，这样其他部分的代码就不用动了。假如你不想每次都自己适配，你可以白嫖其他人做的集中管理层来适配新版本，比如用 dsh-TUI 的

dsh-ecosystem-spec 相关协议欢迎任何 dsh 开发者发起 issue 讨论或 pr。对 dsh-ecosystem-spec 相关生态可以在本仓库讨论，对本仓库收录的具体协议可以到对应仓库留言或发起 pr。

仓库结构：生态入口

本仓库是生态入口，不是协议正文的副本：协议与范例实现都用 git submodule 挂载在 vendor/ 下并固定到具体 revision，本仓库只负责索引、说明、校验与治理。

dsh-ecosystem-spec/
├── README.md / CONTRIBUTING.md / SECURITY.md / LICENSE
├── docs/ 说明文档：总览、目录规范、范例说明 ├── governance/ 治理：权威归属、状态词、挂载纪律 ├── decisions/ 决策记录（ADR） ├── registry/ 机器可读索引：协议 / 范例 / Profile ├── profiles/ 产品准入 Profile（只约束自己声明的生态范围） ├── vendor/ 挂载区（git submodule） │ ├── meta-protocols/ dsh-std、dsh-distribution │ ├── sub-protocols/ 子协议（dsh-skin：DSH UI 皮肤加载公约） │ └── examples/ 范例实现（dsh-dpx） ├── scripts/ 本仓库自己的校验脚本 └── .github/ 本仓库自己的 CI

| 类别 | 条目 | 状态（照录上游） | 挂载 | 说明 |
| 元协议 | dsh-std | Draft | vendor/meta-protocols/dsh-std | 插件 / 宿主 / 运行时互操作 |
| 元协议 | dsh-distribution | Draft | vendor/meta-protocols/dsh-distribution | DSH 环境的身份与可迁移性 |
| 子协议 | dsh-skin | Experimental | vendor/sub-protocols/dsh-skin | 皮肤插件与加载器之间的加载启停接缝 |
| 范例实现 | dsh-dpx | Experimental | vendor/examples/dsh-dpx | dsh-distribution 的标准管理范例 |

- 想知道以后新协议 / 新范例该放哪：docs/directory-guide.md
- 想看机器可读索引：registry/README.md
- 想理解四层模型：docs/overview.md

每次提交，本仓库自己的 CI 都会校验「目录规范 ↔ 索引 ↔ 挂载 ↔ 文档链接」四者一致（.github/workflows/ci.yml）。

目录

- 仓库结构：生态入口
- dsh-std：deepseek-harnessc插件规范
- dsh-std是什么？
- 采取dsh-std有什么好处？
- dsh-distribution：deepseek harness整合包规范
- dsh-dpx：dsh-distribution 的标准管理范例
- 想让AI更好的开发dsh？
- 想参与生态标准的讨论与建设？

dsh-std

dsh-std是什么？

dsh-std 是一套通用的互操作协议。它希望 DSH 的插件、后台运行时以及各种界面能够解耦并顺畅协作。

@dsh-std/core 是一个「元协定」。命令（Command）、工具（Tool）、模型（Model）、界面交互（Presentation）这些具体的业务协议，都在元协定底座上进行发现和协商，各自独立演进。不同的宿主和程序只需要挑选自己需要的部分来实现。

@dsh-std/core 不管任何具体的业务字段，它是「关于协定的协定」。它只定义最底层的规则：协议叫什么名字（apiVersion + kind 坐标）、参与方怎么说「我需要什么」和「我支持什么」、怎么运行纯函数协商并产出一份结构化的兼容报告。

此外，dsh-std要求采用 Adapter 解耦。官方 DSH 内核与生态插件各自的核心诉求是不同的。官方 DSH 希望高频迭代模型调度、上下文管理和内部架构，内核不应该被外部各式各样的 UI 协议和前端标准绑死手脚；而社区插件作者希望 DSH上游接口稳定，不希望上游每次升级自己就得通宵修兼容。

Adapter 在这里充当了「减震器」。它把上游内核与通用协议隔开。官方内核可以自由重构、快速演进，所有可能引发破坏的变化只要在 @dsh-std/adapter-dsh 这一个适配层里消化掉，生态里成千上万的插件就完全不需要改动一行代码。任何独立的 TUI、Web 前端、远程云端 Runner 也能通过各自的 Adapter 平等接入这套标准；不同项目的 Adapter 可以自动进行兼容。

采取dsh-std有什么好处？

- 传统单体框架把所有功能（命令、存储、事件）都硬编码在主 SDK 里，以后只要想加一个新功能，整个主框架就必须发新版甚至搞出破坏性升级。而在元协定体系下，「协议本身」也变成了可拔插的插件——这和dsh本体的理念不谋而合，无论是官方标准、社区扩展还是个人私有协议，都能平等地作为独立的协议接入，生态自己能无限演进
- Adapter减小了上游更新以及不同版本插件之间的兼容性，减小了开发压力
- 插件作者只要面向标准协议写代码。同一个插件写好后，可以在 TUI 终端跑，也可以在 Web 网页里跑，还能丢在 Remote SSH 远程服务或无界面的后台容器里跑，不需要针对不同平台合使用场景重写几份
- 依靠静态清单dsh-plugin.json，插件市场、宿主和 CI 在不运行任何插件代码的前提下，能准汇报你的环境能不能跑这个插件、需要什么权限。彻底告别「装上跑起来报错崩溃了才发现不兼容」。
- 鼓励各种激进的 Agent 架构探索。无界面集群、常驻守护 Agent、远程协作系统，各种新形态都能在元协议上直接生长。

dsh-distribution

dsh-distribution 是什么？

dsh-distribution 是一套用于描述和管理 DSH 运行环境 / 发行物 的最小元协议，他关注一个可运行的 DSH 环境如何被外部世界识别、发现和管理。当一个项目希望把自己声明为一个可发现、可验证、可管理、可迁移的 DSH 环境时，dsh-distribution提供了一套可以使用的共同语言。

或者有个更简单易懂的理解：大家安装python的时候都知道可以勾选「add to path」，而本协议提供了dsh整合包「add to path」的格式，以及一些扩展格式，方便跨整合包/跨dsh版本运行的包管理和路径管理

对于目前dsh官方的基于profile + bundle 组合、seam 可替换、agent-loop 可替换架构，开发者可以像拼积木一样组合出完全不同的产品：

- dsh + TUI：打造类似 Claude Code 的极客终端编码工具；
- dsh + WebUI：封装成类似 Codex App 的现代网页/桌面应用，并且 WebUI 与 TUI 可以无缝互通、共享同一套运行时状态
- dsh + 消息接入插件：蜕变成为一个无界面的、事件驱动的后台常驻 QQ 机器人（参考Nanobot）
- dsh + 周期心跳插件：演化成 Neuro 这样的 AI 伴侣，24 小时自主运行，有自己的心跳和思考周期
- dsh + 未来未知架构：衍生出某种全新 AGI 交互形态，我们今天还无法定义。

这些产品形态，很多需要独立封装、独立运行。而 dsh-distribution 提出了一个问题：当一个项目成为「完整、可运行的 dsh 环境」之后，它应该如何向外部世界描述自己，才能让多个 dsh 发行版本共存，让插件、用户文件与配置迁移成为可能。

采取 dsh-distribution 有什么好处？

- 不对具体产品的封装形式做约束，开发者可以发行任意形态的 dsh 产品
- 提供多 dsh 版本与插件环境隔离的可能性，让不同的 dsh 产品可以在同一台电脑上共存，开发者也可以隔离多种 dsh 版本拆件环境，便于做兼容性测试

dsh-dpx：dsh-distribution 的标准管理范例

dsh-dpx 是 dsh-distribution 的真实使用者，本仓库把它收录为标准管理范例：它按协议创建、注册、发现并启动多个相互隔离的 DSH 环境，把「一个 DSH 环境如何向外部世界说明自己」完整走通了一遍。

它示范了协议的三块能力：环境身份（每个环境根一份 dsh-distribution.json）、 安装实例身份（每次安装一个独立 urn:uuid:，test 与 stable 绝不混同）、 发现（自己的 registry，加上 Windows 上无执行权限的 discovery pointer）。
它同时示范了不越界：不写别的管理器的注册位置、不扫盘猜测、不把目录隔离说成安全沙箱，也不要求别人照抄它的目录布局。

范例不是标准，也不是唯一的管理器。完整说明（含真实用法、复算验证与照抄清单）见 docs/examples/dsh-dpx.md。

想让 AI 更好的开发 dsh？

想参与生态标准的讨论与建设？

- 提交前先读 CONTRIBUTING.md（分区纪律、PR 要件、禁止顺手规范化）；
- 东西该放哪、新协议怎么挂：docs/directory-guide.md；
- 治理与权威归属：governance/README.md；
- 具体协议的语义讨论请到对应上游仓库（见 registry/protocols.json 的 upstream）。