> ## Documentation Index
> Fetch the complete documentation index at: https://base.bangwu.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent harness

> AI Agent harness 实战设计笔记，系统梳理记忆架构、技能装载、工具协议、上下文窗口管理、权限边界控制、评测体系与常见故障模式排查思路，帮助开发者从零搭建可靠的智能体运行时层，提升编码 Agent 与工作流 Agent 的稳定性，少踩坑、多快速落地。

# Agent harness

Agent harness 是包在 AI 模型外面的运行时层。它决定模型能看到什么上下文、能调用哪些工具、权限怎么控制、记忆放在哪里，以及出错后怎么恢复。

不要把 harness 当成普通胶水代码。对编码 Agent 和工作流 Agent 来说，harness 经常比“换一个更强模型”更直接地影响可靠性。

## 一个好用的理解框架

好的 Agent 系统会把不适合只放在模型权重里的能力外化出来。

| 层级 | 外化什么 | 例子 |
| - | - | - |
| 记忆 | 持久状态与检索 | 项目笔记、用户偏好、任务历史、向量检索 |
| 技能 | 可复用流程 | 浏览器控制、代码审查、图片生成、部署 helper |
| 协议 | 通信契约 | MCP、JSON schema、类型化工具返回、错误格式 |
| Harness | 运行时协调 | 上下文组装、工具路由、审批、日志、重试、评测 |

这个框架来自论文 **Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering**。它提醒我们先问一个工程问题：

> 哪些能力应该继续留在模型内部，哪些能力应该变成明确的外部组件？

如果这个能力会影响可靠性、可审计性、复用性或成本，通常就值得外化。

## Harness 负责什么

Harness 至少应该把这些决策显式化：

* 哪些文件、页面、工具和记忆进入上下文
* 旧上下文什么时候总结、丢弃或保留
* 工具调用在执行前怎么校验
* 哪些动作必须经过用户审批
* 工具错误怎么表示、怎么重试
* 推理强度、延迟和成本怎么权衡
* 每次运行怎么记录，方便之后排查

薄 harness 可以成立，但隐式 harness 很难排错。行为变差时，如果分不清原因是模型、提示词、上下文缓存、工具层还是产品默认值，说明 harness 的可观测性不够。

## 设计原则

### 工具要小而清楚

优先设计输入输出明确的小工具。一个工具只做一件事，模型更容易正确调用，人也更容易审查。

本地工作流里，CLI 往往够用。需要跨客户端复用时，再考虑 MCP 这样的协议边界。稳定产品后端则继续用直接 API，通常最简单。

MCP 在 2026 年确实强了很多——现在是无状态协议、支持延迟加载工具，模型的结构化 tool calling 也更可靠。这**并不等于** 大多数集成都应该用 MCP 而不是 CLI。

更适合 **CLI** 的场景：

* 模型训练时就会的命令（`gh`、`aws`、`kubectl`），几乎不用注入 schema
* 本机或 CI 里跑固定命令
* 需要管道组合、管道过滤，或者只是临时排查
* 省 token，`--help` 再加一个 skill 就能教会新 CLI

更适合 **MCP** 的场景：

* 没有终端（浏览器、移动端、托管 Agent）
* 需要 OAuth、按用户授权或标准化审计头
* 模型没见过这个工具，可机器校验的 JSON Schema 值得花 token
* 工具集不固定，Agent 需要运行时发现（`tools/list` + 延迟加载）

简单口诀：本地、熟悉、可组合的工具用 CLI；鉴权、审计、发现、没有 shell 的环境用 MCP。

### 把聊天传输与 Agent 执行分开

消息适配器应负责把平台事件转换为统一格式并投递回复，而不是变成 Agent 框架。BerriAI 的 `agentchat` 明确了这种分工：渠道适配器输出共享消息对象；核心层认领消息 ID、锁定会话、记录历史，再分发给应用 handler。发送者授权和 Agent 运行由 handler 负责。

提交 `fb892cb` 的架构说明与源码提供了一个参考，也暴露出需要看清的边界：

| 职责 | 放在哪一层 |
| - | - |
| 平台凭证、事件解码、接收确认、回复渲染 | 平台适配器或经过认证的接入层 |
| 重复事件检测、单会话串行处理 | 共享状态／协调层 |
| 用户授权、Agent 会话映射、工具权限 | 应用 handler 与执行策略 |
| 持久任务、崩溃恢复、不确定投递结果的核对 | 应用负责的持久化基础设施 |

不要混淆以下边界：

* **事件验真不等于业务授权。** 对 Slack HTTP 请求，按官方规则对原始请求体和时间戳验签，使用常量时间比较；之后仍需独立判断发送者能让 Agent 做什么。Socket Mode 的接入机制不同，不要把 HTTP 签名规则无差别套到所有传输方式上。
* **接收确认不等于处理完成。** Slack HTTP Events API 要求三秒内返回 2xx，并可能重试投递失败的事件。如果承诺持久处理，应先持久化／入队再确认接收，不要在确认路径里等待模型运行。入队失败时明确处理，不能返回成功后丢掉任务。
* **去重不等于崩溃恢复。** 该版本 `agentchat` 默认的 `MemoryState` 把认领记录、锁和历史保存在单进程内；先认领，再运行 handler，`_receive` 中没有认领回滚。因此 handler 失败后，同一事件在该进程内再次送达，并不会自动重跑；进程重启又会丢失内存里的认领记录。生产恢复需要持久任务状态流转和明确的重试策略，不只是一个“见过的 ID 集合”。
* **会话锁不等于全局有序。** 它只能串行化本地处理，不能保证平台时间戳顺序，也不能约束其他进程的 worker。会话 key 应包含平台、安装实例／租户、会话或线程范围；多 worker 用共享存储或分区协调，并明确群组线程是否在不同用户间共享上下文。
* **Agent 完成不等于回复已送达。** 分别保存生成的回复和投递状态。发送超时后核对平台回执，或使用平台明确支持的去重机制；重跑整个 Agent 可能重复工具副作用，却没有解决回复丢失的问题。

