OldSixLi

AgentScope Paw 项目总结

一、项目定位与作用

AgentScope Paw 是 [QwenPaw] 的 Java 移植版，定位为 个人本地助手——安装在你自己的机器上，以你的身份运行在你的文件系统和 Shell 上。

一句话概括：你的私人 Agent，装在你电脑上，会越用越聪明，还能从钉钉/企微/飞书/GitHub/GitLab 聊天直达。

核心设计取舍：

Paw 的选择	说明
无登录	单用户，打开浏览器就用
无多租户隔离	全权访问你的 shell 和文件系统
无 Docker sandbox	直接在你的 OS 上执行命令
无横向扩展	单进程单节点
有自演化	Skills/子Agent/Memory 都是 workspace 中的文件，Agent 自己维护

与 sibling 项目对比：

项目	定位	用户	隔离	沙箱	分布式
paw	个人本地助手	单人	无	无	❌
builder	多租户 Agent 托管平台	团队	per-(user,agent)	Docker可选	✅
codingagent	自治代码机器人	组织	per-session Docker	Docker(运行时自管)	✅
dataagent	数据分析 Agent 产品	团队	per-(user,agent)	运维方自管	✅

历史渊源：Paw 早期曾支持多租户/JWT/Docker 等功能，后来这些能力被剥离到 builder 项目中，Paw 重新回归"纯粹个人助手"定位。代码包名仍为 io.agentscope.claw2（内部代号 claw），这是历史遗留。

二、它是如何工作的

整体架构

┌─────────────────────────────────────────────────────────────────┐
│                          你的电脑                                │
│  ┌─────────────────────┐   ┌─────────────────────────────────┐  │
│  │  Channels           │   │  HarnessAgent (per agent)       │  │
│  │  ├ chatui (web UI)  │──▶│   ├ Reasoning (LLM)             │  │
│  │  ├ dingtalk         │   │   ├ Skills · Sub-agents · MCP   │  │
│  │  ├ wecom · feishu   │   │   └ Self-evolution loop         │  │
│  │  └ github · gitlab  │   └────────────┬────────────────────┘  │
│  └─────────────────────┘                ▼                       │
│                          ┌──────────────────────────────────┐   │
│                          │  LocalFilesystemWithShell        │   │
│                          │   ├ Host FS  (~/.agentscope/...) │   │
│                          │   └ Host shell (bash / zsh)      │   │
│                          └──────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

极简设计：HarnessAgent → LocalFilesystemWithShell → 你的电脑，中间没有任何认证层、沙箱层或远程存储层。

核心工作流程

1. 启动即用

bash

export DASHSCOPE_API_KEY=sk-xxx
java -jar agentscope-paw-*.jar

打开 http://localhost:8080，无需登录，直接进入 Agent 列表
首次运行自动在 ~/.agentscope/ 创建 default agent + agentscope.json

2. 聊天交互（SSE 流式）

与 builder/dataagent 相同的 SSE 流式机制：

前端 → POST /api/agents/{id}/chat/stream  { message }
后端 → SSE 事件流:
        token | tool_call | tool_result | done | error

你可以让 Agent 在你的电脑上做任何事情——执行 shell 命令、读写文件、安装软件等，因为它使用 LocalFilesystemWithShell，直接访问宿主 OS。

3. 自演化机制

Agent 的 "成长" 全靠 workspace 中的文件：

~/.agentscope/agents/<agentId>/workspace/
  ├── AGENTS.md            ← Agent 自己维护的行为准则
  ├── skills/              ← 学到的技能（Markdown + 资源文件）
  ├── subagents/           ← 生出的子 Agent
  ├── memory/              ← 记忆（MEMORY.md + 日志）
  └── tools.json           ← MCP/自定义工具配置

Agent 通过 WorkspaceManager API 读写这些文件，每次对话都可能更新它们——这就是"越用越聪明"的原理。

4. 通道体系——你在哪里，Agent 就在哪里

Paw 最突出的能力是 6 种内置通道，开箱即用：

通道	传输方式	需要公网?	适用场景
`chatui`	in-process SSE	❌	Web 前端（始终在线）
`dingtalk`	Stream WebSocket	❌	钉钉 DM/群聊（无需公网 URL）
`wecom`	HTTP callback + REST	✅	企微 DM/群聊
`feishu`	HTTP event + REST	✅	飞书/Lark DM/群聊
`github`	Webhook + REST	✅	GitHub Issue/PR 评论
`gitlab`	Webhook + REST	✅	GitLab Issue/MR 评论

