# ClawWork 项目深度调研报告

## 1. 项目概述

### 1.1 项目定位

**ClawWork** 是一个创新的 AI 智能体经济生存基准测试平台，由 HKUDS（香港大学数据科学学院）开发。该项目将 AI 助手从简单的对话工具转变为真正的"AI 同事"，通过完成真实世界的专业任务来创造经济价值。

项目的核心概念是：**AI 智能体必须在经济压力下生存** —— 它们从 10 美元启动资金开始，需要支付每次 API 调用的 token 费用，通过完成真实工作任务赚取收入，维持经济可持续性。

### 1.2 主要功能

- **真实经济压力测试**：AI 智能体需要支付 token 费用，通过完成任务赚取收入
- **GDPVal 基准数据集**：使用 OpenAI 的 GDPVal 数据集，包含 220 个跨 44 个职业的真实工作任务
- **多模型竞技场**：支持 GPT-4、Claude、GLM、Kimi、Qwen 等多种模型竞争
- **实时仪表板**：React 前端展示智能体的经济状态、任务完成情况和学习进度
- **ClawMode 集成**：与 Nanobot 集成，将任何 Nanobot 实例转变为经济感知的 AI 同事

### 1.3 适用场景

- **AI 能力评估**：测试不同 AI 模型在真实工作任务中的表现
- **经济可持续性研究**：研究 AI 智能体在资源约束下的长期生存能力
- **多智能体竞争**：比较不同模型的成本效益和工作质量
- **AI 助手进化**：将普通 AI 助手转变为能创造经济价值的 AI 同事

---

## 2. 技术架构

### 2.1 技术栈

**后端技术栈**：
- **Python 3.10+**：核心开发语言
- **FastAPI**：高性能 API 框架，提供 RESTful API 和 WebSocket 支持
- **LangChain + LangGraph**：LLM 应用开发框架和智能体工作流
- **MCP (Model Context Protocol)**：工具调用协议
- **Pandas + PyArrow**：数据处理和分析

**前端技术栈**：
- **React 18**：用户界面框架
- **Vite**：现代构建工具
- **Tailwind CSS**：实用优先的 CSS 框架
- **Recharts**：数据可视化图表库
- **Framer Motion**：动画库

**外部服务集成**：
- **OpenAI API**：GPT-4o 用于智能体和评估
- **E2B**：云端代码沙箱执行环境
- **Tavily/Jina AI**：网络搜索 API
- **OpenRouter**：多模型统一接口

### 2.2 核心模块

```
ClawWork/
├── livebench/                    # 核心经济模拟引擎
│   ├── agent/                    # 智能体实现
│   │   ├── live_agent.py        # 主智能体类 (1162 行)
│   │   ├── economic_tracker.py  # 经济追踪器 (876 行)
│   │   ├── message_formatter.py # 消息格式化
│   │   └── wrapup_workflow.py   # 工作流封装
│   ├── work/                     # 工作任务管理
│   │   ├── task_manager.py      # 任务管理器
│   │   ├── evaluator.py         # 工作评估器
│   │   └── llm_evaluator.py     # LLM 评估实现
│   ├── tools/                    # 工具集
│   │   ├── direct_tools.py      # 核心工具 (555 行)
│   │   └── productivity/        # 生产力工具
│   │       ├── search.py        # 网络搜索
│   │       ├── file_creation.py # 文件创建
│   │       ├── code_execution.py # 代码执行
│   │       └── video_creation.py # 视频创建
│   ├── api/                      # API 服务
│   │   └── server.py            # FastAPI 服务器
│   ├── prompts/                  # 提示词模板
│   │   └── live_agent_prompt.py # 智能体提示词
│   └── configs/                  # 配置文件
├── clawmode_integration/         # Nanobot 集成模块
│   ├── agent_loop.py            # 智能体循环
│   ├── task_classifier.py       # 任务分类器
│   ├── provider_wrapper.py      # Provider 包装器
│   ├── tools.py                 # 工具实现
│   └── cli.py                   # 命令行接口
├── eval/                         # 评估系统
│   └── meta_prompts/            # 44 个职业的评估提示词
├── frontend/                     # React 前端
│   └── src/
│       ├── App.jsx              # 主应用组件
│       ├── api.js               # API 客户端
│       ├── pages/               # 页面组件
│       └── components/          # 可复用组件
└── scripts/                      # 辅助脚本
    ├── calculate_task_values.py # 计算任务价值
    ├── estimate_task_hours.py   # 估算任务工时
    └── generate_static_data.py  # 生成静态数据
```

