dsh-plugin-guide 0.1.0

package/references/official-docs/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.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.md#cordis-waterfall-semantics)）。
+
+harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) 允许策略代替用户作答。
+
+下一章：[配置](05-config.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)

package/references/official-docs/docs/cordis-tutorial/05-config.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/cordis-tutorial/05-config.md
+05-config.md: 17cccce2ec43be65477ce527800ee6a636ee5d96
+05-config.zh.md: 87f1cb465d5f3e52a6f8e449cfb29818ba86dcb8

package/references/official-docs/docs/cordis-tutorial/05-config.md

@@ -0,0 +1,84 @@
+# 5. Configuration
+
+English | [中文](05-config.zh.md)
+
+Each `cordis.yml` entry can carry a `config` block, and the plugin declares a schema that validates it before `apply` runs. Bad config fails the load with a precise error — the plugin never starts half-configured.
+
+## A configurable plugin
+
+Create `config-demo.ts` in `tmp/cordis-tutorial`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+
+export const name = 'config-demo'
+
+export interface Config {
+  greeting: string
+  targets: string[]
+}
+
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello'),
+  targets: Schema.array(String).default(['world']),
+})
+
+export function apply(ctx: Context, config: Config) {
+  for (const target of config.targets) {
+    console.log(`${config.greeting}, ${target}!`)
+  }
+}
+```
+
+The exported `Config` is both a TypeScript interface and a runtime schema with the same name — consumers get the type, Cordis gets the validator. This repo uses [Schemastery](https://github.com/shigma/schemastery) for schemas; Cordis itself accepts any [Standard Schema](https://standardschema.dev/) validator, so a plain object exported as `Config` will not work.
+
+Configure it:
+
+```yaml
+- name: './config-demo.ts'
+  config:
+    targets: ['alpha', 'beta']
+```
+
+Run:
+
+```
+Hello, alpha!
+Hello, beta!
+```
+
+`greeting` was omitted, so the schema default filled it in — `apply` always receives complete, validated config.
+
+## Fail loud
+
+Now feed it something invalid:
+
+```yaml
+- name: './config-demo.ts'
+  config:
+    targets: 'not-an-array'
+```
+
+```
+ValidationError: invalid config:
+  - $.targets expected array but got not-an-array (at targets)
+```
+
+The plugin's fiber goes to FAILED, and this tutorial's launcher exits with status 1 after printing the error. A plugin should also reject schema-valid config that names an unavailable resource or provider as soon as it can resolve that reference.
+
+## Computed config values
+
+The loader used in this repo supports a `!!js` tag for config values that must be computed at load time:
+
+```yaml
+- name: './config-demo.ts'
+  config:
+    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
+```
+
+`!!js` works only inside `config` and in an entry's `disabled` field. `disabled: !!js ...` evaluates against the loader context at every mount decision (this repo's extension), so a row can gate itself on platform or environment; the other metadata (`name`, `id`, `inject`, ...) stays static, where an expression is ordinary truthy data. See [loader configuration](../cordis-primer.md#loader-configuration).
+
+Next: [Composition and HMR](06-composition-and-hmr.md) — treating `cordis.yml` as the application.
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/05-config.zh.md

@@ -0,0 +1,84 @@
+# 5. 配置
+
+[English](05-config.md) | 中文
+
+`cordis.yml` 中的每个 Cordis 配置项都可以携带 `config` 块，插件则声明一个 schema，在运行 `apply` 前验证该块。错误配置会导致加载失败，并给出准确的错误：插件绝不会在配置不完整时启动。
+
+## 可配置插件
+
+创建 `config-demo.ts`，并将其放在 `tmp/cordis-tutorial` 中：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+
+export const name = 'config-demo'
+
+export interface Config {
+  greeting: string
+  targets: string[]
+}
+
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello'),
+  targets: Schema.array(String).default(['world']),
+})
+
+export function apply(ctx: Context, config: Config) {
+  for (const target of config.targets) {
+    console.log(`${config.greeting}, ${target}!`)
+  }
+}
+```
+
+导出的 `Config` 既是 TypeScript 接口，也是同名的运行时 schema：消费方获得类型，Cordis 获得验证器。本仓库使用 [Schemastery](https://github.com/shigma/schemastery) 定义 schema；Cordis 本身接受任意 [Standard Schema](https://standardschema.dev/) 验证器，因此将普通对象导出为 `Config` 无法工作。
+
+对其进行配置：
+
+```yaml
+- name: './config-demo.ts'
+  config:
+    targets: ['alpha', 'beta']
+```
+
+运行：
+
+```
+Hello, alpha!
+Hello, beta!
+```
+
+未提供 `greeting`，因此 schema 默认值会将其补齐：`apply` 始终会收到完整且经过验证的配置。
+
+## 明确报错
+
+现在向它传入无效内容：
+
+```yaml
+- name: './config-demo.ts'
+  config:
+    targets: 'not-an-array'
+```
+
+```
+ValidationError: invalid config:
+  - $.targets expected array but got not-an-array (at targets)
+```
+
+插件的 fiber 进入 FAILED 状态，本教程的启动器打印错误后以状态码 1 退出。如果某个插件的配置通过了 schema 验证，但其中指定的资源或提供方不可用，该插件也应当在能解析该引用时立即拒绝。
+
+## 计算得到的配置值
+
+本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值：
+
+```yaml
+- name: './config-demo.ts'
+  config:
+    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
+```
+
+`!!js` 仅在 `config` 与条目 `disabled` 字段内有效。`disabled: !!js ...` 在每次挂载决策时基于 loader 上下文求值（本仓库的扩展），可以按平台或环境门控一行；其余元数据（`name`、`id`、`inject` 等）保持静态，其中的表达式是普通真值数据。详见 [loader 配置](../cordis-primer.md#loader-configuration)。
+
+下一章：[组合与 HMR（热模块替换）](06-composition-and-hmr.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)

package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/cordis-tutorial/06-composition-and-hmr.md
+06-composition-and-hmr.md: 2b53aa28be99851e77a71de76337f2beb4003e8d
+06-composition-and-hmr.zh.md: cd4afa1d5465a5442bfd6b771ebcd61c46fe2983

package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.md

@@ -0,0 +1,113 @@
+# 6. Composition and HMR
+
+English | [中文](06-composition-and-hmr.zh.md)
+
+Every capability built so far is a plugin, and `cordis.yml` selects the application's plugin tree. This chapter changes that composition, hot-reloads a plugin, and diagnoses a plugin that never loads.
+
+## Entries are more than a name
+
+A config entry accepts metadata beyond `name` and `config`:
+
+```yaml
+- id: greeter          # stable identity for this entry
+  name: './greeter.ts'
+- id: consumer
+  name: './consumer.ts'
+  disabled: true       # keep the entry, skip mounting it
+```
+
+`id` gives the entry a stable identity so the loader can tell an edit to an existing entry apart from a removal plus an addition. `disabled: true` unmounts a plugin without deleting its entry — flip it back and the plugin (and everything PENDING on its services) loads again.
+
+Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently configured `shell` provider without affecting each other. The [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
+
+## Hot module replacement
+
+Because unloading releases effects ([chapter 2](02-lifecycle-and-effects.md)) and loading follows dependencies ([chapter 3](03-services.md)), HMR can replace a running plugin by unloading and loading it. The `@deepseek-ai/cordis-plugin-hmr` plugin watches your files and does exactly that on save.
+
+In `tmp/cordis-tutorial`, write `cordis.yml`:
+
+```yaml
+- id: logger
+  name: '@deepseek-ai/cordis-plugin-logger-console'
+- id: timer
+  name: '@deepseek-ai/cordis-plugin-timer'
+- id: hmr
+  name: '@deepseek-ai/cordis-plugin-hmr'
+  config:
+    root: ['.']
+- id: hello
+  name: './hello.ts'
+```
+
+Two support plugins joined the list: HMR logs through the Cordis logger service, so without a console exporter you would not see its messages, and it `inject`s the `timer` service for debouncing — without `@deepseek-ai/cordis-plugin-timer` it sits in PENDING forever, silently. That silence is the subject of the next section.
+
+HMR reads Node's loader internals through the Loader's native helper. Run Cordis under tsx:
+
+```sh
+node --import tsx ../../vendor/cordis/bin.js
+```
+
+Now edit `hello.ts` — change the log message — and save:
+
+```
+hello from my first plugin
+2026-07-22 15:44:36 [I] hmr watching [ '.' ]
+2026-07-22 15:44:39 [I] hmr reload plugin at hello.ts
+hello from my EDITED plugin
+```
+
+The old instance unloaded (all its effects unwound), the new code loaded, `apply` ran again. Stop the process with Ctrl-C. Editing `cordis.yml` itself is also picked up: the loader diffs entries by `id` and mounts, unmounts, or reconfigures only what changed. This is why the entries above carry explicit `id`s — an entry without one gets a generated id on every read, so after any config-file edit it counts as removed-plus-added and remounts even if its own lines did not change.
+
+## Diagnosing a plugin that never loads
+
+The flip side of dependency-driven loading: a plugin whose `inject` names a service nobody provides waits forever, printing nothing. No error — PENDING is a legitimate state, since the provider may be mounted later.
+
+You can see the states directly. Every context can enumerate the plugin registry; create `diagnose.ts`:
+
+```ts
+import { FiberState, type Context } from '@deepseek-ai/cordis'
+
+export const name = 'diagnose'
+
+export function apply(ctx: Context) {
+  setTimeout(() => {
+    for (const runtime of ctx.registry.values()) {
+      for (const fiber of runtime.fibers) {
+        if (fiber.state === FiberState.PENDING) {
+          console.log(`${fiber.name} is PENDING — a required service is missing`)
+        }
+      }
+    }
+  }, 500)
+}
+```
+
+And a plugin with an unsatisfiable dependency, `needs-timer.ts`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'needs-timer'
+export const inject = ['timer']
+
+export function apply(ctx: Context) {
+  console.log('needs-timer loaded')
+}
+```
+
+```yaml
+- name: './needs-timer.ts'
+- name: './diagnose.ts'
+```
+
+Run it (plain `node --import tsx ../../vendor/cordis/bin.js`; stop with Ctrl-C):
+
+```
+needs-timer is PENDING — a required service is missing
+```
+
+`inject: ['timer']` has no provider. Add `- name: '@deepseek-ai/cordis-plugin-timer'` to the list and the plugin loads. When a plugin does nothing and reports nothing, inspect its fiber state. Iterating without the PENDING filter also shows the loader's own plugins (Loader, Include) as ACTIVE fibers because plugins mount the config file itself.
+
+Next: [Into the harness](07-into-the-harness.md) — the same patterns against real harness services.
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.zh.md

@@ -0,0 +1,113 @@
+# 6. 组合与 HMR（热模块替换）
+
+[English](06-composition-and-hmr.md) | 中文
+
+到目前为止构建的每项能力都是插件，`cordis.yml` 则选择应用的插件树。本章会改变这种组合、热重载一个插件，并诊断始终无法加载的插件。
+
+## Cordis 配置项不只有名称
+
+Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
+
+```yaml
+- id: greeter          # stable identity for this entry
+  name: './greeter.ts'
+- id: consumer
+  name: './consumer.ts'
+  disabled: true       # keep the entry, skip mounting it
+```
+
+`id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
+
+组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `shell` 提供方，互不影响。[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
+
+## 热模块替换
+
+卸载会释放 effect（[第 2 章](02-lifecycle-and-effects.md)），加载则遵循依赖关系（[第 3 章](03-services.md)），因此 HMR 可以先卸载、再加载，以替换正在运行的插件。`@deepseek-ai/cordis-plugin-hmr` 插件会监视文件，并在保存时执行这一过程。
+
+在 `tmp/cordis-tutorial` 中编写 `cordis.yml`：
+
+```yaml
+- id: logger
+  name: '@deepseek-ai/cordis-plugin-logger-console'
+- id: timer
+  name: '@deepseek-ai/cordis-plugin-timer'
+- id: hmr
+  name: '@deepseek-ai/cordis-plugin-hmr'
+  config:
+    root: ['.']
+- id: hello
+  name: './hello.ts'
+```
+
+列表中增加了两个辅助插件：HMR 通过 Cordis logger 服务记录日志，因此没有控制台导出器时看不到其消息；它还会 `inject` `timer` 服务来实现去抖，如果没有 `@deepseek-ai/cordis-plugin-timer`，它就会永远停在 PENDING，而且不发出任何提示。下一节就讨论这种静默状态。
+
+HMR 通过 Loader 的原生辅助工具读取 Node 的 loader 内部结构。请在 tsx 下运行 Cordis：
+
+```sh
+node --import tsx ../../vendor/cordis/bin.js
+```
+
+现在编辑 `hello.ts`，修改日志消息并保存：
+
+```
+hello from my first plugin
+2026-07-22 15:44:36 [I] hmr watching [ '.' ]
+2026-07-22 15:44:39 [I] hmr reload plugin at hello.ts
+hello from my EDITED plugin
+```
+
+旧实例先卸载（其所有 effect 都会回卷），新代码随后加载，`apply` 再次运行。按 Ctrl-C 停止进程。编辑 `cordis.yml` 本身也会触发更新：loader 按 `id` 比较 Cordis 配置项，只挂载、卸载或重新配置发生变化的部分。这就是上述 Cordis 配置项显式携带 `id` 的原因：不带该字段的 Cordis 配置项在每次读取时都会获得一个新生成的 id，所以只要配置文件发生任何编辑，即使自身文本未变，它也会被视为先删除再添加并重新挂载。
+
+## 诊断始终无法加载的插件
+
+依赖驱动加载也有另一面：如果插件的 `inject` 指定了无人提供的服务，它就会一直等待，不输出任何内容。这不是错误，因为 PENDING 是合法状态，提供方可能稍后才挂载。
+
+你可以直接查看这些状态。每个上下文都能枚举插件注册表；创建 `diagnose.ts`：
+
+```ts
+import { FiberState, type Context } from '@deepseek-ai/cordis'
+
+export const name = 'diagnose'
+
+export function apply(ctx: Context) {
+  setTimeout(() => {
+    for (const runtime of ctx.registry.values()) {
+      for (const fiber of runtime.fibers) {
+        if (fiber.state === FiberState.PENDING) {
+          console.log(`${fiber.name} is PENDING — a required service is missing`)
+        }
+      }
+    }
+  }, 500)
+}
+```
+
+再创建一个依赖无法满足的插件 `needs-timer.ts`：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'needs-timer'
+export const inject = ['timer']
+
+export function apply(ctx: Context) {
+  console.log('needs-timer loaded')
+}
+```
+
+```yaml
+- name: './needs-timer.ts'
+- name: './diagnose.ts'
+```
+
+运行它（直接执行 `node --import tsx ../../vendor/cordis/bin.js`，按 Ctrl-C 停止）：
+
+```
+needs-timer is PENDING — a required service is missing
+```
+
+`inject: ['timer']` 没有提供方。向列表添加 `- name: '@deepseek-ai/cordis-plugin-timer'` 后，插件就会加载。如果插件既不执行任何操作，也不报告任何内容，请检查其 fiber 状态。不加 PENDING 过滤条件进行迭代时，还会看到 loader 自身的插件（Loader、Include）处于 ACTIVE，因为配置文件本身也是通过插件挂载的。
+
+下一章：[进入 harness](07-into-the-harness.md)：把相同模式用于真实的 harness 服务。
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/cordis-tutorial/07-into-the-harness.md
+07-into-the-harness.md: 2d3c23f9f7f7fc6bd6cabd4e7e68ebfc46e20665
+07-into-the-harness.zh.md: 45dc0ee6f07ab3b0275499cd4ab0c436eebdddef

package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.md

@@ -0,0 +1,107 @@
+# 7. Into the harness
+
+English | [中文](07-into-the-harness.zh.md)
+
+This chapter registers a model-callable tool with the harness's `tools` service, executes it through the harness tool pipeline, and observes the result event. It remains keyless and does not call a model.
+
+## A tool plugin
+
+Create `greet-tool.ts` in `tmp/cordis-tutorial`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { CallId } from '@deepseek-ai/dsh-llm'
+
+export const name = 'greet-tool'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  ctx.tools.register(defineTool({
+    name: 'greet',
+    description: 'Greet the named person.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'Who to greet' },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) {
+      return `Hello, ${args.name}!`
+    },
+  }))
+
+  // Drive one call through the real execution pipeline, standing in for
+  // the model. CallId brands the correlation id a provider would issue.
+  void (async () => {
+    const result = await ctx.tools.execute({
+      callId: CallId('demo-1'),
+      name: 'greet',
+      arguments: { name: 'Cordis' },
+      signal: new AbortController().signal,
+    })
+    console.log('tool replied:', JSON.stringify(result.content))
+  })()
+}
+```
+
+Every pattern here is from the earlier chapters: `inject: ['tools']` ([chapter 3](03-services.md)) holds the plugin until the tool registry exists; `ctx.tools.register(...)` attaches the registration disposer to the plugin ([chapter 2](02-lifecycle-and-effects.md)), so unloading unregisters the tool. `defineTool` converts the `parameters` spec to the JSON Schema shown to the model, infers the type of `args`, and validates model-supplied arguments before `execute` runs. The tool returns the canonical value declared by `output.schema`; `output.render` separately produces the Native and durable result content.
+
+## An observer plugin
+
+Create `tool-logger.ts` — a separate plugin that watches every tool call in the app through the harness's `tools/result` event:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-tools'
+
+export const name = 'tool-logger'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  ctx.on('tools/result', (exec, result) => {
+    const text = result.content
+      .map(block => (block.type === 'text' ? block.text : ''))
+      .join('')
+    console.log(`[tool-logger] ${exec.name} -> ${text}`)
+  })
+}
+```
+
+The `import type {} from '@deepseek-ai/dsh-tools'` line pulls in the package's declaration merges so `'tools/result'` and its payload are typed — the same move as chapter 4's `stats.ts` import, at package scale.
+
+## Compose and run
+
+```yaml
+- name: '@deepseek-ai/dsh-system-prompt'
+- name: '@deepseek-ai/dsh-tools'
+- name: './tool-logger.ts'
+- name: './greet-tool.ts'
+```
+
+`@deepseek-ai/dsh-tools` injects the `systemPrompt` service because tools contribute schemas to the system prompt, so the composition lists its provider too. Without it, the tools plugin remains PENDING as described in [chapter 6](06-composition-and-hmr.md).
+
+```sh
+node --import tsx ../../vendor/cordis/bin.js
+```
+
+```
+[tool-logger] greet -> Hello, Cordis!
+tool replied: [{"type":"text","text":"Hello, Cordis!"}]
+```
+
+The logger fired first: `tools/result` is emitted as part of result materialization, before `execute`'s promise resolves to the caller. Neither of your plugins knows the other exists — the registry service and the event connect them.
+
+## From here to a full agent
+
+A real agent is this composition plus more plugins: an LLM adapter, the agent loop, persistence, an entry point. Compare [examples/headless-agent/cordis.yml](../../examples/headless-agent/cordis.yml) — you can read every entry in it now. Add your `greet-tool.ts` to a copy of that file.
+
+Where to go next:
+
+- [Build a tool](../user/develop/basic/tool.md) — more of `defineTool`, including presentation and richer schemas.
+- [Three-layer capability design](../user/develop/practice/index.md) — how the harness structures replaceable capabilities.
+- The generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) — everything you can inject and listen to, each on its owning page.
+- [Architecture](../architecture.md) — the system map these plugins live in.
+
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)