在 DeepSeek Harness 上做插件开发，绕不开两个词：作用域隔离与事件系统。前者解决的是「资源怎么分」，后者解决的是「消息怎么通」。如果你的插件组里有两套 Bash 执行器、两套日志配置、两套权限策略，它们必须互不可见又各自独立实例化；而当你需要让十几个互不相识的插件在某个扩展点上协同工作时，又不能让它们硬编码互相调用。Cordis 给出的答案是：用 isolate 做服务隔离，用 scope 管可见性，用 emit / bail / serial / waterfall 五种分发模式把事件通信的语义切分得清清楚楚。这篇文章从一个可跑的最小实验目录 scratch-plugin/cordis.yml 出发，把「同一份 shell 服务怎么裂成两个实例」和「事件怎么从监听端走到触发端」这两条主线一次讲透，让你在真实项目里既能把插件组隔离开，又能在需要时把它们串起来。

isolate 字段怎么让同一份 shell 服务裂成两个实例

先看一个很多人第一次用 Cordis 时会踩的直觉陷阱：以为插件组只是一个「命名空间」，用来给插件起个好看的前缀。实际上，插件组真正的力量在于它可以成为服务实例的边界。默认情况下，一个服务在 Cordis 容器里是单例的——谁 require 到它，拿到的都是同一份对象。这在多数场景下没问题，但一旦涉及有状态、有配置差异、有资源占用的服务（比如一个带超时设置的 Bash 执行器），共享单例就会变成灾难：group-a 想把 Bash 超时设成 5 秒，group-b 想要 60 秒，如果它们共享同一个实例，后设置的配置会覆盖先设置的，行为变得不可预测。

isolate 字段就是用来打破单例语义的。它的写法是键值对形式，键是服务名，值是布尔值，例如 isolate: { shell: true }。当你在一个 group 上声明 isolate: { shell: true } 时，你实际上是在告诉 Cordis：在这个组的边界内，shell 这个服务不使用全局单例，而是为本组单独实例化一份。组内所有插件在注入 shell 服务时，拿到的都是本组专属的那一份；组外插件看到的仍然是它们自己那一份，或者全局那一份。这意味着两个组可以放心地对各自的 shell 实例做不同配置，互不干扰。

理解这一点的关键在于把「服务」和「服务实例」分开看。服务是契约（名称、接口、语义），实例是运行时对象（配置、状态、资源句柄）。在没有 isolate 的情况下，契约与实例是一一对应的全局映射；加了 isolate 之后，契约变成一对多，实例的粒度下沉到插件组。你可以在脑子里把它类比成编程语言里的静态变量与实例变量：不加 isolate 就像全局静态单例，加了 isolate 就像每个对象各持一份成员字段。这个心智模型对后面理解 scope 与 isolate 的分工非常关键。

还有一个容易被忽略的细节：isolate 的隔离是有方向性的。它不会让被隔离的服务对所有组都变成私有——它只是让声明了 isolate 的这个组持有独立实例。如果没有别的组声明隔离，它们仍然共享默认实例。所以你在设计多组架构时，要问自己的问题不是「要不要隔离」，而是「哪些组需要独立实例、哪些组可以共享」。通常的做法是：凡是配置有差异、状态有写入、生命周期需要独立管理的服务，都倾向隔离；纯函数式的工具服务、只读的元数据服务，可以继续共享以节省资源。这条经验法则能帮你避免两个极端：要么什么都隔离导致实例膨胀、内存浪费；要么什么都不隔离导致配置互相污染、调试到怀疑人生。

@deepseek-ai/cordis-plugin-group 与 group: true：插件分组的声明式写法

理解了 isolate 的语义，接下来要解决的是「隔离挂在谁身上」。答案是 @deepseek-ai/cordis-plugin-group 这个插件，它把隔离能力包装成了一种声明式配置。注意，分组是隔离生效的前提条件——你不能凭空给一个普通插件加 isolate 就指望它裂成多实例，isolate 是 group 插件的属性，必须先有组，组才能声明隔离。

一个 group 条目在 cordis.yml 里长这样，涉及三个关键字段：

  • id：组的唯一标识符，比如 group-a、group-b。它不仅仅是个名字，还是日志、诊断、配置引用时的定位锚点。多个组的 id 必须唯一，否则加载阶段就会报冲突。
  • name：这里固定写 '@deepseek-ai/cordis-plugin-group'，表示这个条目由 group 插件来加载。换句话说，name 决定了「用哪种加载器来实例化这个条目」。
  • group：布尔值，必须为 true。这个字段是显式开关，告诉 Harness 这个条目不是普通插件，而是一个「组容器」。很多初学者忘记写这一行，结果 config 里的子插件被当成平铺条目处理，隔离自然不生效。

这三点里最容易被低估的是 group: true 的显式性。为什么不做成自动推断？因为 Cordis 的配置风格偏向显式声明，宁可多写一行也不做魔法推断。显式的好处是：读配置文件的人一眼就能区分「这是一个普通插件」还是「这是一个组」，而且工具链在做静态分析、依赖图渲染时也能精确识别边界。把 group: true 当成一个括号记号，它划定了隔离的作用范围，括号之内是组的内部世界，括号之外是外部世界。

