DeepSeek Harness 无头智能体组装拆解

DeepSeek 开源的 agent 框架 deepseek-harness 里，examples/headless-agent 是一个值得单独拿出来讲的示例：它用一份 cordis.yml 组合配置，把模型适配器、本地执行工具、会话持久化、子智能体编排等 25 个插件逐条挂载成一台完整的无头编码智能体。所有能力都写在同一份清单里，哪个接缝接了哪个插件一目了然，相当于框架组合式设计的一张装配图。

一条命令跑完一轮任务

这个示例对应的产品命令是 dsh 加 --profile headless 参数。它接受一个非空任务，创建并持久化一个新会话，把最终的 assistant 文本打印到标准输出后退出：进程不进入交互界面，标准输出保持格式纯净，既能在脚本里当一次性工具，也适合做回放测试。

无头智能体插件组装全景：五组插件各管一段

快照套件走的是另一条通道：一个仅供测试使用的 JSONL 驱动器运行这份配置，在结果记录之前按 JSONL 发出会话事件供断言使用。这条事件流不是受支持的 CLI 输出格式，子会话也只通过父会话的工具事件和结果对外显示。

密钥与配置：不进组合文件

清单头两个插件负责配置面。settings 插件挂载用户设置文档，对应 DSH_HOME 下的 settings.yaml，支持热更新，其中的 llm-deepseek 段落可以在不重启进程的情况下覆盖适配器入口配置。credentials 插件管凭据：适配器每次请求时现场解析 DEEPSEEK_API_KEY，优先取进程环境，其次读 owner-only 的凭据文件，两者都热更新，所以整份组合文件里不内联任何密钥。

模型与执行：本地工具面

llm-deepseek 是 DeepSeek 官方适配器，示例默认开启 thinking，推理力度 effort 设为 max，注册 deepseek-v4-pro 与 deepseek-v4-flash 两个模型，上下文窗口都是 128000。执行面由一串插件组成：subprocess 为 bash 执行器管理子进程组，bash 本地执行器默认 60 秒超时；fs-local 提供本地文件系统，fs-observation-policy 抢在面向模型的文件工具之前加载策略，写入和编辑必须针对观察过的文件，最后由 tool-fs 统一暴露给模型。

会话主干：持久化、检查点与压缩

agent-spine 预创建一个全新的 main 智能体，默认钉在 deepseek-v4-flash 上，原因是 goal 与 ralph 的回放语料都录在这个模型上；工作区上下文上限 65536 字节，persona 只有短短两句话：通过运行代码或测试来验证工作，回答保持简短并基于事实。

persistence 把会话落盘到 .sessions 目录的 JSONL 文件，默认 zstd 压缩，进入快照模式时自动切回不压缩；checkpoint-policy 决定检查点时机；token-meter 与 compaction-basic 配合，在派生历史逼近上下文窗口时把较旧的区间摘要压缩，阈值 0.8、保留比例 0.16、单次摘要上限 8192 token、失败重试一次；session-projection 登记子智能体的持久身份，缺了它，读取子智能体目录会直接报错。

一轮无头任务从任务参数到进程退出的完整流程

委派与编排：spawn、fork 与工作流

subagent 插件提供两个进程内后端：spawn 生成全新子会话，fork 复用一段已完成的会话前缀。tool-subagent 挂出可续聊模式的 subagent 工具；tool-subagent-fork 复用同一个包、保持一次性执行，并且因为这个示例没有挂任务服务而关闭了后台运行；两者最大深度都是 1。tool-subagent-control 注册全局的 send_message，report 工具只安装在可续聊的子会话作用域里。

编排侧，workflow-worker-thread 把模型写好的 JavaScript 脚本里的 agent() 调用扇出到 spawn 后端执行；tool-ralph 用一个固定消费者演示全新智能体的 Ralph 迭代，不改动工作流工具本身；tool-todo 的 todo_write 每次整表替换任务清单，并允许多个任务同时处于进行中。

两个官方变体

advanced.cordis.yml 用 include 加补丁扩展基础配置：模型换成 deepseek-v4-pro，工具模式改为 both，插入 code-runtime 与 Cordis 自省工具。e2b.cordis.yml 再进一步，把文件系统与子进程换进一台短命的 E2B 云沙箱，同时插入 PTY、终端与 LSP 工具。它守住一条不变式：e2b 的 cwd、sandbox-policy 的 workspaceRoot 与 bash 默认工作目录必须指向同一个远程目录，一旦错位，所有工具调用都会以远程生成失败告终。沙箱超时 300 秒，超时或资源释放时被终止删除，而会话状态与模型调用始终留在宿主上。