dsh-plugin-guide 0.1.0

package/references/official-docs/docs/cordis-api/registry.zh.md

@@ -0,0 +1,154 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/registry.md` 重新记录配对。 -->
+
+# 注册表
+
+[English](registry.md) | 中文
+
+插件加载与依赖注入。
+
+### ctx.inject(deps, callback)
+
+```ts cordis-catalog
+/**
+ * Run a callback once the requested services are available.
+ *
+ * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
+ * is unloaded and re-run whenever a required service changes.
+ *
+ * @param deps — required services, as an array or a name → config map.
+ * @param callback — plugin body called with `(ctx, config)`.
+ * @returns the fiber; awaiting it settles once loading finished.
+ */
+inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
+```
+
+请求的服务可用后，运行回调。
+
+这是 `ctx.plugin({ inject, apply: callback })` 的简写形式：每当某个必需服务发生变化时，系统都会卸载并重新运行该回调。
+
+- `deps`：必需服务，形式可以是数组，也可以是从名称到配置的映射。
+- `callback`：以 `(ctx, config)` 调用的插件主体。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待。
+
+[源码](../../vendor/cordis/src/registry.ts#L176)
+
+### ctx.plugin(plugin, ...args)
+
+```ts cordis-catalog
+/**
+ * Load a plugin in the current context.
+ *
+ * @param plugin — a function, class, or `{ apply }` object plugin.
+ * @param args — the plugin config, validated against its `Config` schema.
+ * @returns the fiber; awaiting it settles once loading finished
+ * (rejecting on config or startup errors).
+ */
+plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
+```
+
+在当前上下文中加载插件。
+
+- `plugin`：函数、类或 `{ apply }` 对象形式的插件。
+- `args`：插件配置，会根据其 `Config` schema 进行校验。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待（如果发生配置错误或启动错误，则会被拒绝）。
+
+[源码](../../vendor/cordis/src/registry.ts#L185)
+
+## Plugin
+
+支持的插件入口点形式。
+
+```ts cordis-catalog
+/** Supported plugin entrypoint shapes. */
+type Plugin<T = any> =
+  | Plugin.Function<T>
+  | Plugin.Constructor<T>
+  | Plugin.Object<T>
+
+/** Types associated with plugin entrypoints and runtime records. */
+namespace Plugin {
+  /** Shared metadata understood by the plugin registry and related tooling. */
+  export interface Base<T = any> {
+    /** Display name used for fiber diagnostics and logger names. */
+    name?: string
+    /** Standard-schema validator applied to config before the plugin starts. */
+    Config?: StandardSchemaV1<any, T>
+    /** Services the plugin requires; it only loads while all are available. */
+    inject?: Inject
+    /** Service name(s) the plugin provides (read by `Service` and by loaders). */
+    provide?: string | string[]
+    /** Service names whose intercept config the plugin declares it consumes. */
+    intercept?: Dict<boolean>
+  }
+
+  export interface Transform<S, T> {
+    /** Marks the transform object as a schema/config transform. */
+    schema?: true
+    /** Convert user-facing config to runtime config. */
+    Config: (config: S) => T
+  }
+
+  /** Function plugin called with `(ctx, config)`. */
+  export interface Function<T = any> extends Base<T> {
+    (ctx: Context, config: T): any
+  }
+
+  /** Class plugin constructed with `(ctx, config)`. */
+  export interface Constructor<T = any> extends Base<T> {
+    new (ctx: Context, config: T): any
+  }
+
+  /** Object plugin with an `apply(ctx, config)` method. */
+  export interface Object<T = any> extends Base<T> {
+    apply(ctx: Context, config: T): any
+  }
+
+  /** Mutable registry record shared by all fibers of one plugin callback. */
+  export interface Runtime {
+    /** Display name copied from the first registered plugin shape. */
+    name?: string
+    /** Every live fiber of this plugin (one per `ctx.plugin()` call). */
+    fibers: DisposableList<Fiber>
+    /** The executable entrypoint all fibers share (registry identity key). */
+    callback: globalThis.Function
+    /** Standard-schema validator applied to each fiber's config. */
+    Config?: StandardSchemaV1
+  }
+}
+```
+
+[源码](../../vendor/cordis/src/registry.ts#L92)
+
+## Inject
+
+插件和 `@Inject` 装饰器接受的服务依赖声明。
+
+数组形式请求不带拦截配置的服务。对象形式将每个服务名称映射到插件上下文中可选的拦截配置。
+
+```ts cordis-catalog
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
+type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
+
+/** Utilities for normalizing plugin dependency declarations. */
+namespace Inject {
+  /**
+   * Convert array/object/class-inherited inject metadata into a plain map.
+   *
+   * @param inject — the declaration to normalize; `null`/`undefined` add nothing.
+   * @param result — the map to fill (service name → intercept config or `null`).
+   * @returns `result`.
+   */
+  export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
+}
+```
+
+[源码](../../vendor/cordis/src/registry.ts#L19)

package/references/official-docs/docs/cordis-api/service.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-api/service.md
+service.md: d4b0f06da16decf31e0d348a88e0360b46ee9d35
+service.zh.md: ec0b443a0eae2787e0a3db919583d8092414c52d

package/references/official-docs/docs/cordis-api/service.md

@@ -0,0 +1,102 @@
+<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
+     Run `pnpm run gen-cordis-catalog` to regenerate. -->
+
+# Service
+
+The base class for context services. A subclass loaded as a plugin registers itself as `ctx.<name>`.
+
+Base class for services that expose a named API on `ctx`.
+
+Subclasses call `super(ctx, name)` from their constructor. The service is registered immediately and is automatically removed with the owning fiber.
+
+[Source](../../vendor/cordis/src/service.ts#L11)
+
+### service.name
+
+```ts cordis-catalog
+/** The service name this instance is registered under. */
+public name!: string
+```
+
+The service name this instance is registered under.
+
+[Source](../../vendor/cordis/src/service.ts#L30)
+
+## Static members
+
+### Service.init
+
+```ts cordis-catalog
+/** Symbol key of an instance method run after construction (class plugins). */
+static readonly init: unique symbol
+```
+
+Symbol key of an instance method run after construction (class plugins).
+
+[Source](../../vendor/cordis/src/service.ts#L13)
+
+### Service.check
+
+```ts cordis-catalog
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
+static readonly check: unique symbol
+```
+
+Symbol key of the availability predicate passed to `ctx.provide()`.
+
+[Source](../../vendor/cordis/src/service.ts#L15)
+
+### Service.config
+
+```ts cordis-catalog
+/** Symbol key of the phantom intercept-config type parameter. */
+static readonly config: unique symbol
+```
+
+Symbol key of the phantom intercept-config type parameter.
+
+[Source](../../vendor/cordis/src/service.ts#L17)
+
+### Service.invoke
+
+```ts cordis-catalog
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+static readonly invoke: unique symbol
+```
+
+Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
+
+[Source](../../vendor/cordis/src/service.ts#L19)
+
+### Service.extend
+
+```ts cordis-catalog
+/** Symbol key of the helper deriving an extended service instance. */
+static readonly extend: unique symbol
+```
+
+Symbol key of the helper deriving an extended service instance.
+
+[Source](../../vendor/cordis/src/service.ts#L21)
+
+### Service.tracker
+
+```ts cordis-catalog
+/** Symbol key of the tracker metadata used for context tracing. */
+static readonly tracker: unique symbol
+```
+
+Symbol key of the tracker metadata used for context tracing.
+
+[Source](../../vendor/cordis/src/service.ts#L23)
+
+### Service.resolveConfig
+
+```ts cordis-catalog
+/** Symbol key of the intercept-config resolution helper below. */
+static readonly resolveConfig: unique symbol
+```
+
+Symbol key of the intercept-config resolution helper below.
+
+[Source](../../vendor/cordis/src/service.ts#L25)

package/references/official-docs/docs/cordis-api/service.zh.md

@@ -0,0 +1,104 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/service.md` 重新记录配对。 -->
+
+# Service
+
+[English](service.md) | 中文
+
+上下文服务的基类。以插件形式加载的子类会将自身注册为 `ctx.<name>`。
+
+用于在 `ctx` 上公开具名 API 的服务基类。
+
+子类在构造函数中调用 `super(ctx, name)`。服务会立即注册，并随所属 fiber 自动移除。
+
+[源码](../../vendor/cordis/src/service.ts#L11)
+
+### service.name
+
+```ts cordis-catalog
+/** The service name this instance is registered under. */
+public name!: string
+```
+
+此实例注册时使用的服务名称。
+
+[源码](../../vendor/cordis/src/service.ts#L30)
+
+## 静态成员
+
+### Service.init
+
+```ts cordis-catalog
+/** Symbol key of an instance method run after construction (class plugins). */
+static readonly init: unique symbol
+```
+
+构造完成后运行的实例方法所使用的符号键（类插件）。
+
+[源码](../../vendor/cordis/src/service.ts#L13)
+
+### Service.check
+
+```ts cordis-catalog
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
+static readonly check: unique symbol
+```
+
+传给 `ctx.provide()` 的可用性谓词所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L15)
+
+### Service.config
+
+```ts cordis-catalog
+/** Symbol key of the phantom intercept-config type parameter. */
+static readonly config: unique symbol
+```
+
+虚设拦截配置类型参数所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L17)
+
+### Service.invoke
+
+```ts cordis-catalog
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+static readonly invoke: unique symbol
+```
+
+使服务可被调用的调用体所使用的符号键（例如 `ctx.logger()`）。
+
+[源码](../../vendor/cordis/src/service.ts#L19)
+
+### Service.extend
+
+```ts cordis-catalog
+/** Symbol key of the helper deriving an extended service instance. */
+static readonly extend: unique symbol
+```
+
+用于派生扩展服务实例的辅助方法所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L21)
+
+### Service.tracker
+
+```ts cordis-catalog
+/** Symbol key of the tracker metadata used for context tracing. */
+static readonly tracker: unique symbol
+```
+
+上下文追踪所用跟踪器元数据的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L23)
+
+### Service.resolveConfig
+
+```ts cordis-catalog
+/** Symbol key of the intercept-config resolution helper below. */
+static readonly resolveConfig: unique symbol
+```
+
+下述拦截配置解析辅助方法所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L25)

