# clawserver

**Repository Path**: teachitback/clawserver

## Basic Information

- **Project Name**: clawserver
- **Description**: claw server claw app

clawserver for clawdroid,clawios
- **Primary Language**: JavaScript
- **License**: BSL-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# clawserver - TeachItBack Learning Assistant

基于 OpenClaw 技能系统的 AI 学习助手，专注于教与学场景的智能辅助。

## 功能特性

- **技能系统架构**: 基于 OpenClaw 的模块化技能设计
- **Gitee 集成**: 支持国内代码仓库管理
- **火山方舟 LLM**: 集成 Doubao/Spark/Qwen 等国产大模型
- **Zenoh P2P 通信**: 支持移动端与本地服务的直连（peer模式）
- **学习辅助**: 专注教与学场景的智能辅助功能

## 快速启动

### 步骤1：安装依赖

```bash
# 进入项目目录
cd d:/git/teachitback/clawserver/.worktrees/feature-space-system-implementation

# 安装依赖
pip install -e .

# 或安装包含开发依赖的版本
pip install -e ".[dev]"
```

### 步骤2：配置环境变量

编辑 `.env` 文件，确保包含以下关键配置：

```bash
# AI API密钥（必须配置至少一个）
HUO_SHAN_API_KEY=your_huoshan_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here

# 可选：存储配置
GITEE_ACCESS_TOKEN=your_gitee_token_here
```

### 步骤3：启动服务

```bash
# 进入项目目录
cd d:/git/teachitback/clawserver/.worktrees/feature-space-system-implementation

# 启动服务（推荐方式 - 跨平台兼容）
python start_server.py

# 或者使用 PowerShell 设置环境变量后启动
$env:PYTHONPATH="src"; python src/clawserver/main.py

# 或者使用 CMD 启动
set PYTHONPATH=src && python src/clawserver/main.py
```

### 步骤4：验证服务状态

服务启动后，访问以下地址验证：

- **健康检查**: http://localhost:8000/api/v1/health
- **API文档**: http://localhost:8000/docs
- **Chat接口**: http://localhost:8000/api/v1/chat
- **Zenoh Peer**: tcp/0.0.0.0:7448

## API端点列表

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/api/v1/health` | 健康检查 |
| POST | `/api/v1/chat` | 发送聊天消息 |
| GET | `/api/v1/spaces` | 列出所有空间 |
| POST | `/api/v1/spaces` | 创建新空间 |
| GET | `/api/v1/spaces/{space_id}` | 获取空间详情 |
| GET | `/api/v1/spaces/{space_id}/messages` | 获取空间消息列表 |
| DELETE | `/api/v1/spaces/{space_id}/messages` | 清空空间消息 |

## ClawDroid真机连接测试

### 架构说明

```
┌─────────────────┐
│   clawdroid   │ (client mode)
│   (Android)    │
└──────┬─────────┘
       │ tcp/127.0.0.1:7448 (via adb reverse)
       ▼
┌─────────────────────────────────────┐
│         clawserver                │
│  ┌───────────────────────────┐   │
│  │   FastAPI (port 8000)   │   │
│  └───────────────────────────┘   │
│         │                      │
│  ┌──────▼───────────────────┐   │
│  │   Zenoh (peer mode)    │   │
│  │   listen: 7448          │   │
│  └───────────────────────────┘   │
│         │                      │
│  ┌──────▼───────────────────┐   │
│  │   SpaceSystem            │   │
│  │   (shared resource)      │   │
│  └───────────────────────────┘   │
└─────────────────────────────────────┘
```

### 连接测试步骤

1. **启动clawserver服务**
   ```bash
   cd d:/git/teachitback/clawserver/.worktrees/feature-space-system-implementation
   python start_server.py
   ```

2. **连接Android真机**
   ```bash
   adb devices
   ```

3. **安装clawdroid应用**
   ```bash
   cd d:/git/teachitback/clawdroid/.worktrees/feature/clawserver-status-display
   ./gradlew assembleDebug
   adb install -r app/build/outputs/apk/debug/app-debug.apk
   ```

4. **设置adb端口转发**
   ```bash
   adb reverse tcp:7448 tcp:7448
   ```

5. **启动clawdroid并查看日志**
   ```bash
   adb shell am start -n com.clawdroid/.MainActivity
   adb logcat -s ZenohManager
   ```

### 预期日志输出

**成功连接**：
```
ZenohManager: Zenoh peer mode initialized successfully
ZenohManager: Health check successful: mode=direct, version=0.1.0
```

**连接失败**：
```
ZenohManager: Health check timeout - no response from clawserver
ZenohManager: Health check failed - clawserver returned error status: error
```

## ZMF (Zeromile Framework) 架构

### 架构设计

clawserver基于 **ZMF (Zeromile Framework)** 构建，采用微服务架构：

- **FastAPI**: 提供HTTP API接口（端口8000）
- **ZMF Services**: 核心服务通过Zenoh通信
  - `UI2AQueryGateway`: UI-to-Agent查询网关
  - `A2UINotifyGateway`: Agent-to-UI通知网关
  - `SpaceService`: 管理Space和聊天功能
  - `QueryService`: 处理查询请求
  - `StreamService`: 处理文件流上传
  - `HandshakeBusinessService`: 握手业务服务
  - `ChatBusinessService`: 聊天业务服务
- **Zenoh**: peer模式，监听 `tcp/0.0.0.0:7448`
- **Clawdroid**: 通过Zenoh连接到clawserver

### 服务通信流程

```
┌─────────────────┐      HTTP      ┌─────────────────────────────────────┐
│   clawdroid     │ ◄─────────────►│   FastAPI (port 8000)              │
│   (Android)     │                │                                     │
└─────────────────┘                │   ┌─────────────────────────────┐  │
       │                           │   │   ZMF Framework             │  │
       │ Zenoh                     │   │   ┌─────────────────────┐   │  │
       │ tcp/0.0.0.0:7448          │   │   │  UI2A Gateway       │   │  │
       ▼                           │   │   │  A2UI Gateway       │   │  │
