系列:DeepSeek Harness(dsh)源码教程 · 下篇(第 8-10 章 + 附录)
上篇:从 API 到 Agent 心脏(第 0-3 章) 中篇:工具、提示词与插件内核(第 4-7 章)
上篇讲了 Agent 的心脏:日志、状态机、工具调度。中篇讲了肌肉和神经:工具流水线、提示词总装、Cordis 插件内核、能力缝 seam。
下篇回答最后三个问题:
- dsh 怎么做到"模型无关"?(第 8 章模型适配器)
- 多 Agent 怎么协作、怎么隔离上下文?(第 9 章子代理)
- 能不能把所有机制浓缩成一个可运行的 Python 程序?(第 10 章综合实战)
第 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 类型,描述了任何流式输出的完整结构:
- block-start / text-delta / block-end:一个文本块的开头、增量、结束
- tool-call-delta:工具调用的参数也是流式的(argumentsDelta 一段段拼)
- reasoning-delta:思考过程单独流(DeepSeek 推理模型的专长)
- usage / finish:token 统计、结束原因
适配器的工作 = 把自家 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 } } }}
三个容错设计,每个都是实战逼出来的:
- 容忍 delta-only 协议:有些适配器不发送 block-start/end,只发 delta——
ensure()会按需创建部分块 - 已关闭的块忽略迟到数据:畸形适配器发了 block-end 又补 delta,不会污染已完成的块,也不会无限涨内存
- 首次关闭为准:重复的 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 本章小结
- 流式 chunk 六类型词汇表:统一所有厂商的流式格式,适配器只做翻译
- BlockAssembler 容错:容忍 delta-only 协议、忽略迟到数据、首次关闭为准——保证"日志里的 chunk"与"组装的消息"一致
- 重试 = 错误码分类 + Provider 策略 + 指数退避 + 抖动:防重试风暴,可重试性由错误码决定
- 错误恢复发生在事件层(agent/request-error),行为可插拔
- Python 完整实现了三个核心机制
第 9 章 多 agent:subagent 与编排
核心机制:会话分叉(继承前导 + 独立记录)、委派深度预算(防递归套娃)、Provider 化(子代理可以是同进程、甚至是外部的 Codex/Claude Code)。
9.1 为什么要子代理:上下文治理
单 agent 的根本矛盾:上下文窗口有限,任务可以无限。
主 agent 探索整个代码库找 bug——如果…