package/references/official-docs/docs/cordis-primer.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-primer.md
+cordis-primer.md: 2a3afe180623d89b006dfa3e73aba5567c15bbe9
+cordis-primer.zh.md: d4d60f60717ffdc01499fdffadba2808557b285f

package/references/official-docs/docs/cordis-primer.md

@@ -0,0 +1,44 @@
+# Cordis Primer
+
+English | [中文](cordis-primer.zh.md)
+
+Cordis is the vendored plugin framework underneath DeepSeek Harness. This primer teaches the Cordis ideas a harness plugin author needs before reading the generated service/event reference on the [subsystem pages](subsystems/core.md); the [Cordis tutorial](cordis-tutorial/index.md) walks the same ideas hands-on. The vendored source and sync procedure live in [vendor/README.md](../vendor/README.md).
+
+## Cordis In Five Ideas
+
+- **A plugin is a object that implements Service.** It can be a function with optional `inject` and `apply(ctx)` fields, or a `Service` subclass whose lifecycle Cordis mounts into the current context.
+- **A context is a repository of services.** A service claims a stable `ctx.<key>` such as `ctx.tools`, `ctx.llm`, or `ctx.sessions` from a context; other plugins find services via key instead of importing a concrete implementation.
+- **Declare service dependency via `inject`.** A plugin that names required services waits until those services exist, so load order is expressed through service requirements rather than manual boot sequencing.
+- **Typed Events for communication.** Services declare event names through TypeScript declaration merging, then dispatch them as `emit`, `waterfall`, `parallel`, or `serial` depending on whether listeners observe, wrap, fan out, or run in order.
+- **Registrations are reversible effects.** Prompt sections, tool schemas, adapters, providers, and listeners are installed through `ctx.effect()` or `ctx.on()` so reload and teardown unwind them predictably.
+
+## Dispatch Modes
+
+Every event can have one of the following dispatch mode and can only be dispatched by these methods accordingly.
+
+| Mode | Awaited? | Dispatch Order | Has Return Value? |
+|---|---|---|---|
+| `emit` | No | listeners observe in registration order | No |
+| `waterfall` | No | listeners observe in registration order | Yes |
+| `parallel` | Yes | all listeners observe the event in parallel | No |
+| `serial` | Yes | listeners observe in registration order | Yes |
+
+The dispatch mode is part of the event's public contract. New harness events document it with an `@mode` tag so the generated catalog can check declarations against dispatch sites.
+
+## Cordis Waterfall Semantics
+
+`ctx.waterfall` is around-middleware. A listener receives `(...args, next)`. Call `next()` to delegate the possibly wrapped result to the next service; return without `next()` to short-circuit. Values propagate through `next()`'s return value.
+
+Cooperative listeners usually mutate a shared request or decision object and then delegate. A listener can also choose to replace the result entirely and downstream listeners will only see the result after replacement. Use `prepend: true` only when the listener must run before ordinary registrations.
+
+For single-decision events, short-circuiting is the design. A policy listener can return without `next()` when it owns the decision, while a listener that only annotates or observes must delegate.
+
+## Loader Configuration
+
+`@deepseek-ai/cordis-plugin-include` parses `!!js` into expression nodes. Loader interpolates an entry's `config` (after declared injections activate, against that plugin context — `ctx.serviceName`) and its `disabled` field (at every mount decision, against the loader context); Include preserves nested row expressions until target activation. Other entry metadata stays literal. Use overlays when the environment selects plugins.
+
+## Practical Rules
+
+Encapsulate behavior into plugins: a tool pipeline event belongs to `ctx.tools`, model streaming belongs to `ctx.llm`, and live agent coordination belongs to `ctx.agents`. Prefer events for interception and policy; prefer service methods for direct capability calls.
+
+Every registration should have a disposer, either by returning one from `ctx.effect()` or using a Cordis helper that does it for you. If teardown order matters, keep the related work in one effect so disposal unwinds in the intended sequence.

