HarnessAgent 2.0 学习指南
版本基准 :本文档基于 AgentScope 2.0 GA(
v2.0.0)编写。具体版本号以 Release Notes 为准。
面向初级程序员的 AgentScope 2.0 HarnessAgent 文档详解
HarnessAgent 2.0 是什么？
一句话：HarnessAgent 是让 AI Agent 从"能用"变成"能长期稳定运行"的工程框架。
在 2.0 版本中，HarnessAgent 经历了一次重大升级：
- Middleware 取代 Hook：更清晰的洋葱模型，统一的扩展机制
- AgentState 取代 Memory 接口：完整的状态快照，配合 AgentStateStore 持久化（内存 / 文件 / Redis / MySQL / OSS 五类后端）
- streamEvents 全新 API：类型安全的事件流，替代旧版 stream()
- 计划模式、自学习技能、分布式沙箱：全新能力模块
如果你用过 1.x 版本，请先阅读 变更指南。
核心设计思想
HarnessAgent 2.0 的设计围绕"身份持续、上下文可控、状态可恢复"三根支柱展开：
┌─────────────────────────┐
│ HarnessAgent 2.0 │
│ (薄封装 + Middleware) │
└─────────┬───────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────────▼────────┐ ┌───▼───────────┐ ┌─▼──────────────┐
│ 身份持续 │ │ 上下文可控 │ │ 状态可恢复 │
│ │ │ │ │ │
│ • Workspace │ │ • Compaction │ │ • AgentStateStore│
│ • MEMORY.md │ │ • Tool Result │ │ • 持久化 │
│ • Skill 系统 │ │ Eviction │ │ • AgentState │
│ • AGENTS.md │ │ • Plan Mode │ │ • Snapshot │
└───────────────────┘ └───────────────┘ │ • 分布式恢复 │
└─────────────────┘概念依赖关系
总览(01) → 工作区(02) → 会话与压缩(03) → 记忆(04)
→ 文件系统(05) → 沙箱(07)
→ 技能(08)
→ 计划模式(06)
→ 子代理与流式(09)
→ 总结(10)推荐阅读顺序：按编号 01→10 顺序阅读，每篇依赖前序知识。
推荐阅读顺序
| 顺序 | 文档 | 一句话导读 | 预计用时 |
|---|---|---|---|
| 1 | 01-overview.md | 总览全局：2.0 的设计思想、Middleware 机制、能力全景 | 15 min |
| 2 | 02-workspace.md | 工作空间：目录结构、System Prompt 组装、tools.json | 20 min |
| 3 | 03-context.md | 会话与压缩：AgentState、5 类 AgentStateStore 后端、4 种压缩策略 | 25 min |
| 4 | 04-memory.md | 双层记忆：日记本 + 整理笔记，2.0 新增禁用开关 | 15 min |
| 5 | 05-filesystem.md | 文件系统：3 种声明式模式，IsolationScope 多租户 | 20 min |
| 6 | 06-plan-mode.md | 计划模式：先规划再执行，HITL 确认门控 | 15 min |
| 7 | 07-sandbox.md | 沙箱隔离：5 种后端、分布式快照、并发控制 | 30 min |
| 8 | 08-skill.md | 技能系统：自学习三阶段、晋升门控、市场管理 | 20 min |
| 9 | 09-subagent.md | 子代理与流式：streamEvents API、远程子代理 | 25 min |
| 10 | 10-summary.md | 总结回顾：串联所有 2.0 概念，形成完整知识体系 | 10 min |
总计约 3 小时，建议分 2-3 次完成。
关键术语速查
| 术语 | 类比 | 简要说明 |
|---|---|---|
HarnessAgent |
装了装备的 AI 员工 | 基于 ReActAgent 的工程化封装 |
ReActAgent |
裸的 AI 助手 | 只有"推理-行动"循环的基础 Agent |
Middleware |
中间件/插件 | 在推理循环的关键时机插入的能力（2.0 新术语，替代 Hook） |
AgentState |
完整工作快照 | 包含对话、摘要、权限、计划等全部运行状态 |
RuntimeContext |
当次调用的身份证 | 包含 sessionId、userId 等调用级元数据 |
Workspace |
办公桌 | Agent 的专属工作目录和文件 |
AgentStateStore |
档案柜 | 状态持久化的存储抽象（内存 / 文件 / Redis / MySQL / OSS 五类后端） |
Compaction |
读书笔记 | 对话压缩，把长对话精简成摘要 |
Sandbox |
安全笼子 | 隔离的执行环境 |
Plan Mode |
先画蓝图再施工 | 只读规划阶段，HITL 确认后才执行 |
Skill |
技能手册 | Markdown 格式的可复用能力指令 |
SubAgent |
下属 | 主 Agent 委派任务的子代理 |
📖 完整术语目录 ：GLOSSARY.md
📊 项目流程图 ：FLOWCHARTS.md
关键变更速查（1.x → 2.0）
| 1.x 术语 | 2.0 术语 | 说明 |
|---|---|---|
Hook（如 MemoryFlushHook） |
Middleware（如 MemoryFlushMiddleware） |
洋葱模型，统一扩展机制 |
Memory 接口 |
AgentState + AgentStateStore |
Memory 接口已标记 @Deprecated，状态用 AgentState 快照、用 AgentStateStore 持久化 |
Event / EventType |
AgentEvent / AgentEventType |
全新事件类型系统 |
stream() |
streamEvents() |
推荐 streamEvents，旧 API 标记废弃 |
AbstractFilesystem 接口 |
FilesystemSpec 声明式 |
LocalFilesystemSpec / RemoteFilesystemSpec / SandboxFilesystemSpec 三种声明式配置替代接口继承 |
前置知识
阅读本系列文档前，建议你了解：
- Java 基础：能看懂 Builder 模式、Lambda、Optional
- Maven 基础：知道怎么引入依赖
- AI Agent 基本概念：知道什么是 LLM、什么是 Prompt
- ReAct 模式（可选）：了解 Agent 的"推理-行动"循环
不需要了解的内容：Docker、Kubernetes、Reactive Programming（涉及时会解释）
封面图提示词
博客《HarnessAgent 2.0 学习指南》的封面图，此系列文章以学习 AgentScope 2.0 HarnessAgent 为目标。颜色：使用深色调（如深蓝、黑色、灰色）搭配亮色调（如青色、琥珀色或蓝色），以突出工程感和稳定性。AgentScope Cyan（青色）与白色或灰色的搭配非常适合与 HarnessAgent 框架相匹配。元素：使用简洁的图形（如升级箭头、版本号"2.0"标识、齿轮与芯片组合）代表版本升级和工程化能力，同时避免过多的装饰，使设计更具现代感。字体：选用简洁、现代的无衬线字体（如 Roboto、Open Sans 或 Montserrat），传达技术的清晰感。构图：封面中央可以使用"2.0"标识配合从左到右递进的能力节点图来突出版本升级主题，背景部分保持简洁，突出博客名称。比例 16:9。