一切皆插件：Cordis 的五个思想

16export interface Context {17  /** Isolation map: service name → scope label. Lookups for a name resolve within its label. */18  [symbols.isolate]: Dict<symbol>19  /** Intercept map: service name → config merged into that service's per-plugin config. */20  [symbols.intercept]: Dict21  /** The root context of the application (every child context shares it). @experimental */22  root: this23  /** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */24  baseUrl?: string25  /** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */26  events: EventsService27  /** The logging service. Call `ctx.logger(name)` for a named logger. */28  logger: LoggerService29  /** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */30  reflect: ReflectService31  /** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */32  registry: RegistryService33}

42export class Context {43  /** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */44  static readonly effect: unique symbol = symbols.effect45  /** Symbol key for a context's listener filter, consulted on every event dispatch. */46  static readonly filter: unique symbol = symbols.filter47  /** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */48  static readonly isolate: unique symbol = symbols.isolate49  /** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */50  static readonly intercept: unique symbol = symbols.intercept⋯  // ... static is() 与其他辅助 ...70  /** Create the root context and install the built-in services. */71  constructor() {72    this[symbols.isolate] = Object.create(null)73    this[symbols.intercept] = Object.create(null)74    const self = new Proxy<this>(this, ReflectService.handler)75    this.root = self76    this.baseUrl = undefined77    this.fiber = new Fiber(self, {}, Object.create(null), null, () => [])78    this.reflect = new ReflectService(self)79    this.registry = new RegistryService(self)80    this.events = new EventsService(self)81    this.logger = new LoggerService(self)82    this.fiber._disposables.clear()83    return self84  }

11export abstract class Service<out T = never> {12  /** Symbol key of an instance method run after construction (class plugins). */13  static readonly init: unique symbol = symbols.init14  /** Symbol key of the availability predicate passed to `ctx.provide()`. */15  static readonly check: unique symbol = symbols.check16  /** Symbol key of the phantom intercept-config type parameter. */17  static readonly config: unique symbol = symbols.config18  /** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */19  static readonly invoke: unique symbol = symbols.invoke20  /** Symbol key of the helper deriving an extended service instance. */21  static readonly extend: unique symbol = symbols.extend22  /** Symbol key of the tracker metadata used for context tracing. */23  static readonly tracker: unique symbol = symbols.tracker24  /** Symbol key of the intercept-config resolution helper below. */25  static readonly resolveConfig: unique symbol = symbols.resolveConfig2627  declare [symbols.config]: T2829  /** The service name this instance is registered under. */30  public name!: string3132  /**33   * Register this instance as `name` in the current context.34   *35   * Calls `ctx.reflect.provide(name, this, this[Service.check])`, so the36   * service is unregistered automatically when the owning fiber unloads.37   * Services with a `[Service.invoke]` body return a callable instance.38   *39   * @param ctx — the context to register in (stored as `this.ctx`).40   * @param name — the service name; defaults to the static `provide` field.41   */42  constructor(protected ctx: Context, name: string) {43    name ??= this.constructor['provide'] as string4445    let self = this46    const tracker: Tracker = {47      associate: name,48      property: 'ctx',49    }50    if (self[symbols.invoke]) {51      self = createCallable(name, joinPrototype(Object.getPrototypeOf(this), Function.prototype), tracker)52    }53    self.ctx = ctx54    self.name = name55    defineProperty(self, symbols.tracker, tracker)5657    self.ctx.reflect.provide(name, self, this[symbols.check])58    return self59  }

100  export interface Base<T = any> {101    /** Display name used for fiber diagnostics and logger names. */102    name?: string103    /** Standard-schema validator applied to config before the plugin starts. */104    Config?: StandardSchemaV1<any, T>105    /** Services the plugin requires; it only loads while all are available. */106    inject?: Inject107    /** Service name(s) the plugin provides (read by `Service` and by loaders). */108    provide?: string | string[]109    /** Service names whose intercept config the plugin declares it consumes. */110    intercept?: Dict<boolean>111  }

402  /**403   * Register a cleanup-aware effect on this fiber.404   *405   * `execute` runs immediately; the disposers it produces are collected and406   * run (in reverse order) either when the returned disposer is called or407   * when the fiber unloads, whichever comes first. Calling the disposer twice408   * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is409   * already disposed, and `TypeError` if `execute` returns an invalid shape.410   *411   * @param execute — the effect body; see {@link Effect} for accepted shapes.412   * @param label — effect label shown in `getEffects()` diagnostics.413   * @returns a disposer that tears the effect down and settles once done.414   */415  effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>416  /** Same as above for async effects; the disposer is also awaitable. */417  effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>418  effect(execute: () => Effect, label = 'anonymous'): any {419    this.assertActive()420    if (this.state === FiberState.UNLOADING) {421      throw new CordisError('INACTIVE_EFFECT')422    }423424    const disposables: Disposable[] = []425    let disposing = false426    let disposalTask: void | Promise<void>427    const dispose = () => {428      if (disposing) return disposalTask429      disposing = true430      let task!: void | Promise<void>431      for (const disposable of disposables.splice(0).reverse()) {432        if (task) {433          task = task.then(() => runDisposable(disposable))434        } else {435          const result = runDisposable(disposable)436          if (isObject(result) && 'then' in result) {437            task = result as any438          }439        }440      }441      return disposalTask = task442    }

24/**25 * Event dispatch strategy used by the event service.26 *27 * `emit` runs synchronous listeners without awaiting them, `parallel` awaits28 * all listeners together, `serial` awaits them in order until one bails,29 * `bail` stops on the first synchronous bail value, and `waterfall` composes30 * listeners around a final `next` callback.31 */32export type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'

234  waterfall(...args: any[]) {235    const cbs = this.dispatch('waterfall', args)236    const inner = args.pop()237    const next = () => {238      const cb = cbs.shift() ?? inner239      return cb(...args)240    }241    args.push(next)242    return next()243  }

107- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).

288  on(name: string | symbol, listener: (...args: any) => any, options?: boolean | EventOptions) {289    if (typeof options !== 'object') {290      options = { prepend: options }291    }292293    // handle special events294    this.ctx.fiber.assertActive()295    listener = this.ctx.reflect.bind(listener)296    const result = this.bail(this.ctx, 'internal/listener', name, listener, options)297    if (result) return result298299    const hooks = this._hooks[name] ||= []300    const label = `ctx.on(${typeof name === 'string' ? JSON.stringify(name) : name.toString()})`301    return this.register(label, hooks, listener, options)302  }

254  register(label: string, hooks: Hook[], callback: any, options: EventOptions): () => void {255    const method = options.prepend ? 'unshift' : 'push'256    return this.ctx.fiber.effect(() => {257      hooks[method]({ ctx: this.ctx, callback, ...options })258      return () => this.unregister(hooks, callback)259    }, label)260  }

329export interface Events {330  /** A plugin fiber was created or its uid was cleared on disposal. */331  'internal/plugin'(fiber: Fiber): void332  /** A fiber changed lifecycle state; receives the fiber and its previous state. */333  'internal/status'(fiber: Fiber, oldValue: FiberState): void334  /**335   * Resolve raw plugin config after the fiber's injections become active.336   * @param config - the raw config for this activation.337   * @mode waterfall338   */339  'internal/config'(this: Fiber, config: any, next: () => any): any340  /** Interception hook for a service binding (no core producer). */341  'internal/service'(this: Context, name: string, value: any): void342  /** Waterfall: a fiber config update is being applied; skip `next()` to veto. */343  'internal/update'(this: Fiber, config: any, noSave: boolean, next: () => void | Promise<void>): void | Promise<void>344  /** Waterfall: a service is being read through the context proxy. */345  'internal/get'(ctx: Context, name: string, error: Error, next: () => any): any346  /** Waterfall: a service is being written through the context proxy. */347  'internal/set'(ctx: Context, name: string, value: any, error: Error, next: () => boolean): boolean348  /** Bail: a listener is being registered; a non-null result replaces registration. */349  'internal/listener'(this: Context, name: string, listener: any, prepend: boolean): void350  /** An event is being dispatched to listeners (fired for non-internal events only). */351  'internal/dispatch'(mode: DispatchMode, name: string, args: any[], thisArg: any): void352}

11- **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.

3This directory contains source-vendored copies of the Cordis framework and its foundation libraries. They are copied into this monorepo instead of being depended on via npm, so that the harness fully owns its framework layer (auditable, patchable, pinned).45All vendored packages are **renamed into the `@deepseek-ai` scope** (`cordis` → `@deepseek-ai/cordis`, `@cordisjs/plugin-<x>` → `@deepseek-ai/cordis-plugin-<x>`): every harness package declares `cordis` as a peer dependency, so publishing the harness publishes this framework layer too, and a publication under the upstream names would squat them on the registry. Directory names and upstream version numbers are deliberately unchanged, so the manifest below still reads as an upstream snapshot. `pnpm-workspace.yaml#linkWorkspacePackages` makes those preserved semver ranges resolve these pinned workspaces, including imports from built `lib/`. The `hygiene` gate `verify-vendored-links` asserts every vendored name resolves to a workspace `link:` in `pnpm-lock.yaml` with no registry copy alongside. Schemastery's manifest additionally declares a conditional `exports` map (import → `.mjs`, require → `.cjs`): pnpm links the directory itself, so without `exports` Node's ESM resolver would fall back to `main` and load the CJS entry whose lazy `require('@deepseek-ai/cosmokit')` can race ESM loading of the same linked module under module-hook hosts (vitest). Upstream MIT `LICENSE` files are preserved in each package directory.

15- **waterfall** (around-middleware) where plugins transform, short-circuit, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.16- **serial** (awaited in listener order) for ordered checkpoints such as `agent/turn-stopping`.17- **parallel** (awaited fan-out) where every listener must get an independent chance: the `session/flush` durability checkpoint.18- **emit** (synchronous fire-and-forget) for notifications: inbox transitions, lifecycle, errors, and the contained immutable `tools/result` observation. Durable session events own turn and step boundaries.

24**A purpose-built middleware stack (koa-compose style)** and **an explicit phase state machine plugins insert into** — both would re-implement dispatch, disposal, and reload semantics that Cordis's native event system already provides; as Cordis effects, listeners get HMR and disposal for free.

103- **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.

13{14  "hooks": {15    "PreToolUse": [16      {17        "matcher": "Bash",18        "hooks": [19          {20            "type": "command",21            "command": "python3 /path/to/claude-code/examples/hooks/bash_command_validator_example.py"22          }23        ]24      }25    ]26  }27}

56def main():57    try:58        input_data = json.load(sys.stdin)59    except json.JSONDecodeError as e:60        print(f"Error: Invalid JSON input: {e}", file=sys.stderr)61        # Exit code 1 shows stderr to the user but not to Claude62        sys.exit(1)6364    tool_name = input_data.get("tool_name", "")65    if tool_name != "Bash":66        sys.exit(0)6768    tool_input = input_data.get("tool_input", {})69    command = tool_input.get("command", "")7071    if not command:72        sys.exit(0)7374    issues = _validate_command(command)75    if issues:76        for message in issues:77            print(f"• {message}", file=sys.stderr)78        # Exit code 2 blocks tool call and shows stderr to Claude79        sys.exit(2)

5The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception points ([the interception extension-points Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)); a "native hook" is just an ordinary Cordis plugin on those extension points. These packages are the **bridges** that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.