一、整体架构分层概览

┌─────────────────────────────────────────────────────┐
│              应用层 (Application Layer)               │
│  Spring Boot微服务  │  命令行应用  │  纯Java应用      │
├─────────────────────────────────────────────────────┤
│               接入层 (Java开发入口)                    │
│  HarnessAgent(推荐) │ ReActAgent(核心) │              │
│  Middleware扩展机制  │ 子Agent编排     │ 事件流系统     │
│  细粒度权限管理      │ 模型调用容错     │ Workspace     │
│  MCP集成            │ Tool注解注册方法  │              │
├─────────────────────────────────────────────────────┤
│             基础设施层 (Infrastructure)               │
│  Kubernetes容器编排 │ MySQL  │ 分布式缓存 │ 对象存储    │
└─────────────────────────────────────────────────────┘

二、核心抽象层详解

2.1 双Agent抽象：ReActAgent vs HarnessAgent

这是2.0重构中最核心的设计决策——“发动机”与“整车”分离：

一句话：ReActAgent是发动机，HarnessAgent给发动机配了油箱、轮胎、刹车片和仪表盘组成的整车。你只管踩油门写业务逻辑，其他事交给框架。

2.2 Workspace：文件驱动架构

设计哲学：所有需要持久化的内容都表达为磁盘上的Markdown/JSON文件，而不是散落在代码或数据库表中。

四大好处：

可审计：可以用 git diff 查看智能体人设变化
可编辑：直接改AGENTS.md里的提示词，下一句话就生效
可迁移：整个workspace打包，记忆/技能/计划全部迁移
可组合：人格、事实、子Agent全部写在文件里，配置即代码，单一事实来源

三、分布式部署架构

设计理念：同一份业务代码，按需切换到分布式形态，任意副本都能恢复任意用户的完整上下文。
分布式部署的三大共享对象

AgentStateStore 支持的后端实现

单机开发阶段零配置开箱即用，生产部署只需替换状态后端，框架还会在装配阶段校验配置一致性——用了沙箱却忘了把会话状态换成分布式后端，启动时直接报错。

四、多租户隔离架构

全链路强制隔离，不依赖业务代码自觉：
userId + sessionId
     │
     ├──→ 工作区路径隔离 (不同用户文件写入不同命名空间)
     ├──→ 存储命名空间隔离 (数据存储按用户分桶)
     └──→ 沙箱环境隔离 (安全执行环境彼此独立)
三种隔离粒度可选：

每段对话隔离：各跑各的
同一用户共享：同一用户多次会话共享工作区
全员共享：公共工具型智能体

五、Middleware扩展机制（取代旧Hook）

5个钩子位置，通过priority排序，职责单一，互不干扰，可独立Mock测试：

特性：完全不依赖主动调用，只要注册到框架中，就自动生效。Worker机制正是在这些钩子位置注入额外能力。

六、核心组件调用链路图

用户请求
  │
  ├── 1. HarnessAgent 接收请求
  │     ├── 绑定 RuntimeContext (userId/sessionId)
  │     └── 上下文溢出时强制压缩并重试
  │
  ├── 2. Middleware 钩子链（按priority排序）
  │     ├── onAgent：初始化租户上下文
  │     ├── onSystemPrompt：注入Workspace文件
  │     ├── onReasoning：Token预算检查
  │     └── onActing：权限检查
  │
  ├── 3. ReActAgent 核心循环
  │     ├── 思考 → 调用LLM推理
  │     ├── 行动 → 调用工具（权限引擎审核）
  │     └── 观察 → 处理结果继续循环
  │
  ├── 4. 模型调用容错层
  │     ├── 自动重试（退避策略）
  │     └── 备用模型切换
  │
  ├── 5. 事件流系统输出
  │     ├── text_chunk（流式文本）
  │     ├── tool_call（工具调用）
  │     ├── human_confirmation（人工确认）
  │     └── ...
  │
  └── 6. 会话持久化 → AgentStateStore

七、架构总结

总结：AgentScope Java 2.0把分布式部署、多租户隔离、权限管控、模型容错、人机协作这些企业级“看不见的肌肉”全部做成框架的原生特性，而不是让开发者自己拼装。