跳到主要内容

汇总地图

这一页管什么: 把 survey/ 里 65 篇摘录汇总成一张能拿去做设计的表。 这是工作稿,给作者和 agent 用;给人读的是 lessons/。

前提已满足: 覆盖账本 386 源逐篇判过,relevant 65 个全部有摘录,pending 归零。

坐标轴​

开题时列了四个决定。读完 65 篇之后,实际是六根轴——多出来的两根(轴 5、轴 6)不是细节, 是各家给出相反答案的地方。

轴在决定什么常见取值有锚的源
1 这一轮喂什么几段东西按什么顺序摆、长了怎么砍顺序写死 / 插槽分类 · 全量贴回 / 只留最近 k / 摘要 / 落盘留取件号 / 逼它收尾17 + 25
2 怎么认出它要调工具走哪条通道把「我要调 X」传回来厂商原生 / 自定义标签 / 代码围栏 / 让它写代码 / 结构化输出模拟 / 训进权重 / 不让它选(打分)30
3 怎么执行、结果怎么回填能不能并发、用什么身份写回、回全量还是回变化串行 / 五种并发判据 · 工具角色 / 伪装用户 / 自定义角色 · 全量 / 增量 · 裸回 / 带防伪边界33
4 什么时候停谁判定「干完了」、有哪几道硬闸不再要工具 / 特殊完成工具 / 答案标签 / 外部裁判签字 · 轮数 / 墙钟 / 窗口 三闸50
5 跑偏了怎么办错误进不进历史写进历史让它改 / 抹掉这一轮重来 / 边生成边打断 / 就地修 / 熔断31
6 循环和状态在哪一层谁拥有「转」这个动作、状态存在哪循环自持 / 上层持有循环无状态 / 状态写进消息 / 服务端持有 / 核心里干脆没有循环39

并发没有单列成轴——16 个源讲并发时讲的都是「结果按什么顺序、以什么形态回来」, 和回填是同一个决定,并进轴 3。

轴 1:这一轮喂什么​

1A 顺序怎么排(被缓存绑死的那一半)​

做法代价证据
段落顺序写死:稳定的在前、变的在后,稳定段末尾打缓存标记加一类新内容要决定排在哪;排错不报错,只是账单变贵(依据:本库摘录 · aider)
硬编码七段装配顺序,提醒永远最后一条;自定义提示不进系统消息而做成用户消息同上(依据:本库摘录 · onyx)
收敛成四个插槽(系统 / 首条用户之前 / 末条用户之后 / 每条用户之上),按「位置 → 后果」选选错插槽不报错,只让缓存变差或信息过期(依据:本库摘录 · lobehub)
切成三段:永不改动的前缀 + 只追加的历史 + 永不进请求的便签,前缀命中约 98%便签这一层要额外维护(依据:本库摘录 · whale)
三层拼一次就冻住整场会话,连时间戳都只精确到天会话中途学到的东西这一场用不上(依据:本库摘录 · hermes-agent)
每轮从磁盘重读重建——模型改了自己的设定下一句就生效前缀每轮都变,缓存全废(依据:本库摘录 · cowagent)

位置为什么重要,有两份独立证据:

1B 长了怎么砍​

做法代价证据
四道防线按代价递增:单结果治理 → 微压缩(不花模型钱) → 全量摘要 → 硬截断阈值全是经验值(依据:本库摘录 · dexter)
六级处置,最便宜那道在工具内部(工具自己先截)同上(依据:本库摘录 · hermes-agent)
分级降级:剥二进制 → 剪旧调用 → 压工具输出 → 调模型摘要同上(依据:本库摘录 · browseros)
不改原始历史,只做投影——窗口侧四道防线,存盘侧另治要维护两套视图(依据:本库摘录 · deepagents)
窗口当内存、暂存文件当磁盘:压缩是从磁盘重组一份精简视图喂进内存要配一条取回路径,否则预览就是纯损失(依据:本库摘录 · dexter)
大结果留在框架里,只把取件号喂给模型模型要知道怎么取回(依据:本库摘录 · griptape)
有损压缩配一张带 hash 的取货单,模型想要就把原文换回来取货单本身占地方(依据:本库摘录 · headroom)
超阈值不截历史,改写最后一条逼它用现有证据立刻交卷答案不完整,但完整成句(依据:本库摘录 · tongyi-deepresearch)
两个布尔开关(对用户可见 / 对模型可见)——「历史里有」不等于「模型看得到」所有产生消息的地方都要记得设(依据:本库摘录 · goose)

