手把手教你学习智能体开发（通过claude上手agentscope）

准备步骤（下载、配置跳过登陆、准备国内模型token）

下载claude code

mac: curl -fsSL https://claude.ai/install.sh | bash
window: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

安装后验证

claude --version
如果显示版本号则安装成功

登陆跳过

安装完毕后，会一直让用户登陆，工具在启动时首先检查用户是否已经完成“入门流程”（onboarding），而不是直接检查可用的 API 凭证。这意味着，即使你的 API 设置完全正确，只要系统认为你还没有完成初始设置，就会强制你进入登录流程。
此时需要执行如下操作：
检查配置文件：ls -la ~/.claude.json
不存在：echo’{“hasCompletedOnboarding”: true}’ > ~/.claude.json
存在则直接修改：

# 使用 sed 命令添加或修改设置
sed -i '' 's/"hasCompletedOnboarding": false/"hasCompletedOnboarding": true/g' ~/.claude.json

选用国内模型token

例如kimi,博主用的deepseek，感觉还是蛮费钱的，可以冲个10块玩下。
Configure the following content in ~/.claude/settings.json to skip logging in and use the kimi api

{
“env”: {
“ANTHROPIC_API_KEY”: “xxx”,
“ANTHROPIC_BASE_URL”: “https://api.moonshot.cn/anthropic/”,
“CLAUDE_CODE_MAX_OUTPUT_TOKENS”: 32000,
“CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC”: 1
}
}

通过claude上手agentscope项目

init项目

使用 /init 命令来初始化项目
Claude 会自动扫描你的代码库——读取 package.json、现有文档、配置文件以及代码结构，然后生成一份专属于你项目的 CLAUDE.md 文件。Claude 整个过程无需手动操作，Claude 会自行分析并输出初始配置。
如agentscope项目的CLAUDE.md如下

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AgentScope Java is a reactive, agent-oriented programming framework for building LLM-powered applications. It's built on Project Reactor and follows reactive programming principles.

**Key Characteristics:**
- **Reactive Architecture**: All asynchronous operations use Project Reactor's `Mono` and `Flux`
- **ReAct Paradigm**: Agents autonomously reason and act using the ReAct (Reasoning-Acting) pattern
- **Multi-Agent Collaboration**: Support for distributed agent communication via A2A protocol
- **Production-Ready**: Includes tool sandboxing, observability with OpenTelemetry, and GraalVM native image support

## Module Structure

This is a multi-module Maven project with the following modules:

1. **agentscope-core** - Core framework containing:
   - Agent implementations (`ReActAgent`, `UserAgent`, etc.)
   - Model integrations (Anthropic, DashScope, Gemini)
   - Formatters and message converters
   - Tool system and MCP (Model Context Protocol) integration
   - Reactive stream handling with Project Reactor

2. **agentscope-extensions** - Optional extensions including:
   - RAG (Retrieval-Augmented Generation) with simple and advanced implementations
   - Skill repositories (MySQL, Redis session storage)
   - Scheduler integrations (Quartz, XXL-Job)
   - AGUI (Automated GUI interaction)
   - Nacos integration for service discovery and A2A protocol
   - Quarkus extensions

3. **agentscope-examples** - Example applications demonstrating:
   - Quickstart tutorials
   - Multi-agent patterns
   - Plan notebook system
   - Boba tea shop simulation
   - Werewolf game with human-in-the-loop

4. **agentscope-dependencies-bom** - BOM (Bill of Materials) for dependency management
5. **agentscope-distribution** - Distribution and packaging modules

## Development Commands

### Building and Testing
```bash
# Build all modules
mvn clean compile

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=YourTestClassName

# Build with tests and coverage (CI standard)
mvn clean verify

# Build with Maven Daemon (faster, used in CI)
mvnd -B -T1 clean verify
```

### Code Quality
```bash
# Check code formatting
mvn spotless:check

# Auto-fix formatting issues
mvn spotless:apply

# Generate Javadoc
mvn javadoc:javadoc
```