那么 isolate 写在哪里？写在组条目自己的层级上，和 id、name、group 平级，而不是塞进某个子插件的配置里。这是一个常见的层级错误：有人会下意识地把 isolate 写到子插件的 config 里，因为他觉得「隔离是针对这个子插件的服务」。但语义上正相反——隔离是组的属性，是组替它的成员统一申请的。组内可能有多个插件，它们都可能消费 shell 服务；组声明一次 isolate，整个组内所有对 shell 的消费都指向本组实例。所以正确的层级观念是：isolate 属于「容器」，不属于「成员」。

另外要提醒的是，name 字段的写法必须与包名完全一致，包括 scope 前缀。如果你本地做了 monorepo 或镜像，包名可能不同，此时要确保 group 的 name 与子插件的 name 都能被解析器找到。解析失败时的表现往往是加载阶段直接抛错，而不是静默降级，所以这一类问题一般很快能发现。

timeoutMs 从 5000 到 60000：用配置差异验证隔离是否真的生效

讲完机制就要讲验证。隔离这种东西最怕「看起来配了但实际没隔离」，而验证隔离最朴素也最可靠的手段，就是制造一个可观测的配置差异，然后观察行为是否按各自的配置走。素材里的例子非常典型：group-a 里的 dsh-bash-local 配置 timeoutMs: 5000，group-b 里同名插件配置 timeoutMs: 60000。同样的服务、同样的插件名，只有 timeout 数值不同。

这里的关键是一个「同名不同配」的构造。如果隔离生效，group-a 里发起的 Bash 调用会在 5 秒左右超时，group-b 里发起的调用可以跑到 60 秒；两个组的超时行为彼此独立，改变其中一个不会影响另一个。如果隔离没有生效（比如你漏写了 isolate，或者把 isolate 写错了层级），两个组会共享同一个 shell 实例，那么后加载的配置会覆盖先加载的，两个组的表现会收敛到同一个数值上。这个收敛现象就是隔离失效的指纹。

为了把这个验证做成可复现的实验，建议按下面的顺序操作：

  1. 准备一个耗时明确超过 5 秒、但远小于 60 秒的命令，例如一个睡眠 10 秒的脚本。这个时长选择是有讲究的：大于 5 秒，才能让 group-a 触发超时；小于 60 秒，才能让 group-b 顺利完成。10 秒正好落在两个阈值的中间，区分度最高。
  2. 在 group-a 的插件里发起这个命令，观察结果是超时失败。记录下实际耗时，应该落在 5 秒附近而不是 10 秒。
  3. 在 group-b 的插件里发起同一个命令，观察结果是成功完成，实际耗时约 10 秒。
  4. 做对照实验：把 group-b 的 timeoutMs 改成 3000（小于 5 秒的另一种差异），重启后再次观察，如果 group-b 开始超时而 group-a 不受影响，就进一步坐实了隔离。
  5. 反证实验：临时删掉某一组的 isolate 声明，重启，观察两个组的行为是否开始互相影响。这一步能帮你建立对「隔离到底改变了什么」的肌肉记忆。

这一步里有个工程细节值得强调：验证时要保证两个组的插件确实是各自组内加载的。如果你把两个插件都写在同一个组里，那么不管有没有 isolate，它们都会共享同一份实例，实验结论会误导你。所以目录结构和配置层级必须和实验目标对齐，这也是下一小节要展开的内容。

cordis.yml 里 config 数组的嵌套结构：组内插件如何被逐层实例化

Cordis 配置最需要小心对待的就是层级，因为它用的是嵌套的 config 数组，而不是平铺的键值表。一个组的条目里，config 是一个数组，数组的每一个元素代表组内的一个成员；成员本身又可以有 name 和 config，它自己的 config 再描述这个成员自己的参数。这就形成了一个递归的树状结构：组 → 成员 → 成员参数。

先把语义对齐一下，避免混淆：

层级字段语义常见错误
组条目id / name / group声明这是一个组容器，唯一标识与加载器漏写 group: true，组退化成普通插件
组条目isolate声明本组要独立实例化哪些服务误写进成员 config，隔离不生效
组条目config（数组）本组要加载的成员清单，按序实例化写成对象而非数组，解析失败
成员条目name成员插件的包名或相对路径路径写错，加载阶段报错
成员条目config该成员的参数（如 timeoutMs）把服务级配置写到这一层导致语义错位

加载顺序是「深度优先、按数组顺序」。当一个组被加载时，Cordis 会按 config 数组里元素的先后顺序依次实例化成员：先加载 @deepseek-ai/dsh-bash-local 并应用它的 timeoutMs，再加载 ./src/plugin-a.ts。这个顺序很重要，因为后面的成员通常会注入前面成员提供的服务。如果顺序反了，后加载的插件在初始化时可能拿不到 shell 服务，出现「注入为空」或「服务未注册」的报错。所以有一条实践原则：把提供服务的插件写在前面，把消费服务的插件写在后面。这跟很多框架的思路一致，但 Cordis 把它做成了纯配置约定，没有额外语法糖，因此更需要你自觉遵守。

