Turtle
f290a8b851
`dsh` shipped two config trees that were 43 rows the same: apps/cli/cordis.yml composed web as 74 flat rows, while the TUI booted examples/tui-agent/cordis.yml whose single `@deepseek-ai/dsh-tui-demo` row mounted twelve plugins behind a twenty-key pass-through Config. Neither file was what its location claimed — apps/cli hardcoded the "example" as the product default and the "demo" bundle was the application — and every capability change had to be made twice. - apps/cli/base.cordis.yml holds the 43 shared rows; tui.cordis.yml and web.cordis.yml are patch lists stating only what differs per surface - overlays apply as SIBLING patch lists at one include level, because include patches never cross an include boundary. Precedence: base < surface < (--config | personal ~/.dsh/config.yaml) < launcher flag/profile patches - `--config` now applies an overlay INSTEAD OF the personal one, so a demo or test tree never inherits the user's route; new `--config-replace` boots a file as the entire tree (the old `--config` behaviour). Both survive /resume - vendor/include: index each `insert`ed row as it is added so a later patch can configure or disable it. Upstream built the id index once before the patch loop, leaving every surface-only row — the whole TUI front door — silently unpatchable from user config. Logged as local modification 8 - session identity moves to dsh-agent-loop's CONFIGURED_AGENT_IDENTITIES_KEY; dsh-tui's MAIN_SESSION_ID_KEY is deleted (only the bundle read it) - delete examples/tui-agent, examples/cordis-agent, packages/examples/tui-demo; TUI tests → apps/cli/tests, cordis e2e → packages/cordis/tool-cordis/tests, examples/code-mode survives as an overlay leaf - `dsh web` gains --config, threaded into AppCLIEntry as an extra overlay Three latent defects surfaced and are fixed here: the TUI captured the optional sessionQuery service once at construction and could permanently disable /resume when it won the mount race; the session-store root silently reverted to a project-local ./.sessions; --config-replace was dropped by the resume handoff. Verified by booting each tree through the real Loader (TUI 55 entries, web 75, zero unsettled) rather than reading YAML. All eight terminal snapshots replay byte-identically; 14/14 PTY smoke, 112/112 snapshots, 25/25 doc-sync, hygiene and lint clean.
96 lines
3.3 KiB
Markdown
96 lines
3.3 KiB
Markdown
# 1. Your first plugin
|
|
|
|
English | [中文](01-first-plugin.zh.md)
|
|
|
|
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](index.md#setup)), create `hello.ts`:
|
|
|
|
```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`:
|
|
|
|
```yaml
|
|
- 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](03-services.md)), not from position in the file.
|
|
|
|
## Run it
|
|
|
|
```sh
|
|
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](../../apps/cli/base.cordis.yml), for example, is a longer plugin composition.
|
|
|
|
## The two other plugin shapes
|
|
|
|
A function is the most common shape, but Cordis accepts three:
|
|
|
|
```ts
|
|
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](03-services.md) covers when the class form earns its place.
|
|
|
|
## Try breaking it
|
|
|
|
Make `apply` throw:
|
|
|
|
```ts ignore-check
|
|
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](02-lifecycle-and-effects.md) — what happens when a plugin unloads.
|
|
|
|
[](https://github.com/deepseek-harness/deepseek-harness)
|