通用 Agent 内核怎么搭:能力即插件、模型即配置

97 阅读17分钟

开篇:通用内核的边界怎么定

做通用 Agent 内核,我先定一条边界:循环和协议交给框架,自己只写框架覆盖不到的三层。 这条边界决定了下面所有设计决策的取舍。

具体来说,ReAct 循环与 function-call 协议由 OpenAI Agents SDK(Runner) 承载,多 agent 状态机编排由 LangGraph 承载;我自己写的只有三块:L2 编排层(收尾门控 / 升级判定 / 预算与墙钟 / 上下文管理)、工具运行时与插件层、知识层(世界模型 / 技能 / 全局记忆)与 执行后端(设备 / GUI)。

也就是说,我自己动手写的是"编排 + 工具 + 知识层",agent 循环本身交给框架。能在框架里解决的,绝不自己造轮子。

通用内核要解决的三个问题,也是这条边界的由来:

  • 加能力不能污染内核。 往循环里塞视觉、塞点击逻辑,每加一个能力内核就被改一次——所以能力必须外挂成插件。
  • 换模型不能改代码。 工具列表、调用格式、prompt 不能和某个模型绑死——所以模型能力要抽成元数据。
  • 知识不能一次性。 这次跑通下次从零,同一个坑踩十遍——所以知识要落盘、可复用。

这篇记录三件事:

  1. 通用内核里我自己写的三层——这是整篇最想讲清楚的部分;
  1. 架构全景——两层循环、一条知识旁路;
  1. 13 个设计决策。

第一部分 · 通用内核里我自己写的三层

先说结论:「通用」不是为了显得高级,是因为它会让三件事产生复利。 每一次加能力、换模型、跑任务,都在给下一次省钱。第四件事(知识层)单独成节,因为它现在的状态需要诚实说明。

1 · 插件化:能力 == 插件(红线)

这是整个内核最核心的一条约束:

加能力 = 加一个外层插件,绝不改内核。

具体到实现,能力来自外层插件层,而且是两类插件完全平级:

插件类型承载什么接入方式
自研 tool基础能力:屏幕观测 / 鼠标键盘 / 视觉 / 文件 IO用 OpenAI Agents SDK 原生 function_tool 包装
外部 MCP外部系统:开源服务、第三方工具纯配置接入,框架原生加载

自研 tool 和开源 MCP 是平级的,都由 LLM 直接调用。 内核不认识它们中的任何一个,只认识"有一批工具可用"这件事。

这跟 MCP 的设计哲学同源:build once as MCP server, any host 可用——一次写好,任何宿主都能用。反过来看内核,就是"core 不认识 X"。

复利在哪:能力数量线性增长,内核复杂度零增长。加第 100 个能力和加第 1 个能力的成本一样,都是写一个插件。自己写循环的话这是指数增长的——第 100 个能力要在已经缠满分支的循环里找位置。

这条红线靠 scripts/review_lint.py 守:内核文件里出现具体 app / 游戏 / 业务的专有 token(如直接读 ocr_text / ui_tree 等感知字段、对具体工具名做 if 分支),CI 直接判违规。

2 · 模型无关:内核认识「能力声明」,不认识模型

自己写循环的话换模型是灾难:工具列表要跟着模型改,prompt 要跟着模型改。

现在把模型能力抽成元数据,动态注入提示词。系统提示是一个动态模板,运行时按两件事自动填充:

于是换一个模型、加一个工具,提示词代码一行都不用改。text_only 的模型被告知"图像和屏幕观测需要依赖工具",text_vision 的模型被告知"可以直接解析图像,也支持工具二次核验"——同一条纪律,两种说法,自动适配。

这套抽象还顺手解决了一个更大的问题:换执行模型(本地 GGUF ↔ 云端 API)也是零代码改动,只改配置。模型端点收口在 model_hub/ 的模型目录(~/.omniagent/models.json),路由与 providers 解耦。