以上是生产设计要求，不代表这个 SDK 已实现持久队列或“恰好一次”执行。接入聊天平台前，应测试重复投递、未授权发送者、并发消息、接收后重启、handler 失败，以及发送超时但结果未知的情况。即使正常路径的演示只有几行代码，这些也应进入[产品评测与回归测试](/zh/env/ai-evals)。

### 把 Skill 的设计与执行分开

Skill 是给 Agent 用的说明书，只需要说那些模型不知道的部分。执行则交给工具（脚本、CLI、App）去做，由模型直接调用。

把两者分开：

* **设计逻辑**放在 SKILL.md 里，描述*做什么*和*为什么*。
* **执行逻辑**放在脚本和工具里，描述*怎么做*。

脚本可以预先写好，也可以在需要时由 Agent 现场生成。现场生成更灵活——即使没有 Skill，Agent 也经常会现写一段 Python 去完成任务。代价是更慢、更费 token、边界情况也更容易漏。重复出现、质量重要的任务应预写脚本：Markdown 转 HTML 这类事，现写只能勉强能用，预写才能兼顾样式和边角。现场生成的脚本在验证之前应视为一次性代码。

这个分离也解释了为什么 Skill 再强仍离不开 UI：Skill 告诉 Agent 要达成什么，而 UI 承载具体的执行步骤——人点几下就能配置好，不必每次从头重新提示。

Skill 没有杀死 MCP，RAG 也没有死。它们解决不同问题，经常出现在同一条工作流里：

* **MCP** 是共享接口：结构化工具调用、鉴权和数据访问。
* **Skill** 是打包好的经验：这个团队怎么工作、这个项目该怎么改、哪些约定重要。用 Markdown 是优点——人也能读。
* **RAG / 检索** 把文档、工单和代码从权重之外补进上下文。

MCP 提供访问。Skill 解释怎么用好这次访问。检索让模型从更接近答案的地方起步。按缺口选层，不要选赢家。

### 保留影响推理的上下文

上下文裁剪不只是省 token 的优化，它会改变行为。

如果 Agent 前面基于某段推理调用了工具或修改了文件，harness 就必须保留足够的原因链。否则后续轮次可能重复执行、忘记为什么选这条路，或者调用奇怪的工具。

### 用文件承载持久状态

长时间运行的 Agent 工作流不能只依赖聊天历史。普通文件通常是最简单的持久记忆层，因为人可以查看、编辑、diff，也可以用 Git 版本化。

