2026 年 7 月 10 日，OpenAI 发布了 GPT-5.6。

这次发布的信息量很大，但如果只抓一个核心变化，那就是：大模型正在从聊天机器人变成能干活的智能体。过去你问它问题，它给你答案；现在你给它目标，它能自己规划步骤、调用工具、协调多个 Agent 并行工作，最终把任务完成。

方向对了还得看数字。GPT-5.6 在效率上也交出了非常亮眼的成绩单：以更少的 Token、更低的成本，在编程、知识型工作、网络安全和科学领域均取得了行业前沿水平。用官方的话说：树立了智能与效率的新标杆。

这篇文章基于 OpenAI 官方发布文档，从核心定位、多智能体架构、编程能力、设计能力、安全机制和开发者影响几个维度展开分析。

一、核心定位：从对话到执行

1.1 一个关键转变

过去几年，大模型的发展路径很清晰：GPT-3 解决语言生成问题，GPT-4 解决复杂推理问题，GPT-5.6 开始解决任务执行问题。

这三种能力不是替代关系，而是叠加关系。GPT-5.6 依然具备强大的语言生成和推理能力，但它更进一步——正如官方文档所说，它能够理解目标、规划步骤、调用工具并完成复杂任务。

1.2 这意味着什么

用一个具体例子来理解。假设你在线上遇到一个接口变慢的问题：

传统模型会给你一套排查建议：查慢 SQL、检查 Redis 命中率、分析 JVM GC、看链路追踪……建议完全正确，但给建议不等于解决问题——你还是得自己去连监控、查日志、改代码、验证效果。

GPT-5.6 代表的方向是：模型自己去连监控系统、查日志、分析 SQL、定位问题、修改代码、跑测试、验证效果。用官方的描述，它能够编写并运行轻量级程序，在工作开展过程中协调工具、处理中间结果、监控进度并自主选择下一步操作。当然，这是一个理想化的场景，实际效果取决于工具集成的完整度和权限配置。

用一个类比来说：传统模型像一个百科全书式的顾问——你问什么它都知道，但不动手；GPT-5.6 更像一个能干的同事——你给它一个任务，它会自己想办法完成。

1.3 数据佐证

这不是概念层面的畅想，具体数据已经在多个 Benchmark 上得到了验证。

Agents’ Last Exam——覆盖 55 个专业领域的长周期 Agent 工作流评估。GPT-5.6 Sol 在该评测中领先 Claude Fable 5（自适应推理）13.1 分，即便在中等推理强度下，也以约 1/4 的成本领先 Fable 5 达 11.4 分。

OSWorld 2.0——衡量模型在真实计算机环境中的操作能力。Sol 得分 62.6%，超越 Claude Opus 4.8，同时输出 Token 用量减少 85%。

BrowseComp——智能体网页浏览评估。Sol 得分 90.4%，ultra 模式下达到 92.2%。

这些数据的共同指向是：GPT-5.6 不只是更聪明了，而是能独立完成更长周期、更复杂的任务了。

需要说明的是，GPT-5.6 本身并不等同于 Agent。更准确地说，它提供了更强的 Agent 核心模型能力，而一个真正可靠的智能体系统仍然需要开发者构建工具层、状态管理层和执行框架——也就是 Agent = LLM + Tools + Memory + Runtime + Verification。GPT-5.6 解决的是其中 LLM 这一环的能力跃升，其余部分仍然是工程问题。

二、多智能体：从单兵到协同

2.1 ultra 模式

GPT-5.6 最值得关注的新能力之一是 ultra 模式下的多智能体并行。官方文档的描述是：

ultra 是我们最高性能的设置，能够跨多个并行工作流协调多个智能体，更快地完成复杂任务。

ultra 模式默认并行 4 个智能体，在 BrowseComp 和 SEC-Bench Pro 的测试中还展示了 16 个智能体的配置。

官方给出的数据结论是：增加并行智能体会将得分-延迟前沿向左上方推移——在更短时间内取得更优的结果。

2.2 为什么这很重要

用一个类比来理解：过去的模型像一个超级聪明的实习生——能力很强，但一次只能干一件事，你得等它做完 A 才能让它做 B。多智能体模式更像是一个小型团队——一个项目经理负责协调，几个执行者分头干活，最后汇总结果。

对于复杂任务（比如分析最近一个月销售下降原因并生成优化方案），多个 Agent 可以分头查销售数据、查用户画像、分析市场趋势、查库存情况——然后汇总分析，生成报告。任务完成时间大幅缩短。

不过需要澄清一点：多智能体的核心价值不在于简单堆叠 Agent 数量——4 个 Agent 重复犯同样的错误并不会比 1 个 Agent 更好。真正的价值在于任务分解和角色分工：不同 Agent 负责不同子任务（比如 Research Agent 负责数据收集、Coding Agent 负责实现、Testing Agent 负责验证），配合共享记忆和验证机制，才能发挥协同效应。ultra 模式的意义也应该从这个角度理解。

2.3 API 层面的支持

开发者可以通过 Responses API 的 multi-agent 功能（测试阶段）实现类似 ultra 的体验：在单个请求中并行运行多个子智能体，并整合它们的工作成果。

三、模型体系：从单一到分层

3.1 三个层级，按需调度

GPT-5.6 提供了三个模型层级：

值得注意的是命名策略：数字标注代系（5.6），Sol/Terra/Luna 是持久的能力层级，可以按各自节奏独立演进（据官方文档描述）。从产品设计来看，OpenAI 正尝试建立一套长期的能力分层体系——如果这套策略持续下去，未来的 GPT-5.7 大概率仍然是 Sol/Terra/Luna 三档。

3.2 效率才是关键

不同任务对模型能力的要求差异巨大。所有任务都用最强模型，成本直接爆炸；都用轻量模型，复杂任务又搞不定。GPT-5.6 的效率数据很有说服力：

• Luna 表现超越 Claude Fable 5，而成本仅为后者的约 1/16（据官方文档）
• Terra 以更低的成本超越了 GPT-5.5 的表现
• 在编程场景中，Sol 相比 Fable 5：输出 Token 减少一半以上，耗时缩短一半以上，成本降低约三分之一
• Prompt Cache 支持显式缓存断点（explicit cache breakpoint），缓存有效期至少 30 分钟，缓存读取享受 90% 费率优惠

不只是同样的钱做同样的事，而是同样的钱做更多的事。

四、软件工程：从生成到协作

4.1 为什么软件工程是最佳试验场

软件工程天然具备几个适合 Agent 发挥的特点：

• 任务目标明确：修 Bug、实现功能、优化性能——每一类都有清晰的完成标准
• 环境反馈丰富：编译结果、测试输出、运行日志都会给出明确信号
• 过程可以验证：单元测试、集成测试、Code Review、线上指标，都是验证手段

软件工程是那种做对了就是对了，做错了立刻能发现的领域——这恰好是 Agent 最需要的环境特征。

4.2 软件 Agent 的三层核心能力

从技术角度拆解，一个能参与软件工程的 Agent 需要具备三层能力：

第一层：Repository Understanding（代码库理解）。不是把整个项目塞进上下文，而是能像工程师一样探索代码——Code Search 定位关键符号、Symbol Graph 分析调用关系、Dependency Analysis 理解模块依赖。GPT-5.6 在可编程工具调用上的突破（前文已述）正是为这一层提供了基础：模型可以自己写程序来检索和分析代码，而不需要每一步都依赖外部系统。

第二层：Execution Feedback（执行反馈）。修改完代码后，Agent 需要能运行测试、查看编译结果、分析日志，根据真实反馈调整策略。Terminal Agent 的能力直接决定了这一层的上限——这也是 Terminal-Bench 成为重要评测的原因。

第三层：Change Management（变更管理）。一次软件变更不只是改代码，还需要 Diff Review 确认修改范围、Rollback 机制应对失败、Human Approval 把控关键决策。这层能力目前更多依赖工程框架而非模型本身，但模型需要能理解和配合这些流程。

GPT-5.6 在这三层上都有提升，但提升幅度不同——第一层和第二层进步最明显（可编程工具调用 + Terminal Agent），第三层仍然需要开发者在框架层面解决。

4.3 Benchmark 数据

值得注意：在 SWE-Bench Pro 上，Fable 5 仍然领先（80% vs 64.6%），说明不同 Benchmark 上各家模型互有胜负。但在 Coding Agent Index、Terminal-Bench、DeepSWE 这三项更侧重完整工程能力的评测上，GPT-5.6 Sol 都拿到了第一。

更重要的是效率：在 Coding Agent Index 上，Sol 以 80 分创下新 SOTA，同时实现了前文所述的效率提升——Token、耗时、成本均大幅下降。不只是更强，还更便宜更快。

4.4 可编程工具调用：一个关键的技术突破

GPT-5.6 在编程场景下的一个重要变化是：模型能够编写并运行轻量级程序，在工作过程中协调工具、处理中间结果、监控进度并自主选择下一步操作。

传统的 Tool Calling 模式是调工具 → 拿结果 → 再调工具 → 再拿结果，每一步都需要模型参与决策，消耗大量 Token 和交互次数。而 GPT-5.6 可以直接在内存中写程序来处理中间数据、过滤噪音、只保留关键信息，然后在运行过程中动态调整工作流。

官方文档的表述是：开发人员无需编写每一个步骤的脚本，也不必将工具的每个响应都回传给模型。Responses API 中的可编程工具调用功能让重度依赖工具的任务能够以更少的 Token、更少的模型交互次数顺利推进。

4.5 Terminal Agent：让模型看到运行结果

过去代码助手主要工作在 IDE 内，模型无法观察代码运行后的真实结果。而软件开发是一个高度依赖反馈的过程——模型生成了代码，但只有运行之后才知道对不对。

通过 Terminal，模型可以执行 git status、mvn test、npm run build、docker logs 等命令，观察编译错误、测试失败、运行异常。这让 AI 从代码生成器变成了开发环境中的参与者。前文 Terminal-Bench 2.1 的成绩也直接反映了这方面的能力。

4.6 真实用户反馈

Benchmark 是实验室数据，真实用户的反馈更值得关注：

GPT-5.6 帮助用户以比前代模型减少约 25% 的步骤和 35-48% 的工具调用量完成任务，同时将项目成功率提升了 15%，并减少了运行卡顿的情况。
—— Fabian Hedin，Lovable 联合创始人

GPT-5.6 是我们在 CursorBench 上测试过的能力最强的模型之一，在早期评估中表现稳健。在任务持久性、智能水平及整体效率方面的提升，对开发者而言是令人振奋的一步。
—— Oskar Schulz，Cursor 总裁

五、能力拓展：从代码到知识

5.1 设计能力跃升

官方文档专门用了一个章节介绍 GPT-5.6 在设计方面的进步：

仅凭高层次指导，GPT-5.6 就能创建美观、符合人体工学且功能完善的界面。凭借更强的计算机使用能力，它不再仅仅局限于生成底层代码或内容，而是能够检查并优化渲染后的结果——从而在交付最终作品前，主动捕获视觉与功能问题，并进行细节修饰。

这个能力转变值得关注——模型从生成完就结束变成了能自己看渲染结果、发现问题、自己修复。官方展示了多个 demo，包括 3D 航海游戏、博物馆网站、室内设计演示文稿、交互式万花尺等，均是仅凭自然语言描述生成。

在 ChatGPT Work 中，GPT-5.6 还能将自然语言请求转化为精美的、具有互动性的解释与可视化呈现——这对前端开发和教育场景有直接价值。

5.2 知识型工作

GPT-5.6 在知识型工作方面也有显著提升。据官方文档描述，它能从用户的文档以及 Slack、Notion、Microsoft 365 和 Google Drive 等日常工作流中提取信息，将其转化为专家级、可共享的成果。