3 · 长任务连续性:把「工作上下文」和「会话连续性」分开

这一条是被任务时长逼出来的。

常见 Agent 的假设是"一次会话 = 一个任务",跑完就 /clear 开下一个。但挂机跑几小时甚至跨天的任务里,这个假设不成立,会撞上三堵墙:

  • 不能靠 /clear 续命——目标全丢;
  • 反复压缩会磨掉初心(JPEG 效应)——一代代压下去,最早那段"我们为什么要做这个"最先没;
  • lost-in-the-middle 更严重——t=0 的全局目标必须活到 t=3h。

解法是把两个概念拆开:

概念性质落在哪
工作上下文有界、可压LLM 窗口,token 占比触发压缩(见 D6)
会话连续性外部、持久世界模型落盘 + 子目标检查点,不进窗口

核心手段是"让大部分状态根本不进窗口" :无状态大脑每次调用只收「世界模型快照 + 当前子目标」,天然不累积历史。压缩的时候不只产窗口内摘要,更要把关键进展写回持久世界模型——窗口里只留指针。外部记忆才是连续性的真靠山,压缩是有损的。

配合子目标分解,把"刷 2 小时副本"拆成"清房间 1 / 清房间 2…",每个子目标给执行单元一个干净的小上下文,只有高层进度回传大脑。单上下文永远小,总任务才能无限长。

诚实插段 · 知识层:留了口子,没做成自动进化

前三个都成立。但知识层我要单独说一句——它没做成自动进化那套。早期有过一套"轨迹蒸馏成记忆+技能、自动晋升"的设计,已经从代码里删了。现在知识层是记忆轴(LLM 提炼 + 检索)加技能轴(人工维护 + 可选自动宏,默认关)。

现状我后面单独拆一篇讲清楚,这里先不展开。


第二部分 · 架构全景

两层循环,职责完全不同

循环载体管什么
外层:编排图LangGraph(graph_runner + orchestration/graph)该不该派发、派给谁、什么时候收尾
内层:块循环OpenAI Agents SDK Runner一次 run 内:推理 → 调工具 → 看结果 → 再推理

内层是常规 Agent 循环;外层是自己的东西——主 agent 决定派不派、派给哪个执行单元槽位,框架负责扇出和 join。

一条旁路:知识回流

它不参与当前任务,只在任务结束后工作。目的只有一个:同一个坑不要踩第二次。

六层职责与代码位置

层文件职责
L2 编排omni_core/local/loop/core.py graph_runner.py sdk_bridge.py编排注入 + 门控 + 收尾 + 意图门
块循环omni_core/brain/sdk_loop.pySDK Runner 分块执行
提示词omni_core/brain/prompt.py动态模板组装(capabilities / tool_catalog)
知识层omni_core/local/(world_model.py scene_executor.py skill_library.py knowledge_inject.py)世界模型 / 场景块 / 技能库 / 注入
执行后端devices/HostBackend(pyautogui)· EmulatorBackend(u2/ADB),已从内核迁出
前端web/Chat / SkillsAndTools / Settings 三页,自研 store
红线守护scripts/review_lint.py内核零场景硬编码检查(R1/R2/R3/R4)

注:旧版单文件 omni_core/local/tool_loop.py 已拆为 omni_core/local/loop/ 下的多个 Mixin(core / graph_runner / sdk_bridge / instructions / parts / emitter / finish),职责更清晰,红线扫描范围不变。


第三部分 · 13 个设计决策

注:设备控制(uiautomator2/ADB vs 纯视觉)属于执行后端层的选择,归 Hachifish 手机端 Agent 篇,本篇聚焦内核。

A. 执行与感知

D1 · 感知工具三角:三件并列,无程序化优先级

背景:三种感知手段各有优劣——UI 层级树(结构准,但有些界面拿不到)、OCR(文字可靠,拿不到语义)、本地 VLM(懂语义,坐标会认错)。