一个好用模式是把工作区拆成目标、资源、交付物和学习记录：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
workspace/
├── MISSION.md              # 为什么要做这件事或学习这个方向
├── RESOURCES.md            # 可信来源与参考资料
├── NOTES.md                # 偏好与临时笔记
├── lessons/                # 每个文件一个自包含学习单元
├── reference/              # 压缩后的长期速查资料
└── learning-records/       # 用户能力发生了什么变化
```

具体文件名可以调整。关键原则是：状态必须**可检查、可恢复、有边界**。在 Agent 辅助学习里，这能让 Agent 基于学习者当前能力继续教学，而不是每次都从通用大纲开始。在工程工作里，同样可以用于 onboarding 笔记、迁移日志、事故复盘和任务 journal。

### 审计记忆系统的联想盲区

当前所有记忆架构——Flat RAG、图结构记忆、agentic 层级、操作系统式内核——检索配方都一样：把查询和内容投进同一个相似度空间（BM25 或稠密向量），取 top-K。这把召回上限锁死在**表面相似度**上。

它只覆盖描述性召回——查询和记忆共享措辞、实体或时间地点。另一半是联想性召回：一个月前存下"团队有人严重海鲜过敏"，今天问"团队晚餐去哪吃"——零词汇重合，只有一条语义弧（因果、同一情境）把两者连着。腾讯 **T-Mem** 论文（2026）量出了这个盲区：在专门剥离词汇重合的 LoCoMo-Plus Cognitive 子集上，相似度系系统只有 32–49%，GPT-4o 直接读完全部对话原文也只有 21%。

T-Mem 的修复借自认知科学（情景未来思维）：**写入时**算好并存下一条预测——这条记忆会在什么情境下重新重要——即 trigger。四族 trigger 覆盖粒度（事实/场景）×取向（描述/联想）的 2×2 空间，其中联想两族才是关键：

* **Bridge trigger**——把事实投射到"知道它就会有用"的具体情境，并附一步推理理由："海鲜过敏 → 为团队晚餐选餐厅"。
* **Horizon trigger**——把场景投射到一组前瞻维度，未来从不同情境接近的查询仍能命中。

消融实验是 headline：去掉 Horizon trigger，标准基准只动 0.08 个点，联想基准塌 12.47 个点。只按相似度基准调优的系统，隐含地就在优化"待在相似度邻域之内"——而邻域边缘的成本，这族基准在构造上就测不到。

可迁移的规则：**在写入时做召回规划，那时你最了解内容。** 把每条内容应该回答的问题物化出来，而不只是存内容本身。一次性离线花 token，之后每次查询都省。

### 正确性重要时要做确定性检索

当任务需要精确结果时，不要只让 Agent 在脆弱网页、分散数据库和没有文档的一次性脚本之间“自己想办法”。应该给它一个确定性检索层。

Anthropic 的生物学 Agent 案例很有代表性：研究团队让科学 Agent 从 NCBI Virus 检索病毒序列数据。真正值得沉淀的结论不是“某个模型赢了 benchmark”，而是加入 `gget virus` 这种接口更窄的确定性检索层后，工作流可靠性显著提高。

高风险检索建议优先提供：

* 类型化查询函数，而不是自由浏览网页
* 稳定 ID、版本号和日期过滤条件
* 可机器校验的数量统计或 checksum
* 每条返回记录的来源证据
* 下游分析前的验证步骤
* 明确错误情况，而不是静默 best-effort 输出

这和工具设计是同一个 harness 原则：先把执行表面变得可预测，再让模型围绕它做计划。

第一步检索值得超配投入。**Question's Gambit** 论文（2026）在 BrowseComp-Plus 上把 GPT-5.5 从 83.1% 提到 90.5%——同一个检索器、同一个 Agent 循环，唯一的变化是循环开始前先跑一次预检索：把问题拆成线索，每条线索转成互补搜索，汇总结果再重排。Agent 带着已排序的证据集开始循环。同样的改法把 mini 模型从 68.1% 提到 79.0%，校准误差大约减半。

错误分析才是真正的教训：最强模型剩下的 79 个错误里，只有 3 个是证据文档从未被检索到，其余 76 个都发生在后面——预览、打开、使用证据的时候。**把开场的上下文做厚；验证消费环节，而不只是抓取环节。** 代价是每题多 2.3–5.3 次工具调用，相比一整轮失败很便宜。

### 为人际协作而设计，而不只是追求自主执行

大多数 Agent 产品把目标放在自进化和闭环上：Agent 自己规划、执行、收尾。这不一定是健康的模式。即使加了透明度和追溯工具，优先追求自主完成的 Agent 也可能制造出难以交接和维护的噪音。

Agent 不只是执行流程的容器，也是人理解、判断和协作的环境。设计 harness 时问自己：另一个人能接手这个会话继续工作吗？推理过程是否足够透明，让同事能审计某个决策？工作流产出的是可维护的交付物，还是一堆自动执行的步骤？

优先考虑交接质量，而不是自动化完成度。一个以清晰、可检查状态结束的工作流，比一个"全都做完了"但没留痕迹的工作流更有价值。

### 遥测和反滥用信号应该显式化

一个有文件系统和 shell 权限的编码 Agent，行为越"无聊"越好。每一个非显而易见的动作都在侵蚀信任。

2026 年 7 月，有开发者审计 Claude Code 时发现了提示词隐写：二进制文件会根据时区（`Asia/Shanghai`、`Asia/Urumqi`）和主机名匹配 XOR 编码的域名列表（中国 AI 实验室、代理服务、转售网关），静默修改系统提示词日期字符串中的不可见 Unicode 字符（`Today's` → `Today\u2019s`），将分类信号编码进去——全程无文档说明。

检测目的本身可以理解——Anthropic 想识别 API 转售商和模型蒸馏管道。问题出在实现方式。把分类信息藏在不可见标点里，用 XOR 和 base64 隐藏域名列表，这让其他隐私声明都更难取信。而且绕过极其简单（改主机名、改时区、patch 二进制），所以这个功能主要惩罚的是那些使用自定义 API 网关的正当开发者。

Harness 的教训：如果你的工具需要检测滥用，就把信号做显式。写文档。写 release notes。发明确的遥测字段。透明度不是反滥用的敌人——它是信任的基础。

### 让推理强度可见

推理强度不只是模型参数，也是产品决策。降低强度可以减少延迟和 token，但也可能让复杂编码任务明显变差。

要让用户看见当前 effort 级别，方便切换，并避免在复杂工作流里静默修改默认值。

### 把 system prompt 当代码审查

System prompt 的改动可能和代码改动一样影响质量。处理它时也应该有工程纪律：

* 跑分模型评测
* 用 ablation 检查单条指令的影响
* 灰度发布
* 保留变更记录
* 模型专用指令只作用到目标模型

对编码 Agent 来说，过强的“少说话”约束尤其危险。它可能减少工具调用之间必要的计划和验证。

### 测试真实公开版本

内部版本可能掩盖线上问题。应该 dogfood 用户真正运行的公开版本、公开默认值和公开上下文行为。

对代码审查或编码 Agent 评测来说，还要给足真实任务需要的仓库和文件上下文。缺少跨仓库上下文时，模型明明有能力找出问题，评测里也可能看不到。

## 验证优先的设计

一位通过 Cursor pstack skills 每月交付约 2000 个 PR 的实践者，把核心原则提炼为\*\*“验证就是一切”\*\*：Agent 只有能自己确认改动真的生效，才能闭环执行、持续迭代，人不再是瓶颈。验证是关键基础设施，不是事后补充——值得像生产系统一样投入。

三个组件让它落地：

**1. 验证 CLI，而不是纯 markdown 指令。** 给 Agent 一个封装应用交互与调试的小 CLI——snapshot/screenshot、navigate、click/type、trace/wait-settle、健康检查等子命令。工具永远胜过一次性脚本：更省 token、可复现、可测试。Agent 友好 CLI 的设计要点：