具体能力包括：

• 演示文稿：从零开始制作完全可编辑的 PPT，能够推断参考文档的设计体系（排版、字体、间距、色彩），并一致地应用到新材料中
• 文档与电子表格：更准确地遵循复杂参考格式，在处理方程式与财务模型时更为精细
• 信息检索与整合：在 BrowseComp（智能体网页浏览）上取得了前文所述的成绩，反映了其从多源信息中提取和整合知识的能力

六、安全机制：从防护到受信

6.1 Agent 安全：从内容过滤到权限控制

传统模型的安全问题相对简单——输入危险内容，模型拒绝回答，核心是内容过滤。但 Agent 的安全问题本质上变了：模型不再只是回答问题，而是拥有了执行动作的能力。

这意味着安全的焦点从内容安全转向了权限控制。一个 Agent 可能拥有文件读写权限、数据库操作权限、代码执行权限、企业系统访问权限——真正需要防范的不是模型回答错误，而是模型在错误的时间、对错误的资源、执行了错误的操作。

所以 Agent Security 更接近传统软件安全中的 Identity + Authorization + Audit + Sandbox，而不只是输入输出过滤。理解了这个背景，再看 GPT-5.6 的安全设计就更有针对性。

6.2 分层保护架构

随着 Agent 能力增强（能自主执行任务、操作文件、运行代码），安全问题变得更加突出。据官方文档，GPT-5.6 采用了分层保护架构：

• 模型内置防护：在训练阶段嵌入安全约束
• 推理监控器（Reasoning Monitor）：审查对话内容，判断是否存在潜在危害——不再只靠分类器标记，而是用推理能力来理解上下文
• 实时校验 + 持续监控 + 账户级干预：多层冗余，确保单层失效时系统仍然安全

6.3 关键数据

• 正式推出前进行了约 70 万个 A100 GPU 小时的黑盒自动化红队测试
• 网络安全防护拦截量比前代模型增加约十倍
• 在生物学与网络安全领域，能力均超越前代，但未跨越严重（Critical）风险阈值
• 最敏感的网络安全能力仅通过 Trusted Access 计划向经过验证的用户开放
• 个人成员需在 9 月 1 日前使用基于硬件的通行密钥启用高级账户安全

6.4 一个值得思考的权衡

官方文档提到了一个有意思的观点：过度拦截本身也有安全风险。如果防护机制太严，防御者无法测试系统和部署补丁，而攻击者却在继续使用其他模型和现有黑客工具。官方的表述是：

有效的防护机制应充分考量请求的具体语境与可能产生的后果；在保护合规防御工作的同时，当有证据表明存在严重危害风险时，则应实施更严格的控制。

七、开发影响：从工具到系统

7.1 AI 辅助研发正在成为常态

OpenAI 在官方文档中披露了内部使用数据：

• 每位活跃研究人员的日均 Token 输出是 GPT-5.5 时期的 2 倍以上
• 用于内部代码推理的计算资源占比增长了 100 倍
• 内部 Agent Token 使用量增加了约 22 倍

官方也坦言：这些使用情况指标本身并不能衡量研究进展，但它们表明 AI 辅助在研究以及销售、营销、用户运营、财务等其他团队中的应用正在快速增长。

7.2 开发重点正在转移

从行业趋势来看，一个明显的变化是：开发者对怎么写 Prompt 的关注正在让位于怎么组织 Agent 的上下文和工具链。GPT-5.6 的产品设计也体现了这一点——可编程工具调用、multi-agent API、显式缓存断点、30 分钟缓存 TTL——这些都是在帮开发者解决工程层面的问题，而不只是提示词层面的问题。

（注：业界将这一趋势概括为从 Prompt Engineering 到 Context Engineering 的转变。这并非 OpenAI 官方术语，而是一个被广泛接受的行业观察。）

7.3 AI 应用越来越像传统软件系统

早期 AI 应用可能只需要一个前端加一个 LLM API 调用。未来需要 Agent 层、Workflow 编排、Memory 管理、Tools 集成、监控体系……AI 应用开发会越来越接近后端系统开发。

RAG 不会消失，但定位会变化——从独立的 AI 应用范式变成 Agent 系统中的一个知识组件。MCP（Model Context Protocol）等协议的重要性也在提升——Agent 需要连接大量外部系统，统一工具协议是降本增效的关键。

八、现实局限：从突破到边界

虽然 GPT-5.6 代表了 Agent 方向的重要进展，但距离完全自主工作的 AI 还有明显差距：

可靠性：模型仍可能理解错误目标、做出错误决策、产生幻觉。在 SWE-Bench Pro 上，Fable 5 仍然以 80% 领先 Sol 的 64.6%——说明在纯代码理解和修复能力上，还有提升空间。

成本：Sol 的输出价格 $30/M tokens 并不算便宜。复杂 Agent 需要多次模型调用，综合成本仍然不低。对于高频调用场景，Terra 和 Luna 是更务实的选择。

抽象推理：Sol 在 ARC-AGI-3 上只拿到 7.78%（据官方数据）——距离通用人工智能还有很长的路。

安全最佳实践缺失：让 Agent 自主执行任务、操作生产系统，安全边界如何划定？OpenAI 的分层防护方案是一个起点，但行业整体还没有成熟的标准。

总结

GPT-5.6 的意义不在于它是不是每个 Benchmark 上的第一名，而在于它代表了大模型应用方向的一次根本转变：

• 从聊天机器人到智能体——不再只是你说它答，而是你给目标，它完成任务
• 从单智能体到多智能体——ultra 模式并行 4-16 个 Agent，从一个超级实习生变成一个小型团队
• 从更贵到更高效——同样的钱做更多的事，Sol 编程场景成本降低 1/3、速度提升一倍
• 从生成内容到交付成果——能自我检查、自我修复，直接交付可用的结果

对于开发者来说，未来竞争的重点不会只是调用更强的模型，而是如何围绕模型构建可靠、高效、可维护的 AI 系统。GPT-5.6 是这个趋势中的一个重要节点，但真正决定 AI 应用价值的，仍然是系统工程能力。

GPT-5.6 的真正意义，不是让模型替代软件工程，而是让软件工程开始具备智能执行层。未来的软件系统，将不再只是由代码定义行为，而是由代码、模型和环境反馈共同驱动。

参考资料

• GPT-5.6: Frontier intelligence that scales with your ambition | OpenAI
• Previewing GPT-5.6 Sol: a next-generation model | OpenAI
• GPT-5.6 Preview System Card
• GPT-5.6 in ChatGPT – OpenAI Help Center

JetCache 是阿里巴巴开源的通用缓存访问框架（开源地址），它做了一件事：用统一的 Cache<K, V>接口，把本地内存缓存和远程 Redis 缓存无缝组合起来，再通过注解、API 两种方式定义出标准的缓存协议接入层，让业务代码以最简洁的方式使用缓存。

和 Spring Cache 比，JetCache 的核心优势：

二、核心概念

2.1 Cache 接口

不管你底层用的是 Caffeine（本地内存）、Redis（远程）还是两级缓存组合，业务代码面对的都是同一个接口：

1
2
3
4
5
6
7

public interface Cache<K, V> {
    V get(K key);
    void put(K key, V value);
    boolean remove(K key);
    V computeIfAbsent(K key, Function<K, V> loader);
    // ... 更多方法
}

用起来就像一个 Map，非常直观。

2.2 CacheType — 缓存类型

2.3 Key 的生成规则

最终在 Redis 里存的 key 格式是：

1

Redis key = keyPrefix + keyConvertor(K)；

• keyPrefix：来自 @Cached(name = "toc:user:info:") 中的 name，或 QuickConfig.newBuilder("toc:user:info:") 中的参数。它的作用就是给不同业务的缓存加个”门牌号”，避免 key 冲突。

• keyConvertor：把 Java 对象转成 String。默认用 fastjson2，对 String 类型的 key 直接透传，对复杂对象做 JSON 序列化。

举个例子：@Cached(name = "toc:user:info:", key = "#userId") ，userId = 12345，最终 Redis 里的 key 就是 toc:user:info:12345。

2.4 Area — 缓存区域

Area 是 JetCache 的多租户机制。默认有一个 "default" area，对应配置里的 jetcache.local.default 和 jetcache.remote.default。如果你的项目需要连多个 Redis 实例，可以配多个 area，然后在注解里通过 area = "otherArea" 指定。大多数场景用默认的就行。

三、快速接入（Spring Boot）

第一步：添加 Maven 依赖

根据业务应用的 Redis 客户端，选择对应的 starter（三选一）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<!-- 方式一：Lettuce（推荐，支持异步 API） -->
<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redis-lettuce</artifactId>
    <version>2.8.0</version>
</dependency>

<!-- 方式二：Jedis（经典选择） -->
<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redis</artifactId>
    <version>2.8.0</version>
</dependency>

<!-- 方式三：Redisson（功能丰富） -->
<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redisson</artifactId>
    <version>2.8.0</version>
</dependency>

版本说明：JetCache 2.8+ 需要 JDK 17+、Spring Boot 3.x+、Spring Framework 6.x+。如果你的项目还在 JDK 8，请用 2.7.x 版本。

第二步：配置 application.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

jetcache:
  # 统计间隔（分钟），0 表示不统计，生产建议 15
  statIntervalMinutes: 15
  # key 前缀是否包含 areaName，新项目建议 false
  areaInCacheName: false
  # 反序列化白名单（2.8+ 必须配置）
  decodeFilterAllowPatterns:
    - com.remotecarter.

  # 本地缓存配置
  local:
    default:
      type: caffeine                        # 推荐 caffeine，也可用 linkedhashmap
      limit: 100                            # 每个缓存实例最大元素数
      keyConvertor: fastjson2               # key 转换方式
      expireAfterWriteInMillis: 60000       # 本地缓存默认超时（毫秒）

  # 远程缓存配置
  remote:
    default:
      type: redis.redisson                   # redis / redis.lettuce / redis.redisson
      keyConvertor: fastjson2
      # 广播 channel，用于两级缓存跨节点同步失效
      # 多个服务共用 Redis 时，不同服务用不同 channel，避免广播风暴
      broadcastChannel: crm-user
      valueEncoder: java                    # 序列化：java / kryo / kryo5
      valueDecoder: java
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      host: ${REDIS_HOST:127.0.0.1}
      port: ${REDIS_PORT:6379}
      # 如果用 lettuce，也可以用 uri 方式
      # uri: redis://127.0.0.1:6379/0

第三步：启动类加注解

1
2
3
4
5
6
7
8

@SpringBootApplication
@EnableMethodCache(basePackages = "com.remotecarter")// 激活 @Cached 等注解
@EnableCreateCacheAnnotation                      // 激活 @CreateCache 注解(2.7+ Deprecated可以不加）
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

• @EnableMethodCache(basePackages = "...")：告诉 JetCache 去扫描哪些包下的 Spring Bean，对其中的 @Cached、@CacheUpdate、@CacheInvalidate 等注解做 AOP 代理。basePackages 要覆盖你所有用了缓存注解的包。

• @EnableCreateCacheAnnotation：激活 @CreateCache 注解支持，用于在字段上直接注入 Cache 实例，源码标记 Deprecated 了，可以不加。

至此，接入完成。下面开始介绍怎么用。

四、使用介绍

4.1 注解驱动缓存（声明式）

这是最常用的方式。在 Service 接口（或实现类）的方法上加注解，JetCache 通过 Spring AOP 代理自动处理缓存的读、写、删。

注意：注解可以加在接口方法上，也可以加在类方法上，但被注解的类必须是 Spring Bean。

@Cached — 缓存读取

1
2
3
4
5
6
7
8
9
10

public interface UserService {

