# ClawCC

**Repository Path**: xusuai/clawcc

## Basic Information

- **Project Name**: ClawCC
- **Description**: 随时随地用自然语言进行企业级生产力编程，Rust语言开发，项目是一个基于开源ClawCode编程环境的QQ-bot机器人，类似于OpenClaw大龙虾的智能CLI命令行智能编程框架，项目的特点是基于ClawCode的优秀的编程能力。拥有非常完善的上下文压缩能力。几乎无限上下文。有非常优秀的记忆系统。支持向量数据库可以对过往的记忆进行智能提取，并进行智能注入提示词。是一个自然语言随身编程工具
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#ClawCode QQ Bot - 智能对话机器人

基于 Rust 开发的 QQ 机器人，集成多厂商 LLM 支持、智能代理、记忆系统和工具调用功能。

随时随地用自然语言进行企业级生产力编程，Rust语言开发，项目是一个基于开源ClawCode编程环境的QQ-bot机器人，类似于OpenClaw大龙虾的智能CLI命令行智能编程框架，项目的特点是基于ClawCode的优秀的编程能力。拥有非常完善的上下文压缩能力。几乎无限上下文。有非常优秀的记忆系统。支持向量数据库可以对过往的记忆进行智能提取，并进行智能注入提示词。是一个自然语言随身编程工具

## ✨ 功能特性

### 🤖 多模型支持
- 支持 GLM、DeepSeek、Qwen、OpenAI 等多种 LLM
- 动态模型切换（通过命令或数字快捷切换）
- 图片解析支持（视模型能力）

### 🧠 智能代理
- 自动工具调用（文件操作、代码搜索、网络搜索）
- 多轮对话记忆
- 会话压缩与摘要

### 💾 记忆系统
- **FTS5 全文搜索**：基于 SQLite 的持久化搜索
- **向量搜索**：语义相似度匹配
- **混合搜索**：结合关键词和语义的最佳搜索体验
- 支持中文分词（jieba）

### 🔧 工具集成
- 文件读写操作
- 代码搜索（按文件名/内容）
- 网络搜索
- Shell 命令执行
- 权限控制与钩子系统

### 🔌 MCP 协议支持
- Model Context Protocol 集成
- 外部工具扩展
- 插件系统

## 📦 项目结构

```
qq-bot/
├── src/
│   ├── main.rs              # 程序入口
│   ├── lib.rs               # 库导出
│   ├── error.rs             # 统一错误类型
│   ├── client.rs            # QQ Bot 客户端
│   ├── agent.rs             # 智能代理
│   ├── session.rs           # 会话管理
│   ├── tools.rs             # 工具执行器
│   ├── api.rs               # QQ Bot API
│   ├── websocket.rs         # WebSocket 连接
│   ├── message.rs           # 消息类型
│   ├── permissions.rs       # 权限控制
│   ├── hooks.rs             # 钩子系统
│   ├── compact.rs           # 会话压缩
│   ├── memory/              # 记忆系统
│   │   ├── mod.rs
│   │   ├── types.rs         # 记忆类型定义
│   │   ├── searcher.rs      # FTS5 搜索器
│   │   ├── searcher_new.rs  # 混合搜索器
│   │   ├── vector.rs        # 向量搜索
│   │   ├── hybrid.rs        # 混合搜索
│   │   ├── embedding_client.rs  # 嵌入服务客户端
│   │   └── extractor.rs     # 记忆提取
│   ├── memory_tool.rs       # 记忆工具
│   ├── mcp/                 # MCP 协议
│   │   ├── mod.rs
│   │   ├── manager.rs       # MCP 管理器
│   │   └── types.rs         # MCP 类型
│   └── plugin/              # 插件系统
│       ├── mod.rs
│       ├── manager.rs
│       └── types.rs
├── examples/                # 示例代码
│   ├── chinese_fts_demo.rs
│   ├── memory_tool_demo.rs
│   ├── vector_search_demo.rs
│   └── fts_english_demo.rs
└── Cargo.toml
```

