通用 AI Agent 骨架 spec(领域无关 · v2.1)
历史资料。 本文不再定义通用强 Agent 基线。其固定九块、Harness 优先级和治理流程主张已由 FinBayes Atlas 中对 Codex、Claude Code、OpenClaw 与 Hermes 的当前参考分析替代。
2026-06-11。这份只描述「一个通用 AI Agent 该由哪几块组成」——领域无关、换业务也能用的那层框架。不含任何 FinBayes 业务(业务对照是下一步,这份是量业务的尺子)。 版本史:v0(5块)→ v1(7块+3横切)→ 两个 Fable 5 复审 → v2(9块+5横切+立场收紧)→ v2.1:对照三篇业界参考资料(见 §5)后的增量 —— Skills 升为一等概念、上下文五层、记忆四类、工具 ACI 阶梯、Harness 组织性论点、落地反模式清单。逐条标注
[v2.1]。
0. 核心立场(措辞收紧 · v2.1 补 Harness 论点)
一个 AI Agent = 一个思考循环(感知 → 决策 → 行动 → 反馈,即 reason → 调工具 → 看结果 → 收尾),外加把它喂饱、收发、记住、唤醒、分身、拦住的若干支撑块。复杂行为是「内容(领域知识)插在这一个循环上」涌现的,不另起一套静态预编排的流程引擎。新能力只加在循环外(扩展工具+handler / 调系统提示结构 / 把状态外化到文件或库),绝不把循环体改成一个大状态机。「模型负责推理,外部系统负责状态和边界」。
[v2.1] 组织性论点:Harness 比模型更关键。 决定系统成败的,往往不是认知核多强,而是 Harness——验收基线 / 执行边界 / 反馈信号 / 回退手段——的质量。更贵的模型带来的提升常被高估,而 Harness + 验证质量对成功率影响更大。先建好骨架(Harness),再磨认知核。 反过来做(半年砸认知核、骨架空着)是本末倒置。
[v2] 「一个循环 ≠ 零显式状态」。 该杀的是「第二套认知/规划引擎」,不是「显式任务状态」。配套三条:
- plan / 任务状态是外部数据对象(写文件/库,JSON 优于 Markdown,循环每轮读写),不是 planner 引擎;
- 确定性流程写成代码/脚本,作为一个工具被循环调用;永远不要反过来把循环嵌进流程引擎;
- durable 执行基座(断点/恢复/重试调度)不在禁令内。
[v2.1] 不是所有场景都要完整 Agent 自主权。 业界五种控制模式(提示链 / 路由 / 并行 / 编排器-工作者 / 评估器-优化器)很多场景搭几种就够。Workflow(代码定执行路径)vs Agent(LLM 动态决策)的区别在控制权归谁。强合规/审批/审计流程用 Workflow 形态(确定性、可预估、日志定位),其余用 Agent 形态。
适用边界:单循环立场适用当且仅当——任务路径不可预枚举 / 失败可回退 / 时延容忍。任一不满足的局部,用「确定性 workflow 作为工具挂进循环」。涌现何时不够用的判定:步骤需确定性顺序?需可重放审计?失败需精确补偿?——命中任一,用显式状态/代码,不要塞进提示词。
1. 九块
| # | 块 | 职责 | 机制 / 内容 / 策略 |
|---|---|---|---|
| 1 | 渠道 / 收发消息 | 消息进出、鉴权、封包;渠道差异收敛在 adapter 层,换渠道不改 Agent | 全机制 |
| 2 | 上下文装配 [v2.1 五层] | 把信息按「使用频率 + 稳定性」分层拼成输入(见下) | 机制=装配引擎;内容=装什么;策略点=分层/检索排序/压缩时机/缓存友好 |
| 3 | 工具注册与执行 [v2.1 ACI 阶梯] | 注册 / schema 暴露 / 沙箱执行 / 超时与结果整形 / MCP 适配 / 副作用声明位 / 工具消息隔离(见下) | 机制为主;工具集内容=业务 |
| 4 | 思考循环(发动机) | reason → 分派工具 → 观察 → 收尾;provider 抽象、停止策略执行点 | 引擎=机制。系统不判断完成、不评估质量、不决定下一步——只忠实执行模型的工具调用 |
| 5 | 护栏 / 权限 [v2.1 实化] | 白名单授权(谁能用)+ 工作空间隔离(能在哪用,路径越界报错、execFile 防注入)+ 审计日志(做了什么可追踪)+ 不可逆操作执行前确认 + 审批/HITL 挂点 | 全机制。安全边界先于功能——加任何新功能前就要到位 |
| 6 | 输出投影 | 模型末答 → 用户面输出 | 机制=骨架;格式契约=内容。注意逆流:格式契约会坐进开头 system prompt 污染上游(讲座腔 bug 即此) |
| 7 | 会话 + 记忆 [v2.1 四类记忆] | 见下方四类 | 存取=机制;记什么=内容;写策略=策略点 |
| 8 | 触发 / 调度 | 只产生唤醒事件(cron 按表 / heartbeat 轮询 / 系统事件 / 子代理回报),不长第二个脑子 | 配套:触发负载=与用户消息并列的标准装配输入;去重 key + 单实例租约 + resume-or-abandon;唤醒任务独立会话、产出以消息投递 |
| 9 | 子代理 / 扇出 [v2.1 顺序] | fork 有界子循环并行干活再聚合;子代理独立 messages[],只回摘要,搜索/调试细节留自己上下文 | 配套五件套:深度上限(防无限递归孙 Agent)/ 并发上限 / 预算继承扣减 / 超时取消传播 / 部分失败聚合契约。子代理最小系统提示(只给 Tooling/Workspace/Runtime,不带 Skills/Memory,防权限外泄)。顺序:协议先定 → 隔离先做(worktree)→ 再协作并行 → 最后加交叉验证(多 Agent 幻觉会互相放大,交叉验证打断) |
块 2 上下文五层([v2.1] 防 Context Rot)
按使用频率 + 稳定性分层,每层只放该放的;别把确定性逻辑放进上下文(能用 Hooks/代码/工具约束表达的都交外部系统):
- 常驻层:身份、项目约定、绝对禁止项——短、硬、可执行(也保护 prompt 缓存命中)。
- 按需加载层(Skills):见下方 §1-Skills。
- 运行时注入:当前时间、渠道 ID、用户偏好,每轮按需拼入。
- 记忆层:跨会话经验,需要时才读取,不默认全进 prompt。
- 系统层:Hooks/代码规则处理确定性逻辑,完全不进上下文。
压缩三策略:滑动窗口 / LLM 摘要(branch summarization 保留架构决策)/ 工具结果替换。压缩保留优先级:架构决策>已改文件>验证状态>未决 TODO>工具输出(可删)。不要改动标识符(UUID/hash/PR号)。
[v2.1] Skills:第一等的「程序性记忆 + 按需知识」
Skills = 「怎么做某件事」的说明书/方法论,不是工具、也不是裸上下文。核心:系统提示只留索引,完整内容触发时才注入。
- 描述含 Use when / Don't use when + 反例(实测:无反例准确率 73%→有反例 85%);要像路由条件不是功能介绍;够短(9 tokens 级,不是 45)。
- 每轮先扫描描述、有明确匹配再读对应 SKILL.md、多匹配选最具体、一次只加载一个;有副作用的 Skill 显式补调用时机/速率限制。
- 反模式(直接当审查清单):几百行手册全塞进 Skill 正文(应拆 supporting files)/ 一个 Skill 覆盖多件事 / 有副作用无调用时机限制 / 系统提示当知识库越堆越长。
块 3 工具设计 ACI 阶梯([v2.1])
- 三代演进:API 封装(粒度过细)→ ACI(工具对应 Agent 目标不是底层 API 操作)→ Advanced(Tool Search 动态发现 / Programmatic 代码编排中间结果不进上下文 / Tool Use Examples 示例驱动)。
- 好工具:粒度对应目标、返回只给下一步要用的字段、错误结构化含修正建议、描述说明何时用/何时不用、定义与实现绑定。
- 工具消息隔离:框架内部事件(压缩发生、通知、跳过)记入会话历史但不进 LLM——分 AgentMessage(应用层任意字段)vs Message(LLM 只收 user/assistant/tool_result),调用前过滤。
块 7 四类记忆([v2.1] 按要解决的问题分,不按存储介质)
- 工作记忆=上下文窗口(messages[]),会话结束清空,token 有限主动管理。
- 程序性记忆=Skills,怎么做某事,按需加载不常驻。
- 情景记忆=JSONL 会话历史,发生了什么,磁盘持久、可跨会话检索。
- 语义记忆=MEMORY.md,Agent 主动写入的稳定事实,启动时注入。
- 任务态(
[v2]干到哪了,生命周期=任务、压缩豁免)是工作记忆里被显式外化的部分。 - 记忆是基础设施不是事后补;整合触发(token 超阈值如 50%)+ 失败回退(原始消息写 archive 保留,避免整合失败丢上下文);大多数规模 Markdown+关键词搜索够用,几千条以上再上向量。
- 写并发契约:单 writer 队列、读容忍陈旧;子代理默认无长期记忆写权限。
2. 五个横切质量维度(贯穿所有块)
| 维度 | 该有的样子 |
|---|---|
| A. 预算与停止策略 | 迭代/token 预算 + 停滞检测(对 pollable 工具豁免)+ 强制收束:用手头信息作答并显式声明缺失了什么(不逼编)+「末答落最后一条 assistant 消息」。预算是任务树属性(子代理从父扣减)+ per-trigger/全局熔断。[v2.1] 兼顾 prompt 缓存:常驻层短而稳定→前缀命中→边际成本降。 |
| B. 并发 / 会话隔离 | 同会话串行(队列/mutex,否则并发写历史+compact 竞态)、跨会话并行;定时触发撞运行中会话的排队/抢占规则。[v2.1] 慢 I/O 放后台线程,通知队列下轮注入,别把整个 loop 改成复杂 async runtime。 |
| C. 可观测性 + 溯源 | 事件流(tool_start/tool_end/turn_end)一次发布多路消费(日志/UI/在线评测/人工队列),主循环不为下游改代码。Trace 记:完整 prompt+messages[]+每次工具调用入参出参+推理链+末答+token/延迟。可重放 + 跨子代理因果链。两层:人工抽样标注校准 LLM 自动评估。 |
| D. 错误处理 / 韧性 | 三层分治:provider 抖动→引擎内重试 / provider fallback 自动切换;工具失败→结构化错误回喂模型换路;致命→中止落 trace。 |
| E. 持久化 / 可恢复 | 任务进度写盘、断点续跑(TaskState JSON:completedSteps/currentStep/remainingSteps);任务超半小时,崩溃恢复是必选项。长任务跨 session:Initializer 把任务变成文件状态,Coding Agent 循环可重入。 |
3. 总原则:机制 / 内容 / 策略点
划块三类:机制(领域无关,换业务不改)/ 内容(领域知识,换业务全改)/ 策略点(骨架定钩子签名+默认值,内容可覆写:压缩豁免、检索排序、子代理协调原语)。
元规则:实现介质 ≠ 归属,判据是「换业务要不要改」——哪怕长成一段提示词。
[v2.1] 约束要编码化不要文档化:能写进类型/Linter/CI/Hook/工具校验的约束才可执行;「约束靠期望(规则躺文档里 Agent 选择性遵守)不靠机制」是反模式。这与「决议别当黑话直接进代码、要落成可执行检查」同向。
4. 落地反模式清单([v2.1] 量 FinBayes 时直接当审查表)
| 反模式 | 问题 | 怎么修 |
|---|---|---|
| 系统提示当知识库 | 越来越长,关键规则被忽略 | 约定留系统提示,领域知识移到 Skills 按需加载 |
| 工具数量失控 | 频繁选错工具 | 合并重叠工具,明确命名空间 |
| 缺少验证机制 | Agent 说完成了但没法验证 | 每类任务绑定可执行验收标准 |
| 多 Agent 无边界 | 状态漂移、归因困难 | 明确角色权限、worktree 隔离、设 maxTurns |
| 记忆不整合 | 长对话第 20 轮后质量下降 | 监控 token 占用,超阈值自动整合 |
| 没有评测 | 改一处不知是否回归 | 每个真实失败案例立刻转测试用例(20-50 个即可启动) |
| 过早引入多 Agent | 协调开销>并行收益 | 先建任务图、验证单 Agent 上限再扩展 |
| 约束靠期望不靠机制 | 规则在文档里被选择性遵守 | 期望 → 工具验证/Linter/Hook |
5. 复审 + 参考资料对照留痕(audit trail)
- 两位 Fable 5 reviewer 一致:9 块无错块、单循环立场是对的赌注。致命四项(护栏/任务状态/崩溃恢复/强制收束改向)已落 v2。
- 三篇业界参考资料(§5.1)对照结果:几乎逐条独立佐证 V2 + red-team——单循环、状态外化、安全先于功能、同会话串行否则记忆竞态、provider fallback、事件流可观测、冷启动评测。增量已折入 v2.1:Skills 升一等(并定位为讲座腔 bug 的架构级根因——金融方法论该是懒加载 Skill 而非常驻字段矩阵)、上下文五层、记忆四类、工具 ACI 阶梯、Harness 组织性论点、反模式清单。
- 关键发现:第二篇《你不知道的 Agent》描述的 OpenClaw 五层架构(Gateway/Channel/Pi Agent/工具集/上下文+记忆 + MessageBus + SOUL.md/MEMORY.md/Skills)正是 FinBayes/martin-FinClaw 的祖架构。故下一步量 FinBayes 的尺子 = 本 spec + 这份同血脉的实战文档。
5.1 参考资料
- cnblogs/tansm《Agent 架构演进:Model-Tool Loop》——六层(Loop/Skills/Tools-MCP/Memory/Middleware/Graph)+「模型弱时框架替其思考,模型强时框架给其边界」。
- 知乎 Tw93《你不知道的 Agent:原理、架构与工程实践》——OpenClaw 五层 + 控制流/上下文工程/工具/记忆/多 Agent/评测/追踪/安全全栈。(本仓 ShareDocs PDF)
- 知乎 Song《Harness Engineering(二):Agent Loop》——循环底层原理:LLM 无状态、ReAct、模型是唯一决策者、系统是手脚不是大脑、三设计点(退出条件/反馈来源/历史膨胀)。(本仓 ShareDocs PDF)
Replaced-by: https://labs-fintecai-gov.topquant.org/projects/finbayes/atlas/