    // 指定 name 和 key
    @Cached(name = "toc:user:info:", key = "#uuid", expire = 3600, cacheType = CacheType.REMOTE)
    User getUserById(String uuid);

    // 缓存 null 值（防止缓存穿透）
    @Cached(name = "toc:user:info:", key = "#uuid", expire = 300, cacheNullValue = true)
    User getUserById(String uuid);
}

@Cached — 属性详解

@CacheUpdate — 更新缓存

当数据被修改时，用这个注解直接更新缓存，避免等 TTL 过期：

1
2
3
4
5
6
7
8
9

public interface UserService {

    @Cached(name = "toc:user:info:", key = "#uuid", expire = 3600)
    User getUserById(String uuid);

    // 更新缓存：key 和 name 必须和 @Cached 对应
    @CacheUpdate(name = "toc:user:info:", key = "#user.uuid", value = "#user")
    void updateUser(User user);
}

@CacheInvalidate — 删除缓存

数据被删除时，从缓存中也移除：

1
2

@CacheInvalidate(name = "toc:user:info:", key = "#uuid")
void deleteUser(String uuid);

@CacheUpdate 和 @CacheInvalidate 的共同注意点：它们的 name 和 area 必须和对应的 @Cached 完全一致，这样 JetCache 才知道操作的是哪个缓存。

@CacheRefresh — 自动刷新

这是 JetCache 的特色功能之一。对于加载开销大、实时性要求不高的数据（比如报表汇总），配置自动刷新，防止缓存过期瞬间的并发请求打爆数据库（缓存雪崩）：

1
2
3
4
5
6

public interface SummaryService {

    @Cached(expire = 3600, cacheType = CacheType.REMOTE)
    @CacheRefresh(refresh = 1800, stopRefreshAfterLastAccess = 3600, timeUnit = TimeUnit.SECONDS)
    BigDecimal salesVolumeSummary(int timeId, long categoryId);
}

关键特性：当 cacheType 为 REMOTE 或 BOTH 时，刷新行为是集群全局唯一的——不管有多少台服务器，同时只有一个节点在刷新某个 key，通过分布式锁实现。

@CachePenetrationProtect — 穿透保护

1
2
3

@Cached(expire = 3600, cacheType = CacheType.REMOTE)
@CachePenetrationProtect
User getUserById(long userId);

当缓存未命中时，同一个 JVM 内同一个 key 只有一个线程去加载，其他线程等待结果。防止高并发场景下大量请求同时穿透到数据库。

当前实现是 单机的保护，不是分布式级别的。如果多个节点同时遇到同一个 key 的缓存未命中，各节点会各自加载一次。

我们可以这样组合：自动刷新 + 穿透保护

1
2
3
4

@Cached(name = "toc:user:info:", key = "#uuid", expire = 3600)
@CacheRefresh(refresh = 1800, stopRefreshAfterLastAccess = 3600, timeUnit = TimeUnit.SECONDS)
@CachePenetrationProtect
User getUserById(String uuid);

每 30 分钟自动刷新（集群唯一），30 分钟没人访问就停止刷新，万一缓存未命中还有穿透保护。

4.2 编程式缓存（Cache API）

注解方式虽然简洁，但灵活性有限——比如你需要在运行时动态决定 key，或者想在非 Spring 管理的类中使用缓存。这时候就用 Cache API。

CacheManager + QuickConfig 创建缓存实例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

@Component
public class OrderService implements InitializingBean {

    @Autowired
    private CacheManager cacheManager;

    private Cache<String, OrderDO> orderCache;

    @Override
    public void afterPropertiesSet() {
        QuickConfig qc = QuickConfig.newBuilder("userCache")
            .expire(Duration.ofSeconds(300))
            .cacheType(CacheType.BOTH)    // 两级缓存
            .syncLocal(true)              // 更新时广播失效其他节点本地缓存
            .localLimit(200)              // 本地缓存最大元素数
            .build();
        orderCache = cacheManager.getOrCreateCache(qc);
    }
}

QuickConfig 支持的配置项：

基本操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 读取
UserDO user = userCache.get("toc:user:info:12345");

// 写入
userCache.put("toc:user:info:12345", user);

// 写入并指定超时
userCache.put("toc:user:info:12345", user, 10, TimeUnit.MINUTES);

// 删除
userCache.remove("toc:user:info:12345");

// 批量读取
Map<String, UserDO> users = userCache.getAll(Set.of("toc:user:info:1", "toc:user:info:2", "toc:user:info:3"));

// 批量写入
userCache.putAll(Map.of("toc:user:info:1", o1, "toc:user:info:2", o2));

// 批量删除
userCache.removeAll(Set.of("toc:user:info:1", "toc:user:info:2"));

computeIfAbsent — 缓存未命中时自动加载

这个方法非常实用，相当于 get + put 的原子操作：

1
2
3
4

// 缓存命中直接返回，未命中则调用 loader 加载并写入缓存
OrderDO order = userCache.computeIfAbsent("toc:user:info:12345", key -> {
    return userMapper.selectById(key);  // 从数据库加载
});

也可以在创建缓存时就设置好 loader，这样每次 get 都会自动加载：

1
2
3
4
5
6
7
8
9

// 创建时设置 loader
QuickConfig qc = QuickConfig.newBuilder("userCache")
    .expire(Duration.ofSeconds(300))
    .loader(key -> userMapper.selectById(key))
    .build();
userCache = cacheManager.getOrCreateCache(qc);

// 之后直接 get 就行，未命中会自动调 loader
UserDO user = userCache.get("toc:user:info:12345");

大写 API — 带完整状态码的操作

小写的 get() 返回 null 时，你分不清是”缓存中没有”还是”缓存出错了”。大写 API 返回 CacheGetResult，提供了完整的状态信息：

1
2
3
4
5
6
7
8
9
10
11

CacheGetResult<UserDO> r = userCache.GET("toc:user:info:12345");
if (r.isSuccess()) {
    UserDO user = r.getValue();
    // 处理业务
} else if (r.getResultCode() == CacheResultCode.NOT_EXISTS) {
    // 缓存不存在
} else if (r.getResultCode() == CacheResultCode.EXPIRED) {
    // 缓存已过期
} else {
    // 缓存访问出错（网络异常等）
}

其他大写 API：GET_ALL、PUT、PUT_ALL、REMOVE、REMOVE_ALL、PUT_IF_ABSENT。

异步 API

当使用 Lettuce 客户端时，大写 API 支持真正的异步非阻塞：

1
2
3
4
5
6
7
8

CacheGetResult<UserDO> r = userCache.GET("toc:user:info:12345");
// 此时操作可能还没完成
CompletionStage<ResultData> future = r.future();
future.thenRun(() -> {
    if (r.isSuccess()) {
        System.out.println(r.getValue());
    }
});

注意：小写的 put() 和 removeAll() 没有返回值，在 Lettuce 下会被自动优化为异步调用，减少 RT。但 get() 需要等待结果，所以仍然会阻塞。

五、Key 类型与策略

JetCache 的 key 是怎么生成和处理的，搞清楚这个才能在 Redis 里看到符合预期的 key。

5.1 Redis Key 的拼接规则

1

Redis 中的 key = keyPrefix + keyConvertor(Java Key 对象)

举个例子：

• @Cached(name = "``toc:user:info:``", key = "#``userId``") + userId= 12345（long 类型）

• keyConvertor 把 long 转成 "Long12345"

• 最终 Redis key = toc:user:info:Long12345

如果 key 是 String 类型：

• @Cached(name = "``toc:user:info:``", key = "#uuid") + uuid = "``X123456``"

• keyConvertor 对 String 直接透传

• 最终 Redis key = toc:user:info:X123456

5.2 支持的 Key 类型

从 ExternalKeyUtil.buildKeyAfterConvert 源码可知，JetCache 支持以下 key 类型：

实践建议：推荐使用 String 类型的 key。如果你用 Long/Integer 类型的 key，最终 Redis 里会带个 Long/Integer 前缀，虽然不影响功能，但看起来不直观。在 SpEL 里做一下转换就行：key = "'' + #userId" 或 key = "#userId.toString()"。

5.3 keyConvertor 机制

keyConvertor 负责把 Java 对象转成 Redis 能存的 String：

5.4 SpEL 表达式指定 Key

@Cached 的 key 属性支持 Spring 的 SpEL 表达式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// 直接用参数名（需 javac -parameters 编译）
@Cached(name = "toc:user:info:", key = "#uuid", expire = 3600)
User getUserById(String uuid);

// 按下标访问（不需要 -parameters）
@Cached(name = "toc:user:info:", key = "args[0]", expire = 3600)
User getUserById(String uuid);

// 访问对象属性
@Cached(name = "toc:user:info:", key = "#user.uuid", expire = 3600)
User getUser(User user);

// 字符串拼接
@Cached(name = "toc:user:archives:", key = "#appId + ':' + #uuid", expire = 1800)
List<Archives> getArchives(String appId, String uuid);

注意：使用参数名（如 #userId）需要编译时加 -parameters 参数，否则只能用 args[0] 按下标访问。

Maven 配置：

1
2
3
4
5
6
7

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgument>-parameters</compilerArgument>
    </configuration>
</plugin>

IntelliJ IDEA 配置：Settings → Build → Compiler → Java Compiler → Additional command-line parameters，填入 -parameters。

5.5 单值 vs 多值缓存场景

JetCache 是纯 KV 模型（底层用 Redis STRING 类型），不支持 Redis HASH 的子字段操作（HGET/HSET）。如果你之前用 Redisson 的 RMap 做过 Hash 缓存，迁移到 JetCache 时需要调整思路。

场景：**toc:user:archives:{uuid} 一个用户对应多条 KYC 记录**

Redisson 的做法（Hash 粒度操作）：

1
2
3
4

// Redisson：可以按 kycType 单独读写
RMap<String, String> map = redissonClient.getMap("user:archives:" + uuid);
map.put("archive_real", jsonString);           // HSET
String json = map.get("archive_real");         // HGET

JetCache 的做法（整体缓存）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 方案一：整个 List 作为 value
@Cached(name = "toc:user:archives:", key = "#appId + ':' + #uuid", expire = 30, timeUnit = TimeUnit.MINUTES)
List<ApiArchivesStatus> getAllArchives(String appId, String uuid);

// 按 kycType 查：整体取出后在内存中过滤
public ApiArchivesStatus getByKycType(String appId, String uuid, String kycType) {
    return getAllArchives(appId, uuid).stream()
        .filter(s -> kycType.equals(s.getKycType()))
        .findFirst().orElse(null);
}

// 方案二：Map 作为 value（kycType 作为 Map 的 key）
@Cached(name = "toc:user:archives:", key = "#appId + ':' + #uuid", expire = 30, timeUnit = TimeUnit.MINUTES)
Map<String, ApiArchivesStatus> getArchivesMap(String appId, String uuid);

JetCache 无法做 Hash 字段级操作，需要把「uuid 对应的全部数据」作为一个完整的 value 来缓存。如果业务对子字段粒度读写要求很高，建议保留 Redisson RMap；如果整体读写为主，JetCache 的两级缓存、自动刷新等能力更有价值。

六、两级缓存（BOTH）

两级缓存是 JetCache 的一大亮点，虽然我们暂时用不到。简单来说就是：本地内存缓存（L1）+ Redis（L2）组合使用，读的时候先查 L1 再查 L2，写的时候两级都写。

6.1 工作原理

1
2
3
4
5
6
7
8
9
10
11
12

读取流程：
  1. 查本地缓存（Caffeine/LinkedHashMap）
  2. 本地命中 → 直接返回
  3. 本地未命中 → 查 Redis
  4. Redis 命中 → 回填本地缓存 → 返回
  5. Redis 也未命中 → 返回 NOT_EXISTS

