OldSixLi

AgentScope DataAgent 项目总结

一、项目定位与作用

agentscope-dataagent 是 AgentScope 生态中的 多租户数据分析 Agent 产品——让公司里每位数据分析师都有一个属于自己的、持续进化的数据 Agent。

一句话概括：每个分析师拥有私有 Agent，它能学 SQL、画图表、写报告，越用越聪明；好技能还能通过能力市场共享给全团队。

三大设计理念：

理念	说明
并行进化、互不干扰	每个用户有私有 workspace，技能/记忆/子 Agent 不会溢出到别人那里
能力市场（Marketplace）	用户贡献好技能 → 管理员审批 → 全团队自动获取
沙箱由你掌控	与 codingagent（运行时自管容器）不同，dataagent 把沙箱生命周期交给运维方

与 sibling 项目对比：

项目	定位	核心场景
claw	单用户自演化 Agent	个人 shell 使用
builder	多租户 Agent 托管平台	任意 Agent 的 UI 构建/管理
codingagent	自治代码机器人	GitHub Issue/PR 自动编码
dataagent	数据分析 Agent 产品	SQL 查询、图表渲染、报告撰写

二、它是如何工作的

整体架构

┌───────────────────────────────────────────────────────────────────────┐
│  agentscope-dataagent (port 8080, Spring Boot WebFlux)                │
│                                                                       │
│   React SPA ──▶ REST API (JWT)                                        │
│                  │                                                    │
│                  ▼                                                    │
│   ┌─────────────────────────────────────────────────────────────────┐ │
│   │  HarnessGateway                                                 │ │
│   │   ├ data-agent              (内置骨架, GLOBAL)                   │ │
│   │   └ uda-{userId}-{agentId}  (per-用户 fork, per-租户)           │ │
│   └────────────────────────┬────────────────────────────────────────┘ │
│                            ▼                                          │
│   ┌─────────────────────────────────────────────────────────────────┐ │
│   │  Per-(userId, agentId) 文件系统栈                                │ │
│   │   ┌──────────────────────────────────────────────────────────┐  │ │
│   │   │ OverlayFilesystem (skills/, subagents/)                  │  │ │
│   │   │   ┌── upper: per-user RemoteFilesystem  (可写) ──────┐   │  │ │
│   │   │   └── lower: shared/{skills,subagents}    (只读)      │   │  │ │
│   │   └──────────────────────────────────────────────────────────┘  │ │
│   │   memory/, MEMORY.md, sessions/, tasks/  ← per-user RemoteFS    │ │
│   │   knowledge/, AGENTS.md                  ← shared (只读)         │ │
│   │   SandboxFilesystem (脚本执行)                                  │ │
│   │     ▲ 生命周期由应用方管理（非运行时自管）                        │ │
│   └─────────────────────────────────────────────────────────────────┘ │
│                                                                       │
│   Marketplace:  用户贡献 ─▶ 管理员审批 ─▶ shared/ 扩充               │
│   Channels:     chatui · dingtalk · generic webhook                   │
│   Storage:      H2(默认) / MySQL/PG(生产)                             │
└───────────────────────────────────────────────────────────────────────┘

核心工作流程

1. 用户登录 → 获得私有 Agent

浏览器访问 http://localhost:8080 → 登录（默认 bob/bob, alice/alice）
每个 (userId, agentId) 组合拥有独立的 HarnessAgent 实例
首次使用时自动 fork 内置 data-agent，创建私有 workspace

2. 聊天交互（SSE 流式）

前端 → POST /api/chat/stream  { message }
后端 → SSE 事件流:
        data: {"type":"token","data":"查询结果如下..."}
        data: {"type":"tool_call","toolName":"run_sql_preview","toolInput":"..."}
        data: {"type":"tool_result","toolResult":"..."}
        data: {"type":"done","sessionKey":"xxx"}

用户可以问："昨天有多少用户注册？"、"帮我画一个月度趋势图"、"写一份运营周报"

3. Agent 执行数据处理

内置 data-agent 拥有专属工具集：

工具	功能
`list_data_sources`	列出可访问的数据源
`describe_table`	查看表结构
`run_sql_preview`	执行 SQL 查询（预览）
`render_chart`	渲染图表
`contribute_to_workspace`	将好技能贡献到共享目录

这些工具是 SPI 接口（v1 提供 stub + InMemoryDataSourceRegistry），具体的 JDBC 连接器和图表渲染器通过 Spring Bean 插入。

4. OverlayFilesystem——私有 + 共享的融合

这是 dataagent 最独特的设计：

skills/ 目录：
  ├── upper: per-user RemoteFilesystem  ← 用户自己写的/学的技能（可写）
  └── lower: shared/skills/             ← 管理员审批通过的共享技能（只读）

