DeepSeek Harness Config 与 Schemastery

2026-09-08 00:00    #AI   #工具   #DeepSeek  

让插件接受 cordis.yml 传入的配置，做到"配置与代码分离"。

导出 Config 类型与同名 schema

 1// 文件路径：scratch-plugin/src/my-plugin.ts
 2import type { Context } from '@deepseek-ai/cordis'
 3import Schema from '@deepseek-ai/schemastery'
 4
 5export const name = 'my-plugin'
 6
 7// Config 接口：定义插件接受哪些配置项
 8export interface Config {
 9  greeting: string // 问候语
10  maxRetries: number // 最大重试次数
11  verbose?: boolean // 是否输出详细日志（可选）
12}
13
14// 同名的 Config schema：默认值写在这里
15export const Config: Schema<Config> = Schema.object({
16  greeting: Schema.string().default('Hello'),
17  maxRetries: Schema.number().default(3),
18  verbose: Schema.boolean().default(false),
19})
20
21// apply 的第二个参数就是校验后的配置
22export function apply(ctx: Context, config: Config) {
23  console.log(config.greeting)
24}

在 cordis.yml 里传入配置

1# 文件路径：scratch-plugin/cordis.yml
2- insert:
3  - id: hello
4    # 插件路径必须是绝对路径
5    name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
6    config:
7      greeting: 'Hi there, runoob!'
8      maxRetries: 5

插件加载时，Cordis 通过导出的 schema 校验配置，并填充未提供字段的默认值。上面没写 verbose，会取 schema 默认值 false。

Schema 校验（更严格约束）

 1// 文件路径：scratch-plugin/src/validated-plugin.ts
 2import type { Context } from '@deepseek-ai/cordis'
 3import Schema from '@deepseek-ai/schemastery'
 4
 5export const name = 'validated-plugin'
 6
 7export interface Config {
 8  apiKey: string // 必填
 9  timeout: number // 超时毫秒数
10  mode: 'fast' | 'accurate' // 只能取这两个值之一
11}
12
13export const Config = Schema.object({
14  apiKey: Schema.string().required(),
15  timeout: Schema.number().default(30000),
16  mode: Schema.union(['fast', 'accurate']).default('fast'),
17})
18
19export function apply(ctx: Context, config: Config) {
20  // config 已经过校验，类型安全
21}

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

设计原则：无硬编码可调参数

1// 错误：把超时时间硬编码
2const TIMEOUT = 30000
3
4// 正确：定义为配置字段，默认值仍由 schema 提供
5export interface Config {
6  timeoutMs: number // 默认 30000
7}

检验标准：能否在 cordis.yml 中改变这个值，而不需要修改代码？如果能就是合格的可调参数；如果不能，就要提成配置字段。

硬编码是把本应可调的值写死在代码里。它让"改配置"变成"改代码加重新部署"，是生产事故的常见来源。

配合 HMR：配置热替换

要点