Yichen Jiang
a45aa28ca6
Master removed the TUI package, the `meta` and `upgrade` subcommands, and `--config-replace`, and made raw `dsh` require a `--config` overlay. Resolved onto that shape: - Dropped this branch's TUI edits with the surface itself, including `tui.cordis.yml`, `runTui`, and the TUI keyless PTY smoke. - Dropped the `--config-replace` plumbing rather than reintroducing a flag master deliberately removed. The gap this branch fixed remains: `dsh -p` still could not name its composition, so it keeps `--config`. - Kept this branch's deletion of the personal `$DSH_HOME/config.yaml` layer, which master still carried, and provided the environment snapshot in the new raw `runConfig` surface alongside web and headless. - Ported the headless shutdown PTY test off the personal overlay onto a named `--config` file, which is what proves that flag now exists on `-p`.
73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# Configuration
|
|
|
|
English | [中文](config.zh.md)
|
|
|
|
Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports, avoiding a second hand-maintained reference.
|
|
|
|
## Start from a real configuration
|
|
|
|
The repository examples are runnable configurations and the most reliable starting points for a new project:
|
|
|
|
- [the shared `dsh` base](../../../apps/cli/config/base.cordis.yml) provides the common model, tools, persistence, policy, and telemetry rows; raw `dsh --config <path>` requires a patch list that selects deployment-specific agents and front doors.
|
|
- [the Web overlay](../../../apps/cli/config/web.cordis.yml) adds the browser host, Workspace management, browser interaction, and client plugins.
|
|
- [headless-agent](../../../examples/headless-agent/cordis.yml) exposes the coding composition as a one-shot task.
|
|
- [acp-agent](../../../examples/acp-agent/cordis.yml) exposes fresh sessions to programmatic ACP clients.
|
|
|
|
A minimal configuration is a list of plugin entries:
|
|
|
|
```yaml
|
|
- id: llm-deepseek
|
|
name: '@deepseek-ai/dsh-llm-deepseek'
|
|
config:
|
|
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
|
models:
|
|
- deepseek-v4-flash
|
|
|
|
- id: bash
|
|
name: '@deepseek-ai/dsh-bash-local'
|
|
|
|
- id: agent-loop
|
|
name: '@deepseek-ai/dsh-agent-loop'
|
|
config:
|
|
agents:
|
|
- id: main
|
|
provider: deepseek-official
|
|
model: deepseek-v4-flash
|
|
```
|
|
|
|
## Plugin entries
|
|
|
|
`name` identifies an npm package or a local module relative to `cordis.yml`; `id` gives the plugin instance a stable identity; and `config` supplies plugin-specific configuration. Set `disabled: true` to skip an entry temporarily.
|
|
|
|
```yaml
|
|
- id: local-tool
|
|
name: './src/my-tool.ts'
|
|
disabled: false
|
|
config:
|
|
toolName: my_tool
|
|
```
|
|
|
|
Plugins load in file order. Place plugins that depend on services after the applications or capability plugins that provide them. Missing models, tools, and plugins fail as early as possible instead of being silently ignored.
|
|
|
|
## CLI overlays
|
|
|
|
Raw `dsh --config <path>` requires a patch list and applies it directly over `base.cordis.yml`; the named file is not a complete replacement tree. `dsh web` and `dsh -p` compose `base.cordis.yml` and `web.cordis.yml`, then any `--config <path>` overlay, then the launcher's own CLI-flag patches. No overlay is discovered on disk: naming a file is the only way to compose your own tree, and `dsh -p` accepts `--config` for exactly that reason.
|
|
|
|
A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
|
|
|
|
## JavaScript values and environment variables
|
|
|
|
The Cordis loader evaluates runtime expressions tagged with `!!js`. Keep API keys and other secrets in the gitignored `.env` file at the repository root, never in committed configuration.
|
|
|
|
```yaml
|
|
config:
|
|
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
|
cwd: !!js process.cwd()
|
|
```
|
|
|
|
The tag is `!!js`, not `!js`.
|
|
|
|
## Exact configuration reference
|
|
|
|
The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability interfaces](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it.
|