写入流程：
  1. 同时写入本地缓存和 Redis

删除流程：
  1. 同时删除本地缓存和 Redis 中的 key

6.2 配置使用

注解方式：

1
2
3
4
5
6
7

@Cached(name = "toc:user:info:", key = "#uuid", expire = 3600,
    cacheType = CacheType.BOTH,     // 两级缓存
    syncLocal = true,               // 更新时广播失效其他节点本地缓存
    localLimit = 100,               // 本地最大元素数
    localExpire = 60                // 本地缓存 60 秒超时（通常小于远程的 expire）
)
User getUserById(String uuid);

编程方式：

1
2
3
4
5
6
7
8

QuickConfig qc = QuickConfig.newBuilder("userCache")
    .expire(Duration.ofSeconds(3600))
    .cacheType(CacheType.BOTH)
    .syncLocal(true)
    .localLimit(100)
    .localExpire(Duration.ofSeconds(60))
    .build();
Cache<Long, User> userCache = cacheManager.getOrCreateCache(qc);

6.3 syncLocal — 跨节点同步失效

这是两级缓存的关键配置。加入你有 3 台服务器，每台都有本地缓存。如果节点 A 更新了某个用户数据，节点 B 和 C 的本地缓存还是旧值，这就出现了不一致。

syncLocal = true 的解决方式：

1. 节点 A 更新缓存时，向 Redis 的 broadcastChannel 发一条失效消息

2. 节点 B 和 C 订阅了这个 channel，收到消息后清除本地对应的缓存

3. 下次读取时，B 和 C 会从 Redis 拉取最新数据

前提条件：yml 中必须配置了 broadcastChannel。

1
2
3
4

jetcache:
  remote:
    default:
      broadcastChannel: crm-user  # 必须有这个配置

注意：多个服务共用同一个 Redis 时，不同服务请使用不同的 broadcastChannel，否则一个服务的缓存更新会触发其他服务的本地缓存全部失效，造成广播风暴。

6.4 localExpire — 本地和远程过期时间分离

两级缓存场景下，本地缓存的过期时间通常应该 小于 远程缓存。比如远程设 1 小时，本地设 1 分钟，这样即使广播消息丢失，本地最多 1 分钟后也会自动过期重新从 Redis 拉取。

七、序列化配置

远程缓存（Redis）里的数据是字节流，存入时需要 序列化（encode），取出时需要 反序列化（decode）。JetCache 提供了三种序列化方式：

7.1 valueEncoder / valueDecoder 选择

1
2
3
4
5

jetcache:
  remote:
    default:
      valueEncoder: java    # 或 kryo / kryo5
      valueDecoder: java

这里不建议自定义编解码实现，存在造成多级缓存不一致的风险。因为编解码器不一致，会导致 jetcache 广播 start 异常。

7.2 反序列化安全过滤器（2.8+）

JetCache 2.8.x 默认开启了反序列化安全过滤器，只允许白名单中的类被反序列化。这是为了防止反序列化漏洞攻击。默认白名单包含：java.lang、java.util.、java.time.、java.math、com.alicp.jetcache.。

如果你的缓存值包含自定义类（比如 UserDO、OrderDO），必须添加白名单，否则反序列化会报错：

1
2
3
4

jetcache:
  decodeFilterAllowPatterns:
    - com.remotecarter.                    # 前缀匹配：该包及子包下所有类
    - com.remotecarter.UserDto             # 精确匹配：仅这一个类

模式匹配规则：

拒绝列表（内置）包含已知反序列化攻击 gadget chain（Commons Collections、Spring AOP、Hibernate 等），以及 Runtime、ProcessBuilder 等危险类。拒绝列表不可被允许列表覆盖。

也可以通过编程方式配置：

1

DecodeFilter.getDefault().addAllowPatterns("com.yourcompany.");

八、业务接入实战

场景一：单值缓存（用户信息）

最常见的场景——按 ID 查用户，缓存到 Redis。

1
2
3
4
5
6
7
8
9
10
11

public interface UserService {

    @Cached(name = "toc:user:info:", key = "#uuid", expire = 3600, cacheType = CacheType.REMOTE)
    User getUserById(String uuid);

    @CacheUpdate(name = "toc:user:info:", key = "#user.uuid", value = "#user")
    void updateUser(User user);

    @CacheInvalidate(name = "toc:user:info:", key = "#uuid")
    void deleteUser(String uuid);
}

Redis 里的 key 长这样：toc:user:info:X12345。

场景二：多值缓存（Hash 替代方案）

一个用户对应多条 KYC 记录，之前在 Redisson 中用 RMap（Hash）实现，迁移到 JetCache 后用 整体缓存 替代：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// 整个 List 作为一条缓存
public interface ArchivesCacheService {

    @Cached(name = "toc:user:archives:", key = "#appId + ':' + #uuid",
            expire = 30, timeUnit = TimeUnit.MINUTES, cacheType = CacheType.REMOTE)
    List<ApiArchivesStatus> getAllArchives(String appId, String uuid);

    @CacheUpdate(name = "toc:user:archives:", key = "#appId + ':' + #uuid", value = "#list")
    void saveAllArchives(String appId, String uuid, List<ApiArchivesStatus> list);

    @CacheInvalidate(name = "toc:user:archives:", key = "#appId + ':' + #uuid")
    void deleteArchives(String appId, String uuid);
}

// 按 kycType 查询
@Service
public class ArchivesServiceImpl {
    @Autowired
    private ArchivesCacheService archivesCacheService;

    public ApiArchivesStatus getByKycType(String appId, String uuid, String kycType) {
        List<ApiArchivesStatus> list = archivesCacheService.getAllArchives(appId, uuid);
        return list.stream()
            .filter(s -> kycType.equals(s.getKycType()))
            .findFirst()
            .orElse(null);
    }
    
    // 也可以使用 Map
}

场景三：高频读 + 自动刷新（报表汇总）

1
2
3
4
5
6

public interface ReportService {
    @Cached(expire = 7200, cacheType = CacheType.BOTH, syncLocal = true)
    @CacheRefresh(refresh = 1800, stopRefreshAfterLastAccess = 3600, timeUnit = TimeUnit.SECONDS)
    @CachePenetrationProtect
    ReportSummary getReportSummary(String reportId);
}

缓存 2 小时，每 30 分钟自动刷新一次（集群唯一），30 分钟没人访问就停止刷新。本地 + Redis 两级缓存，万一未命中还有穿透保护。

场景四：条件缓存

普通场景下需要根据条件决定是否使用缓存：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 只有 type 为 1 的时候才走缓存
@Cached(name = "data-", key = "#id", expire = 3600, condition = "#type == 1")
DataObject getData(long id, int type);

// 只有结果不为空才缓存
@Cached(name = "data-", key = "#id", expire = 3600, postCondition = "#result != null")
DataObject getData(long id);

// 某个场景下临时禁用缓存（比如数据导出时不能用缓存）
@Cached(name = "data-", key = "#id", expire = 3600, enabled = false)
DataObject getData(long id);

// 在需要缓存的地方激活
public void exportData() {
    CacheContext.enableCache(() -> {
        // 这里的 getData 会走缓存
        DataObject data = getData(123L);
        return data;
    });
}

如果需要通过配置热部署开启 / 关闭缓存：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package com.remotecarter.appuser.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

@Component
@RefreshScope
public class SwitchCache {

    private static volatile boolean *CACHE_ON *= true;

    @Value("${nacos.user.info.cacheOn:true}")
    public void setCacheOn(boolean cacheOn) {
        *CACHE_ON *= cacheOn;
    }

    public static boolean isCacheOn() {
        return *CACHE_ON*;
    }
}

@Cached(name = "toc:user:info:",
        key = "#uuid",
        expire = 3600,
        condition = "T(com.remotecarter.appuser.config.SwitchCache).isCacheOn()")
interface UserInfoDetailDTO queryUserDetail(String uuid);

最佳实践与注意事项

1. TTL 必须设置

@CacheUpdate 和 @CacheInvalidate 可能因为网络波动失败。如果没有设置 TTL，失败的删除/更新操作就会导致缓存永远不一致。一定要设置合理的 expire 作为最终一致性的兜底。

2. 序列化选择

• 开发阶段 / 不确定选啥：用 java，兼容性最好;

• 追求性能：用 kryo，体积小、速度快，但需要注册类;

• JSON 序列化：不推荐。JSON 不是专门的 Java 序列化工具，反射无法识别类型时会反序列化为 JSONObject，兼容性差;

3. broadcastChannel 隔离

多个服务共用同一个 Redis 实例时，不同服务一定要用不同的 broadcastChannel。否则 A 服务更新了缓存，广播消息会触发 B 服务的本地缓存失效——虽然看起来没啥问题，但当广播量大的时候就是灾难。

4. AOP 代理陷阱

JetCache 的注解通过 Spring AOP 代理实现。同一个类内部的方法调用不经过代理，缓存不会生效：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

@Service
public class UserServiceImpl implements UserService {

    public User getUser(long userId) {
        // 这里调用了 getUserById，但缓存不会生效！
        // 因为 this.getUserById() 不经过代理
        return getUserById(userId);
    }

    @Cached(expire = 3600)
    public User getUserById(long userId) {
        return userMapper.selectById(userId);
    }
}

解决办法：通过 @Autowired 注入自己，用注入的实例调用：

1
2
3
4
5
6
7
8
9
10

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserService self;  // 注入代理实例

    public User getUser(long userId) {
        return self.getUserById(userId);  // 经过代理，缓存生效
    }
}

5. -parameters 编译参数

如果想在 SpEL 中用参数名（如 #uuid），编译时必须加 -parameters 参数。否则只能用 args[0] 按下标访问。

6. name 命名规范

name 会作为 Redis key 的前缀，建议：

• 用业务含义明确的名称，如 "toc:user:info:";

• 末尾加 - 或 : 作为分隔符，如 "userCache-12345"

• 不要给不同的 @Cached 注解分配相同的 name + area

7. 本地缓存的内存控制

localLimit 是每个缓存实例的限制，不是全部。如果有 10 个 @CreateCache 创建的缓存实例，每个 limit 100，那本地总共可能有 1000 个元素。大对象场景下要注意控制。

九、FAQ

Q: @Cached 注解加在同类的另一个方法上，为什么没生效？

Spring AOP 基于代理实现，同类内部的方法调用不经过代理。解决方案见上面”最佳实践”第 4 条。

Q: 用了参数名做 key，但缓存没生效？

检查是否配置了 -parameters 编译参数。没有配置的话改用 args[0] 按下标访问。

Q: 升级到 2.8 后反序列化报错？

2.8+ 默认开启了反序列化安全过滤器。需要在 yml 中配置 decodeFilterAllowPatterns 添加你的自定义类所在的包。

Q: 如何同时连接多个 Redis 实例？

配置多个 area：

1
2
3
4
5
6
7
8

jetcache:
  remote:
    default:
      host: redis-host-1
      port: 6379
    second:
      host: redis-host-2
      port: 6380

然后在注解中指定 area：@Cached(area = "second", ...)。

Q: @CacheUpdate / @CacheInvalidate 操作失败了怎么办？

这两个操作可能因网络问题失败。JetCache 不会抛异常，只是静默失败。所以 设置合理的 TTL 是必须的——即使更新/删除失败，缓存也会在 TTL 后自动过期，从数据库重新加载。

Q: 本地缓存和 Redis 数据不一致怎么办？

确保配置了 syncLocal = true 和 broadcastChannel。另外设置一个比 Redis expire 更小的 localExpire，作为兜底——即使广播消息丢失，本地缓存也会在 localExpire 后自动过期。

Q: JetCache 的分布式锁能用吗？