再强调一次 isolate 与 config 层的分离，这是最容易踩的坑。看这个结构：组条目的 isolate 是容器级声明，它决定「这个组内的 shell 是不是独立实例」；而成员条目里的 config 的 timeoutMs 是成员级参数，它决定「这个 shell 实例的具体行为」。两者配合才完整：isolate 负责把实例裂开，成员 config 负责给裂开后的实例填参数。如果你只写了 isolate 却没在成员里写不同参数，那么两个实例虽然相互独立，但配置一模一样，实验上观察不到差异，会让人误以为隔离没生效；如果你只在成员里写了不同参数却没写 isolate，那么两个组共享实例，后写的参数覆盖先写的，实验上同样观察不到差异。所以验证隔离必须同时具备正确的 isolate 声明和差异化的成员参数，缺一不可。

那么嵌套层级写错了会怎样？通常有两种表现：一是加载阶段直接抛解析错误，比如把 config 数组写成了对象（用了花括号而不是方括号），解析器无法把它当成成员序列处理；二是加载能过但语义错位，比如把 timeoutMs 放到了组条目自己的 config 里，结果它既不是组容器参数也不是某个成员的参数，被静默忽略，你看到的现象就是「我明明配了 60 秒但没有效果」。第二种更隐蔽，因为不报错。建议养成一个习惯：配完后检查每个数值落在哪一层，问自己「这个数值是给谁的」。如果答案是「给某个具体成员的」，它就该在成员的 config 里；如果答案是「给这个组统一的」，它才在组条目层。

scratch-plugin/cordis.yml：一个最小可跑的服务隔离实验目录

理论说再多，也不如一个能跑起来的目录。素材给出的路径是 scratch-plugin/cordis.yml，这个命名本身就有讲究：scratch 暗示「草稿、可抛弃」，用它来做隔离实验意味着这只是一个验证性质的小工程，而不是生产目录。把实验和生产分开是一件好事，因为它允许你大胆地删配置、改参数、做反证，而不必担心污染正式环境。

一个最小可跑的隔离实验目录建议这样组织：

scratch-plugin/
├── cordis.yml          # 主配置，定义 group-a 与 group-b
└── src/
    ├── plugin-a.ts     # group-a 的成员插件，消费 shell
    └── plugin-b.ts     # group-b 的成员插件，消费 shell

对应地，cordis.yml 的内容就是我们在前面反复拆解的两组配置：group-a 声明 isolate: { shell: true }，其成员包含 @deepseek-ai/dsh-bash-local（timeoutMs: 5000）和 ./src/plugin-a.ts；group-b 同样声明 isolate: { shell: true }，成员包含同名插件但 timeoutMs: 60000，以及 ./src/plugin-b.ts。把这份配置完整贴出来是这样的：

# 文件路径：scratch-plugin/cordis.yml
# 定义两个插件组 group-a 与 group-b，各自隔离一份 shell 服务
- id: group-a
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true   # 让本组内的 shell 服务独立实例化
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 5000
    - name: './src/plugin-a.ts'
- id: group-b
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 60000
    - name: './src/plugin-b.ts'

关于相对路径，有一个容易忽略的细节：./src/plugin-a.ts 里的 ./ 是相对于配置文件的解析基准（通常是项目根或配置所在目录），不同工具链的解析基准可能略有差异。稳妥的做法是先用最小配置只加载一个插件，确认路径能被解析，再补第二个组。如果路径解析出问题，报错通常是「找不到模块」之类，比较直白。另外一个实用技巧：实验初期可以只写 group-a、不写 group-b，先确保单组内的 isolate 和 timeoutMs 生效，再加入第二个组观察隔离效果。这样能把「配置层级错误」和「隔离未生效」两类问题分开定位，不要一上来就两个组全开，一旦出问题很难判断是哪一层错了。

跑起来之后，你还可以在插件里打印一些诊断信息，比如在 plugin-a 和 plugin-b 初始化时打印当前 shell 实例的某个标识或超时值。这里要注意素材里没有给出具体的实例 ID 接口，所以不要假设存在某个固定的实例标识字段；更稳妥的验证方式仍然是上小节讲的行为验证（用 10 秒命令去撞击 5 秒 / 60 秒两个阈值），而不是去读某个内部 ID。行为验证不依赖内部实现，长期来看更可靠。

作用域（scope）与 isolate 的分工：谁决定可见性，谁决定实例数

这是整篇文章最需要掰清楚的一对概念。很多开发者在排查插件问题时会把 scope 和 isolate 混为一谈，结果方向全错。它们的职责正交：scope 管可见性，isolate 管实例数。

先讲 scope。scope 回答的是「这个服务对谁可见」。它是一道可见性屏障：一个服务在某个 scope 内注册，就在该 scope 内可以被注入；scope 外的插件去看它，就像看一个不存在的东西。scope 可以有层级，形成树状结构，子 scope 通常能访问父 scope 的服务，但反过来不行。scope 的价值在于权限与封装：你希望某个工具只对某个子系统开放，就把它注册在对应 scope 里；你希望某个全局能力对所有插件开放，就注册在根 scope 上。