常见做法是降级链:先试 A,失败降级 B,再不行 C。

选择:三件并列成工具 observe / ocr_screenshot / vision_describe,由模型自主选择,无程序化优先级。

理由:降级链本质上是把"什么时候该用哪个"写成了程序判断——那就是场景知识,属于内核污染。而且降级链写死之后,模型看到的是"被选好的"观测结果,它没机会表达"这个层级树在骗我,我要看截图"。代价是每次判断都要花 token 让模型思考,比固定流水线慢一点、贵一点——这是并列带来的开销。

D2 · 视觉通道:默认关闭,本地 VLM 转文本

背景:截图直接回传强模型,效果确实更好,但很贵。

选择:视觉能力由模型元数据声明驱动——text_vision 模型可直看也可调工具,text_only 模型被告知"用视觉工具看";默认不把原图回传大脑,截图先给本地 VLM 理解,只把文本摘要回传。保留升级通道,本地连续搞不定的界面才直传截图。

理由:成本决策。截图的 token 成本远高于文本摘要,而绝大多数步骤不需要大脑看原图。"本地看懂 → 转述"是个划算的压缩,但本地 VLM 转述会丢信息,所以升级通道必须留着。

B. 编排与调度

D3 · 升级判定:大脑不做模型路由,交给可量化条件

背景:什么时候该从本地小模型升级到强模型?直觉方案是"让大脑自己判断"。

选择:不做。升级回流完全靠量化条件触发:

理由:让大脑判断"我该升级了",本身就是一次 LLM 调用,判断质量还不稳定。改成量化条件后,这套逻辑可测试、可复现、可调参——出问题能定位到是哪个阈值不对。代价是阈值有刚性:"一步都没超但明显跑偏"的情况量化条件抓不到,所以全部阈值放 config,默认值先跑通再实测反推。

D4 · 派发可选:分层与否由配置决定

背景:多 agent 派发是核心能力,很容易做成"默认开启多层"。

选择:派发默认开启,但单模型也能跑(主 agent 自派发,并发与上下文隔离本身就有价值)。要分层需两步显式配置:先在模型目录声明槽位,再在 runtime.dispatch.agents 显式列出参与派发的槽。

理由:不让人在还不知道需不需要分层的时候先背上分层的复杂度。能力默认关、需显式开启——这条对自动化系统尤其重要,代价是新用户得多读两段文档才能用上分层的价值。

D5 · 编排兜底:max_rounds + max_parallel 双硬边界

背景:派发机制一旦跑起来,最典型的故障是"派发 → 回收 → 再派发"的无限循环;其次是一次扇出太多子任务打满资源。

选择:max_rounds(默认 3 轮)+ max_parallel(默认 4 个)双兜底,超长计划自动截断。

理由:这是被真实故障教的——任何带循环的编排机制,都必须有一个跟模型无关的硬边界。不能靠"模型应该不会这么做"来保证收敛。 代价是正常长任务可能被截断、需要手动调高,但宁可截断后手动放行,也不要无限循环。

C. 上下文与记忆

这一组是整份设计文档里我花时间最多的部分,也是改动最频繁的——下面 D6/D8/D10 都按当前代码口径重写。

D6 · 压缩按 token 占比触发,不按轮数

选择:照样压,且以 token 占比为主触发,不按轮数:

参数出处缺省
brain.maxInputTokensconfig / 设置页300000(>0 启用粘性压缩;0 = 显式关闭)
compress_threshold运行时回退(config 无键)0 → 取 0.5
hard_ceiling运行时回退0 → 取 0.9
retain_ratioconfig0.5
worker_history_keepconfig3(worker 硬滑窗保留轮数)

阈值 = maxInputTokens × compress_threshold / × hard_ceiling;token 计数当前用启发式近似,正迁移到真实 tokenizer 计数。

