Yan-Zero/dsh-std

DSH Standard

简单来说，DSH Standard 是一套通用的互操作协议。它的目的很简单：让 DSH 的插件、后台运行时（Runtime）以及各种界面（TUI 终端、Web 网页、桌面端、无界面后台）能够解耦并顺畅协作。

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

规范仓库提供了类型、校验器、纯函数协商器等参考实现。外部实现完全不强制依赖这些 npm 包，也不强制要求运行在 DeepSeek Harness 里。

什么是“元协定”（协定的协定）？

大部分大家熟悉的协议都是管具体业务的：
- 比如 Command 协议管命令怎么注册和执行；
- Model 协议管模型提供方怎么接入；
- Presentation 协议管界面怎么弹窗和审批。

而 @dsh-std/core 不管任何具体的业务字段（它连什么是命令、什么是模型都不知道）。它是“关于协定的协定”：

- 它只定义最底层的规则：协议叫什么名字（apiVersion + kind 坐标）、参与方怎么说“我需要什么”和“我支持什么”、怎么运行纯函数协商并产出一份结构化的兼容报告。
- 打个比方：它就像 USB 接口规范，核心只管插槽尺寸和握手协议。至于你插进来的是键盘、鼠标、U 盘还是摄像头，核心根本不用管。

这为什么强大？
传统单体框架把所有功能（命令、存储、事件）都硬编码在主 SDK 里，以后只要想加一个新功能，整个主框架就必须发新版甚至搞出破坏性升级。而在元协定体系下，“协议本身”也变成了可拔插的插件：无论是官方标准、社区扩展还是个人私有协议，都能平等地作为独立的协议接入。核心永远不用动，生态自己就能无限演进。

为什么采用 Adapter 解耦？

官方 DSH 内核与生态插件各自的核心诉求是不同的：

- 官方 DSH 负责敏捷创新：它的核心任务是做最快、最强的 Agent 执行底座，需要高频迭代模型调度、上下文管理和内部架构。内核不应该被外部各式各样的 UI 协议和前端标准绑死手脚。
- 生态插件需要稳定契约：插件作者只想专心写业务逻辑，不希望上游每次升级自己就得通宵修兼容。

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

除了“不炸依赖”，这套架构还有什么好东西？

把上游变化单点吸收只是基本功，这套体系在实际开发中还带来了许多非常实在的好处：

- 真正的一次编写，到处运行（跨端免重写）：插件作者只要面向标准协议写代码。同一个插件写好后，既能无缝扔给 TUI 终端跑，也能直接在 Web 网页里跑，还能丢在 Remote SSH 远程服务或无界面的后台容器里跑，不需要针对不同平台重写几份。
- 按需加载与干净的生命周期（不漏内存）：一个插件包里可以同时写好前端界面和后台逻辑。宿主按需只加载自己要的部分（比如无头服务器跑的时候根本不会去加载前端代码）；插件一旦停用或卸载，所有占用的定时器、事件监听和资源都会被作用域自动一锅端清理掉，绝不残留副作用。
- 装之前就知道能不能跑（告别开盲盒）：依靠静态清单（dsh-plugin.json），插件市场、宿主和 CI 在不运行任何插件代码的前提下，一秒钟就能准确算出来你的环境能不能跑这个插件、需要什么权限。彻底告别“装上跑起来报错崩溃了才发现不兼容”。
- 闭着眼睛做单元测试（极速轻量）：协议的核心全是纯数据结构和纯函数协商器。测试插件或宿主时，完全不需要把庞大的 DSH 启动起来，也不需要开浏览器，几十毫秒在轻量 Node.js / CI 里就能测完全部功能。
- 生态去中心化野蛮生长：想搞个全新的 Agent 能力（比如新型多模态流、特种工具协议）？自己定义一份协议就能跑起来，不需要苦等官方或任何人审批发版。

愿景：分层、可选、不强制

元协议（core）       只约定"如何声明与协商协议"，不预设领域概念，不定义固定角色
│
独立领域协议         connection / command / tool / session / presentation / agent ...
│                 彼此独立版本化，可独立实现、独立替换，可被未来新协议取代
│
Profile            面向具体产品形态的准入与互操作规范，由生态项目承载
（如 dsh-ecosystem-spec 提供 TUI Profile）

- 采用全凭自愿：任何项目都没有必须采用本标准的义务；但一旦声明兼容某个协议版本，就必须遵守对应的规范测试。
- 鼓励各种激进的 Agent 架构探索：无界面集群、常驻守护 Agent、远程协作系统，各种新形态都能在元协议上直接生长。
- 想要“传统 Host + 插件清单”开发体验的项目，参考对应 Profile 即可；不想要这些概念的实现完全不受限制。

从这里开始

- 阅读架构说明，了解元协议、独立协议与产品实现的边界。
- 各组件的拟议设计集中在设计提案索引。
- @dsh-std/connection 的设计提案见 Endpoint Connection。
- 通过包索引挑选需要的协议包。
- 针对 DSH 的适配代码位于 @dsh-std/adapter-dsh。

状态

现有代码与提案均处于早期草案阶段。

每个包在自身的 CHANGELOG.md 中记录变化。修改公开契约时，必须同步更新对应的 changelog。

开发

需要 Node.js ^22.19 || >=24 与 pnpm。

pnpm install
pnpm check

发布

发布版本直接维护在各个 packages/*/package.json 中，release workflow 不自动改写版本号。代码 push 到 main 后，workflow 将这些版本与 push 前的 commit 比较，对每个确实升高的版本依次打包、通过 OIDC 发布、创建 tag 和 GitHub Release。预发布版本以其预发布标识作为 npm dist-tag（rc、alpha 或 beta），稳定版本使用 latest。

许可证

MIT