再讲 isolate。isolate 回答的是「这个服务有几个实例」。它不改变可见性，改变的是实例化粒度。一个服务可能对所有组都可见（可见性没问题），但每个组各拿一份独立实例（隔离生效）。反过来，一个服务也可能只有一个全局实例（没隔离），但通过 scope 只对部分插件可见。两种机制可以自由组合，形成四种情况：

配置组合可见性实例数典型用途
无 isolate + 宽 scope全局可见单例无状态工具、只读元数据
无 isolate + 窄 scope仅特定 scope 可见单例子系统专属但内部共享的能力
isolate + 宽 scope各组均可见每组一份有配置差异的有状态服务（如 shell）
isolate + 窄 scope仅特定 scope 可见该 scope 内一份既有权限约束又需独立配置的敏感服务

理解这张表的关键在于：可见性和实例数是两个独立的维度，不要用一个机制去解决另一个机制的问题。如果你希望某个服务不被别的组看到，光加 isolate 是没用的——isolate 只负责裂实例，不负责挡视线，别的组仍然能看到并拿到它们自己那份实例。如果你希望某个服务在每个组里有不同配置，光调 scope 也没用——scope 只负责挡视线，不管实例裂不裂。所以排查问题时先问自己：我想要的是「看不到」还是「各一份」？前者用 scope，后者用 isolate，两个都要就都配上。

还有一个常见误解是「isolate 之后实例之间不能通信」。并非如此。隔离的是实例，不是通信能力。两个组的插件仍然可以通过事件系统（下一小节的主题）互相通信，只是它们拿到的是各自的服务实例而已。隔离解决的是资源归属，不解决耦合；解耦交给事件。把这两件事分清，你的架构思路会清爽很多。

ctx.on 与 ctx.emit：事件系统的两端与回调注册时机

说完了隔离，切换到通信。Cordis 的事件系统只有两端：监听端 ctx.on 和 触发端 ctx.emit。这两端构成了 Cordis 插件之间松耦合通信的核心机制，Harness 大量使用事件来实现可扩展的扩展点——也就是说，框架里很多「你可以插入自己逻辑」的位置，本质都是事件。

监听端注册回调，触发端广播给所有监听器，基本形态如下：

// 监听事件：注册一个回调
ctx.on('event-name', (payload) => {
  // 处理事件
})

// 触发事件：广播给所有监听器
ctx.emit('event-name', payload)

这两行看似简单，但工程上有几个必须想清楚的问题。第一个是注册时机。ctx.on 必须在事件被触发之前执行，否则你注册的回调不会收到那次触发。这意味着监听端通常要放在插件初始化阶段（比如插件的 setup 或 apply 逻辑里），而不是放在某个「用到时才注册」的惰性分支里。如果你的插件依赖某个事件，却把它注册在首次调用时才执行的位置，那么第一次事件触发时你必然错过。这是一类非常隐蔽的 bug，因为它在单次流程测试里可能不出现，只有并发或时序敏感的场景才会暴露。

第二个问题是生命周期与清理。监听器不是免费的，注册了就要考虑什么时候解除。如果插件被卸载、如果某个上下文被销毁，监听器却仍然挂在事件上，就会造成回调被调用到已失效的对象，或者内存里的监听器列表越积越长。Cordis 提供了基于上下文的事件注册能力——监听器和注册它的上下文绑定，上下文销毁时监听也随之失效。这是一个重要的架构便利：把 ctx.on 理解为「在某个上下文的生命里监听」，而不是「往一个全局数组里塞回调」。前者会自动清理，后者要你手动管。在写代码时，优先使用上下文绑定的注册方式，能省掉大量清理逻辑。

第三个问题是payload 的约定。events 的文章标题里只给了 (payload) 这个形参，没有规定 payload 的结构。这是刻意的：Cordis 的事件系统不强制 payload 的类型，具体事件的 payload 由事件的定义者决定。作为插件的开发者，你消费哪个事件，就要按事件定义方的约定去读 payload；你定义自己的扩展点时，也要在文档里写清 payload 的字段。工程上的建议是：payload 尽量用可扩展的对象而不是位置参数，这样未来加字段时不会破坏已有监听者。同时，payload 里应该包含足够的上下文信息（比如来源标识、目标、配置），让监听者不必再回头去查全局状态，这一点对多组隔离的场景尤其重要——因为隔离之后各组可能看不到彼此的全局状态，payload 几乎成了唯一可靠的信息通道。

还有一个与隔离呼应的问题：事件本身是否隔离？这是很多人会下意识追问的。这里要区分开来讲：素材只说明了事件的两端 API 与分发模式，没有说明事件在 isolate 组之间是否自动隔离。因此稳妥的工程设计是：不要假设事件会随组自动隔离，也不要假设所有组都一定能收到对方的事件。如果你的插件组需要严格的事件隔离，应该在事件名或 payload 里带上组标识，并在监听端做过滤；如果你希望跨组通信，就使用明确的公共事件名。把「事件是否跨组可见」当成一个需要你显式设计的决策点，而不是默默依赖某个默认行为，这样无论框架后续如何演进，你的代码都是稳的。

五种分发模式全景：emit / bail / serial / waterfall 各自的语义

