发布日期：2026-09-14 | 分类：AI与智能服务

DeepSeek Harness（命令名 dsh）是 DeepSeek 于 2026 年 8 月 13 日以开发者预览版形式开源的 Agent 框架，采用"一切皆插件"架构，模型、工具、会话、循环、调度等能力全部由 Cordis 插件组合而成。面向需要跑几十分钟到数小时的长任务，它把三件事拆成了三组独立插件：goal 让一个完成目标跨多轮自动续跑并持久化到会话日志，默认上限 256 轮；compact 在上下文占用达到模型窗口 80% 时自动把旧历史压成一段摘要，也可以用 /compact 手动触发；后台 job 让耗时命令和子 Agent 以 run_in_background 方式立即返回 job id，由 job_output、job_list、job_kill 三个工具收集与终止，每个 Agent 默认最多并发 10 个。本文依据官方 GitHub 仓库的子系统文档、包 README 与配置目录，逐项梳理三者的状态机、默认参数、命令语法和配合方式，并说明接入模型端点的位置。文中数据截至 2026 年 9 月 14 日。

DeepSeek-Harness长任务-20260914-img1.png

DeepSeek Harness 是什么，长任务为什么要拆成三件

DeepSeek Harness 是 DeepSeek 于 2026 年 8 月 13 日发布并以 MIT 协议开源的 Agent 框架，官方中文 README 的定义是"由 DeepSeek AI 开发的开源 agent harness（智能体框架）"，构建于"一切皆插件"架构之上，由 Cordis 插件系统驱动。官网 deepseek.com/harness 把它概括成一句话：Agent = Model + Harness，模型是 Agent 的灵魂，Harness 给予 Agent 理解环境、使用工具并在真实场景中持续工作的能力。

几个可核对的现状数据：GitHub 仓库 deepseek-ai/deepseek-harness 在 2026 年 9 月 14 日的 Star 数为 222,693；npm 包 @deepseek-ai/dsh 的 latest 标签为 0.1.5-rc.1，发布于 2026 年 9 月 10 日，next 标签为 0.1.5-rc.2；仓库 README 明确标注项目处于 developer preview 阶段，"将会出现破坏兼容性的变更"。官网列出四种运行模式，其中标准模式的官方描述是"功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流"，目标（goal）和子代理是长任务能力的一部分。

长任务在 Agent 框架里有三个互相独立的难点：任务目标如何跨越多次模型调用不丢、上下文涨满后怎么办、耗时几分钟的命令怎么不阻塞主循环。DeepSeek Harness 没有把它们做进一个"长任务模式"，而是分别对应 goal、compaction、jobs 三组插件包，官方子系统文档把 compaction 明确标为"可选能力（optional capability），不属于 Agent 循环主干"，goal 与 jobs 同样是独立插件包，都可以在配置层单独挂载或移除。

goal：一个目标跨多轮自动续跑

goal 是 DeepSeek Harness 中"一个会话保留一个长期完成目标"的插件组，官方包文档的定义是：dsh-goal 让一个长时间运行的完成目标跨越多个轮次、会话恢复、分叉和进程重启而持久存在。它由三个包组成：dsh-goal 负责存状态，dsh-tool-goal 给模型 get_goal、create_goal、update_goal 三个工具，dsh-goal-round-driver 负责在 Agent 空闲时自动排入下一轮。

官方文档给出的层级是 Goal → Goal Round → Turn → Step：一个目标包含若干轮（round），每一轮变成一个由目标发起的会话 turn，一个 turn 内可以有任意多次模型与工具调用的 step。人类在同一会话里发的消息不算目标轮次，不消耗轮次配额。目标有四个持久化阶段：active、paused、blocked、complete，另外还有一个不落盘的进程内标记 armed/disarmed，决定驱动器是否允许自动续跑。

三个默认参数值来自官方配置目录（config-catalog，2026 年 9 月）：

  • defaultMaxGoalRounds：目标轮次上限，默认 256，创建时可以单独指定；轮次耗尽时驱动器记录一条 code 为 round-limit 的 blocked 状态。

  • blockedAfterConsecutiveRounds：模型自行报告 blocked 前，同一阻塞条件必须持续的最少连续轮数，默认 3。官方系统提示词原文要求"困难、不确定或仍有有用工作可做都不算 blocked"。

  • 会话恢复后自动禁用：官方文档写明，任何会话恢复或分叉之后，active 状态的目标都会被置为 disarmed，Agent 不会自行继续，直到人类明确 resume。

