AI Agent 工程 on 卓琪的开发笔记

Codex 为什么不把所有工具都交给模型？讲透 tool_search、BM25 与模型替换

Sat, 08 Aug 2026 00:00:00 +0000

把模型想成只有一张小桌子的工程师。工具说明书有几百本时，全部摊在桌上既贵又难找；更好的办法是先给它一本目录，需要什么再取出最相关的几本。本文就讲清 Codex 怎样做这件事、为什么使用 BM25 排序，以及怎样把同一办法搬到 Python、Go 和其他模型上。

本文固定在 2026-08-07 发布的稳定版 rust-v0.147.0，源码 commit 为 be6e8eac；另复查了 2026-08-09 的 main commit 646f7c0a。先给两个不会误导人的结论：

模型第一次能看到哪些工具，不是一张永远不变的名单。 它会随模型、接入方式、运行环境和功能开关变化。
tool_search 和背后的 BM25 排序代码都已经写好，普通直连方式可以使用；但这个稳定版给 GPT-5.6 采用的 exec 集中调用方式漏掉了搜索入口。 这不是功能没开发，而是一条接线没有接通。

这篇文章写给谁
#

默认读者只需要知道“大模型可以调用外部工具”。不要求会 Rust，也不要求读过 Codex 源码。 如果你主要写 Python 或 TypeScript，后面的 Rust 连写可以直接理解成“筛选列表 → 改造每一项 → 收集结果”。

有两条阅读路线：

只想理解做法：读小桌子问题、机场图、工具搜索过程、跨语言复用和模型替换；
想跟进源码：继续读伪代码、Rust 对照、完整查询实例和源码索引。

先只记住四句大白话
#

先把 Rust 函数名和 OpenAI 的专有叫法全部擦掉，一个会使用工具的模型仍逃不开四件事：

读完 Codex 源码后，我认为最值得企业 Agent 借鉴的是这 5 个设计

Sun, 02 Aug 2026 00:00:00 +0000

可以把 Codex 想成一支小型施工队：模型像会判断下一步的现场负责人，Agent Harness 则是围绕他的派工台、门禁、档案柜和进度看板。源码真正展示的，不只是“负责人会下命令”，而是整套系统如何让工作安全开工、暂停后接着做，并让用户始终知道事情进行到了哪里。

很多 Agent 教程只有这样一个循环：

while True:
    response = model(messages, tools)
    if response.tool_calls:
        messages += execute(response.tool_calls)
    else:
        return response.text

它没有错，只是省略了真正困难的部分：几张工单能否同时开工？测试十分钟不退出时由谁保管现场？每次查看进度是否都要打扰用户？一句“还在检查”会不会被误认为已经交付？用户不知道操作手册叫什么时，系统能否主动找到？用户明确说“不要停”后，任务怎样跨越多轮处理仍不丢失？

这次我没有再从界面现象反推实现，而是阅读了官方 openai/codex 仓库在 commit bb5054f 的 Rust 源码。下文的组件名、状态分支和数值都能在对应源码中找到；产品未来仍可能演进，但这些设计已经足够回答一个问题：企业 Agent Harness 应该替模型承担什么？

先看懂：Agent 的一轮 Turn 到底做了什么
#

把一次完整用餐看成一个 Thread：它是整件事情的总账。前菜、主菜和甜点可以是不同 Turn；每个 Turn 都是从“用户提出这一轮要求”到“这一轮结果真正交付”的完整周期。

一轮 Turn 像一次点单到上菜：中间可以反复派出多张工具工单，也可以完全不调用工具。

顺着图走，一轮通常包含六件事：

OpenClaw 记忆实战：从「向量搜索挂了也能用」到用 NVIDIA 免费 API 补全最后一块拼图

Sat, 20 Jun 2026 00:00:00 +0000

OpenClaw 记忆系统的向量检索默认不可用——但 BM25 文本搜索兜底让系统照常运转了两周。当你发现「不配 embedding 也能跑」，到底要不要修？怎么用 NVIDIA 免费 API 零成本补上？

OpenClaw 实战：一行路径省掉 84% 的工具调用——Cron Job 排障实录

Sat, 20 Jun 2026 00:00:00 +0000

OpenClaw 的 daily-ai-news 定时任务连续超时。根因不是模型不够强——是 SKILL.md 里少写了一行绝对路径，导致 Agent 每次花 15 次 exec 搜索工具位置。消息数 165→54，exec 调用 44→7，一行路径比任何算法调优都管用。

Claude 工具调用范式转移：Programmatic Tool Calling 与 Dynamic Filter 深度解读

Sat, 13 Jun 2026 00:00:00 +0000

真正的变化不是“又多了两个工具功能”，而是 Agent 开始把多步工具编排移入代码执行环境，并只把压缩后的结果带回模型上下文。

背景：Agent 工具调用的成本困境
#

在传统 Agent 工具调用模型中，每调用一个工具都需要完成一次"模型推理 → 工具执行 → 结果返回 → 模型再推理"的完整回合。这个看似自然的循环，在工具调用变多时会暴露出三个致命问题：

