deepseek-harness/website/zh-CN/guide/config.md

配置文件

Harness 使用 cordis.yml 描述一个 Agent 加载哪些插件、以什么参数运行。

从例子开始

echo-agent 的配置

这是一开始的第一个 Agent 的完整配置：

# 热替换：修改代码后自动重载，不用手动重启
- id: hmr
  name: '@cordisjs/plugin-hmr'
  config:
    root: ['.']

# Mock 模型：从本地 `.ts` 文件加载，注册一个名为 `mock-llm` 的工具
# 本地模拟 LLM 响应，不联网
- id: mock-llm
  name: './src/mock-llm.ts'

# Echo 工具：收到文本后转大写返回
- id: echo-tool
  name: './src/echo-tool.ts'

# Bash 执行器：从 npm 包 `@deepseek-ai/dsh-bash-local`加载，提供 bash 命令执行能力
- id: bash
  name: '@deepseek-ai/dsh-bash-local'

# 应用主体：把 session 管理、tool 调度、agent loop 等组装成一个可交互的终端 Agent
# 只需告诉它用哪个模型 (`model`)、什么人设 (`persona`)
- id: stdio-agent
  name: '@deepseek-ai/dsh-stdio-agent'
  config:
    model: mock-echo
    persona: 'You are echo-agent, a demo agent.'
    welcome: 'echo-agent ready. Type a message ("echo <text>" triggers the tool).'
    persistenceRoot: './.sessions'

coding-agent 的配置

真实场景——接入 DeepSeek API，带完整工具链：

# 热替换：同上，开发时自动重载
- id: hmr
  name: '@cordisjs/plugin-hmr'
  config:
    root: ['.']

# LLM 后端：从 npm 包加载，具备接入 DeepSeek API 能力
# `!!js` 从环境变量读取密钥，不会写进配置文件
# `models` 声明该适配器能处理哪些模型名
- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    apiKey: !!js process.env.DEEPSEEK_API_KEY
    baseURL: !!js process.env.DEEPSEEK_BASE_URL
    models:
      - deepseek-v4-pro
      - deepseek-v4-flash

# Bash 执行器：让 Agent 能跑 shell 命令
# timeoutMs 设置单条命令的超时时间
- id: bash
  name: '@deepseek-ai/dsh-bash-local'
  config:
    timeoutMs: 60000

# 应用主体：和 echo-agent 一样的框架，只是配置不同
# `model` 指定默认使用哪个模型（要和上面 models 列表里的名字对应）
# `persona` 是系统提示词，{{model}} 会被替换为实际模型名
# `resumeSessionId` 设了就恢复旧对话，没设就每次新建
- id: stdio-agent
  name: '@deepseek-ai/dsh-stdio-agent'
  config:
    model: deepseek-v4-flash
    resumeSessionId: !!js process.env.RESUME_SESSION_ID
    persistenceRoot: './.sessions'
    welcome: 'agent REPL ready. Give it a coding task.'
    persona: |
      You are coding-agent, a coding assistant powered by the {{model}} model.
      Verify your work by running the code or tests. Keep answers brief and factual.

# 自动压缩：对话太长时自动总结旧内容，腾出上下文空间
# contextWindow 是模型能看到的 token 上限
# thresholdRatio 超过这个比例就触发压缩
- id: compact-basic
  name: '@deepseek-ai/dsh-compact-basic'
  config:
    contextWindow: 128000
    thresholdRatio: 0.8
    retainTokens: 20480
    maxTokens: 8192

# 子代理：把子任务分配给独立的 Agent 去做
# subagent 是服务注册，spawn/fork 是两种委派方式：
#   spawn — 全新子代理，不知道父级在聊什么
#   fork  — 继承父级对话上下文的子代理
# tool-subagent 把委派能力暴露给模型，toolName 是模型看到的工具名
- id: subagent
  name: '@deepseek-ai/dsh-subagent'

- id: subagent-spawn
  name: '@deepseek-ai/dsh-subagent-spawn'
  config:
    providerName: spawn

- id: subagent-fork
  name: '@deepseek-ai/dsh-subagent-fork'
  config:
    providerName: fork

- id: tool-subagent
  name: '@deepseek-ai/dsh-tool-subagent'
  config:
    provider: spawn
    toolName: subagent

- id: tool-subagent-fork
  name: '@deepseek-ai/dsh-tool-subagent'
  config:
    provider: fork
    toolName: subagent_fork

# 任务追踪：模型可以用 todo_write 记录和更新任务清单
- id: tool-todo
  name: '@deepseek-ai/dsh-tool-todo'

# 文件系统：让 Agent 能读写编辑文件
# fs-local 提供本地文件操作能力，cwd 是工作目录
# fs-policy 是安全策略——必须先读才能写，防止模型盲写
# tool-fs 把能力暴露给模型（read / write / edit 三个工具）
- id: fs-local
  name: '@deepseek-ai/dsh-fs-local'
  config:
    cwd: !!js process.cwd()

- id: fs-policy
  name: '@deepseek-ai/dsh-fs-policy'

- id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'

和 echo-agent 对比：同一个 dsh-stdio-agent 应用主体，只是把 mock 换成了真实 API，加上了更多工具插件。

语法详解

插件声明字段

每个插件条目支持以下字段：

字段	类型	必填	说明
name	string	是	插件来源（npm 包名或相对路径）
id	string	否	实例标识符，用于日志和调试
config	object	否	传递给插件的配置
disabled	boolean	否	设为 true 临时禁用该插件

插件来源 (name)

npm 包 — 已安装的 @deepseek-ai/dsh-* 包或第三方包：