人类侧的控制入口是 /goal 命令，语法整理自 dsh-command-goal 的设计说明：

命令

作用

/goal

查看目标、当前阶段、已用轮次/上限、armed 或 disarmed

/goal 目标描述

创建一个 active 且 armed 的目标；有未完成目标时直接报错，不会静默替换

/goal edit 目标描述

修改目标文本，不改变阶段与激活状态

/goal pause / resume / clear

暂停、恢复、清除；clear 后会话日志仍保留墓碑记录

2026 年 9 月 1 日归档的一条修复说明值得长任务用户注意：此前在 Web UI 点击"暂停目标"只会把状态改为 paused，正在运行的模型 turn 会继续执行，甚至能在同一 turn 内调用 update_goal resume 撤销暂停。修复后，由宿主（Web 按钮）发起的 pause 会直接中止正在运行的 turn，模型自己发起的 pause 则允许它正常收尾。

compact：上下文到阈值自动压缩，也能手动 /compact

compaction 是 DeepSeek Harness 中把旧对话历史替换为一段摘要的可选能力，官方子系统文档把它拆成三层：dsh-compaction 定义接口，dsh-compaction-basic 是默认后端，dsh-command-compact 提供人类可用的 /compact 命令。压缩成功后，被选中的旧历史区间被一条摘要消息替换，最近的历史保持不动。

默认后端 dsh-compaction-basic 的策略参数（官方配置目录，2026 年 9 月）：

  • thresholdRatio 0.8：上下文达到模型窗口的 80% 时触发压缩。

  • retainRatio 0.16：保留最近约 16% 窗口的原始上下文不压缩，也可以改用绝对值 retainTokens。

  • maxTokens 8192：生成摘要时的输出上限；摘要模型默认沿用当前对话模型，也可以通过 summarizationProvider 与 summarizationModel 指定另一个模型。

  • compactionRetries 1、maxOverflowRetries 1：首次压缩后仍超阈值时再试 1 次；模型返回上下文溢出错误后最多恢复重试 1 次，设为 0 关闭。

压缩前还有一道确定性的工具结果裁剪（dsh-compaction-tool-result-pruner）：单条工具输出超过 8192 个 Unicode 码点时，保留开头 4096 与末尾 1024 个码点，中间用占位替换，先不调用模型就能腾出空间。官方文档说明，自动压缩在每个 step 开始前的 agent/pre-step 阶段执行，区间边界会保持工具调用与工具结果配对完整，但不要求保留整个 turn，因此一个超大 turn 里较早的 step 也能被压掉。

手动路径是 /compact 命令。官方 README 写明它不消耗模型轮次，执行后报告被压缩的历史条目数和估算节省的 token 数；没有可压缩历史时返回"No compactable history yet."；Agent 正在执行 turn 或已有压缩进行中时返回不可用提示；压缩期间用户发送的提示会排队，压缩结束后再开始。每次压缩都在会话日志里以 compaction/start、compaction/summary、compaction/end 三个事件包裹，进程崩溃只会留下一个能被识别的孤儿 start 记录，不会出现假的完成标记。

后台 job：耗时命令和子 Agent 都走同一套任务运行时

后台 job 是 DeepSeek Harness 的通用长运行任务运行时，官方子系统文档命名为 Background Task Runtime：bash 命令、PTY 会话和子 Agent 都通过同一个 ctx.jobs 注册中心登记，拿到形如 bash-1、subagent-2 的 job id，再由同一组工具读取和终止。

进入后台的方式是在 bash 工具调用里传 run_in_background: true。官方 dsh-tool-bash 文档写明，此时调用立即返回 job id，不再受超时限制，命令在 Agent 处理其他工作时继续运行；子 Agent 工具 dsh-tool-subagent 同样支持 run_in_background 参数，默认开启。三个控制工具由 dsh-tool-jobs 提供：

工具

作用

官方说明中的关键行为

job_output(job_id, wait?, timeout_ms?)

读取输出

流式任务只返回上次读取后的增量；默认非阻塞，wait 为 true 时等待，默认 30 秒，单次最长 10 分钟

job_list()

列出本 Agent 的任务

每行格式为 id、kind、status、label

job_kill(job_id, reason?)

请求终止

先进入 stopping，工作真正停止后才记为 killed

