better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/02-lifecycle-and-effects.md

@@ -0,0 +1,98 @@
+# 2. Lifecycle and effects
+
+English | [中文](02-lifecycle-and-effects.zh.md)
+
+A Cordis plugin can be unloaded by a config edit, hot reload, explicit disposal, or loss of a required service. Registrations made through Cordis APIs are effects and are undone when their owning plugin unloads; resources managed outside those APIs must be wrapped in `ctx.effect()`.
+
+## Effects
+
+For a resource Cordis does not already manage — a timer, a connection, a watcher — wrap it in `ctx.effect()` and return a disposer:
+
+Create `lifecycle.ts` in `tmp/cordis-tutorial`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'lifecycle-demo'
+
+function heartbeat(ctx: Context) {
+  console.log('heartbeat plugin loading')
+  ctx.effect(() => {
+    const timer = setInterval(() => console.log('tick'), 200)
+    return () => {
+      clearInterval(timer)
+      console.log('heartbeat cleaned up')
+    }
+  })
+}
+
+export function apply(ctx: Context) {
+  // Mount a child plugin and keep its fiber to dispose it later.
+  const fiber = ctx.plugin(heartbeat)
+  // The demo timer is itself an effect: if THIS plugin is unloaded first,
+  // the pending callback is cancelled instead of firing on a dead app.
+  ctx.effect(() => {
+    const timer = setTimeout(async () => {
+      await fiber.dispose()
+      console.log('disposed')
+      process.exit(0)
+    }, 700)
+    return () => clearTimeout(timer)
+  })
+}
+```
+
+Point `cordis.yml` at it:
+
+```yaml
+- name: './lifecycle.ts'
+```
+
+Run (`node --import tsx ../../vendor/cordis/bin.js`) and you get:
+
+```
+heartbeat plugin loading
+tick
+tick
+tick
+heartbeat cleaned up
+disposed
+```
+
+Three things to notice:
+
+- `ctx.plugin(heartbeat)` mounts a function **from code** as a plugin — the same operation the YAML loader performs for each config entry. A function plugin needs no `apply` method: Cordis calls the function directly and uses its name only for diagnostics. An `apply` method is required only for the object form, `ctx.plugin({ apply(ctx) { /* ... */ } })`. The call returns a **fiber**, the runtime handle for one loaded plugin instance.
+- The effect body runs during load; the disposer it returns runs during unload. You never call the disposer yourself for a plugin-lifetime resource.
+- `fiber.dispose()` resolves after all of the plugin's cleanup — including async disposers — has finished, and recursively unloads any child plugins it mounted.
+
+## The fiber state machine
+
+Every loaded plugin instance owns a fiber that moves through these states:
+
+```
+PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
+                 ↘ FAILED
+```
+
+- **PENDING** — declared, but a required service (chapter 3) is not available yet.
+- **LOADING / ACTIVE** — `apply` is running / has completed.
+- **FAILED** — `apply` or config validation threw.
+- **UNLOADING / DISPOSED** — disposers are running / everything is torn down.
+
+You will meet PENDING again in [chapter 6](06-composition-and-hmr.md), where it is the usual answer to "why does my plugin print nothing?".
+
+## What is already an effect
+
+You rarely write `ctx.effect()` yourself, because the built-in registration APIs are effects already:
+
+- `ctx.on(event, listener)` — the listener is removed on unload ([chapter 4](04-events.md)).
+- `ctx.plugin(child)` — the child is disposed with its parent.
+- Service registrations are effects. Harness registries such as `ctx.tools.register(...)` also attach their returned disposers to the calling plugin, so they unwind automatically ([chapter 7](07-into-the-harness.md)).
+
+For a resource Cordis does not manage, acquire it inside `ctx.effect()` and return a disposer that releases it. Cordis then invokes that release during unloading, including hot reload.
+
+One ordering caveat: disposers start in reverse registration order, but multiple **async** disposers run concurrently. If teardown steps must run in sequence, keep them in one disposer and await them there.
+
+Next: [Services](03-services.md) — how plugins share capabilities.
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md

@@ -0,0 +1,98 @@
+# 2. 生命周期与 effect
+
+[English](02-lifecycle-and-effects.md) | 中文
+
+Cordis 插件可能因修改配置、热重载、显式资源释放或所需服务消失而卸载。通过 Cordis API 建立的注册属于 effect，会在所属插件卸载时撤销；在这些 API 之外管理的资源必须包装在 `ctx.effect()` 中。
+
+## Effect
+
+对于 Cordis 尚未管理的资源，例如定时器、连接或 watcher，应将其包装在 `ctx.effect()` 中并返回 disposer（资源释放函数）：
+
+创建 `lifecycle.ts`，将它放在 `tmp/cordis-tutorial` 中：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'lifecycle-demo'
+
+function heartbeat(ctx: Context) {
+  console.log('heartbeat plugin loading')
+  ctx.effect(() => {
+    const timer = setInterval(() => console.log('tick'), 200)
+    return () => {
+      clearInterval(timer)
+      console.log('heartbeat cleaned up')
+    }
+  })
+}
+
+export function apply(ctx: Context) {
+  // Mount a child plugin and keep its fiber to dispose it later.
+  const fiber = ctx.plugin(heartbeat)
+  // The demo timer is itself an effect: if THIS plugin is unloaded first,
+  // the pending callback is cancelled instead of firing on a dead app.
+  ctx.effect(() => {
+    const timer = setTimeout(async () => {
+      await fiber.dispose()
+      console.log('disposed')
+      process.exit(0)
+    }, 700)
+    return () => clearTimeout(timer)
+  })
+}
+```
+
+让 `cordis.yml` 指向该文件：
+
+```yaml
+- name: './lifecycle.ts'
+```
+
+运行（`node --import tsx ../../vendor/cordis/bin.js`）后会得到：
+
+```
+heartbeat plugin loading
+tick
+tick
+tick
+heartbeat cleaned up
+disposed
+```
+
+请留意三点：
+
+- `ctx.plugin(heartbeat)` 会把一个**来自代码**的函数挂载为插件，这与 YAML loader 为每个配置项执行的操作相同。函数插件不需要 `apply` 方法：Cordis 会直接调用该函数，其名称只用于诊断。只有对象形态才要求 `apply` 方法，例如 `ctx.plugin({ apply(ctx) { /* ... */ } })`。调用会返回一个 **fiber**，即一个已加载插件实例的运行时句柄。
+- effect 主体在加载期间运行；它返回的 disposer 在卸载期间运行。对于生命周期与插件一致的资源，你绝不需要自行调用 disposer。
+- `fiber.dispose()` 会等该插件的所有清理工作（包括异步 disposer）完成后才结束，并递归卸载它挂载的所有子插件。
+
+## Fiber 状态机
+
+每个已加载插件实例都拥有一个 fiber，并在以下状态之间转换：
+
+```
+PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
+                 ↘ FAILED
+```
+
+- **PENDING**：已经声明，但所需服务（第 3 章）尚不可用。
+- **LOADING / ACTIVE**：`apply` 正在运行／已经完成。
+- **FAILED**：`apply` 或配置校验抛出异常。
+- **UNLOADING / DISPOSED**：disposer 正在运行／一切均已拆除。
+
+你会在[第 6 章](06-composition-and-hmr.zh.md)再次遇到 PENDING，它通常就是「为什么我的插件没有输出」的答案。
+
+## 已经属于 effect 的操作
+
+你很少需要亲自编写 `ctx.effect()`，因为内置注册 API 本身已经是 effect：
+
+- `ctx.on(event, listener)`：监听器会在卸载时移除（[第 4 章](04-events.zh.md)）。
+- `ctx.plugin(child)`：子插件会随父插件一同 dispose（资源释放）。
+- 服务注册属于 effect。`ctx.tools.register(...)` 等 harness 注册表也会把返回的 disposer 附着到调用插件上，因此会自动撤销（[第 7 章](07-into-the-harness.zh.md)）。
+
+对于 Cordis 不管理的资源，应在 `ctx.effect()` 内获取它，并返回用于释放资源的 disposer。此后 Cordis 会在卸载期间调用该释放逻辑，热重载时也不例外。
+
+有一项顺序注意事项：disposer 会按注册顺序的逆序启动，但多个**异步** disposer 会并发运行。如果拆除步骤必须按顺序执行，请把它们放在同一个 disposer 中，并在其中依次等待每步完成。
+
+下一章：[服务](03-services.zh.md)：插件如何共享功能。
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/03-services.md

