第 1 章 · 02 四层地图与双子星架构

第 1 章 · 02 四层地图与双子星架构

本节摘要：本节给约 57 万行代码画一张"四层地图"——core（499 文件 11.7 万行，纯净 ReAct 内核）、harness（414 文件 8.6 万行，工程层）、service（209 文件 3.1 万行，控制面含 Go 的 aistio）、extensions（1201 文件 27.3 万行，21 类扩展 + 11 个 Spring Boot starter），外加 examples 的 50 个教学示例与 3 个完整应用。然后正式引出贯穿全书的双子星架构：内核星 ReActAgent（5459 行单巨类）对照工程星 HarnessAgent（2989 行 + 20 个工程包），并给出全书章节地图与 SKILL.md 避坑规则的阅读姿势。

内容来源：原项目源码 agentscope-core/agentscope-harness/agentscope-service/agentscope-extensions/agentscope-examples 目录统计、README_zh.md、SKILL.md、docs/v2/zh/。

⚠️ 注意：行数/文件数为 2.0.3-SNAPSHOT 快照统计（源码 main/java 下 *.java 计数），会随版本漂移；四层的体量比例与依赖方向才是要记住的东西。

学习目标

阅读完本节，你应当能够：

1. 画出四层模块地图并说出各层的体量与职责。
2. 解释依赖方向为何严格单向：service → extensions → harness → core。
3. 复述双子星分工：ReActAgent 5459 行纯内核星 vs HarnessAgent 2989 行 + 20 工程包工程星。
4. 盘点 50 个示例、3 个完整应用与 11 个 Spring Boot starter 的位置。
5. 知道 SKILL.md（31KB 避坑规则）会在全书哪些位置被引用。

一、四层模块地图：体量与职责

三个佐证体量感的事实：

1. core 是"纯净"的：agentscope-core 不依赖任何模型厂商 SDK——2.0 起模型提供商全部拆到 extensions（agentscope-extensions-model-dashscope/openai/anthropic/gemini/ollama 等）。core 的包目录（io.agentscope.core 下）只有这些：

agentscope-core/src/main/java/io/agentscope/core/
├─ ReActAgent.java        ← 5459 行，内核星本体（顶层单类）
├─ agent/                 ← Agent/AgentBase/RuntimeContext/accumulator/user（含 HITL 累积器）
├─ message/               ← Msg/MsgRole/ContentBlock 体系（23 文件，第 3 章）
├─ event/                 ← 31 种类型化事件（35 文件，第 4 章）
├─ tool/                  ← @Tool/Toolkit/MCP 三传输（38 文件，第 5 章）
├─ permission/            ← 权限引擎与五模式（第 6 章）
├─ middleware/            ← 五切点洋葱（第 6 章）
├─ state/                 ← AgentState/检查点/版本化保存（16 文件，第 7 章）
├─ memory/                ← Memory/LongTermMemory/压缩
├─ interruption/          ← 中断三件套（第 2 章 03 节）
├─ shutdown/              ← 优雅停机十件套（第 2 章 03 节）
├─ formatter/ skill/ rag/ hook/ workspace/ credential/ tracing/ util/ exception/
​

每一项都是"裸 Agent"的必要件，没有一件是基础设施。
2. service 里有 Go：agentscope-service 的 aistio 组件用 Go 实现，兼容 AgentScope、LangChain、ADK、Claude/Qoder 等多种 Agent 运行时做观测与注册——Java 框架配 Go 控制面，这是"平台化"野心的直接证据。
3. extensions 是星云：1201 个文件里既有 Mem0 长期记忆、Dify RAG 这类集成，也有 11 个开箱即用的 Spring Boot starter（core/a2a/admin/agui/chat-completions-web/dashscope/openai/anthropic/gemini/ollama/nacos）——Java 企业生态的杀手锏，第 9 章专讲。

harness 的 20 个工程包（io.agentscope.harness.agent 下）先混个脸熟，第 8 章逐个进：workspace（工作区/人格/记忆目录）、sandbox（本地/Docker/K8s/E2B 沙箱 + 快照）、skill（技能仓库与 curator 自进化）、subagent（子 agent 与跨副本路由）、team（多 agent 团队）、gateway（钉钉/飞书/企微/GitHub 通道）、coordination（PeriodicGate 定时唤醒）、filesystem（可插拔文件系统）、memory（分层记忆）、middleware/artifact/bus/transcript/tool(s) 等，加上顶层的 DistributedStore/IsolationScope 两个分布式原语。

examples 里 3 个完整应用值得先记名字：codingagent（9487 行，类 Claude Code 的编码助手）、dataagent（23387 行，数据分析）、paw（16806 行）。它们是"这本书讲的所有零件如何拼成产品"的参考答案。

50 个教学示例（agentscope-examples/documentation 等，共 359 个 Java 文件）按主题成群分布，本教程各章都会"回到现场"引用：

读源码卡住时的口诀同样适用于这个仓库：先读它的示例，再读它的测试（全仓 802 个测试类）——示例展示"官方想让你怎么用"，测试展示"边界在哪里"。

二、双子星架构：一纯一厚的两颗星