上下文污染：每个工具的结果都被原封不动地注入上下文窗口。查 20 个员工的报销记录，2000+ 条费用明细全部进入 context，即使你只需要知道"哪 3 个人超预算了"。
推理开销：每个工具调用都需要一次完整的模型推理。5 个工具调用 = 5 次推理 pass，每次几百毫秒到几秒不等。
噪声导致准确率下降：当上下文窗口塞满了中间结果，模型不得不在大量噪声中寻找信号。Context Rot 研究表明，LLM 在复杂任务上的性能会随上下文增长而下降 50-70%。

正如 Bruno 在 Claude Code Architecture Guide 中所指出的：“Outer Loop（模型外的一切：上下文管理、工具调用、验证、记忆巩固）开始比模型推理本身更决定系统质量。”

Anthropic 在 2025 年 11 月到 2026 年 2 月间陆续推出的一系列工具使用增强功能，本质上都是为了解决 Outer Loop 的效率问题。其中 Programmatic Tool Calling (PTC) 和 Dynamic Filtering 是最具范式转移意义的两项。

OpenClaw 生产踩坑：当最先进的记忆系统遇到最静默的失败

Wed, 27 May 2026 00:00:00 +0000

从部署到排障，记录 OpenClaw 从启动失败、飞书消息静默吞回复到 production 稳定的全链路实战经验——compaction safeguard、五层排查法、model-harness-fit 与记忆系统对比。

生产环境 Agent 实践：为什么我们从 Celery 迁移到 Temporal

Sat, 16 May 2026 00:00:00 +0000

2026 年 4 月，我们把 seo-project 的任务队列从 Celery 全面迁移到了 Temporal。删除的依赖只有一个（celery），新增的核心代码有 11 个文件（src/infrastructure/temporal/），容器从 api/worker/beat 变成了 api/temporal_worker_blue/green（蓝绿部署）。

这件事做完后，最常被问到的问题是：为什么不用 Celery？已经能跑的东西换它干什么？

这篇文章就是答案。它不来自文档对比，来自生产环境跑 Agent 流水线时逐条撞上的坑。

这张图先划清两个工具的问题层级。Celery 负责把任务交给 Worker；Temporal 额外保存事件历史，让多阶段流程能够从故障点恢复。迁移的核心不是换一个更快的队列，而是获得可重放的状态机。

Celery 与 Temporal：前者擅长分发独立异步任务；后者用事件历史、检查点与重放语义支撑长时多阶段流程。C 阶段失败时，关键差异是整批重试还是从 C 恢复。

Celery 能做的事，为什么在 Agent 场景里开始不够用
#

先说清楚一个基本判断：Celery 是好工具。对于"发封邮件、生成一张缩略图、推送一条通知"这类标准异步任务，它完全够用，工业界跑了十几年。

但我们跑的负载和这不一样：

一个 Run 包含 N 条 longtail
每条 longtail 跑 A → B → C → D 四个 Agent 阶段
每个阶段调一次或多次 AI API
总耗时任意一条都在 60-180 秒区间
每一步的中间结果需要持久化
任何一步失败需要知道"停在哪、为什么、能不能只重试这一步"

这是有状态的、长时的、多阶段的业务流程。任务队列和业务流程引擎之间的分界线，就在这里。

什么时候用 RAG，什么时候用 LLM Wiki，什么时候用纯文本记忆——一个 Agent 记忆选型框架

Mon, 11 May 2026 00:00:00 +0000

做 Agent 系统的人迟早会撞上这个选择题：用户的数据往哪放，下次对话怎么记住？

目前工业界有三条主流路线——RAG（向量检索）、LLM Wiki（结构化知识注入）、纯文本上下文记忆（CLAUDE.md / Cursor Rules 模式）。三条路各有拥趸，但选错的代价很大：RAG 做轻了是噪音生成器，纯文本做重了是 token 焚化炉。

这篇给出一个可以直接用的决策框架。

先看三条路线的系统边界。它们的核心差异不是数据库品牌，而是检索发生在什么时候、多少内容进入 Context、写入和维护由谁负责。

三种记忆路线：RAG 擅长从大规模异构资料中按需召回；LLM Wiki 强调结构与审计；纯文本适合少量高价值、需要确定性注入的规则。没有一条路线在所有维度都占优。

三种方案一句话定义
#

方案	核心机制	代表产品/模式
RAG	向量检索 → top-k 片段 → 拼入 prompt	Mem0, Zep, LangChain RAG, Cursor Codebase Index
LLM Wiki	结构化文档 → 全量或按需注入 system prompt	Claude Projects, GPTs Knowledge, Notion AI
纯文本上下文	Markdown/文本文件 → 直接拼入 system prompt	CLAUDE.md, Cursor Rules, AGENTS.md, Devin Knowledge

关键区别不在于"存哪里"，而在于检索方式和注入时机。