学会了 on 和 emit 这两端，接下来要面对的是 Cordis 事件系统真正的精华：分发模式。素材标题里点名了五种：emit、bail、serial、waterfall（严格说标题里出现的是这四个词加上「等五种」，从这四者的命名规律看，它们代表了返回值处理与中断行为的几种基本语义）。为什么需要多种模式？因为「一个事件被多个监听器订阅」这件事，在不同场景下的期望行为完全不同：有时候你要的是通知式的广播，谁也不影响谁；有时候你要的是「第一个人给出有效结果就停下」；有时候你要的是顺序处理且能累积结果；有时候你要的是每个监听器都能改写输入、再传给下一个。把这几种语义做成不同的分发模式，而不是让每个事件自己去约定，能让插件生态的协作规则统一、可预测。

下面用对比表把各模式的返回值处理与中断行为摊开。表中强调的是「多个监听器同时存在时」的行为，因为这才是模式下差异真正的战场：

模式返回值处理中断行为典型语义适用场景
emit广播式，各监听器的返回值通常不汇聚不因单个监听器结果而中断通知、广播日志打点、状态上报
bail取第一个有意义的返回值即返回任一监听器给出结果后短路竞争、短路取得第一个可用的处理结果
serial按序执行并收集各监听器的返回值顺序执行，通常逐个处理串行累积需要多个参与者依次贡献结果
waterfall前一个监听器的输出作为后一个的输入沿链传递、逐步改写管道、变换链内容改写、配置覆盖、中间件式处理

逐条展开：emit 是最基础的模式，语义是「我发生了这件事，谁关心谁说」。它的核心期望是监听器之间互不干扰，所以它对返回值不做强约定，也不会因为某个监听器的结果而打断其他监听器。这种模式的典型用途是日志、打点、状态广播——它们的共同点是「多个消费者互相独立」，一个监听器出错不应该影响其他监听器收到通知。

bail 的语义是「谁先给出结果就用谁的，后面的不跑了」。这适合那种「多个插件都能处理同一件事，但只需要一个结果」的场景：比如多个策略插件都能为某个决策提供建议，取第一个有效的就行；后续监听器因为已经有人给了答案，就不用浪费计算了。bail 模式下要注意监听器的执行顺序——如果顺序是不确定的，那么「第一个」就不确定，这在高并发下可能导致行为漂移。所以使用 bail 时，要么保证监听器顺序是可控的，要么确保多个结果之间是可互换的、选哪个都行。

serial 的语义是「排好队，一个个来，把结果收集起来」。它和 emit 的区别在于结果是否被汇聚，和 bail 的区别在于是否短路。当一个扩展点需要多个插件依次贡献内容、且所有贡献都要保留时，serial 就是自然选择。比如生成一份报告，多个插件各追加一个章节，最终把所有章节拼起来。serial 模式下要关注单个监听器的失败是否影响后续：如果约定是「一个失败就中断整个链」，那失败的插件会拖累其他贡献者；如果约定是「各自独立、失败只记录不影响别人」，那么报告里可能缺一章但仍然可用。这需要在设计扩展点时明确，否则会变成生产环境的偶发数据缺失。

waterfall 是最强大也最容易误用的模式。它的语义是「输入沿着监听器链流动，每个监听器都能看到前一个的输出，并可以改写后传给下一个」，非常像中间件或管道。它适合内容改写类场景：比如一个插件给配置补默认值，下一个插件基于补过的值再做一次覆盖，再下一个做最终校验。waterfall 的顺序极其重要，因为输入是有流向的，顺序变了结果就变了。使用时要有两点纪律：一是每个监听器都应该明确自己是否修改 payload，不修改就原样透传，不要返回一个残缺的对象把后面的插件坑了；二是要能容忍上游的变化，因为你的输入可能被任何上游监听器改写过，不要假设字段一定存在。

那选择模式的思路是什么？给自己两个问题：第一，多个监听器的结果要不要汇聚？不汇聚用 emit，汇聚用 serial。第二，是否允许短路？允许且只要第一个结果用 bail，需要逐个变换、输出即输入用 waterfall。把这两个问题答清楚，模式基本就定了。最后强调一个跨模式的共性问题：无论哪种模式，监听器的异常处理都要有统一约定。素材没有规定某个监听器抛错时其他监听器会怎样，所以工程上你应该在自己的监听器内部做好 try/catch，尤其是那些并发被调用的打点类回调——一个未捕获的异常可能在 emit 广播时影响到整个调用栈。把「监听器不应该抛出未处理异常」当成一条团队纪律，能省掉很多莫名其妙的现场。

到这里，隔离与通信的两条主线已经各自铺开：用 isolate 让 shell 服务在每个组里各自成实例，用 group: true 划定组的边界，用 timeoutMs 的差异来验证隔离真的生效，用 scope 与 isolate 的分工厘清可见性和实例数这两个正交维度；同时用 ctx.on / ctx.emit 搭起通信两端，用 emit / bail / serial / waterfall 的对比选出正确的分发语义。下一段我们会把这些机制放进更复杂的真实协作场景里，讨论多个隔离组之间如何通过事件安全地互相协作、以及配置与代码如何配合以避免隔离失效和事件风暴。