### Development Tools
```bash
# Install mvnd (Maven Daemon) for faster builds
curl -fsSL https://github.com/apache/maven-mvnd/releases/download/1.0.3/maven-mvnd-1.0.3-linux-amd64.tar.gz | tar xz
mkdir -p ~/.mvnd
mv maven-mvnd-1.0.3-linux-amd64/* ~/.mvnd/
```

## Critical Coding Guidelines

### 🚫 ABSOLUTELY FORBIDDEN
1. **NEVER use `.block()` in library/agent code** - Only allowed in `main()` methods or test code
2. **NEVER use `Thread.sleep()`** - Use `Mono.delay()` for delays
3. **NEVER use `ThreadLocal`** - Use Reactor Context with `Mono.deferContextual()`
4. **NEVER hardcode API keys** - Always use `System.getenv()` or configuration
5. **NEVER ignore errors silently** - Always provide error handling with `.onErrorResume()` or `.onErrorReturn()`

### ✅ ALWAYS DO
1. **Use reactive patterns** - Chain operations with `.map()`, `.flatMap()`, `.then()`
2. **Use Builder pattern** for creating agents, models, and messages
3. **Add logging** with SLF4J for important operations
4. **Use correct imports**: `import io.agentscope.core.model.DashScopeChatModel;` (NOT `io.agentscope.model.*`)
5. **Follow API conventions** (see SKILL.md for detailed API mappings)

### Code Examples
```java
// ✅ CORRECT - Non-blocking reactive pattern
return model.generate(messages, null, null)
    .map(response -> processResponse(response))
    .onErrorResume(e -> {
        log.error("Operation failed", e);
        return Mono.just(fallbackValue);
    });

// ❌ WRONG - Blocking in agent logic (NEVER do this)
String result = model.generate(messages, null, null).block();

// ✅ CORRECT - Only allowed in main() methods
public static void main(String[] args) {
    // ⚠️ .block() is ONLY allowed here because this is a main() method
    Msg response = agent.call(userMsg).block();
    System.out.println(response.getTextContent());
}
```

## Key Architectural Concepts

### Agents
- **ReActAgent**: Primary agent implementation using Reasoning-Acting pattern
- **UserAgent**: For human-in-the-loop interactions
- **ObservableAgent**: Agents that can be observed via event streams
- **StreamableAgent**: Support for streaming responses

### Messaging
- **Msg**: Primary message class with content, metadata, and conversation history
- **Content types**: Text, image, audio, tool calls, tool results
- **Formatter system**: Convert between LLM provider formats and internal Msg representation

### Tools and Skills
- **Tool system**: Register Java methods as tools with `@Tool` annotation
- **Skill repository**: Persistent storage and retrieval of tools/skills
- **MCP integration**: Connect to Model Context Protocol servers for external tool access
- **Tool validation**: JSON schema validation for tool inputs

### Hooks and Observability
- **StreamingHook**: Intercept and modify streaming responses
- **StructuredOutputHook**: Handle structured output parsing and self-correction
- **OpenTelemetry integration**: Distributed tracing across agent execution

## Configuration and Environment

### Required Environment Variables
```bash
# Model API keys (examples)
export DASHSCOPE_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
```

### Maven Dependency
```xml
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version>1.0.9</version> <!-- Check for latest version -->
</dependency>
```

## Testing Strategy

- **Unit tests**: Use JUnit 5 with Project Reactor's `StepVerifier` for testing reactive streams
- **Integration tests**: Mock external services with OkHttp's `MockWebServer`
- **Coverage**: JaCoCo integration with `mvn verify` generating coverage reports
- **Test isolation**: Each test should be independent and not rely on shared state

## Commit Conventions

Follow Conventional Commits specification:
- `feat(<scope>):` New feature
- `fix(<scope>):` Bug fix
- `docs(<scope>):` Documentation changes
- `style(<scope>):` Code style changes (formatting, etc.)
- `refactor(<scope>):` Code refactoring
- `perf(<scope>):` Performance improvements
- `ci(<scope>):` CI/CD changes
- `chore(<scope>):` Build process or tool changes