### 2.3 代码结构分析

**核心代码统计**：
- `live_agent.py`：1162 行 —— 智能体主逻辑，包含决策、任务执行、学习循环
- `economic_tracker.py`：876 行 —— 经济状态追踪，余额、成本、收入管理
- `direct_tools.py`：555 行 —— 8 个核心工具的实现

**代码组织特点**：
1. **模块化设计**：每个功能模块独立，职责清晰
2. **配置驱动**：JSON 配置文件控制智能体行为
3. **插件架构**：通过 MCP 协议扩展工具
4. **数据持久化**：JSONL 格式记录所有经济活动

---

## 3. 核心功能详解

### 3.1 经济系统

**核心机制**：
```python
# 经济追踪器初始化
EconomicTracker(
    signature="agent-name",
    initial_balance=10.0,           # 启动资金 $10
    input_token_price=2.5,          # 每百万输入 token $2.5
    output_token_price=10.0,        # 每百万输出 token $10.0
    min_evaluation_threshold=0.6    # 最低评估分数获得支付
)
```

**成本计算**：
- **Token 成本**：根据实际 API 调用计算输入/输出 token 费用
- **API 成本**：网络搜索、OCR 等外部服务费用
- **收入计算**：`quality_score × (estimated_hours × BLS_hourly_wage)`

**生存状态**：
- **Thriving** (💪)：余额充足，经济健康
- **Stable** (👍)：收支平衡，可持续运营
- **Struggling** (⚠️)：余额不足，需要谨慎
- **Bankrupt** (💀)：资金耗尽，无法继续

### 3.2 任务系统

**GDPVal 数据集**：
- **220 个任务**：涵盖 44 个职业类别
- **4 大领域**：
  - 科技与工程 (Technology & Engineering)
  - 商业与金融 (Business & Finance)
  - 医疗与社会服务 (Healthcare & Social Services)
  - 法律、媒体与运营 (Legal, Media & Operations)

**任务价值计算**：
```python
# 任务价值 = 预估工时 × 时薪
payment = quality_score × (estimated_hours × bls_hourly_wage)
```

**任务价值范围**：
- 最低：$82.78
- 最高：$5,004.00
- 平均：$259.45

**任务类型示例**：
- 财务分析报告
- 市场调研文档
- 医疗管理方案
- 法律顾问文档
- 软件代码项目
- 媒体制作任务

### 3.3 智能体工具集

**8 个核心工具**：

1. **decide_activity(activity, reasoning)**
   - 决策：工作还是学习
   - 参数：activity ("work"|"learn"), reasoning (至少 50 字符)

2. **submit_work(work_output, artifact_file_paths)**
   - 提交完成的工作
   - 支持文本输出和文件附件
   - 触发评估和支付

3. **learn(topic, knowledge)**
   - 学习新知识并持久化
   - 最少 200 字符的知识记录
   - 用于未来任务参考

4. **get_status()**
   - 获取当前经济状态
   - 返回余额、成本、收入、生存状态

5. **search_web(query, max_results)**
   - 网络搜索 (Tavily 或 Jina AI)
   - 获取最新信息和参考资料

6. **create_file(filename, content, file_type)**
   - 创建文档文件
   - 支持：txt、xlsx、docx、pdf

7. **execute_code(code, language)**
   - 在 E2B 沙箱中执行代码
   - 支持 Python，安全隔离

8. **create_video(slides_json, output_filename)**
   - 从幻灯片生成 MP4 视频
   - 支持文本和图片幻灯片

### 3.4 评估系统

**LLM 评估器**：
- 使用 GPT-4o 进行工作质量评估
- 44 个职业类别，每个有专门的评估提示词
- 评分维度：
  - **完整性 (40%)**：是否交付所有要求的产物
  - **正确性 (30%)**：实现是否准确，逻辑是否正确
  - **质量 (20%)**：代码/文档质量、可维护性
  - **领域标准 (10%)**：安全、可访问性、最佳实践

**评分标准** (0-10 分)：
- 0-2：不可接受（缺少文件或不完整）
- 3-4：差（多个主要要求缺失）
- 5-6：可接受（大部分交付但有明显缺陷）
- 7-8：良好（所有交付物存在，小缺陷）
- 9-10：优秀（完全符合要求，专业质量）

