AgentScope Java2.0 版本Builder 本地启动指南

项目地址：https://github.com/agentscope-ai/agentscope-java

一、环境要求

依赖	最低版本	验证命令
JDK	17+	`java -version`
Maven	3.8+	`mvn -version`
Node.js	18+	`node -v`
npm	8+	`npm -v`

二、设置环境变量

复制代码

# 必须: DashScope API Key (用于调用 qwen-max 模型)
export DASHSCOPE_API_KEY=你的key

# 可选: 覆盖默认配置
# export BUILDER_MODEL_NAME=qwen-max          # 模型名称
# export BUILDER_WORKSPACE=/path/to/workspace # 工作目录 (默认当前目录)
# export BUILDER_JWT_SECRET=your-secret-key   # JWT 签名密钥 (开发环境有默认值)

三、编译

复制代码

# 进入项目根目录
cd agentscope-java/

# 首次编译: 编译 Builder 及其所有依赖模块 (跳过测试, 约 2--5 分钟)
mvn clean install -DskipTests -pl agentscope-examples/agents/agentscope-builder -am

# 后续仅修改 Builder 代码时: 只编译 Builder 模块 (约 20 秒)
mvn clean package -DskipTests -pl agentscope-examples/agents/agentscope-builder

编译产物：

agentscope-examples/agents/agentscope-builder/target/agentscope-builder-2.0.0-SNAPSHOT.jar（约 149MB）

四、启动

复制代码

cd agentscope-examples/agents/agentscope-builder
java -jar target/agentscope-builder-2.0.0-SNAPSHOT.jar

启动成功标志：

复制代码

INFO ... BuilderApp : Started BuilderApp in 9.407 seconds
INFO ... BuilderBootstrap ! AgentBootstrap: cwd=..., main=default, agents=[default]
INFO ... BuilderConfig : BuilderBootstrap initialized: chatui dmScope=PER_PEER

访问地址：http://localhost:8080

五、登录

用户名	密码	说明
bob	bob	演示用户 1
alice	alice	演示用户 2

种子数据来自 src/main/resources/data-h2.sql，H2 MERGE INTO 幂等写入

六、⚠️ 已知问题与修复

问题 1：启动报错 RemoteFilesystemSpec + InMemoryAgentStateStore 不兼容

错误信息：

复制代码

java.lang.IllegalStateException: filesystem(RemoteFilesystemSpec) is designed for distributed / multi-replica deployments, but the effective AgentStateStore is a local in-process implementation (JsonFileAgentStateStore / InMemoryAgentStateStore).

原因：BuilderConfig.java 硬编码使用了 RemoteFilesystemSpec（分布式文件系统），但本地开发没有配置分布式 AgentStateStore（如 Redis），HarnessAgent 的安全检查拒绝了这个组合

修复方案（2 处改动）：

改动 1：application.yml --- 添加 fs-spec 配置项

修改前：

复制代码

workspace-store:
  local:
    max-file-size-mb: 10

修改后：

复制代码

workspace-store:
  fs-spec: ${BUILDER_WORKSPACE_FS_SPEC:local} # -- 新增, 默认 local
  local:
    max-file-size-mb: 10

改动 2：BuilderConfig.java --- 按 fs-spec 条件加载文件系统

新增字段：

复制代码

@Value("${builder.workspace-store.fs-spec:remote}")
private String fsSpec;

修改 configureAllAgents 逻辑：

复制代码

builder.configureAllAgents(b -> {
    b.middleware(new ToolNotificationMiddleware(eventBus));
    b.stateStore(stateStore);
    // 仅分布式 (sandbox/remote) 才使用 RemoteFilesystemSpec
    if (!"local".equalsIgnoreCase(fsSpec)) {
        b.filesystem(
            new RemoteFilesystemSpec(baseStore)
                .isolationScope(IsolationScope.USER)
                .addSharedPrefix("activity/")
        );
    }
});

