最近DeepSeek 开源了一个名为DSHDeepSeek Harness的项目它提供了一整套连接大模型与真实世界的 Agent 脚手架项目背后的核心理念可以概括为Agent Model Harness如果说 Model 是负责推理与决策的大脑那么 Harness 就是让这个大脑能够感知环境、调用工具并采取行动的身体DSH 并不是第一个 Harness 产品Codex、Claude Code、OpenCode、Pi、Kimi Code 等产品本质上都包含一套 Harness为什么这些产品最终呈现出相似的形态为什么大模型 Agent 的架构逐渐收敛到近似的结构本文将从 DSH 出发拆解 Harness 的设计理念与核心组成01 一切皆插件的 DSHDeepSeek Harness 构建在一个名为Cordis的插件内核之上其设计理念是Everything is a plugin在 DSH 中模型适配器、工具、技能、会话、沙箱、存储、Agent 循环、任务调度甚至 UI原则上都可以作为插件存在Cordis Kernel 本身不承载具体业务逻辑只负责插件的加载、卸载和依赖关系管理。开发者可以通过配置文件选择、替换或扩展任意能力而不必直接修改核心源码DSH 内置了四种运行模式Standard提供完整工具集包括文件编辑、Shell、搜索、Skills、Planning、Subagents 和 Workflows 等Code Mode通过 TypeScript SDK 向模型暴露工具使模型可以编写程序来编排多步操作而不是一次只调用一个工具Minimal仅保留persistent bash和str_replace_editor两个工具适合在尽可能纯净的环境中进行模型基准测试Creator用于组合自定义 Preset可以进行运行时检查和插件组合实验DSH 的插件化不仅体现了扩展性也体现了它对可追溯性的重视模型实际接收到的系统提示词、上下文注入、工具调用与结果、子智能体调度以及 API 对外暴露的推理信息都会被记录到一条只增不改的append-only session log中这正是 DSH 较有特点的地方它不把一次 Agent 任务仅仅看成一段聊天记录而是将其视为一条完整、不可被静默改写的执行事件链这条事件链可以在 Trajectory 视图中按照来源逐条回放。基于同一条事件流系统可以实现resume、fork、search和replayresume从已有事件链的末尾恢复状态并继续追加新事件fork从某个历史节点创建分支尝试另一条执行路径search在统一事件流中检索消息、工具调用、上下文注入或子智能体事件replay从头回放事件重建当时的执行轨迹其中resume和fork可以类比 Git 的提交与分支模型# resume A → B → C → D → 新事件 E # fork A → B → C → D ├→ E1 → F1 └→ E2 → F2这种“全面插件化 全程可回放”的组合使 Harness 能够观察到的输入、输出和执行行为都具备可追溯性02 Agent Model Harness单独的模型本质上仍然是一个文本生成系统接收输入然后生成输出一个裸模型不会主动读取文件不知道自己给出的建议能否通过测试也不会在命令执行失败后自动分析原因并再次修改代码但把同一个模型放进 Harness 后情况就不同了模型可以读取文件、编辑代码、运行测试、观察失败结果再根据反馈继续修改。发生变化的并不是模型参数而是模型外部多了一套系统把“这句话应该怎么回答”转化成了“下一步应该采取什么行动行动结果是什么是否需要继续”这就是Agent Model HarnessModel是大脑负责理解、推理和决策Harness是包裹在模型外部的执行系统负责提供工具、组织上下文、管理状态、实施规则并把环境反馈重新交给模型这一工作机制通常可以用ReAct 循环概括Reason → Act → Observe → Repeat这一概念来自论文 ReAct: Synergizing Reasoning and Acting in Language Models模型先判断下一步应该做什么Harness 执行动作再把执行结果反馈给模型模型基于新的观察继续推理直到任务完成、需要人工介入或者达到预设的终止条件正是 Reason、Act 和 Observe 构成的闭环让大语言模型表现出了智能体行为Agent 不是模型单独具备的属性而是模型与环境形成闭环后涌现出来的系统行为。从这个角度看Harness 代表了人工智能应用方式的进一步演进随着模型能力增强开发者关注的重点逐渐从模型内部转向模型外部Prompt Engineering关心如何写好一段提示词Context Engineering关心如何筛选、组织和注入模型需要的信息Harness Engineering关心如何设计整套围绕模型运行的执行系统它们并不是彼此替代的关系而是关注范围逐层扩大从一句提示词扩展到一次推理所需的上下文再扩展到整个 Agent 的运行环境03 Harness 的核心结构理解了基本概念之后我们再具体看看 Harness 这个身体由哪些部分构成3.1 Agent 主循环Harness 最底层通常是一个循环这是整个 Agent 架构的地基用户输入任务后Harness 首先组装上下文并调用模型。模型决定当前步骤是直接返回文本还是调用工具如果模型不再调用工具Harness 输出最终结果并结束循环如果模型请求调用工具Harness 就执行相应动作将结果写回上下文再进入下一轮模型调用如果需要人工审批则暂停循环并等待用户确认如果达到最大迭代次数、时间限制或资源上限则强制终止简化后可以表示为while task_not_finished: context build_context() response call_model(context) if response.has_tool_call: result execute_tool(response.tool_call) append_result_to_context(result) else: return response这个循环通常是**机器节拍machine-paced**的并不是每一步都需要人工参与人只在权限审批、异常处理或任务完成时介入3.2 系统提示词在成熟的 Harness 中系统提示词通常不是一段完全固定的字符串而是运行时动态组装的它可能包含Harness 自身定义的基础行为规则从当前目录及其父目录加载的CLAUDE.md、AGENTS.md等项目指令当前 Git 状态、分支信息或最近的提交记录操作系统、工作目录和运行环境等元数据本次会话可用的工具、技能及其权限等级用户配置、团队规范和任务级约束因此模型看到的系统提示词实际上是多个信息源组合后的结果不同 Harness 在“加载哪些信息、以什么顺序组合、发生冲突时谁优先”方面通常有不同设计这也是它们行为差异的重要来源3.3 工具与技能工具是 Agent 与外部世界交互的基础能力例如读取和写入文件执行 Shell 命令搜索代码调用浏览器查询数据库访问外部 API在工具之上还可以进一步构建SkillsSkill 通常是针对特定任务封装的说明、工具组合和执行流程例如“分析当前变更并生成一条符合 Conventional Commits 规范的提交信息”Harness 需要维护一套工具注册与分发机制明确当前有哪些工具和技能可用每个工具需要哪些参数工具对应什么权限等级模型发出的调用应该如何派发工具结果应该如何截断、记录并返回模型调用失败时应该重试、报错还是请求人工处理工具和技能的质量是不同 Harness 之间最重要的差异化来源之一3.4 沙箱与文件系统许多 Harness 会在隔离环境中执行工具调用这个隔离环境通常被称为Sandbox沙箱提供了一块受控的执行空间使 Agent 可以运行代码、执行命令同时减少对宿主环境造成意外影响的风险它通常承担以下职责限制可读写的文件范围控制网络访问拦截高风险系统调用为多个 Agent 提供相互隔离的工作空间在任务结束后清理或重置环境记录命令及其执行结果沙箱之上是文件系统和持久化存储Agent 可以将代码、计划、笔记和中间产物写入磁盘使任务进度能够跨轮次甚至跨会话保存而不是每次都从零开始在软件工程场景中Git worktree、容器和虚拟机都是常见的隔离手段3.5 上下文管理基座模型本身不具备超出当前上下文窗口的长期记忆因此 Harness 必须决定哪些信息需要保留哪些信息可以摘要哪些内容可以丢弃哪些历史内容需要在特定条件下重新加载哪些文件应该按需检索而不是一次性全部注入当上下文接近模型窗口上限时Harness 通常会执行Context Compaction上下文压缩这并不是一句抽象概念落到实现中往往是一系列具体限制达到多少 token 时触发压缩保留最近多少条完整消息单次文件读取的大小上限grep最多返回多少行glob最多匹配多少文件工具输出最多允许多少字节哪些信息只能摘要哪些信息必须原样保留这些看似琐碎的数字实际上构成了上下文管理的重要边界能够避免一次意外的大文件读取或超长命令输出挤占整个上下文窗口3.6 Subagent当任务规模过大或者多个子任务可以并行处理时Harness 可以派生相对独立的Subagent例如一个主 Agent 可以同时派出多个子智能体一个负责探索代码结构一个负责定位相关测试一个负责检索历史实现一个负责验证最终修改子智能体完成任务后将结果汇总给主 Agent由主 Agent 继续决策常见的 Subagent 类型包括Explore只读探索型负责搜索和分析General Purpose通用执行型可以读取、修改和运行代码Verification验证型独立检查实现是否正确Subagent 通常需要具备一定程度的隔离拥有独立上下文避免污染主任务限制文件写入范围减少并发冲突控制递归派生避免子智能体无限嵌套限制 token、时间和调用次数明确最终结果应该如何返回主 Agent因此Subagent 不只是“同时开几个聊天窗口”而是一套包含上下文隔离、资源限制、任务调度和结果汇总的执行机制3.7 权限与护栏**Guardrails护栏**是写入 Harness 的安全规则用来阻止未经授权或风险过高的动作例如删除文件修改工作区之外的内容访问网络安装软件执行高风险 Shell 命令向外部系统发送消息操作生产环境或敏感数据一种常见的权限划分方式是只读只能读取文件和查询信息工作区可写允许修改当前项目但不能影响工作区之外的环境完全权限可以访问更广泛的文件、网络和系统资源对于 Shell 命令Harness 还可能进行动态分类。例如ls通常属于只读操作而rm、sudo或向外部系统写入数据则需要更高权限权限管理既可以采用交互式审批也可以通过声明式的allow/deny规则配置但如果审批变成大量高频、低差异的重复操作人很容易形成无脑点击允许的肌肉记忆反而削弱安全机制。因此一些系统会引入独立的规则引擎或分类器帮助处理低风险、可重复判断的权限请求只把真正重要的决策交给用户3.8 持久化与可观测性长时间运行的任务不能只存在于内存中否则进程一旦崩溃全部执行状态都会丢失因此Harness 通常会持续把事件增量写入持久化存储。一种典型实现是 append-only 的 JSONL 日志{type:user_message,content:修复登录问题}{type:tool_call,tool:grep,args:{query:login}}{type:tool_result,status:success,content:...}{type:context_compaction,summary:...}每条消息、每次工具调用、每次上下文压缩和每次状态变化分别占据一行。系统可以基于这些事件恢复会话并重建某个历史节点的状态在持久化之上则是更广义的可观测性Log记录具体发生了什么Trace串联一次任务中的模型调用、工具调用和子任务Metrics统计耗时、token、成本、错误率和成功率Dashboard将执行过程以可理解的方式展示给用户这些机制帮助开发者回答Agent 调用了哪些工具哪一步开始偏离目标哪次上下文压缩丢失了关键信息哪个子智能体消耗了最多资源错误来自模型判断、工具执行还是权限配置需要注意的是可观测性可以帮助我们还原 Agent 接收到的信息和采取的行动但不一定能够完整解释模型内部为什么形成某个判断DeepSeek Harness 的 append-only session log 与 Trajectory 视图就是这一层的具体实现。3.9 生命周期 Hooks**Lifecycle Hooks生命周期钩子**允许开发者在 Harness 执行过程的特定节点插入自定义逻辑而不必 Fork 整个项目并修改核心源码常见的 Hook 节点包括模型调用之前或之后工具调用之前或之后上下文压缩之前或之后Subagent 启动或结束时权限审批前任务完成或失败时例如一个pre-toolHook 可以在工具执行前直接放行调用拒绝危险操作修改调用参数记录审计信息要求人工审批Hook 的通信方式可以很简单通过标准输入传入 JSON再通过标准输出或退出码返回判断结果Hooks 是 Harness 实现可扩展性的重要机制而像 DSH 这样的插件架构则进一步把这种扩展能力系统化使模型、工具、循环、存储和 UI 都能够被替换或组合04 结语不同 Harness 产品有着不同的设计取舍DeepSeek Harness 把更多决策权交给配置和插件系统模型、工具、Agent 循环、存储与 UI 都可以被替换或组合。开发者可以通过配置调整系统而不必频繁修改核心源码Claude Code、Cursor、Codex 等产品则更偏向opinionated的产品设计厂商预先选择并深度优化模型、工作流、权限体系与交互方式为用户提供完整、稳定且开箱即用的体验这种模式的优势是成熟、省心代价则是底层组件的替换空间通常更有限。当然它们也提供 Skills、MCP、Hooks、插件或配置机制只是可扩展边界由产品方预先定义而不是所有核心组件都可以自由替换无论采取哪种路线它们的共同点都是Harness 负责提供执行机制、环境反馈和安全边界模型负责在这些条件下进行判断和决策。Harness 不应该完全替模型做决定但它决定了模型能看到什么能使用什么工具可以采取什么行动行动结果如何反馈哪些操作必须经过审批任务失败后能否恢复整个过程是否能够追溯因此优秀的 Harness 可以让能力普通的模型变得更加实用糟糕的 Harness也可能浪费最强模型的能力模型能力当然重要但决定一个 Agent 系统最终是否可靠、是否安全、是否真正好用的往往不只是模型参数还包括包裹在模型外部的那套 Harness 是否设计得足够好05 参考资料DeepSeek Harness 官方页面What Is an AI Agent Harness — DatabricksWhat Is an Agent Harness — Arize AI