阴性格: 直接删历史消息被判成架构级错误——老消息躺在厂商缓存里读只要 0.1 倍钱, 删一条会让它后面所有缓存作废、按 1.25 倍重写(依据:本库摘录 · headroom)。

轴 2:怎么认出它要调工具​

通道怎么做代价证据
厂商原生结构化字段直接读绑一家的格式;不是所有模型都支持多数源
自定义标签四种文本标签,<tool_call> 里放参数要自己设停止词、自己防它编造结果(依据:本库摘录 · tongyi-deepresearch)
代码围栏每个工具认领一个围栏标签,「模型最会写的是代码块」工具没有参数结构,没法校验(依据:本库摘录 · agenticseek)
让它写代码一步的行动是一整段代码,一步内能连调多个工具需要沙箱;复杂度挪进了环境(依据:本库摘录 · smolagents)
补丁文本不用工具调用,在回复里夹一段约定格式的补丁要处理分隔符冲突、缩进、解析报错(依据:本库摘录 · aider)
结构化输出模拟厂商不支持强制调工具时,把可选工具编译成一个格式约束逼出合法调用只在支持结构化输出的厂商上可用(依据:本库摘录 · beeai-framework)
文本协议降级原生路径在运行时报「不支持」就当场切回文本 ReAct,不让整次执行失败两条路都要维护(依据:本库摘录 · crewai)
方言层双向编解码编进 / 解出纯文本流,上层完全看不出区别十一套方言要跟着模型更新(依据:本库摘录 · oh-my-pi)
整副外壳伪装系统提示 + 工具格式 + 走哪个协议,三样一起塑成模型最熟悉的样子十五副外壳要维护(依据:本库摘录 · open-interpreter)
训进权重五个控制标签是加进词表的真 token,提示里没有工具说明换基座就得重训(依据:本库摘录 · deepanalyze)
不让它选并发拿每个工具自带的判定说明去问模型「这个工具适不适合」,打分取高工具数 × 一次模型调用(依据:本库摘录 · nlweb)

底层事实: 工具调用不是新机制,是「微调过的模型 + 接口层的语法糖」——工具定义最后还是 变成系统消息里的一段文字,要占词元预算(依据:本库摘录 · prompt-engineering-for-llms)。

兜底: 模型不走标准通道时三层兜底(流式剥离 → 事后从文本里挖 → 整轮只允许兜底一次) (依据:本库摘录 · onyx)。

轴 3:怎么执行、结果怎么回填​

3A 一批调用能不能并发 —— 五种判据​

判据怎么判证据
按动作类型硬分写死哪类可并行(依据:本库摘录 · openai-agents-js)
按读写集合自动推各自读写哪些状态键 → 分层拓扑排序(依据:本库摘录 · haystack)
工具自己声明只读声明不准调度就不准(依据:本库摘录 · nanobot)
连续只读凑一批遇到写就断批(依据:本库摘录 · dexter)
资源访问冲突模型专门判定「两把访问算不算冲突」,并加一条不变量:发和收都按原顺序(依据:本库摘录 · kimi-code)

一条别家没明说的:并发执行不等于乱序回填。

3B 结果用什么身份写回​

身份理由证据
专门的工具结果角色 + 调用 id 配对主流;id 是配对的钥匙(依据:本库摘录 · dong-shou-zuo-ai-agent)
伪装成用户消息不需要专门角色,任何最简陋的对话接口都能跑(依据:本库摘录 · agenticseek)
同上拆解文档明确标注这是取舍(依据:本库摘录 · tongyi-deepresearch)
自定义角色和五个标签配套训练出来的,换模型会渲染错(依据:本库摘录 · deepanalyze)