┌──────────────────────────────────┤   │   │   │  SpaceService       │   │  │
│   Zenoh (peer mode)              │   │   │  QueryService       │   │  │
│   listen: 7448                   │   │   │  StreamService      │   │  │
└──────────────────────────────────┘   │   │   └─────────────────────┘   │  │
                                   │   └─────────────────────────────┘  │
                                   └─────────────────────────────────────┘
```

### Zenoh Topics

| Topic | 模式 | 描述 |
|--------|------|------|
| `ui2a/tib/dev-user-001/handshake` | Queryable | 连接握手 |
| `ui2a/tib/dev-user-001/chat` | Queryable | 聊天消息 |
| `ui2a/tib/dev-user-001/query` | Queryable | 数据查询 |
| `ui2a/tib/dev-user-001/upload` | Queryable | 文件上传 |
| `ui2a/tib/dev-user-001/download` | Queryable | 文件下载 |
| `a2ui/tib/dev-user-001/notification` | Pub/Sub | 通知推送 |

**说明**: 
- `dev-user-001` 是默认 USER_ID，可在 `.env` 文件中配置
- 必须与 clawdroid 的 `BuildConfig.DEV_USER_ID` 保持一致
- **安全设计**: clawserver 使用实际的 user_id 监听，而非通配符，确保只接收属于当前用户的消息

## 项目结构

```
clawserver/
├── src/clawserver/
│   ├── api/            # FastAPI路由和端点
│   ├── communication/    # 4-Gateway架构（UI2A, A2UI, EventBus）
│   ├── core/           # 核心系统（SpaceSystem, LLMDispatcher等）
│   ├── llm/            # LLM提供商集成
│   ├── models/         # 数据模型
│   ├── services/       # ZMF服务
│   ├── skills/         # 技能模块
│   ├── space/          # Space管理
│   ├── storage/        # 存储层
│   ├── config.py
│   ├── gateway_init.py
│   └── main.py
├── config/             # 配置文件
├── tests/              # 测试文件
│   ├── communication/    # Gateway单元测试
│   └── e2e/            # E2E测试（使用ZMFClient）
├── docs/               # 文档
└── web/                # Web前端文件
```

## 开发指南

### 环境准备

```bash
# 1. 进入项目目录
cd d:/git/teachitback/clawserver/.worktrees/feature-space-system-implementation

# 2. 创建虚拟环境（推荐 Python 3.12+）
conda create -n clawserver python=3.12
conda activate clawserver

# 3. 安装依赖
pip install -e ".[dev]"

# 4. 安装 pre-commit hooks
pre-commit install
```

### 代码规范

```bash
# 格式化代码
ruff format src/

# 检查代码
ruff check src/

# 类型检查
pyright src/
```

## 测试指南

### 运行测试

```bash
# 运行所有单元测试
pytest

# 运行特定测试
pytest tests/communication/test_ui2a_gateway.py -v

# 运行带覆盖率报告
pytest --cov=src/clawserver --cov-report=html
```

### E2E测试

```bash
# 运行E2E测试（需要clawserver运行）
pytest tests/e2e/ -v -m e2e

# 运行特定E2E测试
pytest tests/e2e/test_ui2a_gateway_e2e.py -v
```

## 常见问题

### 端口占用
```bash
# 检查端口占用
netstat -ano | findstr "LISTENING" | findstr ":8000 :7448"
```

### API密钥
确保至少配置了一个有效的AI API密钥（HUO_SHAN_API_KEY 或 DEEPSEEK_API_KEY）

### 依赖缺失
```bash
# 检查依赖
pip list | grep -E "(fastapi|uvicorn|httpx|eclipse-zenoh)"
```

## 许可证

MIT License