轻量级 Agent 状态事务库 —— 保护 Agent 执行期间的状态变更，失败时自动回滚。零外部依赖，兼容所有主流 Java AI 框架。
AI Agent 在运行时可能修改对话历史、业务状态、缓存数据等共享可变状态。一旦 Agent 调用出错或工具异常，这些状态就脏了。atom-tx 提供了一个 两阶段回滚引擎，保证状态在失败时恢复到变更前的样子。
以下是一个真实生产事故：Agent 重复调用下游工具 2000 次，打爆线程池和数据库连接。这类事故的根本原因是 运行时没有状态保护机制。atom-tx 用一行代码解决这个问题。
xml <dependency> <groupId>org.atomtx</groupId> <artifactId>atom-tx</artifactId> <version>0.1.0</version> </dependency>
AgentScope：
java TxTemplate tx = new TxTemplate(); HarnessAgent agent = HarnessAgent.builder() .name("demo") .model("dashscope:qwen-max") .middleware((context, next) -> tx.execute("agent-tx", providers, () -> next.execute(context)) ) .build();
Spring AI：
java ChatClient client = ChatClient.builder(model) .defaultAdvisors((Advisor) (request, chain) -> tx.execute("chat-tx", providers, () -> chain.nextAroundCall(request)) ) .build();
LangChain4j：
java ChatLanguageModel txModel = new ChatLanguageModel() { public Response<AiMessage> generate(List<ChatMessage> messages) { return tx.execute("lc4j-tx", providers, () -> delegate.generate(messages)); } };
纯 Java：
java String reply = tx.execute("plain-tx", providers, () -> agent.chat(input));
所有场景都只需 1 个 TxTemplate 对象 + 1 行 lambda。atom-tx 不依赖任何 AI 框架的 API，框架升级不影响它。
tx.execute(name, providers, action) ← 唯一入口 └── UnitOfWork.begin() ← ① 快照当前状态，替换为变更追踪代理 └── action.run() ← ② Agent 执行（LLM + tool calling） ├── success → commit() ← ③ 变更生效 └── failure → rollback() ← ④ 自动回滚（逆向操作 → 快照兜底）
回滚策略（两阶段）：
- ChangeLog 逆向操作（高效） —— 对变更过的 key 逐个做反向 put/remove，恢复到变更前
- 快照覆盖（兜底） —— 如果逆向操作失败，直接用 begin 时保存的全量快照覆盖
` atom-tx/ ← 零外部依赖，单模块 ├── TxTemplate ← 唯一面向用户的入口 ├── UnitOfWork ← 事务引擎（状态机：IDLE→ACTIVE→COMMITTED|ROLLED_BACK） ├── UnitOfWorkManager ← ThreadLocal 管理器（可选） ├── ProxyFactory ← Map/List 变更追踪代理（JDK Proxy） ├── MapProxyHandler / ListProxyHandler ├── ChangeLog / DefaultChangeLog ← 变更记录与逆向回滚 ├── MemoryProvider ← 状态提供者 SPI ├── InMemoryMapMemoryProvider ← 内置内存态提供者 └── exception/ ← 3 个异常类型
atom-tx-spring-boot-starter/ ← 可选模块（仅依赖 spring-boot-starter-aop） ├── @TransactionalAgent ← 注解 └── AtomTxAspect ← AOP 切面 `
| 决策 | 方案 | 原因 |
|---|---|---|
| 框架集成 | 1 行 lambda 包裹，无适配器模块 | 框架升级不造成断裂，无需维护 N 个适配器 |
| 外部依赖 | 零依赖 | JDK 17+ 即可运行，不引入 CGLIB/Jackson/SLF4J |
| 代理范围 | 仅 Map/List（JDK Proxy） | POJO 代理需要 CGLIB（final 类问题 + --add-opens + GC 压力）；Agent 中最常见的可写状态是 Map |
| 状态机 | 3 个状态（IDLE→ACTIVE→COMMITTED|ROLLED_BACK） | 去掉 COMMITTING/ROLLING_BACK 中间态，纯内存操作不需要它们 |
| 序列化 | 无 JSON Patch | 回滚在内存中操作 ChangeLog 对象，不经过序列化 |
| 异常声明 | hrows Throwable | Spring AOP 的 ProceedingJoinPoint.proceed() 抛出 Throwable |
�ash mvn test
结果：21 个测试全部通过，覆盖 Map 代理、List 代理、ChangeLog 逆向回滚、事务提交/回滚、多 Provider 隔离。
atom-tx 是从 Atom 治理容器中提取的核心事务引擎，保留了原子能力，去掉了以下冗余组件：
Pipeline + 4 个拦截器→ 用户用 Spring AOP / AgentScope Middleware 替代TokenBucket 限流→ 用 Redis / Sentinel / GuavaBehaviorSandbox→ SecurityManager 已废弃，用 Docker 沙箱SlidingWindowMemory→ 各 AI 框架自带记忆管理SPI 接口层（Orchestrator/GovernanceMetrics/ToolDiscoveryProtocol）→ 直接用框架原生接口CGLIB POJO 代理→ 仅 Map/List 代理Spring AI / LangChain4j 适配模块→ 用户通过 lambda 自行集成
MIT