JetCache 的锁是基于 Redis SETNX + TTL 实现的非严格分布式锁，适用于”防止重复执行”的场景。可以用。但目前了解到各域都有自己的分布式锁，建议还是用自己的吧，毕竟 JetCache 核心职责是定义缓存框架协议。

Q：完整配置参考列表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

jetcache:
  # ============ 全局配置 ============
  statIntervalMinutes: 15                    # 统计间隔（分钟），0 = 不统计
  areaInCacheName: false                     # key 前缀是否包含 area，新项目建议 false
  hidePackages: com.remotecarter                # 自动生成 name 时截掉的包名前缀
  useDefaultLocalExpireInMultiLevelCache: false  # BOTH 时是否用本地 builder 的超时

  # ============ 反序列化安全（2.8+） ============
  decodeFilterEnabled: true                  # 总开关
  decodeFilterAllowPatterns:                 # 允许列表
    - com.remotecarter.
  decodeFilterDenyPatterns:                  # 拒绝列表（始终优先于允许列表）
    - com.dangerous.

  # ============ 本地缓存配置 ============
  local:
    default:                                 # area 名称
      type: caffeine                         # caffeine 或 linkedhashmap
      limit: 100                             # 每个缓存实例最大元素数
      keyConvertor: fastjson2                # fastjson2 / jackson / jackson3 / none
      expireAfterWriteInMillis: 60000        # 默认超时（毫秒）
      expireAfterAccessInMillis: 0           # 访问后超时（0 = 不使用）

    # 可以配多个 area
    otherArea:
      type: linkedhashmap
      limit: 50
      keyConvertor: none

  # ============ 远程缓存配置 ============
  remote:
    default:                                 # area 名称
      type: redis.redisson                   # redis / redis.lettuce / redis.redisson / redis.springdata
      keyConvertor: fastjson2                # key 转换
      valueEncoder: java                     # 序列化：java / kryo / kryo5
      valueDecoder: java                     # 反序列化：java / kryo / kryo5
      broadcastChannel: crm-user             # 两级缓存广播 channel（未配置则不开启）

      # --- Jedis / Redisson 连接池配置 ---
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      host: 127.0.0.1
      port: 6379
      # password: xxx                       # 有密码时配置

      # --- Lettuce 连接（二选一） ---
      # uri: redis://127.0.0.1:6379/0

      expireAfterWriteInMillis: 300000       # 默认超时（毫秒）

JD-HotKey 是京东开源的实时热点 key 探测与缓存中间件（开源地址），它做了一件事：在高并发场景下，自动发现热点 key，毫秒级推送到所有应用节点的 JVM 内存中，让热点请求直接在本地内存响应，不再打到 Redis 和数据库。

经典场景：某明星突然官宣，相关商品瞬间涌入海量请求。你事先根本不知道这个商品 ID 会变热，Redis 某个节点被这些请求打得 CPU 飙升——这就是典型的不可预知突发热点。

这时候你就需要 JD-HotKey：它能自动发现这类热点，把数据”镜像”到每台应用服务器的本地内存里，后续请求直接从内存读，RT 从几十毫秒降到 < 1ms。

和直接用本地缓存（比如 Caffeine）比，JD-HotKey 的核心优势：

简单总结：已知的热点用本地缓存就够了，不可预知的热点用 JD-HotKey。

二、核心架构

2.1 整体架构

2.1.1 综合架构

2.1.2 分层架构

系统由四个核心组件构成：

2.2 数据流转过程

整个热点探测的过程就像一条流水线：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

1. 业务请求打到 app，client SDK 对 key 做访问计数
        ↓
   ┌─────────────────────────────────────────────┐
   │  TurnKeyCollector（双 Map 无锁化收集）       │
   │                                             │
   │  Map[0]  ← 偶数次调用写入                    │
   │  Map[1]  ← 奇数次调用写入                    │
   │  AtomicLong 递增 → % 2 → 决定写哪个 Map     │
   │  读写完全隔离，不阻塞业务线程                  │
   └─────────────────────────────────────────────┘
        ↓
2. client 每隔 500ms 将其中一个 Map 的数据批量上报给 worker
   （读一个 Map 时，写操作在另一个 Map 进行，互不影响）
        ↓
3. worker 汇聚所有 app 节点的数据，执行热点判定算法
        ↓
4. 某 key 在时间窗口内的总访问次数 >= 阈值 → 判定为热点
        ↓
5. worker 通过 etcd watch 机制，将热点 key 实时推送给所有客户端
        ↓
6. 客户端收到通知，将热点数据缓存到本地内存（Caffeine）
        ↓
7. 后续请求直接走本地缓存，不再访问 Redis / DB
        ↓
8. 当 key 不再热门 → worker 通知客户端移除本地缓存，释放内存

关键设计：集中计算。你可能会想，为什么不直接在每个客户端本地判断热点？因为分布式场景下，单机请求是分散的——一个 key 在 100 台机器上每台只被访问了 5 次，单看任何一台都不算热，但汇总起来有 500 次。必须由 worker 集中汇总计算，才能准确识别全局热点。

Worker 内部处理流程：worker 收到 client 上报的数据后，经过一条责任链处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Netty 收到消息
    ↓
HeartBeatFilter（心跳消息直接处理）
    ↓
AppNameFilter（解析客户端 App 名称）
    ↓
HotKeyFilter（排除白名单 key，有效数据入队）
    ↓
KeyCounterFilter（统计数据处理）
    ↓
LinkedBlockingQueue（容量 200 万，削峰缓冲）
    ↓
KeyConsumer 多线程消费 → SlidingWindow.addCount() → 判定热点
    ↓
热点 key → 写入 etcd + 推送到所有 Client（每 10ms 批量推送）

Worker 内部还有一个 hotCache（Caffeine 实现，5 秒 TTL），用来防抖——同一个 key 在 5 秒内不会重复推送，避免热点持续触发时产生大量无效推送。

2.3 etcd 的角色

etcd 在这个系统里承担了三个职责：

1. 规则存储：你在 dashboard 配置的热点规则（哪个 key 前缀、阈值多少、窗口多大），都持久化在 etcd 中。worker 和 client 通过 watch etcd 来感知规则变化。

2. worker 注册：每个 worker 启动时把自己的 IP 注册到 etcd，client 通过读 etcd 知道该连哪些 worker。

3. 热点推送中转：worker 判定出热点 key 后，写入 etcd 并设置 TTL 过期时间；客户端 watch 对应的 etcd 路径，收到变更事件后立即更新本地缓存。

一个巧妙的设计：etcd 原生支持 key 的 TTL 自动过期删除。热点 key 写入 etcd 时设一个过期时间（比如 60 秒），过期后 etcd 自动删除，删除事件通过 watch 回调通知所有 client 清除本地缓存。这样就实现了热点 key 的自动淘汰，不需要额外的清理逻辑。

为什么选 etcd 而不是 ZooKeeper？ etcd 原生支持 key TTL 自动删除（ZooKeeper 不支持），性能更高，资源占用更少，API 风格也更现代（基于 gRPC）。

etcd 版本要求：3.4.x 及以上。

2.4 滑动窗口算法

这是热点判定的核心算法。JD-HotKey 用的是双缓冲 Map实现滑动窗口：

1
2
3
4
5
6
7
8
9

Worker 内部的双 Map 机制：

  ┌─────────────────────────────────────────────────┐
  │  Map[0]（写 Map） ← 当前时间片，接收新 key 上报   │
  │  Map[1]（读 Map） ← 上一时间片，被消费线程读取统计 │
  │                                                 │
  │  AtomicLong 递增 → % 2 → 决定当前写哪个 Map      │
  │  读写分离 → 永不阻塞 → 高并发吞吐                 │
  └─────────────────────────────────────────────────┘

• 双 Map 交替：一个 Map 负责写入新上报的数据，另一个负责读取统计和清理。通过 AtomicLong 取模 2 切换读写对象，完全无锁设计
• 读写不阻塞：消费线程在统计 Map[0] 时，写入线程往 Map[1] 写数据，互不干扰
• 演进历史：最初用的是 Disruptor，但在实际高并发中发现会导致个别数据延迟且空耗 CPU，后来换成了 LinkedBlockingQueue + 读写分离锁的方案，性能反而更稳定

Key 的 Hash 分发：client 上报数据时，会对 key 做 Hash 计算（hash(key) % workerCount），同一个 key 始终路由到同一个 worker。这样保证了某个 key 的所有统计数据集中在一个 worker 上，不需要跨 worker 聚合。worker 之间也互不通信，各自独立计算。

2.5 JdHotKeyStore — 核心 API

JdHotKeyStore 是 client SDK 提供的核心操作类，只有 4 个静态方法：

注意区分这几个方法的行为差异，很多人刚接触时会搞混：

1
2
3
4

isHotKey(key)  → 返回 true/false，同时上报 key 的访问量（计数 +1）
get(key)       → 只从本地缓存读值，不上报
smartSet(key, value) → 只在该 key 是热点时才写入本地缓存（非热点写入会被忽略）
getValue(key)  → 读值 + 上报（如果本地没值，返回 null，同时上报）

一个内部细节：当 worker 推送热点通知到 client 时，client 会先在 Caffeine 中存入一个魔术值（0x12fcf76）作为占位标记，表示”这个 key 已经是热点了，但还没填入实际业务数据”。所以 get(key) 可能返回这个魔术值或者 null——说明热点标记已生效，但数据还没被 smartSet 填进去，你需要自己加载数据并写入。

Caffeine 分桶设计：client 内部不是用一个 Caffeine 实例存所有热点 key，而是按过期时间（duration）分桶——相同过期时间的 key 共享同一个 Caffeine 实例。这样不同规则下的热点 key 可以有不同的 TTL，互不干扰。

三、快速接入（Spring Boot）

第一步：部署基础环境

JD-HotKey 依赖 etcd，部署前需要先准备好 etcd 集群。

安装 etcd（开发环境）

1
2
3
4
5
6
7
8

# Docker 方式（快速启动单节点）
docker run -d --name etcd \
  -p 2379:2379 \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  bitnami/etcd:3.4

# 验证连接
docker exec etcd etcdctl endpoint health

部署 worker

worker 是独立部署的 Java 进程，负责聚合计算。

1
2
3
4
5
6
7
8
9

# 从源码编译
cd worker
mvn clean package -DskipTests

# 启动 worker（关键参数）
java -jar worker/target/worker.jar \
  --etcd=http://127.0.0.1:2379 \
  --threads=16 \
  --workerPath=/jd/hotkey/worker

部署 dashboard

dashboard 是 Web 管理控制台，需要连接 MySQL 和 etcd。

1
2
3
4
5
6
7

# 1. 创建数据库，执行 db.sql 初始化脚本
# 2. 修改 application.yml 中的数据库和 etcd 配置
# 3. 启动
java -jar dashboard.jar

# 访问 http://localhost:8081
# 默认管理员账号按 README 说明配置

第二步：引入 Maven 依赖

1
2
3
4
5

<dependency>
    <groupId>com.jd.platform.hotkey</groupId>
    <artifactId>hotkey-client</artifactId>
    <version>0.0.4-SNAPSHOT</version>
</dependency>

依赖冲突注意：

• 如果项目中有 guava，需要升级到 28.2-jre 以上
• 如果项目中有 fastjson，需要降到 1.2.70（hotkey-client 内部使用的版本）
• 通信协议用的 protobuf，注意版本兼容

第三步：初始化客户端

在 Spring Boot 启动时初始化 client，连接到 etcd 并启动数据管道：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@Component
public class HotKeyConfig {

    @Value("${etcd.server}")
    private String etcdServer;

    @Value("${spring.application.name}")
    private String appName;

    @PostConstruct
    public void init() {
        ClientStarter starter = new ClientStarter.Builder()
                .setAppName(appName)          // 应用名，和 dashboard 中的配置对应
                .setEtcdServer(etcdServer)    // etcd 集群地址
                .build();
        starter.startPipeline();
    }
}