## 🚀 快速开始

### 环境要求

- Rust 1.70+
- SQLite3（已内置）

### 配置

创建 `config.json`：

```json
{
  "qq_bot": {
    "app_id": "你的QQ机器人AppID",
    "app_secret": "你的QQ机器人AppSecret",
    "target_openid": "目标用户OpenID"
  },
  "models": [
    {
      "name": "GLM-5",
      "vendor": "zhipu",
      "api_key": "你的API密钥",
      "model_id": "glm-5",
      "description": "智谱GLM-5",
      "supports_images": true
    }
  ],
  "default_model": "glm-5"
}
```

### 运行

```bash
# 开发模式
cargo run

# 生产模式
cargo build --release
./target/release/qq-bot
```

## 📖 使用指南

### 基础对话

直接发送文字消息与 AI 对话：

```
你好
帮我写一个冒泡排序
解释一下什么是闭包
```

### 模型切换

```
/model              # 查看所有可用模型
/model 1            # 按编号切换
/model deepseek     # 按名称切换
```

查看模型列表后 60 秒内，直接发送数字可快速切换。

### 图片解析

发送图片（可附加文字说明）：

```
[图片] 分析这张图的代码
[图片] 识别图中的文字
```

### 会话管理

```
/clear    # 清除对话记忆
/help     # 查看完整帮助
```

### 智能工具

直接提问即可触发工具调用：

```
读取 config.json 文件
搜索代码中的 WebSocket
搜索网络上的 Rust 教程
列出当前目录文件
```

## 🏗️ 架构设计

### 错误处理

使用 `thiserror` 实现统一错误类型：

```rust
pub enum QQBotError {
    Io(io::Error),
    Api(String),
    Memory(String),
    Session(String),
    Tool(String),
    WebSocket(String),
    // ...
}

pub type Result<T> = std::result::Result<T, QQBotError>;
```

### 并发性能

使用 `DashMap` 替代 `Arc<Mutex<HashMap>>` 提升并发性能：

```rust
// 旧方式
let times = model_list_time.lock().await;
if let Some(shown_time) = times.get(&user_id) { ... }

// 新方式（无锁读取）
if let Some(shown_time) = model_list_time.get(&user_id) { ... }
```

### 记忆系统架构

```
┌─────────────────────────────────────────────────────┐
│                   MemoryManager                      │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │ Searcher    │  │ Hybrid      │  │ Embedding   │ │
│  │ (FTS5)      │  │ Searcher    │  │ Client      │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
│         │                │                 │        │
│         ▼                ▼                 ▼        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │ SQLite FTS5 │  │ Vector Index│  │ HTTP API    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────┘
```

## 🔧 开发指南

### 运行测试

```bash
# 所有测试
cargo test --all-targets

# 特定测试
cargo test test_hybrid_search

# 示例程序
cargo run --example memory_tool_demo
```

### 代码检查

```bash
# Clippy 检查
cargo clippy --all-targets -- -D warnings

# 格式化
cargo fmt
```

### 构建发布

```bash
cargo build --release
```

## 📊 性能优化

| 优化项 | 方案 | 效果 |
|--------|------|------|
| 并发 HashMap | DashMap | 减少锁竞争 |
| 错误处理 | thiserror | 统一错误类型 |
| 中文搜索 | jieba 分词 | 提高搜索精度 |
| 会话压缩 | Token 计数 | 控制上下文长度 |

## 🔐 安全特性

- 权限控制：可配置工具执行权限
- 钩子系统：执行前后拦截
- 路径限制：文件操作限制在工作目录

## 📝 更新日志

### v0.1.0 (2026-04)

- ✅ 多模型支持
- ✅ 智能代理与工具调用
- ✅ 记忆系统（FTS5 + 向量搜索）
- ✅ MCP 协议支持
- ✅ 统一错误类型
- ✅ DashMap 并发优化

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！