Examples:
```bash
feat(agent): add support for Claude-3 model
fix(memory): resolve memory leak in ReActAgent
docs(readme): update installation instructions
```

## Resources
- **Documentation**: https://java.agentscope.io/
- **GitHub Issues**: https://github.com/agentscope-ai/agentscope-java/issues
- **SKILL.md**: Detailed API reference and coding guidelines in repository root
- **Examples**: Comprehensive examples in `agentscope-examples/` directory

基于项目进行问答学习

直接ask，之前看过ai编码很强大，可以不了解代码直接由ai进行代码issue修复和feature完善。所以上来就想直接提PR，发现看了issue并不能看懂，所以就先从了解项目入手。

如何贡献这个开源项目

 AgentScope Java 是一个响应式、代理导向的 Java 框架，用于构建基于大语言模型（LLM）的生产级 AI 应用。它基于 Project Reactor 实现全异步非阻塞架构，核心采用
   ReAct（推理‑行动）范式，支持多智能体协作、工具调用、长期记忆、RAG 等企业级能力，并内置 MCP、A2A 协议、安全沙箱和 OpenTelemetry 可观测性。              
                                                                                                                                                          
  🎯 项目核心亮点                                                                                                                                                                                                                                                                                              
  - ReAct 自主推理：智能体动态规划工具使用，支持安全中断、优雅取消和人机协同                                                                              
  - 生产就绪工具：PlanNotebook（任务分解）、结构化输出（自纠错解析）、长期记忆、RAG 集成
  - 企业集成：MCP 协议扩展工具生态，A2A 协议实现分布式多智能体发现与调用
  - 高性能与安全：GraalVM 原生镜像（200ms 冷启动）、运行时沙箱、全链路追踪

  📦 项目结构

  多模块 Maven 项目：
  - agentscope-core – 核心框架（Agent、Model、Formatter、Tool 系统）
  - agentscope-extensions – 扩展（RAG、技能仓库、调度器、AGUI、Nacos 集成）
  - agentscope-examples – 示例应用（快速入门、多智能体模式、模拟游戏）
  - agentscope-dependencies-bom – 依赖管理 BOM
  - agentscope-distribution – 分发打包

  🛠️  如何贡献

  1. 准备工作

  - 环境要求：JDK 17+、Maven 3.6+
  - 代码规范：严格遵循 CLAUDE.md 和 SKILL.md 中的编码准则
    - 绝对禁止：在非 main()/测试代码中使用 .block()、Thread.sleep()、ThreadLocal、硬编码 API 密钥
    - 必须使用：Mono/Flux 响应式链、Builder 模式、环境变量读取、错误处理

  2. 贡献流程

  1. 查看现有计划
    - 浏览 https://github.com/agentscope-ai/agentscope-java/issues
    - 新手建议：选择标记为 https://github.com/agentscope-ai/agentscope-java/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22 的
  Issue
    - 进阶任务：寻找 https://github.com/agentscope-ai/agentscope-java/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22 标签
  2. 沟通与分配
    - 若 Issue 未分配，留言表示参与意向
    - 若需新增功能/修复，先创建 Issue 讨论方案
  3. 开发与测试
  # 构建
  mvn clean compile
  # 运行测试
  mvn test
  # 检查代码格式
  mvn spotless:check
  # 自动修复格式
  mvn spotless:apply
  # 完整验证（含覆盖率）
  mvn verify
  4. 提交代码
    - 遵循 Conventional Commits 规范：
    <type>(<scope>): <subject>
        - feat(agent): 添加对新模型的支持
      - fix(memory): 修复内存泄漏
      - docs(readme): 更新安装说明
    - PR 原则：单一功能/修复、包含测试、不破坏现有 API、不添加不必要依赖

  3. 贡献方向建议

  - 模型集成：新增 LLM 提供商（如本地模型、云服务）
  - 工具扩展：实现常用业务工具（数据库、API 调用、文件操作）
  - 示例应用：编写更多场景示例（客服、数据分析、自动化流程）
  - 文档完善：中英文文档、API 注释、教程案例
  - 性能优化：响应式链调优、内存管理、启动速度
  - 测试覆盖：补充单元测试、集成测试、性能测试

  4. 获取帮助

  - 讨论区：https://github.com/agentscope-ai/agentscope-java/discussions
  - 即时交流：Discord、钉钉群（见 README 二维码）
  - 详细指南：./CONTRIBUTING_zh.md、./SKILL.md

  🚀 快速验证环境

  # 克隆并构建
  git clone https://github.com/agentscope-ai/agentscope-java.git
  cd agentscope-java
  mvn clean compile
  mvn test -Dtest=ReActAgentTest  # 运行核心测试

  贡献前请务必阅读项目文档，理解响应式编程范式（Project Reactor）和 AgentScope 的架构设计。任何贡献都需通过 CI
  检查（格式、测试、构建），确保代码质量与项目标准一致。