修改后重新编译即可。

问题 2：Spotless 代码格式违规构建失败

构建失败的原因是 spotless-maven-plugin

解决方法，全局执行：

复制代码

mvn spotless:apply

七、数据存储

存储	位置	说明
H2 数据库	`~/.agentscope-builder/db.*`	用户、Agent、分享等元数据
Agent 配置	`~/.agentscope/builder/agentscope.json`	Agent 定义（首次启动自动生成）
Agent 会话状态	内存（`InMemoryAgentStateStore`）	重启后丢失，生产需配置 Redis

八、常用操作命令

复制代码

# ====== 启动 ======
cd agentscope-examples/agents/agentscope-builder
java -jar target/agentscope-builder-2.0.0-SNAPSHOT.jar

# ====== 后台启动 ======
java -jar target/agentscope-builder-2.0.0-SNAPSHOT.jar > /tmp/builder-app.log 2>&1 &

# ====== 查看日志 ======
tail -f /tmp/builder-app.log

# ====== 检查端口 ======
lsof -i :8080

# ====== 健康检查 ======
curl http://localhost:8080/actuator/health

# ====== 停止 ======
pkill -f agentscope-builder

# ====== 清理重建 ======
pkill -f agentscope-builder
cd ../../../ # 回到 agentscope-java 根目录
mvn clean install -DskipTests -pl agentscope-examples/agents/agentscope-builder -am
cd agentscope-examples/agents/agentscope-builder
java -jar target/agentscope-builder-2.0.0-SNAPSHOT.jar

九、自动生成的 agentscope.json

首次启动会在 ~/.agentscope/builder/agentscope.json 生成默认配置：

复制代码

{
  "main": "default",
  "agents": {
    "default": {
      "name": "builder-agent",
      "sysPrompt": "You are a helpful assistant built with AgentScope Builder...",
      "maxIters": 10,
      "model": "qwen-max"
    }
  }
}

可直接编辑此文件修改 Agent 的系统提示词、最大推理轮数等参数，重启后生效。

十、切换到 MySQL / PostgreSQL

复制代码

# 激活 jdbc profile
java -jar target/agentscope-builder-2.0.0-SNAPSHOT.jar \
--spring.profiles.active=jdbc \
--BUILDER_DB_URL=jdbc:mysql://localhost:3306/builder \
--BUILDER_DB_USER=root \
--BUILDER_DB_PASSWORD=your_password \
--BUILDER_DB_DRIVER=com.mysql.cj.jdbc.Driver

或通过环境变量：

复制代码

export SPRING_PROFILES_ACTIVE=jdbc
export BUILDER_DB_URL=jdbc:mysql://localhost:3306/builder
export BUILDER_DB_USER=root
export BUILDER_DB_PASSWORD=your_password
export BUILDER_DB_DRIVER=com.mysql.cj.jdbc.Driver

十一、前端开发模式

如果需要修改前端代码并热更新：

复制代码

cd agentscope-examples/agents/agentscope-builder/frontend

# 安装依赖
npm install

# 启动 Vite 开发服务器 (自动代理 /api → localhost:8080)
npm run dev

# 访问 http://localhost:5173 (Vite 默认端口)

前端构建产物输出到 src/main/resources/static/，打包进 Fat JAR。

十二、故障排查

问题	排查方向
端口 8080 被占用	`lsof -i :8080` 找到占用进程，kill 或更换端口
编译失败找不到依赖	确保先执行了 `-am` 编译所有依赖模块
启动后无法登录	检查 H2 数据库是否创建：`ls ~/.agentscope-builder/db.*`
聊天无响应	检查 `DASHSCOPE_API_KEY` 是否有效：curl 调用 DashScope API 验证
RemoteFilesystemSpec 报错	确认已应用上述 `fs-spec: local` 修复
前端页面空白	确认 `src/main/resources/static/index.html` 存在（前端已构建）