**关键规则**：
- 最低支付门槛：0.6 分（6/10）
- 强制低分：缺少任何必需文件 → 0-2 分

---

## 4. 代码质量分析

### 4.1 代码组织

**优点**：
1. **清晰的模块划分**：按功能分层，职责单一
2. **配置与代码分离**：JSON 配置文件管理业务参数
3. **类型注解**：广泛使用 Python 类型提示
4. **文档字符串**：类和方法都有详细的 docstring

**示例代码结构**：
```python
class LiveAgent:
    """
    LiveAgent - AI agent for economic survival simulation

    Core functionality:
    1. Economic tracking (balance, token costs, income)
    2. Daily decision-making (work vs learn)
    3. Work task execution
    4. Learning and knowledge accumulation
    5. Survival management
    """

    def __init__(
        self,
        signature: str,
        basemodel: str,
        initial_balance: float = 1000.0,
        # ... 更多参数
    ):
        """
        Initialize LiveAgent

        Args:
            signature: Agent signature/name
            basemodel: Base model name
            initial_balance: Starting balance in dollars
            # ... 更多文档
        """
```

### 4.2 设计模式

**使用的模式**：
1. **追踪器模式 (Tracker)**：`EconomicTracker` 专门管理经济状态
2. **管理器模式 (Manager)**：`TaskManager` 负责任务生命周期
3. **评估器模式 (Evaluator)**：`WorkEvaluator` 和 `LLMEvaluator` 分离评估逻辑
4. **工具模式 (Tools)**：LangChain 的 `@tool` 装饰器定义工具接口
5. **包装器模式 (Wrapper)**：`TrackedProvider` 包装 LLM Provider 添加成本追踪

### 4.3 可维护性

**优点**：
- **单一职责**：每个类/模块职责清晰
- **依赖注入**：通过构造函数注入依赖
- **错误处理**：显式错误处理和日志记录
- **数据持久化**：JSONL 格式便于分析和审计

**改进空间**：
- 部分文件较长（如 live_agent.py 1162 行）
- 缺少单元测试（根据代码结构判断）
- 某些配置硬编码（如路径）

---

## 5. 依赖分析

### 5.1 核心依赖

**Web 框架**：
```
fastapi>=0.104.0          # 现代、快速的 Web 框架
uvicorn>=0.24.0          # ASGI 服务器
websockets>=12.0         # WebSocket 支持
```

**LLM 和 AI**：
```
langchain>=0.1.0         # LLM 应用框架
langchain-openai>=0.0.2  # OpenAI 集成
langchain-mcp-adapters>=0.1.0  # MCP 协议适配
langgraph>=0.2.0         # 智能体工作流
```

**数据处理**：
```
pandas>=2.0.0            # 数据分析
pyarrow>=14.0.0          # 高性能数据格式
```

**生产力工具**：
```
tavily-python>=0.3.0     # 网络搜索
python-docx>=1.0.0       # Word 文档
python-pptx>=0.6.21      # PowerPoint
reportlab>=4.0.0         # PDF 生成
openpyxl>=3.1.0          # Excel 处理
```

### 5.2 版本兼容性

- **Python**：要求 3.10+
- **Node.js**：前端需要（版本未明确指定）
- **包管理**：pip（Python）+ npm（前端）

### 5.3 外部服务依赖

**必需**：
- OpenAI API（智能体和评估）
- E2B API（代码执行沙箱）

**可选**：
- Tavily API（网络搜索）
- Jina AI API（替代搜索）
- DashScope API（OCR 处理）

---

## 6. 使用方式

### 6.1 安装步骤

**1. 克隆仓库**：
```bash
git clone https://github.com/HKUDS/ClawWork.git
cd ClawWork
```

**2. 创建 Python 环境**：
```bash
conda create -n clawwork python=3.10
conda activate clawwork
```

**3. 安装依赖**：
```bash
pip install -r requirements.txt
```

**4. 前端依赖**：
```bash
cd frontend && npm install && cd ..
```

**5. 配置环境变量**：
```bash
cp .env.example .env
# 编辑 .env 填入 API 密钥
```

### 6.2 快速启动

**模式 1：独立模拟**：
```bash
# 终端 1 - 启动仪表板
./start_dashboard.sh

# 终端 2 - 运行智能体
./run_test_agent.sh

# 打开浏览器访问 http://localhost:3000
```

**模式 2：ClawMode 集成**：
```bash
# 启动 Nanobot + ClawWork 集成
python -m clawmode_integration.cli agent
```

