# NanoClaw

基于 LLM 大语言模型的 AI 对话应用，支持工具调用、思维链、流式回复和工作目录隔离。

## 功能特性

- 💬 **多轮对话** - 支持上下文管理的多轮对话
- 🔧 **工具调用** - 网页搜索、代码执行、文件操作等
- 🧠 **思维链** - 支持链式思考推理
- 📁 **工作目录** - 项目级文件隔离，安全操作
- 📊 **Token 统计** - 按日/周/月统计使用量
- 🔄 **流式响应** - 实时 SSE 流式输出
- 💾 **多数据库** - 支持 MySQL、SQLite、PostgreSQL

## 快速开始

### 1. 安装依赖

```bash
conda create -n claw python=3.12
conda activate claw
pip install -e .
```

### 2. 配置

复制并编辑 `config.yml`：

```yaml
# Port
backend_port: 3000
frontend_port: 4000

# LLM API
api_key: {{your-api-key}}
api_url: https://open.bigmodel.cn/api/paas/v4/chat/completions

# Available models
models:
  - id: glm-5
    name: GLM-5
  - id: glm-4-plus
    name: GLM-4 Plus

default_model: glm-5

# Workspace root directory
workspace_root: ./workspaces

# Database Configuration
db_type: sqlite
db_sqlite_file: nano_claw.db
```

### 3. 启动后端

```bash
python -m backend.run
```

### 4. 启动前端

```bash
cd frontend
npm install
npm run dev
```

## 项目结构

```
backend/
├── models.py        # SQLAlchemy 数据模型
├── routes/          # API 路由
│   ├── conversations.py
│   ├── messages.py
│   ├── projects.py  # 项目管理
│   └── ...
├── services/        # 业务逻辑
│   ├── chat.py      # 聊天补全服务
│   └── glm_client.py
├── tools/           # 工具系统
│   ├── core.py      # 核心类
│   ├── executor.py  # 工具执行器
│   └── builtin/     # 内置工具
├── utils/           # 辅助函数
│   ├── helpers.py
│   └── workspace.py # 工作目录工具
└── migrations/      # 数据库迁移

frontend/
└── src/
    ├── api/         # API 请求层
    ├── components/  # Vue 组件
    └── views/       # 页面
```

## 工作目录系统

### 概述

工作目录系统为文件操作提供安全隔离，确保 AI 只能访问指定项目目录内的文件。

### 使用流程

1. **创建项目** - 在侧边栏点击"新建项目"或上传文件夹
2. **选择项目** - 在对话中选择当前工作目录
3. **文件操作** - AI 自动在项目目录内执行文件操作

### 安全机制

- 所有文件操作需要 `project_id` 参数
- 后端强制验证路径在项目目录内
- 阻止目录遍历攻击（如 `../../../etc/passwd`）

## API 概览

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/conversations` | 创建会话 |
| `GET` | `/api/conversations` | 会话列表 |
| `GET` | `/api/conversations/:id/messages` | 消息列表 |
| `POST` | `/api/conversations/:id/messages` | 发送消息（SSE 流式） |
| `GET` | `/api/projects` | 项目列表 |
| `POST` | `/api/projects` | 创建项目 |
| `POST` | `/api/projects/upload` | 上传文件夹 |
| `GET` | `/api/tools` | 工具列表 |
| `GET` | `/api/stats/tokens` | Token 统计 |

## 内置工具

| 分类 | 工具 | 说明 |
|------|------|------|
| **爬虫** | web_search, fetch_page, crawl_batch | 网页搜索和抓取 |
| **数据处理** | calculator, text_process, json_process | 数学计算和文本处理 |
| **代码执行** | execute_python | 沙箱环境执行 Python |
| **文件操作** | file_read, file_write, file_list 等 | **需要 project_id** |
| **天气** | get_weather | 天气查询（模拟） |

## 文档

- [后端设计](docs/Design.md) - 架构设计、数据模型、API 文档
- [工具系统](docs/ToolSystemDesign.md) - 工具开发指南、安全设计

## 技术栈

- **后端**: Python 3.11+, Flask, SQLAlchemy
- **前端**: Vue 3, Vite
- **LLM**: 支持 GLM 等大语言模型