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.3 KiB

Raw Blame History

1. Your first plugin

English | 中文

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), create hello.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:

- 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), not from position in the file.

Run it

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:

The launcher created a root Context and mounted the Loader plugin.
The Loader read cordis.yml, resolved ./hello.ts, and mounted it as a child plugin.
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, 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:

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 covers when the class form earns its place.

Try breaking it

Make apply throw:

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 — what happens when a plugin unloads.

3.3 KiB Raw Blame History