ClientStarter.Builder 支持的配置项：

第四步：配置热点规则

在 dashboard 中配置你的热点规则。规则以 JSON 格式存储，支持以下参数：

1
2
3
4
5
6
7
8

{
    "desc": "商品信息热点规则",
    "key": "goods:",
    "prefix": true,
    "threshold": 100,
    "duration": 5,
    "interval": 1
}

上面的配置含义：以 goods: 开头的 key，在 5 秒内被访问超过 100 次，判定为热点。

四、使用介绍

4.1 场景一：热点拦截 + 限流

最简单的用法——判断是否热点，是的话做特殊处理（降级、限流或直接返回）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

@RestController
public class GoodsController {

    @GetMapping("/goods/{id}")
    public Object getGoods(@PathVariable String id) {
        String key = "goods:" + id;

        // isHotKey 会同时上报 key 的访问量
        if (JdHotKeyStore.isHotKey(key)) {
            // 热点 key 的降级处理：直接返回缓存数据或友好提示
            return "当前访问量大，请稍后再试";
        }

        // 非热点 key 走正常流程
        return goodsService.getGoodsDetail(id);
    }
}

4.2 场景二：热点数据本地缓存（推荐）

更实用的方式——检测到热点后，把数据缓存到本地内存，后续请求直接从内存读：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

@Service
public class GoodsService {

    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    @Autowired
    private GoodsMapper goodsMapper;

    public GoodsDetail getGoodsDetail(String goodsId) {
        String key = "goods:" + goodsId;

        // 1. 判断是否热点
        if (JdHotKeyStore.isHotKey(key)) {
            // 2. 先尝试从本地缓存读取
            GoodsDetail cached = (GoodsDetail) JdHotKeyStore.get(key);
            if (cached != null) {
                return cached;
            }
            // 3. 本地没有，从 Redis 加载
            GoodsDetail goods = loadFromRedis(goodsId);
            if (goods != null) {
                // 4. 写入本地热点缓存（只有 key 是热点时才会写入成功）
                JdHotKeyStore.smartSet(key, goods);
            }
            return goods;
        }

        // 5. 非热点 key，正常走 Redis
        return loadFromRedis(goodsId);
    }

    private GoodsDetail loadFromRedis(String goodsId) {
        GoodsDetail goods = (GoodsDetail) redisTemplate.opsForValue().get("goods:" + goodsId);
        if (goods == null) {
            goods = goodsMapper.selectById(goodsId);
            if (goods != null) {
                redisTemplate.opsForValue().set("goods:" + goodsId, goods, 300, TimeUnit.SECONDS);
            }
        }
        return goods;
    }
}

这里的 smartSet 很巧妙：它只在 key 已被判定为热点时才写入本地缓存。如果 key 不是热点，写入会被忽略——不用担心内存被非热点数据撑爆。

4.3 场景三：用 getValue 简化逻辑

getValue 把”查本地缓存 + 上报”合并成了一步，代码更简洁：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public GoodsDetail getGoodsDetail(String goodsId) {
    String key = "goods:" + goodsId;

    // getValue 自动处理：本地有值返回值 + 上报访问量
    GoodsDetail cached = (GoodsDetail) JdHotKeyStore.getValue(key);
    if (cached != null) {
        return cached;
    }

    // 本地没有（可能刚变热点还没缓存数据），从 Redis 加载并写入
    GoodsDetail goods = loadFromRedis(goodsId);
    if (goods != null) {
        JdHotKeyStore.smartSet(key, goods);
    }
    return goods;
}

4.4 场景四：热用户 / 热接口探测

JD-HotKey 不只局限于数据 key，也能探测热用户和热接口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// 热用户探测（防爬虫 / 防刷子）
public void handleRequest(String userId) {
    if (JdHotKeyStore.isHotKey("hot:user:" + userId)) {
        // 该用户访问频率异常，触发限流或验证码
        log.warn("检测到异常高频用户: {}", userId);
        throw new RateLimitException("访问过于频繁，请稍后再试");
    }
    // 正常业务逻辑...
}

// 热接口探测
public void handleApiCall(String apiPath) {
    if (JdHotKeyStore.isHotKey("hot:api:" + apiPath)) {
        // 接口被大量请求，触发熔断或降级
        log.warn("接口被高频访问: {}", apiPath);
        return fallbackResponse;
    }
    // 正常业务逻辑...
}

在 dashboard 中配置对应的规则就行：key = "hot:user:" 和 key = "hot:api:"。

五、性能数据

5.1 Worker 性能演进

JD-HotKey 的性能不是一蹴而就的，从初版到最终版经历了 17 倍 的提升：

最大的性能跃升来自序列化方案的切换：从 Fastjson 换为 Protobuf 后，序列化效率显著提升，CPU 使用率反而下降了。

5.2 推送性能

5.3 生产实战数据

对比一下：普通请求访问 Redis 的 RT 通常在 1-5ms，访问数据库 5-50ms。JD-HotKey 让热点请求直接从 JVM 内存读取，RT 降到纳秒级。

六、与同类方案对比

什么时候该用 JD-HotKey？

• 突发热点：热搜、突发新闻、秒杀商品——你没法提前知道哪些 key 会变热
• 大促场景：618、双11，热点模式不可预测
• 全站热点保护：不想人工分析哪些 key 是热点，交给系统自动发现
• 热用户 / 热接口探测：防爬虫、防刷子

什么时候不需要 JD-HotKey？

• 热点数据固定且已知：直接用 Caffeine 或 JetCache BOTH 就够了
• 数据量不大，Redis 压力不大：没必要引入额外组件
• 团队运维能力有限：etcd 集群的部署和维护有学习成本

七、最佳实践与注意事项

7.1 阈值调优

阈值设太低 → 太多 key 被判定为热点 → 本地内存撑爆；阈值设太高 → 热点漏判 → Redis 被打。

建议：

• 核心业务（如商品详情）：阈值设低一点（如 5 秒内 50 次）
• 边缘业务：阈值设高一点（如 5 秒内 200 次）
• 通过 dashboard 配置分级阈值，不同业务用不同规则

7.2 内存控制

smartSet 存入的热点数据占用的是应用 JVM 内存。注意：

• CaffeineSize 默认 200000，根据单机内存和数据大小调整
• 大对象场景下（如完整的商品详情 JSON），适当减小容量
• 热点 key 过期后会自动从本地缓存移除，不需要手动清理

7.3 etcd 集群容灾

etcd 是核心依赖，但 client 有容灾设计：

• etcd 短暂不可用时，已推送的热点数据仍然在本地缓存中正常工作
• 只是新的热点判定和规则变更无法生效
• 建议 etcd 至少 3 节点部署，保证高可用

7.4 依赖冲突处理

这是接入时最常踩的坑：

建议：引入依赖后先跑一遍单元测试，确认没有类冲突。特别注意 guava 和 fastjson 版本，这两个最容易出问题。

7.5 配合降级策略

热点探测不是万能的，建议配合降级策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public GoodsDetail getGoodsDetail(String goodsId) {
    String key = "goods:" + goodsId;

    try {
        if (JdHotKeyStore.isHotKey(key)) {
            GoodsDetail cached = (GoodsDetail) JdHotKeyStore.get(key);
            if (cached != null) {
                return cached;
            }
        }
    } catch (Exception e) {
        // hotkey 组件异常时降级到普通流程
        log.warn("hotkey 判断异常，降级处理", e);
    }

    // 正常流程：Redis → DB
    return loadFromRedis(goodsId);
}

7.6 监控告警

建议监控以下指标：

• 热点 key 数量：突增可能意味着异常流量
• 热点 key 变化趋势：发现异常模式
• worker 健康状态：etcd 中 worker 注册是否正常
• client 上报延迟：是否因为网络问题导致上报积压

八、FAQ

Q: worker 和 server 是什么关系？

JD-HotKey 中，worker 就是实际干活的服务节点。有些文章叫它”server”，其实是一个东西。worker 接收 client 上报的数据，执行热点判定，推送结果。它独立部署，不依赖 Spring Boot，是个纯 Java 进程。

Q: 一个 etcd 集群可以支撑多少个应用？

理论上不限，但建议按业务域隔离。不同应用用不同的 appName，规则互不影响。大规模场景下建议 etcd 独立集群部署。

Q: isHotKey 每次调用都会上报吗？

是的，isHotKey 每次调用都会在 client 本地的双 Map 中计数 +1。client 每隔 pushPeriod（默认 500ms）将聚合后的数据批量上报给 worker。所以不是每次调用都发网络请求，是批量聚合后上报，开销很小。

Q: worker 的吞吐量怎么评估？

worker 内部用 LinkedBlockingQueue（容量 200 万）做消息缓冲，多线程消费。经验数据：1 台 16 核 worker 可以支撑约 1000 台业务服务。大促期间如果需要扛百万级热 key，大约需要 30 台 worker。

Q: smartSet 和直接用 Caffeine 存有什么区别？

smartSet 内部用的也是 Caffeine，但它有个关键区别：只有 key 被判定为热点时才会写入成功。如果你直接用 Caffeine，所有 key 都会缓存，内存可能被非热点数据占满。smartSet 帮你做了这个过滤。

另外还有个 forceSet 方法可以强制设置缓存值（不管 key 是否热点），一般用不到。

Q: 热点 key 被判定后，数据怎么填充到本地缓存？

JD-HotKey 只负责告诉你”这个 key 是热点”和”管理本地缓存的存取”，不负责帮你从数据库加载数据。你需要在代码中自己实现数据加载逻辑（见场景二的示例代码）。

完整流程是这样的：

1. worker 判定热点 → 推送通知到所有 client
2. client 在 Caffeine 中存入魔术值（0x12fcf76）作为占位
3. 业务代码调用 isHotKey(key) 返回 true
4. 业务代码调用 get(key) → 返回 null（因为是魔术值占位，还没填实际数据）
5. 业务代码从 Redis / DB 加载真实数据
6. 调用 smartSet(key, value) 写入本地缓存
7. 后续请求直接命中本地缓存

Q: 和 Redis Cluster 的热点 key 问题有什么关系？

Redis Cluster 的热点 key 问题是：某个 key 的访问量集中到一个分片节点，导致该节点 CPU / 带宽打满。JD-HotKey 的解决思路是在应用层就把热点请求拦截掉——数据缓存在 JVM 内存中，根本不会打到 Redis。两者是不同层面的解决方案。

Q: 生产环境怎么部署？

推荐架构：

• etcd：3 节点集群（奇数，容忍 1 节点故障）
• worker：至少 2 个实例（worker 之间不通信，各自独立计算。client 通过 Hash 将不同 key 路由到不同 worker，天然负载均衡）
• dashboard：1-2 个实例（Web 控制台，不承载核心流量）
• client：嵌入每个业务应用实例

Q: 和 JetCache 的两级缓存（BOTH）怎么配合？

它们不冲突，可以一起用：

• JetCache BOTH：适用于已知的高频读数据，提供 L1 + L2 两级缓存 + 自动刷新
• JD-HotKey：适用于不可预知的突发热点，自动发现并缓存

配合方式：JetCache 负责常规缓存，JD-HotKey 负责突发热点保护。当 JD-HotKey 判定某 key 为热点时，数据直接走 JVM 内存，连 JetCache 的 L2（Redis）都不需要访问。

九、总结

JD-HotKey 的核心价值在于自动发现热点——这是它区别于其他缓存方案的最大优势。你不需要提前知道哪些 key 会变热，系统会根据实际访问量自动判定、自动推送、自动过期释放。