你现在是这个代码工程的专家，请进一步分析agent-core中的代码，并向我这个新加入的成员进行介绍，帮助我上手这个工程的开发工作

claude通过一系列猛如虎的操作之后，

分析项目整体结构（根pom.xml）

分析agent-core模块结构（agentscope-core/pom.xml）

查看核心Agent类（ReActAgent.java等）

查看消息系统（Msg类和相关类）

查看模型集成和格式化器

查看工具系统和MCP集成

分析测试结构和开发模式

编写新成员上手指南

答复如下

AgentScope Java - agent-core 模块开发上手指南
欢迎加入 AgentScope Java 项目！本文档将帮助你快速了解 agent-core 模块（agentscope-core）的核心架构和开发流程。

项目概述
AgentScope Java 是一个基于 Project Reactor 的反应式、面向代理（Agent-Oriented）的 LLM 应用开发框架。核心特性包括：

反应式架构：所有异步操作使用 Mono 和 Flux
ReAct 范式：代理自主推理和行动（Reasoning-Acting）
多代理协作：支持分布式通信（A2A 协议）
生产就绪：包含工具沙箱、OpenTelemetry 可观测性、GraalVM 原生镜像支持
模块结构
这是一个多模块 Maven 项目，agentscope-core 是核心框架模块：


agentscope-java/
├── agentscope-core/          # 核心框架
├── agentscope-extensions/    # 扩展模块（RAG、调度器、AGUI等）
├── agentscope-examples/      # 示例应用
├── agentscope-dependencies-bom/  # 依赖管理
└── agentscope-distribution/  # 分发模块
agent-core 模块详解
核心依赖

<!-- agentscope-core/pom.xml 关键依赖 -->
<dependency>
    <groupId>io.projectreactor</groupId>
    <artifactId>reactor-core</artifactId>  <!-- 反应式编程 -->
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>  <!-- JSON 序列化 -->
</dependency>
<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java</artifactId>    <!-- Anthropic SDK -->
</dependency>
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>              <!-- MCP 协议集成 -->
</dependency>
核心包结构

