阅读指南

这本书在讲什么

Nexus 是腾讯内部开发的 AI Agent 编排框架，面向强化学习、SFT/RFT 数据生成和评测等研究场景。它的核心设计理念是将 Agent、Tool、Task、Runtime 解耦为独立可组合的模块，通过统一的注册系统和执行上下文串联。

截至 v1.1.3（2026-08-12 抓取），Nexus 包含 1047 个文件，16 种内置 Agent，28 个 Task（涵盖 SWE-bench、WebArena、GAIA、GSM8K 等主流 benchmark），34 个 Tool，8 种 OpenAI 兼容 LLM Client，6 种 Runtime Provider（本地/Docker/工蜂/AGS/Android）。

本书对这个框架进行系统性拆解。不是 API 文档的翻译，也不是功能清单，而是从源码中提取设计意图。

两种阅读路径

路径 A：赶时间——「给我跑起来」

如果你是 Nexus 的新用户，想尽快跑通自己的任务：

1. 第 1 章：理解核心概念（5 分钟）
2. 第 2 章：跑通第一个任务（10 分钟）
3. 第 3 章：接入你关心的 benchmark
4. 第 4 章：选择和切换 Agent
5. 第 5 章：如果你需要产出训练数据
6. 第 6 章：如果你需要写自定义模块

遇到”为什么这样设计”的困惑时，跳到对应的原理章节。

路径 B：搞明白——「为什么这么做」

如果你想理解框架的设计哲学，或者想贡献代码：

从 第 7 章（注册系统） 开始顺序阅读。每一章从一个实践中会遇到的问题出发，然后深入到代码层面解释设计决策。推荐同时打开 Nexus 源码对照阅读。

另需注意一处口径差：第 2 章为上手效率只介绍 3 种最常用的 Runtime Provider，但 Nexus 实际内置 6 种（local / docker / gongfeng / ags / android_websocket / android_cloudtest），完整对比见第 1 章。走这条路径的读者请以第 1 章的表为准。

前置知识

• 必须：Python async/await、Pydantic 基础、Docker 基本操作
• 推荐：对 Agent 框架有概念性了解（如知道 ReAct 范式）
• 加分：有 SWE-bench 等 benchmark 的评测经验

行业动态（截至 2026-10）

Nexus 的”模块化解耦”设计哲学在 2026 年获得了来自行业前沿的呼应：

Anthropic Agent Graph 方法公开（2026-08-02）：Anthropic 工程师 Lamis 在伦敦 AI Native DevCon 首次公开内部 Agent 工程体系——用结构化的图式工作流替代传统提示词工程。其四代记忆演进（CLAUDE.md → memory tool → Skills → 文件系统化记忆）和”dreaming”复盘机制，与 Nexus 将 Agent/Tool/Task/Runtime 解耦为独立模块的思路底层相通——两者虽然实现路径不同（Anthropic: 图工程+文件记忆 / Nexus: 注册系统+执行上下文），但都建立在”模块化优于一体化”的架构判断之上。这一外部信号验证了 Nexus 设计方向的前瞻性。

CMA 平台升级（2026 年 7 月下旬）：Anthropic 托管智能体平台（CMA）一次性推出六项更新——技能上限 20 → 500（单会话内所有 agent 共享，运行于统一托管沙箱，agent 间共享内存与环境变量）；思考力度五档可调（low / medium / high / xhigh / max，可按单个 agent 配置）；种子会话一步创建（最多预载 50 条初始事件，消除冷启动）；子 agent 实时流下探到线程级；新增 7 个生命周期 webhook（4 个环境事件 + 3 个记忆存储事件）；agent 更新接口的 version 字段改为可选。

⚠️ 日期存疑：上段时间多家二手来源一致指向 2026-07-22（依据之一为”Fable 5 发布后 45 天”），但 Anthropic 自己的 Claude Code 变更日志另有一处”Managed Agents Aug 19 release”（自带托管沙箱上的 web search/fetch 域设置与 memory store）。两者可能是同一次升级的不同批次，也可能是两次独立升级，官方一手 release notes 未直接核到，故本章取”2026 年 7 月下旬”这一较宽的写法。引用时请以官方 release notes 为准。

对本书读者更关键的其实是它的实现机制：500 个技能能塞进一个会话，靠的是 progressive disclosure（渐进式披露，三级按需加载）——不再一次性展开全部技能定义，而是按需载入，把技能定义对上下文的占用压缩一到两个数量级。也就是说，“容量扩展”是由”上下文压缩”买单的。这与本书第 8 章（上下文）与第 15 章（上下文管理与 Compaction）讨论的是同一类问题：Agent 编排基础设施的上限，最终由上下文预算决定，而不是由功能数量决定。

⚠️ 有二手来源把该机制的收益量化为”50 个技能从约 150,000 tokens 压到约 2,000 tokens（约 75×）“。该数字目前仅见于单一二手源，未获官方确认，故正文只保留定性表述。若后续在 Anthropic 官方 release notes 核到，可替换为本条数字。

ACP 生态扩张（2026-09）：Agent Canvas（原 OpenHands）已迭代至 v1.24.0（2026-09-25），定位收敛为”自托管的开发者控制中心”，通过开放协议 ACP 接入 Claude Code / Codex / Gemini CLI / OpenHands Agent，卖点是”保留你原有的订阅与模型”。这与上面 Anthropic Agent Graph 是同向信号——“开放协议 / 可组合”正在成为 Agent 编排的主流路线；Nexus 的注册系统 + 执行上下文属于同一架构判断，只是实现路径不同（协议优先 vs 可观测优先）。