@@ -0,0 +1,98 @@
+# 3. Services
+
+English | [中文](03-services.zh.md)
+
+A **service** is a named capability one plugin provides and other plugins consume through `ctx`. In the harness, `ctx.tools`, `ctx.llm`, and `ctx.agents` are services. A consumer names the capability, such as `'tools'`, rather than importing its provider, so configuration can select a provider without changing the consumer.
+
+## Provide a service
+
+Create `greeter.ts` in `tmp/cordis-tutorial`:
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    greeter: GreeterService
+  }
+}
+
+export class GreeterService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'greeter')
+  }
+
+  greet(who: string) {
+    return `Hello, ${who}!`
+  }
+}
+
+export const name = 'greeter'
+
+export function apply(ctx: Context) {
+  ctx.plugin(GreeterService)
+}
+```
+
+Two pieces work together:
+
+- **Runtime**: `super(ctx, 'greeter')` registers the instance under the name `greeter`. From then on, any plugin can reach it as `ctx.greeter`. The registration is an effect — unloading the provider removes the service.
+- **Compile time**: the `declare module '@deepseek-ai/cordis'` block is TypeScript declaration merging. It adds `greeter` to the `Context` interface so `ctx.greeter` typechecks everywhere. It generates no code; without it the service still works at runtime, but consumers lose type safety.
+
+A `Service` subclass is itself a plugin (the class form from chapter 1), so `ctx.plugin(GreeterService)` mounts it like any other.
+
+## Consume a service with `inject`
+
+Create `consumer.ts`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'consumer'
+export const inject = ['greeter']
+
+export function apply(ctx: Context) {
+  console.log(ctx.greeter.greet('world'))
+}
+```
+
+`inject` lists the services this plugin requires. Cordis holds the plugin in PENDING until every listed service exists, so inside `apply`, `ctx.greeter` is guaranteed ready. Load order in `cordis.yml` does not matter — dependencies, not file order, decide when plugins start.
+
+Compose and run:
+
+```yaml
+- name: './greeter.ts'
+- name: './consumer.ts'
+```
+
+```
+Hello, world!
+```
+
+Swap the two lines in `cordis.yml` and rerun: same output. Try removing `./greeter.ts` entirely: the consumer stays PENDING and prints nothing — no crash, no partial run. A PENDING fiber does not keep Node's event loop alive either, so a composition with nothing else running exits 0 silently. [Chapter 6](06-composition-and-hmr.md) shows how to diagnose that state.
+
+## Dependencies are tracked after load
+
+`inject` is not a one-shot boot check. If a required service disappears while the app runs — its provider was unloaded or hot-replaced — every dependent plugin is unloaded too, and loads again when the service returns. Combined with effects ([chapter 2](02-lifecycle-and-effects.md)), this prevents a running consumer from retaining a reference to an unavailable service: its own registrations are unwound when the dependency disappears.
+
+This is also why service replacement works in config: unload the `dsh-bash-local` entry, mount a different `shell` provider, and every plugin injecting `'shell'` cleanly restarts against the new implementation.
+
+## Optional dependencies
+
+`inject` is for hard requirements. For a capability the plugin can live without, skip `inject` and probe at the use site:
+
+```ts ignore-check
+export function apply(ctx: Context) {
+  // undefined when no provider is loaded; the plugin still runs.
+  const greeter = ctx.get('greeter')
+  console.log(greeter?.greet('maybe') ?? 'no greeter available')
+}
+```
+
+## Naming
+
+Service names live in one flat namespace per application. Prefix or namespace your own services distinctively (the harness claims plain names like `tools` and `llm`); the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) list every name the harness registers.
+
+Next: [Events](04-events.md) — communication without a shared service.
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/03-services.zh.md