理由:纯按轮数触发是错的——worker 吐几十 K 终端日志时,还没到第 N 轮就已经爆窗。主触发必须是 token 占比,而非"窗口够大就不用压"。代价是阈值依赖大脑真实窗口,换模型后窗口变了阈值得跟着改——这是配置维护成本。

D7 · 上下文分层:worker 硬滑窗 vs 大脑质量压缩,不可混用

背景:上下文管理看起来是一个功能,其实要处理两个完全不同的场景。

选择:刻意不让它们共用机制:

层策略原因
子 agent(worker 槽)硬滑动窗口 history_keep: 3,不做摘要本地小模型没有摘要能力,ctx 也塞不下
主 agent(brain)粘性压缩 + token 占比触发 + 硬上限兜底绝不 3 轮硬截断——全局目标和约束会被切掉

理由:混用是很典型的错误。给 worker 上摘要,是小模型做不了的事;给大脑上硬截断,等于每隔几轮失忆一次。worker = 存活裁剪,大脑 = 质量压缩,这是两条红线。代价是两套机制要分别维护调参,比一套统一复杂。

D8 · 摘要形态:八段结构化检查点,不是"回顾式"摘要

背景:压缩时写摘要,最自然的写法是"回顾刚才发生了什么"。

选择:摘要指令统一为八段 SUMMARY_INSTRUCTION:

任务目标 / 已完成动作 / 关键观测与工具结果 / 已生成产物 / 当前状态 / 未决问题 / 下一步计划 / 风险与约束

总长目标 ≤ 原文 40%,且提炼要点而非照搬流水账。

理由:Agent 要的是"接着做",不是"知道刚才干了啥"。而且用户消息原文和目标的原文不参与压缩——压缩只动中间过程。代价是写八段摘要对模型能力有要求,弱模型写出来的交接质量堪忧——所以这事只能交给大脑,worker 不上摘要(见 D7)。

D9 · 长任务连续性:无状态大脑 + 持久世界模型 + 子目标检查点

背景:任务可能连续跑几小时甚至跨天,撞上开篇说的那三堵墙(不能 /clear、JPEG 效应、lost-in-the-middle)。

选择:把大部分状态根本不放回窗口。 三层机制:

机制作用是否进 LLM 窗口
无状态大脑(每次调用重建上下文)只收世界模型快照 + 当前子目标极小
持久外部记忆(world-model 落盘)目标 / 约束 / 已学事实 / 进度,每次重注入仅摘要指针
子目标检查点(checkpoint 落盘)崩溃重启从检查点续不进

理由:外部记忆才是长任务连续性的靠山。压缩时不只产窗口内摘要,更要把关键进展写回世界模型落盘,窗口里只留指针。代价是世界模型的读写、合并、去重成了关键路径上的一环,写坏了比不写更糟——所以这块有 scene_executor 在做去重和精炼。

D10 · 记忆检索:做检索,不做全量注入

背景:记忆系统上了规模,标准答案似乎就是上向量检索;但规模还小时,全量注入看似最省事。

选择:做检索,不堆全量。L1 原子记忆落 SQLite + FTS5 trigram 索引,两库合计 ≥20 条(_INJECT_TRIGGER)才注入,双库检索取 top-5,以 <relevant-memories> 包裹并带"仅作参考,不代表当前任务进程"免责声明。

理由:全量注入在记忆小时看着方便,但会随记忆增长无界膨胀、且把无关事实硬塞进每个任务。检索(哪怕只是字面召回)先把"该不该出现"这关过了。代价是 FTS5 trigram 是字面召回,同义改写查不到已存事实时会漏;扩容路径已预留:0(单角色全局单份,当前)→ 1(per-role 隔离)→ 2(轻量 embedding 检索臂)→ 3(真多 agent),漏召回实测出现再升级,不为还没发生的问题提前引入一层可能出错的机制。

D. 知识与工程

D11 · 技能晋升:N=3 门,但自动供给默认关

背景:自动提炼技能,不设门槛的话,一次偶然成功就被固化。