两条对长任务实际影响最大的规则：

  1. 并发上限：进程内注册中心 dsh-jobs-local 的 maxConcurrentJobsPerOwner 默认为 10，统计的是 running 加 stopping 的任务数，也就是 job_kill 之后资源尚未释放的任务仍占名额；超限时 start 直接报错并提示模型先 job_kill 或等待。这条限制来自 2026 年 8 月 11 日归档的修复说明，原因是 maxParallelToolCalls 只能限制单个 step 内的并行调用，管不住跨 step 存活的后台进程。

  2. 完成通知：任务结束时 Agent 收到会话内消息"background job 〈id〉 finished"，忙碌中的 Agent 在下一个 step 收到注入，空闲的 Agent 会被唤醒开一个新 turn。唤醒有预算：maxConsecutiveWakes 默认 3，连续被唤醒 3 次后通知降级为注入，收到任何用户消息后预算重置，防止"被唤醒的 turn 又启动一个后台任务再唤醒自己"的自激链。

三件怎么配合：一次长任务的实际流程

三组插件在一次长任务中的分工，可以按官方文档描述的机制拼成下面这条链：

  1. 用户在 Web UI 或 TUI 输入 /goal 加目标描述，或直接用自然语言下达长期任务，模型通过 create_goal 建立目标，默认 256 轮上限。

  2. 驱动器在 Agent 空闲时排入一轮 goal_round 提示，提示里带 JSON 引号包裹的目标文本和"第几轮/上限"。

  3. 模型在一轮内遇到耗时命令（测试套件、构建、爬取）时用 run_in_background 起后台 job，继续做其他工作，完成通知到达后用 job_output 收集。

  4. 上下文接近模型窗口 80% 时，压缩后端先裁剪超长工具结果，再把旧区间替换为摘要；用户也可以在 Agent 空闲时手动 /compact。

  5. 目标达成时模型调用 update_goal complete；同一阻塞条件持续 3 轮才允许报 blocked；用户随时可 /goal pause 中止当前 turn。

  6. 会话恢复后目标处于 disarmed，需要用户 /goal resume 或用自然语言要求继续，模型才能重新 arm。

三组插件在配置文件里是独立条目，官方 README 给出的最小挂载写法如下（YAML，字段名以官方配置目录为准）：

- name: '@deepseek-ai/dsh-goal'
  config:
    defaultMaxGoalRounds: 256
- name: '@deepseek-ai/dsh-tool-goal'
  config:
    blockedAfterConsecutiveRounds: 3
- name: '@deepseek-ai/dsh-goal-round-driver'

- name: '@deepseek-ai/dsh-compaction-basic'
  config:
    thresholdRatio: 0.8
    retainRatio: 0.16
- name: '@deepseek-ai/dsh-command-compact'

- name: '@deepseek-ai/dsh-jobs-local'
  config:
    maxConcurrentJobsPerOwner: 10
- name: '@deepseek-ai/dsh-tool-jobs'

官方文档同时提醒两条边界：SDK 一次性调用（sdk-minimal）默认不挂 goal 栈，因为它的结果 API 只结算一个物理 turn，不应静默变成长期目标；没有挂载 dsh-tool-jobs 的组合无法启动后台任务，会报"background jobs unavailable"。

模型端点在哪里配

长任务对模型的消耗集中在 goal 的多轮续跑和 compact 的摘要调用上，这两项都走同一个模型路由。官方 Web UI 指南写明，模型在"Settings → Models"中配置，填入 DeepSeek API key 保存后立即生效、无需重启；模型配置指南另外覆盖其他供应商和自定义 OpenAI 兼容端点。压缩摘要如果不想占用主模型额度，可以在 compaction 配置里用 summarizationProvider 与 summarizationModel 指向另一条路由。

对于通过自定义 OpenAI 兼容端点接入多款主流大模型的团队，七牛云开发者中心 2026 年 8 月 24 日更新的 DeepSeek Harness 配置文档给出的填写位置是"设置 - 模型 - 自定义设置"，API 地址为 https://api.qnaigc.com/v1，模型 ID 在控制台模型广场查询。

小结

DeepSeek Harness 把长任务拆成 goal、compaction、jobs 三组可选插件，每组都有明确的状态机和可配置的默认值：目标 256 轮、压缩阈值 80%、后台任务每 Agent 并发 10 个。三者共享同一份仅追加的会话日志，目标变更、压缩区间、任务生命周期都能在日志里回放，这也是官网强调的"每一次运行都有迹可循"。项目仍处于开发者预览阶段，上述包名与字段名以 GitHub 仓库 docs/config-catalog.md 和各包 README 的当前版本为准，后续版本可能变化。本文数据截至 2026 年 9 月 14 日。

参考资料