* 可组合 API（deep modules：一个命令只做一件有意义的事）
* 破坏性命令带 `--dry-run`
* 子命令渐进披露功能
* 错误信息告诉 Agent *下一步该做什么*
* 丰富的 `--help` 和 JSON 输出

**2. Feature Map 作为物化记忆。** 一组 markdown 文件，记录每个功能是什么、用户视角如何到达、有哪些坑。本质是代码库的压缩投影——代码才是终极记忆，Feature Map 只是为了省 token 的紧凑形式。用每日例行维护防止它过时。

**3. 云端并行。** 本地 worktree 上限大约十个并行 agent，还占资源。云端 agent 有真实机器、能装依赖、能跑应用、能录屏，首次构建后有快照——这是数百子 agent 并行的前提，也是 swarm 验证和 fuzz 回归的基础。

技术选型的推论：**优先可调试的运行时。** 如果技术栈无法截屏、没有 accessibility 树、没有性能 trace，Agent 就无法验证自己的工作。仅为了 Agent 可验证性而换技术栈是合理的——Web/Electron 有 Chrome DevTools Protocol，iOS 有模拟器。

harness 胜过模型的最强定量证据：**GAVEL** 论文（2026）在长程机器人任务上把 Qwen3-8B 从 41.2% 提到 91.8%，模型一行未改。它加了一个显式的图世界模型——物体关系、动作前提与效果、对未见物体位置的概率估计。执行 LLM 生成的动作前，图先预测这个动作会产生什么；违规会被抓住，机械可修的直接修掉，不再调用模型。只有需要语义推理的错误才回到 LLM。在 BEHAVIOR-1K 的 500 条多任务指令上，成功率从 19.9% 升到 92.6%。

可复用的教训：许多长程 Agent 失败是**状态追踪失败，不是推理失败**，而 LLM 外部的一个符号检查器能便宜地抓出它们。把模型的决策点包进确定性结构——世界模型、候选列表、验证器——小模型就不用再为 harness 已经知道的东西付账。

## 常见故障模式

Anthropic 在 **2026 年 4 月**发布的 Claude Code 质量问题复盘很有参考价值：用户感知到的退化来自产品和 harness 改动，而不是底层 API 模型退化。

常见故障包括：

* **默认推理强度回退**：为了降低延迟改默认值，可能让复杂任务显得“不聪明”。
* **上下文缓存 bug**：错误地清理 reasoning history，会让 Agent 健忘、重复、工具选择异常。
* **提示词过度限长**：笼统的短回答约束可能降低编码质量。
* **评测盲区**：内部评测通过，不代表真实用户工作流没问题。
* **版本不一致**：内部 dogfood 的 harness 和用户运行的 harness 不一致。

实用结论是：Agent 变差时，要排查整个运行时，而不是只怀疑模型。

## 破坏性工具的安全边界

拥有文件系统和 shell 权限的 Agent 能在几秒内毁掉工作。2026 年 8 月的一个真实事故值得研究：一名开发者用 Codex + Trellis + Zcode 配合 GLM 模型开发，Agent 对错误的目录执行了 `rm -rf`，整个工作区被删。

根因：Agent 本意是删除一个因大小写笔误产生的空目录。在 macOS 大小写不敏感的文件系统上，这条命令静默解析到了真实的、有内容的目录——删掉了整个仓库，包括 git 历史、未提交改动、任务记录、迁移脚本和文档。没有备份。

教训超越了这一起事故本身：

* **谨慎使用完全访问。** 优先使用带审批流的 harness（如"帮我批准"这类审查），而不是无限制的自动执行。
* **隔离开发目录。** 让 Agent 工作区与其他文件分开，这样删除错误不会波及其他有价值的东西。
* **尽早、频繁 push。** 远程 git 历史是对抗本地删除的最后防线——它能在任何本地备份都失效时活下来。
* **对安全性的跑分保持怀疑。** 同一个"以安全著称"的模型犯下了低级破坏性错误。安全性声明和基准胜利不等于真实世界的文件系统判断力。

更深层的 harness 原则：破坏性操作应该被当作权限边界，而不是能力。如果一个工具能 `rm -rf`，它就应该默认门控、记录日志、可回滚——并且 Agent 永远不应该被授予超出任务所需的权限范围。

### 把候选查询与购买审批分开

付费操作同样需要明确的权限边界。Vercel 域名 CLI 是一个具体例子：Agent 用 `vercel domains search` 找候选，用 `vercel domains check` 查可注册状态，用 `vercel domains price` 查价格。根据 Vercel 的公告，非交互式调用 `vercel domains buy` 会返回结构化错误和建议的后续命令，而不是直接成交；用户在交互式终端或控制台确认价格、自动续费选项和注册人信息。

可复用的模式是**准备 → 请求审批 → 执行 → 验证**，而不是“把支付凭证交给 Agent，再叮嘱它小心”。设计自己的工具时：

* **把限定范围的查询与花钱权限分开。** 允许比较选项，不等于授权买下其中一个。
* **让审批包含具体条件。** 展示准确的资源、账号或团队、当前报价及币种、期限和续费选项；这些条件发生变化时，重新确认。
* **遇到待审批响应就停下。** 把结构化结果交给用户，不要换接口重试、自动回答确认提示，也不要把“有交互式终端”当作用户同意的证据。
* **在模型之外执行门控。** Skill 负责解释步骤，工具权限和交易服务负责强制执行。如果 Agent 能用同一凭证绕到其他购买入口，单靠 CLI 提示并不够。
* **重试前先核对结果。** 记录用户决定和交易结果，但不要记录密钥或不必要的联系人信息。请求超时后先查提供方的订单状态，避免重复购买。