package/references/official-docs/docs/cordis-primer.zh.md

@@ -0,0 +1,50 @@
+# Cordis 入门
+
+[English](cordis-primer.md) | 中文
+
+Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读[子系统页面](subsystems/core.md)上生成的服务/事件参考之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](../vendor/README.md)。
+
+## 五个核心概念
+
+- **插件是实现 Service 的对象。** 它可以是一个带有可选 `inject` 和 `apply(ctx)` 字段的函数，也可以是一个 `Service` 子类，其生命周期由 Cordis 挂载到当前上下文中。
+- **上下文是服务的容器。** 一个服务占据一个稳定的 `ctx.<key>`（如 `ctx.tools`、`ctx.llm`、`ctx.sessions`）；其他插件通过 key 查找服务，而非导入具体实现。
+- **通过 `inject` 声明服务依赖。** 插件声明所需的服务后，会等待这些服务就绪才启动；加载顺序通过服务依赖表达，而非手动编排启动序列。
+- **类型化事件用于通信。** 服务通过 TypeScript 声明合并注册事件名，然后以 `emit`、`waterfall`（瀑布式事件）、`parallel` 或 `serial` 方式分发，分别对应监听者观察、包装、并行扇出或按序执行。
+- **注册是可逆的副作用。** 提示词片段、工具 schema、适配器、提供方和监听器通过 `ctx.effect()` 或 `ctx.on()` 安装，reload 和 teardown 时会按预期撤销。
+
+<a id="dispatch-modes"></a>
+
+## 分发模式
+
+每个事件具有以下分发模式之一，且只能通过对应方法分发。
+
+| 模式 | 是否 await？ | 分发顺序 | 是否有返回值？ |
+|---|---|---|---|
+| `emit` | 否 | 监听器按注册顺序观察 | 否 |
+| `waterfall` | 否 | 监听器按注册顺序观察 | 是 |
+| `parallel` | 是 | 所有监听器并行观察事件 | 否 |
+| `serial` | 是 | 监听器按注册顺序观察 | 是 |
+
+分发模式是事件公开约定的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
+
+<a id="cordis-waterfall-semantics"></a>
+
+## Cordis Waterfall 语义
+
+`ctx.waterfall` 是环绕中间件。监听器接收 `(...args, next)`。调用 `next()` 会执行下游监听器；下游返回值通过 `next()` 返回当前包装层，可由该层包装后继续向外返回。不调用 `next()` 直接返回则短路。
+
+协作式监听器通常修改一个共享的请求或决策对象，然后委托。监听器也可以选择完全替换结果，下游监听器将只看到替换后的结果。仅当监听器必须在普通注册之前运行时才使用 `prepend: true`。
+
+对于单决策事件，短路是设计意图。策略监听器在拥有决策权时可以不调用 `next()` 直接返回，而仅做标注或观察的监听器则必须委托。
+
+<a id="loader-configuration"></a>
+
+## Loader 配置
+
+`@deepseek-ai/cordis-plugin-include` 将 `!!js` 解析为表达式节点。Loader 在声明的注入激活后，基于该插件上下文（`ctx.serviceName`）插值条目的 `config`，并在每次挂载决策时基于 loader 上下文插值其 `disabled` 字段；Include 会保留嵌套行表达式，直到目标行激活。其余条目元数据保持字面值。由环境选择插件时，请使用 overlay。
+
+## 实践规则
+
+将行为封装为插件：工具流水线事件属于 `ctx.tools`，模型流式输出属于 `ctx.llm`，实时 agent（智能体）协调属于 `ctx.agents`。拦截和策略优先使用事件；直接能力调用优先使用服务方法。
+
+每个注册都应有对应的 disposer（资源释放函数）：要么从 `ctx.effect()` 返回一个，要么使用 Cordis 提供的辅助方法自动处理。如果 teardown 顺序有要求，请将相关工作放在同一个 effect 中，以确保资源按预期顺序释放。