上一段我们把 isolate 与 group 的组合拳拆开讲透，明确了「同一服务、多份实例、按组可见」这条主线。这一段落我们把视角切到另一条轨道：插件之间真正用来对话的通道——事件系统。更关键的是，我们要回答一个容易被忽视的问题：当你做了作用域隔离之后，事件广播会不会也被隔在墙外？

waterfall 的载荷流转：上一个监听器如何改写下一个的输入

waterfall 是五种事件分发模式里最像「流水线」的一种。它的核心规则只有一条：每个监听器的返回值，会作为下一个监听器的输入载荷继续往下传。如果你不返回任何东西（返回 undefined），那么下一个监听器收到的仍是上游传下来的那份载荷，链条不会断。

这个机制在工程上的价值在于：它把「加工」这件事拆成了可插拔的多段。比如一个请求进入系统，第一个监听器补默认超时，第二个监听器注入鉴权头，第三个监听器做参数校验，第四个监听器打点计时——每一环只关心自己那一段，不需要知道前后是谁。这跟中间件模型几乎同构，区别在于 waterfall 的链是由事件名动态聚合出来的，而不是写死在一条数组里。

要注意一个细节：waterfall 的载荷是「逐环替换」而不是「逐环合并」。也就是说，第二个监听器返回的对象完全取代了它拿到的载荷，而不是附加在上面。这意味着如果你只返回了变化的那一个字段，上游字段就丢了。所以在实际写监听器时，稳妥的做法是把入参先展开，再覆盖自己关心的字段，例如把 {...payload, timeoutMs: 8000} 返回出去，而不是只返回 { timeouts: 8000 }。很多「后面监听器拿不到前面字段」的 bug，根因就出在这里。

另一个坑是异步。如果监听器返回的是 Promise，那么链条会在 Promise 解析后才继续传值。这意味着一个慢监听器会拖住整条 waterfall。对于超时敏感的场景（比如 timeoutMs: 5000 的 shell 调用路径），要确保链上的监听器都是轻量的、无阻塞 IO 的，或者把重活丢到 emit 的旁路里去做。

下面这段代码可以直接粘贴到一个 TypeScript 插件里，演示一条典型的 waterfall 加工链，包含载荷继承与顺序观测：

// 文件路径：scratch-plugin/src/waterfall-demo.ts
import type { Context } from '@deepseek-ai/cordis'

export const name = 'waterfall-demo'

export function apply(ctx: Context) {
  // 第一环：补默认超时，注意保留其余字段
  ctx.on('harness:command:before-run', async (payload) => {
    console.log('[waterfall #1] 收到载荷:', JSON.stringify(payload))
    return { ...payload, timeoutMs: payload.timeoutMs ?? 5000 }
  })

  // 第二环：注入来源标记，同样做浅拷贝合并
  ctx.on('harness:command:before-run', (payload) => {
    console.log('[waterfall #2] 上一环结果:', JSON.stringify(payload))
    return { ...payload, origin: 'plugin-waterfall-demo' }
  })

  // 第三环：只做观测，不返回，载荷原样透传
  ctx.on('harness:command:before-run', (payload) => {
    console.log('[waterfall #3] 最终载荷:', JSON.stringify(payload))
    // 无 return —— 链条继续沿用 #2 的返回值
  })
}

跑起来之后你会看到日志严格按 #1 → #2 → #3 打印，且 #3 能同时看到 timeoutMs 与 origin 两个字段。这就是 waterfall 的「接力」形态：返回值即下一棒的交接物。

bail 的短路语义：首个非空返回如何终止后续监听器

bail 的语义可以概括成一句话：第一个返回了「非空值」的监听器，直接终止整条分发链，后续监听器不再收到事件。这里的「非空值」指的是 undefined 与 null 之外的一切返回值——注意，返回 false、0、空字符串 '' 都可能被视作有效返回值而触发短路，具体以你所在版本的判定为准，写代码时不要依赖这些边界值去表达「不拦截」的意图。

用状态流转的视角来看会更清楚：整条链只有两个状态——继续传播与已终止。事件初始处于继续传播态，每经过一个监听器就做一次判定：返回值非空吗？非空则切到已终止态，后面全部跳过；为空则保持继续传播态。一旦进入已终止态，就没有回头路，即使后面有监听器能返回更合适的结果，也没有机会执行。

这个特性对扩展点的顺序有隐含要求。因为「谁先谁后」直接决定了「谁能否决掉谁」，所以 bail 型扩展点的监听注册顺序必须是一个明确的契约，而不是随机。工程上有两条应对思路：其一，约定一条优先级字段（比如 priority），由注册方显式声明；其二，把互斥的决策逻辑收敛到同一个监听器里，减少跨插件的否决竞争。最危险的情况是：两个插件都以为自己是唯一的决策者，结果后来注册的那个永远抢不到短路机会，表现为「我明明返回了拦截值，但系统还是继续跑了」。

bail 特别适合做三件事：权限拦截、缓存命中直接返回、熔断前置检查。它们的共同点是——命中即终局，不需要后续环节再加工。

serial 与并行触发：监听器执行顺序对副作用的影响

serial 的关键特征是串行：监听器一个接一个执行，前一个完成（含其异步部分解析完）之后才轮到下一个。这带来一个非常重要的保证——执行顺序是确定的，所以当多个监听器都要写同一份外部状态时，不会出现并发覆盖。