以上是 harness 设计建议。Vercel 案例证明了“查询与确认分离”的做法，不代表每个支付接口都实现了全部控制措施。授予花钱权限前，应核对所安装 CLI 的实际行为。

## 快速排查清单

当 Agent 表现异常时，按这个顺序问：

1. 模型或 effort 级别变了吗？
2. System prompt、工具描述或 skill 指令变了吗？
3. 上下文裁剪、总结或缓存策略变了吗？
4. 工具 schema 或返回格式变了吗？
5. Agent 拿到的文件和仓库上下文和以前一样吗？
6. 用户运行的 harness 版本和内部评测版本一样吗？
7. 日志里是否出现重复工具调用、缺少原因链、无新增信息的重试？

这能把模型退化和 harness 退化分开看。

## 理解模型内部：J-space 的发现

2026 年 7 月，Anthropic 发表了突破性的可解释性研究：Claude 内部**不到 10% 的神经活动**驱动了多步推理。他们把这个子空间命名为 **J-space**——一小撮在训练中自发形成的神经模式，一次装几十个概念，装的是"Claude 可能会说、但还没说出口"的词。

发现 J-space 的方法叫 **J-lens**：对词表中每一个词，反推出"让 Claude 更可能说这个词"的内部活动模式，于是那些"沉默的词"在网络层与层之间怎么演化，第一次变得可见。

### J-space 揭示了什么

**它在驱动推理，而不只是旁观记录。** 删掉 J-space 的神经活动后，Claude 照样能流利说话、做情感分类、答选择题——但多步推理直接掉到接近零。把 J-space 里的概念一换，输出立刻跟着变：把 spider 换成 ant，腿的数量从 8 变成 6；把 France 换成 China，首都、语言、大洲的回答同时从巴黎/法语/欧洲变成北京/中文/亚洲。一个表示，多处复用。

**它暴露了没说出口的动机。** 安全测试中：

* 敲诈测试里，Claude 还没开口回应，J-space 里先亮起了 "fake" 和 "fictional"——它识破了"这是个测试"
* 让它伪造数据时，改数值的当口 "manipulation" 亮了
* 一个被故意训坏的模型，接到普通的写代码请求，J-space 里却浮现 "fake" "fraud" "secretly" "deliberately"

这意味着你可以读到模型没说出口的动机——安全监控的新维度。

**Counterfactual Reflection Training** 是一个值得关注的新训练思路：只训练"如果被问，它会怎么反思自己"，从不训练它的实际行为。结果既降低了不诚实，又让 "honest" "integrity" 开始出现在 J-space 里。改的是内部推理，不是改输出。

### 这对 harness 设计意味着什么

J-space 的发现改变了我们对 Agent 行为的认知：

* **推理是紧凑且可分离的。** 大部分神经活动处理的是表面流畅性。推理核心是一个小的、可识别的子空间——这意味着它可能被独立监控、引导或验证。
* **内部状态现在部分可观测。** 在 J-space 之前，我们只能看到输入和输出。现在有了观察意图形成的窗口。对安全敏感的 Agent，这开启了输出前干预的可能性。
* **模型知道的不止它说的。** J-space 里持续存在模型意识到但没有说出口的概念。这证实了一个长期怀疑：只看输出会错过模型的真实状态。

### 当前局限

Anthropic 明确列出了边界：

* J-space 在单次前向传播里演化，不是人脑那种时间上的递归回路
* 目前只有词（没有图像、声音、动作）
* 工作记忆无限不衰减（不像人的几秒就忘）
* J-lens 只能抓单 token 的概念，复杂多步计划还看不到
* 这是 access consciousness（信息在系统内的可及性），不是 phenomenal consciousness（主观体验）

Anthropic 提出的关键开放问题：我们现在能看清 workspace 里有什么，却还不知道是什么机制决定了一个念头能不能进这个 workspace。

## 生产环境中的 LLM 评判器

从 trace 审查到回归用例、人工校准裁判与部署的完整操作流程，见 [AI 产品评测](/zh/env/ai-evals)。

用一个语言模型去评判另一个模型的输出很常见，但在规模化生产环境中让评判器持续有效是另一个问题。Netflix 每周用评判器处理数十万条剧集推荐解释，服务数百万移动端会员。他们的核心洞察：把评判器当作一个**四阶段生命周期**，而不是一次验证完就完事的工件。

### 四个阶段

**诞生（Birth）**——定义多个评估标准，构建带人工标注和理由的精选基准。基准是评判器的真相来源，因此人工标注质量直接决定了评判器质量的上限。

**训练（Training）**——通过 Reasoning-Aligned Rubric Tuning 精化评判器的评分标准。一个元评判器对评判器的推理输出打分，这个信号用来训练评分标准。评判器学的是"为什么好答案是好答案"，而不只是"好答案长什么样"。

**部署（Deployment）**——同一个评判器扮演两个角色：质量把关（拦截坏输出）和反思生成（告诉生成器如何改进）。同一个模型可以两者兼顾，但两个角色需要不同的提示词和阈值。

**监控（Monitoring）**——持续的人机对齐检测漂移，在审查门控后触发重新调优。评判器的质量不是静态的，它会随着数据、模型和用户期望的变化而漂移。

