@dsh-std/core 元协议设计提案

August 28, 2026 · View on GitHub

文档类型：设计提案
状态：方向已确认，接口草案
日期：2026-08-16

Summary

@dsh-std/core 定义 DSH Standard 的元协议。实现使用它声明自己理解、需要和实现哪些协议，并在共同支持的协议版本之间完成协商。

各领域协议独立发布、独立版本化，也可以被独立实现。实现 connection 不要求同时实现 command、tool 或 presentation；一个产品也不必使用 @dsh-std 发布的 TypeScript 代码，只要其行为符合所实现协议的文档与互操作要求。

Core 不规定领域对象、调用方法、网络承载、插件生命周期或界面模型。这些内容属于可拔插的协议及其实现。

Motivation

DSH Standard 包含多份用途不同的规范。Host、TUI、Web、GUI、插件运行时和远端连接程序通常只需要其中一部分，而且它们可能由不同项目、不同语言实现。

仅比较软件包名称无法回答以下问题：

两个实现是否理解同一份协议；
双方支持的版本能否互操作；
某项协议是必需还是可选；
协议的可选部分如何选择；
协商失败来自未知协议、版本不兼容，还是协议自身的约束。

Core 提供共同的声明外壳和协商入口。领域协议负责解释自身声明，core 负责找到对应的协议解释器并汇总结果。

Guide-level explanation

协议与实现

一份协议由 apiVersion 和 kind 标识。例如：

{
  apiVersion: 'connection.dsh/v1alpha1',
  kind: 'ConnectionService',
}

协议包可以提供类型、schema、校验器、协商器、codec、状态机或一致性测试。这些代码是规范的可复用部件，不是产品实现。

例如，@dsh-std/connection 可以定义应用消费的 ConnectionService，并提供 offer 校验、协商算法、codec 和通用状态机。Connection Host 实现监听、认证、承载、调用分派和产品集成；TUI、Web、GUI 与业务插件通过 service facade 使用连接，不分别实现这些基础设施。其他语言的 Host 可以不使用 npm 包而实现同一协议。

协议声明

参与协商的一方提交 ProtocolDeclaration。声明包含参与者身份，以及它对各协议的需求和支持：

interface ProtocolDeclaration {
  readonly participant: ParticipantIdentity
  readonly requires?: readonly ProtocolRequirement[]
  readonly supports?: readonly ProtocolSupport[]
}

requires 表示该参与者希望协商的协议。Requirement 可以是必需或可选。

supports 表示该参与者在当前协商范围内实际可用的协议实现。安装了某个包、在静态清单中提到某项协议，或者能够解析其数据，都不能代替运行中的 support 声明。

Requirement 和 support 可以携带由所属协议定义的 spec。Core 保留该数据，但不解释其字段：

interface ProtocolRequirement extends ApiReference {
  readonly optional?: boolean
  readonly spec?: unknown
}

interface ProtocolSupport extends ApiReference {
  readonly spec?: unknown
}

协议可以用 spec 表达角色、功能子集、限制或协商参数。Core 不预设 client/server、provider/consumer、execution plane 或 locality 等模型。

协议解释器

理解一份协议的 evaluator 注册该协议的 ProtocolDefinition。Definition 至少负责：

识别自己支持的 API version；
校验 requirement 与 support 中的协议专属 spec；
判断一组声明能否共同工作；
生成该协议的协商结果和诊断。

协议可以只提供声明 schema，也可以附带确定性的参考协商器。connection 这类约束较多的协议适合提供参考实现；只有简单版本选择的协议则可以只提供校验和兼容性规则。

协商

调用方先确定本次参与协商的声明集合，再交给 core。Core 不自行发现进程、插件或远端设备，也不决定哪些参与者应当被放进同一协商范围。

协商过程为：

校验 core 外壳和参与者身份；
按协议族归集 requirements 与 supports；
为每个协议族选择已注册且能处理相应版本的 definition；
由 definition 校验协议专属数据并产生协议结果；
汇总必需协议错误、可选协议缺失和各协议的 agreement。

Core 不把“找到同名 support”直接等同于协商成功。多实现选择、角色关系、功能交集和参数降级均由相应协议决定。

按需实现

每个参与者只声明本次实际理解和支持的协议。例如：

一个无界面的后台进程可以提供 ConnectionService 和 AgentControl；
TUI 可以要求 Connection Service，并实现若干 presentation 协议；
Web 可以要求相同的 Connection Service，但提供另一组 presentation 协议；
只提供工具目录的组件可以实现 tool，而不实现 command。

协商不会把未声明的协议视为缺陷。只有另一参与者将其列为必需 requirement 时，缺失才会使该次协商失败。