配置方式：在 ~/.agentscope/agentscope.json 的 channels 块中添加通道配置，启动后自动生效。

5. Outbound 主动推送

每个 Agent 自动注册 outbound_send 工具，两种使用方式：

HTTP API：POST /api/outbound/send — 外部系统主动推送消息到 IM
Agent 工具：让 Agent 在对话中主动调用 outbound_send 发消息到钉钉/企微等

子 Agent 完成后，HarnessGateway 自动回用发起方的通道 OutboundAddress，结果通知自然回到同一个 IM 对话中。

6. 可靠性保障（始终开启）

机制	说明
幂等去重	按 `<channelId
Bot 循环保护	每个对端 20 事件/60s，超限冷却 60s
签名验证	WeCom SHA1、GitHub HMAC、飞书 AES-256-CBC
Token 自动刷新	在 80% TTL 时主动刷新 access token
自评论过滤	GitHub/GitLab 自动过滤自己账号发出的评论

前端（React SPA）

13 个页面，10 个 API 模块
无登录/认证——打开就用，没有 PrivateRoute 也没有 LoginPage（对比 builder/dataagent 需要 JWT 登录）
路由结构：
- /agents — Agent 列表 Hub
- /agents/new — 创建 Agent（空白/模板/AI 草稿）
- /agents/:id/chat — 聊天页面
- /agents/:id/workspace — 文件管理
- /agents/:id/skills — 技能管理
- /agents/:id/subagents — 子 Agent 管理
- /agents/:id/tools — 工具/MCP 管理
- /agents/:id/sessions — Session 管理
- /agents/:id/channels — 通道绑定
- /agents/:id/settings — Agent 设置
- /channels — 通道管理 Hub
- /channels/:channelId — 通道详情

双类 Agent 体系

类型	存储	说明
Built-in Agent	`~/.agentscope/agentscope.json`	只读，编辑 JSON 文件修改
Custom Agent	`~/.agentscope/agents.json`	通过 UI 或 `POST /api/agents` 创建

创建方式：空白脚手架 / 内置模板 / AI 草稿（POST /api/agents/draft，LLM 生成 Agent 定义 JSON）

数据持久化

无数据库（对比 builder/dataagent 用 H2/JPA）
所有状态都是文件：
- agentscope.json — 内置 Agent 定义
- agents.json — 自定义 Agent 目录
- sessions.json — per-agent session 索引
- workspace 文件 — 技能/子Agent/记忆/工具配置

配置与目录

~/.agentscope/                  ← paw.home（可通过 PAW_HOME 覆盖）
  ├── agentscope.json           ← 内置 Agent + 通道配置
  ├── agents.json               ← 自定义 Agent 目录
  └── agents/<agentId>/workspace/ ← 每个 Agent 的 workspace
      ├── AGENTS.md, skills/, subagents/, memory/, tools.json
      └── agents/<subId>/        ← 子 Agent 的 workspace

Paw vs Builder 关键差异

特性	Paw	Builder
登录/认证	❌ 无	✅ JWT + Spring Security
多租户	❌ 单用户	✅ per-(userId, agentId)
沙箱	❌ LocalFilesystemWithShell	✅ Docker sandbox 可选
分布式	❌ 单进程	✅ Redis 共享状态
数据库	❌ 纯文件	✅ H2 → MySQL/PG
Agent 分享	❌	✅ 三级权限(RUN/EDIT/CLONE)
Marketplace	✅ 技能市场(git/nacos)	✅ Marketplace(git/nacos)
前端认证	❌ 无 PrivateRoute	✅ JWT + PrivateRoute
包名/前缀	`io.agentscope.claw2` / `claw.*`	`io.agentscope.builder` / `builder.*`

三、一句话总结

Paw = 纯粹的个人本地助手：装在你电脑上，直接访问你的 shell 和文件系统，会自演化（技能/子Agent/记忆），开箱支持 6 种 IM/DevOps 通道（钉钉/企微/飞书/GitHub/GitLab），无需登录、无沙箱、无分布式——所有复杂场景交给 builder/dataagent/codingagent 去做。

AgentScope Paw 项目总结 ​

一、项目定位与作用 ​

二、它是如何工作的 ​

整体架构 ​

核心工作流程 ​

前端（React SPA） ​

双类 Agent 体系 ​

数据持久化 ​

配置与目录 ​

Paw vs Builder 关键差异 ​

三、一句话总结 ​