用户看到的是 两层合并后的视图
用户只能写 upper 层（自己的技能）
lower 层（共享技能）只读，修改必须走 Marketplace 贡献流程
同理 subagents/ 也是 Overlay 结构

5. Marketplace 能力市场流程

用户在 workspace 写了一个好技能 "cohort-builder"
  ↓
提交贡献: POST /api/me/contributions  { targetType: "skill", targetPath: "cohort-builder/SKILL.md" }
  ↓
管理员审批: POST /api/admin/contributions/{id}/approve
  ↓
技能写入: ~/.agentscope/dataagent/workspace/shared/skills/cohort-builder/SKILL.md
  ↓
所有用户的 Overlay 下层自动更新，无需重启

文件系统分层详解

路径	挂载方式	说明
`memory/`, `MEMORY.md`, `sessions/`, `tasks/`	`RemoteFilesystem` (per-user)	完全私有，按 `(userId, agentId)` 命名空间隔离
`skills/`, `subagents/`	`OverlayFilesystem`	上层私有(可写) + 下层共享(只读)
`knowledge/`, `AGENTS.md`	共享目录 (只读)	修改只能通过 Marketplace 贡献流程
脚本执行	`SandboxFilesystem`	隔离沙箱，生命周期由运维方控制

双层 Agent 体系

Agent	类型	说明
`data-agent`	GLOBAL（内置骨架）	SQL 分析、图表渲染、数据探索、报告撰写
`uda-{userId}-{agentId}`	per-用户 fork	每个 fork 有独立 workspace，独立进化
`data-explorer`	子 Agent	嵌入在主 Agent 中，负责数据探索
`report-writer`	子 Agent	嵌入在主 Agent 中，负责报告撰写

通道（Channel）体系

Channel	传输方式	适用场景
ChatUI	SSE 流式（始终在线）	Web 前端主要交互
DingTalk	Stream WebSocket	IM 聊天（无需公网 URL）
Webhook	HMAC 签名的 HTTP	外部系统接入（回调/长轮询）

Webhook 通道的交互模式：

callback：结果 POST 回 callbackUrl
poll：结果存放在 GET /api/webhook/{channelId}/outbound/{inboundId} 等待拉取

沙箱策略差异

项目	沙箱生命周期	谁管
codingagent	运行时自管（per-session Docker，自动创建/销毁）	Agent 运行时
dataagent	应用方掌控（运维方配置驱动/回收策略）	运维人员

这意味着运维可以决定沙箱用什么镜像、装什么驱动（JDBC、notebook 工具）、回收频率。

分布式部署

dataagent 从第一天就为分布式设计：

开启 Redis (dataagent.session.redis.enabled=true) 后：
- RemoteFilesystem 写入走 Redis → 多副本间 workspace 互通
- ToolEventBus 变为 Redis Pub/Sub → SSE 消费者可在任意副本看到 tool_call 事件
- 无需 sticky session，任意副本可服务任意用户

前端（React SPA）

25 个页面，15 个 API 模块
路由结构：
- /chat — 主聊天页面（核心交互）
- /workspace — Workspace 文件浏览（RUN 权限也可读）
- /configure/* — Skills/Subagents/Channels/Tools/Settings 配置（需 EDIT 权限）
- /contributions — 贡献提交页面
- /admin/* — 管理员页面（Overview/Approvals/Instances/Sessions/Users/Usage 等）
EditTierGate 组件：只允许 EDIT 权限用户进入配置页面
AdminRoute 组件：只允许 ADMIN 角色进入管理页面

认证与权限

JWT 认证（存储在 localStorage 的 claw_token）
H2 默认播种 bob/bob、alice/alice + 一个 ADMIN 用户
生产环境切换 MySQL/PG（激活 jdbc Spring Profile）
三级 Agent 分享权限：RUN（只可用）/ EDIT（可配置）/ CLONE（可 fork）

三、一句话总结

DataAgent = 多租户数据分析 Agent 产品：每位分析师拥有独立进化的数据 Agent（SQL + 图表 + 报告），私有技能只属于自己，好技能通过 Marketplace 审批后全团队共享。沙箱由运维方掌控而非运行时自管，天然支持 Redis 分布式部署。

AgentScope DataAgent 项目总结 ​

一、项目定位与作用 ​

二、它是如何工作的 ​

整体架构 ​

核心工作流程 ​

文件系统分层详解 ​

双层 Agent 体系 ​

通道（Channel）体系 ​

沙箱策略差异 ​

分布式部署 ​

前端（React SPA） ​

认证与权限 ​

三、一句话总结 ​