dsh-plugin-dev-kb 1.0.0

package/kb/site/develop/basic/publish.md

@@ -0,0 +1,185 @@
+---
+editSource: "docs/user/develop/basic/publish.zh.md"
+---
+
+# 打包与安装插件
+
+前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。本文假设 `dsh` CLI 已安装。请先完成[插件配置](./config.md)。
+
+如果改用全新的源码 checkout，请先按照[从源码运行章节](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md#run-from-source)完成准备，将本教程的 `hello-plugin` 目录放在仓库根目录，并从该目录把下文的 `dsh ...` 命令改为 `pnpm dsh ...`。构建与启动器行为见[源码执行](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md#source-execution)。
+
+## 两个概念，两种 manifest
+
+安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest（元数据清单）种类不同，回答的问题也不同：
+
+- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。
+- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。
+
+组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。
+
+### 组合包 manifest
+
+创建包目录：
+
+```sh
+mkdir -p hello-plugin
+```
+
+```
+hello-plugin/
+├── package.json       # declares dsh.bundle
+├── cordis.patch.yml   # the layer applied when a profile lists this bundle
+└── index.js           # plugin modules the patch rows reference
+```
+
+创建 `hello-plugin/package.json`：
+
+```json
+{
+  "name": "dsh-hello-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "files": ["index.js", "cordis.patch.yml"],
+  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+}
+```
+
+创建 `hello-plugin/index.js`，写入插件入口：
+
+```js
+export const name = 'hello-plugin'
+
+export function apply() {
+  console.log('[hello-plugin] plugin loaded!')
+}
+```
+
+创建 `hello-plugin/cordis.patch.yml`。这个 patch 与一直在写的 `--patch` overlay 一样，是一个 patch 条目的 YAML 数组；区别是插件行按包名而不是相对源码路径引用这个包，这样 Node 的模块解析才能找到已安装的代码：
+
+```yaml
+- insert:
+    - id: hello
+      name: dsh-hello-plugin
+```
+
+没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
+
+### profile manifest
+
+profile 目录包含两个文件：
+
+- `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。
+- `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。
+
+profile manifest 从不需要手写：`dsh plugin` 负责创建和维护它。下一节展示其结果。
+
+## 安装进 profile
+
+`dsh plugin --profile <name> <args...>` 在 profile 目录内转发给 pnpm，因此所有 pnpm 子命令都可用。在包含 `hello-plugin` 的目录中安装该包的 checkout：
+
+```sh
+dsh plugin --profile demo add ./hello-plugin
+```
+
+首次使用会初始化 profile（`@deepseek-ai/dsh-base` 作为它的第一个组合包），pnpm 链接该 checkout，而 `dsh` 因为这个包声明了 `dsh.bundle`，把它追加进 `dsh.profile.bundles`：
+
+```json
+{
+  "name": "dsh-profile-demo",
+  "private": true,
+  "dependencies": {
+    "dsh-hello-plugin": "link:/path/to/hello-plugin"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "dsh-hello-plugin"
+      ]
+    }
+  }
+}
+```
+
+先不启动、只验证该层，再启动：
+
+```sh
+dsh --profile demo --dump-config   # shows a "# == dsh-hello-plugin" layer
+dsh --profile demo
+```
+
+`dsh plugin --profile demo remove dsh-hello-plugin` 会同时移除依赖和对应的层。
+
+## 加载顺序
+
+生效配置在空根之上按以下顺序逐层组合：
+
+1. profile 的 `dsh.profile.bundles` 列表所列的各个组合包 patch，按列表顺序——先是 `@deepseek-ai/dsh-base`，然后是每个已安装组合包，按其加入顺序。
+2. profile 自己的 `cordis.patch.yml`。
+3. home 级的 `$DSH_HOME/cordis.patch.yml`——各 profile 共享的机器本地偏好。
+4. 每个 `--patch <path>` overlay，按 argv 顺序。
+
+应用参数不是另一层 patch。表层组合包可以通过下文所述的普通应用自有服务解析它们。
+
+后应用的层按行胜出，且 patch 会替换目标行的整个 `config` 值，而不是深度合并各键。这给组合包作者带来两个推论：
+
+- 你的 patch 可以按 `id` 覆盖前面各层的行——就像 [`dsh-web-app` 组合包](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/web-app/cordis.patch.yml)覆盖 `dsh-base` 的行那样——但必须重述该行需要的每一个键，而不是只写改动的那个。
+- 用户可以在自己 profile 的 `cordis.patch.yml` 中覆盖你的行，无需改动你的包，所以优先给出用户大概率会保留的配置默认值，其余交给 schema 承担。
+
+内置组合包名称始终从 dsh 安装目录本身解析；pnpm 只管理树外的包，所以你的组合包可以放心依赖 `@deepseek-ai/dsh-base` 存在且与安装保持一致。
+
+## 让表层组合包持有自己的命令行
+
+定义了可运行应用的组合包挂载一个普通提供方插件：
+
+```yaml
+- id: hello-startup
+  name: 'dsh-hello-plugin/startup'
+```
+
+该插件导出 `inject = ['cmdlineArgs']`，使用自己的 commander program 调用 [`@deepseek-ai/dsh-cmdline`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/cmdline/README.md) 中的 `parseCmdline`，再在 program 自己的 action 中把应用自有服务提供出去。启动器把自身 flag 之后的同一份不可变参数交给每个插件，因此添加应用专属 flag 无需修改启动器，多个插件也可以解析该快照。Loader 行不需要启动器标记或特殊类型。
+
+受这些参数配置的行会注入提供方服务，并在自己的 `!!js` 选项中读取它，同时把部署取值写在旁边作为回退：
+
+```yaml
+- id: my-app
+  name: '@example/my-app'
+  inject: [myAppStartup]
+  config:
+    port: !!js ctx.myAppStartup.port ?? 8080
+```
+
+遇到 `--help` 时，提供方不会发布该服务，所以这些行不会激活。Loader 只挂载一次组合，等待每一行的普通注入，再基于其已注入的上下文求值该行的 `!!js` 配置。
+
+## 从 GitHub 安装：构建脚本这道坎
+
+发布到注册表不是必须的——用户可以直接从 git 托管安装：
+
+```sh
+dsh plugin --profile demo add github:you/hello-plugin
+```
+
+但 git 安装拉取的是**源码，不是构建产物**：没有任何环节运行你的 `build` 脚本，因此 TypeScript 包到手时没有 `lib/` 输出，加载会失败。必须两边各做一件事：
+
+- **作者**提供一个 `prepare` 脚本——pnpm 在 git 安装后运行它——从源码构建出发布入口，且必须自包含：不能假设仅开发环境才有的上下文，例如旁边有一份 monorepo checkout。[turtle-ui](https://github.com/deepseek-harness/turtle-ui) 是一个可用的例子：它的 `prepare` 运行一份专用的 tsdown 配置，直接转译 `src/`，不用项目引用，也不做类型检查。
+- **用户**为构建授权。pnpm ≥10 在得到显式允许之前拒绝运行 git 依赖的 `prepare` 脚本，所以第一次 `add` 会失败；`dsh` 会指出修法——把 pnpm 打印的确切包键复制进该 profile 的 `pnpm-workspace.yaml`：
+
+  ```yaml
+  allowBuilds:
+    dsh-hello-plugin: true
+  ```
+
+  然后重新执行 `add`。
+
+请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
+
+如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
+
+- **发布到 npm**，在 `pnpm publish` 时构建好 `lib/`；`dsh plugin add your-package` 安装的就是预构建代码。
+- **交付 tarball**：用 `pnpm pack` 打包；用户执行 `dsh plugin add ./hello-plugin-0.1.0.tgz`。
+
+## 下一步
+
+- [插件与生命周期](../framework/index.md) — 插件的完整生命周期
+- [CLI（命令行界面）行为参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md) — 确切的层优先级、flag 与 profile 机制

package/kb/site/develop/basic/tool.md

@@ -0,0 +1,54 @@
+---
+editSource: "docs/user/develop/basic/tool.zh.md"
+---
+
+# 开发一个工具
+
+本教程会在 Web UI 中添加一个 `greet` 工具。请先完成[第一个插件](./index.md)，并保留其中的 `scratch-plugin` 目录。
+
+## 创建工具插件
+
+将 `scratch-plugin/src/my-plugin.ts` 替换为：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'greet-tool'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  ctx.tools.register(defineTool({
+    name: 'greet',
+    description: 'Greet someone by name.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'The name to greet' },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) {
+      return `Hello, ${args.name}!`
+    },
+  }))
+}
+```
+
+`inject` 让 Cordis 等待工具注册表就绪。`defineTool` 根据 `parameters` 推导并校验 `args`；`execute` 返回 `output.schema` 声明的规范值，`output.render` 再将该值转换为面向模型的内容。
+
+## 运行并调用工具
+
+如果开发命令未在运行，请重新启动：
+
+```sh
+pnpm dsh web --patch ./scratch-plugin/cordis.yml
+```
+
+打开 `http://127.0.0.1:3080`，然后输入：`Use the greet tool to greet Ada.` 模型可以调用 `greet`，并收到 `Hello, Ada!` 这一工具结果。
+
+## 下一步
+
+- [插件配置](./config.md) — 让问候语可配置。
+- [工具编写参考](../../reference/cookbook/adding-a-tool.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、Code Mode 和 UI 卡片。
+- [能力分层](../practice/index.md) — 将可替换能力拆分为 Service Definition、Service Provider 和 Consumer 三类包。

package/kb/site/develop/cordis-tutorial/01-first-plugin.md

@@ -0,0 +1,95 @@
+---
+editSource: "docs/cordis-tutorial/01-first-plugin.zh.md"
+---
+
+# 1. 编写第一个插件
+
+在本教程使用的 loader 配置中，Cordis 插件模块通过命名导出提供 `apply` 函数。Cordis 加载模块时，会用一个 **上下文** 调用 `apply`；该上下文就是 `ctx` 对象，插件通过它注册自己贡献的所有内容。
+
+## 编写插件
+
+在 `tmp/cordis-tutorial` 目录中（参见[环境设置](./index.md#setup)）创建 `hello.ts`：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'hello'
+
+export function apply(ctx: Context) {
+  console.log('hello from my first plugin')
+}
+```
+
+`name` 导出项是可选的显示元数据；它用于在诊断信息中标识插件。
+
+## 组合应用
+
+本教程的启动器通过配置组装应用。创建 `cordis.yml`：
+
+```yaml
+- name: './hello.ts'
+```
+
+该文件是一组 Cordis 配置项的列表。`name` 是模块指定符，可以是相对路径或 NPM 包名；loader 会挂载每个配置项。各项会并发启动，因此它们在列表中的位置不保证插件的加载先后；顺序由服务依赖（`inject`，参见[第 3 章](./03-services.md)）决定，而非文件中的位置。
+
+## 运行
+
+```sh
+node --import tsx ../../vendor/cordis/bin.js
+```
+
+预期输出：
+
+```
+hello from my first plugin
+```
+
+当没有任何内容继续运行时，进程会自行退出。具体过程如下：
+
+1. 启动器创建根 `Context`，并挂载 **Loader** 插件。
+2. Loader 读取 `cordis.yml`，解析 `./hello.ts`，然后将其作为子插件挂载。
+3. Cordis 调用你的 `apply(ctx)`。
+
+你的文件中没有框架启动代码：插件描述自己的贡献，`cordis.yml` 则组合应用。例如，[`dsh` base](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/base/cordis.patch.yml) 就是一份更长的插件组合，由部署 overlay 对它进行修补。
+
+## 其他两种插件形态
+
+函数是最常见的形式，但 Cordis 接受三种形式：
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+// 1. Function plugin (what you just wrote).
+export function apply(ctx: Context) {}
+
+// 2. Object plugin: an object with an `apply` method.
+export const objectPlugin = {
+  name: 'object-plugin',
+  apply(ctx: Context) {},
+}
+
+// 3. Class plugin: a Service subclass (covered in chapter 3).
+export class MyService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'myTutorialService')
+  }
+}
+```
+
+在你需要公开服务之前，请一直使用函数形态；[第 3 章](./03-services.md)介绍了何时应当使用类形态。
+
+## 尝试制造错误
+
+让 `apply` 抛出异常：
+
+```ts ignore-check
+export function apply(ctx: Context) {
+  throw new Error('apply exploded')
+}
+```
+
+再次运行：进程会因该错误而终止。插件加载失败会明确报错，不会仅跳过该配置项。
+
+还需要尽早了解一个例外：如果某个配置项的模块无法被 **解析**，例如路径或包名拼写错误，Cordis 会通过 logger 服务报告错误，而不会使进程崩溃。在启动阶段，这条报告可能在 console 导出器开始观察之前丢失。如果新增配置项似乎没有任何效果，请先检查拼写。
+
+下一章：[生命周期与 effect](./02-lifecycle-and-effects.md)：插件卸载时会发生什么。

package/kb/site/develop/cordis-tutorial/02-lifecycle-and-effects.md

@@ -0,0 +1,98 @@
+---
+editSource: "docs/cordis-tutorial/02-lifecycle-and-effects.zh.md"
+---
+
+# 2. 生命周期与 effect
+
+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.md)再次遇到 PENDING，它通常就是「为什么我的插件没有输出」的答案。
+
+## 已经属于 effect 的操作
+
+你很少需要亲自编写 `ctx.effect()`，因为内置注册 API 本身已经是 effect：
+
+- `ctx.on(event, listener)`：监听器会在卸载时移除（[第 4 章](./04-events.md)）。
+- `ctx.plugin(child)`：子插件会随父插件一同 dispose（资源释放）。
+- 服务注册属于 effect。`ctx.tools.register(...)` 等 harness 注册表也会把返回的 disposer 附着到调用插件上，因此会自动撤销（[第 7 章](./07-into-the-harness.md)）。
+
+对于 Cordis 不管理的资源，应在 `ctx.effect()` 内获取它，并返回用于释放资源的 disposer。此后 Cordis 会在卸载期间调用该释放逻辑，热重载时也不例外。
+
+有一项顺序注意事项：disposer 会按注册顺序的逆序启动，但多个**异步** disposer 会并发运行。如果拆除步骤必须按顺序执行，请把它们放在同一个 disposer 中，并在其中依次等待每步完成。
+
+下一章：[服务](./03-services.md)：插件如何共享功能。

package/kb/site/develop/cordis-tutorial/03-services.md

@@ -0,0 +1,98 @@
+---
+editSource: "docs/cordis-tutorial/03-services.zh.md"
+---
+
+# 3. 服务
+
+**服务**是一个插件提供、其他插件通过 `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.md)介绍如何诊断这种状态。
+
+## 加载后仍会跟踪依赖关系
+
+`inject` 并非一次性的启动检查。如果应用运行期间所需服务消失，例如提供方被卸载或热替换，每个依赖插件也会随之卸载，并在服务恢复后再次加载。结合 effect（[第 2 章](./02-lifecycle-and-effects.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` 等普通名称）；[子系统页面](../../reference/subsystems/core.md)上生成的 `cordis-surface` 区块列出 harness 注册的每个名称。
+
+下一章：[事件](./04-events.md)：无需共享服务即可通信。

package/kb/site/develop/cordis-tutorial/04-events.md

@@ -0,0 +1,144 @@
+---
+editSource: "docs/cordis-tutorial/04-events.zh.md"
+---
+
+# 4. 事件
+
+服务支持直接调用；**事件**让插件无需知道有哪些插件正在监听，就能发出通知。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 事件都会在其所属[子系统页面](../../reference/subsystems/core.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 语义](../../reference/cordis-primer.md#cordis-waterfall-semantics)）。
+
+harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../../reference/subsystems/core.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../../reference/subsystems/approval.md#approvalrequest--waterfall) 允许策略代替用户作答。
+
+下一章：[配置](./05-config.md)：来自 `cordis.yml` 的插件选项。