dsh-plugin-guide 0.3.42 → 0.4.0

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

@@ -1,154 +0,0 @@
-<!-- 英文源文件由 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

@@ -1,37 +0,0 @@
-# Bilingual-pair consistency record for service.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/cordis-api/service.md
-/:
-  en: d2c0c5bce430d1be
-  zh: 124ab2656ea6d044
-/service:
-  en: a163fe605c4a8045
-  zh: 060a6f4ce086c5c2
-/service/service-name:
-  en: 32a75e66b17c0b79
-  zh: 0a5ff9fc45b3bea0
-/service/static-members:
-  en: ceb197529207a8ed
-  zh: 7d444c03f8be0f0d
-/service/static-members/service-init:
-  en: ade1a1c4543fac8c
-  zh: b7a4b616ee930b5b
-/service/static-members/service-check:
-  en: 111351ada5972a9a
-  zh: 1537da7793a6a02c
-/service/static-members/service-config:
-  en: 93d8ff69722f9b46
-  zh: 9ba1532d164c2231
-/service/static-members/service-invoke:
-  en: 6d87f35f8cf52b05
-  zh: 278dbce6025b2834
-/service/static-members/service-extend:
-  en: 5b78b68d8de8cef9
-  zh: 6df27f37da11a104
-/service/static-members/service-tracker:
-  en: 52071ebded7ec026
-  zh: 4647fa3f989b5deb
-/service/static-members/service-resolveconfig:
-  en: ad62f59468d1a765
-  zh: 4a31b52f61e1af6e

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

@@ -1,102 +0,0 @@
-<!-- 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

@@ -1,104 +0,0 @@
-<!-- 英文源文件由 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

@@ -1,22 +0,0 @@
-# Bilingual-pair consistency record for cordis-primer.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/cordis-primer.md
-/cordis-primer:
-  en: 065178153a059ae3
-  zh: d1c5c429a8c35ac2
-/cordis-primer/cordis-in-five-ideas:
-  en: c11cc0f2927f7bad
-  zh: 4fc01f41da6b1c3e
-/cordis-primer/dispatch-modes:
-  en: 7adc1e4cc7a7a471
-  zh: 879bf8afcd8f7c9f
-/cordis-primer/cordis-waterfall-semantics:
-  en: 34055815ef4034ee
-  zh: a7e0c9c8cf12959a
-/cordis-primer/loader-configuration:
-  en: affe2b40ba1aa67d
-  zh: 34ed011226c6488b
-/cordis-primer/practical-rules:
-  en: 94846dacd018f8a1
-  zh: 2bae19522ab2e33f

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

@@ -1,45 +0,0 @@
-# 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`, `serial`, or `bail` depending on whether listeners observe, wrap, fan out, run in order, or stop at the first bail value.
-- **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 |
-| `bail` | No | listeners observe in registration order until one bails | 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

@@ -1,51 +0,0 @@
-# Cordis 入门
-
-[English](cordis-primer.md) | 中文
-
-Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读[子系统页面](subsystems/core.zh.md)上生成的服务/事件参考之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.zh.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` 或 `bail` 方式分发，分别对应监听者观察、包装、并行扇出、按序执行或停在首个 bail 值。
-- **注册是可逆的副作用。** 提示词片段、工具 schema、适配器、提供方和监听器通过 `ctx.effect()` 或 `ctx.on()` 安装，reload 和 teardown 时会按预期撤销。
-
-<a id="dispatch-modes"></a>
-
-## 分发模式
-
-每个事件具有以下分发模式之一，且只能通过对应方法分发。
-
-| 模式 | 是否 await？ | 分发顺序 | 是否有返回值？ |
-|---|---|---|---|
-| `emit` | 否 | 监听器按注册顺序观察 | 否 |
-| `waterfall` | 否 | 监听器按注册顺序观察 | 是 |
-| `parallel` | 是 | 所有监听器并行观察事件 | 否 |
-| `serial` | 是 | 监听器按注册顺序观察 | 是 |
-| `bail` | 否 | 监听器按注册顺序观察，直到某个监听器返回 bail 值 | 是 |
-
-分发模式是事件公开约定的一部分。新的 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

@@ -1,22 +0,0 @@
-# Bilingual-pair consistency record for 01-first-plugin.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# 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
-/1-your-first-plugin:
-  en: 2b4f2febdeebdc74
-  zh: 98bc166d6cfd188a
-/1-your-first-plugin/write-the-plugin:
-  en: e2ec9e26bfd71d59
-  zh: 7c0d2b90a711ae4b
-/1-your-first-plugin/compose-the-app:
-  en: 529a55fb5ee74567
-  zh: f4b447fc0a68c0dd
-/1-your-first-plugin/run-it:
-  en: 7c55b7ecb982e94e
-  zh: dec70eb3ef18faec
-/1-your-first-plugin/the-two-other-plugin-shapes:
-  en: 39b0764924d85146
-  zh: 801fb0297e282df1
-/1-your-first-plugin/try-breaking-it:
-  en: 127d7a0916de2b66
-  zh: 86d4616c7a6aa82a

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

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