dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/cordis-tutorial/04-events.md

@@ -1,144 +0,0 @@
-# 4. Events
-
-English | [中文](04-events.zh.md)
-
-Services support direct calls; **events** let a plugin announce something without knowing which plugins listen. The harness uses events for interactions such as tool results, model requests, and approval decisions.
-
-## Declare, emit, listen
-
-Create `stats.ts` in `tmp/cordis-tutorial` — a service that counts things and announces each change:
-
-```ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    stats: StatsService
-  }
-  interface Events {
-    'stats/report'(name: string, count: number): void
-  }
-}
-
-export class StatsService extends Service {
-  private counts = new Map<string, number>()
-
-  constructor(ctx: Context) {
-    super(ctx, 'stats')
-  }
-
-  bump(name: string) {
-    const next = (this.counts.get(name) ?? 0) + 1
-    this.counts.set(name, next)
-    this.ctx.emit('stats/report', name, next)
-  }
-}
-
-export const name = 'stats'
-
-export function apply(ctx: Context) {
-  ctx.plugin(StatsService)
-}
-```
-
-The `interface Events` merge is the event-system twin of the `interface Context` merge from chapter 3: it declares the event name and its listener signature, so `ctx.emit` and `ctx.on` are fully typed. The `namespace/action` naming convention keeps the flat event namespace readable.
-
-Create `reporter.ts`:
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from './stats.ts'
-
-export const name = 'reporter'
-export const inject = ['stats']
-
-export function apply(ctx: Context) {
-  ctx.on('stats/report', (name, count) => {
-    console.log(`[stats] ${name} -> ${count}`)
-  })
-  ctx.stats.bump('tool_call')
-  ctx.stats.bump('tool_call')
-  ctx.stats.bump('prompt')
-}
-```
-
-The `import type {} from './stats.ts'` line imports nothing at runtime; it exists so TypeScript sees the declaration merges. Compose and run:
-
-```yaml
-- name: './stats.ts'
-- name: './reporter.ts'
-```
-
-```
-[stats] tool_call -> 1
-[stats] tool_call -> 2
-[stats] prompt -> 1
-```
-
-Because `ctx.on()` is an effect, the listener disappears with the plugin — no manual `removeListener` bookkeeping, ever.
-
-## Dispatch modes
-
-`emit` is one of five dispatch modes. Which one an event uses is part of its contract — it decides whether listeners can return values, run concurrently, or short-circuit each other:
-
-| Mode | Call | Semantics |
-|---|---|---|
-| emit | `ctx.emit(name, ...args)` | Synchronous broadcast; returned promises and values are not awaited or collected. |
-| parallel | `await ctx.parallel(name, ...args)` | All listeners run concurrently; awaited together. |
-| serial | `await ctx.serial(name, ...args)` | Listeners run in order, awaited; the first non-`null`/`false`/`undefined` return wins and stops the rest. |
-| bail | `ctx.bail(name, ...args)` | Synchronous version of serial. |
-| waterfall | `ctx.waterfall(name, ...args, next)` | Around-middleware; see below. |
-
-Every harness event documents its mode in the generated reference on its owning [subsystem page](../subsystems/core.md).
-
-## Waterfall: transform or short-circuit
-
-Waterfall is the mode that powers interception. Each listener receives the arguments plus a `next()` continuation; it can transform what `next()` returns, or return without calling `next()` and short-circuit the rest of the chain — what the Cordis docs call the veto. Create `waterfall-demo.ts`:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Events {
-    'demo/transform'(input: string, next: () => Promise<string>): Promise<string>
-  }
-}
-
-export const name = 'waterfall-demo'
-
-export function apply(ctx: Context) {
-  // Listener 1: wrap the downstream result.
-  ctx.on('demo/transform', async (input, next) => {
-    const downstream = await next()
-    return downstream.toUpperCase()
-  })
-
-  // Listener 2: short-circuit when it owns the decision.
-  ctx.on('demo/transform', async (input, next) => {
-    if (input.includes('blocked')) return '** blocked **'
-    return next()
-  })
-
-  void (async () => {
-    console.log(await ctx.waterfall('demo/transform', 'hello', async () => 'hello'))
-    console.log(await ctx.waterfall('demo/transform', 'blocked words', async () => 'blocked words'))
-  })()
-}
-```
-
-Point `cordis.yml` at just this file and run:
-
-```
-HELLO
-** BLOCKED **
-```
-
-Walk through the second line: listener 1 runs first, calls `next()`, which invokes listener 2; listener 2 sees `blocked` and returns without calling `next()` — the innermost default (the function passed to `ctx.waterfall`) never runs — and listener 1 uppercases the replacement message on the way out.
-
-The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. It is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
-
-The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../subsystems/core.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) lets a policy answer instead of the user.
-
-Next: [Configuration](05-config.md) — plugin options from `cordis.yml`.
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/04-events.zh.md