如果你的业务中存在”不知道什么时候会突然变热”的场景（电商秒杀、热搜话题、突发新闻），JD-HotKey 能帮你自动识别并保护这些热点 key，将请求拦截在 JVM 内存中，避免打垮 Redis 和数据库。

但它也不是万能的——etcd 的部署运维、依赖冲突的处理、阈值的调优，都需要一定的投入。建议先在非核心业务上试水，验证效果后再推广到核心链路。

当系统从单个 Agent 进化到多个 Agent 协作时，一个核心问题就会浮出水面：Agent 之间怎么通信？

通信设计直接决定了你的 Multi-Agent 系统是高效协作还是混乱互怼。

打个比方：单个 Agent 像一个独立工作的程序员，能力再强也有天花板。Multi-Agent 就像一个开发团队——你需要设计好团队的沟通机制：谁向谁汇报？用什么格式交流？出了问题怎么兜底？这些决策决定了团队是 1+1>2 还是 1+1<0。

这篇文章会系统性地拆解 Multi-Agent 通信的三个核心维度：拓扑（谁跟谁聊）、机制（数据怎么流）、协议（聊什么格式）**，并深入分析工程落地中的失败模式和成本控制。

一、本质问题

Multi-Agent 的通信，本质上不是”数据包交换”，而是”认知语义的传递”与”任务状态的对齐”。

传统分布式系统里，通信关心的是：HTTP 还是 gRPC？JSON 还是 Protobuf？超时时间设多少？这些当然重要，但在 Multi-Agent 系统里，它们只是基础设施层面的问题。

真正让 Multi-Agent 通信变得独特且困难的，是以下三个问题：

比如：当 Agent A 告诉 Agent B “这个 Bug 很严重”时，B 需要理解的不只是”严重”这两个字，还包括 A 判断严重的依据、影响的范围、以及 A 对修复难度的预判。这种心智模型的传递，是传统 RPC 调用里不存在的。

基于这一点，我们再来看具体的通信设计。

二、通信拓扑：谁跟谁聊？

拓扑设计是架构的第一个决策。它决定了系统的耦合度、容错性和扩展上限。

2.1 中心化编排（Orchestrator / Supervisor）

这是最常见的模式，也最容易理解和实现。

1
2
3
4
5
6
7
8
9
10
11

            ┌─────────────────┐
            │  Supervisor Agent│
            │  （任务调度中心）  │
            └───┬────┬────┬───┘
                │    │    │
       ┌────────┘    │    └────────┐
       ▼             ▼             ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Researcher │ │  Coder     │ │  Reviewer  │
│   Agent    │ │   Agent    │ │   Agent    │
└────────────┘ └────────────┘ └────────────┘

核心逻辑：一个 Supervisor 负责接收任务、拆解子任务、分配给 Worker Agent、收集结果并汇总。Worker 之间不直接通信，所有信息流都经过 Supervisor 中转。

生活类比：这就像一个项目经理带团队。需求先交给 PM，PM 拆分任务分给开发、测试、设计，最后由 PM 汇总交付。开发人员不需要直接跟测试沟通——PM 是信息枢纽。

优势：

• 逻辑清晰：控制流一目了然，容易调试
• 可观测性强：Supervisor 知道全局状态，方便监控和日志
• 易于加入 Human-in-the-loop：人类可以在 Supervisor 层做审批

致命缺陷：

• 单点瓶颈：Supervisor 挂了，整个系统瘫痪
• 性能天花板：所有通信都经过 Supervisor，吞吐量受限
• 上下文爆炸：Supervisor 需要维护所有 Worker 的状态，上下文窗口压力巨大

适用场景：任务流程明确、Agent 数量较少（3-5 个）的场景。比如”搜索 → 分析 → 生成报告”这种线性流水线。

2.2 去中心化协作（Peer-to-Peer / 群聊模式）

所有 Agent 地位平等，直接互相通信，没有中心节点。

1
2
3
4
5
6
7

┌────────────┐     ┌────────────┐
│  Agent A   │◄───►│  Agent B   │
└─────┬──────┘     └─────┬──────┘
      │                   │
      │    ┌────────────┐ │
      └───►│  Agent C   │◄┘
           └────────────┘

核心逻辑：每个 Agent 都能发起对话、响应请求、推荐下一个处理者。没有谁是”老板”，大家通过协商决定谁来干活。

生活类比：这像一个开源项目的维护者社区。每个人都能提 Issue、Review PR、Merge 代码，没有绝对的上下级关系。

优势：

• 扩展性强：新增 Agent 不需要修改中心节点
• 灵活路由：Agent 之间可以动态发现、动态协作
• 无单点故障：某个 Agent 挂了，其他 Agent 可以继续工作

致命缺陷：

• 无限循环风险：A 让 B 做，B 觉得该 C 做，C 又踢回给 A → 死循环
• 上下文爆炸：群聊消息指数级增长，每个 Agent 都要维护所有对话历史
• 收敛性差：没有”裁判”，很难判断任务什么时候算完成

防循环的工程手段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 设置最大轮次
groupchat = GroupChat(max_round=10)

# 2. 加入"终止条件"检测
def should_terminate(messages):
    last_msgs = messages[-3:]
    # 如果最近 3 条消息都在重复相同观点，终止
    return len(set(m["content"] for m in last_msgs)) == 1

# 3. 引入"主持人"角色做仲裁
moderator = AssistantAgent(
    name="Moderator",
    system_message="你是讨论主持人。当讨论陷入循环时，做出最终决策。"
)

适用场景：头脑风暴、多角色辩论、代码审查等需要多视角碰撞的场景。

2.3 层次化混合（Hierarchical）

现实中的大型系统，往往是两者的结合——分层。

1
2
3
4
5
6
7
8
9
10
11
12
13

      ┌───────────────┐
      │   CEO Agent   │
      │  （战略规划）   │
      └───┬───────┬───┘
          │       │
┌─────────▼─┐   ┌─▼──────────┐
│ VP-研发    │   │ VP-运营     │
│ （中层管理）│   │ （中层管理） │
└──┬────┬───┘   └──┬────┬────┘
   │    │           │    │
 ┌─▼─┐┌─▼─┐      ┌─▼─┐┌─▼─┐
 │Dev││QA │       │Mkt││CS │
 └───┘└───┘       └───┘└───┘

核心逻辑：顶层 Agent 做任务拆解和战略规划，中层 Agent 做子任务协调，底层 Agent 执行具体操作。每层只跟相邻层直接通信。

生活类比：这就是公司的组织架构。CEO 定方向，VP 拆目标，一线执行。你不会希望 CEO 直接管到实习生——层级是管理复杂度的利器。

关键设计原则：

适用场景：大型企业级系统，如金融风控（合规层 → 策略层 → 执行层）、智能客服（路由层 → 业务层 → 工具层）。

2.4 三种拓扑对比

三、通信机制：数据怎么流动？

拓扑解决的是”谁跟谁聊”，机制解决的是”数据怎么从 A 到 B”。

3.1 基于共享状态（State-Based）

这是 LangGraph 的核心设计哲学，也是目前最流行的方案。

核心思想：Agent 之间不直接发送消息，而是共同读写一个全局状态对象。前一个 Agent 更新状态，后一个 Agent 读取状态变化，间接完成通信。

1
2
3
4
5
6
7
8

┌──────────┐       ┌──────────────┐       ┌──────────┐
│ Agent A  │──写──►│  Global State │◄──读──│ Agent B  │
└──────────┘       │  {            │       └──────────┘
                   │   task: "...", │
┌──────────┐       │   result: "...",│      ┌──────────┐
│ Agent C  │──写──►│   status: "..."│◄──读──│ Agent D  │
└──────────┘       │  }            │       └──────────┘
                   └──────────────┘

生活类比：想象一个共享的 Google Docs。团队成员不需要开会讨论，直接打开文档看最新内容，需要修改就直接编辑。文档本身就是通信媒介。

优势：

注意事项：

• 状态冲突：如果两个 Agent 并发修改同一字段，需要冲突解决策略（如 last-write-wins、merge 函数）
• 状态膨胀：长时间运行的任务，状态会越来越大，需要定期压缩或归档

3.2 基于消息队列（Message Queue / Event Bus）

当你的 Agent 系统需要跨语言、跨进程、跨机器通信时，共享状态就不够用了。这时候需要引入消息中间件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

┌───────────┐                    ┌───────────┐
│ Python     │                    │ Java       │
│ Research   │                    │ Recommend  │
│ Agent      │                    │ Agent      │
└─────┬──────┘                    └─────┬──────┘
      │ 发布                             │ 订阅
      ▼                                 ▼
┌───────────────────────────────────────────────┐
│              消息队列 / 事件总线                 │
│         (Kafka / RabbitMQ / Redis Streams)    │
│                                               │
│  Topic: research.results                      │
│  Topic: recommendation.requests               │
│  Topic: code.generation.tasks                 │
└───────────────────────────────────────────────┘
      ▲                                 ▲
      │ 订阅                             │ 发布
┌─────┴──────┐                    ┌─────┴──────┐
│ Python     │                    │ Python     │
│ Coder      │                    │ Summarizer │
│ Agent      │                    │ Agent      │
└────────────┘                    └────────────┘

生活类比：这像公司的邮件系统 + 公告板。你需要别的团队配合时，发邮件（发布消息）到对方的收件箱（Topic），对方在自己方便的时候查看并处理（异步消费）。不需要面对面沟通。

与共享状态的核心区别：

3.3 基于共享向量记忆（Shared Memory / RAG）

这是一种隐式通信方式：Agent 之间不直接交换数据，而是通过一个共享的向量知识库来间接协作。

1
2
3
4
5
6
7
8
9
10
11

┌──────────┐                    ┌──────────┐
│ Agent A  │──向量化写入────────│ 向量数据库 │
│(信息生产者)│                   │(共享记忆)  │
└──────────┘                    └─────┬────┘
                                      │
                                语义检索 │
                                      │
                                ┌─────▼────┐
                                │ Agent B  │
                                │(信息消费者)│
                                └──────────┘

核心逻辑：Agent A 将中间推理结果、观察到的事实、学到的经验向量化后存入向量库。Agent B 在需要时，通过语义检索主动”拉取”相关信息。

生活类比：这像公司的知识库（Confluence / Notion）。前人在项目结束后把经验写成文档，后来的人遇到类似问题时去搜索，找到相关文档后借鉴。写文档的人和读文档的人不需要直接沟通。

适用场景：

• 长期记忆：Agent 需要记住之前学到的东西
• 跨任务知识复用：不同任务之间共享经验
• 隐式协作：Agent 之间不需要实时交互，各自独立工作

关键设计点：

四、通信协议：聊什么格式？

拓扑和机制解决的是”通道”问题，协议解决的是”内容”问题——Agent 之间传什么格式的消息，才能确保对方准确理解？

4.1 纯文本通信（最原始，也最脆弱）

1
2
3
4
5

# Agent A 发给 Agent B 的消息
message = "帮我查一下这个 Bug，我觉得可能是数据库连接池的问题，你看看是不是 max_connections 设太小了"

# Agent B 收到的就是这段自然语言，需要自己解析意图
# 问题：B 怎么知道 A 是要"查询"还是"修复"？"我觉得"说明 A 的置信度不高？

问题：

• 意图不明确（是要查询？修复？还是只是讨论？）
• 没有结构，下游 Agent 解析困难
• 无法传递置信度、优先级等元信息

4.2 结构化工具调用（Structured Tool Call）

这是目前业界的主流做法。把 Agent 之间的通信标准化为函数调用格式，充分利用 LLM 原生的 Function Calling 能力。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "tool_call_id": "call_abc123",
  "name": "delegate_to_agent",
  "arguments": {
    "target_agent": "code_reviewer",
    "task_type": "review",
    "payload": {
      "code": "def calculate_price(...): ...",
      "review_focus": "security",
      "priority": "high"
    },
    "context": {
      "parent_task": "修复价格计算的安全漏洞",
      "requester_agent": "code_generator",
      "deadline": "5min"
    }
  }
}