3C 回全量还是回变化​

做法代价证据
只回两次快照的行级差异,动作工具自动附带这份差异模型手上没有全貌;差异是有状态的(依据:本库摘录 · browseros)
执行函数只返回规范结构,再由三个纯函数分别投影给模型/界面/程序要维护三套投影(依据:本库摘录 · deepseek-harness)
五步流水线:查表 → 校验入参 → 执行 → 校验出参 → 投影返回—(依据:本库摘录 · mcp-typescript-sdk)

3D 外来内容要不要围起来​

要,而且提示层不够: 所有把外来文本喂回模型的工具走同一个信任边界,用带每次随机口令 的标记围起来——页面预测不到口令,就伪造不出闭合标记(依据:本库摘录 · browseros)。

协议侧的对应说法: 工具输出与被引用的文本默认「无权威」,里面的指令只能当信息看、 不能当命令执行(依据:本库摘录 · openai-model-spec)。

轴 4:什么时候停​

4A 谁判定「干完了」​

判据代价证据
这轮没要任何工具、也没有积压的用户输入模型可能没干完就停(见轴 5)(依据:本库摘录 · codex)
登记一个「特殊工具」,执行它的副作用就是把状态改成完成模型可能忘了调(依据:本库摘录 · openmanus)
不硬编码工具名,看工具的一个属性同上(依据:本库摘录 · cline)
忘了调就替它调:纯文本被兜底转成一次收工调用掩盖「模型为什么没调」这个真问题(依据:本库摘录 · beeai-framework)
环境在输出里认出一个哨兵字符串——完成不由模型自称要设计一个不会被误触的哨兵(依据:本库摘录 · mini-swe-agent)
真去执行、拿执行结果当裁判,失败原因变成下一轮输入只适用于可重复、无副作用的动作(依据:本库摘录 · db-gpt)
让另一个模型看着逐条证据签字,签字文件不存在就不准结束每次收工多一次模型调用(依据:本库摘录 · webwright)
抽成一个只看「已经跑过哪些步」的纯函数谓词,任一为真即停—(依据:本库摘录 · vercel-ai-sdk)

一条底线:不能只信厂商给的「结束原因」——有些厂商在消息里明明有工具调用时也回「已停止」, 所以还要自己数一遍未完成的工具(依据:本库摘录 · opencode)。

4B 硬闸​

轮数上限(26 源提到)、墙钟上限、窗口上限。三者判据不同:

4C 停止原因必须能说出名字​

做法证据
十三种出口,只有一种算正常;初值是「未知」,谁没覆盖就暴露出来(依据:本库摘录 · hermes-agent)
一轮一定带一个「为什么停了」的枚举收尾,五种取值各有明确语义(依据:本库摘录 · acp-agent-client-protocol)
因让步而停时状态记为「成功」而非「暂停」——它是被设计地主动停的(依据:本库摘录 · cherry-studio)
停在半路时不发结束事件,前端据此知道要留着会话等结果(依据:本库摘录 · agentscope)

阴性格: 把「步数耗尽」也标成完成——它自己把这个缺陷诚实写了出来 (依据:本库摘录 · fara)。

4D 反面:什么时候「不准停」​

轴 5:跑偏了怎么办​

这一轴的核心分歧:错误进不进历史。