- name: '@deepseek-ai/dsh-llm-deepseek'

相对路径 — 本地 TypeScript 文件（相对于 cordis.yml 所在目录）：

- name: './src/my-tool.ts'

环境变量 (!!js)

用 !!js 标签在配置中引用运行时表达式：

config:
  apiKey: !!js process.env.DEEPSEEK_API_KEY
  cwd: !!js process.cwd()

::: warning 是 !!js（两个感叹号），不是 !js。写错了会静默失败。 :::

环境变量从仓库根目录的 .env 文件自动加载（已被 gitignore）。

禁用插件

不想删配置但暂时不加载？加一行 disabled：

- id: compact-basic
  name: '@deepseek-ai/dsh-compact-basic'
  disabled: true
  config:
    contextWindow: 128000

各插件配置参考

stdio-agent（标准应用主体）

包名: @deepseek-ai/dsh-stdio-agent

字段	类型	默认值	说明
model	string	必填	使用的模型名，需与 LLM 适配器注册的名字一致
persona	string	''	系统提示词。支持 {{model}} 等模板变量
toolOrder	string[]	—	模型看到的工具顺序。省略则按字母排序
persistenceRoot	string	'./.sessions'	会话日志存储目录
welcome	string	'ready.'	启动时显示的欢迎信息
resumeSessionId	string	—	恢复指定会话 ID。留空则每次新建

llm-deepseek（DeepSeek 适配器）

包名: @deepseek-ai/dsh-llm-deepseek

字段	类型	默认值	说明
apiKey	string	$DEEPSEEK_API_KEY	API 密钥。省略则从环境变量读取
baseURL	string	$DEEPSEEK_BASE_URL 或官方地址	API 端点
models	string[]	['deepseek-v4-flash', 'deepseek-v4-pro']	注册的模型名列表
thinking	'enabled' | 'disabled'	'enabled'	是否开启思维链
reasoningEffort	'high' | 'max'	—	思维链深度（仅 thinking 开启时有效）

bash-local（Bash 执行器）

包名: @deepseek-ai/dsh-bash-local

字段	类型	默认值	说明
cwd	string	process.cwd()	命令执行的工作目录
timeoutMs	number	120000	单条命令的超时时间（毫秒）
maxTimeoutMs	number	600000	单条命令超时的上限（模型不能请求更久）
maxOutputBytes	number	64000	单次输出的内存上限（超出后溢出到临时文件）
graceMs	number	3000	kill 时从 SIGTERM 到 SIGKILL 的等待时间

compact-basic（自动压缩）

包名: @deepseek-ai/dsh-compact-basic

字段	类型	默认值	说明
contextWindow	number	必填	模型的上下文窗口大小（token）
thresholdRatio	number	必填	token 占用超过此比例时触发压缩（0-1）
retainTokens	number	必填	压缩后至少保留多少 token 的近期内容
maxTokens	number	必填	总结时的最大输出 token
summarizationModel	string	''（用当前模型）	专门用于总结的模型名
compactionRetries	number	必填	首次压缩后仍超标时的额外重试次数
auto	boolean	true	是否自动在每步前检查并触发压缩
charsPerToken	number	4	每 token 估算字符数。中文应设 1-2

fs-local（文件系统）

包名: @deepseek-ai/dsh-fs-local

字段	类型	默认值	说明
cwd	string	process.cwd()	工作目录，相对路径以此为基准

fs-policy（文件系统策略）

包名: @deepseek-ai/dsh-fs-policy

无配置项。加载即启用"必须先读才能写"的安全策略。

tool-fs（文件系统工具）

包名: @deepseek-ai/dsh-tool-fs

无配置项。加载后向模型暴露 read、write、edit 三个工具。

tool-web（Web 工具）

包名: @deepseek-ai/dsh-tool-web

字段	类型	默认值	说明
search	boolean	true	是否注册 web_search 工具
fetch	boolean	true	是否注册 web_fetch 工具
searchMaxResults	number	8	单次搜索返回的最大结果数

subagent-spawn / subagent-fork（子代理后端）

包名: @deepseek-ai/dsh-subagent-spawn / @deepseek-ai/dsh-subagent-fork

字段	类型	默认值	说明
providerName	string	'spawn' / 'fork'	注册到子代理服务的 provider 名称

tool-subagent（子代理工具）

包名: @deepseek-ai/dsh-tool-subagent

字段	类型	默认值	说明
provider	string	必填	使用哪个 provider（如 spawn、fork）
toolName	string	'subagent'	暴露给模型的工具名。多次加载时必须不同
agentOptions.model	string	—	子代理使用的模型名（省略则继承父代理）

tool-todo（任务清单）

包名: @deepseek-ai/dsh-tool-todo

无配置项。加载后向模型暴露 todo_write 工具。

hmr（热替换）

包名: @cordisjs/plugin-hmr

字段	类型	默认值	说明
root	string[]	必填	监听文件变更的目录列表

::: tip hmr 仅用于开发环境。它需要 node --expose-internals 启动参数，demo:* 脚本已自动添加。 :::

---

加载顺序

cordis.yml 的顺序就是加载顺序。推荐：

1. hmr — 热替换（仅开发时需要）
2. LLM 适配器 — 模型后端
3. 执行器 — bash、fs 等能力提供者
4. 应用主体 — dsh-stdio-agent 或 dsh-acp-agent
5. 附加插件 — compact、subagent、todo 等

应用主体内部已经捆绑了核心能力（session、tools、agent-loop），不需要手动加载。

下一步

• 开发插件 — 编写自己的插件
• API 参考 — 查看各插件完整接口