目录1. 如何优雅地驾驭长期运行的 AI Agent2. 上下文压缩让长期 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 PersonaHarnessAgent.builder().workspace(/path/to/workspace).build();这是一个非常巧妙的设计人格、知识、子 Agent、技能、MCP 白名单全部以文件形式存在于工作区目录中。这意味着非开发人员如产品经理、领域专家可以直接编辑文件来调整 Agent 行为人格配置可以纳入版本管理Git具备完整的变更审计能力修改 AGENTS.md 或 MEMORY.md 后立即生效无需重启——因为 system prompt 每轮都会重新拼装。3.2 双层长期记忆Two-Layer MemoryHarness 的记忆系统分为两层日志层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、工具状态 │ │ RuntimeContextsessionId、userId、沙箱句柄、extra │ └─────────────────────────────────────────────────────────┘三个关键规律System prompt 每轮重新拼装——修改工作区文件立即生效零停机压缩、记忆提炼、后台维护都有节流闸门——不会每轮都触发避免不必要的开销AgentState 的持久化由 Core 层自动完成——ReActAgent AgentStateStore 协作Harness 不重复做这件事。五、自定义 Middleware 的实践指南在不绕过 Harness 内置链路的前提下插入自定义行为需要遵循以下规范✅ 正确做法HarnessAgentagentHarnessAgent.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 的架构设计思路——叠加而非改写、共享而非耦合、按需装配而非全量捆绑——本身就是一份值得参考的工程实践指南。