做法错误去哪代价证据
工具报错和参数非法都不抛异常,一律变成消息喂回模型让它自己改进历史历史会堆一串失败版本(依据:本库摘录 · cline)
五关流水线「几乎不抛异常」——模型犯的任何错都变成一段文字告诉它错在哪进历史同上(依据:本库摘录 · semantic-kernel)
明确区分「工具业务失败」与「协议级问题」:前者包成带错误标记的正常结果,后者才抛进历史—(依据:本库摘录 · mcp-typescript-sdk)
所有失败收敛成同一个「反思消息」字段,最多三轮进历史失败原因被抹平(依据:本库摘录 · aider)
失败原因原样变成下一轮输入,而且失败本身也写进记忆进历史—(依据:本库摘录 · db-gpt)
四把尺子量完这一轮,亮红灯就把刚加的那条消息撤掉当没发生过不进历史这一轮的推理一起丢了(依据:本库摘录 · mirothinker)
边吐字边查规则,一犯规就中止、注入提醒、从这一轮起点重来不进历史打断得越晚越浪费,越早越易误判(依据:本库摘录 · oh-my-pi)
就地修:参数别名改名、补必填、从系统提示反解工具名不进历史只能修「信息全但拼错了」的(依据:本库摘录 · mirothinker)
模型幻觉出不存在的工具被当成一等状态,给了五种恢复动作视动作而定—(依据:本库摘录 · rig)
工具不存在时不报错也不停,回一段「你点的不存在,可用的是这些」当观察进历史—(依据:本库摘录 · dong-shou-zuo-ai-agent)
同参同工具分级熔断—阈值是经验值(依据:本库摘录 · cowagent)
复读检测两级(归一化后一致 / 二元组相似度≥0.85),抓到先注入恢复指令三次进历史阈值换语言要重调(依据:本库摘录 · kun)
工具出错后不只回滚副作用,还把历史里那条「成功」改写成「已回滚」改写历史违反「只追加」(依据:本库摘录 · langchain4j)

判据(我的判断,无锚): 两条路不冲突,按失败的性质分—— 信息型失败(命令报错、字段不存在)写进历史,模型据此改正; 格式型失败(写错格式、拒答、原地复读)抹掉重来,写进历史只会让它学坏。 如果错,会错在: 如果模型的格式错误是因为提示里有矛盾指令,那抹掉重来会无限重复同一个错—— 这时错误必须进历史,让它看见「你上次这么写不行」。

所有补救机制都要有自己的次数上限——连续回滚上限 5、压缩失败 3 次不再试、 兜底整轮只一次、反思最多三轮。四份材料独立撞上同一条。

轴 6:循环和状态在哪一层​

做法状态在哪换机器接着跑?证据
循环无状态,每轮由外层新建一个外层否(依据:本库摘录 · cline)
带上限的 while + 只增不改的消息列表 + 一个状态字段,全部压进 196 行循环自持否(依据:本库摘录 · openmanus)
消息列表只增不改就是全部状态,约 100 行循环自持否(依据:本库摘录 · mini-swe-agent)
循环刻意不拥有会话、传输、权限界面、压缩执行,全靠回调借用上层否(依据:本库摘录 · kimi-code)
决策函数只读状态,返回三选一;人工确认/外部执行/中断全成可存盘状态写进消息里是(依据:本库摘录 · agentscope)
大脑只返回可序列化的指令,引擎只负责执行一份可持久化的状态是,而且能换执行面(依据:本库摘录 · lobehub)
完全不做 IO、可整个序列化存盘的状态机拥有全部决策状态机内是(依据:本库摘录 · rig)
一次运行的状态能整个存成字符串再还原,人点同意后跨进程续跑可序列化快照是(依据:本库摘录 · openai-agents-js)
历史在服务端,客户端只发增量;关掉终端再开,待批准的调用还在服务端是,换机器也行(依据:本库摘录 · letta-code)
核心里根本没有转圈的循环,转圈职责交给入口层入口层否(依据:本库摘录 · qwen-code)
只留一条只能追加的事件日志当唯一事实,消息数组是从它投影出来的事件日志是(依据:本库摘录 · deepseek-harness)
双层循环:内层管「还有工具要跑」,外层管「本该停了但有人排队追问」分层否(依据:本库摘录 · pi)
超步模型:一批一批跑、每批末尾一道同步栅栏,版本号同时解决「跑谁/到哪/崩了从哪续」版本号 + 检查点是(依据:本库摘录 · langgraph)

