dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/site/reference/cordis-api/fiber.md

@@ -1,435 +1,459 @@
----
-editSource: "docs/cordis-api/fiber.zh.md"
-rawMarkdownPath: "reference/cordis-api/fiber.md"
----
-
-<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
-     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md` 重新记录配对。 -->
-
-# Fiber
-
-fiber 是一个已加载的插件实例，包含其生命周期状态、经过校验的配置以及已注册的作用。`ctx.fiber` 是当前 fiber，`ctx.effect()` 会将调用委托给它。
-
-### ctx.effect(execute, label?)
-
-```ts cordis-catalog
-/**
- * Register a cleanup-aware effect on this fiber.
- *
- * `execute` runs immediately; the disposers it produces are collected and
- * run (in reverse order) either when the returned disposer is called or
- * when the fiber unloads, whichever comes first. Calling the disposer twice
- * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
- * already disposed, and `TypeError` if `execute` returns an invalid shape.
- *
- * @param execute — the effect body; see {@link Effect} for accepted shapes.
- * @param label — effect label shown in `getEffects()` diagnostics.
- * @returns a disposer that tears the effect down and settles once done.
- */
-effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
-effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
-```
-
-在此 fiber 上注册一个支持清理的作用。
-
-`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
-
-- `execute`：作用主体；可接受的结构见 `Effect`。
-- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
-
-**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L421)
-
-### ctx.fiber
-
-```ts cordis-catalog
-/** The fiber (plugin runtime instance) that owns this context. */
-fiber: Fiber
-```
-
-拥有此上下文的 fiber（插件运行时实例）。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L12)
-
-## Fiber 类
-
-单次插件应用的运行时实例。
-
-fiber 会跟踪 `ctx.plugin()` 返回的插件上下文所对应的依赖状态、原始配置与有效配置、生命周期作用和清理操作。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L184)
-
-### fiber.uid
-
-```ts cordis-catalog
-/** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
-public uid: number | null
-```
-
-在注册表中的唯一 id；根 fiber 的 id 为 0，dispose 后为 `null`。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L186)
-
-### fiber.ctx
-
-```ts cordis-catalog
-/** The context this fiber's plugin runs in (extends the parent context). */
-public readonly ctx: Context
-```
-
-此 fiber 的插件运行所在的上下文（扩展自父上下文）。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L188)
-
-### fiber.config
-
-```ts cordis-catalog
-/** Raw plugin input retained for the next activation. */
-public config: any
-```
-
-为下次激活保留的原始插件输入。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L190)
-
-### fiber.state
-
-```ts cordis-catalog
-/** Current lifecycle state; transitions emit `internal/status`. */
-public state
-```
-
-当前生命周期状态；状态转换会发出 `internal/status`。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L192)
-
-### fiber.dispose
-
-```ts cordis-catalog
-/** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
-public readonly dispose: () => Promise<void>
-```
-
-dispose 此 fiber：卸载插件，并在清理完成后结算。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L194)
-
-### fiber.committed
-
-```ts cordis-catalog
-/** Required implementations retained through dependent teardown. */
-public committed: Readonly<Dict<Impl>> | undefined
-```
-
-在依赖方清理完成前保留的所需服务实现。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L196)
-
-### fiber.provisions
-
-```ts cordis-catalog
-/** Service implementations owned by this fiber, including isolated provisions. */
-public readonly provisions: Set<Impl>
-```
-
-此 fiber 拥有的服务实现，包括隔离域中的服务。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L198)
-
-### fiber.inertia
-
-```ts cordis-catalog
-/** The in-flight load/unload transition, if one is currently running. */
-public inertia: Promise<void> | undefined
-```
-
-当前正在进行的加载或卸载转换；如果没有此类转换，则为 undefined。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L200)
-
-### fiber.name
-
-```ts cordis-catalog
-/** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
-get name()
-```
-
-插件的显示名称，继承自最近的具名祖先；如果不存在，则为 `'root'`。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L342)
-
-### fiber.assertActive()
-
-```ts cordis-catalog
-/**
- * Throw if the fiber has already been disposed.
- *
- * @returns nothing when the fiber is still active.
- * @throws {CordisError} `INACTIVE_EFFECT` when the fiber's uid has been cleared.
- */
-assertActive()
-```
-
-如果 fiber 已经 dispose，则抛出异常。
-
-**返回**：fiber 仍处于活动状态时不返回任何内容。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L357)
-
-### fiber.effect(execute, label?)
-
-```ts cordis-catalog
-/**
- * Register a cleanup-aware effect on this fiber.
- *
- * `execute` runs immediately; the disposers it produces are collected and
- * run (in reverse order) either when the returned disposer is called or
- * when the fiber unloads, whichever comes first. Calling the disposer twice
- * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
- * already disposed, and `TypeError` if `execute` returns an invalid shape.
- *
- * @param execute — the effect body; see {@link Effect} for accepted shapes.
- * @param label — effect label shown in `getEffects()` diagnostics.
- * @returns a disposer that tears the effect down and settles once done.
- */
-effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
-effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
-```
-
-在此 fiber 上注册一个支持清理的作用。
-
-`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
-
-- `execute`：作用主体；可接受的结构见 `Effect`。
-- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
-
-**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L421)
-
-### fiber.getEffects()
-
-```ts cordis-catalog
-/**
- * Return metadata for currently registered effects.
- *
- * @returns one {@link EffectMeta} tree per labeled live effect.
- */
-getEffects()
-```
-
-返回当前已注册作用的元数据。
-
-**返回**：每个带标签的活动作用对应一棵 `EffectMeta` 树。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L574)
-
-### fiber.rawConfig
-
-```ts cordis-catalog
-/** Raw input retained for the next activation, without evaluating expressions or validating it. */
-get rawConfig(): unknown
-```
-
-
-保留供下次激活使用的原始输入，不执行表达式求值或验证。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L649)
-
-### fiber.effectiveConfig
-
-```ts cordis-catalog
-/**
- * The object passed to plugin activation or the latest successful update that retained the instance.
- * Candidate resolution does not publish it; volatile updates retain its references.
- * Undefined before activation and readable after unload; callers requiring a live instance check `state`.
- */
-get effectiveConfig(): unknown
-```
-
-传给插件激活过程或最近一次成功保留实例的更新的对象。候选配置求值不发布结果；volatile 更新保留其中的引用。激活前为 undefined，卸载后仍可读取；需要运行中实例的调用方还应检查 `state`。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L664)
-
-### fiber.resolveConfig(config)
-
-```ts cordis-catalog
-/**
- * Evaluate and validate a candidate using this fiber's `internal/config` hooks and runtime schema.
- * Does not publish the result, replace raw input, or commit running volatile references.
- * Required injections must be available when a hook uses them.
- * @param config Raw candidate input.
- * @returns The candidate's resolved config, retaining the schema's result identity.
- * @throws {ValidationError} when the runtime schema rejects the candidate; hook errors propagate.
- */
-resolveConfig(config: unknown): unknown
-```
-
-
-通过此 fiber 的 `internal/config` 钩子和运行时 schema 对候选值求值并验证。此操作不发布结果、不替换原始输入，也不提交运行中的 volatile 引用。钩子访问的注入服务必须已经可用。
-
-- `config`：原始候选输入。
-
-**返回**候选配置的解析结果，保留 schema 返回对象的身份。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L676)
-
-### fiber.await()
-
-```ts cordis-catalog
-/**
- * Wait for current lifecycle work and rethrow startup errors.
- *
- * @returns this fiber, once it has settled into a stable state.
- * @throws the config-validation or plugin-startup error, if any.
- */
-async await()
-```
-
-等待当前生命周期工作完成，并重新抛出启动错误。
-
-**返回**：进入稳定状态后的此 fiber。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L754)
-
-### fiber.restart()
-
-```ts cordis-catalog
-/**
- * Dispose and immediately reload this plugin with its current config.
- *
- * @returns a promise resolving once the reload settled.
- * @throws {CordisError} `INACTIVE_EFFECT` when the fiber is already disposed.
- */
-async restart()
-```
-
-dispose 此插件，并立即使用其当前配置重新加载。
-
-**返回**一个在重新加载完成后兑现的 promise。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L768)
-
-### fiber.update(config, noSave?)
-
-```ts cordis-catalog
-/**
- * Resolve a candidate, retain its raw config and apply it through the update waterfall.
- * @param config Raw config; pending fibers defer resolution until activation.
- * @param noSave Suppress the persistence notification when true.
- * @returns The awaited update/restart result, or undefined when a synchronous listener handles it.
- * @throws {ValidationError} when an active fiber's candidate is invalid.
- */
-update(config: any, noSave = false): Awaitable<void>
-```
-
-求值候选配置，保留原始输入，并通过更新 waterfall 应用结果。
-
-- `config` — 原始配置；pending fiber 将求值推迟到激活时。
-- `noSave` — 为 true 时不发出持久化通知。
-
-**返回** 可等待的更新或重启结果；同步监听器处理更新时为 undefined。
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L783)
-
-## Effect
-
-`ctx.effect()` 和插件启动所接受的作用主体结果。
-
-可以是单个清理函数、兑现为清理函数的 promise，或生成多个清理函数的（可能为异步的）可迭代对象。生成器作用会在每个清理函数产生时将其注册。
-
-```ts cordis-catalog
-/**
- * Effect body result accepted by `ctx.effect()` and plugin startup.
- *
- * Either a single disposer, a promise of one, or a (possibly async) iterable
- * yielding several — generator effects register each yielded disposer as it
- * is produced.
- */
-type Effect<T = any> =
-  | SyncEffect<T>
-  | AsyncEffect<T>
-```
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L83)
-
-## Disposable
-
-作用返回的函数，用于在资源释放期间释放资源。
-
-拥有该函数的 fiber 卸载时，清理函数会按注册的相反顺序运行；清理函数可以是异步的，此时卸载过程会等待其完成。
-
-```ts cordis-catalog
-/**
- * Function returned by an effect to release resources during disposal.
- *
- * Disposers run in reverse registration order when the owning fiber unloads;
- * they may be async, in which case unloading awaits them.
- */
-type Disposable<T = any> = () => T
-```
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L74)
-
-## EffectMeta
-
-用于在诊断信息中公开嵌套作用标签的树节点。
-
-```ts cordis-catalog
-/** Tree node used to expose nested effect labels for diagnostics. */
-interface EffectMeta {
-  /** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
-  label: string
-  /** Metadata of nested effects registered while this effect ran. */
-  children: EffectMeta[]
-}
-```
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L96)
-
-## CordisError
-
-具有稳定机器可读错误码的框架错误。
-
-```ts cordis-catalog
-/** Framework error with a stable machine-readable code. */
-class CordisError extends Error {
-  /**
-   * @param code — the stable error code; also the default message.
-   * @param message — optional human-readable override.
-   */
-  constructor(public code: CordisError.Code, message?: string)
-}
-
-/** Cordis error code definitions. */
-namespace CordisError {
-  export type Code = keyof typeof Code
-
-  export const Code = {
-    INACTIVE_EFFECT: 'cannot create effect on inactive context',
-  } as const
-}
-```
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L157)
-
-## ValidationError
-
-插件配置未通过 standard-schema 校验时抛出的错误。
-
-```ts cordis-catalog
-/** Error raised when plugin configuration fails standard-schema validation. */
-class ValidationError extends TypeError {
-  name = 'ValidationError'
-
-  /**
-   * Build the aggregated message from schema issues.
-   *
-   * @param issues — the standard-schema issues, one message line each.
-   */
-  constructor(issues: readonly StandardSchemaV1.Issue[])
-}
-```
-
-[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L19)
+---
+editSource: "docs/cordis-api/fiber.zh.md"
+rawMarkdownPath: "reference/cordis-api/fiber.md"
+---
+
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md` 重新记录配对。 -->
+
+# Fiber
+
+fiber 是一个已加载的插件实例，包含其生命周期状态、经过校验的配置以及已注册的作用。`ctx.fiber` 是当前 fiber，`ctx.effect()` 会将调用委托给它。
+
+### ctx.effect(execute, label?)
+
+```ts cordis-catalog
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
+effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
+effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
+```
+
+在此 fiber 上注册一个支持清理的作用。
+
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
+
+- `execute`：作用主体；可接受的结构见 `Effect`。
+- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
+
+**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L443)
+
+### ctx.fiber
+
+```ts cordis-catalog
+/** The fiber (plugin runtime instance) that owns this context. */
+fiber: Fiber
+```
+
+拥有此上下文的 fiber（插件运行时实例）。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L12)
+
+## Fiber 类
+
+单次插件应用的运行时实例。
+
+fiber 会跟踪 `ctx.plugin()` 返回的插件上下文所对应的依赖状态、原始配置与有效配置、生命周期作用和清理操作。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L214)
+
+### fiber.uid
+
+```ts cordis-catalog
+/** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
+public uid: number | null
+```
+
+在注册表中的唯一 id；根 fiber 的 id 为 0，dispose 后为 `null`。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L216)
+
+### fiber.ctx
+
+```ts cordis-catalog
+/** The context this fiber's plugin runs in (extends the parent context). */
+public readonly ctx: Context
+```
+
+此 fiber 的插件运行所在的上下文（扩展自父上下文）。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L218)
+
+### fiber.config
+
+```ts cordis-catalog
+/** Raw plugin input retained for the next activation. */
+public config: any
+```
+
+为下次激活保留的原始插件输入。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L220)
+
+### fiber.state
+
+```ts cordis-catalog
+/** Current lifecycle state; transitions emit `internal/status`. */
+public state
+```
+
+当前生命周期状态；状态转换会发出 `internal/status`。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L222)
+
+### fiber.dispose
+
+```ts cordis-catalog
+/** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
+public readonly dispose: () => Promise<void>
+```
+
+dispose 此 fiber：卸载插件，并在清理完成后结算。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L224)
+
+### fiber.committed
+
+```ts cordis-catalog
+/** Required implementations retained through dependent teardown. */
+public committed: Readonly<Dict<Impl>> | undefined
+```
+
+在依赖方清理完成前保留的所需服务实现。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L226)
+
+### fiber.provisions
+
+```ts cordis-catalog
+/** Service implementations owned by this fiber, including isolated provisions. */
+public readonly provisions: Set<Impl>
+```
+
+此 fiber 拥有的服务实现，包括隔离域中的服务。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L228)
+
+### fiber.inertia
+
+```ts cordis-catalog
+/** The in-flight load/unload transition, if one is currently running. */
+public inertia: Promise<void> | undefined
+```
+
+当前正在进行的加载或卸载转换；如果没有此类转换，则为 undefined。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L230)
+
+### fiber.name
+
+```ts cordis-catalog
+/** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
+get name()
+```
+
+插件的显示名称，继承自最近的具名祖先；如果不存在，则为 `'root'`。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L364)
+
+### fiber.assertActive()
+
+```ts cordis-catalog
+/**
+ * Throw if the fiber has already been disposed.
+ *
+ * @returns nothing when the fiber is still active.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber's uid has been cleared.
+ */
+assertActive()
+```
+
+如果 fiber 已经 dispose，则抛出异常。
+
+**返回**：fiber 仍处于活动状态时不返回任何内容。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L379)
+
+### fiber.effect(execute, label?)
+
+```ts cordis-catalog
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
+effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
+effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
+```
+
+在此 fiber 上注册一个支持清理的作用。
+
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
+
+- `execute`：作用主体；可接受的结构见 `Effect`。
+- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
+
+**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L443)
+
+### fiber.getEffects()
+
+```ts cordis-catalog
+/**
+ * Return metadata for currently registered effects.
+ *
+ * @returns one {@link EffectMeta} tree per labeled live effect.
+ */
+getEffects()
+```
+
+返回当前已注册作用的元数据。
+
+**返回**：每个带标签的活动作用对应一棵 `EffectMeta` 树。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L596)
+
+### fiber.rawConfig
+
+```ts cordis-catalog
+/** Raw input retained for the next activation, without evaluating expressions or validating it. */
+get rawConfig(): unknown
+```
+
+
+保留供下次激活使用的原始输入，不执行表达式求值或验证。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L671)
+
+### fiber.effectiveConfig
+
+```ts cordis-catalog
+/**
+ * The object passed to plugin activation or the latest successful update that retained the instance.
+ * Candidate resolution does not publish it; volatile updates retain its references.
+ * Undefined before activation and readable after unload; callers requiring a live instance check `state`.
+ */
+get effectiveConfig(): unknown
+```
+
+传给插件激活过程或最近一次成功保留实例的更新的对象。候选配置求值不发布结果；volatile 更新保留其中的引用。激活前为 undefined，卸载后仍可读取；需要运行中实例的调用方还应检查 `state`。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L686)
+
+### fiber.resolveConfig(config)
+
+```ts cordis-catalog
+/**
+ * Evaluate and validate a candidate using this fiber's `internal/config` hooks and runtime schema.
+ * Does not publish the result, replace raw input, or commit running volatile references.
+ * Required injections must be available when a hook uses them.
+ * @param config Raw candidate input.
+ * @returns The candidate's resolved config, retaining the schema's result identity.
+ * @throws {ValidationError} when the runtime schema rejects the candidate; hook errors propagate.
+ */
+resolveConfig(config: unknown): unknown
+```
+
+
+通过此 fiber 的 `internal/config` 钩子和运行时 schema 对候选值求值并验证。此操作不发布结果、不替换原始输入，也不提交运行中的 volatile 引用。钩子访问的注入服务必须已经可用。
+
+- `config`：原始候选输入。
+
+**返回**候选配置的解析结果，保留 schema 返回对象的身份。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L698)
+
+### fiber.await()
+
+```ts cordis-catalog
+/**
+ * Wait for current lifecycle work and rethrow startup errors.
+ *
+ * @returns this fiber, once it has settled into a stable state.
+ * @throws the config-validation or plugin-startup error, if any.
+ */
+async await()
+```
+
+等待当前生命周期工作完成，并重新抛出启动错误。
+
+**返回**：进入稳定状态后的此 fiber。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L776)
+
+### fiber.restart()
+
+```ts cordis-catalog
+/**
+ * Dispose and immediately reload this plugin with its current config.
+ *
+ * @returns a promise resolving once the reload settled.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber is already disposed.
+ */
+async restart()
+```
+
+dispose 此插件，并立即使用其当前配置重新加载。
+
+**返回**一个在重新加载完成后兑现的 promise。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L790)
+
+### fiber.update(config, noSave?)
+
+```ts cordis-catalog
+/**
+ * Resolve a candidate, retain its raw config and apply it through the update waterfall.
+ * @param config Raw config; pending fibers defer resolution until activation.
+ * @param noSave Suppress the persistence notification when true.
+ * @returns The awaited update/restart result, or undefined when a synchronous listener handles it.
+ * @throws {ValidationError} when an active fiber's candidate is invalid.
+ */
+update(config: any, noSave = false): Awaitable<void>
+```
+
+求值候选配置，保留原始输入，并通过更新 waterfall 应用结果。
+
+- `config` — 原始配置；pending fiber 将求值推迟到激活时。
+- `noSave` — 为 true 时不发出持久化通知。
+
+**返回** 可等待的更新或重启结果；同步监听器处理更新时为 undefined。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L805)
+
+## Effect
+
+`ctx.effect()` 和插件启动所接受的作用主体结果。
+
+可以是单个清理函数、兑现为清理函数的 promise，或生成多个清理函数的（可能为异步的）可迭代对象。生成器作用会在每个清理函数产生时将其注册。
+
+```ts cordis-catalog
+/**
+ * Effect body result accepted by `ctx.effect()` and plugin startup.
+ *
+ * Either a single disposer, a promise of one, or a (possibly async) iterable
+ * yielding several — generator effects register each yielded disposer as it
+ * is produced.
+ */
+type Effect<T = any> =
+  | SyncEffect<T>
+  | AsyncEffect<T>
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L113)
+
+## Disposable
+
+作用返回的函数，用于在资源释放期间释放资源。
+
+拥有该函数的 fiber 卸载时，清理函数会按注册的相反顺序运行；清理函数可以是异步的，此时卸载过程会等待其完成。
+
+```ts cordis-catalog
+/**
+ * Function returned by an effect to release resources during disposal.
+ *
+ * Disposers run in reverse registration order when the owning fiber unloads;
+ * they may be async, in which case unloading awaits them.
+ */
+type Disposable<T = any> = () => T
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L104)
+
+## EffectMeta
+
+用于在诊断信息中公开嵌套作用标签的树节点。
+
+```ts cordis-catalog
+/** Tree node used to expose nested effect labels for diagnostics. */
+interface EffectMeta {
+  /** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
+  label: string
+  /** Metadata of nested effects registered while this effect ran. */
+  children: EffectMeta[]
+}
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L126)
+
+## CordisError
+
+具有稳定机器可读错误码的框架错误。
+
+```ts cordis-catalog
+/** Framework error with a stable machine-readable code. */
+class CordisError extends Error {
+  /**
+   * @param code — the stable error code; also the default message.
+   * @param message — optional human-readable override.
+   */
+  constructor(public code: CordisError.Code, message?: string)
+}
+
+/** Cordis error code definitions. */
+namespace CordisError {
+  export type Code = keyof typeof Code
+
+  export const Code = {
+    INACTIVE_EFFECT: 'cannot create effect on inactive context',
+  } as const
+}
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L187)
+
+## ValidationError
+
+插件配置未通过 standard-schema 校验时抛出的错误。
+
+```ts cordis-catalog
+/** Error raised when plugin configuration fails standard-schema validation. */
+class ValidationError extends TypeError {
+  name = 'ValidationError'
+
+  /**
+   * Build the aggregated message from schema issues.
+   *
+   * @param issues — the standard-schema issues, one message line each.
+   */
+  constructor(public issues: readonly StandardSchemaV1.Issue[])
+
+  /**
+   * Test whether a value is a config `ValidationError`, including one from another copy of Cordis.
+   *
+   * @param error — the value to test.
+   * @returns `true` if `error` carries the global validation-error brand.
+   */
+  static is(error: unknown): error is ValidationError
+
+  /**
+   * Convert an issue path to plain property keys.
+   *
+   * @param path — the standard-schema issue path; segments may be `{ key }` objects.
+   * @returns the property keys, or an empty array when the issue has no path.
+   */
+  static normalizePath(path: StandardSchemaV1.Issue['path'] = [])
+
+  /**
+   * Format an issue path as a dotted string.
+   *
+   * @param path — the standard-schema issue path.
+   * @returns the keys joined with `.`.
+   */
+  static formatPath(path: StandardSchemaV1.Issue['path'])
+}
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/fiber.ts#L19)