dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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)

package/kb/extra/cordis-tutorial/01-first-plugin.zh.md

@@ -1,95 +0,0 @@
-# 1. 编写第一个插件
-
-[English](01-first-plugin.md) | 中文
-
-在本教程使用的 loader 配置中，Cordis 插件模块通过命名导出提供 `apply` 函数。Cordis 加载模块时，会用一个 **上下文** 调用 `apply`；该上下文就是 `ctx` 对象，插件通过它注册自己贡献的所有内容。
-
-## 编写插件
-
-在 `tmp/cordis-tutorial` 目录中（参见[环境设置](index.zh.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.zh.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.zh.md)介绍了何时应当使用类形态。
-
-## 尝试制造错误
-
-让 `apply` 抛出异常：
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  throw new Error('apply exploded')
-}
-```
-
-再次运行：进程会因该错误而终止。插件加载失败会明确报错，不会仅跳过该配置项。
-
-还需要尽早了解一个例外：如果某个配置项的模块无法被 **解析**，例如路径或包名拼写错误，Cordis 会通过 logger 服务报告错误，而不会使进程崩溃。在启动阶段，这条报告可能在 console 导出器开始观察之前丢失。如果新增配置项似乎没有任何效果，请先检查拼写。
-
-下一章：[生命周期与 effect](02-lifecycle-and-effects.zh.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/kb/extra/cordis-tutorial/02-lifecycle-and-effects.md

@@ -1,98 +0,0 @@
-# 2. Lifecycle and effects
-
-English | [中文](02-lifecycle-and-effects.zh.md)
-
-A Cordis plugin can be unloaded by a config edit, hot reload, explicit disposal, or loss of a required service. Registrations made through Cordis APIs are effects and are undone when their owning plugin unloads; resources managed outside those APIs must be wrapped in `ctx.effect()`.
-
-## Effects
-
-For a resource Cordis does not already manage — a timer, a connection, a watcher — wrap it in `ctx.effect()` and return a disposer:
-
-Create `lifecycle.ts` in `tmp/cordis-tutorial`:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'lifecycle-demo'
-
-function heartbeat(ctx: Context) {
-  console.log('heartbeat plugin loading')
-  ctx.effect(() => {
-    const timer = setInterval(() => console.log('tick'), 200)
-    return () => {
-      clearInterval(timer)
-      console.log('heartbeat cleaned up')
-    }
-  })
-}
-
-export function apply(ctx: Context) {
-  // Mount a child plugin and keep its fiber to dispose it later.
-  const fiber = ctx.plugin(heartbeat)
-  // The demo timer is itself an effect: if THIS plugin is unloaded first,
-  // the pending callback is cancelled instead of firing on a dead app.
-  ctx.effect(() => {
-    const timer = setTimeout(async () => {
-      await fiber.dispose()
-      console.log('disposed')
-      process.exit(0)
-    }, 700)
-    return () => clearTimeout(timer)
-  })
-}
-```
-
-Point `cordis.yml` at it:
-
-```yaml
-- name: './lifecycle.ts'
-```
-
-Run (`node --import tsx ../../vendor/cordis/bin.js`) and you get:
-
-```
-heartbeat plugin loading
-tick
-tick
-tick
-heartbeat cleaned up
-disposed
-```
-
-Three things to notice:
-
-- `ctx.plugin(heartbeat)` mounts a function **from code** as a plugin — the same operation the YAML loader performs for each config entry. A function plugin needs no `apply` method: Cordis calls the function directly and uses its name only for diagnostics. An `apply` method is required only for the object form, `ctx.plugin({ apply(ctx) { /* ... */ } })`. The call returns a **fiber**, the runtime handle for one loaded plugin instance.
-- The effect body runs during load; the disposer it returns runs during unload. You never call the disposer yourself for a plugin-lifetime resource.
-- `fiber.dispose()` resolves after all of the plugin's cleanup — including async disposers — has finished, and recursively unloads any child plugins it mounted.
-
-## The fiber state machine
-
-Every loaded plugin instance owns a fiber that moves through these states:
-
-```
-PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
-                 ↘ FAILED
-```
-
-- **PENDING** — declared, but a required service (chapter 3) is not available yet.
-- **LOADING / ACTIVE** — `apply` is running / has completed.
-- **FAILED** — `apply` or config validation threw.
-- **UNLOADING / DISPOSED** — disposers are running / everything is torn down.
-
-You will meet PENDING again in [chapter 6](06-composition-and-hmr.md), where it is the usual answer to "why does my plugin print nothing?".
-
-## What is already an effect
-
-You rarely write `ctx.effect()` yourself, because the built-in registration APIs are effects already:
-
-- `ctx.on(event, listener)` — the listener is removed on unload ([chapter 4](04-events.md)).
-- `ctx.plugin(child)` — the child is disposed with its parent.
-- Service registrations are effects. Harness registries such as `ctx.tools.register(...)` also attach their returned disposers to the calling plugin, so they unwind automatically ([chapter 7](07-into-the-harness.md)).
-
-For a resource Cordis does not manage, acquire it inside `ctx.effect()` and return a disposer that releases it. Cordis then invokes that release during unloading, including hot reload.
-
-One ordering caveat: disposers start in reverse registration order, but multiple **async** disposers run concurrently. If teardown steps must run in sequence, keep them in one disposer and await them there.
-
-Next: [Services](03-services.md) — how plugins share capabilities.
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)