0 Fork 0

Files

T

imccyu ec601ca13d build(vendor): rescope the vendored Cordis packages into @deepseek-ai

Machine-produced by `pnpm run rescope-vendor --apply` plus the regeneration it
prints: `pnpm install` for the lockfile, `pnpm run gen-third-party-notices`,
`verify-translation-pairing --write` for the touched bilingual pairs,
`gen-doc-graphs`, and one typert snapshot whose ids embed character offsets.
`pnpm run rescope-vendor --check` verifies the result.

Renames nine vendored packages (cordis, cosmokit, schemastery and the six
@cordisjs plugins) and every reference that resolves them: manifest names and
dependency keys, module specifiers including declare-module merges, cordis.yml
plugin names, tsconfig paths, every Markdown fence, and `docs/` prose.
Directory names, upstream versions, and dependency ranges are unchanged, so
vendor/README.md still reads as an upstream snapshot; its manifest table gains
an upstream-name column so THIRD_PARTY_NOTICES keeps MIT attribution pointed
at each fork's origin.

The tutorial tier follows the rename end to end: its yaml fences named plugins
the Loader can no longer resolve, its `ts ignore-check` fences disagreed with
the compiled fences beside them, and its prose quoted both. The contracts that
told readers to keep upstream names — the root convention and the vendoring
cookbook's tree comment and manifest invariant — now say to rescope instead.

Two rules read `@deepseek-ai/` as "another workspace plugin": the client bundle
purity gate now names the vendored libraries a browser bundle inlines, and the
files where a bare `cordis` is an agent-preset id keep that product data.

2026-08-10 22:04:13 +08:00

3.7 KiB

Raw Blame History

Services and dependencies

English | 中文

A service is a capability one plugin exposes to other plugins. inject declares the services a plugin requires.

What is a service?

In Harness, tools, llm, and agents are services. Each is a named capability mounted on ctx:

ctx.tools    // ToolRegistry service
ctx.llm      // LLM service
ctx.agents   // Agent service

Any plugin can provide a service for other plugins to consume.

Consume a service

Declare inject to use an existing service:

export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools exists and is ready here.
  ctx.tools.register(/* ... */)
}

When apply runs, every service declared by inject is ready. If a service is not ready, the plugin waits instead of running.

Provide a service

Extend Service

import { Service, type Context } from '@deepseek-ai/cordis'

export default class MetricsService extends Service {
  static inject = ['llm']  // A service may depend on other services.

  constructor(ctx: Context) {
    super(ctx, 'metrics')  // 'metrics' is the service name.
  }

  // Public service method.
  record(event: string, value: number) {
    // ...
  }
}

After loading this plugin, consumers access the service as ctx.metrics:

export const inject = ['metrics']

export function apply(ctx: Context) {
  ctx.metrics.record('tool_call', 1)
}

Declare its type

Use TypeScript declaration merging to type ctx.metrics:

import { Service, type Context } from '@deepseek-ai/cordis'

declare module '@deepseek-ai/cordis' {
  interface Context {
    metrics: MetricsService
  }
}

export default class MetricsService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'metrics')
  }

  record(event: string, value: number) { /* ... */ }
}

Dependency behavior

Required and optional dependencies

// Required: the plugin does not load while the service is absent.
export const inject = ['tools']

// Optional: omit inject and query with ctx.get() at the use site.
export function apply(ctx: Context) {
  const metrics = ctx.get('metrics')
  metrics?.record('plugin_loaded', 1)
}

When a service disappears

If a required service disappears while the application is running, for example because its provider unloads:

Dependent plugins dispose automatically.
They load again when the service returns.

This prevents a plugin from calling a service that no longer exists.

Service isolation

cordis.yml can isolate services so separate plugin groups see separate instances of the same service:

- id: group-a
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    bash: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 5000
    - name: './src/plugin-a.ts'

- id: group-b
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    bash: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 60000
    - name: './src/plugin-b.ts'

plugin-a and plugin-b each see the Bash instance in their own group, with no cross-group effect.

Built-in Harness services

The repository generates the service names, public methods, and source locations into each service's subsystem page. Use those generated regions and the service's TypeScript interface while developing a plugin; do not maintain a second static list.

Next steps

Event system — communicate between plugins without tight coupling
Capability layering — use services as capability interfaces

3.7 KiB Raw Blame History