src/main/java/io/agentscope/core/
├── agent/                    # 代理基础类
│   ├── AgentBase.java        # 所有代理的抽象基类
│   ├── ReActAgent.java       # 核心 ReAct 代理实现
│   ├── UserAgent.java        # 人机交互代理
│   ├── ObservableAgent.java  # 可观察代理
│   └── StreamableAgent.java  # 流式响应代理
├── message/                  # 消息系统
│   ├── Msg.java             # 核心消息类
│   ├── MsgRole.java         # 消息角色
│   └── ContentBlock.java    # 内容块
├── model/                    # 模型集成
│   ├── ChatModelBase.java   # 模型基类
│   ├── AnthropicChatModel.java
│   ├── DashScopeChatModel.java
│   ├── GeminiChatModel.java
│   └── OpenAIChatModel.java
├── formatter/               # 格式化器（转换消息格式）
│   ├── anthropic/          # Anthropic 格式
│   ├── dashscope/          # DashScope 格式
│   ├── gemini/             # Gemini 格式
│   └── openai/             # OpenAI 格式
├── tool/                    # 工具系统
│   ├── Tool.java           # @Tool 注解
│   ├── ToolRegistry.java   # 工具注册表
│   ├── ToolExecutor.java   # 工具执行器
│   └── mcp/                # MCP 集成
├── skill/                   # 技能系统
│   ├── SkillRegistry.java  # 技能注册
│   └── repository/         # 技能存储库
├── pipeline/               # 管道系统
│   ├── Pipeline.java       # 管道抽象
│   ├── MsgHub.java         # 消息中心
│   └── SequentialPipeline.java
├── memory/                 # 记忆系统
│   ├── Memory.java         # 记忆接口
│   ├── InMemoryMemory.java # 内存记忆
│   └── LongTermMemory.java # 长期记忆
└── hook/                   # 钩子系统
    ├── Hook.java           # 钩子接口
    ├── StreamingHook.java  # 流式钩子
    └── StructuredOutputHook.java # 结构化输出钩子
核心概念
1. 消息系统（Msg）
Msg 是代理间通信的基本单位：


// 创建消息
Msg userMsg = Msg.user("你好，请帮我分析这个数据");
Msg assistantMsg = Msg.assistant("分析结果如下...");

// 消息包含内容块
Msg complexMsg = Msg.builder()
    .role(MsgRole.USER)
    .content(ContentBlock.text("文本内容"))
    .content(ContentBlock.image("base64数据", "image/png"))
    .metadata("key", "value")
    .build();
2. 代理系统（Agents）
所有代理都继承自 AgentBase：

ReActAgent：核心推理-行动代理，实现 ReAct 模式
UserAgent：人机交互代理，支持流式输入
ObservableAgent：可通过事件流观察的代理
StreamableAgent：支持流式响应的代理

// 创建 ReActAgent
ReActAgent agent = ReActAgent.builder()
    .model(model)          // ChatModel 实例
    .name("数据分析师")
    .description("擅长数据分析和可视化")
    .tools(tools)          // 工具列表
    .memory(memory)        // 记忆实例
    .build();

// 调用代理（反应式）
Mono<Msg> response = agent.call(userMsg);

// 流式调用
Flux<Msg> stream = agent.stream(userMsg);
3. 反应式编程模式
绝对禁止在库/代理代码中使用 .block()：


// ✅ 正确 - 反应式链式调用
return model.generate(messages, tools, options)
    .map(response -> processResponse(response))
    .onErrorResume(e -> {
        log.error("操作失败", e);
        return Mono.just(fallbackValue);
    });

// ❌ 错误 - 在代理逻辑中阻塞（永远不要这样做）
String result = model.generate(messages, tools, options).block();

// ✅ 允许 - 仅在 main() 方法中使用
public static void main(String[] args) {
    // ⚠️ .block() 只允许在这里使用
    Msg response = agent.call(userMsg).block();
    System.out.println(response.getTextContent());
}
4. 工具系统
通过 @Tool 注解注册工具：


@Tool(name = "calculator", description = "执行数学计算")
public Mono<String> calculate(
    @ToolParam(description = "数学表达式") String expression) {
    // 计算逻辑
    return Mono.just(result);
}

// 注册工具
ToolRegistry registry = new ToolRegistry();
registry.registerTool(this);
5. 模型集成
支持多种 LLM 提供商：


// 创建模型实例
ChatModel model = OpenAIChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .model("gpt-4")
    .build();

// 或使用 DashScope
ChatModel dashScopeModel = DashScopeChatModel.builder()
    .apiKey(System.getenv("DASHSCOPE_API_KEY"))
    .model("qwen-max")
    .build();