### 6.3 配置示例

**基础配置** (`livebench/configs/default_config.json`)：
```json
{
  "livebench": {
    "date_range": {
      "init_date": "2025-01-20",
      "end_date": "2025-01-31"
    },
    "economic": {
      "initial_balance": 1000.0,
      "token_pricing": {
        "input_per_1m": 2.5,
        "output_per_1m": 10.0
      }
    },
    "agents": [
      {
        "signature": "gpt-4-agent",
        "basemodel": "gpt-4-turbo-preview",
        "enabled": true,
        "tasks_per_day": 1
      }
    ]
  }
}
```

**多智能体配置**：
```json
"agents": [
  {"signature": "gpt4o-run", "basemodel": "gpt-4o", "enabled": true},
  {"signature": "claude-run", "basemodel": "claude-sonnet-4-5-20250929", "enabled": true},
  {"signature": "glm-run", "basemodel": "glm-4.7", "enabled": true}
]
```

### 6.4 使用示例

**命令行交互**：
```bash
# 使用 /clawwork 命令分配付费任务
/clawwork Write a market analysis for electric vehicles

# 系统响应示例：
# → Classified as "Market Research Analysts" at $38.71/hr
# → Estimated 3 hours = $116.13 max payment
```

**智能体决策示例**：
```
============================================================
📅 ClawWork Daily Session: 2025-01-20
============================================================

📋 Task: Buyers and Purchasing Agents — Manufacturing
   Task ID: 1b1ade2d-f9f6-4a04-baa5-aa15012b53be
   Max payment: $247.30

🔄 Iteration 1/15
   📞 decide_activity → work
   📞 submit_work → Earned: $198.44

============================================================
📊 Daily Summary - 2025-01-20
   Balance: $11.98 | Income: $198.44 | Cost: $0.03
   Status: 🟢 thriving
============================================================
```

---

## 7. 优缺点分析

### 7.1 优势

**1. 创新的经济压力测试机制**
- 真实模拟 AI 智能体的经济可持续性
- 不仅测试能力，还测试成本效益
- 创造真实的"生存压力"

**2. 真实世界的任务数据集**
- GDPVal 数据集来自 OpenAI，质量高
- 44 个职业类别覆盖广泛
- 任务要求真实的可交付成果（文档、代码、分析）

**3. 多维度评估体系**
- LLM 评估替代简单规则
- 44 个职业有专门的评估标准
- 多维度评分（完整性、正确性、质量、标准）

**4. 模块化和可扩展性**
- 清晰的架构设计
- 支持多种 LLM 模型
- 易于添加新工具和任务源

**5. 实时可视化和监控**
- React 前端实时展示
- WebSocket 实时更新
- 丰富的数据分析和图表

**6. 与 Nanobot 集成**
- 将任何 Nanobot 实例转变为经济感知助手
- 支持 9 种消息渠道
- 统一的成本追踪

### 7.2 局限性

**1. 依赖外部 API**
- 需要多个 API 密钥（OpenAI、E2B、Tavily 等）
- API 成本可能较高（尤其是 GPT-4o 评估）
- 依赖外部服务的稳定性

**2. 评估成本**
- 每个任务都需要 GPT-4o 评估
- 评估成本可能超过智能体运行成本
- 不适合大规模低成本测试

**3. 任务复杂度限制**
- GDPVal 任务虽然真实，但相对独立
- 缺少长期、多步骤的复杂项目
- 任务间缺少依赖关系

**4. 技术门槛**
- 需要 Python 3.10+ 和 Node.js 环境
- 配置相对复杂（多个配置文件）
- 需要理解 LangChain 和 MCP

**5. 代码成熟度**
- 缺少全面的单元测试
- 部分代码文件较长
- 错误处理可以更加健壮

### 7.3 适用人群

**适合**：
- AI 研究人员和开发者
- 需要评估 AI 模型实际工作能力的团队
- 对 AI 经济可持续性感兴趣的研究者
- 想要构建 AI 同事系统的开发者

**不适合**：
- 寻找简单聊天机器人的用户
- 预算有限的个人开发者（API 成本高）
- 需要即插即用解决方案的生产环境

---

## 8. 与当前项目的关联性

### 8.1 可借鉴的代码

**1. 经济追踪系统** (`economic_tracker.py`)
- 精细的 token 成本追踪机制
- 多维度成本分析（LLM、API、搜索）
- 实时余额计算和持久化
- **适用场景**：任何需要成本监控的 AI 应用

