AgentScope Java Harness：1. 如何优雅地驾驭长期运行的 AI Agent
目录：
1. 如何优雅地驾驭长期运行的 AI Agent
2. 上下文压缩：让长期 Agent 永不“失忆“
3. 工作区（Workspace）文件即真理，目录即架构
4. 双层记忆系统 让 Agent 拥有真正的“长期大脑“
5. 文件系统一套代码，三种部署，零改动切换
6. 沙箱（Sandbox）让 Agent 在安全笼子里自由奔跑
7. 子 Agent 编排 文件驱动的多智能体协作架构
8. Skill技能让 Agent 从“会说话“进化为“会做事“
9. Plan Mode 让 Agent 先想清楚再动手
10. Channel Agent 通信的“神经系统“设计
从"一次对话"到"持续运行"——Harness 为 ReAct Agent 补齐了生产环境缺失的那块拼图。
一、引言：裸 Agent 的困境
当我们用 LLM 构建智能体时，一个最基础的 ReAct Agent 只需要完成一件事：**接收请求 → 推理 → 调用工具 → 返回回复。**这在 Demo 阶段完全够用。
但一旦走向生产环境，一系列"工程级"问题会接踵而至：
- 下一轮对话如何接上上一轮？
- 上下文窗口溢出了怎么办？
- 多用户并发时如何隔离？
- 危险操作如何先审批再执行？
- 可复用的能力如何沉淀和复用？
AgentScope Java 2.0 的 Harness 架构正是为回答这些问题而生的。HarnessAgent 作为 ReActAgent 的一层薄包装，将长期运行 Agent 必备的工程能力打包进单一 Builder，让开发者可以按需装配、即插即用。
二、核心设计理念：三条黄金法则
理解 Harness 架构，只需记住三条核心原则。这三条原则贯穿整个设计，体现了极高的工程品味。
法则一：能力是"叠加"的，不是"改写"的
Harness 没有修改 ReAct 循环的核心算法。工作区注入、上下文压缩、子 Agent 编排、沙箱隔离、Plan Mode——每个能力都钩在 ReAct 循环的关键时机上，以 Middleware 的形式叠加。
这意味着：
- 核心推理逻辑始终保持纯净，不因工程能力而变得臃肿；
- 每个能力可以独立开关，互不干扰；
- 升级核心推理引擎时，工程能力层无需跟着改动。
这是一种典型的 装饰器模式（Decorator Pattern） 思想在 Agent 框架中的应用。
法则二：能力之间互不依赖，只通过共享对象通信
每个能力模块只做自己的事，互相不感知。它们之间的通信依赖三个共享对象：
| 共享对象 | 职责 | 生命周期 |
|---|---|---|
| RuntimeContext | 标识当前调用身份：sessionId、userId、自定义 extra | 单次调用内，不持久化 |
| 工作区（Workspace） | 定义谁读写哪些文件，物理位置由配置决定 | 跟随 Agent 实例 |
| AgentStateStore | 跨调用恢复运行时状态 | 跨调用、跨进程持久化 |
这种设计带来了极好的解耦性——你可以替换文件系统的实现（本机 → 沙箱 → 远端存储），而不影响记忆模块或子 Agent 模块的行为。
法则三：内置 Middleware 顺序固定，自定义 Middleware 优先执行
Harness 在构建期按固定顺序串起所有内置 Middleware，开发者通过 .middleware(…) 添加的自定义 Middleware 会跑在所有内置 Middleware 之前。这保证了：
- 自定义逻辑（如鉴权、日志、限流）可以在框架行为之前介入；
- 内置能力的执行顺序是确定性的，不会因为外部扩展而被打乱。
三、核心组件全景图
Harness 提供了 12 项核心能力，每一项都对应一个具体的工程问题，通过 Builder 按需开启：
3.1 工作区驱动的人格（Workspace-Driven Persona）
HarnessAgent.builder().workspace("/path/to/workspace").build();这是一个非常巧妙的设计：人格、知识、子 Agent、技能、MCP 白名单全部以文件形式存在于工作区目录中。这意味着：
- 非开发人员（如产品经理、领域专家）可以直接编辑文件来调整 Agent 行为；
- 人格配置可以纳入版本管理（Git），具备完整的变更审计能力；
- 修改 AGENTS.md 或 MEMORY.md 后立即生效，无需重启——因为 system prompt 每轮都会重新拼装。
3.2 双层长期记忆（Two-Layer Memory）
Harness 的记忆系统分为两层：
- 日志层：memory/YYYY-MM-DD.md，只追加，记录每次会话中提炼出的有价值事实；
- 摘要层：MEMORY.md，由后台节流任务周期性合并日志层内容，每轮推理时注入 system prompt。
这种"先记录、后提炼"的两阶段策略，既保证了信息不丢失，又控制了注入 prompt 的 token 量。
3.3 上下文压缩与大结果卸载
这是解决 LLM 上下文窗口有限这一根本矛盾的关键机制：
- 对话压缩（.compaction(…)）：当上下文接近窗口上限时，自动对历史对话进行摘要压缩；
- 大工具结果卸载（.toolResultEviction(…)）：超过 80K 字符的工具返回结果自动落盘，原位替换为占位符；
- 溢出兜底：即使模型真的溢出了，框架也会强制重试，确保不会静默失败。
3.4 子 Agent 编排（Subagent Orchestration）
支持将复杂任务委派给子 Agent，具备以下特性：
- 同步调用或后台异步执行；
- 子 Agent 完成后自动反向通知父 Agent；
- 支持流式转发子 Agent 的输出；
- 可通过工作区 subagents/ 目录声明式配置。
3.5 可插拔文件系统与沙箱隔离
// 本机文件系统.filesystem(newLocalFilesystemSpec())// Docker 沙箱.filesystem(newDockerFilesystemSpec().image("python:3.11"))文件系统层完全可插拔，支持本机 + Shell、共享存储、Docker 沙箱三种模式，且切换时不需要修改业务代码。沙箱模式还提供了：
- 文件与命令的完全隔离；
- 跨调用的沙箱状态恢复；
- 多副本部署支持。
3.6 其他关键能力
| 能力 | 一句话说明 |
|---|---|
| 状态持久化 | 同一 (userId, sessionId) 跨请求、跨进程、跨副本恢复 |
| 计划模式 | 只读思考阶段 + Human-in-the-Loop 退出，适合高风险操作 |
| 技能装配 | 从 Git / Nacos / MySQL / classpath / 工作区多源加载 |
| MCP 集成 | 声明式 MCP Server 配置 + 工具粒度允许/拒绝白名单 |
| Channel 路由 | 会话管理、per-session 并发控制、多 Agent 路由、流式 SSE |
四、状态流转：三层架构的精妙设计
Harness 的状态管理是整个架构中最值得深入理解的部分。它将状态分为三层，框架自动在层间搬运数据：
┌─────────────────────────────────────────────────────────┐ │ Layer 3: 长期记忆（跨 Session 累积） │ │ memory/YYYY-MM-DD.md → 节流合并 → MEMORY.md │ │ 每轮注入 system prompt │ ├─────────────────────────────────────────────────────────┤ │ Layer 2: 跨调用状态（自动持久化） │ │ AgentState 快照 · 对话日志 (.jsonl) · 子任务记录 · 沙箱元数据 │ │ 按 (userId, sessionId) 寻址，存于 AgentStateStore │ ├─────────────────────────────────────────────────────────┤ │ Layer 1: 调用内状态（单次 call() 生命周期） │ │ AgentState（对话上下文、权限、Plan Mode、工具状态） │ │ RuntimeContext（sessionId、userId、沙箱句柄、extra） │ └─────────────────────────────────────────────────────────┘三个关键规律：
- System prompt 每轮重新拼装——修改工作区文件立即生效，零停机；
- 压缩、记忆提炼、后台维护都有节流闸门——不会每轮都触发，避免不必要的开销；
- AgentState 的持久化由 Core 层自动完成——ReActAgent + AgentStateStore 协作，Harness 不重复做这件事。
五、自定义 Middleware 的实践指南
在不绕过 Harness 内置链路的前提下插入自定义行为，需要遵循以下规范：
✅ 正确做法
HarnessAgentagent=HarnessAgent.builder()// 自定义 middleware，跑在所有内置 middleware 之前.middleware(newMyAuthMiddleware()).middleware(newMyRateLimitMiddleware()).workspace("/path/to/workspace").build();- 通过 RuntimeContext 获取当前调用身份（userId / sessionId）；
- 读写工作区使用 harnessAgent.getWorkspaceManager()，它会按当前文件系统模式正确路由。
❌ 常见错误
// 危险！在沙箱或远端模式下会写错位置Files.writeString(Path.of("/workspace/output.txt"),content);// 正确：通过 WorkspaceManager 路由harnessAgent.getWorkspaceManager().writeFile("output.txt",content);直接使用 java.nio.Files 在沙箱或远端模式下会导致文件写入错误的位置，这是一个容易被忽视但后果严重的陷阱。
六、架构评价与思考
从工程角度看，AgentScope Harness 的设计有几个值得称道的亮点：
1. "薄包装"哲学
Harness 没有重新发明轮子，而是在 ReActAgent 之上做了一层精心设计的包装。核心推理逻辑保持不变，工程能力以 Middleware 形式叠加。这使得框架的演进可以分层进行，降低了耦合风险。
2. 文件即配置
将人格、知识、技能、MCP 白名单全部文件化，是一个极具实用主义色彩的设计。它降低了非技术人员的参与门槛，也天然适配 GitOps 工作流。
3. 三层状态分离
调用内 → 跨调用 → 长期记忆的三层状态模型，清晰地区分了不同生命周期的数据，避免了"一锅炖"式的状态管理混乱。
4. 节流闸门的克制
压缩、记忆提炼等重操作不是每轮都跑，而是通过节流闸门控制频率。这种"懒执行"策略在长期运行的 Agent 中至关重要，直接影响成本和延迟。
七、总结
AgentScope Java Harness 回答的核心问题是：如何让一个"能对话"的 Agent 变成一个"能持续工作"的 Agent。
它通过 Middleware 叠加机制、三层状态管理、可插拔基础设施和文件驱动的配置体系，构建了一套完整的生产级 Agent 运行框架。对于正在将 AI Agent 从原型推向生产的团队来说，Harness 的架构设计思路——叠加而非改写、共享而非耦合、按需装配而非全量捆绑——本身就是一份值得参考的工程实践指南。