项目地址https://github.com/agentscope-ai/agentscope-java一、环境要求依赖最低版本验证命令JDK17java -versionMaven3.8mvn -versionNode.js18node -vnpm8npm -v二、设置环境变量# 必须: DashScope API Key (用于调用 qwen-max 模型) export DASHSCOPE_API_KEY你的key # 可选: 覆盖默认配置 # export BUILDER_MODEL_NAMEqwen-max # 模型名称 # export BUILDER_WORKSPACE/path/to/workspace # 工作目录 (默认当前目录) # export BUILDER_JWT_SECRETyour-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..., maindefault, agents[default] INFO ... BuilderConfig : BuilderBootstrap initialized: chatui dmScopePER_PEER访问地址http://localhost:8080五、登录用户名密码说明bobbob演示用户 1alicealice演示用户 2种子数据来自src/main/resources/data-h2.sqlH2 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如 RedisHarnessAgent的安全检查拒绝了这个组合修复方案2 处改动改动 1application.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改动 2BuilderConfig.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/) ); } });修改后重新编译即可。问题 2Spotless 代码格式违规构建失败构建失败的原因是spotless-maven-plugin解决方法全局执行mvn spotless:apply七、数据存储存储位置说明H2 数据库~/.agentscope-builder/db.*用户、Agent、分享等元数据Agent 配置~/.agentscope/builder/agentscope.jsonAgent 定义首次启动自动生成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 21 # 查看日志 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.activejdbc \ --BUILDER_DB_URLjdbc:mysql://localhost:3306/builder \ --BUILDER_DB_USERroot \ --BUILDER_DB_PASSWORDyour_password \ --BUILDER_DB_DRIVERcom.mysql.cj.jdbc.Driver或通过环境变量export SPRING_PROFILES_ACTIVEjdbc export BUILDER_DB_URLjdbc:mysql://localhost:3306/builder export BUILDER_DB_USERroot export BUILDER_DB_PASSWORDyour_password export BUILDER_DB_DRIVERcom.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存在前端已构建