package/references/official-docs/docs/cordis-tutorial/01-first-plugin.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/01-first-plugin.md
+01-first-plugin.md: 79df2f42df1f34a7ef32cc81607e1b926a1854ae
+01-first-plugin.zh.md: 87cd7a96843d69d68fb95662e59bbfb9ebfc2a37

package/references/official-docs/docs/cordis-tutorial/01-first-plugin.md

@@ -0,0 +1,95 @@
+# 1. Your first plugin
+
+English | [中文](01-first-plugin.zh.md)
+
+In the loader configuration used here, a Cordis plugin module named-exports an `apply` function. When Cordis loads it, it calls `apply` with a **context** — the `ctx` object through which the plugin registers everything it contributes.
+
+## Write the plugin
+
+In your `tmp/cordis-tutorial` directory (see [setup](index.md#setup)), create `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')
+}
+```
+
+The `name` export is optional display metadata; it labels the plugin in diagnostics.
+
+## Compose the app
+
+This tutorial's launcher assembles the application from configuration. Create `cordis.yml`:
+
+```yaml
+- name: './hello.ts'
+```
+
+The file is a list of plugin entries. `name` is a module specifier — a relative path or an npm package name — and the loader mounts every entry. Entries start concurrently, so list position guarantees nothing about which plugin loads first; ordering comes from service dependencies (`inject`, [chapter 3](03-services.md)), not from position in the file.
+
+## Run it
+
+```sh
+node --import tsx ../../vendor/cordis/bin.js
+```
+
+Expected output:
+
+```
+hello from my first plugin
+```
+
+The process exits on its own once nothing is left running. What happened:
+
+1. The launcher created a root `Context` and mounted the **Loader** plugin.
+2. The Loader read `cordis.yml`, resolved `./hello.ts`, and mounted it as a child plugin.
+3. Cordis called your `apply(ctx)`.
+
+There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application. The [`dsh` base](../../packages/bundle/base/cordis.patch.yml), for example, is a longer plugin composition that deployment overlays patch.
+
+## The two other plugin shapes
+
+A function is the most common form, but Cordis accepts three:
+
+```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')
+  }
+}
+```
+
+Use the function form until you need to expose a service; [chapter 3](03-services.md) covers when the class form earns its place.
+
+## Try breaking it
+
+Make `apply` throw:
+
+```ts ignore-check
+export function apply(ctx: Context) {
+  throw new Error('apply exploded')
+}
+```
+
+Run again: the process dies with your error. A plugin that fails to load is a loud failure, not a skipped entry.
+
+One caveat worth knowing early: a config entry whose module cannot be **resolved** — a typo'd path or package name — is reported through the Cordis logger service instead of crashing the process, and at boot that report can be lost before a console exporter is watching. If a freshly added entry seems to do nothing, check the spelling first.
+
+Next: [Lifecycle and effects](02-lifecycle-and-effects.md) — what happens when a plugin unloads.
+
+[![](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/01-first-plugin.zh.md

@@ -0,0 +1,95 @@
+# 1. 编写第一个插件
+
+[English](01-first-plugin.md) | 中文
+
+在本教程使用的 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](../../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)：插件卸载时会发生什么。
+
+[![](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/02-lifecycle-and-effects.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/02-lifecycle-and-effects.md
+02-lifecycle-and-effects.md: 8e75708eb0cba1aceb7fa3dae5ae334995eb113f
+02-lifecycle-and-effects.zh.md: bc4489e702ab58b5d1efd8a72fc693ee48af2624