@@ -1,144 +0,0 @@
-# 4. 事件
-
-[English](04-events.md) | 中文
-
-服务支持直接调用；**事件**让插件无需知道有哪些插件正在监听，就能发出通知。harness 使用事件处理工具结果、模型请求和审批决定等交互。
-
-## 声明、发出与监听
-
-创建 `stats.ts`，将它放在 `tmp/cordis-tutorial` 中。它是一项负责计数并在每次变化时发出通知的服务：
-
-```ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    stats: StatsService
-  }
-  interface Events {
-    'stats/report'(name: string, count: number): void
-  }
-}
-
-export class StatsService extends Service {
-  private counts = new Map<string, number>()
-
-  constructor(ctx: Context) {
-    super(ctx, 'stats')
-  }
-
-  bump(name: string) {
-    const next = (this.counts.get(name) ?? 0) + 1
-    this.counts.set(name, next)
-    this.ctx.emit('stats/report', name, next)
-  }
-}
-
-export const name = 'stats'
-
-export function apply(ctx: Context) {
-  ctx.plugin(StatsService)
-}
-```
-
-`interface Events` 合并与第 3 章的 `interface Context` 合并在事件系统中相互对应：它声明事件名称及其监听器签名，因此 `ctx.emit` 和 `ctx.on` 都具有完整类型。`namespace/action` 命名约定让扁平的事件命名空间保持易读。
-
-创建 `reporter.ts`：
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from './stats.ts'
-
-export const name = 'reporter'
-export const inject = ['stats']
-
-export function apply(ctx: Context) {
-  ctx.on('stats/report', (name, count) => {
-    console.log(`[stats] ${name} -> ${count}`)
-  })
-  ctx.stats.bump('tool_call')
-  ctx.stats.bump('tool_call')
-  ctx.stats.bump('prompt')
-}
-```
-
-`import type {} from './stats.ts'` 行不会在运行时导入任何内容；它的作用是让 TypeScript 看到声明合并。组合并运行：
-
-```yaml
-- name: './stats.ts'
-- name: './reporter.ts'
-```
-
-```
-[stats] tool_call -> 1
-[stats] tool_call -> 2
-[stats] prompt -> 1
-```
-
-因为 `ctx.on()` 属于 effect，监听器会随插件一同消失，绝不需要手动维护 `removeListener`。
-
-## 分发模式
-
-`emit` 是 5 种分发模式之一。事件采用哪种模式是其约定的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路：
-
-| 模式 | 调用 | 语义 |
-|---|---|---|
-| emit | `ctx.emit(name, ...args)` | 同步广播；不会等待或收集返回的 promise 与值。 |
-| parallel | `await ctx.parallel(name, ...args)` | 所有监听器并发运行，并一同等待。 |
-| serial | `await ctx.serial(name, ...args)` | 监听器按顺序运行并等待；第一个非 `null`/`false`/`undefined` 返回值胜出，并停止后续监听器。 |
-| bail | `ctx.bail(name, ...args)` | serial 的同步版本。 |
-| waterfall（瀑布式事件） | `ctx.waterfall(name, ...args, next)` | 环绕中间件，见下文。 |
-
-每个 harness 事件都会在其所属[子系统页面](../subsystems/core.zh.md)自动生成的参考文档中记录其模式。
-
-## waterfall：转换或短路
-
-waterfall 是实现拦截的模式。每个监听器都会收到参数和一个 `next()` continuation；它可以转换 `next()` 的返回值，也可以不调用 `next()` 就直接返回，从而短路链条的其余部分。Cordis 文档把后一种行为称为否决。创建 `waterfall-demo.ts`：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Events {
-    'demo/transform'(input: string, next: () => Promise<string>): Promise<string>
-  }
-}
-
-export const name = 'waterfall-demo'
-
-export function apply(ctx: Context) {
-  // Listener 1: wrap the downstream result.
-  ctx.on('demo/transform', async (input, next) => {
-    const downstream = await next()
-    return downstream.toUpperCase()
-  })
-
-  // Listener 2: short-circuit when it owns the decision.
-  ctx.on('demo/transform', async (input, next) => {
-    if (input.includes('blocked')) return '** blocked **'
-    return next()
-  })
-
-  void (async () => {
-    console.log(await ctx.waterfall('demo/transform', 'hello', async () => 'hello'))
-    console.log(await ctx.waterfall('demo/transform', 'blocked words', async () => 'blocked words'))
-  })()
-}
-```
-
-让 `cordis.yml` 只指向该文件并运行：
-
-```
-HELLO
-** BLOCKED **
-```
-
-按顺序看第二行如何产生：监听器 1 先运行并调用 `next()`，从而调用监听器 2；监听器 2 看到 `blocked` 后直接返回而不调用 `next()`，因此最内层默认逻辑（传给 `ctx.waterfall` 的函数）从未运行；返回途中，监听器 1 再把替换消息转换为大写。
-
-由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这是本仓库的常设规则（[waterfall 语义](../cordis-primer.zh.md#cordis-waterfall-semantics)）。
-
-harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.zh.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.zh.md#approvalrequest--waterfall) 允许策略代替用户作答。
-
-下一章：[配置](05-config.zh.md)：来自 `cordis.yml` 的插件选项。
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

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

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for 05-config.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/05-config.md
-/5-configuration:
-  en: 6867b9ed15839cf1
-  zh: 97425aab3396a458
-/5-configuration/a-configurable-plugin:
-  en: 1fcc4b1a64c6e6bb
-  zh: 85444447b593f18f
-/5-configuration/fail-loud:
-  en: 261253c9d96b0fc1
-  zh: 3f4ea5f34aa2637d
-/5-configuration/volatile-fields:
-  en: ee367f4db7e8598c
-  zh: c1f17caebad9cc0a
-/5-configuration/computed-config-values:
-  en: dbd47e8aa99fb2e0
-  zh: dc441f610416909d

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

@@ -1,111 +0,0 @@
-# 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.
-
-<a id="volatile-fields"></a>
-## Volatile fields
-
-Use `.volatile()` for a field that the plugin reads during each operation. A change to that field updates its stable reference without remounting the plugin. Read it with `.get()`:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '@deepseek-ai/cordis-plugin-loader'
-import Schema from '@deepseek-ai/schemastery'
-
-export const Config = Schema.object({
-  greeting: Schema.string().default('Hello').volatile(),
-})
-
-export function apply(ctx: Context, config: ReturnType<typeof Config>) {
-  ctx.on('loader/volatile-update', () => {
-    console.log(config.greeting.get())
-  })
-}
-```
-
-A direct `Config(raw)` call also returns references. An optional field without a default still has a reference; `.get()` returns `undefined` when it is absent. Keep the reference, or capture its value for one operation, including across `await`. Do not retain that value for later operations. Object and array values are detached, recursively frozen snapshots of plain data; functions, class instances, and cycles are rejected.
-
-Loader compares raw config while ignoring schema-declared volatile fields. A volatile-only change is parsed through the plugin’s `internal/config` hook and validated; when every ordinary effective value still matches, Loader commits the new values into the running references and emits one instance-local `loader/volatile-update` with the changed paths as arrays of keys, bypassing the target plugin’s `internal/update`. Equal values do not notify. An invalid candidate is logged and leaves the running references unchanged until the next activation. A changed ordinary effective value, including a changed expression result, and simultaneous ordinary-field changes retain the existing update flow, leaving old references unchanged and unnotified. Group/Include still dispatch child updates. Direct `fiber.update()`, code replacement, and dependency replacement retain their lifecycle; `noSave` still controls direct-update persistence. Notifications use ordinary `emit` without awaiting resource reconfiguration.
-
-Declare volatile fields at fixed object paths, or mark an entire object or array volatile. Independent references inside arrays, dictionaries, union or intersect branches, lazy schemas, transforms, or another volatile value are rejected. Configuration files store ordinary values; `simplify()` unwraps references. Serialized schemas preserve their field types, defaults, roles, and volatile marker for schema-driven forms. Existing settings consumers continue to use their own settings interfaces.
-
-## 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

@@ -1,111 +0,0 @@
-# 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 验证，但其中指定的资源或提供方不可用，该插件也应当在能解析该引用时立即拒绝。
-
-<a id="volatile-fields"></a>
-## Volatile 字段
-
-对于插件在每次操作中读取的字段，可以使用 `.volatile()`。字段变化会更新稳定引用，无需重新挂载插件。通过 `.get()` 读取：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '@deepseek-ai/cordis-plugin-loader'
-import Schema from '@deepseek-ai/schemastery'
-
-export const Config = Schema.object({
-  greeting: Schema.string().default('Hello').volatile(),
-})
-
-export function apply(ctx: Context, config: ReturnType<typeof Config>) {
-  ctx.on('loader/volatile-update', () => {
-    console.log(config.greeting.get())
-  })
-}
-```
-
-直接调用 `Config(raw)` 也会返回引用。没有默认值的可选字段仍然具有引用；字段缺省时，`.get()` 返回 `undefined`。可以保存引用，也可以在单次操作中保存读取值，包括跨越 `await`，但不能将该值用于后续操作。对象和数组值是脱离输入、递归冻结的普通数据快照；函数、类实例和循环引用会被拒绝。
-
-Loader 比较原始配置时忽略 schema 声明的 volatile 字段。仅 volatile 变化会经目标插件的 `internal/config` 钩子解析并校验；当所有普通字段的有效值仍然一致时，Loader 把新值提交到运行中的引用，并向所属实例发出一次 `loader/volatile-update`，参数是以键数组表示的变化路径，不进入目标插件的 `internal/update`。等值更新不通知。无效候选会记录日志，运行中的引用保持不变，直到下次激活。普通字段有效值变化（包括表达式求值结果变化）以及普通字段同时变化时沿用原更新流程，旧引用不更新也不接收通知。Group/Include 仍分发子条目更新。直接 `fiber.update()`、代码替换和依赖替换保留原有生命周期；`noSave` 仍控制直接更新的持久化。通知使用普通 `emit`，不等待资源重新配置完成。
-
-在固定对象路径上声明 volatile 字段，或将整个对象、数组标记为 volatile。数组、字典、union 或 intersect 分支、lazy、transform 或另一个 volatile 值内部的独立引用会被拒绝。配置文件保存普通值；`simplify()` 会解包引用。序列化 schema 保留字段类型、默认值、角色和 volatile 标记，供基于 schema 的表单使用。现有 settings 消费者继续使用原有 settings 接口。
-
-## 计算得到的配置值
-
-本仓库使用的 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.zh.md#loader-configuration)。
-
-下一章：[组合与 HMR（热模块替换）](06-composition-and-hmr.zh.md)：将 `cordis.yml` 视为应用。
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

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

@@ -1,16 +0,0 @@
-# Bilingual-pair consistency record for 06-composition-and-hmr.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/06-composition-and-hmr.md
-/6-composition-and-hmr:
-  en: 628a6175275ee566
-  zh: 0880eb3d5a90be9e
-/6-composition-and-hmr/entries-are-more-than-a-name:
-  en: bdbf57b5166d37e5
-  zh: 9b3b38f52be1dbd9
-/6-composition-and-hmr/hot-module-replacement:
-  en: 3ee3fbb053f19118
-  zh: 35145132c1c01a37
-/6-composition-and-hmr/diagnosing-a-plugin-that-never-loads:
-  en: 25907bb752af3a02
-  zh: 7b8fefc7567d9aef

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

@@ -1,113 +0,0 @@
-# 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/dsh-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/dsh-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)