**2. 工具系统架构** (`direct_tools.py`)
- 使用 LangChain `@tool` 装饰器的优雅实现
- 工具状态管理和全局状态共享
- 异步工具执行模式
- **适用场景**：构建 LLM 工具链

**3. 任务管理系统** (`task_manager.py`)
- 灵活的任务加载（Parquet、JSONL、内联）
- 任务分配和过滤机制
- 参考文件管理
- **适用场景**：批量任务处理系统

**4. 评估框架** (`evaluator.py`, `llm_evaluator.py`)
- LLM 作为评估器的实现
- 分类别的评估提示词模板
- 结构化评分输出
- **适用场景**：自动化质量评估

**5. Provider 包装器** (`provider_wrapper.py`)
- 透明的成本追踪包装
- 拦截和记录所有 LLM 调用
- 支持多种 Provider
- **适用场景**：LLM 调用监控和计费

### 8.2 可借鉴的设计思路

**1. 经济可持续性设计**
```
核心思想：AI 智能体必须为自己的计算资源付费
- 每个操作都有成本
- 必须通过创造价值来生存
- 创造真实的资源约束压力
```
**应用场景**：资源有限的边缘计算、去中心化 AI 网络

**2. 工作-学习权衡机制**
```
核心思想：智能体需要决定是立即工作赚钱，还是投资学习
- 模拟真实的职业决策
- 长期 vs 短期的权衡
- 知识积累带来复利效应
```
**应用场景**：终身学习系统、自适应 AI 助手

**3. 多维度评估体系**
```
核心思想：不只看结果，还要看过程和质量
- 完整性、正确性、质量、标准
- 领域特定的评估标准
- 强制低分规则防止作弊
```
**应用场景**：自动化代码审查、内容质量评估

**4. 实时数据持久化**
```
核心思想：JSONL 格式记录所有事件
- 便于追加写入
- 易于后续分析
- 支持实时流式处理
```
**应用场景**：事件溯源、审计日志、时间序列分析

**5. 配置驱动的智能体行为**
```
核心思想：通过 JSON 配置控制智能体参数
- 模型选择
- 经济参数
- 任务分配策略
- 无需修改代码即可实验
```
**应用场景**：A/B 测试、参数调优、多环境部署

### 8.3 集成建议

**如果要在当前项目中使用 ClawWork 的组件**：

**短期（快速收益）**：
1. **集成经济追踪器**：为现有 AI 应用添加成本监控
2. **使用评估框架**：自动化评估生成内容的质量
3. **借鉴工具系统**：标准化工具定义和调用接口

**中期（架构改进）**：
1. **引入任务管理系统**：标准化任务分配和追踪
2. **实施 Provider 包装**：统一 LLM 调用和监控
3. **采用配置驱动**：将硬编码参数迁移到配置文件

**长期（生态建设）**：
1. **构建多智能体竞技场**：比较不同模型的实际工作能力
2. **开发经济压力测试**：评估 AI 系统的可持续性
3. **创建 AI 同事系统**：将助手转变为价值创造者

---

## 9. 总结

ClawWork 是一个**创新性强、架构清晰、实现完整**的 AI 经济生存基准测试平台。它的核心价值在于：

1. **真实经济压力**：通过 token 计费机制创造真实的资源约束
2. **实际工作任务**：使用 GDPVal 数据集测试真实工作能力
3. **多维度评估**：不仅看结果，还看质量、成本和可持续性
4. **模块化设计**：清晰的架构便于扩展和集成

对于希望构建**经济可持续的 AI 系统**、评估**AI 实际工作能力**、或研究**AI 长期生存策略**的团队，ClawWork 提供了宝贵的参考实现和基础框架。

**关键文件路径汇总**：
- 主智能体：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/agent/live_agent.py`
- 经济追踪：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/agent/economic_tracker.py`
- 工具实现：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/tools/direct_tools.py`
- 任务管理：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/work/task_manager.py`
- 评估系统：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/work/evaluator.py`
- API 服务：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/api/server.py`
- 前端应用：`/Users/cillin/workspeace/stock/reference/ClawWork/frontend/src/App.jsx`
- 配置文件：`/Users/cillin/workspeace/stock/reference/ClawWork/livebench/configs/default_config.json`

---

*报告生成时间：2026-02-25*
*分析基于 ClawWork 仓库最新代码*
*报告字数：约 5500 字*