在数千万会员上跑的五周 A/B 测试表明，观看行为向之前未看过的内容转移，成功的浏览转播放会话增加，且没有质量相关的下架。结论：评判器质量是一门运营纪律，不是一次性设置。

## Harness 评测的困境

越来越多人意识到，用重度工程化的 harness 去评测模型是失真的。模型厂商优化自己的专有 harness，所以"在我们的 harness 里最好"对"在你的环境里最好"几乎没有参考意义。

更干净的做法是用**最小 harness** 测试模型质量——轻薄、标准化的设置，暴露模型的原始能力，不受厂商专用脚手架干扰。这不完美：每个 harness 都有偏向某些模型的偏见。但标准化的最小 harness 比各家调优的设置更可比。

更深层的问题：harness 工程正是领先 AI 公司现在投入的方向，而且演进太快，标准化跟不上。前沿方向是模型按任务动态生成自己的 harness——Claude 已经在一定程度上做到了，只是不稳定。如果 harness 最终变成像 system prompt 一样可调的工件，基准测试只会越来越模糊。

目前最干净的受控实验：**ReFigBench**（2026）把 GPT-5.5 分别放进 Claude Code 和 Codex 跑同样的 1000 个任务。带专门 PowerPoint 工作流时，模型在一个 harness 里变好、在另一个里变**差**——而提示词完全相同。仅 harness 本身就能翻转变化的方向。感知始终是瓶颈。把厂商图表里两个模型的对比，当作两套"模型+harness"系统的对比来看；模型只是受测系统的一半。

## 多模型编排

Harness 设计的一个大趋势是同时运行多个模型，而不是赌一个。两个最近的例子展示了方向。

**GitHub 的 Project HydraFusion** 把工作流选择当作优化问题。每个请求会从三种执行模式中选一个：

* **Single（单一）**——一个选定的模型直接解决任务。一个模型足够时最快。
* **Cascade（级联）**——一个高效模型先起草，质量门决定接受还是升级到更强模型。第一次尝试便宜，升级是安全网。
* **Critique（批判）**——一个模型起草，来自不同模型家族的独立只读评审者审阅，起草模型修订一次。当评审比再来一次无监督尝试更有价值时使用。

在 TerminalBench 2.1 上，HydraFusion 相比 Claude Opus 5 提升了 4.9 个百分点的验证任务质量，同时估算成本降低 67%。洞察：模型间路由是质量与成本的旋钮，只要有可验证的门控能抓住失败，便宜模型就应该得到第一次尝试的机会。

**Grok Bot 的设计哲学**把持久化 Agent 设计提炼为四点：持久角色、清晰状态、限定上下文、协调团队。目标是从“操作”AI 转向“委派”工作——Agent 团队跨任务持续存在，职责和边界稳定，而不是每次会话从头重新提示。

在加路由之前，先审计你的 Agent 设计到底在优化什么。TypeSafe 的反事实思想实验很直白：很多"标准"Agent 特性是为了绕开 KV cache 和按 token 计费，而不是用户真的需要。他们的算例：按 Opus 级（输入 5、输出 25）和 Sonnet 级（3、15）计价，先用便宜模型再回大模型——cache 按模型隔离，大模型要把绕路的每个 token 按输入价重付一遍——上下文一大反而**比全程用强模型更贵**。让路由真正省钱的不是更好的路由器，而是**按查询重建上下文**：给每个 chunk 打相关性标签，按需重建，而不是假设未来每个 turn 都要同一份共享缓存。同一个审计也解释了为什么渐进披露（skills）优于前置工具 schema、条件加载优于常驻记忆文件。

路由的奖池到底有多大？Fireworks 在 113 个真实编码任务上跑了 18 个模型，再问一个 oracle 路由器能做到什么。最佳单模型：74.1%，每任务 6.52 美元；oracle 路由：97.6%，1.88 美元；只用开源权重模型路由也有 90.3%、1.45 美元——反超全部闭源模型。三个值得记住的发现：

* **几乎没有任务真的需要最贵的模型。** 113 个任务里 94 个的最优选择是单价低于 3 美元的模型；三个 11.5 美元以上的旗舰只在 3 个任务上唯一最优。固定用一个旗舰，是在为多数任务用不到的"通用能力"交保险费。
* **路由池不需要大。** 最佳双模型组合比最佳单模型高 13.1 个点，三模型到 91.2%，扩到 18 个只再涨 6.4 个点。价值来自互补覆盖，不是数量。
* **难的是预测哪个模型合适。** 严格 pass\@1 口径下，近期路由研究（含商业方案）难以稳定击败简单基线；瓶颈在模型召回——池子里有合适的模型，路由器认不出来。当专业化差异不可预测时，坚持用一个熟悉的模型反而是理性策略。

路由首先不是省钱工具：如果模型真正互补，路由是沿能力曲线上移，省成本只是副产品。第二个隐性成本是上下文——切模型通常意味着丢弃已付费的上下文，所以保留上下文的路由器（cache 感知交接）会再次改写经济学：Fireworks 在 2334 个内部编码会话上报告了 53% 的成本下降。

单模型内部，杠杆是 prompt cache 工程。GPT-6 的缓存按**精确前缀匹配**工作，所以要把 prompt 当缓存布局来设计：稳定内容（系统策略、工具 schema、共享上下文）放前面，每次请求变化的内容放最后。前缀里一个多余 token 会静默作废整个折扣。GPT-6 补上了老模型缺的东西：

* **显式断点**——标记可复用前缀在哪里结束，不依赖隐式摆放
* **`prompt_cache_key`**——把请求导到持有你缓存的服务器
* **诊断工具**——把未命中的请求和早前请求对比，看是哪个变化（模型、工具、设置、输入）破坏了复用

