1. 插件模型

1.1 一切皆插件

DSH 内嵌（vendored）Cordis（@deepseek-ai/cordis v4），用 @deepseek-ai/dsh-* 插件组装自己。 **服务（service）**是挂在上下文键（ctx.tools、ctx.llm、ctx.sessions、ctx.agents …）上的 命名能力。**seam（可替换能力）**是有三个角色的可插拔能力：

• Service Definition（服务定义）——拥有 ctx.<key> 及其词表类型（如 ShellExecutor）。
• Service Provider（服务提供者）——该定义的一个或多个实现（如 bash-local、bash-sandbox）。
• Consumer（消费者）——inject 该服务并调用它的插件（如 tool-bash）。

插件用 inject 声明它需要哪些服务；loader 在这些服务就绪后才运行 apply。 加载顺序由服务依赖表达，绝不由文件顺序决定。

1.2 时空可组合性

DSH 的运行时保证来自 Cordis 论文形式化的两个维度：

• 时间可组合性（可逆副作用）：卸载插件时，它对共享上下文所做的一切修改都被完整、安全地撤销。 每个注册都携带一个 disposer（清理器）；运行时累积它们，卸载时按 LIFO 顺序回放。
• 空间可组合性（响应式协作用）：插件声明自己的依赖，运行时随 provider 出现/消失/变化而响应式地 激活/反激活插件。依赖缺失的插件只是保持未激活——绝不会因缺服务而崩溃。

落到实践就是：你为每个原子副作用提供一个逆，复合拆除由运行时推导，你永远不用手写卸载路径。

1.3 术语表

English	中文	含义
plugin / component	插件 / 组件	导出 apply(ctx) 的模块（可带 name/inject/Config）
context	上下文 (ctx)	一切注册流经的一等实体
service	服务	ctx.<key> 上的命名能力
seam	可替换能力	Service Definition + Providers + Consumers
inject	依赖声明	apply 运行前插件需要的服务
effect	副作用	对共享环境的修改
revertible effect	可逆副作用	配有一个逆、由运行时跟踪的副作用
coeffect	协作用	插件对环境的依赖（effect 的对偶）
reactive coeffect	响应式协作用	每次上下文变化都重算依赖满足性
disposer	清理器	注册返回的逆，卸载时执行
fiber	纤程	插件的一次实例化，带自己的生命周期状态
bundle	bundle	携带配置层（cordis.patch.yml）的 npm 包
profile	profile	$DSH_HOME/profiles/<name> 下的一次可运行组合
dispatch mode	派发模式	emit / waterfall / parallel / serial

1.4 三种插件形态

出自 docs/cordis-tutorial/01-first-plugin.md：

import { Service, type Context } from '@deepseek-ai/cordis'

// ① 函数插件（最常用）：具名导出，无 default export。
export const name = 'hello'
export function apply(ctx: Context) {}

// ② 对象插件：带 apply 方法的对象。
export const objectPlugin = { name: 'object-plugin', apply(ctx: Context) {} }

// ③ 类插件：Service 子类（需要对外暴露自己的服务时）。
export class MyService extends Service {
  constructor(ctx: Context) { super(ctx, 'myService') }
}

服务包 default-export 服务类；函数插件具名导出 name/inject/Config/apply， 不能有 default export。

---

← Prev: 摘要 · Contents · Next: 三类插件形态 →