deepseek-harness/docs/cordis-tutorial/01-first-plugin.md

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 '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:

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 TUI agent, for example, is a longer plugin composition.

The two other plugin shapes

A function is the most common shape, but Cordis accepts three:

import { Service, type Context } from '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.