deepseek-harness/docs/user/develop/basic/config.zh.md

插件配置

English | 中文

让你的插件接受用户在 cordis.yml 中传入的配置。

定义 Config 类型

在插件中导出一个 Config 类型和同名的 Schemastery schema；默认值直接写在 schema 中：

import type { Context } from 'cordis'
import Schema from 'schemastery'

export const name = 'my-plugin'

export interface Config {
  greeting: string
  maxRetries: number
  verbose?: boolean
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

export function apply(ctx: Context, config: Config) {
  console.log(config.greeting)  // User value or schema default.
}

用户在 cordis.yml 中这样使用：

- name: './src/my-plugin.ts'
  config:
    greeting: 'Hi there'
    maxRetries: 5

插件加载时，Cordis 会通过导出的 schema 校验配置，并填充未提供字段的默认值。不要导出普通对象作为 Config，因为它不满足 Cordis 要求的 Standard Schema 接口。

Schema 校验

对于需要严格校验的场景，使用 Schemastery 定义 schema：

import type { Context } from 'cordis'
import Schema from 'schemastery'

export const name = 'validated-plugin'

export interface Config {
  apiKey: string
  timeout: number
  mode: 'fast' | 'accurate'
}

export const Config = Schema.object({
  apiKey: Schema.string().required(),
  timeout: Schema.number().default(30000),
  mode: Schema.union(['fast', 'accurate']).default('fast'),
})

export function apply(ctx: Context, config: Config) {
  // config is validated and type-safe.
}

Schema 在插件加载时执行校验。如果配置不合法，插件会加载失败并给出明确错误信息。

设计原则

无硬编码可调参数

Harness 的约定：任何两个部署可能想要不同值的东西，都应该是配置字段。

// Wrong: hardcoded timeout.
const TIMEOUT = 30000

// Correct: configurable.
export interface Config {
  timeoutMs: number  // Defaults to 30000.
}

检验标准：能否在 cordis.yml 中改变这个值，而不需要修改代码？

配置错误要响亮

如果配置引用了未注册的 LLM 提供方路由或其他不存在的资源，应该尽早报错，而不是静默跳过：

import type { Context } from 'cordis'
import type {} from '@deepseek-ai/dsh-llm'

export interface ModelConfig {
  provider: string
}

export function apply(ctx: Context, config: ModelConfig) {
  if (!ctx.llm.listProviders().some(provider => provider.id === config.provider)) {
    throw new Error(`LLM provider "${config.provider}" is not registered`)
  }
}

配合 HMR

配置变更会触发插件热替换：修改 cordis.yml 中某个插件的 config，框架会卸载旧实例、加载新实例。由于注册都是效果（自动清理），这个过程是安全的。

下一步

• 插件与生命周期 — 深入了解插件的完整生命周期
• 服务与依赖 — 让你的插件对外提供服务