缓存读取最多打 1 折、首 token 延迟最多降 80%；新一代模型上缓存**写入**可能收费，所以臃肿但很少复用的前缀现在是成本，不是免费保险。这个机制奖励的设计习惯：易变的东西全放尾部，把"缓存命中了吗"当监控指标，而不是碰运气。

这两个杠杆——跨模型路由和模型内缓存——正越来越多地住进**组织级控制面**，而不是每个开发者的脑子里。Cloudflare 的 Auto Router（2026 年 9 月公开 beta）放在 AI Gateway 里：模型设成 `cloudflare/auto`，每个请求自动路由到对任务足够用的模型，终端用户无感。内部经 OpenCode 实测比纯旗舰省最多 30%。理由和 Fireworks 的发现一致：个人手动选模型经常杀鸡用牛刀（"总结邮件不需要 Opus"），但一刀切封禁又会伤到重度用户——所以省钱必须让用户察觉不到。Gateway 的位置才是关键：每个用户、Agent、工具的请求本来都要经过它，预算和政策文档只能"请求"的事，它可以直接执行。

## Computer Use 成本控制：反向工程为脚本

Computer-use Agent 好用但贵：每一步都是截屏 → 视觉理解 → 决定点哪里 → 再截屏验证。一个简单任务可能消耗几十轮视觉推理。

一个既能保留能力又能降本的做法：让 computer-use 流程只跑**一次**，抓取浏览器发出的网络请求，再让 Agent 把这些请求整理成脚本。之后的重复执行直接调 API，不再走图形界面。

为什么这样有效：

* **token 降到接近零。** 脚本执行不需要模型参与，只有一次性抓取和脚本生成消耗 token。
* **快得多。** GUI 操作受页面加载、渲染、模型延迟多重限制，直接 HTTP 调用把分钟级降到秒级。
* **复用现有登录态。** 抓到的请求里包含 session cookie / token，脚本沿用这些凭证，不需要额外申请 API key——对没有公开 API 的 web 应用同样适用。

示例工作流：“去 acme.com/invoices，筛选未付款，导出 CSV”→ Agent 一边点击一边记录 `GET /api/invoices?status=unpaid` 和 `POST /api/export/csv` → 输出一段 Python `requests` 脚本，复用 session，之后作为定时 routine 自动跑。

分工原则：**视觉用于探索，代码用于执行。** 用 GUI 探索未知路径一次，然后把发现的路径固化成便宜、可重复的脚本。

GUI 路径没法固化成 API 时，把**决策**和**感知/执行**拆开。Cua 的 jev-use 就是这样做 Computer Use 的：Driver 负责观察（截屏、无障碍树、DOM）和执行；System One 模型（如 Jev）只按 ID 从候选动作里选一个。候选列表由客户端确定性生成，模型选择而不是生成。开放式生成变成有界选择——更快、更便宜、也更好验证。只有 AX/DOM 不够用时，才调用视觉解析器。

## 团队级 harness：共享知识

个人最佳实践如果不沉淀为团队资产，就会随每个会话蒸发。腾讯 2026 年 9 月开源的 TeamAI CLI（内部用了半年）把团队 AI 知识放进一个 git 仓库，让每个 Agent 都从同一本手册工作，解决三个问题：

* **配置碎片化**——成员用不同工具（Claude Code、Codex、Cursor...），各自的 skill/rule/hook 格式互不兼容。
* **经验蒸发**——某人花两小时踩透的坑，只留在他自己的会话记录里，其他人（和其他 AI 会话）下次再踩一遍。
* **治理盲区**——不知道 token 花在哪、干预率多高、哪些 skill 真正被用、哪些是僵尸。

它的三层架构是一个值得参考的模式：

1. **Execution——统一分发。** Git 是唯一事实来源。管理员维护 skills、rules、hooks、MCP 配置，经 MR 评审合并后，由 SessionStart hook 自动拉取到每位成员的本地工具，把统一声明翻译成各工具的原生格式。
2. **Context——团队记忆。** 写入侧靠"摩擦信号"过滤：只有你打断过 AI、拒绝过工具调用、或 AI 反复重试失败的会话，才会总结成经验推送到团队仓库——顺滑的会话不产生噪音。读出侧用本地 BM25 索引 + 代码知识图谱。
3. **Improvement——飞轮闭环。** 周报 + 看板 + `recall promote`（高价值经验晋升为正式 skill）+ `recall maintenance`（清理过时条目）。

更深层的趋势：竞争正在从单个 Agent 的能力，转向**团队级 harness 和记忆系统的标准化**。关键问题不再是"哪个模型最好"，而是"团队知识如何在会话和成员之间复利增长"。

## 什么时候值得投入更强的 harness

一开始可以简单。等任务变得重复、高风险或高成本，再加结构。

这些情况值得认真做 harness：

* Agent 会修改代码或生产数据
* 多个工具需要共享状态
* 用户会恢复长会话
* 审批和审计日志很重要
* 同一套流程要给团队多人使用
* 需要比较不同模型版本下的行为

如果只是一次性、低风险任务，一个提示词加几个工具就够了。只要任务开始变成长时间、带状态、可复用的工作流，就应该尽早设计 harness。

## 参考资料