Reference-level explanation

Protocol identity

interface ApiReference {
  readonly apiVersion: string
  readonly kind: string
}

apiVersion 由协议 group 和版本组成，kind 标识该 group 中的协议。二者共同确定一份版本化协议。

kind 必须（MUST）匹配 ^[A-Z][A-Za-z0-9]*$：它以 ASCII 大写字母开头，后续只能包含 ASCII 字母或数字。空字符串、Unicode 字母、连字号和下划线均不是合法的 Core 协议 kind。Evaluator 必须（MUST）在注册 definition、解析声明或查询坐标时拒绝不符合该语法的引用。

Core 可以解析版本标识并建立候选集合，但不假定同一 major 下的 alpha、beta 和 stable 必然互通。精确版本之外的兼容关系由该协议的 definition 声明。没有对应 definition 时，evaluator 不能声称已经完成该协议的协商。

Core 不根据 group 名称判断协议是否属于某个标准集合。命名空间归属与保留规则、协议发布状态和目录收录规则由相应治理或分发机制规定，不属于协商算法。只要坐标、definition 和声明满足本协议，evaluator 对它们采用相同的校验与协商过程。

目录收录不是协议可用性的必要条件。实现可以从静态目录、安装包、产品内建模块或显式配置取得 definition；目录也不能仅凭收录条目产生 live support。不同来源提供同一坐标但 definition 内容不一致时，evaluator 必须报告定义冲突，不能以发现顺序选择其一。

Participant identity

参与者是在一次组合或连接中提交协议声明的实体。它可以对应插件实例、profile、进程、客户端、服务或其他实现单位。

Core 只要求身份在当前协商范围内唯一。身份如何认证、是否跨重启稳定、是否可向对端公开，由建立该协商范围的协议或产品决定。

Manifest facet 不是 participant。Facet 是发行物中的静态声明和激活单位；participant 是 coordinator 为 activation instance 创建、实际参加某次协商的运行实体。组件模型第一版令一个 activation instance 对应一个本地 participant；同一 facet 的多次激活仍会产生不同 participants。产品也可以产生没有 manifest facet 的内建 participant。

Core 不把 component id、facet name 或进程位置规定为 ParticipantIdentity 的固定字段。需要归属信息的实现通过 lifecycle/provenance 保存本地关联；向连接对端公开哪些关联由 connection view 和 policy 决定。

Protocol definition

ProtocolDefinition 是 evaluator 对一份领域协议的本地解释。概念接口如下：

interface ProtocolValidationContext extends ApiReference {}

interface ProtocolDefinition<RequirementSpec = unknown, SupportSpec = unknown, Agreement = unknown>
  extends ApiReference {
  readonly accepts?: readonly string[]
  validateRequirement(spec: unknown, context: ProtocolValidationContext): RequirementSpec
  validateSupport(spec: unknown, context: ProtocolValidationContext): SupportSpec
  negotiate(input: ProtocolNegotiationInput<RequirementSpec, SupportSpec>): ProtocolNegotiationResult<Agreement>
}

具体 TypeScript API 可以为 schema-only 协议提供默认适配器，但不得改变以下语义：

协议专属字段由协议 definition 拥有；
accepts 只表示同一 definition 能识别哪些准确坐标，不推断这些版本兼容；
validator 接收原始 apiVersion + kind 上下文，并按该准确版本校验 spec；
协商结果可由其他符合规范的实现独立复算；
注册顺序不影响结果；
definition 不因被注册而产生一项 live implementation。

Evaluator 在解释一项协议专属 spec 前必须取得能够处理该坐标的 definition。Definition 的发现和装载先于依赖它的声明校验；装载 definition 所需的包格式、签名、信任和执行策略不属于 core。未知 required requirement 阻止该次协商；未知 optional requirement 作为未满足的可选项报告。未知 support 不得被当作已经理解或可以调用的实现。

Negotiation result

一次 core 协商产生机器可读报告。报告至少包含：

参与协商的声明及其 revision 或 digest；
负责处理该组声明的 definition 主坐标；
各协议 definition 产生的 agreement；
缺失的可选 requirement；
阻止协商的 issue 及其声明路径；
evaluator 的身份与版本。

Agreement 是协议拥有的数据。Core 不假定它一定是 RPC binding、资源选择或权限 grant。调用方也不能仅凭 agreement 绕过相应协议和产品实现的授权检查。

当一份 definition 识别多个 apiVersion 时，Core report 的协议坐标仍是 definition 主坐标。请求版本、support 版本和最终采用的 contract dialect 由协议自己的 agreement 按协议版本兼容与协商提案记录；Core 不提供通用的版本选择字段。