通用互操作协议 T-Auto/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 的功能和实现 它把产品内部服务映射到所采用的标准协议，是标准能力接入产品的一环。可复用的适配实现可以减少第三方插件重复适配产品 API 的工作；各项目可以自行设计 Adapter 或选用已有实现。

第三方插件面向其采用的协议契约开发，适配器的内部接口和包名不构成共同入口。@dsh-std/adapter-dsh 提供针对 DeepSeek Harness 的一组产品映射；TUI、Web 前端、远程 Runner 或其他集成方可以提供自己的适配实现。兼容范围取决于协议版本、实际能力和产品映射。

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

协议契约与产品实现分开后，这套体系还可以支持以下开发方式：

- 减少跨端重复适配：插件可以复用符合协议契约的业务逻辑，由各产品的适配实现连接到本地能力。
- 按需加载与干净的生命周期（不漏内存）：一个插件包里可以同时写好前端界面和后台逻辑。宿主按需只加载自己要的部分（比如无头服务器跑的时候根本不会去加载前端代码）；插件一旦停用或卸载，所有占用的定时器、事件监听和资源都会被作用域自动一锅端清理掉，绝不残留副作用。
- 装之前就知道能不能跑（告别开盲盒）：依靠静态清单（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 即可；不想要这些概念的实现完全不受限制。

从这里开始

- 阅读架构说明，了解元协议、独立协议与产品实现的边界。
- 阅读跨 Profile 应用指南，了解同一个插件包与可能挂载它的多个 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。

发布 job 通过 GitHub 仓库 ID 限定在本仓库运行，因此转移所有权不会使其失效，fork 也不会发布包。GitHub Release 通过 GH_REPO 指向运行 workflow 的当前仓库。

转移到 T-Auto/dsh-std 时，每个已发布 npm 包的 trusted publisher 都需要配置为 Owner T-Auto、Repository dsh-std、Workflow release.yml（不设置 Environment）。从转移后的仓库发布之前，需要在各包的 npm 设置中完成配置；GitHub 仓库转移不会更新 npm 配置。参见 npm trusted publishing。

许可证

MIT