按 GitHub Releases 的发布序列，自 2026-08 中旬更名（v1.12）以来，Agent Canvas 已迭代 12 个版本（v1.13 至 v1.24）。

Agent 轨迹成为被觊觎的资产（2026-09-10）：Anthropic 威胁情报报告首次把模型蒸馏列为七大危害域之一，点名 7 家实验室、单场战役交换量上亿次，攻击目标明确包括 agent 的能力与工具使用。对本书的意义很直接：Nexus 的原生 Trace 体系产出的不是调试副产品，而是高价值资产，其存储与访问控制应作为设计考量进入架构决策，而不只是”方便排查”。详见 CCI 第 23 章。

AgenticBench 把”轨迹可审计”做成了被测项（2026-09-26~28）：一个第三方开放基准，明写不测能力、测行为——22 个受测 Agent，每个跑 18 项测试（四类：5 / 5 / 4 / 4），四类分别是什么离开了你的机器、给了谁、关闭开关是否真的有效、无人看管时会发生什么、Agent 自己的记录是否显示它做了什么。评分规则里有一条对本书格外重要：“缺失一项保护措施”即计为 Fail。

这恰好是上一条的反面：本章此前只能说”Trace 是高价值资产、其存储与访问控制应进入架构决策”——那是一个倡导。AgenticBench 把它变成了会被公开打分的测试项：一个 Agent 有没有留下可审计的行为记录，现在直接对应榜单上的一个 Fail。方法论论文 v1 已于 2026-09-28 发布（doi 10.5281/zenodo.23012408）。

⚠️ 本条的两条限制，读结果时必须一并带上（站方自述）：① 机械泄漏测试不检查发给模型本身的请求——一个 Pass 只意味着”其他请求里没发现”，打包进模型请求的数据收集仅由人工复核覆盖；② 多数 Agent 是在替换掉厂商默认模型提供方、且未登录厂商账号的条件下跑的，换成厂商自有服务或登录态后行为可能不同。 另：截至本书核于 2026-10-02，该站首页仍自标 v0.2 preliminary，且部分厂商结果处于披露冻结（站方列有 “Withheld during disclosure” 一节）。本章据此不写入任何具体 Agent 的通过/未通过数；v0.3 安全基准结果（站方预告 2026-10-01 发布）在本轮核时未上线，同样不写。

评测基准换代（2026-09）：Terminal-Bench 4.0 已取代 2.0（Artificial Analysis 指数同步切换），SWE-bench Pro 则存在 vendor-scaffold 与标准化公开集两种不可互换的口径。基准半年一换、口径各说各话，正是”快速接入新 benchmark”这一 Nexus 卖点的价值所在——详见第 1 章与第 3 章。

⚠️ 引用 Terminal-Bench 4.0 数字时，“官方榜”与”聚合站”已出现榜首不一致：官方 tbench.ai 4.0 榜（updated 2026-09-21）榜首为 GPT-6 Astra 58.2%；同期第三方聚合站 llm-stats 榜首为 Claude Sonnet 5.5 70.6%，而该站自标 Status: Unverified、Self-reported 10 / Verified 0。两者对已共有模型的分数也不完全一致（Astra 官方 58.2% vs 聚合站 57.7%）。本章引用 TB 分数时须标明取自官方榜还是聚合站，不可混用，更不可用聚合站榜首替换官方榜榜首。

Harbor：本书缺位的那类对照物出现了（2026-10-10 核）：Terminal-Bench 团队（Laude Institute）开源的评测框架 Harbor（github.com/harbor-framework/harbor，Apache-2.0，v0.24.0 / 2026-10-05，5955★ / 1961 forks）是本书此前唯一缺位的对照类型——全书对标对象（OpenHands / SWE-Agent / LangChain / verl）分属 Agent 侧与 RL 侧，没有一个评测 harness 级的对等物，而”评测 + 训练闭环”恰恰是 Nexus 的主赛道。

它其实已三度出现在本书里：第 3 章引 Terminal-Bench 官方页头 Hosted by Stanford / Harbor / Laude Institute、第 5 章的”Harbor Hub”与 github.com/harbor-framework/terminal-bench-2 链接——三处都只把它当托管方名字或 URL 片段用过，从未追问它是什么、它的 task / verifier / agent 契约与 Nexus 差在哪。本书自本轮起把它作为正式对照物写入，落点分布在第 1、3、5、7、13 章。

⚠️ Harbor 仍在 v0.x 高频迭代（近两个月 v0.20→v0.24 共 5 个版本）。本书所有 Harbor 计数（版本 / star / 数据集数 / environment 数 / agent 数）均核于 2026-10-10，引用前请对照当期仓库复核——本书第 0 章自身已因”快照 51 天未复核”吃过一次亏。

约定

• 代码引用格式：nexus/core/registry.py:L77 表示文件和行号
• 版本基准：v1.1.3（pyproject.toml 中 version = "1.1.3"，本书所有数字以此版本为准，抓取于 2026-08-12）

  ⚠️ 该快照距今已 51 天（本书核于 2026-10-02）。1047 文件 / 16 Agent / 28 Task / 34 Tool / 8 LLM Client / 6 Runtime Provider 这六项计数自抓取日起未再复核。若 Nexus 在此期间发过新版，这一段就是全书中错误传播最广的一段。使用本书任何计数型数字前，请先对照当前 pyproject.toml 与 nexus modules 输出确认。

• 推测性判断会标注”推测”
• 「」用于强调概念，""用于引述