AgentScope Builder 项目总结

一、项目定位

AgentScope Builder 是 AgentScope 生态中的 多租户自演化智能体托管平台。它是 agentscope-claw（单用户版）的"多租户版本"，让整个团队或公司可以通过浏览器共享使用。

核心理念：用户通过浏览器 UI 点几下即可创建智能体，无需编写代码或 Maven 构建。选择 skills、subagents、tools 和 MCP servers，保存即得到一个可运行的智能体。

特性	说明
用户模式	多用户 — 每个认证用户有独立 workspace
隔离机制	按 (userId, agentId) 命名空间隔离 workspace
自演化	✅ 同 claw — 但在每个用户自己的 workspace 内
分享	✅ 三级权限：run-only / edit / fork
文件系统	CompositeFilesystem — local / sandbox(Docker) / remote(Redis/OSS) 三种模式

---

二、前后端协作架构

整体架构如下：

┌─────────────────────────────────────────────────────────────────────┐
│  AgentScope Builder (Spring Boot, port 8080)                        │
│                                                                     │
│   React SPA ──▶  REST API (JWT)                                     │
│                  │                                                  │
│                  ▼                                                  │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │  HarnessGateway                                              │  │
│   │   ├─ Agent (alice, agent-A) ──┐                              │  │
│   │   ├─ Agent (alice, agent-B)   │  HarnessAgent per (user,id)  │  │
│   │   └─ Agent (bob,   agent-A) ──┘                              │  │
│   └──────────────────────────────────┬───────────────────────────┘  │
│                                      ▼                              │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │  CompositeFilesystem  (per-(userId, agentId) namespace)      │  │
│   └──────────────────────────────────────────────────────────────┘  │
│   User & agent records  (H2 by default; MySQL/PG for prod)         │
└─────────────────────────────────────────────────────────────────────┘

1. 前端（React SPA）

• 技术栈: React 18 + TypeScript + Vite + react-router-dom 6

• 位置: frontend/src/

• 路由结构 (见 main.tsx):

  • /login — 登录页
  • /agents — Agent 列表 Hub（需认证）
  • /agents/new — 创建 Agent
  • /agents/:id/chat — 聊天页面（核心交互）
  • /agents/:id/workspace — Workspace 文件管理
  • /agents/:id/skills — 技能管理
  • /agents/:id/tools — 工具/MCP 管理
  • /agents/:id/subagents — 子 Agent 管理
  • /agents/:id/channels — Channel 绑定（钉钉/飞书等）
  • /agents/:id/sessions — Session 收件箱
  • /agents/:id/settings — Agent 设置
  • /agents/:id/activity — 操作日志
  • /channels, /marketplaces, /admin/users, /profile — 管理页面

• 认证流程: JWT 存储在 localStorage (claw_token)，每次请求通过 Authorization: Bearer <token> 传递。PrivateRoute 组件在挂载时调用 /api/auth/me 验证 token 是否有效，失效则清除并跳转 /login。

2. 后端（Spring Boot）

• 入口: BuilderApp.java — Spring Boot 主类
• 核心编排: BuilderBootstrap.java — 负责 Agent 构建、Gateway 连接、Session 管理

3. 前后端交互方式

所有 API 以 /api/ 为前缀，前端通过 15 个 API 模块与后端通信：

API 模块	关键端点	交互方式
auth.ts	/api/auth/login, /api/auth/me	POST (JSON) → JWT token
agents.ts	/api/agents, CRUD + /api/agents/draft	REST (JSON)
chat.ts	/api/agents/{id}/chat/stream	SSE 流式 (核心)
workspace.ts	/api/agents/{id}/workspace/file, tree, upload	REST + multipart
skills.ts	/api/agents/{id}/skills/workspace	REST (JSON)
tools.ts	/api/agents/{id}/tools/active, config, catalog	REST (JSON)
shares.ts	/api/agents/{id}/shares	REST (JSON)
sessions.ts	/api/agents/{id}/sessions	REST (JSON)
channels.ts	/api/channels/*	REST (JSON)
marketplaces.ts	/api/marketplaces/*	REST (JSON)
templates.ts	/api/templates/*	REST (JSON)
clone.ts	/api/agents/{id}/clone	POST (JSON)
activity.ts	/api/agents/{id}/activity	REST (JSON)
admin.ts	/api/admin/users/*	REST (JSON)
subagents.ts	/api/agents/{id}/subagents/*	REST (JSON)

聊天交互是核心的 SSE 流式通信（见 chat.ts 的 stream() 函数）：

前端 → POST /api/agents/{id}/chat/stream  { message, sessionKey }
后端 → SSE 事件流:
        data: {"type":"token","data":"我"}       ← 流式 token
        data: {"type":"tool_call","toolName":"execute","toolInput":"..."}
        data: {"type":"tool_result","toolResult":"..."}
        data: {"type":"done","sessionKey":"xxx"}
        data: {"type":"error","error":"..."}

前端用 fetch + ReadableStream 逐块读取 SSE 事件，解析 data: 行并 yield 给 React 组件渲染。

4. SPA 与 Spring Boot 的集成方式

前端通过 frontend-maven-plugin 在 Maven 构建时自动执行 npm install + vite build，产物输出到 frontend/dist/，然后由 Spring Boot 的 SpaWebMvcConfig 配置将所有非 /api/ 请求重定向到 index.html，实现 SPA serving。

即：同一个 8080 端口既服务 React SPA 静态文件，又提供 REST/SSE API。

5. 多租户隔离机制

• 每个 (userId, agentId) 组合有独立的 SessionAgentManager 和命名空间
• Workspace 路径格式: users/{userId}/agents/{agentId}/
• ChatController 在处理请求时通过 JWT 解析出 userId，与 agentId 组合构成会话 key
• 分享体系：三级权限 RUN（只能用）/ EDIT（可改）/ CLONE（可 fork），通过 AgentShareController 管理

6. 数据持久化

• 默认使用嵌入式 H2，自动播种 admin/admin, bob/bob, alice/alice 三个账户
• 生产环境可通过 jdbc Spring Profile 切换到 MySQL/PostgreSQL
• Agent 定义存储在 ~/.agentscope/builder/agentscope.json + H2 数据库