与之相对的是 emit 的广播行为：它把事件同时散发给所有监听器，是一种「通知」语义，而不是「处理」语义。emit 不关心返回值，也不承诺监听器之间的先后关系（具体调度细节依运行时实现而定）。所以凡是需要「有顺序、有返回值、有串行副作用」的场景，都不该用 emit 去凑合。

这里有一个很容易踩的工程坑：在 timeoutMs: 5000 这种短超时路径上，如果你用 emit 广播出去、而某个监听器偷偷做了远程调用，由于 emit 不等待，调用方可能在远程结果回来之前就已经往下一步走了，结果就是「日志里明明执行了，状态却没落库」。这类问题排查起来极其费时，所以在事件选型阶段就要想清楚语义。

为了把四种模式（含 waterfall 与 bail）的差异放一起看，下面这张表可以直接当作选型对照：

模式返回值处理是否短路执行顺序典型用途
emit忽略返回值不会广播，不承诺顺序通知、日志、埋点
serial一般忽略，按序等待不会严格串行有顺序副作用的初始化、注册
bail首个非空即生效会，且不可逆串行至短路点权限拦截、缓存命中、熔断
waterfall作为下一环输入不会严格串行载荷加工、中间件式处理

把这张表贴在团队文档里，能省掉大量「这个扩展点该用哪种事件」的口水战。

Harness 扩展点为什么建在事件之上：松耦合通信的取舍

Harness 之所以把大量扩展点建在事件机制之上，根本原因是插件之间互不感知。插件 A 不需要 import 插件 B，也不需要知道 B 的类名、方法名、构造参数。A 只负责在某个事件名上挂一个回调，B 只负责在合适的时机触发这个名字。双方共享的契约缩减为一个字符串（事件名）加一个载荷约定，这是耦合度最低的一种协作方式。

这种设计的收益在扩展性上体现得淋漓尽致：新增一个插件不需要改动任何既有代码，只要它监听对了事件名，就自动被编织进流程。反过来，移除一个插件也不会引发调用方的编译错误——最多是某个事件少了一个监听器，行为退化为「不做额外加工」，而不是崩溃。对于需要长期演进的 Agent 框架来说，这种「可增可减、不炸主链路」的性质极其宝贵。

但代价也很明确：调试成本显著上升。因为调用关系不在代码里显式出现，你没法靠「跳转到定义」找到事件的触发点，只能靠全局搜索事件名字符串。当事件名拼写有细微差异、或者载荷字段名对不上时，问题不会在启动阶段暴露，而是表现为某个功能「静默不生效」。前面提到的 ctx.on('event-name', ...) 与 ctx.emit('event-name', payload) 这种基本用法，恰恰是最需要建立命名规范的地方。

实务上的应对措施有三条：一是给事件名建立统一前缀（比如 harness:command:before-run 这种分层命名），避免撞名；二是把常用载荷结构定义成共享的类型文件，让 TypeScript 在编译期替你抓类型不匹配；三是在关键扩展点上加一条「监听器数量」的运行时日志，超过预期上限时告警，防止某次改动不小心注册了两遍。

隔离与事件的交叉地带：跨组事件是否会被隔离挡住

这是整篇文章最容易被误解的部分。很多人以为一旦用 isolate 把 shell 服务分成两份实例，事件广播也会跟着被隔开——事实并非如此简单。isolate 隔离的是服务实例，它决定的是「不同插件组拿到的是同一个对象还是各自的副本」；而事件的分发可见范围，取决于事件本身挂在哪个 作用域（scope） 上。

换句话说，隔离与事件是两条正交的轴。你把 shell 隔成两份，只影响 ctx.shell 这个引用指向的实例；但如果你在 group-a 里 ctx.emit('some-event', payload)，这个广播到底会不会被 group-b 的监听器收到，要看事件通道是绑定在根作用域还是组内作用域上。如果绑定在根上，跨组可见；如果绑定在组内，那么它就只在这个组的插件集合里流转。

这就带来了一个典型的排查场景：某个插件在 group-a 里发事件，期望 group-b 里的插件能收到并做响应，结果 group-b 那边一直没有动静。此时你的第一反应不应该是「bail 把事件短路了」，而应该先怀疑作用域边界。下面的批量演练配置可以帮你快速复现这个现象——两个组各自隔离 shell，但事件通道保持默认：

# 文件路径：scratch-plugin/cordis.yml
# 定义两个插件组 group-a 与 group-b，各自隔离一份 shell 服务
- id: group-a
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true          # 让本组内的 shell 服务独立实例化
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 5000  # group-a 的 Bash 超时 5 秒
    - name: './src/plugin-a.ts'

- id: group-b
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 60000 # group-b 的 Bash 超时 60 秒
    - name: './src/plugin-b.ts'

注意两组 timeoutMs 的差异：group-a 是 5000，group-b 是 60000。隔离生效之后，group-a 里的插件无论怎么调 shell，拿到的都是 5 秒超时的那份实例，绝不会被 group-b 的 60 秒配置污染。这正是隔离要解决的问题——同一服务、不同实例、不同配置。