@@ -0,0 +1,98 @@
+# 3. 服务
+
+[English](03-services.md) | 中文
+
+**服务**是一个插件提供、其他插件通过 `ctx` 消费的具名能力。在 harness 中，`ctx.tools`、`ctx.llm` 和 `ctx.agents` 都是服务。消费方只指定 `'tools'` 之类的能力，而不导入其提供方，因此配置可以选择提供方，无需修改消费方。
+
+## 提供服务
+
+创建 `greeter.ts`，将它放在 `tmp/cordis-tutorial` 中：
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    greeter: GreeterService
+  }
+}
+
+export class GreeterService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'greeter')
+  }
+
+  greet(who: string) {
+    return `Hello, ${who}!`
+  }
+}
+
+export const name = 'greeter'
+
+export function apply(ctx: Context) {
+  ctx.plugin(GreeterService)
+}
+```
+
+两部分协同工作：
+
+- **运行时**：`super(ctx, 'greeter')` 以名称 `greeter` 注册该实例。此后，任何插件都可以通过 `ctx.greeter` 访问它。注册属于 effect，卸载提供方时会移除该服务。
+- **编译时**：`declare module '@deepseek-ai/cordis'` 块使用 TypeScript 声明合并，把 `greeter` 加入 `Context` 接口，使 `ctx.greeter` 在各处都能通过类型检查。它不会生成代码；没有该声明时，服务在运行时仍能工作，但消费方会失去类型安全。
+
+`Service` 子类本身就是插件（第 1 章介绍的类形态），因此 `ctx.plugin(GreeterService)` 会像挂载其他插件一样挂载它。
+
+## 使用 `inject` 消费服务
+
+创建 `consumer.ts`：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'consumer'
+export const inject = ['greeter']
+
+export function apply(ctx: Context) {
+  console.log(ctx.greeter.greet('world'))
+}
+```
+
+`inject` 列出该插件需要的服务。Cordis 会让插件保持 PENDING，直到列出的每项服务都存在，因此在 `apply` 内可以保证 `ctx.greeter` 已经就绪。`cordis.yml` 中的加载顺序无关紧要：决定插件何时启动的是依赖关系，而不是文件顺序。
+
+组合并运行：
+
+```yaml
+- name: './greeter.ts'
+- name: './consumer.ts'
+```
+
+```
+Hello, world!
+```
+
+交换 `cordis.yml` 中两行的顺序后重新运行，输出仍然相同。尝试彻底移除 `./greeter.ts`：消费方会保持 PENDING，不输出任何内容，既不崩溃，也不会只运行一部分。处于 PENDING 的 fiber 也不会让 Node 的事件循环保持活跃，因此如果组合中没有其他运行项，进程会静默地以状态码 0 退出。[第 6 章](06-composition-and-hmr.zh.md)介绍如何诊断这种状态。
+
+## 加载后仍会跟踪依赖关系
+
+`inject` 并非一次性的启动检查。如果应用运行期间所需服务消失，例如提供方被卸载或热替换，每个依赖插件也会随之卸载，并在服务恢复后再次加载。结合 effect（[第 2 章](02-lifecycle-and-effects.zh.md)），这能防止运行中的消费方保留对不可用服务的引用：依赖消失时，它自己的注册也会撤销。
+
+这也是配置中可以替换服务的原因：卸载 Cordis 配置项 `dsh-bash-local`，挂载另一个 `shell` 提供方，所有注入 `'shell'` 的插件都会重新启动并使用新实现。
+
+## 可选依赖
+
+`inject` 用于硬性依赖。如果某项功能缺失时插件仍可运行，请跳过 `inject`，并在使用处探测：
+
+```ts ignore-check
+export function apply(ctx: Context) {
+  // undefined when no provider is loaded; the plugin still runs.
+  const greeter = ctx.get('greeter')
+  console.log(greeter?.greet('maybe') ?? 'no greeter available')
+}
+```
+
+## 命名
+
+每个应用中的服务名称共用一个扁平命名空间。请为自有服务添加有辨识度的前缀或命名空间（harness 已占用 `tools` 和 `llm` 等普通名称）；[子系统页面](../subsystems/core.zh.md)上生成的 `cordis-surface` 区块列出 harness 注册的每个名称。
+
+下一章：[事件](04-events.zh.md)：无需共享服务即可通信。
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/04-events.md

