Harness 与 Agent 工程 · 运行控制与长任务 · 2026-08-24

DeepSeek Harness 源码深潜(下)——模型适配、多 Agent 与 Python 实战(附DSH源码)

DeepSeek Harness源码教程下篇,揭秘模型适配、多Agent协作与Python实战,附完整源码助你上手实践。 核心内容:

  1. 模型适配器:实现模型无关的核心机制
  2. 多Agent协作:子代理协同与上下文隔离
  3. Python综合实战:可运行程序的构建与实践

系列:DeepSeek Harness(dsh)源码教程 · 下篇(第 8-10 章 + 附录)

上篇:从 API 到 Agent 心脏(第 0-3 章) 中篇:工具、提示词与插件内核(第 4-7 章)


上篇讲了 Agent 的心脏:日志、状态机、工具调度。中篇讲了肌肉和神经:工具流水线、提示词总装、Cordis 插件内核、能力缝 seam。

下篇回答最后三个问题:


第 8 章 模型适配器——模型无关的真相

核心机制:流式 chunk 的标准词汇表、BlockAssembler 的容错组装、重试策略的错误码分类。

8.1 适配器注册表:模型是插件

回顾第 7 章的 seam 概念——ctx.llm 就是一个 seam:

ctx.llm(接口:stream / prepareCall / ...) ├── llm-deepseek (DeepSeek 官方适配器) ├── llm-pi-ai (OpenAI 兼容端点:可接任何 openai 兼容服务) └── llm-replay (回放适配器:测试用,不烧 token)

消费方(agent-loop)只调接口:

const stream = this.loopCtx.llm.stream(request)

模型无关的真相:不是"支持很多模型",而是"适配器协议统一"。任何供应商,只要实现 stream() 接口(把自家 API 的流式输出翻译成 dsh 的标准 chunk),就能接入。

8.2 机制深潜 1:流式 chunk 的标准词汇表

不同模型 API 的流式格式天差地别(OpenAI 的 delta、Anthropic 的 content_block_delta、DeepSeek 的 reasoning_content……)。dsh 定义了一套与供应商无关的 chunk 词汇表(packages/llm/llm/src/types.ts):

type StreamChunk = | { type: 'block-start'; index: number; blockType: 'text' | 'reasoning' | 'tool-call' } | { type: 'text-delta'; index: number; text: string } | { type: 'reasoning-delta'; index: number; text: string } | { type: 'tool-call-delta'; index: number; id: string; name?: string; argumentsDelta: string } | { type: 'block-end'; index: number; block: ContentBlock } | { type: 'usage'; usage: TokenUsage } | { type: 'finish'; reason: FinishReason; replayState?: unknown }

六个 chunk 类型,描述了任何流式输出的完整结构:

适配器的工作 = 把自家 API 的流翻译成这套词汇表。agent-loop 只认这套词汇表,从不关心"这是哪个厂商的格式"。

8.3 机制深潜 2:BlockAssembler——容错的流式组装器

packages/llm/llm/src/assembler.ts 是"把 chunk 流组装成完整消息"的规范算法。它的设计极其注意容错:

export class BlockAssembler { private partials = new Map() // 按 index 的部分块 private order: number[] = [] push(chunk: StreamChunk): void { switch (chunk.type) { case 'text-delta': { const partial = this.ensure(chunk.index, 'text') if (partial.block) return // ← 已关闭的块:忽略迟到的 delta(防畸形流) partial.text += chunk.text return } case 'tool-call-delta': { const partial = this.ensure(chunk.index, 'tool-call') if (partial.block) return partial.toolCallId = chunk.id if (chunk.name) partial.toolCallName = chunk.name partial.toolCallArguments += chunk.argumentsDelta // 参数流式拼接 return } case 'block-end': { const partial = this.ensure(chunk.index, chunk.block.type) if (partial.block) return // 首次关闭为准(防重复关闭) partial.block = chunk.block return } } }}

三个容错设计,每个都是实战逼出来的:

