0 Fork 0

Files

T

Yichen Jiang 8ddc53f7a0 feat(cli)!: complete --config on every surface and delete the personal overlay

$DSH_HOME/config.yaml was an implicit composition layer: if the file existed,
every launch applied an arbitrary Loader patch graph over the shipped tree,
kept live by a dedicated HMR watcher. Three costs came from the implicitness,
not the capability. A patch replaces its target row's whole config, so a file
written months ago pins that row to the field set it knew and every default
the shipped tree later adds silently stops applying. It competed with the
typed settings namespaces llm-deepseek and llm-pi-ai already register, so
which one wins was a function of layer order rather than meaning. And the
explicit escape hatch it was supposedly redundant with did not exist on every
surface: dsh -p, dsh meta, and dsh upgrade all rejected --config, so for them
the implicit file was the only composition route at all.

Complete the explicit layer first: --config and --config-replace now work on
every booting surface. A headless --config-replace tree must still mount a
webserver row, because that surface reaches its own agent over the same HTTP
gateway the browser uses; AppCLIEntry names that contract in the failure
instead of reporting a bare missing service.

Then delete the implicit one. PERSONAL_CONFIG_FILENAME, loadPersonalPatches,
watchPersonalPatches, and the config-only HMR row mounted for it are gone; a
file left at that path is inert, and --dump-config no longer reads the Harness
home. --config therefore stops *replacing* the personal overlay and simply
*is* the user overlay.

No migration: a user who wants the old behavior names the same file
(dsh --config ~/.dsh/config.yaml), which a shell alias makes permanent.

2026-08-04 15:25:04 +08:00

3.3 KiB

Raw Blame History

Configuration

English | 中文

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 plus the tui.cordis.yml overlay combines the DeepSeek model, Bash, filesystem, compaction, subagents, workflows, and the interactive TUI.
headless-agent exposes the coding composition as a one-shot task.
acp-agent exposes fresh sessions to programmatic ACP clients.

A minimal configuration is a list of plugin entries:

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

- 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

The TUI composes base.cordis.yml and tui.cordis.yml, then applies the optional dsh --config <path> overlay. dsh --config-replace <path> instead boots the named file as the complete tree, without any shipped layer. Every booting surface takes both flags — dsh -p, dsh web, dsh meta, and dsh upgrade included — because naming a file is the only way to compose your own tree.

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.

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 lists every current field, type, and default. For composition concepts, continue to the architecture and capability interfaces. To create a configuration, copy the closest entry from the examples overview and adapt it.

3.3 KiB Raw Blame History