核心优势：

• 意图明确：name 字段直接说明要做什么
• 参数结构化：下游 Agent 不需要”猜”参数
• 可追踪：tool_call_id 让每次调用都可溯源
• LLM 原生支持：直接利用 Function Calling，不需要额外的解析层

4.3 心智模型传递（Theory-of-Mind / CoT 共享）

这是进阶玩法。不只要传递”结果”，还要传递”推理过程”和”置信度”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "from": "research_agent",
  "to": "decision_agent",
  "content": "推荐使用 Redis 作为缓存层",
  "reasoning": {
    "steps": [
      "分析了数据访问模式：读多写少，比例约 100:1",
      "评估了数据一致性要求：允许秒级延迟",
      "对比了 Redis 和 Memcached：Redis 支持更丰富的数据结构",
      "考虑了团队技术栈：后端团队有 Redis 使用经验"
    ],
    "assumptions": [
      "日活用户不超过 100 万",
      "缓存数据不需要强一致性"
    ],
    "alternatives_considered": [
      {"option": "Memcached", "rejected_reason": "数据结构支持有限"},
      {"option": "本地缓存", "rejected_reason": "多实例部署，本地缓存无法共享"}
    ]
  },
  "confidence": 0.82,
  "risk_assessment": {
    "level": "low",
    "details": "Redis 单点故障风险可通过 Sentinel 解决"
  }
}

为什么这很重要？

因为下游 Agent 需要根据置信度来决定下一步行动：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

def decision_agent(received_message):
    confidence = received_message["confidence"]

    if confidence >= 0.8:
        # 高置信度，直接采纳
        return execute(received_message["content"])
    elif confidence >= 0.5:
        # 中等置信度，交给另一个 Agent 复核
        return delegate_to("reviewer_agent", received_message)
    else:
        # 低置信度，要求重新调研
        return delegate_to("research_agent", {
            "action": "redo_research",
            "feedback": received_message["reasoning"]
        })

生活类比：这像医生会诊。一个医生不能只说”我觉得是肺炎”，他需要说”基于 X 光片和血常规结果（推理依据），我有 80% 的把握是肺炎（置信度），但也考虑了支气管炎的可能性（备选方案），建议再做 CT 确认（下一步建议）”。

4.4 标准化 Agent 协议（A2A / MCP）

目前最重要的行业趋势之一：Agent 通信协议的标准化。

两个值得关注的协议：

MCP 解决的是：Agent 怎么调用外部工具和数据源。它定义了一套标准接口，让不同的 LLM 应用能以统一方式访问工具，类似于 USB-C 之于外设。

A2A 解决的是：不同平台、不同供应商的 Agent 之间怎么互通。它定义了 Agent Card（能力描述）、Task（任务生命周期）、Artifact（产出物）等标准对象。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

A2A 协议核心对象：

Agent Card:
  - name: "代码审查 Agent"
  - skills: ["code_review", "security_audit"]
  - endpoint: "https://api.example.com/a2a"

Task:
  - id: "task-123"
  - status: "submitted" → "working" → "completed" / "failed"
  - messages: [输入消息列表]
  - artifacts: [输出产物列表]

Artifact:
  - type: "code_review_result"
  - content: {...}
  - metadata: {...}

为什么标准化很重要？

想象一下这个场景：你的公司用 LangChain 写了 5 个 Agent，合作伙伴用 AutoGen 写了 3 个 Agent，供应商用自研框架写了 2 个 Agent。如果没有标准协议，每两个 Agent 之间都需要写一个”翻译层”——N 个 Agent 需要 N×(N-1)/2 个适配器。有了标准协议，所有 Agent 只需要实现协议接口，N 个 Agent 只需要 N 个适配器。

五、通信的失败模式：怎么确保”聊不崩”？

这是工程落地中最关键、也最容易被忽视的部分。你的系统在 Demo 里跑得很好，一上生产就炸，大概率就是通信失败处理没做好。

5.1 语义漂移（Semantic Drift）

问题：Agent A 的意图在传递过程中被曲解，Agent B 理解的意思和 A 想表达的不一样。

1
2
3
4
5

Agent A: "优化这个函数的性能"（意图：降低时间复杂度）
    ↓ 传递
Agent B: "优化函数命名和代码风格"（理解：改善可读性）
    ↓ 结果
返回了命名更规范但性能没变的代码

解决方案：

• 意图确认机制：Agent B 在执行前先回述自己对任务的理解，让 A 确认
• 结构化任务描述：用 schema 定义任务的”验收标准”，而不是纯自然语言

1
2
3
4
5
6
7
8
9
10

# 结构化的任务描述，避免语义漂移
task = {
    "action": "optimize",
    "target": "calculate_price",
    "objective": "reduce_time_complexity",  # 明确优化目标
    "metric": "execution_time",
    "current_value": "O(n^2)",
    "target_value": "O(n log n)",
    "constraint": "不改变函数签名和返回值"
}

5.2 上下文溢出（Context Overflow）

问题：多轮通信导致消息列表越来越长，超出 LLM 的上下文窗口限制。

1
2
3
4
5
6

Round 1: 2,000 tokens
Round 2: 4,500 tokens
Round 3: 9,000 tokens
Round 4: 18,000 tokens
Round 5: 35,000 tokens  ← 接近 GPT-4 的 32K 限制
Round 6: 💥 超出限制

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

def compress_context(messages: list, max_tokens: int = 4000):
    """上下文压缩策略"""
    if count_tokens(messages) <= max_tokens:
        return messages

    # 1. 保留系统消息和最近 3 轮
    system_msgs = [m for m in messages if m["role"] == "system"]
    recent_msgs = messages[-6:]  # 最近 3 轮 = 6 条消息

    # 2. 中间的历史消息压缩成摘要
    old_msgs = messages[len(system_msgs):-6]
    summary = summarize(old_msgs)  # 用 LLM 生成摘要

    return system_msgs + [{"role": "system", "content": f"历史摘要：{summary}"}] + recent_msgs

5.3 死锁与活锁（Deadlock / Livelock）

死锁：Agent A 等待 Agent B 的结果，Agent B 等待 Agent C 的结果，Agent C 等待 Agent A 的结果 → 三个都卡住。

活锁：Agent A 和 B 互相传递任务，谁都不处理，一直踢皮球 → 系统一直在”忙”但没有进展。

1
2
3
4
5
6
7
8
9
10
11
12

死锁示例：
Agent A: "我需要 B 的分析结果才能给出建议"
Agent B: "我需要 C 的数据才能分析"
Agent C: "我需要 A 的建议才能确定数据范围"
→ 循环等待，无人能开始

活锁示例：
Agent A: "这个任务应该交给 B"
Agent B: "不，应该交给 A"
Agent A: "还是交给 B 吧"
Agent B: "不不不，A 更适合"
→ 无限循环，没有实际工作

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 1. 全局超时机制
import asyncio

async def with_timeout(coro, timeout_seconds=30):
    try:
        return await asyncio.wait_for(coro, timeout=timeout_seconds)
    except asyncio.TimeoutError:
        return {"error": "timeout", "message": "任务执行超时"}

# 2. 循环检测
class LoopDetector:
    def __init__(self, max_repeats=3):
        self.history = []
        self.max_repeats = max_repeats

    def check(self, message):
        self.history.append(hash(message["content"]))
        if len(self.history) >= self.max_repeats * 2:
            # 检查最近 N 条是否重复
            recent = self.history[-self.max_repeats:]
            if len(set(recent)) == 1:
                return True  # 检测到循环！
        return False

# 3. 强制降级
def fallback_when_stuck(agents_in_loop):
    """当检测到死锁/活锁时，强制交给更高级的 Agent 处理"""
    return escalate_to_supervisor(
        task="检测到 Agent 间通信死锁，请人工介入",
        context=agents_in_loop
    )

5.4 错误传播（Error Propagation）

问题：一个 Agent 的输出错误，会导致下游所有 Agent 基于错误信息做出错误决策。

1
2
3
4
5
6
7

Agent A（数据收集）: 错误地认为 API 限额是 1000 次/小时（实际是 10000 次）
    ↓
Agent B（方案设计）: 基于"1000 次限额"设计了保守的缓存策略
    ↓
Agent C（代码实现）: 实现了不必要的复杂缓存逻辑
    ↓
结果: 过度设计，性能反而下降

解决方案：

• 置信度传递：每个 Agent 标注自己输出的置信度，下游根据置信度决定采信程度
• 交叉验证：关键决策让多个 Agent 独立给出答案，投票决定
• 溯源机制：保留完整的推理链，出问题时可以逐级回溯

六、通信成本控制

每次 Agent 间的通信都不是免费的。架构师需要在”充分通信”和”成本控制”之间找平衡。

6.1 通信成本构成

6.2 成本控制策略

策略一：按需通信，不要全程直播

1
2
3
4
5

❌ 差的做法：Agent A 的每一步都实时通知 Agent B
✅ 好的做法：Agent A 完成阶段性成果后再通知 Agent B

不是每想了一步就要同步，而是想清楚了一个完整方案再交流。
就像高效的团队协作——不需要每分钟站会，有阶段性产出时再同步。

策略二：通信分级

不是所有通信都需要完整的推理链。简单的状态同步，一个枚举值就够了。

策略三：缓存复用

1
2
3
4
5
6
7
8
9
10
11
12

# 缓存其他 Agent 的历史输出，避免重复请求
agent_output_cache = {}

def get_agent_output(agent_id: str, task_hash: str):
    cache_key = f"{agent_id}:{task_hash}"
    if cache_key in agent_output_cache:
        return agent_output_cache[cache_key]  # 命中缓存

    # 未命中，实际调用
    result = call_agent(agent_id, task_hash)
    agent_output_cache[cache_key] = result
    return result

七、实战选型指南

7.1 按场景选拓扑

1
2
3
4
5
6
7
8
9
10
11
12
13

你的 Agent 系统是什么场景？
│
├── 线性流水线（A → B → C）
│   └── 中心化编排（Supervisor 模式）
│
├── 多角色讨论/辩论
│   └── 去中心化协作（GroupChat 模式）
│
├── 大型复杂系统（>10 个 Agent）
│   └── 层次化混合（Hierarchical 模式）
│
└── 动态任务分配（不知道谁来做）
    └── 去中心化 + 竞争机制（Contract Net 协议）

7.2 按需求选机制

1
2
3
4
5
6
7
8
9
10
11
12
13

你的 Agent 在哪里运行？
│
├── 单进程 / 同一运行时
│   └── 共享状态（LangGraph State）
│
├── 多进程 / 跨语言
│   └── 消息队列（Redis Streams / Kafka）
│
├── 需要长期记忆
│   └── 共享向量记忆（Vector Store）
│
└── 以上都需要
    └── 混合方案（状态 + 消息队列 + 向量记忆）

7.3 按阶段选协议

1
2
3
4
5
6
7
8
9
10

你的项目处于什么阶段？
│
├── MVP / 原型阶段
│   └── 结构化 JSON + Tool Call（够用了，别过度设计）
│
├── 生产环境
│   └── 心智模型传递（CoT + 置信度）+ 完整的错误处理
│
└── 跨组织协作
    └── A2A / MCP 标准协议（互操作性优先）

八、总结

Multi-Agent 通信设计，核心就是回答三个问题：

1. 拓扑（谁跟谁聊）：中心化、去中心化、还是层次化？
2. 机制（数据怎么流）：共享状态、消息队列、还是向量记忆？
3. 协议（聊什么格式）：纯文本、结构化工具调用、还是心智模型传递？