内核星：ReActAgent（agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java，5459 行）。它是一个单巨类：类头注释自述为 "ReAct (Reasoning and Acting) Agent implementation"；Reactor 反应式全栈、流式事件发射、HITL 暂停/恢复、failover、中断与优雅停机全部浓缩在这一个类里。它不依赖任何基础设施（无数据库、无沙箱、无消息网关），是"裸 Agent"的完整实现。第 2-7 章逐层解剖它。

工程星：HarnessAgent（agentscope-harness/.../harness/agent/HarnessAgent.java，2989 行）。它本身没有 5459 行那么吓人，但它身后站着 20 个工程包——agent 包目录下的 workspace、sandbox、skill、subagent、team、gateway、coordination、filesystem、memory、middleware、artifact、bus、transcript、tool(s) 等。README_zh 的描述精确："HarnessAgent 在 ReActAgent 之上通过 Middleware 与 Toolkit 叠加工程基础设施，核心推理循环原样保留"。第 8 章验证这个"原样保留"。

为什么这个对照值得用一本书的篇幅？因为它们代表了两类工程判断：

三、官方文档、SKILL.md 与本书的分工

官方文档：docs/ 约 470 个 md（v1/v2 中英双版本），其中 docs/v2/zh/ 是约 115 篇原生中文。它偏 API 手册（building-blocks/agent.md、message-and-event.md 等写得非常清楚），本教程大量引用它作为"官方怎么说"的锚点，再下潜到源码看"官方为什么这么写"。读法建议：每学完本书一章，把对应的官方文档页通读一遍做交叉验证——两边说法一致说明理解到位，不一致时以源码为准。

SKILL.md：仓库根目录 31KB 的框架编码避坑规则，源自我方写 AgentScope 代码时最易踩的坑。全书会把它融入各章的 ⚠️ 注意 与 💡 双星要点，最核心的三条先立此存照：

SKILL.md「CRITICAL RULES」节选
1. NEVER use `.block()` in example code —— 只允许出现在 main()/测试里
2. NEVER use `Thread.sleep()` —— 用 Mono.delay() 代替
3. NEVER use `ThreadLocal` —— 用 Reactor Context + Mono.deferContextual()
​

这三条禁令的共同背景是：AgentScope 全栈反应式（第 2 章 02 节展开），任何阻塞调用都可能卡死少数 Reactor 线程，而 ThreadLocal 在"一个线程先后跑多个订阅"的模型下会串上下文。

本书章节地图（与四层地图的对应）：

第 1 章 全貌与双子星          ← 本章（总览层）
第 2 章 ReActAgent 循环 ★     ← 内核星·心脏（core/ReActAgent.java）
第 3 章 消息与内容块          ← 内核星·血液（core/message 23 文件）
第 4 章 事件系统 ★            ← 内核星·神经（core/event 35 文件，31 种事件）
第 5 章 工具体系             ← 内核星·四肢（core/tool 38 文件 + Toolkit 1073 行）
第 6 章 权限与中间件 ★        ← 内核星·免疫（五模式三态 + 五切点洋葱）
第 7 章 状态检查点与记忆       ← 内核星·海马（core/state 16 文件）
第 8 章 工程星 HarnessAgent   ← 工程层（harness 8.6 万行）
第 9 章 多 Agent 与扩展星云    ← 星云层（extensions 27.3 万行 + 11 starter）
第 10 章 Service 平台与回顾   ← 平台层（Go 控制面 + DAG + 3 应用）
​

第 2、4、6 章是内核星的三个高点（★），第 2 章又是全书高潮——下一节起我们逐段贴源码解剖 5459 行。

💡 双星要点：四层地图的依赖方向严格单向（service → extensions → harness → core），所以"只用内核星"是合法配置（单独依赖 agentscope-core 跑裸 ReActAgent），"跳过内核星"则不可能。记住这个方向，后面每一章问自己一个问题就够了：这个能力住在哪一层？

本节要点回顾

1. 四层体量：core 499 文件 11.7 万（纯净内核）/ harness 414 文件 8.6 万（工程层）/ service 209 文件 3.1 万（控制面含 Go aistio）/ extensions 1201 文件 27.3 万（21 类 + 11 starter）。
2. 依赖单向：service → extensions → harness → core；core 不捆绑任何厂商 SDK。
3. 双子星：ReActAgent 5459 行单巨类（裸 Agent 完整实现）vs HarnessAgent 2989 行 + 20 工程包（裸 Agent 到生产 Agent 的桥梁，核心循环原样保留）。
4. 资源三件套：docs/v2/zh 约 115 篇原生中文（API 锚点）、SKILL.md 31KB 避坑规则（禁 .block()/Thread.sleep()/ThreadLocal）、examples 50 示例 + 3 应用（codingagent/dataagent/paw）。
5. 全书十章沿四层展开，第 2/4/6 章是内核星三个高点。

下一章进入全书高潮：我们把 ReActAgent.java 5459 行摊开在解剖台上，先看类头与继承体系，再逐段走读推理-行动循环——reasoning、acting、observation 是如何在 Reactor 的 Mono 链上转起来的。