主题
第4章 经典 Agent 应用的技术原理解析
第 3 章把 Agent 的技术底座拆成两半来讲:一半是从 Prompt 到 Graph 的五个层层套叠的工程范式,另一半是让长链路任务真正跑得起来的二十种循环设计模式。
但这两样东西在第 3 章里都还停在「应该这样」。范式是归纳出来的,模式是从实践里提炼出来的:只有对上具体代码,它们才算数。
这一章要做的,就是找两个真实项目,把它们对上代码。
选样本只有一条标准:能被读者自己复现。所以选了两个开源项目:
- OpenClaw(https://openclaw.ai):一个把「大模型 + 工具调用」跑成产品级服务的运行时,接十几个聊天渠道、管几百个会话、扛住重启、撑住长时间运行;
- DeepSeek Harness(下称 DSH,https://github.com/deepseek-ai/deepseek-harness):一个把插件、会话、沙箱、压缩、子 Agent 全部拆成独立模块的编程式框架。
两个都不是功能最全的。这恰恰是选它们的理由:功能最全的框架会让读者误以为「做长任务就得把这些全装上」,而真正该学的,是哪些能力是底座不可省的、哪些是应用层自己加的。
关于顺序,需要交代一句。
先讲 OpenClaw 对二十种循环模式的落地,再讲 DSH 对五个范式的落地。这不是随意排列:二十种模式是「让系统真的转起来」的那一层,它比范式更具体、更可照抄、也更难糊弄;五个范式则是一个更大的框架,适合放在具体之后再来套。
还有一点必须说在前面。
本书第 3 章讲的五大范式,是本书为了把 AI 工程化这几年的演进讲清楚而做的一次归纳:它不是业界统一的术语表,你在别的书里未必能看到同样的分法。所以读这一章时,不必纠结「五大范式是不是公认的」,更值得问的是:当一套范式落到真实代码里,它变成了什么样,又在哪里被迫妥协。
本章三节都可以跳读。只想拿结论的读者,直接看 4.1.8 的七条原则、4.2.8.3 的自检清单,以及 4.3 的对照表;正在自己搭系统的读者,建议对照源码读:每一处结论后面都给了文件和行号,版本也已经钉死,你能自己核对。
4.1 OpenClaw:二十种循环模式在源码里长什么样
4.1.1 引子:为什么拿它当解剖对象
本章我们拿两个真实项目,把第 3 章的范式与模式对到代码上:具体是五个工程范式加二十种循环模式。先看 OpenClaw,因为二十种循环模式比五大范式更具体,也更容易验证。
讲长链路任务,常见的错误是拿功能最全的框架当样板。
功能最全的框架什么都有,计划器、评审器、多智能体辩论、记忆图谱,一个不少。读完之后容易产生一种错觉:做长任务,这些都得装上。
于是开始堆模块,堆到第三个月发现,系统比模型更容易出错,而且不知道是哪个模块在捣乱。
更有效的路径正好相反,先找一个只做了最少必要工作的实现,把它读透。搞清楚哪些能力是底座必须的,哪些是应用层加上去的。
OpenClaw 就是这样一个样本。它把大模型与工具调用跑成了产品级服务,接二十多个聊天渠道,同时管理大量会话,扛得住重启,也撑得住长时间运行。它是开源项目,仓库在 github.com/openclaw/openclaw,可用 npm 全局安装(包名 openclaw);本节依据 OpenClaw 2026.8.35 的 dist/ 构建产物。
但它的内核只有一件事。把一句话变成一轮模型调用,把模型要的工具执行掉,把结果塞回上下文,然后重复。
没有计划器,没有评审团,没有搜索树。全书讲的二十种循环模式,它完整落地的只有七种。
这不是缺点。恰恰因为它薄,才看得清一件事:剥离所有高级循环之后,一个 Agent 运行时还剩什么?剩下的那些,才是不能省的东西。
后面的路线是这样:先看骨架,再看它实现了哪些模式,中间还要看它刻意不做什么、为什么不做,然后重点看它怎么防死循环。最后回到一个更根本的问题,Agent 怎么知道自己做对了,并把观察收成七条可以直接照做的原则。
4.1.2 先看骨架:一句话在源码里怎么走完
4.1.2.1 三个粒度:轮、步、run
读任何 Agent 框架,第一件事是把循环粒度分清。我们这里按三层拆 OpenClaw,混起来就永远读不懂。
- 轮(turn):一次模型调用,加上它要求的工具执行,构成一个完整的思考与行动单元。要不要进下一轮,由模型决定。
- 步(step,也译作批次):同一条 assistant 消息里要求的那组工具调用。模型一次可能要求三个工具,这就是一步。
- run:从用户说一句话开始,到给出最终答复为止的整段过程。一个 run 包含若干个轮,靠终止条件收口。
三个词在代码里各有各的变量,在讨论里却常被混用。说这个任务跑了三十步时,最好先确认说的是轮还是步。
4.1.2.2 主循环只有二十行
真正的控制环在 agent-core:236 的 runLoop(),剥掉参数处理,骨架如下。本章引用的 file:line 均指 OpenClaw 2026.8.35 的 dist/ 打包产物;文件名带内容哈希,行号会随版本漂移,核对时优先按函数名搜(命令见 4.1.6.3)。
js
async function runLoop(...) {
while (true) { // 外层
let hasMoreToolCalls = true;
while (hasMoreToolCalls || pendingMessages.length > 0) { // 内层:ReAct 体
const message = await streamAssistantResponse(...); // 问模型
if (message.stopReason === "error" || message.stopReason === "aborted") return;
if (message.stopReason === "toolUse" && toolCalls.length > 0) {
const batch = await executeToolCalls(...); // 执行工具
hasMoreToolCalls = !batch.terminate;
pendingMessages = batch.steeringMessages;
}
await config.prepareNextTurn?.(...); // 重建上下文
if (await config.shouldStopAfterTurn?.(...)) return; // 停机判定
}
pendingMessages = await config.getFollowUpMessages?.() ?? [];
if (pendingMessages.length === 0) break;
}
}几十行代码,把长链路 Agent 的骨架问题全摆出来了。
什么时候再来一轮?看 stopReason 是不是 toolUse,也看有没有中途插话。
一轮之内怎么并行?executeToolCalls 会把同一步的工具分成并行与串行两组(agent-core:507/564/668)。
两轮之间要不要改上下文?看 prepareNextTurn(agent-core:385),这是全系统的关键钩子,本节后面会反复回到它。
什么时候该停?看 shouldStopAfterTurn(agent-core:399),要留意的是,内核不自己决定停不停,它只留一个钩子给外层。
prepareNextTurn 与 shouldStopAfterTurn 这两个钩子,值得我们停下来想一想。很多自研 Agent 的循环,把压缩上下文、换模型、检查完成全硬写进 while 里。半年之后,这段代码变成谁也不敢动的一坨。
OpenClaw 的做法是:循环体只留骨架,每轮要做的事全部通过钩子注入。
这是第一个可以立刻搬走的原则。循环体越薄,寿命越长。
4.1.3 二十种循环模式的对照结果
我们拿全书那二十种模式逐一比对,先给结论,再讲为什么。下表按本书 3.1.1 的口径列出全集:第 3 章只举了其中十个「如……」的例子,完整清单以本表为准。
共 15 行;其中 4 行合并了 9 个模式,省下 5 行——Multi-Critic / Adversarial Critique / Judge Ensemble(3 个)、Error Library / Success Pattern(2 个)、Dynamic Workflow / Goal Decomposition(2 个)、Tree Search / Debate(2 个)。
| 大类 | 模式 | 模式数 | OpenClaw |
|---|---|---|---|
| 质量提升 | Generate→Critique→Rewrite | 1 | 未实现 |
| Score-and-Retry | 1 | 半落地(有打分,没重写) | |
| Multi-Critic / Adversarial Critique / Judge Ensemble | 3 | 均未实现 | |
| 记忆演化 | Memory Update | 1 | 已实现 |
| Memory Compression | 1 | 已实现 | |
| Reflexion | 1 | 半落地(只写回,不重试) | |
| Error Library / Success Pattern | 2 | 半落地(会话内指纹 / 轨迹转技能) | |
| 规划调整 | Progress Evaluation | 1 | 已实现 |
| Constraint Satisfaction | 1 | 已实现 | |
| Plan→Execute→Replan | 1 | 未实现 | |
| Dynamic Workflow / Goal Decomposition | 2 | 未实现 | |
| 探索搜索 | Branch-and-Explore | 1 | 已实现 |
| Tree Search / Debate | 2 | 未实现 | |
| 系统自优化 | Prompt Optimization | 1 | 已实现 |
| Workflow Optimization | 1 | 已实现 |
半落地的判据是:有可核验的部分机制、缺闭环。Error Library 的半个机制是会话内失败身份指纹加上重复失败拦截,缺的是跨会话错题本与复用检索;Success Pattern 的半个是「轨迹(transcript)转技能」,且只收成功。这两项维持半落地判定,本节口径始终是 7 项完整、4 项部分、9 项未实现。
计数规则:本节按模式计,不按机制计。同一套源码机制服务多个模式时,每个模式各计一次。例如 4.1.4.7 的「体验复盘→改 SKILL.md」同时服务 Prompt Optimization、Workflow Optimization,以及 Success Pattern 的半个。模式是读者单位,机制是源码单位;按机制重算会让第 3 章的二十种清单无法逐项对账。
表中标为半落地的三行(按模式算四项),在正文都有落点。Score-and-Retry 的「打分」落在 4.1.4.2 晋升门那套加权评分上,分数只用来决定留不留,不用来重写本轮输出。Error Library / Success Pattern 指 4.1.4.3 的轨迹复盘与 4.1.4.7 的「轨迹转技能」,经验落成文件,但不在同一轮里复用。
统计下来,7 项完整、4 项部分、9 项未实现。完整落地的七项分布在记忆、规划、探索与自优化四类(2/2/1/2),质量提升类一项完整都没有;部分落地的四项集中在质量(1)与记忆(3)。为什么这样切、哪些是刻意不做,留到 4.1.5 讲。
先逐个看落地的那几个。
4.1.4 七种完整落地,另有一种只做一半,逐个拆
这一节按顺序拆开落地的模式。八个模式落在七个小节里:
| 小节 | 承载模式 | 完整 / 半 |
|---|---|---|
| 4.1.4.1 | Memory Compression | 完整 |
| 4.1.4.2 | Memory Update | 完整(另承载 Score-and-Retry 的打分锚点,不单独计节) |
| 4.1.4.3 | Reflexion | 半落地(只写回,不重试;另承载 Error Library 的会话内指纹) |
| 4.1.4.4 | Branch-and-Explore | 完整 |
| 4.1.4.5 | Progress Evaluation | 完整 |
| 4.1.4.6 | Constraint Satisfaction | 完整 |
| 4.1.4.7 | Prompt Optimization | 完整 |
| 4.1.4.7 | Workflow Optimization | 完整(同一小节;另承载 Success Pattern 的「轨迹转技能」) |
顺序按「记忆 → 反思 → 并行 → 治理 → 自优化」重排。
4.1.4.1 记忆压缩(Memory Compression):不是截断,是结构化重写
长对话必然超窗,粗暴的做法是丢掉最早的几条消息,这也是伤得最深的做法:最早的几条往往含着目标与约束。
OpenClaw 的做法是让模型把旧对话重写成一份结构化的检查点。提示词(Prompt)是硬编码的常量(compaction-D9ok_o6I.js:699 的 SUMMARIZATION_PROMPT),规定了固定骨架。以下骨架为译写,原文英文见 compaction-D9ok_o6I.js:699-729。
markdown
## Goal [保留原目标,任务扩展则补充]
## Constraints & Preferences
## Progress
### Done [x] ...
### In Progress [ ] ...
### Blocked
## Key Decisions **[决策]**:理由
## Next Steps
## Critical Context [保留精确路径、函数名、错误信息]骨架不是随便定的,它把继续干活需要什么拆成六类,其中三条要特别留意。
第一是 Done、In Progress、Blocked 三分。它记录的不是聊了什么,而是做到哪了,把对话转成任务状态。
第二是 Blocked 独立成节,它逼模型显式承认卡点,很多 Agent 失败不是能力不够,是不肯说我卡住了。
第三是 Critical Context 要求保留精确路径与错误信息。压缩的主要风险,就是把 /src/foo.ts:42 这种救命细节概括成某个文件。
更关键的是 UPDATE_SUMMARIZATION_PROMPT(:731)。如果已有旧检查点,它不重新总结全部对话,而是让模型把新消息增量合并进旧检查点。
压缩与演化的分界线在于增量合并:每次从零重写,信息会在多次重写里持续衰减,像反复复印。增量合并则让检查点成为一份不断被修订的文档。
触发条件的设计更实用。agent-runner-memory-CZMzDnRW.js:607 是双触发:Token 超过阈值,或者轨迹字节数超过 maxActiveTranscriptBytes。第二个条件看着冗余,其实很有用。Token 估算依赖各家的 tokenizer(分词器),provider 之间差异很大,字节数是硬指标,永远准,两个都设,谁先到算谁。
4.1.4.2 记忆更新(Memory Update):三条管线,各管一段
记忆在工程上不是一个东西,至少是三样东西。OpenClaw 用三条独立管线分别处理,这个拆法可以直接搬。
管线一是压缩前抢写(agent-runner-memory-CZMzDnRW.js:133)。
压缩是破坏性的,原话没了,所以在压缩之前,先跑一轮,把即将消失的内容蒸馏进当日记忆文件。
三个细节都对应一个真实故障。幂等校验(:148)比对 memoryFlush.compactionCount 与当前计数,同一次压缩周期只准 flush 一次,否则每次检查都会多一次模型调用。
失败上限(:157)是 MAX_FLUSH_FAILURES = 3。flush 本身也是模型调用,也会失败,失败就重试是常见反应,无上限重试会拖垮任务。
触发判定在 :133,要求 Token 超过阈值,且本周期没有 flush 过。
管线二是夜间晋升,带打分门(dreaming-CeTJnIOU.js:260)。
每天凌晨三点(dreaming-Axy2NX7c.js:14,cron 表达式 0 3 * * *),系统跑一次记忆整理。它把当日流水里的片段,晋升为持久记忆。晋升不是全收,而是打分过门(short-term-promotion-KmCGL-LA.js:1942),分数由六项加权求和,再加一个阶段加成(phaseBoost):
js
score = w_freq * frequency // 被召回过的次数(log 压缩)
+ w_rel * avgScore // 召回时相关度均值
+ w_div * diversity // 不同查询/不同天的覆盖度
+ w_recency * recency // 半衰期 14 天
+ w_consol * consolidation // 反复出现且跨天
+ w_conceptual * conceptual // 概念标签一致性
+ phaseBoost // 阶段信号加成变量名为示意,源码里实际取 weights.frequency 等字段;公式与 :1942 逐项一致。
门禁三条:minScore ≥ 0.75,minRecallCount ≥ 3,minUniqueQueries ≥ 3。
核心思想是:一条记忆值不值得长期保留,不由写入时觉得它重要来决定,而由后来被用到过几次来决定。
与多数 Agent 记忆方案最大的分歧点在这里:多数方案写入即永久,结果是记忆库越滚越大,检索越来越慢,噪声越来越多。
拿使用频率当晋升信号,等于让记忆库自己完成优胜劣汰。
管线三是持久记忆的预算内重写(short-term-promotion-KmCGL-LA.js:786)。这一环常被忽略:MEMORY.md 会一直增长,OpenClaw 因此给它设了字符预算。
超预算时,它的处理不是截断,而是让模型重写。提示里那句原话是:Revise the supplied MEMORY.md using only the supplied candidates as new evidence.
:878 处还有校验:超预算直接判失败,逼模型在预算内重新组织。
这句看着只是工程细节,其实点破了记忆系统的本质矛盾。记忆不是仓库,是叙事,仓库满了要扔东西,叙事满了要重写。
4.1.4.3 反思(Reflexion):只写回,不回头
Reflexion 的经典形态是四步:失败,自我批评,带着批评重试,成功。
OpenClaw 只做了前半截,它事后把经验写回去,但不带着它重试本轮任务。
实现是一个后台机制(experience-review-default-Cs48zOMl.js),几个设计点值得看。
触发条件(:19)是 EXPERIENCE_REVIEW_MIN_MODEL_ITERATIONS = 10,只有跑过 10 轮以上模型的轨迹,才有资格被复盘。这一条很聪明,短任务没有可提炼的东西,复盘它们只是浪费。
调度在 :98。系统空闲 30 秒后启动(:20),系统忙则退避(:21),超时 120 秒(:22),全局并发一(reviewInFlight),最多积压 32 个待复盘任务(:23)。
复盘在 :210 执行:开一个隐藏会话,读轨迹并产出提案。工具面被限制到只剩 skill_workshop(tool-policy-shared-Dz9K-0M1.js:36),改动预算一次(提示词 :91;配置项 skillWorkshopProposalMutationBudget)。
复盘提示词 experience-review-prompt-BQx_HkYg.js:54 给出本次轨迹中实际被调用过的技能清单,注释写的是 authoritative runtime receipt;同文件的 :91 是「一次最多一处改动」的预算(One mutation at most)。
以运行时回执为准,不采信模型自述。这条原则后面还会出现,这里第一次露面:凡是能让系统拿到事实的,就不要让模型回忆。
它为什么不做同一轮里的「批评—重试」,留到 4.1.5 讨论。
4.1.4.4 分支探索(Branch-and-Explore):并行可以,搜索不行
sessions_spawn 让模型在同一条消息里开出多个子代理。各自独立会话、独立工作区,甚至可以独立 git worktree(工作树;context: "isolated" | "fork",worktree: true)。
管理上有三项限制。第一项是深度:zod-schema-Dyhj0mbn.js:302 把 maxSpawnDepth 限在 1 到 5,默认 1,注释写着 1 表示不嵌套,sessions-spawn-tool-rRhXRAhF.js:3141 读取这个默认值。
第二项是等待:子代理完成后事件推送回来,主会话用 sessions_yield 让出。系统提示词里明文禁止忙轮询(system-prompt-params-BsU4X-Xb.js:834)。
第三项是助推::175 有一段 Proactive Sub-Agent Orchestration,要求并行调查、并行实现、并行验证。
但要留意它的边界,分支之间没有任何比较机制,没有评分,没有剪枝,没有回溯。
所以它是分支探索(Branch-and-Explore),不是树搜索(Tree Search),差别不在实现难度,在意图。前者为了并行提速,后者为了在不确定中找最优。
一个判据可以帮你分清自己在做哪一种。分支结果最后取第一个成功的,那是并行。全部收集后比较打分再选,才是搜索。
4.1.4.5 进度评估(Progress Evaluation):状态机加预算
goal 的实现跨 session-accessor-BFuIWHmX.js 的 :3905(状态集合)与 :3940-3991(构造器),状态枚举定义在 schema。状态集是 active、complete、blocked、paused、budget_limited、usage_limited;只有 complete 进终态后不可逆(TERMINAL_GOAL_STATUSES 只含它),其余都能回到 active。关键一行在 :3935:
js
if (next.status === "active" && next.tokenBudget !== undefined && tokensUsed >= next.tokenBudget) {
next.status = "budget_limited";
}完成由模型自己声明,花超了由系统判定,这个分工很关键。目标是否达成只有模型能判断,因为那是语义问题。资源是否耗尽必须是硬判定,因为那是算术问题。
把语义问题交给模型、算术问题交给代码,是这一章很实用的一条分工原则。
还有一处小设计更见功力。update_goal 的说明里写着(openclaw-tools-DoMY3wUr.js:3318):同一个阻塞连续三轮才算 blocked,普通难度与打磨不算。
这是用提示词约束模型的一种做法,模型遇到一点困难就宣布失败,这条约束专门堵这个。
但它只是提示词约束,代码没有强制。这是一个诚实的提醒,提示词能塑造行为,不能保证行为。需要保证的地方,必须落成代码。
4.1.4.6 约束满足(Constraint Satisfaction):把约束做成硬裁剪
这一类模式的名字容易让人误解成求解约束,OpenClaw 走了另一条路:不求解,直接裁。
六项约束,裁法各不相同。
- Token 预算:
session-accessor:3935,超了转budget_limited,停。 - 上下文预算:
agent-compaction-constants-CzVH4jGZ.js。提示词的最小预算取 8000 Token 与窗口 50% 中的较小者(MIN_PROMPT_BUDGET_TOKENS = 8000、MIN_PROMPT_BUDGET_RATIO = 0.5):大窗口下保底就是 8000,不是一半。 - 工具预算:
tool-surface-plan-Bl27z5-I.js:1702,maxToolCalls限制在 1 到 200 之间,超了直接失败(:1774)。 - 子代理深度:
zod-schema:302,1 到 5,超了拒绝 spawn。 - 权限:
agent-core:917的beforeToolCall,返回{block:true}就不执行。 - 墙钟:
timeoutSeconds加agent-core:246的stopIfAborted(),每步检查。
上下文预算那条见功力。
js
function resolveEffectiveCompactionReserveTokens({ contextTokenBudget, reserveTokens }) {
const minPromptBudget = Math.min(8000, Math.floor(contextTokenBudget * 0.5));
return Math.min(reserveTokens, contextTokenBudget - minPromptBudget);
}代码是简化示意,原文还套了两层 Math.max(1, …) / Math.max(0, …) 限幅。三行代码,防的是一个很现实的坑。使用者把 reserve 配成 200000 Token,想给压缩多留空间,结果大窗口模型被预留到没有空间放提示词,请求直接返回 400。
给使用者自由配置,同时用一行 Math.min 兜住下限,这是配置设计里很实用的做法。
4.1.4.7 自我优化:让系统改写自己的说明书
Prompt Optimization 与 Workflow Optimization,在 OpenClaw 里是同一套机制的两面,本书把这两者合称「自我优化」。载体是技能文件 SKILL.md。流程就是 4.1.4.3 讲的体验复盘:读轨迹,产出对技能的修改提案;按配置可为直接应用、留在 pending,或关闭修复。
为什么这算自我优化,不算普通日志?因为技能文件会被注入后续会话的系统提示词,改技能,等于改自己未来的提示词。系统在用自己的运行历史,训练自己的行为规范。
这个闭环有隐患,值得点出来。如果复盘的模型和干活的模型是同一个,它的自我批评质量上限,就是它自己的能力上限。
真正可靠的自我优化,需要外部信号参与评分。测试是否通过,使用者是否采纳,上线后是否回滚。
自己给自己的作业打分,分数再高也不作数。
重启续跑不属二十种模式,见 4.1.7 开头。
4.1.5 没实现的九种,与「为什么不做」的学问
上一节讲它有什么,这一节讲它没有什么。在源码里搜关键词,结果干净得让人意外。
| 关键词 | 命中 |
|---|---|
critique | 0 |
self-review | 0 |
debate | 0 |
second opinion | 0 |
mcts / beamSearch / treeSearch | 0 |
replan / re-plan | 0 |
表中「0 命中」均指运行时 JS 内 0 命中,不含 i18n(多语言包);critique、debate 仅在法、西语包出现。replan/re-plan 标 0 是按词边界、排除子串误命中后的结果;纯子串会命中 Poincareplane、configure-plan、prepare-plan。
九种缺失的模式可以归成三类,每一类的缺席理由都不同。
第一类是质量提升,四种模式都在这一类。Multi-Critic / Adversarial Critique / Judge Ensemble 在表格里挤在同一行,实际是三种做法,各自算一个模式。
缺席理由是:质量标准的定义权不在平台。什么叫好代码取决于项目,什么叫好文案取决于品牌。
平台若内置一套评审器,等于强行注入一种审美,注定被所有使用者绕过。这类循环必须由使用者定义,天然属于应用层。
这条理由也解释了 4.1.4.3 留下的那个问题:反思为什么不做同一轮里的「批评—重试」。自我批评同样要一套「什么叫更好」的标准,这套标准同样不在平台手里。原因在同一条边界:平台能把轨迹沉淀成经验,判不了这一版比上一版好多少。这条边界到底画在哪,等三类讲完一起收。
第二类是规划,Plan→Execute→Replan、Dynamic Workflow、Goal Decomposition 属于这一类。
缺席理由有两层,表层是规划粒度取决于任务,任务由使用者定义。
更现实的一层是:让模型自己生成计划再由自己执行,计划会退化成演给人看的文本。它随时可以偏离,而偏离不可见。
真要可靠,计划必须是外部可校验的产物。能被读,能被改,能被勾选,这就落到平台的存储层之外了。
第三类是搜索,Tree Search 与 Debate 缺席的理由只有一个,就是成本。
两者的代价同构,都要把一次调用变成多次。树搜索是分支数乘深度,辩论是辩手数乘轮数。对一个按 Token 计费、按并发受限的运行时,把默认行为设成每个问题探索八条路径,等于默认让使用者破产。
所以搜索出现在需要搜索的场景里,不会成为默认底座。
把三条理由合起来,可以给出一条清晰的架构判断。
平台负责不崩,应用负责更好。
凡是判断标准依赖业务语义的循环,比如质量、规划、搜索,都不能下沉到平台。凡是判断标准与业务无关的循环,比如记忆、预算、安全、并行,必须由平台兜住。
这条界线画错,两个方向都会出问题:平台越界,就变成臃肿且没人用的框架;应用该做的没做,就变成模型在没有护栏的情况下运行。
对读者的直接含义是:如果你在做长任务 Agent,别等框架给你质量环。它不会给,这块必须自己写。
4.1.6 防死循环:不数步数,数「无进展」
平台不该做的讲完了,再看平台必须做的那一半。这一节技术密度很高,也是 OpenClaw 借鉴价值很高的设计。
4.1.6.1 一个反直觉的事实:它不设最大步数(Max Steps)
在主循环文件 agent-core-Dp2OAIE9.js 里搜 turnCount、maxTurns、iteration,0 命中。原生循环不数轮数,不设步数上限,理论上一个 run 没有轮数上限。
对照一下就清楚了:主循环不消费 maxTurns 与 maxToolCalls。maxTurns 在 2026.8.35 的 dist 里 grep -rl 命中 9 个文件,主要分布在托管的外部 CLI 会话(如 runtime-DN4tCNMy.js:2241 往命令行塞 --max-turns=)、子代理乒乓上限与个别工具配置;maxToolCalls 命中 3 个文件(tool-surface-plan-Bl27z5-I.js、server-cron、worker/worker.mjs)。
第一反应通常是,这太危险了。
想清楚之后会发现,最大步数本身就是坏设计,因为步数上限惩罚的是做得多的任务,不是做错的任务。
一个正常的重构任务,改四十个文件、跑二十次测试,五十步根本不够。而一个死循环,可能在八步内就把同一条命令重复八次。
用固定步数当门槛,等于惩罚做得多的任务,纵容失控的任务。正确的门槛必须看进展,不看数量。
4.1.6.2 判据:结果哈希相等
核心文件是 tool-loop-detection-CcpBUDef.js,673 行,判据只有一条,但极其坚硬。
js
// :225 入参哈希
hashToolCall(toolName, params)
// :344 结果哈希
hashToolOutcome(toolName, params, result, error)
// :158 连续「无进展」计数
countNoProgressStreak(history, toolName, argsHash, ...)countNoProgressStreak 的循环体里,最关键是一行比较:
js
if (record.resultHash !== latestOutcome.resultHash && !repeatsSameFailure) break;直说:同名工具、同参数、同结果,算一次无进展;一旦结果变了,计数归零。这个定义很讲究,同一个工具调两次不算重复,因为 read 一个文件两次完全合法。
它要求三要素全部相同:工具、参数、结果。三者全同,说明世界状态没有因为这次调用改变分毫。对 exec 还有一层加强(:252 与 :280),先按固定模式(:273 的 VOLATILE_EXEC_FAILURE_PATTERNS)把输出里易变的片段抹掉,再哈希。
被抹掉的是五类:日期时间、时刻、attempt/retry 序号、时长单位、pid/ppid(进程号 / 父进程号)。这样同一个报错,只是日志里时间不同,也能被识别为同一个失败。带时间戳的临时路径是被时间戳规则顺带覆盖的,路径并没有被归一化。
这就是状态哈希比对的完整实现。把动作和结果都归一化成指纹,只认指纹,不认说辞。
4.1.6.3 六个检测器与三档阈值
detectToolCallLoop(:501)里挂了六个检测器,按严重度短路返回。下表阈值单位统一为次(工具调用次数)。
| 检测器 | 触发 | 级别 | 场景 |
|---|---|---|---|
unknown_tool_repeat | 同一不存在工具 ≥10 | critical | 模型在幻觉工具名 |
global_circuit_breaker | 完全无进展 ≥30 | critical | 总熔断 |
known_poll_no_progress | 10 警告 / 20 拦截 | warn/critical | 轮询类工具(process poll/log、command_status,见 :144) |
ping_pong | A↔B 交替 ≥10 / ≥20 | warn/critical | 乒乓式来回(:419) |
generic_repeat | 同参数 ≥10 警告 / 同结果 ≥20 拦截 | warn/critical | 通用重复 |
argument_churn | 每变体 ≥3 次、变体 >1 个、总失败 ≥10 次 | warn | 参数抖动但无进展(:101) |
三个常量定调(:214-216):
js
TOOL_CALL_HISTORY_SIZE = 30 // 滑动窗口大小
CRITICAL_THRESHOLD = 20 // 关键阈值
GLOBAL_CIRCUIT_BREAKER_THRESHOLD = 30 // 全局熔断阈值10、20、30 是权衡的结果:10 次足够让模型试错,编译、修、再编译,往往不止一两轮;20 次已经不像在探索,更像在撞墙;30 次无条件判死。
读源码还有一个前提要说清,本章引用的代码都来自 OpenClaw 的构建产物,也就是 dist/ 下的打包文件。文件名里带内容哈希,同一个哈希就对应同一份代码。
行号以写作时的打包产物为准,你换一个版本,行号会有偏移,但函数名不会变,用函数名去搜,比记行号可靠。
想自己核对,两条命令就够。前提是有 bash,以及一份 OpenClaw 的安装目录(npm 全局安装即可,包名 openclaw),目录下有 dist/。
bash
# 定位循环检测文件
grep -rn "countNoProgressStreak" dist/ | head
# 定位三个熔断常量
grep -rn "GLOBAL_CIRCUIT_BREAKER_THRESHOLD" dist/ | head第一条命令能定位到循环检测文件,第二条能定位到熔断常量的定义处。这也是 4.1.9 索引表保留文件名而不是只给行号的原因。
4.1.6.4 两级升级:先给一次机会,第二次直接杀
整套熔断机制的精妙之处在两级升级。第一击在 agent-tools.before-tool-call-BV6HiLJA.js:2441 检测,:2454 返回干预对象。系统不执行这次工具调用,而是返回一条错误结果给模型(agent-core:1198 的 completeToolLoopInterventionBatch)。
正文(:1214)要求模型不要重复这个动作,重新评估任务。它可以回答用户,可以请求澄清,也可以换工具或换参数继续。
同一步里的其他工具也一并挡掉,因为同一步里有一个动作在死循环,说明整步决策都不可信。第二击在 agent-core:331 记录状态,:347 终止。
js
if (executedToolBatch.intervention) toolLoopRecoveryState.criticalToolLoopSeen = true;
// ...
if (terminateRun) {
// 推入终止消息(:143),直接 agent_end 返回,不再给模型机会
}终止文本(:143)写得很明确。它说明这次 run 被停止,原因是循环恢复又遇到一次严重循环,被挡住的动作没有执行。
最后那句是点睛之笔,它明确告诉用户,被挡下的动作没有执行。在自动化系统里,最危险的不是失败,是不确定有没有产生副作用。这一句消除了歧义。
为什么要给第一次机会?因为检测器可能误判,一个真正需要重试的幂等操作,一刀切会杀掉正常任务。
给一次被挡加被提醒的机会,让模型自己换路,只有它换不动,才升级为终止。
这是所有熔断器的通用范式:先降级,后熔断。一上来就熔断,误杀率太高;永远不升级,等于没装。
4.1.6.5 盲区:这套机制防不住什么
哈希检测有三个已知缺口。对读者来说,讲缺口比讲优点更有价值。
缺口一,只认同参数、同结果,不认每次都变但都无用。如果模型每轮换一个参数,改不同行号、请求不同 URL、换不同文件,generic_repeat 永远不触发。
argument_churn(:101)是补丁,但它要求每个变体至少 3 次(MIN_STABLE_CALLS_PER_VARIANT)、变体数 > 1(即至少 2 个变体),且总失败次数 ≥ 10,覆盖太窄。
结论是,哈希相等能抓原地踏步,抓不到绕圈。要抓绕圈,需要更高层的语义判据,比如目标是否更近了。那不是哈希能做的事。
缺口二,没有全局轮数上限,单会话可以无限长,只靠压缩维持,有 goal 加预算时是安全的,budget_limited 兜底,没有 goal 时不设限。
这是有意的取舍,但它意味着使用者必须自己设超时。
缺口三,ping_pong 依赖 noProgressEvidence。
两边输出只要有一点变化,比如时间戳、随机 id,判据就失效。仓里对 exec 做了易变片段归一化(:273),但只能覆盖已知模式。
这一节的真正教训是:任何基于状态重复的检测,共同的敌人是输出里天然带的噪声。
想让检测可靠,先做归一化,归一化做不到的地方,就是检测的边界。
4.1.7 客观信号:让退出码说话
这一节回到一个根本问题。Agent 怎么知道自己做对了?
先补一个不属于二十种模式、但决定长任务能不能跑完的机制:重启续跑(main-session-restart-recovery-Cgmh4l7t.js:312 的 resumeMainSession)。
网关重启时,正在等工具结果或模型返回的那一轮会被打断。恢复的做法不是把会话清空重开,也不是让模型凭记忆接着编,而是把原有轨迹原样交回,再注入一条续跑提示(:160)。提示里只说两件事:从已有记录继续,把被中断或缺失的工具结果当作「结果未知」。
第二句是重点。中断之后最危险的,是模型把「没拿到结果」当成「命令成功」或「命令没执行」,两种猜测都可能引出错误的下一步。标成未知,等于把不确定性显式写进上下文,这与本节讲的「信号不失真」是同一条原则的另一种用法。
4.1.7.1 信号必须结构化,且无条件回灌
看 exec 工具怎么整形结果(bash-tools-DQBo2xnq.js:4161):
js
const status = outcome.status === "completed"
? (outcome.exitCode === 0 ? "succeeded" : "failed")
: (outcome.timedOut ? "timed_out"
: outcome.exitReason === "manual-cancel" ? "cancelled" : "failed");结果对象里带齐了 exitCode、status、timedOut、cwd、durationMs(:2023),文本末尾还会追加 (Command exited with code N)(:2036)。关键在于,这些结构化字段与尾部退出码无条件进入轨迹,不筛、不按重要性保留;正文超长时会被截断并标注 [... more characters truncated](truncateOversizedToolResultsInMessages / resolveLiveToolResultMaxChars),但不做语义摘要。概括地说:字段与退出码不丢,正文只做长度截断,不做摘要。
很多框架在这里省掉了这一步,把 stderr(标准错误)截一截,把非零退出码直接标成工具失败,甚至只在日志里记一笔、不往上下文塞。
结果模型在不知道刚才发生了什么的状态下继续行动。这才是长任务跑偏的常见原因。
4.1.7.2 错误分层:不是所有失败都叫失败
agent-core:913-1078 把工具错误主要分成五种,各有不同标记。
| 层 | 触发条件 | 标记 |
|---|---|---|
| 参数不合 schema | validateToolArguments 抛出 | isError:true, errorKind:"argument-validation"(:992) |
| 工具不存在 | 名字解析失败 | Tool X not found(:966) |
| 策略拦截 | beforeToolCall 返回 {block:true} | Tool execution was blocked(:930) |
| 循环干预 | 检测器 critical | status:"blocked", deniedReason:"tool-loop"(:1222) |
| 执行异常 | 工具自身抛出 | coerceErrorMessage(error)(:945) |
为什么分层?因为模型对不同错误的正确反应完全不同。参数错,改参数重试,这是好事;工具不存在,换个工具,不要重试。
被策略挡,放弃这条路,或者请人批准,循环干预,停下来重新想。把五种错误揉成一句 failed,模型只能猜。分层标注本质上是在给模型下指令,只不过借了错误信息的形式。
4.1.7.3 但它没有验收门
必须说清楚:OpenClaw 不判断任务做完了没有。没有跑测试必须通过的硬门,没有 verify 阶段,没有 PR 检查回路。唯一相关的是 agent-core:399 的 shouldStopAfterTurn,一个可选钩子,默认未设置,宿主可注入。
提示词层只有软约束(system-prompt-params-BsU4X-Xb.js:398)。
原文要求最终结论必须有证据,或者给出明确的阻塞说明。要求弱结果先换查询、换路径、换命令,再下结论。要求可变事实必须现场核实,比如文件、git 状态、版本、服务进程。
写得很好,但它只是提示词。
4.1.7.4 于是形成一条清晰的界线
把 4.1.6 与 4.1.7 合起来看,OpenClaw 的态度是:保证信号不失真,但不定义什么叫作对。
这是正确的切分,因为做对了的标准是业务语义,平台无从判断。而信号不失真是传输层职责,平台必须保证。
由此推出的几条做法,落到操作层面就是 4.1.8 的第 6、7 条原则:信号不失真、不定义对错,这里不再重复。
4.1.8 七条原则
把上面的观察收成七条,每一条都能直接落到代码上。
- 循环体要薄。压缩、换模型、停机判定全部做成钩子,不要塞进 while。循环体的寿命取决于它有多简单。
- 压缩要重写成结构,不要截断。固定骨架加增量合并。多次重写的衰减,比一次截断更致命。
- 记忆的淘汰由被用过几次决定,不由写的时候觉得重要决定。打分晋升比写入即永久撑得久。
- 别用步数当门槛,用无进展当门槛。三要素哈希全同才算原地踏步。步数上限惩罚做得多的任务,纵容死循环。
- 熔断要两级,先降级,后熔断。第一次挡住并提醒重新评估,第二次直接终止。误杀成本高于漏放。
- 客观信号必须无条件回灌,并分层标注。退出码不进上下文等于没测,五种错误揉成一句 failed 等于没告诉模型怎么办。
- 平台管不崩,应用管更好。质量环与规划环的判断标准依赖业务语义,不会由通用平台提供。要么自己写,要么就没有。
这一节把 OpenClaw 的循环看完了。下一节换一个角度,看 DeepSeek Harness(下称 DSH)怎么把五大范式拆进模块。
4.1.9 源码索引(附录:正文读完可跳过)
| 结论 | 源码位置 |
|---|---|
| 主循环 / 外层 / 内层 | agent-core-Dp2OAIE9.js:236 / :274 / :276 |
| 单轮模型调用 | agent-core-Dp2OAIE9.js:432 |
| 工具步(并行/串行) | agent-core-Dp2OAIE9.js:507 / :564 / :668 |
| 每轮钩子 / 停机钩子 | agent-core-Dp2OAIE9.js:385 / :399 |
| 循环终止消息 | agent-core-Dp2OAIE9.js:143 / :331 / :347 |
| 循环干预注入文本 | agent-core-Dp2OAIE9.js:1198 / :1214 |
| 循环检测主函数 | tool-loop-detection-CcpBUDef.js:501 |
| 熔断常量 | tool-loop-detection-CcpBUDef.js:214-216 |
| 状态哈希(入参/结果/失败身份/无进展) | tool-loop-detection-CcpBUDef.js:225 / :344 / :280 / :158 |
| 易变片段归一化 | tool-loop-detection-CcpBUDef.js:273 |
| 检测器接线 | agent-tools.before-tool-call-BV6HiLJA.js:2441 / :2454 |
| 压缩提示词(骨架 / 增量合并) | compaction-D9ok_o6I.js:699 / :731 |
| 压缩触发(双条件) | agent-runner-memory-CZMzDnRW.js:607 |
| 压缩前抢写 memory flush | agent-runner-memory-CZMzDnRW.js:133 / :148 / :157 |
| 夜间晋升(cron 与门禁) | dreaming-Axy2NX7c.js:14 / :29-32;dreaming-CeTJnIOU.js:260 |
| 晋升打分与 MEMORY.md 改写 | short-term-promotion-KmCGL-LA.js:1942 / :786 / :878 |
| 体验复盘(触发/调度/执行) | experience-review-default-Cs48zOMl.js:19-23 / :98 / :210 |
| 复盘输入与改动预算 | experience-review-prompt-BQx_HkYg.js:54 / :91 |
| 子代理深度限制 | zod-schema-Dyhj0mbn.js:302;sessions-spawn-tool-rRhXRAhF.js:3141 |
| 工具预算限制 | tool-surface-plan-Bl27z5-I.js:1702 / :1774 |
| 目标预算熔断 | session-accessor-BFuIWHmX.js:3905 / :3935 |
exec 退出码整形 | bash-tools-DQBo2xnq.js:2023 / :2036 / :4161 |
| 重启续跑 | main-session-restart-recovery-Cgmh4l7t.js:160 / :312 |
| 执行偏好提示词(软约束) | system-prompt-params-BsU4X-Xb.js:398 |
| 子代理助推提示词(软约束) | system-prompt-params-BsU4X-Xb.js:175 |
4.2 DeepSeek Harness:五大范式在代码里的落点
上一节我们沿着 OpenClaw 的源码,看完了二十种循环模式怎么被落成一套最小运行时。那是模式层面的答案,解决的是系统怎么转起来。4.1 拆的是 Loop 层内部的形态,这一节把镜头拉远,看五个范式各自的位置。 但第 3 章还留了一个问题没答:提示词(Prompt)、上下文(Context)、工具使用层(Harness)、执行循环(Loop)、图编排(Graph)这五个范式,落到真实代码里,各自是什么样子?这一节换一个样本,专门回答这个问题。 样本是 DeepSeek Harness(下称 DSH)。选它的理由一句话:它把五个范式都落到了代码里,开源、能读也能跑,而且不假装自己什么都有。理由在 4.2.2 展开,这里先把版本钉死。
4.2.1 版本与阅读范围
开源项目每天都在动,同一个文件路径,隔一周再去看,行号可能已经漂了几十行。所以动手之前,第一件事是先把版本钉死。
下面这组信息,是本节全部结论的地基。读者手上的代码如果不是这个提交,后面的行号会全部对不上。
- 仓库:github.com/deepseek-ai/deepseek-harness
- 分支:master
- 提交号:ce7073d51254c26cd63b22a60835b8f948deb447
- 提交时间:2026-10-30 00:13:15 +0800
- 根包版本:@deepseek-ai/dsh-root 0.2.2-alpha.2
- 阅读范围:仓库根下的
packages目录,一共 52 个子目录(58 个条目)。 - 引用口径:31 个文件 + 2 个目录,均在
packages内;另 4.2.8.2 引用了根目录benchmarks。
复现只要四行,复制就能跑。
bash
git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
git checkout ce7073d51254c26cd63b22a60835b8f948deb447
git rev-parse HEAD最后一行应该回显 ce7073d51254c26cd63b22a60835b8f948deb447,一旦它和上面写的不一致,就先别往下读,先换版本。 还有一件事要交代清楚。我们本机跑的是 npm 上的 @deepseek-ai/dsh 0.2.1-rc.2,和 master 上的源码并不完全一致,有些模块在发布包里还没跟上。
本机实验单独注明,不写成源码行为。
引用格式统一写成 packages/core/tools/src/pipeline.ts:539 这样,冒号后面是行号;只写目录或包名、不给行号的,指整个目录或整个包。所有行号都按 ce7073d 计算,换了版本就要重新数。
4.2.2 为什么拿 DSH 当解剖样本
导语里只给了一个理由,这里展开成三条。
第一条,开源,能读源码,也能跑。能跑的是 npm 发布版(0.2.1-rc.2),master 以源码阅读为主,未完整运行。只读文档学不到的东西,读源码能学到;把发布版跑一遍,能看到源码里看不到的行为。 第二条,模块化。它把插件、会话、沙箱、压缩、子 Agent 都做成了独立模块,彼此之间靠服务接口连接,可以一块一块拆开看。 第三条,边界诚实。它并不假装自己什么都有。评测模块没有,分布式调度也没有。
这种边界反而适合用来讲课。一个什么都有的框架,会让人误以为做 Agent 必须把这些全装上;一个边界清楚的框架,才能让人看清哪一层是地基,哪一层是装修。
我们用一个比喻贯穿本节,把 Agent 当成一名刚入职的工程师。
工程团队要做的,不是替他思考,而是给他一套能问、能记、能用、能改、能协作的工作环境。
五个范式,正好对应这五件事。把顺序对上是这样的:能问对应 Prompt,能记对应 Context,能用对应 Harness,能改对应 Loop,能协作对应 Graph。
- Prompt 工程:让他学会提问
- Context 工程:让他学会记笔记
- Harness 工程:让他学会使用工具
- Loop 工程:让他学会有逻辑地思考
- Graph 工程:让他学会复杂的规划
下面按顺序拆开看,关键结论会给出源码位置,便于直接核对。
4.2.3 Prompt 工程:让 Agent 学会提问
新人入职第一天,最怕的不是不会干活,是不敢问。需求含糊时硬着头皮做,结果一定返工。
Agent 也一样。Prompt 工程的真正难点,不在于把话说漂亮,而在于让模型知道什么时候该停下来问一句。
4.2.3.1 Prompt 是一张装配图
很多人以为系统提示词就是一大段字符串。DSH 的做法不是这样。 它把 Prompt 拆成有序的分区(section),由插件分别贡献,最后统一装配。装配入口是一个瀑布式钩子(waterfall),任何插件都可以在装配前后插入自己的逻辑。
代码在 packages/core/system-prompt/src/index.ts:31。
装配好之后还有一步严格渲染,renderPrompt 只做三件事:替换 、丢弃空分区、拼接,代码在 packages/core/system-prompt/src/index.ts:297。按声明位置排序发生在装配阶段,index.ts:659 排分区,index.ts:680 排上下文。
这里面有两个固定分区值得注意,一个是 deployment:persona-prefix,一个是 deployment:persona-suffix,分别定义部署级人设的前缀和后缀。 它们分别在 index.ts:197 和 index.ts:200,同名分区会让更近的作用域版本生效,这意味着团队可以定统一人设,具体 Agent 再局部覆盖。
人设靠装配,不写死在代码里。工作区里的规范文件走另一条路:首次请求时注入为持久的用户消息,文件变更或会话恢复时刷新。DSH 会自动发现 AGENTS.md 和 CLAUDE.md,按用户全局链和项目链分别读取。候选文件名配置在 packages/context/agent-instructions/src/config.ts:12。
读取有字节预算,文件太大就整份丢弃或截断,并给预算提示,避免一个仓库的说明文档把上下文吃光。
装配与渲染是两步,不是一步,这一点在代码里看得很清楚。
ts
const assembly = ctx.systemPrompt.assemble(context)
const text = renderPrompt(assembly)如果把它们合成一步,插件就没有插入点,缓存也没法复用。分开之后,装配可以按需重算,渲染可以按内容做缓存。
装配得当,模型才知道什么该自己定、什么该交回来问,这是「学会提问」的前半截。
4.2.3.2 提问要写进工具契约
让模型会提问,不能只靠一句「遇到不确定就问」,要在工具层面给它一个动作。
DSH 提供了 ask_user_question 工具,描述写得很直接:需要确认、需要选择、缺少信息时,向用户提出一个简洁的问题。
代码在 packages/interaction/tool-ask-user/src/index.ts:31。
这个工具默认会阻塞等待答案,支持一次问多个问题,id/question 必填,header/options 可选。如果模型有推荐项,要把推荐项放在第一位,并在标签后加上 (Recommended)。 这些约束写在 schema 里,代码在 index.ts:46-59,工具还提供 timed 模式,默认等待 120 秒。
超时后模型可以继续做不依赖答案的工作,问题仍然保留可答,配置在 index.ts:24-25,这个设计比一直阻塞更实用。
注意:子 Agent 调用这个工具会被直接拒绝(
DELEGATED_CALLER),因为它没有可以直接对话的人类界面,不会进入等待。拒绝发生在user-questions/src/index.ts:144-148,不在工具本身;子 Agent 必须把未决问题写进最终结果。
一句话总结这一层:提问不是模型的态度,是工具的能力。工具不给它这个口子,它就只能猜。
4.2.3.3 计划先审后干
除了问一句,还有一种更重的提问方式,就是先交计划再动手。
DSH 的计划模式(plan mode)用 /plan 进入,模型先探索、先设计,然后交出一份完整计划,等用户批准。用户可以批准继续,也可以退回意见让它重做。
状态能跨会话恢复和分叉,说明它落在事件流(session log)里,不是内存里的临时开关。 这里有一个容易被忽略的取舍:进入计划模式后,所有工具仍然可用。
说明在 packages/plan/plan-mode/README.md:12:真正的限制要靠沙箱模式和审批提示,不能指望计划模式本身。
这个取舍值得读者记住,计划模式约束的是节奏,不是权限。把两者混在一起,容易出事。
所以计划审批也是提问,问的是方案本身:这个方案你认不认,而不是某个参数对不对。
4.2.3.4 本小节可以带走的做法
- 把系统 Prompt 拆成可注册的分区,让人设、规范、工具说明分别维护。
- 给模型一个显式的提问工具,并在描述里写清什么时候用。
- 需要重决策时先要计划,再放执行,别把计划和权限混为一谈。
4.2.4 Context 工程:让 Agent 学会记笔记
新人记性再好,也记不住三个月的项目细节,所以他得记笔记。记笔记要回答两个问题:记什么,丢什么。
记什么,分两层。底层是事件流,所有原始记录都往那里追加,这是笔记的底稿(4.2.4.1);日志之上有两类笔记,一类是给模型看的待办列表(todo_write),一类是给系统看的长期说明书,两类都在 4.2.4.2。
丢什么,也分两步。先有记不下时的三层处理(4.2.4.3),再把窗口、输出、余量三项预算绑在一起算(4.2.4.4)。
4.2.4.1 笔记的底稿是事件流
DSH 的会话不是一段聊天记录,而是一条事件流。模型消息、工具调用、工具结果、系统消息,全部通过 session.append 追加成事件。
界面上看到的标题、Token 用量、上下文压力、待办列表,都是事件流的投影,不是另存的真值。
这个选择带来三个直接好处:可以回放、可以压缩、可以恢复。
回放是把整条轨迹重新走一遍,用来复盘和调试,出了问题能看到当时每一步看到了什么、做了什么。
压缩之所以可行,是因为模型看到的只是投影层,原始事件还在事件流里,需要时能查回来。
恢复则靠检查点,DSH 在模型请求前、工具产生副作用前,会做一次语义检查点(semantic checkpoint),说明在 packages/session/session-checkpoint-policy/src/index.ts:53-59(文档注释),实现行用 semantic checkpoint 关键字定位。
检查点失败就不发请求,也不执行工具。宁可停下,也不留下半截状态。
所以两者分工不同:事件流保存原始记录,检查点提供快速恢复点。
4.2.4.2 给模型看的待办列表,给系统看的说明书
任务一长,模型会忘记自己做到哪一步,所以要给它一张待办列表。
DSH 的待办列表就是 todo_write,它让模型把多步任务拆成条目,标出当前正在做哪一条,做完一条勾掉一条。
每次更新都替换整张列表,而且只有拥有该会话的 Agent 能改。这张列表跨轮次存在,重开会话也还在,本质上也是事件流上的一个投影。
工具说明在 packages/todo/tool-todo/README.md。
模型下一轮读到的是落盘的清单,不是自己的记性。计划模式提供的是另一种待办,计划卡片会留在对话里,用户能看到,模型也能回看。
两种待办一个对内,一个对外,配合起来刚好。
待办之外,还有一类长期知识,它更像说明书。长期知识不放在会话里,它放在工作区的 AGENTS.md 里,与 4.2.3.1 的规范文件同一套注入机制。
这个选择的代价是每轮都要花 Token,好处是知识可以进版本库、可以评审、可以回滚。
两者的区别可以概括成一句:待办记的是这一轮做到哪,说明书定的是每一轮都要守什么。
4.2.4.3 记不下时的三层处理
上下文窗口再大也有上限,DSH 的处理分三层,从便宜到贵。
第一层是计量,它用固定文本密度估算 Token,先用便宜的办法算个大概,代码在 packages/llm/token-meter/src/estimate.ts:13。
真实用量回来之后,在相同信封下复用模型服务商(provider)的用量作锚点,其余按路由重算,包括缓存命中的部分。
第二层是确定性剪枝。工具结果超过 thresholdChars(默认 8192)时,只留头部 4096 个字符和尾部 1024 个字符,中间替换成固定标记,配置在 packages/compaction/compaction-tool-result-pruner/src/config.ts:11-12(thresholdChars 在 :11,headChars 在 :12)。
这一层不需要模型,也不会破坏工具调用与结果的配对关系,所以回放是安全的。
第三层才是模型摘要,阈值上限是窗口的 0.8,实际取它与 pressureBudget 的较小值;保留比例 0.16 的基数是 messageBudget。两个默认值配置在 packages/compaction/compaction-basic/src/config.ts:20 和 config.ts:23。
压力检查挂在每一步开始前,代码在 packages/compaction/compaction-basic/src/index.ts:157。如果摘要做完还是溢出,还有一条兜底路径。
模型服务商报上下文超限时,会触发溢出恢复(context-overflow recovery),压缩成功后重试,代码在 index.ts:213。
大结果还有一条单独的出口。单条工具结果超过内联预算时,全文写入溢出存储(spill),模型只看到头尾和一条可读路径,代码在 packages/spill/spill-policy/src/index.ts:99-107。
这条出口不属于上面三层。三层处理的是整个上下文,溢出存储处理的是单条大结果,是旁路,不是第四层。
压缩失败时,原始内容仍然可见,不会二次丢信息。
4.2.4.4 三个预算必须一起算
4.2.4.4 是 4.2.4 里最容易被忽略的一节。我们把公式写出来。
压缩预算不是窗口减一点,它要同时扣掉两样东西:本轮请求预留的输出 Token,以及给增长留的余量。
text
messageBudget = contextWindow - reservedCompletionTokens
pressureBudget = messageBudget - headroomTokens
threshold = min(contextWindow × 0.8, pressureBudget)reservedCompletionTokens 的取值逻辑在 packages/compaction/compaction-basic/src/index.ts:65,它优先用请求头里的输出上限,没有就用适配器的默认值。
这就埋了一个坑。假设窗口设成 128K(128000),输出上限也设成 128K(128000),那么 messageBudget 直接变成 0,每次定价解析配置(resolveCompactSpec)时都会抛 TargetPressureConfigError,代码在 config.ts:172-179,由 compaction-basic/index.ts:157-178 的 agent/pre-step 钩子捕获。
注意:这个异常在每次 pre-step 被捕获后只记一条警告(同一目标用
Set去重),压缩会被静默禁用;长会话会一直跑到模型服务商报上下文超限才失败,中间没有任何提示。
我们在 2026-10-17 做过一次这样的本机实验(本机 npm 0.2.1-rc.2,未在 ce7073d 复验),把窗口和输出都压到 128K,本意是更早触发压缩。源码读完才发现,压缩根本没有运行。
后来改成窗口 128K(128000)、输出 32K(32768)、默认余量 64K(65536),阈值才落到 29696 个 Token,压缩真正生效。
这三个数,可以自己代进去算一遍。
javascript
// node >= 18,直接 node budget.js 就能跑
const contextWindow = 128000
const reservedCompletionTokens = 32768 // 32K 输出上限
const headroomTokens = 65536
const messageBudget = contextWindow - reservedCompletionTokens
const pressureBudget = messageBudget - headroomTokens
const threshold = Math.min(contextWindow * 0.8, pressureBudget)
console.log({ messageBudget, pressureBudget, threshold })
// { messageBudget: 95232, pressureBudget: 29696, threshold: 29696 }把 reservedCompletionTokens 改成 128000,messageBudget 变成 0,解析配置时抛配置错误;若只按公式算,threshold 会是 -65536,但代码走不到那一步。
这个例子说明一件事,上下文参数不是三个独立的旋钮,而是一组联立方程。改一个数之前,先把另外两个数代进去算一遍。
4.2.4.5 本小节可以带走的做法
- 会话用事件流做底稿,投影层负责展示,别把两者混成一份数据。
- 让模型自己维护待办列表,列表比记忆可靠;长期规则另放说明书,首次请求注入,文件变更或会话恢复时刷新。
- 记不下时的三层处理,从计量、剪枝到摘要,能用不花钱的办法就别调模型。
- 窗口、输出上限、余量三个数必须一起算,单独调一个数往往不生效。
4.2.5 Harness 工程:让 Agent 学会使用工具
新人会用工具,靠的是工位上有工具、有说明书、有权限卡,还有安全员,而不是聪明。
Harness 工程就是把这一整套配齐,它包含五件事:工具契约、工具形态、执行隔离、权限审批、外部工具接入。这五件事分别对应 4.2.5.1 到 4.2.5.5。
4.2.5.1 工具是契约,不是函数
DSH 定义工具的方式很像定义 API,参数有 schema,输出也有 schema。
参数校验在模型给出参数之后、工具执行之前完成,入口是 validateArgs,代码在 packages/core/tools/src/schema.ts:480。
输出校验在工具返回之后完成,违规直接转成错误结果,代码在 packages/core/tools/src/pipeline.ts:539。
这套双向校验的价值在于边界清晰。模型乱填参数,进不了工具体;工具返回脏数据,也进不了上下文。
错误也不会以异常形式炸穿整个循环。任何监听器或审批环节抛错,都会被折叠为一个带 isError 的工具结果,代码在 pipeline.ts:496。
packages/core/tools/src/pipeline.ts:484 的注释把这条规则写得很明白。模型下一步能看到它,然后自己决定怎么改。
4.2.5.2 工具形态:原生与 PTC 两种
这是 DSH 里最有意思的设计,同一批工具可以有两种呈现方式。
一种是原生模式,每个工具都是一条函数定义,模型逐个调用。另一种叫 PTC(DSH 文档称 Program-based tool execution)。
模型只看到一个 run_code,外加一份生成的 SDK。工具变成宿主提供的异步函数,模型写一段 TypeScript 程序来编排它们,说明在 packages/core/tool-executor-ptc/README.md:8-10。
这个模式解决的是工具太多导致的上下文膨胀。五十个工具就是五十段 schema,每轮都要占用窗口(数量为经验估算,未实测)。收成一个 run_code 之后,schema 只剩一段。
代价是执行面变大,模型写的程序必须被关起来跑,DSH 的执行方式在 packages/ptc-runtime/ptc-runtime-node/README.md。
默认是每次调用起一个全新的 Node 进程,套用文件沙箱,限制执行时长、输出大小和 V8 堆内存。取消时清理整个受管进程范围。
什么时候用哪种,判据有三条:工具数量少、调用频率低,用原生,模型能逐条看见工具说明;工具多到把窗口撑满,用 PTC;要把多个调用编排成一段带分支、带循环的程序,也只有 PTC 能做。工具数量的分界没有硬阈值,以实际窗口占用为准。
一句话概括:把工具调用从多轮对话,变成一次程序执行。
4.2.5.3 沙箱是内核给的
一些框架的沙箱是「我们建议你不要越界」。DSH 不是,它直接用操作系统的隔离能力。
Linux 上先用 bwrap,不可用再退到 Landlock;macOS 用 Seatbelt;Windows 用受限令牌加 ACL。平台链代码在 packages/sandbox/sandbox-local/src/index.ts:161。
选哪条链不是猜的,启动时会逐个探测,能创建 profile 才算可用,探测失败就换下一条。
文件策略只有两种语义:只读,或者工作区可写。翻译成具体参数在 packages/sandbox/sandbox-local/src/profiles.ts:16。
只读模式挂载整个根目录为只读,再挂 /dev、/proc,并加 --die-with-parent。工作区可写时,额外把工作区目录以可写方式绑定进去。
沙箱不是 Prompt 能绕过的,拒绝发生在系统调用层,进程拿不到那个能力,这是 Harness 与 Prompt 的分界线。
命令执行还有两重预算,默认前景超时 120 秒,输出上限 64KB,代码在 packages/shell/bash-local/src/index.ts:102-104。
每次调用都会把请求的超时夹在配置的上下限之间,代码在 index.ts:122。进程也不是杀一个就完,Linux 上按进程组回收,先发 SIGTERM,再按需发 SIGKILL,宽限期 DEFAULT_GRACE_MS = 3000。
回收代码在 packages/subprocess/subprocess-local/src/linux-scope.ts:608,这样才不会留下孤儿进程继续跑。
4.2.5.4 审批要默认拒绝
权限系统最怕默认放行,DSH 的选择是失败关闭(fail-closed,即默认拒绝)。
审批只有四种结果:允许一次、拒绝、取消、不可用,只有「允许一次」会放行,剩下三种全部按拒绝处理,代码在 packages/interaction/user-approval/src/types.ts:32。
连审批通道不存在这种情况,也按拒绝走,代码在 packages/core/tools/src/pipeline.ts:437-440。
这个细节很关键,很多事故就出在「拿不到审批就当他同意」。
用户侧的权限预设是两个独立旋钮的组合:沙箱模式加审批策略。预设只是把两个值一起写下去,并不会绕过任何一层,接口在 packages/interaction/permission-presets/src/index.ts:57-67,写入逻辑在文件头注释与 apply。
DSH 还有一个实验性的自动复核插件。工具执行前,让当前模型先判断这个动作该不该放行。允许就全权执行,拒绝就转人工,说明在 packages/experimental/auto-review/README.md。
这个插件自己的文档写得很克制,它明确说可能放行危险动作,也可能误拒正常工作,还会额外消耗 Token。
这种克制的写法,比功能本身更值得学。
4.2.5.5 外部工具怎么接
企业环境里,工具往往不在本进程,它们通过模型上下文协议(Model Context Protocol,MCP)暴露。
DSH 有一个 MCP 客户端桥,它连接 MCP server,把对方声明的工具注册到本地工具注册表。
对模型来说,远程工具和本地工具没有区别。代码在 packages/mcp/mcp-client。
这一层的价值是统一:注册、命名、校验、审批复用同一套管道,不需要为远程工具再写一遍治理逻辑。超时由 MCP 自己的 per-call 默认(60 秒)控制,本机 shell 是 120 秒;沙箱策略按工具类型分别套用。
4.2.5.6 本小节可以带走的做法
- 工具要有输入与输出双 schema,错误以结果形式回灌,不要把异常抛出循环。
- 工具太多时,考虑把工具形态收成一个程序入口,再配一个沙箱执行器。
- 沙箱优先用操作系统能力,不要用 Prompt 当围栏。
- 审批默认拒绝,通道不可用也拒绝。
- 外部工具走同一套注册与治理管道,别为远程调用另开一扇门。
4.2.6 Loop 工程:让 Agent 学会有逻辑地思考
新人干活,第一次做错很正常,区别在于有人能自己发现、自己改。
Loop 工程就是把这个过程工程化,它要解决三个问题:循环怎么转,错误怎么回,什么时候停。本小节按这三问展开:4.2.6.1 讲怎么转,4.2.6.2 讲错误怎么回,4.2.6.3 讲什么时候停,4.2.6.4 讲循环本身不适用时换什么。
4.2.6.1 循环的最小骨架
DSH 的循环很朴素,一个轮(turn)里套若干步(step),每一步做四件事:装配 Prompt、发模型请求、收流、执行工具批。
主循环在 packages/core/agent-loop/src/agent.ts:344,是一个 while (true),每步结束时判断下一步怎么走。
判断条件也很朴素,模型这一轮没有产生工具调用,就认为本步完成,代码在 agent.ts:587。有工具调用,就交给工具执行器,执行完继续下一轮。
工具批不是串行跑的,执行器维护一个并发池,同时最多跑 maxParallelToolCalls 个调用,池的实现从 packages/core/tools/src/batch.ts:186 开始。
并发之后还要保证顺序,结果提交按原调用顺序进行,这样事件流是可回放的。
并发与确定性在这里并不冲突,它们只是需要把提交和调度分开。
4.2.6.2 错误是输入,不是异常
这一条是 Loop 工程的核心。
工具失败时,DSH 不会让异常穿出循环,它把失败写成一条工具结果,标上 isError,追加进事件流。代码在 packages/core/tools/src/batch.ts:258。
模型下一步自然读到这条结果,然后决定重试、换方法,还是停下来问人。
一步失败时,已经完成的工具结果也不会被丢掉。恢复逻辑在 agent.ts:374,这一点在长任务里很重要,否则一次失败会把前面十分钟的成果全部作废。
请求层面也有恢复,模型请求失败时,会走一个瀑布式钩子,下游可以决定重试,代码在 agent.ts:549,只有下游返回重试,循环才继续。
这就是「有逻辑地思考」的工程含义。不是让模型多想几步,而是让每一步都有可读的反馈,并且反馈能进入下一轮。
4.2.6.3 失控必须有边界
没有边界的重试,就是死循环。
DSH 的重试策略按模型服务商配置,默认值配置在 packages/llm/llm/src/retry-policy.ts:14-17,四行分别对应次数、初始延迟、最大延迟和抖动比例。
只重试五类瞬时错误:空响应、限流、服务端错误、超时、传输错误。退避是标准的指数加抖动,代码在 packages/llm/llm-retry/src/index.ts:59。
抖动的作用是避免多个请求在同一时刻一起重试。溢出恢复也有上限,溢出重试次数超过配置值就放弃,代码在 packages/compaction/compaction-basic/src/index.ts:222-223。
死循环还有另一种形态:重复。同一个工具、同样的参数,连续调用很多次。
DSH 的处理是提醒,不拦截。第 3 次、第 5 次、第 8 次重复时,插入一条建议,让模型检查上一条结果,说明在 packages/guard/repeat-tool-reminder/README.md。
提醒而不是拦截,是因为合法重复确实存在。比如轮询一个部署状态,这属于有边界的例外,不推翻前面的判断。
重试有边界,循环本身也要有停止条件:
- 循环自身只在没有工具调用时正常结束。
- 轮次、Token、时间预算不在 agent-loop 里,它们属于外层:目标循环 256 轮、工作流上限(caps)、作业超时。
- 重复调用只提醒,不拦截。
- 审批被拒是一条工具结果,不是停止条件。
工作流 caps 与作业超时的默认值以配置为准。
循环内部只能判定第一条,其余都由外层决定。任何一条都不满足时,继续转才是对的。
4.2.6.4 什么时候该换一种循环
同一种循环跑不动所有任务。DSH 准备了三种替代,各有各的适用条件。
第一种是目标(goal)循环。一个目标跨多轮持续存在,可以暂停、恢复、完成、阻塞。自动续跑有轮次上限,默认 256 轮,说明在 packages/goal/goal/README.md。它适合目标明确、但一次做不完、需要跨轮次活着的任务,比如持续盯一个指标。
第二种是子 Agent。把一段独立工作交给子 Agent,并发上限默认 8,代码在 packages/subagent/subagent/src/index.ts:197。它适合能独立出去、不需要和主循环共享上下文的一段工作。
第三种是 Ralph 循环。每一个 Round(轮次)都起一个全新的子 Agent,只把上一轮的有界报告交给下一轮。它适合目标固定、但每次尝试都可能失败、需要反复重来的任务,因为每轮都从干净上下文开始。
文档里有一句很重要的话:这些报告不会被独立验证。
这句话值得记住。Loop 工程的边界就在这里。循环能自纠,但不能自证。
4.2.6.5 本小节可以带走的做法
- 循环的终止条件要简单可判定,比如本轮没有工具调用。
- 工具错误写成结果回灌,不要抛出异常打断整轮。
- 重试按错误类型区分,设次数、延迟和抖动三重边界。
- 重复调用先提醒,别急着拦截。
- 停不下来的循环先把边界写清楚:内部只看有没有工具调用,预算、重复提醒与审批都在外层。
- 循环能自纠,但不能自证,验证要交给外部信号。
4.2.7 Graph 工程:让 Agent 学会复杂的规划
一个人能改一个模块,一个版本却要十几个人协作。
协作靠的不是更聪明的个人,是更清晰的流程图。谁先做,谁后做,哪几步能并行,失败了回到哪一步,这些是图的问题,不是循环的问题。
4.2.7.1 图是给执行器读的
DSH 的图不画在白板上,它就是一段 JavaScript。
模型写一段编排脚本,脚本里可以调用 agent()、parallel()、pipeline()、phase() 和 log(),执行完返回一个 JSON 结果。能力说明在 packages/workflow/workflow/README.md。
agent() 起一个子 Agent 干活,parallel() 并发跑多个分支,pipeline() 把多个阶段串起来。phase() 标记阶段方便观测,log() 输出过程日志。
这段脚本由执行引擎跑,模型不逐句解释。引擎负责创建子会话、归属关系、失败与取消的收尾。脚本在受管运行时里执行,受权限与审批约束;隔离由所选运行时的操作系统层机制完成(见 4.2.5.3 与 4.3)。模型负责画图,引擎负责执行图。
这是一个很清晰的分工。模型擅长在不确定中做设计,引擎擅长在确定中做执行。让模型直接控制几十个子任务的时序,容易乱套。
4.2.7.2 节点里跑循环,边上做路由
图的基本单位是节点。每个节点内部仍然是前面那个 Loop。
一个节点可以是一个子 Agent,也可以是一段固定步骤。节点内部自己转圈,转不出来就返回失败,边上的逻辑决定下一步去哪。
DSH 的编排脚本里有条件分支,也有并发汇合。失败处理有一条纪律:致命错误会从 parallel() 和 pipeline() 直接抛出,而不是被吞掉。
代码在 packages/workflow/workflow/src/index.ts:124;index.ts:141-148 是具体判定。
前台执行会等所有工作结束。需要异步时,可以带 run_in_background,立刻拿到一个作业编号,之后查输出,说明在 packages/workflow/tool-workflow/README.md。
取消或异常结束时,返回的是错误,部分成功不会被当成结果,这个选择很硬,但对企业场景是对的。半成品比没有更危险。
4.2.7.3 团队也是一种图
除了脚本,DSH 还提供了团队形态。
一个 Lead,若干具名队友,直接消息,加一块持久任务板,代码在 packages/experimental/agent-team。团队名册和任务状态会被保留,队友可以冷启动恢复。
这个包目前是实验性的,而且要求持久化存储可用。用它之前要先确认这两点,否则会出现任务板丢失。
从图的角度看,团队就是一张动态图。节点是人,边是消息和任务依赖。和脚本编排相比,它更适合开放式的长任务。
具体说,Lead 是调度节点,队友是执行节点,消息与任务依赖是边,任务板是共享状态。图的三样东西在这里都能对上。
4.2.7.4 长目标怎么放图上
有些任务没有明确的结束点。比如持续盯住一个指标,有异常就处理。
这类任务其实不放在图上。目标是 Loop 的持久化,不是图:一个会话一个目标,跨轮次存活,可以暂停和恢复,它解决的是单条循环怎么活下去,不是多条分支怎么路由。轮次上限的细节,4.2.6.4 已经讲过,这里不再重复。
它的边界很清楚:目标服务只存状态,不负责调度。真正把它推起来的,是目标轮次驱动器。所以有目标不等于会自动跑,这两件事要分开配置。
4.2.7.5 什么时候不要上图
这一节写给急着上架构的读者。
DSH 的工作流(workflow)工具文档说得很直白。只在用户明确要求工作流,或者确实需要大规模多 Agent 编排时使用;一两次委派,用普通子 Agent 就够了。
图不是免费的。每多一个节点,就多一份上下文、多一次模型请求、多一个失败点。图的价值在于并行和路由,不在于显得高级。
判断标准只有一条:分支和依赖能用一句话说清,用循环;说不清,才画图。
4.2.7.6 本小节可以带走的做法
- 用代码表达图,让引擎执行,不要让模型用自然语言临时指挥。
- 节点内部跑小循环,节点之间用条件边做路由。
- 致命错误直接抛出,别让图带着坏状态继续跑。
- 节点少于三个时,先想想是不是一个子 Agent 就够了。
4.2.8 五个范式怎么合体
分开讲容易,合起来才是真实系统。
4.2.8.1 一次请求的完整旅程
用户发来一句话,Prompt 层把系统分区、工作区规范、工具说明装配成一次请求。Context 层在此之前已经算好预算,必要时先做一次剪枝或摘要。
模型开始流式输出,然后决定调用工具。Harness 层校验参数,检查权限,选择沙箱,执行命令,收集输出,再按输出 schema 校验一遍。
工具报错,Loop 层把错误写成结果回灌,模型看到后改参数重试。同一工具、同一参数重复调用到第 3 次,提醒插入。
事情变复杂时,模型写了一段编排脚本,Graph 层例如起三个子 Agent 并行调研,再把结果汇合。
整个过程中,Session 层一直在追加事件。任何一步失败,都能从检查点恢复;任何一次压缩,都不会丢掉原始记录。
五个范式不是五个模块,是五个层次。从外到内是 Graph → Loop → Harness → Context → Prompt:Graph 调度节点,节点里跑 Loop,Loop 的每一步由 Harness 执行工具,Harness 的每次模型请求由 Context 备料、由 Prompt 装配。外层依赖内层,内层不感知外层。
Session 不在这五层里,它是底座。五层都往它上面写事件,它只负责记录与恢复,不参与排序。事件流是 Context 的底稿,也是全局共享的底座;4.2.4 讲 Context 怎么用它,这里讲它为什么不参与分层。上面那段旅程从 Prompt 起步向外走,正好是这条层次链反过来读。
4.2.8.2 DSH 没做的两件事
合体之后,还要看它没合什么。
讲优点容易,讲缺口更有用。
第一,它没有模型质量评测。仓库根目录的 benchmarks 是性能门禁,它不在 packages 里。那一层测的是耗时和内存,不是回答对不对。全仓没有 LLM-as-a-Judge。
第二,它没有分布式调度。没有 Ray,没有多机队列,它是一个单机控制面,多机要靠外部系统拼。
这两个缺口不一定是缺点,它们说明 DSH 把自己定位在运行时,而不是评测平台或调度平台。定位清楚,边界才稳。
4.2.8.3 一张自检清单
读者如果正在设计自己的 Agent,可以用下面七个问题过一遍,括号里是它对应的范式。
- Prompt 是装配出来的,还是一整段硬编码。(Prompt)
- 模型有没有一个明确的提问动作。(Prompt / Harness)
- 任务状态存在会话里,还是存在模型记忆里。(Context)
- 上下文压缩有没有不花钱的第一层。(Context)
- 工具错误是回灌,还是抛出异常。(Loop)
- 沙箱是系统能力,还是 Prompt 约束。(Harness)
- 复杂任务有没有图,图是不是非画不可。(Graph)
七个问题覆盖五个范式,其中 Prompt 与 Context 各两问。但答对五个不等于五个范式都有落点:若两问都落在 Prompt、两问落在 Context、一问落在 Loop,Harness 与 Graph 就没有覆盖。要保证覆盖,按五个范式分组核对,每组至少一问;答上七个,才意味着每一层都想过一遍,才谈得上稳定交付。
五个范式听起来像五个流行词,落到代码里,其实是五件很朴素的事。
让模型问得清楚,记得住,用得上,改得动,协作得起来。
DSH 的价值在于把每一项都做成分层模块,还把没做的部分写进了文档。
这就是一个成熟工程系统该有的样子。能力有边界,边界有文档,关键行为能从代码里核对。
前一节我们看到,OpenClaw 选择把能力内置,把不确定尽量兜住。DSH 选择把能力拆开,把组合权交给使用者。这两条路各自解决了什么、又各自付出了什么,下一节逐项对照。
4.3 两个框架的对照:什么该抄,什么不该抄
如果只数功能清单,容易得出一个印象:DeepSeek Harness(下称 DSH)更完整,OpenClaw 更简陋。
这个印象是错的,因为两个项目解决的根本不是同一个问题,连比较的单位都不一样。
DSH 是编程式框架,它假设使用者要自己写代码、自己组合能力。所以它必须把每一层做成可插拔的模块,否则使用者无处下手。
OpenClaw 是运行时,它假设使用者只想把一句话扔进来,然后拿到结果。所以它必须把不确定的东西全部兜住,把需要业务判断的东西全部推给应用层。
一个是开放式工具箱,一个是封闭式发动机。用零件数去比较它们,等于用工具箱的零件数去评价一台发动机。
比较要分层,不能数件数。这一节按五个维度对照(加一行推论),接着看三件不要照抄的事,最后给出三件可以带走的做法。
4.3.1 五个维度的实际差异
我们先看表,表里的结论都能在 4.1 / 4.2 找到依据,个别格是本书归纳,正文再逐条解释。
| 维度 | OpenClaw | DSH |
|---|---|---|
| 定位 | 运行时,能力内置 | 框架,能力可组合 |
| 范式覆盖 | 4.1 只解剖到执行循环(Loop)层;Prompt、Context、Harness 打成内建 | 五范式齐全,各有落点 |
| 循环模式覆盖 | 完整 7 项、部分 4 项、未实现 9 项 | 4.2 未按二十种模式逐项比对 |
| 扩展方式 | 应用层自己写 | 插件 + 服务接口 |
| 边界诚实度 | 明写「不判断任务做完没有」 | 明写「没有评测、没有分布式调度」 |
| 适合谁读 | 想知道生产环境该兜住什么 | 想自己搭一套 |
表不是评分卡,它只说明两者把复杂度放在了不同位置。读者可以先看最后一行「适合谁读」,再回头读前五行。
定位这一行最容易被误读。DSH 在 packages 下拆了 52 个子目录(58 个条目:52 个目录加 6 个非目录项),插件、会话、沙箱、压缩各成一包,包与包之间靠服务接口连接。OpenClaw 把主循环压在 agent-core-Dp2OAIE9.js 里(2604 行)。压缩提示词、循环检测、工具预算分属不同模块:工具预算走 maxToolCalls(工具形态 / Code Mode 两处计数口径见 4.1.4.6 与 4.1.6.1),循环检测单独在 tool-loop-detection 模块(673 行)。
前者把复杂度摊在目录里,后者把复杂度收在运行时里。两种都是成本:一种付在装配期,一种付在维护期。
摊在目录里的好处是边界清楚,升级一个模块不必动其他包。收在运行时里的好处是路径短,一次调用经过的层数少,延迟和排障成本都低。
这两种结构没有高下,只有代价落在谁身上。
如果团队更怕上线后反复排障,选 DSH;更怕一开始写大量装配代码,选 OpenClaw。
范式覆盖的差异也来自定位。DSH 的 Prompt、Context、Harness、Loop、Graph 五个范式各有落点;代码按功能拆模块,目录不是按五范式切的。OpenClaw 走到 Loop 就停了,Prompt、Context、Harness 没有拆成对外接口,而是直接打成内建能力。
这不是能力缺失,是接口选择:运行时不需要向使用者解释每一层怎么装,它只需要保证装好的东西能跑。
这个选择还有一个副作用:内建能力不容易被替换,使用者遇到不满意的地方,只能绕开或改写源码。
循环模式的分布更值得看。按 4.1.3 的逐项比对,二十种模式里,OpenClaw 完整 7 项、部分 4 项、未实现 9 项。完整落地的七项在记忆、规划、探索、自优化四类里分别落地 2、2、1、2 项,质量提升类完整落地一项没有;未实现的九项里,质量提升类占 4 项,也是占比最大的一类。
这里只借它的分布形状,不用它评优劣。这张分布图说明一件事:它把「让模型更聪明」的循环几乎全部外包,只留下「让模型不崩」的循环。
这个切分与 4.1.5 的三条缺席理由互相印证。这并非巧合,而是同一条边界在不同侧面的投影。
扩展方式和边界诚实度是同一枚硬币的两面。DSH 用插件加服务接口扩展,OpenClaw 让应用层自己写扩展。
这两种扩展方式各有各的重复劳动。应用层自己写,意味着每个业务都要重新实现一套质量环(评估、反馈、重试);插件加接口,意味着平台先替你定好插槽,插槽之外的东西仍然要自己写。
边界诚实度也一样:OpenClaw 在 4.1.7.3 里写得很直白,它提供客观信号,但不设验收门。DSH 在 4.2.8.2 里说得同样清楚:没有评测,没有分布式调度。
两者的说明书都诚实,只是诚实的位置不同:前者交代自己缺什么模块,后者交代自己不做哪种判断。写清缺什么,使用者才不会误以为插件能补上;写清不做什么判断,使用者才不会以为运行时能替业务验收。
对使用者来说,这两种诚实都比「什么都能做」有用,因为它提前告诉你哪里要自己动手。
适合谁读这一行,其实是前五行的推论。想在生产环境少踩坑的人,应该先读 OpenClaw 的兜底设计。想自己搭一套的人,应该先读 DSH 的模块边界。
前面用计数看的是结构,不是高低。所以「落地了几项模式」这种比较没有意义:不宜按同一张表计数,DSH 侧没有按二十种模式逐项统计。本节只比较两者的取舍位置,不比较模式数量。
前者在问「你能装多少」,后者在问「你能兜多少」,两个问题的答案本来就不该一样。
4.3.2 两次相反的取舍,同一条边界
差异看完,再看共识。两者在「让系统别崩」这件事上,做法几乎相反,结论完全一致。
DSH 把沙箱做到操作系统层。Linux 上先用 bwrap(bubblewrap),不可用再退到 Landlock;macOS 用 Seatbelt;Windows 用受限令牌加 ACL。这些都是操作系统级隔离机制,拒绝发生在系统调用层,进程根本拿不到那个能力。
OpenClaw 不碰内核,它把工具预算和循环检测做成硬判定。同名工具、同参数、同结果连续出现,计数就往上走:10、20、30 次分别触发警告、拦截、全局熔断(见 4.1.6.3)。
前者往下沉到内核,后者往上收到工具调用前的拦截层,方向相反,但都在做同一件事:不靠模型自觉。
为什么一边下沉、一边上收?因为两者的部署前提不同。DSH 把自己定位为单机控制面(4.2.8.2),本机内核的隔离能力随手可用。OpenClaw 不假设宿主一定允许创建命名空间(本书判断),只能在自己能控制的地方做硬判定。
所以沙箱是 DSH 的默认能力,熔断是 OpenClaw 的默认能力。两者都在用自己的位置,解决同一个「别失控」的问题。
代价也各自清楚。容器里如果没有创建命名空间的权限,bwrap 探测会失败并退到 Landlock。退到 Landlock 后,bwrap 提供的 PID 与网络命名空间隔离就没有了;只有整条链都不可用,才会真正失去沙箱。工具调用前的拦截看不见语义,只能按重复次数判断。
把上面这些判断收成一句:能用代码保证的,绝不用提示词保证。
第二层共识更隐蔽。两者都没有回答「什么叫做好」。
DSH 没有 LLM-as-a-Judge,仓库根的 benchmarks 只测耗时和内存。OpenClaw 在质量提升类上没有一项完整落地,唯一半落地的是 Score-and-Retry(只打分、不重写);critique 与 self-review 在源码里零命中;debate 属探索搜索类,不在质量提升类里比。理由在 4.1.5 和 4.2.8.2 已经展开,这里只记对照事实:两者都选择不做质量评测(LLM-as-a-Judge 那类打分)。
检索口径:全库 grep judge|critic|self.?review,排除注释与测试,版本 ce7073d。
所以两者真正的共识不是技术选型,而是这条边界:
平台负责「不崩」,应用负责「更好」。
我们把这条边界再收紧一点:平台只判断可计算的失败,应用才判断不可计算的好坏。
举个例子:客服智能体(Agent)的工具调用次数、超时、死循环,平台可以兜住,因为这些判据与业务无关。但「这句话的语气合不合适」,平台无从判断,只能由业务方给出评分标准和样本。
判断一条能力该放在哪一层,只问一句:这个判据换个业务还成立吗。成立,下沉到平台;不成立,留在应用层。
这条线画在哪里?就画在「判据换个业务还成立吗」这一问上。
4.3.3 什么该抄,什么不该抄
对照做完,下面只看具体的事:先说三件不要照抄的,再说三件可以带走的。
三套阈值的来源和适用条件不同,先放在一张表里对照。
| 来源 | 阈值 | 适用条件 | 误杀代价 |
|---|---|---|---|
| OpenClaw(4.1.6.3) | 10 次警告 / 20 次拦截 / 30 次全局熔断 | 运行时按工具调用次数,同参数、同结果 | 正常长任务被中断 |
DSH(4.2.6.3 repeat-tool-reminder) | 第 3 次、第 5 次、第 8 次提醒,不拦截 | 框架侧只提醒,调用方自己停 | 死循环靠调用方发现 |
| 本书建议 | 第 1 次给改错机会,第 2 次终止 | 应用层策略,按单任务重复次数 | 正常重试被误杀 |
三套不是同一量纲:OpenClaw 是运行时硬拦截,DSH 是提醒,本书建议是应用层策略。抄之前先确认自己站在哪一层。
第一,别只抄 OpenClaw 的「没有步数上限」。
OpenClaw 不设步数上限,但默认有三层兜底:目标预算、循环检测、超时。目标预算限制这一次任务还能烧多少 Token,前提是任务设置了目标(goal);未设 goal 时这一层不生效,超预算转入 budget_limited。循环检测的熔断,管的是这一步有没有让状态前进,默认 10、20、30 次三档:警告、拦截、全局熔断。第三层是超时,但它不由运行时强加,4.1.6.5 明说使用方必须自己设。也就是说,默认情况下真正生效的是循环检测;目标预算与超时要使用方自己补齐。
三层各管一个维度:任务成本、步级进展、单次调用时长。缺一层,另外两层之间就会出现空档。
把三层拆开看,你会发现它们并不是三个开关,而是一组互相补位的保护,任何一层单独使用都有缺口。
只抄「不设上限」,等于开一辆拆掉刹车的车。
下面这段代码把差别写出来了(阈值取小值便于复现)。同样的工具,同样的死循环,运行时会在第 3 次无进展时停下;框架侧在第 3 次、第 5 次、第 8 次重复时只提醒、不拦截(见 4.2.6.3),调用方不喊停就一直跑。
python
# runtime_vs_framework.py — Python 3.10+,只用标准库
import hashlib
import json
class Runtime:
"""运行时:预算与无进展熔断都内建。"""
def __init__(self, tool_budget=8, no_progress_limit=3):
self.tool_budget = tool_budget
self.no_progress_limit = no_progress_limit
self.calls = 0
self.history = []
@staticmethod
def _fingerprint(tool, args, result):
raw = json.dumps([tool, args, result], sort_keys=True, ensure_ascii=False)
return hashlib.sha256(raw.encode()).hexdigest()
def call(self, tool, args, fn):
if self.calls >= self.tool_budget:
return "stopped: budget exhausted"
self.calls += 1
result = fn(**args)
fp = self._fingerprint(tool, args, result)
self.history.append(fp)
streak = 0
for old in reversed(self.history):
if old != fp:
break
streak += 1
if streak >= self.no_progress_limit:
return f"stopped: no progress x{streak}"
return result
def read_file(path):
try:
return open(path, encoding="utf-8").read()
except FileNotFoundError:
return "ERROR: file not found"
stuck_plan = [("read_file", {"path": "missing.txt"})] * 10
rt = Runtime(tool_budget=8, no_progress_limit=3)
for name, args in stuck_plan:
out = rt.call(name, args, read_file)
print("runtime:", out)
if out.startswith("stopped:"):
break运行环境为 Python 3.10 及以上,只用标准库。保存为 runtime_vs_framework.py,执行 python3 runtime_vs_framework.py 即可,退出码为 0。
text
runtime: ERROR: file not found
runtime: ERROR: file not found
runtime: stopped: no progress x3差别就在最后一行。同样的场景放在框架侧,不会有这一行。
这里只演示重复结果检测,不演示状态判定:read_file 只能证明结果重复,不能证明状态没变。
真正的护栏不在「允许跑多久」,而在「怎么判断这一步有没有改变世界状态」。
这套硬判定也有盲区。结果哈希只认完全相同的输出;如果每次结果都不一样、但同样无用,这套判定就会漏掉。4.1.6.5 已经列过这个边界。
所以它不是万能的,只是比数步数更接近问题的本质。步数衡量的是工作量,哈希衡量的是状态变化。
这两种尺子都不完美,但后者至少和「有没有往前走」直接相关,前者只和「走了多少步」相关。
第二,别默认抄 DSH 的插件化。
插件化的代价是每扩一次能力,就要多写一层装配代码。注册表、接口、生命周期、依赖顺序,一样都不能少。
它解决的是变更隔离:改一个插件,不必重新读整个系统,这对多人协作很值钱。
但隔离有成本。接口一层层加下去,读代码的人要先穿过若干层装配,才能看到业务本身。
这个成本在团队规模变大时会反过来变成收益,因为接口把变更隔离开,读一处不必读全系统。
所以它的价值在多人长期协作。十个人维护三十个模块,接口就是合同,插件化省下的是沟通成本。一个人写的小系统用不上这套,反而会被装配代码拖慢。
判断标准很朴素:一个人维护、工具不到两位数,先用一个字典注册函数就够了。这是经验条件,不是从两者默认值抄来的。
等到接口开始频繁变更、多人同时改同一块代码,再引入插件层也不迟,重构成本远低于一开始就过度设计。
第三,别抄任何一家的默认值。
DSH 的默认值是 0.8 压缩阈值、0.16 保留比例;OpenClaw 的默认值是 10、20、30 三档(警告、拦截、全局熔断)。换一种负载,这些数字立刻失效。
默认值是结果,不是原因。抄数字,不如抄当初的推导过程。
推导过程通常只有三行:量什么、在什么负载下量、留多少余量。把这三行写进设计文档,比记三个数字有用。
我们建议的替代做法写在下面三条里,读者可以按自己的任务负载重新算一遍。
- 压缩阈值 0.8:依赖窗口大小、输出预留、增长余量;你该测会话在第几轮开始溢出。
- 保留比例 0.16:依赖任务对早期目标的依赖程度;你该测压到多少比例时任务开始丢约束。
- 熔断阈值 10、20、30:依赖正常试错步数、单步成本;你该测重试分布的 P95 落在第几次。
测法不复杂。把最近 100 次真实任务的工具调用序列导出来,按单任务连续重复长度取 P95,数一遍重复次数和恢复位置。样本至少 100 次,余量留 P95×1.2,比抄别人的数可靠得多。
注意:直接沿用 10、20、30,会导致正常任务被误判为死循环、无法继续:单任务重复达到 10 次只收到警告,达到 20 次就被拦截。
三件不要照抄的说完了。反过来,也有三件事可以带走。
第一件,能用代码保证的,不用提示词保证。 判据能硬判定,就不要只给建议。真实系统还要在第一次命中时给模型一次改错机会,第二次才终止,否则正常试错会被误杀。升级策略比阈值更值得抄,因为它决定了系统在「可能错了」和「确定错了」之间怎么区分。
第二件,按「判据换个业务还成立吗」分层。 4.3.2 已经给出这条判据:成立的下沉到平台,不成立的留在应用层。它比任何一张功能对照表都耐用,因为它不依赖具体框架。
第三件,默认值的来源比默认值本身更值得带走。 上面那三条就是模板:每个数字旁边写清它依赖什么、你该测什么,再用自己最近 100 次真实任务重算一遍。
4.3.4 本章留下的判断
回到本章主线。如果只能记一句话,记这句:
范式告诉你系统分几层,模式告诉你每层怎么转,而「哪一层不该由平台做」才是架构师真正的判断。
第 3 章给的是地图,4.1 和 4.2 是两张照片,这一节是把两张照片叠在一起看。地图不会告诉你哪条路正在修,照片能看出路面,但看不出正在施工。
这一章的方法也可以带走。读一个框架时,先找它把哪件事做成了硬约束,再看它把哪件事留给了使用者。前者的数量决定它有多稳,后者的数量决定它有多灵活。读者如果只带走一个动作,可以先把自己的默认值全部标上来源。
照片看完了,还要回到自己的工地。下一章,我们把镜头从源码拉回工程现场,看一个 Agent 应用到底怎么搭起来。