开篇:通用内核的边界怎么定
做通用 Agent 内核,我先定一条边界:循环和协议交给框架,自己只写框架覆盖不到的三层。 这条边界决定了下面所有设计决策的取舍。
具体来说,ReAct 循环与 function-call 协议由 OpenAI Agents SDK(Runner) 承载,多 agent 状态机编排由 LangGraph 承载;我自己写的只有三块:L2 编排层(收尾门控 / 升级判定 / 预算与墙钟 / 上下文管理)、工具运行时与插件层、知识层(世界模型 / 技能 / 全局记忆)与 执行后端(设备 / GUI)。
也就是说,我自己动手写的是"编排 + 工具 + 知识层",agent 循环本身交给框架。能在框架里解决的,绝不自己造轮子。
通用内核要解决的三个问题,也是这条边界的由来:
- 加能力不能污染内核。 往循环里塞视觉、塞点击逻辑,每加一个能力内核就被改一次——所以能力必须外挂成插件。
- 换模型不能改代码。 工具列表、调用格式、prompt 不能和某个模型绑死——所以模型能力要抽成元数据。
- 知识不能一次性。 这次跑通下次从零,同一个坑踩十遍——所以知识要落盘、可复用。
这篇记录三件事:
- 通用内核里我自己写的三层——这是整篇最想讲清楚的部分;
- 架构全景——两层循环、一条知识旁路;
- 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.py | SDK 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.maxInputTokens | config / 设置页 | 300000(>0 启用粘性压缩;0 = 显式关闭) |
compress_threshold | 运行时回退(config 无键) | 0 → 取 0.5 |
hard_ceiling | 运行时回退 | 0 → 取 0.9 |
retain_ratio | config | 0.5 |
worker_history_keep | config | 3(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)——这些东西不聪明,但它们不会骗你。
而"通用"的价值,体现在我自己写的三层上:能力变成插件,模型变成配置,任务长度不再有上限。 知识层我没把它包装成什么亮点——它现在的状态是:记忆轴机制已验证、长期观察中,技能轴以人工为主、自动宏留了口子。这不好看,但这是仓库里真实长出来的样子。