而事件这块，如果你希望事件也严格限制在组内，就得显式地在组的作用域上注册监听与触发，而不是在根 ctx 上操作。判定的核心问题是：我的 ctx 是从哪里来的？组内插件的 apply 拿到的 ctx 天然带着组的作用域，用它注册的监听器就落在这个组里；如果用根 ctx 或跨层传递出来的引用去注册，就会跑到组外去。

排查清单：隔离没生效时先查这五个点

当你发现「配置写了 isolate，但两个组好像还在共用同一份服务实例」时，不要盲目改配置，按下面这条路径逐项核对，能覆盖绝大多数翻车场景：

  1. group 声明检查：确认承载隔离的条目确实带上了 group: true。没有 group 语义的普通插件条目，isolate 字段没有承载者，写了也白写。
  2. isolate 字段检查：确认被隔离的服务名写在 isolate 之下，且拼写与服务注册名一致。素材中的写法是 isolate: { shell: true }，键名对应服务标识，值为布尔开关。
  3. config 层级检查：注意隔离声明与插件配置的层级关系。服务配置（如 timeoutMs）要落到它所属的插件条目下，而不是平铺到 group 的顶层，否则会被当成未知字段静默忽略。
  4. 实例命名空间检查：确认两份实例确实是两个独立对象，而不是同一个对象被两个组引用。可以在插件 apply 里打印实例特征（比如一个自增 id 或配置快照）来验证。
  5. 作用域归属检查：确认你要隔离的事件监听/触发是挂在组内 ctx 上，而不是根 ctx 上。事件跨组可见与否，由这一步决定，与 isolate 字段无关。

把这条清单固化进团队的排障手册，可以把「隔离失效」这类问题的平均定位时间压到很短。

2026 年 9 月视角：Harness 插件隔离与事件分发的最新实践走向

站在 2026 年 9 月回看，Harness 在多组多实例的配置治理上已经形成了一些比较稳定的实践共识。首先是隔离粒度的细化：早期大家习惯对整个服务目录一把梭地开 isolate，现在更倾向于只隔离那些真正需要差异化配置的服务，比如 shell（超时不同）、网络出口（代理不同）、缓存（容量不同）。把所有服务都隔离，反而会带来不必要的实例膨胀与内存开销。

其次是事件边界约定的显式化。随着插件数量增长，靠「默认可见」来传事件会越来越危险——A 组的事件意外被 C 组收到并触发了副作用，这类问题在多实例场景下极难复现。因此越来越多的团队开始给事件分类：全局事件（跨组广播，走根作用域，用于框架级通知）与局部事件（组内流转，走组作用域，用于业务逻辑）。分类之后，事件名也带上可区分的层级前缀，便于静态检索。

第三是配置即契约的思路。既然 isolate 决定了实例边界，那么每个组里各服务的关键参数（如前面反复提到的 5000 与 60000 两个超时档）就应该被当作公开契约来管理：写进配置、进版本控制、在文档里列成对照表。这样当有人问「为什么 A 组的命令 5 秒就断」时，答案在配置里一目了然，而不需要去翻插件源码。

第四是可观测性的补位。因为事件调用链不可见，所以运行时的监听器计数、分发模式命中统计、短路发生率这几项指标变得格外重要。把它们采集出来，等于给「看不见的调用关系」装上了仪表盘。这是对事件机制固有调试成本的一种系统性补偿。

总结与最佳实践

把全文要点压成一份可执行清单，建议直接落地到你的项目评审 checklist 里：

  • 隔离只作用于服务实例，不作用于事件：isolate 决定「拿到哪个实例」，事件可见范围由作用域决定，两件事分开思考。
  • group + isolate 成套使用：isolate 需要 group 条目承载，group: true 与 isolate: { shell: true } 要成对出现。
  • 服务配置落在插件条目下：timeoutMs: 5000 这类参数要挂在具体服务插件的 config 里，层级错了会被静默忽略。
  • waterfall 记得展开合并再返回：用 { ...payload, ...change } 避免字段丢失，返回即下一环输入。
  • bail 依赖顺序契约：首个非空返回即终止，注册顺序必须显式约定，不要依赖随机顺序。
  • serial 用于有顺序副作用的场景：需要串行保证时别用 emit 凑合，emit 是广播通知语义。
  • 事件选型先想语义再写代码：通知用 emit，加工用 waterfall，拦截用 bail，顺序副作用用 serial。
  • 事件名分层命名 + 共享类型：用统一前缀防撞名，用 TypeScript 类型在编译期抓载荷不匹配。
  • 跨组通信先查作用域归属：确认监听与触发挂在组内 ctx 还是根 ctx，这是跨组事件失效的第一嫌疑点。
  • 隔离没生效按五步查：group 声明 → isolate 字段 → config 层级 → 实例命名空间 → 作用域归属。
  • 建立可观测性：统计监听器数量与短路发生率，为不可见的事件链装上仪表盘。
  • 隔离粒度按需细化：只隔离需要差异化配置的服务，避免实例膨胀。

走到这里，作用域隔离与事件系统这两条线就合上了：隔离管的是「同一服务怎么各拿各的实例」，事件管的是「插件之间怎么互不感知地对话」。把它们分开理解、交叉验证，才能让多个插件在同一套 Harness 里和平共处、不打架。