super-dsh 0.3.0-c → 0.3.0-e

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

@@ -1,98 +0,0 @@
-# 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/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md

@@ -1,98 +0,0 @@
-# 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/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/03-services.md

@@ -1,98 +0,0 @@
-# 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/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/03-services.zh.md

@@ -1,98 +0,0 @@
-# 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/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/04-events.md

@@ -1,144 +0,0 @@
-# 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/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/cordis-tutorial/04-events.zh.md

@@ -1,144 +0,0 @@
-# 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)