开发工作流
构建和测试

# 构建所有模块
mvn clean compile

# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=ReActAgentTest

# 构建并生成覆盖率报告（CI 标准）
mvn clean verify

# 使用 Maven Daemon 加速构建
mvnd -B -T1 clean verify
代码质量

# 检查代码格式
mvn spotless:check

# 自动修复格式问题
mvn spotless:apply

# 生成 Javadoc
mvn javadoc:javadoc
测试策略
单元测试：使用 JUnit 5 + Reactor 的 StepVerifier 测试反应式流
集成测试：使用 OkHttp 的 MockWebServer 模拟外部服务
覆盖率：JaCoCo 集成，mvn verify 生成报告
示例测试：


@Test
void testAgentCall() {
    ReActAgent agent = createTestAgent();
    
    StepVerifier.create(agent.call(testMsg))
        .expectNextMatches(msg -> 
            msg.getRole() == MsgRole.ASSISTANT)
        .verifyComplete();
}
关键开发约定
🚫 绝对禁止
永远不要在库/代理代码中使用 .block() - 仅允许在 main() 方法或测试代码中
永远不要使用 Thread.sleep() - 使用 Mono.delay() 进行延迟
永远不要使用 ThreadLocal - 使用 Reactor Context 和 Mono.deferContextual()
永远不要硬编码 API 密钥 - 始终使用 System.getenv() 或配置
永远不要静默忽略错误 - 始终使用 .onErrorResume() 或 .onErrorReturn() 处理错误
✅ 始终要做
使用反应式模式 - 使用 .map()、.flatMap()、.then() 链式操作
使用 Builder 模式 - 创建代理、模型和消息
添加日志 - 使用 SLF4J 记录重要操作
使用正确的导入：import io.agentscope.core.model.DashScopeChatModel;（不要使用 io.agentscope.model.*）
遵循 API 约定（参考 SKILL.md 获取详细 API 映射）
环境配置
必需的环境变量

# 模型 API 密钥（示例）
export DASHSCOPE_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
Maven 依赖

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version>1.0.9</version> <!-- 检查最新版本 -->
</dependency>
提交约定
遵循 Conventional Commits 规范：

feat(<scope>): 新功能
fix(<scope>): 错误修复
docs(<scope>): 文档更改
style(<scope>): 代码样式更改
refactor(<scope>): 代码重构
perf(<scope>): 性能改进
ci(<scope>): CI/CD 更改
chore(<scope>): 构建过程或工具更改
示例：


feat(agent): 添加 Claude-3 模型支持
fix(memory): 修复 ReActAgent 中的内存泄漏
docs(readme): 更新安装说明
快速开始示例

public class QuickStart {
    public static void main(String[] args) {
        // 1. 创建模型
        ChatModel model = OpenAIChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .model("gpt-4")
            .build();
        
        // 2. 创建代理
        ReActAgent agent = ReActAgent.builder()
            .model(model)
            .name("助手")
            .description("一个有用的助手")
            .build();
        
        // 3. 发送消息
        Msg userMsg = Msg.user("你好，介绍一下你自己");
        
        // 4. 获取响应（仅在 main 方法中使用 block）
        Msg response = agent.call(userMsg).block();
        
        System.out.println(response.getTextContent());
    }
}
资源
文档：https://java.agentscope.io/
GitHub Issues：https://github.com/agentscope-ai/agentscope-java/issues
SKILL.md：仓库根目录下的详细 API 参考和编码指南
示例：agentscope-examples/ 目录中的完整示例
总结
AgentScope Java 的 agent-core 模块提供了一个强大、反应式的代理框架。关键要点：

始终使用反应式编程，避免阻塞操作
理解消息系统是代理间通信的基础
掌握工具系统如何扩展代理能力
遵循项目约定，特别是禁止使用 .block()
利用现有的测试基础设施确保代码质量
欢迎加入 AgentScope 社区，祝你开发愉快！