摘要最近“DeepSeek Harness”这个词在Agent和Coding Agent圈里快速升温。但真正值得开发者研究的不是某个项目是不是“国产Claude Code”。更重要的问题是为什么同一个DeepSeek V4模型放进不同Agent工具里实际完成任务的能力会差这么多答案在Harness。本文从插件协议、任务状态机、上下文管理、工具注册、沙箱、验证闭环、模型适配与多模型路由几个角度拆解Model Harness Agent背后的工程实现。FACT-001先把“官方信息”和“第三方项目”分开DeepSeek官方目前可以确认的是V4明确强化了Agentic Coding能力并提供Claude Code、OpenCode、OpenClaw、Copilot CLI、Pi等Agent与Coding Assistant的官方接入文档。DeepSeek官方GitHub中也存在awesome-deepseek-agent仓库用于整理V4 Pro / Flash与不同Agent工具的集成方案。但“DeepSeek官方独立Harness产品、MIT协议、npx deepseek-ai/dsh web、4小时34K stars”等说法目前没有在DeepSeek官方组织仓库或API文档里找到对应页面。当前公开的deepseek-harness项目来自第三方开发者因此本文不会把第三方项目属性写成DeepSeek官方产品事实。1. Harness到底是什么先别把它理解成一个“Agent App”用汽车做类比其实非常准确。大模型更像发动机。它提供推理、理解和生成能力。但只有发动机没有方向盘、刹车、仪表盘、传动系统和车身仍然不能真正上路。Harness负责的就是“整车系统”。Agent Model Context Planner Tools State Memory Guardrails Verifier Retry / Recovery所以Harness不是简单包一层UI。它真正控制的是模型如何拿到上下文、如何调用工具、如何执行、如何验证以及什么时候停止。2. DeepSeek V4为什么特别适合拿来讨论HarnessDeepSeek V4官方发布时就把Agentic Coding单独列为重点能力。V4 Pro面向更复杂的Agent任务。V4 Flash则强调更低成本和更快速度并且在简单Agent任务上接近Pro。两者都支持1M上下文和工具调用。这给Harness留下了很大的调度空间。User Task ↓ Harness ├── Simple Search → V4 Flash ├── File Summary → V4 Flash ├── Main Planning → V4 Pro ├── Deep Debug → V4 Pro └── Result Check → Flash / Pro同一个用户任务内部可以同时使用多个模型层级。这已经不是传统Chatbot的调用方式。3. Harness的第一层Plugin Contract而不是“所有代码写死”真正可扩展的Harness需要把模型、工具、记忆、工作流甚至UI能力抽象成插件。否则每增加一种Agent场景都要复制整套代码。from dataclasses import dataclass from typing import Protocol, Any class Plugin(Protocol): name: str version: str async def setup(self, context: dict) - None: ... async def invoke(self, payload: dict) - Any: ... async def teardown(self) - None: ... dataclass class PluginMeta: name: str version: str kind: str permissions: set[str] enabled: bool True有了统一Plugin Contract以后模型适配、网页工具、知识库、终端、视觉理解都可以挂在同一个运行时上。PLUGIN-101NO_CONTRACT插件只靠约定调用没有统一输入输出、生命周期和权限声明插件数量一多就无法治理。4. 第二层Model Adapter让Harness和模型解耦插件化系统最重要的一个能力是不能把Agent逻辑写死在某一家模型SDK上。DeepSeek官方同时提供OpenAI兼容和Anthropic兼容接口。这意味着Harness完全可以做统一Model Adapter。class ModelAdapter(Protocol): async def generate( self, messages: list[dict], tools: list[dict], ) - dict: ... class DeepSeekAdapter: def __init__(self, client, model: str): self.client client self.model model async def generate(self, messages, tools): return await self.client.chat( modelself.model, messagesmessages, toolstools, )如果以后换成其他兼容模型只需要新增Adapter。Planner、Tool Registry和Task State都不需要重写。5. 第三层Task State专门解决“目标遗忘”和“任务跑偏”长任务最怕的不是模型不会做而是做了十几轮以后开始忘记最初目标。from dataclasses import dataclass, field from enum import Enum class Phase(str, Enum): PLAN plan EXECUTE execute VERIFY verify DONE done FAILED failed dataclass class TaskState: task_id: str goal: str phase: Phase plan: list[str] field(default_factorylist) completed: list[str] field(default_factorylist) observations: list[str] field(default_factorylist) iteration: int 0 max_iterations: int 20Goal、Plan、Completed、Observation应该成为结构化状态。不能只靠模型“自己记住”。STATE-202STATE_IN_PROMPT_ONLY任务状态全部存在自然语言上下文里上下文压缩、断线恢复或者多Agent协作时都容易丢状态。6. 第四层Tool Registry工具不能等于“无限Shell”Agent真正开始“干活”靠的不是回答而是工具。读文件、检索网页、调用数据库、运行测试、分析图片都应该被抽象成受控能力。from dataclasses import dataclass from typing import Callable dataclass class Tool: name: str handler: Callable read_only: bool True requires_approval: bool False timeout_seconds: int 60 class ToolRegistry: def __init__(self): self.tools {} def register(self, tool: Tool): self.tools[tool.name] tool def get(self, name: str) - Tool: if name not in self.tools: raise KeyError(funknown tool: {name}) return self.tools[name]工具必须声明权限。读操作和写操作不能混在一起。高风险工具还应该进入审批。TOOL-303UNRESTRICTED_TOOL所有插件都能任意读写本地文件、访问公网或执行命令插件化会直接变成权限失控。7. 第五层“一切皆插件”真正难在权限不在安装插件越多系统越灵活。但同时攻击面也越大。所以插件系统必须带Capability声明。plugin: name: vision-reviewer permissions: - image.read - model.invoke network: allow: - api.example-model.com filesystem: read: - /workspace/assets write: [] secrets: - VISION_PROVIDER_KEY这样一个视觉插件只能读取素材并调用模型。它没有权限修改代码也不能访问任意网络。8. 第六层Context Engineering1M上下文不等于“全塞进去”DeepSeek V4已经把1M上下文作为默认能力。但Harness仍然要做上下文选择。因为Context越大不代表有效信息比例越高。dataclass class ContextItem: source: str relevance: float freshness: float token_count: int content: str def select_context(items, budget): items sorted( items, keylambda x: 0.7 * x.relevance 0.3 * x.freshness, reverseTrue, ) result, used [], 0 for item in items: if used item.token_count budget: continue result.append(item) used item.token_count return resultContext Engineering不是“拼Prompt”。它更像一个实时信息调度系统。CTX-404DUMP_EVERYTHING因为模型支持超长上下文就把全部文件、历史和日志塞进去最终会同时增加噪声、延迟与成本。9. 第七层Plan → Execute → Verify才是长任务真正的闭环Harness最重要的设计不是一次调用有多聪明。而是失败以后还能不能继续。async def run_task(state: TaskState): while state.iteration state.max_iterations: if state.phase Phase.PLAN: state.plan await planner(state) state.phase Phase.EXECUTE elif state.phase Phase.EXECUTE: observation await executor(state) state.observations.append(observation) state.phase Phase.VERIFY elif state.phase Phase.VERIFY: passed await verifier(state) if passed: state.phase Phase.DONE return state state.phase Phase.PLAN state.iteration 1 state.phase Phase.FAILED return stateSTEP 1计划先明确当前要做什么避免模型一上来就直接操作。STEP 2执行通过受控工具完成当前步骤并保存Observation。STEP 3验证检查任务是不是满足验收条件而不是相信模型自己宣布完成。STEP 4继续如果验证失败根据新的Observation重新规划而不是整条任务重来。10. 第八层Checkpoint解决“长任务中途断掉怎么办”真正跑半小时以上的Agent不可能保证永远不断线。模型服务可能超时工具可能失败用户也可能关闭页面。dataclass class Checkpoint: task_id: str goal: str current_plan: list[str] completed_steps: list[str] important_context: list[str] unresolved_errors: list[str] next_action: str恢复任务时不需要重新把完整历史塞给模型。只需要恢复继续工作必需的最小状态。11. 第九层模型路由让Pro和Flash承担不同工作Agent和普通对话最大的不同是一个任务内部可以调用几十次模型。如果每次都使用最贵模型成本会快速放大。def route_model(task_type: str, complexity: int): if task_type in { summarize_file, classify, simple_tool_decision, }: return deepseek-v4-flash if complexity 2: return deepseek-v4-flash return deepseek-v4-pro主规划和复杂Debug可以使用Pro。文件摘要、分类和简单子任务可以交给Flash。12. 视觉Agent怎么做重点仍然不是“换个多模态模型”如果需要增加图片理解能力可以增加一个Vision Adapter。底层模型可以是任何符合接口的视觉模型。class VisionAdapter: async def analyze( self, image_uri: str, instruction: str, ) - dict: result await self.client.generate( imageimage_uri, promptinstruction, ) return { summary: result.text, confidence: result.score, }真正重要的是Harness仍然统一负责权限、任务状态、工具调用与结果验证。换模型只是Adapter层的事情。13. 为什么这套架构也适用于多模型AI平台如果平台只有聊天聚合模型主要解决“选谁回答”。当平台加入智能体、图片、视频、音频、漫剧和PPT以后任务已经不再是一次调用。它会变成多阶段工作流。User Goal ↓ Task Planner ↓ Text Model ↓ Image / Video / Audio Model ↓ Asset Registry ↓ Quality Gate ↓ Final Deliverable对于创源AIGC这类聚合500模型并同时提供智能体、无限画布、AI漫剧、AI PPT等能力的平台来说下一阶段真正有技术价值的部分并不是继续把模型列表做长。而是让不同模型通过统一Harness参与同一个任务。Multi-Model Harness ├── Model Registry ├── Model Router ├── Plugin Runtime ├── Tool Registry ├── Task State ├── Asset Registry ├── Workflow DAG ├── Checkpoint ├── Quality Gate └── Audit Log14. 五个Harness系统最容易踩的坑PLUGIN-101PLUGIN_WITHOUT_PERMISSION插件支持热插拔但没有权限声明和隔离扩展能力越多安全风险越高。STATE-202NO_CHECKPOINTAgent任务状态只保存在当前会话里一旦中断就只能从头开始。TOOL-303SHELL_EVERYWHERE所有工具最终都被实现成任意Shell命令平台失去最小权限和审计能力。CTX-404CONTEXT_IS_STORAGE把上下文窗口当数据库使用不做筛选、压缩和状态持久化。DONE-505MODEL_SAYS_DONE模型说任务完成就直接返回没有独立Verifier确认验收条件。15. 如果真要做一个Harness建议从这4层开始STEP 1先做统一状态模型不要先追求复杂插件市场先保证Goal、Plan、Observation和Checkpoint能够可靠保存。STEP 2再做Tool Registry把读、写、网络和执行能力显式拆开建立最小权限模型。STEP 3然后做Verifier没有独立验收的Agent本质上只是会自动连续聊天。STEP 4最后做插件和多模型路由等运行时稳定以后再扩展视觉模型、第三方模型、办公插件与复杂Workflow。16. 最后Agent下一阶段拼的可能真的不是模型过去两年我们习惯把AI产品差异归结为模型差异。但Agent时代开始以后越来越多体验差距会来自模型之外。上下文怎么选。工具怎么开放。状态怎么保存。任务怎么恢复。结果怎么验收。模型怎么分工。这些才是Harness真正要解决的问题。模型决定Agent的智力上限。Harness决定这个上限能不能稳定地变成真实产出。 DeepSeek Harness爆火之后：Model + Harness = Agent，到底该怎么工程化落地？
摘要最近“DeepSeek Harness”这个词在Agent和Coding Agent圈里快速升温。但真正值得开发者研究的不是某个项目是不是“国产Claude Code”。更重要的问题是为什么同一个DeepSeek V4模型放进不同Agent工具里实际完成任务的能力会差这么多答案在Harness。本文从插件协议、任务状态机、上下文管理、工具注册、沙箱、验证闭环、模型适配与多模型路由几个角度拆解Model Harness Agent背后的工程实现。FACT-001先把“官方信息”和“第三方项目”分开DeepSeek官方目前可以确认的是V4明确强化了Agentic Coding能力并提供Claude Code、OpenCode、OpenClaw、Copilot CLI、Pi等Agent与Coding Assistant的官方接入文档。DeepSeek官方GitHub中也存在awesome-deepseek-agent仓库用于整理V4 Pro / Flash与不同Agent工具的集成方案。但“DeepSeek官方独立Harness产品、MIT协议、npx deepseek-ai/dsh web、4小时34K stars”等说法目前没有在DeepSeek官方组织仓库或API文档里找到对应页面。当前公开的deepseek-harness项目来自第三方开发者因此本文不会把第三方项目属性写成DeepSeek官方产品事实。1. Harness到底是什么先别把它理解成一个“Agent App”用汽车做类比其实非常准确。大模型更像发动机。它提供推理、理解和生成能力。但只有发动机没有方向盘、刹车、仪表盘、传动系统和车身仍然不能真正上路。Harness负责的就是“整车系统”。Agent Model Context Planner Tools State Memory Guardrails Verifier Retry / Recovery所以Harness不是简单包一层UI。它真正控制的是模型如何拿到上下文、如何调用工具、如何执行、如何验证以及什么时候停止。2. DeepSeek V4为什么特别适合拿来讨论HarnessDeepSeek V4官方发布时就把Agentic Coding单独列为重点能力。V4 Pro面向更复杂的Agent任务。V4 Flash则强调更低成本和更快速度并且在简单Agent任务上接近Pro。两者都支持1M上下文和工具调用。这给Harness留下了很大的调度空间。User Task ↓ Harness ├── Simple Search → V4 Flash ├── File Summary → V4 Flash ├── Main Planning → V4 Pro ├── Deep Debug → V4 Pro └── Result Check → Flash / Pro同一个用户任务内部可以同时使用多个模型层级。这已经不是传统Chatbot的调用方式。3. Harness的第一层Plugin Contract而不是“所有代码写死”真正可扩展的Harness需要把模型、工具、记忆、工作流甚至UI能力抽象成插件。否则每增加一种Agent场景都要复制整套代码。from dataclasses import dataclass from typing import Protocol, Any class Plugin(Protocol): name: str version: str async def setup(self, context: dict) - None: ... async def invoke(self, payload: dict) - Any: ... async def teardown(self) - None: ... dataclass class PluginMeta: name: str version: str kind: str permissions: set[str] enabled: bool True有了统一Plugin Contract以后模型适配、网页工具、知识库、终端、视觉理解都可以挂在同一个运行时上。PLUGIN-101NO_CONTRACT插件只靠约定调用没有统一输入输出、生命周期和权限声明插件数量一多就无法治理。4. 第二层Model Adapter让Harness和模型解耦插件化系统最重要的一个能力是不能把Agent逻辑写死在某一家模型SDK上。DeepSeek官方同时提供OpenAI兼容和Anthropic兼容接口。这意味着Harness完全可以做统一Model Adapter。class ModelAdapter(Protocol): async def generate( self, messages: list[dict], tools: list[dict], ) - dict: ... class DeepSeekAdapter: def __init__(self, client, model: str): self.client client self.model model async def generate(self, messages, tools): return await self.client.chat( modelself.model, messagesmessages, toolstools, )如果以后换成其他兼容模型只需要新增Adapter。Planner、Tool Registry和Task State都不需要重写。5. 第三层Task State专门解决“目标遗忘”和“任务跑偏”长任务最怕的不是模型不会做而是做了十几轮以后开始忘记最初目标。from dataclasses import dataclass, field from enum import Enum class Phase(str, Enum): PLAN plan EXECUTE execute VERIFY verify DONE done FAILED failed dataclass class TaskState: task_id: str goal: str phase: Phase plan: list[str] field(default_factorylist) completed: list[str] field(default_factorylist) observations: list[str] field(default_factorylist) iteration: int 0 max_iterations: int 20Goal、Plan、Completed、Observation应该成为结构化状态。不能只靠模型“自己记住”。STATE-202STATE_IN_PROMPT_ONLY任务状态全部存在自然语言上下文里上下文压缩、断线恢复或者多Agent协作时都容易丢状态。6. 第四层Tool Registry工具不能等于“无限Shell”Agent真正开始“干活”靠的不是回答而是工具。读文件、检索网页、调用数据库、运行测试、分析图片都应该被抽象成受控能力。from dataclasses import dataclass from typing import Callable dataclass class Tool: name: str handler: Callable read_only: bool True requires_approval: bool False timeout_seconds: int 60 class ToolRegistry: def __init__(self): self.tools {} def register(self, tool: Tool): self.tools[tool.name] tool def get(self, name: str) - Tool: if name not in self.tools: raise KeyError(funknown tool: {name}) return self.tools[name]工具必须声明权限。读操作和写操作不能混在一起。高风险工具还应该进入审批。TOOL-303UNRESTRICTED_TOOL所有插件都能任意读写本地文件、访问公网或执行命令插件化会直接变成权限失控。7. 第五层“一切皆插件”真正难在权限不在安装插件越多系统越灵活。但同时攻击面也越大。所以插件系统必须带Capability声明。plugin: name: vision-reviewer permissions: - image.read - model.invoke network: allow: - api.example-model.com filesystem: read: - /workspace/assets write: [] secrets: - VISION_PROVIDER_KEY这样一个视觉插件只能读取素材并调用模型。它没有权限修改代码也不能访问任意网络。8. 第六层Context Engineering1M上下文不等于“全塞进去”DeepSeek V4已经把1M上下文作为默认能力。但Harness仍然要做上下文选择。因为Context越大不代表有效信息比例越高。dataclass class ContextItem: source: str relevance: float freshness: float token_count: int content: str def select_context(items, budget): items sorted( items, keylambda x: 0.7 * x.relevance 0.3 * x.freshness, reverseTrue, ) result, used [], 0 for item in items: if used item.token_count budget: continue result.append(item) used item.token_count return resultContext Engineering不是“拼Prompt”。它更像一个实时信息调度系统。CTX-404DUMP_EVERYTHING因为模型支持超长上下文就把全部文件、历史和日志塞进去最终会同时增加噪声、延迟与成本。9. 第七层Plan → Execute → Verify才是长任务真正的闭环Harness最重要的设计不是一次调用有多聪明。而是失败以后还能不能继续。async def run_task(state: TaskState): while state.iteration state.max_iterations: if state.phase Phase.PLAN: state.plan await planner(state) state.phase Phase.EXECUTE elif state.phase Phase.EXECUTE: observation await executor(state) state.observations.append(observation) state.phase Phase.VERIFY elif state.phase Phase.VERIFY: passed await verifier(state) if passed: state.phase Phase.DONE return state state.phase Phase.PLAN state.iteration 1 state.phase Phase.FAILED return stateSTEP 1计划先明确当前要做什么避免模型一上来就直接操作。STEP 2执行通过受控工具完成当前步骤并保存Observation。STEP 3验证检查任务是不是满足验收条件而不是相信模型自己宣布完成。STEP 4继续如果验证失败根据新的Observation重新规划而不是整条任务重来。10. 第八层Checkpoint解决“长任务中途断掉怎么办”真正跑半小时以上的Agent不可能保证永远不断线。模型服务可能超时工具可能失败用户也可能关闭页面。dataclass class Checkpoint: task_id: str goal: str current_plan: list[str] completed_steps: list[str] important_context: list[str] unresolved_errors: list[str] next_action: str恢复任务时不需要重新把完整历史塞给模型。只需要恢复继续工作必需的最小状态。11. 第九层模型路由让Pro和Flash承担不同工作Agent和普通对话最大的不同是一个任务内部可以调用几十次模型。如果每次都使用最贵模型成本会快速放大。def route_model(task_type: str, complexity: int): if task_type in { summarize_file, classify, simple_tool_decision, }: return deepseek-v4-flash if complexity 2: return deepseek-v4-flash return deepseek-v4-pro主规划和复杂Debug可以使用Pro。文件摘要、分类和简单子任务可以交给Flash。12. 视觉Agent怎么做重点仍然不是“换个多模态模型”如果需要增加图片理解能力可以增加一个Vision Adapter。底层模型可以是任何符合接口的视觉模型。class VisionAdapter: async def analyze( self, image_uri: str, instruction: str, ) - dict: result await self.client.generate( imageimage_uri, promptinstruction, ) return { summary: result.text, confidence: result.score, }真正重要的是Harness仍然统一负责权限、任务状态、工具调用与结果验证。换模型只是Adapter层的事情。13. 为什么这套架构也适用于多模型AI平台如果平台只有聊天聚合模型主要解决“选谁回答”。当平台加入智能体、图片、视频、音频、漫剧和PPT以后任务已经不再是一次调用。它会变成多阶段工作流。User Goal ↓ Task Planner ↓ Text Model ↓ Image / Video / Audio Model ↓ Asset Registry ↓ Quality Gate ↓ Final Deliverable对于创源AIGC这类聚合500模型并同时提供智能体、无限画布、AI漫剧、AI PPT等能力的平台来说下一阶段真正有技术价值的部分并不是继续把模型列表做长。而是让不同模型通过统一Harness参与同一个任务。Multi-Model Harness ├── Model Registry ├── Model Router ├── Plugin Runtime ├── Tool Registry ├── Task State ├── Asset Registry ├── Workflow DAG ├── Checkpoint ├── Quality Gate └── Audit Log14. 五个Harness系统最容易踩的坑PLUGIN-101PLUGIN_WITHOUT_PERMISSION插件支持热插拔但没有权限声明和隔离扩展能力越多安全风险越高。STATE-202NO_CHECKPOINTAgent任务状态只保存在当前会话里一旦中断就只能从头开始。TOOL-303SHELL_EVERYWHERE所有工具最终都被实现成任意Shell命令平台失去最小权限和审计能力。CTX-404CONTEXT_IS_STORAGE把上下文窗口当数据库使用不做筛选、压缩和状态持久化。DONE-505MODEL_SAYS_DONE模型说任务完成就直接返回没有独立Verifier确认验收条件。15. 如果真要做一个Harness建议从这4层开始STEP 1先做统一状态模型不要先追求复杂插件市场先保证Goal、Plan、Observation和Checkpoint能够可靠保存。STEP 2再做Tool Registry把读、写、网络和执行能力显式拆开建立最小权限模型。STEP 3然后做Verifier没有独立验收的Agent本质上只是会自动连续聊天。STEP 4最后做插件和多模型路由等运行时稳定以后再扩展视觉模型、第三方模型、办公插件与复杂Workflow。16. 最后Agent下一阶段拼的可能真的不是模型过去两年我们习惯把AI产品差异归结为模型差异。但Agent时代开始以后越来越多体验差距会来自模型之外。上下文怎么选。工具怎么开放。状态怎么保存。任务怎么恢复。结果怎么验收。模型怎么分工。这些才是Harness真正要解决的问题。模型决定Agent的智力上限。Harness决定这个上限能不能稳定地变成真实产出。