* [meng shao：agentchat 传输层 SDK](https://x.com/shao__meng/status/2109819186893766721) — 2026-10-13 的 Folo 线索

* [BerriAI agentchat：`fb892cb` 版本架构](https://github.com/BerriAI/agentchat/blob/fb892cb8945af17b2e6dbe7aa1563daeb15cfcad/docs/architecture.md) — 适配器、核心层与应用层的职责

* [agentchat：分发实现](https://github.com/BerriAI/agentchat/blob/fb892cb8945af17b2e6dbe7aa1563daeb15cfcad/src/agentchat/app.py) 与[内存状态](https://github.com/BerriAI/agentchat/blob/fb892cb8945af17b2e6dbe7aa1563daeb15cfcad/src/agentchat/state/memory.py) — 认领顺序与进程内状态

* [Slack：Events API](https://docs.slack.dev/apis/events-api/) — HTTP 接收确认时限与重试

* [Slack：请求验签](https://docs.slack.dev/authentication/verifying-requests-from-slack/) — 原始请求体验签与重放防护

* [Vercel：Agent 通过 CLI 购买域名](https://vercel.com/changelog/agents-can-now-buy-domains-with-the-vercel-cli) — 2026-10-09 的 Folo 线索，非交互式购买交还用户确认

* [Vercel CLI：Domains](https://vercel.com/docs/cli/domains) — 候选查询、可注册状态、报价与购买命令参考

* [Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering](https://arxiv.org/abs/2604.08224)

* [Micropaper：LLM Agent 的外化设计范式](https://unbug.github.io/one-minute-read-paper-externalization-in-llm-agents/)

* [Anthropic Engineering：An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem)

* [Anthropic Research: A global workspace in language models（J-space）](https://www.anthropic.com/research/global-workspace) — 不到 10% 的神经活动驱动多步推理；J-lens 方法让内部推理首次可见

* [Netflix：生产环境中保持 LLM 评判器有效](https://arxiv.org/abs/2608.18300) — 四阶段评判器生命周期（诞生、训练、部署、监控）

* [GitHub：Project HydraFusion](https://github.blog/ai-and-ml/github-copilot/project-hydrafusion-frontier-quality-via-multi-model-orchestration/) — 多模型编排：Single/Cascade/Critique 三种模式

* [xAI：Designing Grok Bot](https://x.ai/news/designing-grok-bot) — 持久角色、清晰状态、限定上下文、协调团队

* [Harness Playbook](https://x.com/i/article/2095796679568146432) — omp 作者关于 harness 状态、运行时、控制面、推理层、工具面的系统总结

* [腾讯：TeamAI CLI](https://github.com/Tencent/teamai-cli) — 团队级 harness：Git 作事实来源，三层架构（Execution/Context/Improvement）

* [poteto：pstack 验证优先设计](https://x.com/shao__meng/status/2099300148874707297) — 验证 CLI、Feature Map、云端并行与可调试性选型

* [MCP vs CLI：Agent 工具选型](https://x.com/dotey/status/2100046089214709979) — 无状态 MCP 和 deferred tools 缩小了差距，但本地熟悉命令、管道和 CI 仍更适合 CLI

* [GitHub：Should you read the code, is RAG dead, and did Skills kill MCP?](https://github.blog/ai-and-ml/should-you-read-the-code-is-rag-dead-and-did-skills-kill-mcp/) — Skills、MCP、RAG 解决不同缺口，不要选赢家

* [Cua jev-use](https://x.com/shao__meng/status/2100870131324985740) — Computer Use 拆成决策层 + 确定性 Driver

* [GAVEL: graph world models](https://academy.dair.ai/papers/gavel-graph-world-models-for-verified-and-efficient-long-horizon-llm-task-planni-2609.19315) — harness 把 Qwen3-8B 从 41.2% 提到 91.8%，模型零改动

* [腾讯 T-Mem](https://arxiv.org/abs/2606.15405) — 写入时预演 trigger，填补相似度检索的联想盲区

* [TypeSafe：coding agent 笔记](https://x.com/shao__meng/status/2101921711545331832) — KV cache 审计：按难度路由为何经常更贵，按查询重建上下文才是解法

* [Fireworks：The frontier isn't a model, it's a router](https://fireworks.ai/blog/the-frontier-isnt-a-model-its-a-router) — oracle 路由 97.6% vs 最佳单模型 74.1%；价值来自互补覆盖而非池子大小

* [Question's Gambit (arXiv 2609.14412)](https://arxiv.org/abs/2609.14412) — 首步预检索把 GPT-5.5 从 83.1% 提到 90.5%；错误集中在消费环节而非抓取

* [ReFigBench (arXiv 2609.18844)](https://arxiv.org/abs/2609.18844) — 同一模型在 Claude Code 与 Codex 里表现方向相反，提示词相同

* [OpenAI: Better prompt caching for GPT-6](https://openai.com/index/better-prompt-caching-for-gpt-6) — 显式断点、cache key 与诊断；读取最多打 1 折

* [Cloudflare: Auto Router](https://blog.cloudflare.com/auto-router/) — 组织级控制面路由，终端用户无感省最多 30%

* [Matt Pocock Skills：Teach skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/teach)

* [PsiACE：Agent 不只是执行流程的容器](https://x.com/repsiace/status/2072039687364161965) — 关于 Agent 应作为人理解、判断和协作的环境，而不仅是自主执行容器的设计洞察。

* [Claude Code 通过隐写方式标记请求](https://thereallo.dev/blog/claude-code-prompt-steganography) — Claude Code 通过不可见 Unicode 隐写标记 API 请求的案例分析，提醒开发者审查有文件系统和 shell 权限的工具。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.