选择:技能宏 success_count 累计(失败只累加 failure_count),满 3 → active;同名技能合并累计成功次数;升全局仅人工 promote_to_global。

理由:过滤"运气好"。而且必须是跨任务——同任务内重复成功不算。

当前状态是晋升偏慢,且自动宏提取 skill.auto_distill 默认关。原因摆在明处——早期真实试点,注入技能序列 Δsteps=0(简单 UI 任务),自动产出暂时拿不到正向证据。所以现在技能平面以人工维护为主,自动宏提取只作为可选项保留、开关在配置里。

这里要划清否定对象:否定的是「自动蒸馏」这个供给方式,不是「技能」这个平面——平面保留,改为人工编写 + 可选自动宏。等回放执行器在确定性工具链场景跑出 A/B 正向证据,再按预设口径放开,而不是现在就把它当项目的核心能力写进架构。

D12 · 维护进程:触发式,不挂周期性定时器

背景:后台维护(清理轨迹、精炼世界模型、复核技能候选)天然适合做成定时任务。

选择:触发式——每次顶层任务完成后跑一次(flush + 900s 水位),不挂周期性后台定时器。

理由:定时器会带来并发写 world-model / skill 的锁复杂度。为了"及时维护"引入一整套并发控制,在单用户桌面场景里性价比很低。代价是任务不密集时维护滞后,但可以接受——知识沉淀本来就不需要实时。

D13 · CI 策略:只跑红线 lint,不跑测试

背景:scripts/review_lint.py 守着"内核零场景硬编码",实际检查四条:

规则检测内容
R1 屏幕字段泄露内核文件里直接访问 ocr_text / ui_tree / active_window 等感知字段
R2 具体工具名分支内核文件里对具体设备工具名做 if 分支
R3 抽象缺失devices/base.py 里 text_of / verify_done 仍有默认实现体(出现 @abstractmethod 即合规)
R4 记忆注入回流内核里出现尾部每步重发机制的记号(_TailInjectModel / tail_inject*);或在内核非记忆入口读取 L2 场景全文

选择:CI 每次 push / PR 跑 review_lint.py --strict,但刻意不跑 pytest。

还有个刻意的分层:omni_core/**/*.py 强制 R1+R2,而 能力层(omni_core/tools/**)与设备层(devices/**)豁免 R1/R2——它们本来就是具体实现,红线只该管内核。设备层额外强制 R3。

理由:测试依赖 torch / opencv / pyautogui 这些原生包,在 CI 里装齐会把反馈从秒级拖到分钟级;而红线 lint 是纯标准库、秒级返回。把最需要高频执行的检查做得足够轻,它才会真的被执行——一个每次要等五分钟的检查,最后一定会被人用 --no-verify 绕过去。代价是 CI 抓不到功能回归,只能靠本地跑重型测试。

注:旧版只写 R1/R2/R3,当前已新增 R4(对应已删除的 _TailInjectModel 尾部每步重发机制)。


写在最后

回头看这 13 个决策,它们指向同一个判断:

能交给模型的语义判断,交给模型;不能交给模型的,用可量化、可测试的机制兜住。

  • 感知用什么、要不要派发、这是闲聊还是任务 → 模型判断(D1、D4)
  • 什么时候升级、什么时候压缩、什么时候算完成 → 量化条件(D3、D6、D11)

以及一条更朴素的:

机制要诚实。 硬边界(max_rounds)、显式开关(能力默认关)、可测量的门槛(N=3)——这些东西不聪明,但它们不会骗你。

而"通用"的价值,体现在我自己写的三层上:能力变成插件,模型变成配置,任务长度不再有上限。 知识层我没把它包装成什么亮点——它现在的状态是:记忆轴机制已验证、长期观察中,技能轴以人工为主、自动宏留了口子。这不好看,但这是仓库里真实长出来的样子。

项目地址:github.com/momo-null/O…