三层嵌套的命名(回合 / 步 / 批次),各对应一个函数边界 (依据:本库摘录 · kimi-code);另一份把它分成「往返 / 回合 / 交互」三级 (依据:本库摘录 · qwen-code)。

跨家共识(融会贯通的部分,可以直接抄)​

出身完全不同的几家撞在同一个答案上——这八条不用再想。

#共识撞上的源
1调用与结果必须配对,历史里不能留「有调用没结果」的孤儿cowagent / agentscope / goose / qwen-code / nanobot / langchain4j / mcp-typescript-sdk
2每轮都变的东西不能进前缀,只能追加在末尾kun / agentscope / nanobot / hermes-agent / aider / whale
3工具报错不抛异常,变成一段话喂回模型cline / semantic-kernel / mcp-typescript-sdk / dong-shou-zuo-ai-agent / mini-swe-agent
4压缩是一条按代价排序的阶梯,先便宜后贵dexter / hermes-agent / browseros / cherry-studio / deepagents
5大结果落盘,只把取件号喂给模型dexter / griptape / headroom / hermes-agent / qwen-code / agentscope
6停止原因必须能说出名字,异常停不能混进正常停hermes-agent / acp-agent-client-protocol / kun / agentscope / cherry-studio(fara 是反例)
7格式要顺着模型的训练分布,不是顺着我们的审美aider / oh-my-pi / open-interpreter / prompt-engineering-for-llms
8工具多了要按需披露,不要一次全塞cherry-studio / qwen-code / whale / agent-skills-spec / hermes-agent / shen-ru-li-jie-ai-agent

共识 3 的深化版:给模型的错误信息应该是一条修改指令,不是一句故障描述 (依据:本库摘录 · agenticseek)。

分歧(我们真要选的地方)​

#分歧一边另一边判据
1系统提示冻不冻拼一次冻住整场(hermes-agent)每轮从磁盘重建(cowagent)你更在乎「模型立刻看到最新状态」还是「账单」
2错误进不进历史写进去让它改(cline / db-gpt / aider)抹掉重来(mirothinker / oh-my-pi)失败是信息型还是格式型
3结果用什么身份回填专门的工具角色(主流)伪装用户(agenticseek / tongyi)接口支不支持专门角色
4循环在哪一层自持(openmanus / mini-swe-agent)上层持 / 服务端持 / 干脆没有(kimi-code / letta-code / qwen-code)要不要「换机器接着跑」
5谁判定干完了模型说了算(codex / vercel-ai-sdk)外部裁判说了算(db-gpt / webwright / mini-swe-agent)有没有可自动判定的成功信号
6并发按什么判五种判据各有拥趸—工具能不能可靠声明自己碰什么

空白格(没人做过,创新入口)​

#空白谁点到了但没做
1由「它没把握」触发的停下来问人 —— 见下面的澄清(依据:本库摘录 · langgraph-blueprint)
2第二个模型全程旁观、随时插话纠偏只有一家(依据:本库摘录 · oh-my-pi)
3最终答案里每个数的溯源——「这个数是哪一步产生的」病症被点出(工具没背书的数进了答案),没人做检查(依据:本库摘录 · hands-on-large-language-models)
4「它以为自己做完了」的自动检测被命名、被定义成可数指标,但没有自动检出办法(依据:本库摘录 · ai-engineering)

澄清空白格 1:人机协同到处都是,空的是它的触发条件​

第一版这一格写成「没人做主动问人」,措辞不准——人机协同(HITL)在 65 篇里至少八家做了。 空的不是「问不问人」,是「谁来决定该问」。

各家的触发条件,逐条核过:

出处触发条件谁定的
(依据:本库摘录 · goose)五个检查器按注册顺序跑,裁决三选一我们注册的规则
(依据:本库摘录 · letta-code)工具被标了「需要批准」工具的属性
(依据:本库摘录 · dexter)写操作过权限闸门;跑命令用默认拒绝的三步判定按操作类型
(依据:本库摘录 · langgraph)静态断点:在指定节点前后停我们预先指定的位置
(依据:本库摘录 · openai-agents-js)先查这个调用批没批过,没批就不执行查表
(依据:本库摘录 · cherry-studio)审批门工具永不被折叠工具的属性
(依据:本库摘录 · agentscope)权限判定要求确认,状态转「在问」权限规则