@@ -0,0 +1,144 @@
+# 4. Events
+
+English | [中文](04-events.zh.md)
+
+Services support direct calls; **events** let a plugin announce something without knowing which plugins listen. The harness uses events for interactions such as tool results, model requests, and approval decisions.
+
+## Declare, emit, listen
+
+Create `stats.ts` in `tmp/cordis-tutorial` — a service that counts things and announces each change:
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    stats: StatsService
+  }
+  interface Events {
+    'stats/report'(name: string, count: number): void
+  }
+}
+
+export class StatsService extends Service {
+  private counts = new Map<string, number>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'stats')
+  }
+
+  bump(name: string) {
+    const next = (this.counts.get(name) ?? 0) + 1
+    this.counts.set(name, next)
+    this.ctx.emit('stats/report', name, next)
+  }
+}
+
+export const name = 'stats'
+
+export function apply(ctx: Context) {
+  ctx.plugin(StatsService)
+}
+```
+
+The `interface Events` merge is the event-system twin of the `interface Context` merge from chapter 3: it declares the event name and its listener signature, so `ctx.emit` and `ctx.on` are fully typed. The `namespace/action` naming convention keeps the flat event namespace readable.
+
+Create `reporter.ts`:
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from './stats.ts'
+
+export const name = 'reporter'
+export const inject = ['stats']
+
+export function apply(ctx: Context) {
+  ctx.on('stats/report', (name, count) => {
+    console.log(`[stats] ${name} -> ${count}`)
+  })
+  ctx.stats.bump('tool_call')
+  ctx.stats.bump('tool_call')
+  ctx.stats.bump('prompt')
+}
+```
+
+The `import type {} from './stats.ts'` line imports nothing at runtime; it exists so TypeScript sees the declaration merges. Compose and run:
+
+```yaml
+- name: './stats.ts'
+- name: './reporter.ts'
+```
+
+```
+[stats] tool_call -> 1
+[stats] tool_call -> 2
+[stats] prompt -> 1
+```
+
+Because `ctx.on()` is an effect, the listener disappears with the plugin — no manual `removeListener` bookkeeping, ever.
+
+## Dispatch modes
+
+`emit` is one of five dispatch modes. Which one an event uses is part of its contract — it decides whether listeners can return values, run concurrently, or short-circuit each other:
+
+| Mode | Call | Semantics |
+|---|---|---|
+| emit | `ctx.emit(name, ...args)` | Synchronous broadcast; returned promises and values are not awaited or collected. |
+| parallel | `await ctx.parallel(name, ...args)` | All listeners run concurrently; awaited together. |
+| serial | `await ctx.serial(name, ...args)` | Listeners run in order, awaited; the first non-`null`/`false`/`undefined` return wins and stops the rest. |
+| bail | `ctx.bail(name, ...args)` | Synchronous version of serial. |
+| waterfall | `ctx.waterfall(name, ...args, next)` | Around-middleware; see below. |
+
+Every harness event documents its mode in the generated reference on its owning [subsystem page](../subsystems/core.md).
+
+## Waterfall: transform or short-circuit
+
+Waterfall is the mode that powers interception. Each listener receives the arguments plus a `next()` continuation; it can transform what `next()` returns, or return without calling `next()` and short-circuit the rest of the chain — what the Cordis docs call the veto. Create `waterfall-demo.ts`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    'demo/transform'(input: string, next: () => Promise<string>): Promise<string>
+  }
+}
+
+export const name = 'waterfall-demo'
+
+export function apply(ctx: Context) {
+  // Listener 1: wrap the downstream result.
+  ctx.on('demo/transform', async (input, next) => {
+    const downstream = await next()
+    return downstream.toUpperCase()
+  })
+
+  // Listener 2: short-circuit when it owns the decision.
+  ctx.on('demo/transform', async (input, next) => {
+    if (input.includes('blocked')) return '** blocked **'
+    return next()
+  })
+
+  void (async () => {
+    console.log(await ctx.waterfall('demo/transform', 'hello', async () => 'hello'))
+    console.log(await ctx.waterfall('demo/transform', 'blocked words', async () => 'blocked words'))
+  })()
+}
+```
+
+Point `cordis.yml` at just this file and run:
+
+```
+HELLO
+** BLOCKED **
+```
+
+Walk through the second line: listener 1 runs first, calls `next()`, which invokes listener 2; listener 2 sees `blocked` and returns without calling `next()` — the innermost default (the function passed to `ctx.waterfall`) never runs — and listener 1 uppercases the replacement message on the way out.
+
+The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. It is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
+
+The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../subsystems/core.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) lets a policy answer instead of the user.
+
+Next: [Configuration](05-config.md) — plugin options from `cordis.yml`.
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/04-events.zh.md

@@ -0,0 +1,144 @@
+# 4. 事件
+
+[English](04-events.md) | 中文
+
+服务支持直接调用；**事件**让插件无需知道有哪些插件正在监听，就能发出通知。harness 使用事件处理工具结果、模型请求和审批决定等交互。
+
+## 声明、发出与监听
+
+创建 `stats.ts`，将它放在 `tmp/cordis-tutorial` 中。它是一项负责计数并在每次变化时发出通知的服务：
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    stats: StatsService
+  }
+  interface Events {
+    'stats/report'(name: string, count: number): void
+  }
+}
+
+export class StatsService extends Service {
+  private counts = new Map<string, number>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'stats')
+  }
+
+  bump(name: string) {
+    const next = (this.counts.get(name) ?? 0) + 1
+    this.counts.set(name, next)
+    this.ctx.emit('stats/report', name, next)
+  }
+}
+
+export const name = 'stats'
+
+export function apply(ctx: Context) {
+  ctx.plugin(StatsService)
+}
+```
+
+`interface Events` 合并与第 3 章的 `interface Context` 合并在事件系统中相互对应：它声明事件名称及其监听器签名，因此 `ctx.emit` 和 `ctx.on` 都具有完整类型。`namespace/action` 命名约定让扁平的事件命名空间保持易读。
+
+创建 `reporter.ts`：
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from './stats.ts'
+
+export const name = 'reporter'
+export const inject = ['stats']
+
+export function apply(ctx: Context) {
+  ctx.on('stats/report', (name, count) => {
+    console.log(`[stats] ${name} -> ${count}`)
+  })
+  ctx.stats.bump('tool_call')
+  ctx.stats.bump('tool_call')
+  ctx.stats.bump('prompt')
+}
+```
+
+`import type {} from './stats.ts'` 行不会在运行时导入任何内容；它的作用是让 TypeScript 看到声明合并。组合并运行：
+
+```yaml
+- name: './stats.ts'
+- name: './reporter.ts'
+```
+
+```
+[stats] tool_call -> 1
+[stats] tool_call -> 2
+[stats] prompt -> 1
+```
+
+因为 `ctx.on()` 属于 effect，监听器会随插件一同消失，绝不需要手动维护 `removeListener`。
+
+## 分发模式
+
+`emit` 是 5 种分发模式之一。事件采用哪种模式是其约定的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路：
+
+| 模式 | 调用 | 语义 |
+|---|---|---|
+| emit | `ctx.emit(name, ...args)` | 同步广播；不会等待或收集返回的 promise 与值。 |
+| parallel | `await ctx.parallel(name, ...args)` | 所有监听器并发运行，并一同等待。 |
+| serial | `await ctx.serial(name, ...args)` | 监听器按顺序运行并等待；第一个非 `null`/`false`/`undefined` 返回值胜出，并停止后续监听器。 |
+| bail | `ctx.bail(name, ...args)` | serial 的同步版本。 |
+| waterfall（瀑布式事件） | `ctx.waterfall(name, ...args, next)` | 环绕中间件，见下文。 |
+
+每个 harness 事件都会在其所属[子系统页面](../subsystems/core.zh.md)自动生成的参考文档中记录其模式。
+
+## waterfall：转换或短路
+
+waterfall 是实现拦截的模式。每个监听器都会收到参数和一个 `next()` continuation；它可以转换 `next()` 的返回值，也可以不调用 `next()` 就直接返回，从而短路链条的其余部分。Cordis 文档把后一种行为称为否决。创建 `waterfall-demo.ts`：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    'demo/transform'(input: string, next: () => Promise<string>): Promise<string>
+  }
+}
+
+export const name = 'waterfall-demo'
+
+export function apply(ctx: Context) {
+  // Listener 1: wrap the downstream result.
+  ctx.on('demo/transform', async (input, next) => {
+    const downstream = await next()
+    return downstream.toUpperCase()
+  })
+
+  // Listener 2: short-circuit when it owns the decision.
+  ctx.on('demo/transform', async (input, next) => {
+    if (input.includes('blocked')) return '** blocked **'
+    return next()
+  })
+
+  void (async () => {
+    console.log(await ctx.waterfall('demo/transform', 'hello', async () => 'hello'))
+    console.log(await ctx.waterfall('demo/transform', 'blocked words', async () => 'blocked words'))
+  })()
+}
+```
+
+让 `cordis.yml` 只指向该文件并运行：
+
+```
+HELLO
+** BLOCKED **
+```
+
+按顺序看第二行如何产生：监听器 1 先运行并调用 `next()`，从而调用监听器 2；监听器 2 看到 `blocked` 后直接返回而不调用 `next()`，因此最内层默认逻辑（传给 `ctx.waterfall` 的函数）从未运行；返回途中，监听器 1 再把替换消息转换为大写。
+
+由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这是本仓库的常设规则（[waterfall 语义](../cordis-primer.zh.md#cordis-waterfall-semantics)）。
+
+harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.zh.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.zh.md#approvalrequest--waterfall) 允许策略代替用户作答。
+
+下一章：[配置](05-config.zh.md)：来自 `cordis.yml` 的插件选项。
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)