  1. 容忍 delta-only 协议:有些适配器不发送 block-start/end,只发 delta——ensure() 会按需创建部分块
  2. 已关闭的块忽略迟到数据:畸形适配器发了 block-end 又补 delta,不会污染已完成的块,也不会无限涨内存
  3. 首次关闭为准:重复的 block-end 被忽略,保证流式输出与最终组装一致

为什么这么较真?因为 agent-loop 在实时消费流的同时,还要把每个 chunk 写进会话日志(第 2 章的 assistant/chunk)。日志里的 chunk 和最终组装的消息必须一致——否则回放就失真。容错不是"软件工程洁癖",是"日志完整性"的硬需求。

8.4 机制深潜 3:重试策略——错误码分类驱动

packages/llm/llm/src/retry-policy.ts 展示了"重试不是 try/except"的工业级做法:

第一步:错误结构化。LlmError 带 code:

export class LlmError extends Error { code: string // 'RATE_LIMIT' | 'SERVER' | 'TIMEOUT' | 'TRANSPORT' | 'EMPTY_RESPONSE' | 'NO_ADAPTER' ...}

第二步:策略声明。每个 Provider 注册自己的重试策略(配置化,不是写死):

// 默认策略(normal 模式):const DEFAULT_MAX_RETRIES = 2const DEFAULT_RETRYABLE_CODES = ['EMPTY_RESPONSE', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT']// ↑ 只有这些”可重试的临时错误”才重试// 不可重试的(NO_ADAPTER、参数错误)→ 直接失败,不浪费重试 // 还有 always 模式:任何失败都重试直到成功/取消(用于长任务容错)

第三步:指数退避 + 抖动(关键细节):

const DEFAULT_INITIAL_DELAY_MS = 500 // 首次重试等待 500msconst DEFAULT_MAX_DELAY_MS = 10_000 // 封顶 10sconst DEFAULT_JITTER_RATIO = 0.1 // ±10% 抖动// 500ms → 1000ms → 2000ms ... 封顶 10s,每次 ±10% 随机化

为什么要有 jitter(抖动)?如果没有抖动,多个并发请求同时失败会同时重试,形成"重试风暴"(thundering herd)——把已经过载的服务彻底打垮。±10% 的随机化让重试自然散开。

为什么 backoff 是 Provider 拥有的?因为不同的 API 有不同的限流语义——DeepSeek 的 429 和 OpenAI 的 429 可能意味着不同的等待时间。重试策略跟着 Provider 走,而不是全局写死。

8.5 错误恢复的完整链路(把第 3、4、8 章串起来)

模型请求失败(RATE_LIMIT) → BlockAssembler 报告 finish.kind === 'error' → agent-loop 触发 agent/request-error 瀑布事件 → 监听器(llm-retry 插件)读取 provider 的 retryPolicy → 可重试?→ 指数退避 + 抖动等待 → continue(回到 step 循环再来一次) → 不可重试?→ 抛 LlmError → turn 以 error 结束(写进日志)

关键:重试决策发生在事件层,不在循环代码里。想改重试行为?换一个监听器插件,agent-loop 一行不动。这又是 seam/事件思想的体现——连"怎么处理失败"都是可替换的。

8.6 深度 Python 对照:流式词汇表 + 组装器 + 重试

”””深度版:标准 chunk 词汇表 + 容错组装器 + 错误码重试”””from dataclasses import dataclass, field # ---- 标准词汇表(模仿 StreamChunk 六类型) ----def text_delta(index, text): return {”type”: ”text-delta”, ”index”: index, ”text”: text}def tool_delta(index, args): return {”type”: ”tool-call-delta”, ”index”: index, ”id”: f”call-{index}”, ”argumentsDelta”: args}def block_end(index, block): return {”type”: ”block-end”, ”index”: index, ”block”: block} # ---- 容错组装器 ----class Assembler: def __init__(self): self._partials = {} self._order = [] def push(self, chunk): idx = chunk[”index”] if chunk[”type”] == ”text-delta”: p = self._partials.setdefault(idx, {”text”: ””, ”closed”: False}) if not p[”closed”]: # 已关闭的忽略(防畸形流) p[”text”] += chunk[”text”] elif chunk[”type”] == ”tool-call-delta”: p = self._partials.setdefault(idx, {”text”: ””, ”closed”: False, ”args”: ””}) if not p[”closed”]: p[”args”] += chunk[”argumentsDelta”] elif chunk[”type”] == ”block-end”: p = self._partials.setdefault(idx, {”text”: ””, ”closed”: False, ”args”: ””}) if not p[”closed”]: # 首次关闭为准 p[”closed”] = True p[”block”] = chunk[”block”] def message(self): blocks = [] for idx in self._order: p = self._partials[idx] blocks.append(p.get(”block”) or {”type”: ”text”, ”text”: p[”text”]}) return blocks # ---- 错误码 + 重试(指数退避 + 抖动) ----import random, time RETRYABLE = {”RATE_LIMIT”, ”SERVER”, ”TIMEOUT”, ”TRANSPORT”} class LlmError(Exception): def __init__(self, code): self.code = code def call_with_retry(fn, max_retries=2): delay = 0.5 # initialDelayMs for attempt in range(max_retries + 1): try: return fn() except LlmError as e: if e.code not in RETRYABLE or attempt == max_retries: raise jitter = delay * random.uniform(-0.1, 0.1) # ±10% 抖动 time.sleep(max(delay + jitter, 0)) # 防重试风暴 delay = min(delay * 2, 10) # 指数退避,封顶 10s # ---- 使用 ----asm = Assembler()for chunk in [text_delta(0, ”你好”), tool_delta(1, '{”path”:'), tool_delta(1, '”a.py”}'), block_end(1, {”type”: ”tool-call”, ”id”: ”call-1”, ”name”: ”read_file”, ”arguments”: '{”path”:”a.py”}'})]: asm.push(chunk)print(”组装结果:”, asm.message())

对照 dsh 的差距:dsh 的 assembler 支持 reasoning 块、usage/finish 状态、replayState;retry 是 Provider 声明 + 事件驱动 + 配置 schema 校验。但"标准词汇表 + 容错组装 + 错误码分类重试"三个核心,你已经实现。

8.7 本章小结


第 9 章 多 agent:subagent 与编排

核心机制:会话分叉(继承前导 + 独立记录)、委派深度预算(防递归套娃)、Provider 化(子代理可以是同进程、甚至是外部的 Codex/Claude Code)。

9.1 为什么要子代理:上下文治理

单 agent 的根本矛盾:上下文窗口有限,任务可以无限。

主 agent 探索整个代码库找 bug——如果…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/OpenSourceLLM/2026082454089.html