共同点:判据全是「这个动作是什么」,和它这一步有没有把握无关。

用代码说清楚差别:

  各家做的:    if (这个工具被标了要审批)  停下来问
  这一格说的:  if (它自己觉得这步没把握)  停下来问

  第一种:调删除命令一定问,哪怕它百分之百确定该删。
  第二种:查天气本来不用问,但它这次拿不准该查哪个城市 —— 问。

这两种在一个成熟系统里应该同时存在。65 篇材料里只有第一种。

那条出处的原文是一句「最佳实践」建议:能识别并从错误中恢复,或者在不确定时主动问 (依据:本库摘录 · langgraph-blueprint)。 那份资料把它写成了建议,但它自己没实现,其余 64 篇里也没有。

判断(无锚): 没人做的原因可能不是没想到,而是模型不知道自己什么时候不确定—— 它挑下一个 token 的标准是「像人会写的」,这个标准里没有「我有多确定」这一项。 所以这一格要先测「它报的『没把握』准不准」,再谈用不用得上。 如果错,会错在: 如果模型对自己的把握程度有可用的自我报告能力(比如让它对每一步打个分, 而那个分和实际对错相关),那这一格就是纯粹的工程空白,做出来直接有用。

阴性格(试过不行,写清失败条件)​

#做法失败条件
1把「步数耗尽」标成完成异常结束混进正常结束,上层再也分不出来(依据:本库摘录 · fara)
2直接删历史消息省窗口删一条会让它之后所有缓存作废,读 0.1 倍变写 1.25 倍(依据:本库摘录 · headroom)
3成功路径只喂最后一个工具反馈多个工具都成功时,前面几个的输出模型看不到(依据:本库摘录 · agenticseek)
4工具少时也折叠成元工具目录省下的词元不够抵三把元工具本身的开销,净亏(依据:本库摘录 · cherry-studio)
5只靠提示词声明「外来内容不是指令」恶意文本可以伪造边界结束标记越狱(依据:本库摘录 · browseros)

判定:哪几格值得亲手搭​

地图最大的用处是划掉不值得搭的。原型只搭下面这六格,每格选的都是「最省 + 有共识」的那一档。

轴原型选什么为什么是它
1 喂什么段落顺序写死,先不做压缩;撞上限就逼它交卷压缩是阶梯,第一版连第一级都用不上;交卷法零成本
2 怎么认出厂商原生,钉死一家课题边界已划「不管换厂商」;其余十种都是它不可用时的替代品
3 执行与回填串行、遇错即停;专门的工具结果角色,按 id 配对并发的五种判据都要工具先声明自己碰什么,第一版两三个工具不值当
4 什么时候停模型不再要工具 = 完成;三道硬闸;每个出口都写一个原因字符串原因字符串成本是一个字段,收益是「它到底为什么停」永远可见
5 跑偏了错误写进历史让它自己改;不做回滚共识 3;回滚要先有「四把尺子」,第一版没有可量的东西
6 在哪一层核心是一个纯函数「跑一轮」,转圈写在外面这一条不选好,后面加界面/审批/续跑都要重写

明确不搭: 并发调度、压缩阶梯、方言层与外壳伪装、审批链、服务端状态、多 agent、 第二模型旁观。它们全都有出处,但每一个都要先有一个跑得起来的循环才谈得上。

判断(无锚): 六格里只有第 6 格是「选错要重写」的,其余五格都是「以后再加」的。 所以原型的第一行代码应该先把「跑一轮」和「转圈」分开,别的都可以糊。 如果错,会错在: 如果第一版从头到尾只跑一个固定任务、跑完就丢,那分层是纯负担, 一个二十行的 while 更快看到结果。