ViperEkura
/
nanoClaw
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
53 Commits 1 Branch 0 Tags 791 KiB
Python 52.9%
Vue 34.1%
JavaScript 7.3%
CSS 5.5%
HTML 0.2%
Go to file
ViperEkura 7bd19a7529 feat: 初步搭建 multi-agent 框架 2026-03-27 16:35:13 +08:00
backend feat: 初步搭建 multi-agent 框架 2026-03-27 16:35:13 +08:00
docs refactor: 支持多 LLM 提供商自动检测 2026-03-27 13:21:20 +08:00
frontend refactor: 更新UI 样式 2026-03-27 15:49:14 +08:00
.gitignore feat: 增加项目管理部分 2026-03-26 15:25:47 +08:00
README.md refactor: 支持多 LLM 提供商自动检测 2026-03-27 13:21:20 +08:00
pyproject.toml feat: 增加用户认证系统 2026-03-26 20:47:51 +08:00

README.md

NanoClaw

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

功能特性

  • 多轮对话 - 支持上下文管理的多轮对话
  • 工具调用 - 网页搜索、代码执行、文件操作等 13 个内置工具
  • 思维链 - 支持链式思考推理（DeepSeek R1 / GLM thinking）
  • 工作目录 - 项目级文件隔离，安全操作
  • Token 统计 - 按日/周/月统计使用量
  • 流式响应 - 实时 SSE 流式输出，穿插显示思考/文本/工具调用
  • 代码编辑器 - 基于 CodeMirror 6，支持 15+ 语言语法高亮和暗色主题
  • 多数据库 - 支持 MySQL、SQLite、PostgreSQL
  • 多用户/单用户 - 支持单用户免登录和多用户 JWT 认证两种模式

快速开始

1. 安装依赖

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

2. 配置

复制并编辑 config.yml：

# Port
backend_port: 3000
frontend_port: 4000

# Max agentic loop iterations (tool call rounds)
max_iterations: 15

# Available models
# Each model must have its own id, name, api_url, api_key
models:
  - id: deepseek-chat
    name: DeepSeek V3
    api_url: https://api.deepseek.com/chat/completions
    api_key: sk-xxx
  - id: glm-5
    name: GLM-5
    api_url: https://open.bigmodel.cn/api/paas/v4/chat/completions
    api_key: xxx

default_model: deepseek-chat

# Database Configuration
# Supported types: mysql, sqlite, postgresql
db_type: sqlite

# MySQL/PostgreSQL Settings (ignored for sqlite)
# db_host: localhost
# db_port: 3306
# db_user: root
# db_password: "123456"
# db_name: nano_claw

# SQLite Settings (ignored for mysql/postgresql)
db_sqlite_file: nano_claw.db

# Workspace Configuration
workspace_root: ./workspaces

# Authentication (optional, defaults to single-user mode)
# auth_mode: single  # "single" (default) or "multi"
# jwt_secret: nano-claw-default-secret-change-in-production

说明：api_key 支持环境变量替换，例如 api_key: ${DEEPSEEK_API_KEY}。

3. 启动后端

python -m backend.run

4. 启动前端

cd frontend
npm install
npm run dev

项目结构

backend/
├── __init__.py          # 应用工厂，数据库初始化，load_config()
├── config.py            # 配置加载与验证
├── models.py            # SQLAlchemy 数据模型
├── run.py               # 入口文件
├── routes/              # API 路由
│   ├── auth.py          # 认证（登录/注册/JWT/profile）
│   ├── conversations.py # 会话 CRUD
│   ├── messages.py      # 消息 CRUD + 聊天（SSE 流式）
│   ├── models.py        # 模型列表
│   ├── projects.py      # 项目管理 + 文件操作
│   ├── stats.py         # Token 使用统计
│   └── tools.py         # 工具列表
├── services/            # 业务逻辑
│   ├── chat.py          # 聊天补全服务（SSE 流式 + 多轮工具调用）
│   └── llm_client.py    # OpenAI 兼容 LLM API 客户端
├── tools/               # 工具系统
│   ├── core.py          # 核心类（ToolDefinition/ToolRegistry）
│   ├── factory.py       # @tool 装饰器 + register_tool()
│   ├── executor.py      # 工具执行器（缓存、去重、上下文注入）
│   ├── services.py      # 辅助服务（搜索/抓取/计算）
│   └── builtin/         # 内置工具
│       ├── crawler.py   # 网页搜索、抓取
│       ├── data.py      # 计算器、文本、JSON 处理
│       ├── weather.py   # 天气查询（模拟）
│       ├── file_ops.py  # 文件操作（6 个工具，project_id 自动注入）
│       └── code.py      # Python 代码执行（沙箱）
└── utils/               # 辅助函数
    ├── helpers.py       # 通用函数（ok/err/build_messages 等）
    └── workspace.py     # 工作目录工具（路径验证、项目目录管理）

frontend/
└── src/
    ├── api/             # API 请求层（request + SSE 流解析）
    ├── components/      # Vue 组件（12 个）
    ├── composables/     # 组合式函数（主题/模态框/Toast）
    └── utils/           # 工具模块（Markdown 渲染/代码高亮/图标）

工作目录系统

概述

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

使用流程

  1. 创建项目 - 在侧边栏点击"新建项目"或上传文件夹
  2. 选择项目 - 在对话中选择当前工作目录
  3. 文件操作 - AI 自动在项目目录内执行文件操作（project_id 由后端自动注入，对 AI 透明）

安全机制

  • 所有文件工具的 project_id 由后端自动注入，AI 不可见也不可伪造
  • 后端强制验证路径在项目目录内
  • 阻止目录遍历攻击（如 ../../../etc/passwd）

API 概览

认证

方法 路径 说明
GET /api/auth/mode 获取当前认证模式
POST /api/auth/login 用户登录
POST /api/auth/register 用户注册
GET /api/auth/profile 获取当前用户信息
PATCH /api/auth/profile 更新当前用户信息

会话管理

方法 路径 说明
GET/POST /api/conversations 会话列表 / 创建会话
GET /api/conversations/:id 会话详情
PATCH /api/conversations/:id 更新会话
DELETE /api/conversations/:id 删除会话

消息管理

方法 路径 说明
GET /api/conversations/:id/messages 消息列表
POST /api/conversations/:id/messages 发送消息（SSE 流式）
DELETE /api/conversations/:id/messages/:mid 删除消息
POST /api/conversations/:id/regenerate/:mid 重新生成消息

项目管理

方法 路径 说明
GET/POST /api/projects 项目列表 / 创建项目
GET/PUT/DELETE /api/projects/:id 项目详情 / 更新 / 删除
POST /api/projects/upload 上传文件夹作为项目
GET /api/projects/:id/files 列出项目文件
GET/PUT/PATCH/DELETE /api/projects/:id/files/:path 文件 CRUD
POST /api/projects/:id/directories 创建目录
POST /api/projects/:id/search 搜索文件内容

其他

方法 路径 说明
GET /api/models 获取可用模型列表
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_delete, file_list, file_exists, file_mkdir project_id 自动注入
天气 get_weather 天气查询（模拟）

文档

技术栈

  • 后端: Python 3.10+, Flask, SQLAlchemy, requests
  • 前端: Vue 3, Vite 6, CodeMirror 6, marked, highlight.js, KaTeX
  • LLM: 支持任何 OpenAI 兼容 API（DeepSeek、GLM、OpenAI、Moonshot、Qwen 等）