LLClaw - 智能 AI 助手平台

一个基于 FastAPI + LangChain 的现代化 AI 助手平台，支持流式对话、RAG 知识库、长期记忆、MCP 协议扩展等功能。

---

📸 功能展示

💬 智能对话界面

现代化的聊天界面，支持流式输出、工具调用可视化、会话管理

🎨 设置中心

标签式设置界面，包含模型配置、RAG 设置、会话管理等功能

🧠 长期记忆系统

基于 ChromaDB 的长期记忆索引，自动学习和回忆用户偏好

📚 知识库管理

支持 PDF、Word、Markdown 等多种格式的知识库检索（RAG）

🔧 技能扩展系统

基于 Skill 文件的工具扩展机制，支持 MCP 协议集成

📊 Token 统计

详细的 Token 使用统计和会话分析

---

✨ 核心特性

🤖 智能对话

• ✅ 流式输出 - 实时显示 AI 回复
• ✅ 工具调用 - 自动识别并调用外部工具
• ✅ 多会话管理 - 支持多个独立对话会话
• ✅ 会话压缩 - 自动压缩长对话以节省 Token

🧠 记忆系统

• ✅ 长期记忆 - 基于 ChromaDB 的向量记忆存储
• ✅ 用户画像 - 自动学习和更新用户偏好
• ✅ 记忆检索 - 根据上下文智能检索相关记忆
• ✅ 记忆归档 - 自动归档旧会话到日志文件

📚 RAG 知识库

• ✅ 多格式支持 - PDF、Word (.docx)、Markdown、TXT
• ✅ 混合检索 - 向量搜索 + BM25 关键词检索
• ✅ 动态启用 - 可配置是否启用 RAG 检索
• ✅ 知识索引 - 自动索引知识库文档

🔧 工具扩展

• ✅ 内置工具 - 终端执行、Python REPL、文件读取、网页抓取
• ✅ Skill 系统 - 基于 YAML frontmatter 的技能定义
• ✅ MCP 协议 - 支持 Model Context Protocol 扩展
• ✅ 邮件发送 - SMTP 邮件发送工具（支持附件）
• ✅ 书旗小说 - 集成阿里云百炼 MCP 服务

⚙️ 配置管理

• ✅ 统一配置 - 所有配置集中在 config.json
• ✅ 前端修改 - 支持通过 Web 界面动态修改配置
• ✅ 增量保存 - 只更新修改的字段，保留其他配置
• ✅ 配置模板 - 提供 config.example.json 示例

---

🚀 快速开始

1️⃣ 环境要求

• Python 3.12+
• uv（推荐）或 pip

2️⃣ 安装依赖

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -r requirements.txt

3️⃣ 配置文件

# 复制配置模板
cp config.example.json config.json

# 编辑配置文件，填入你的 API Key
# - dashscope_api_key: 阿里云百炼 API Key
# - SMTP_SERVER/PASSWORD: 邮箱配置（可选）
# - mcpServers: MCP 服务配置（可选）

4️⃣ 启动应用

uv run python app.py

访问 http://127.0.0.1:8000 即可使用！

---

📁 项目结构

LLClaw/
├── api/                    # API 路由
│   ├── chat.py            # 聊天接口
│   ├── sessions.py        # 会话管理
│   ├── knowledge.py       # 知识库管理
│   ├── config_api.py      # 配置接口
│   └── ...
├── graph/                  # Agent 核心逻辑
│   ├── agent.py           # Agent 管理器
│   ├── session_manager.py # 会话管理
│   ├── memory_indexer.py  # 记忆索引
│   └── knowledge_indexer.py # 知识库索引
├── tools/                  # 工具集合
│   ├── email_tool.py      # 邮件发送工具
│   ├── mcp_client_tool.py # MCP 客户端
│   ├── terminal_tool.py   # 终端工具
│   └── ...
├── mcp_servers/            # MCP 服务器
│   └── email_server.py    # 邮件 MCP 服务（已废弃）
├── skills/                 # Skill 定义
│   ├── send_email/        # 邮件发送技能
│   ├── get_weather/       # 天气查询技能
│   └── shuqi_novel_search/ # 书旗小说搜索
├── workspace/              # 工作区目录
├── memory/                 # 记忆存储
│   ├── logs/              # 记忆日志
│   └── MEMORY.md          # 用户画像
├── knowledge/              # 知识库文档
├── sessions/               # 会话存储
│   └── archive/           # 归档会话
├── storage/                # 向量数据库
│   ├── memory_chroma/     # 记忆向量库
│   └── knowledge_chroma/  # 知识向量库
├── templates/              # HTML 模板
├── static/                 # 静态资源
├── config.json             # 主配置文件
├── config.example.json     # 配置模板
└── app.py                  # 应用入口

---

🔧 配置说明

基础配置

{
  "openai_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "openai_model": "qwen-max",
  "dashscope_api_key": "your-api-key",
  "embedding_model": "text-embedding-v3"
}

邮件配置

{
  "SMTP_SERVER": "smtp.qq.com",
  "SMTP_PORT": "587",
  "SENDER_EMAIL": "your_email@qq.com",
  "PASSWORD": "your-auth-code"
}

MCP 服务配置

{
  "mcpServers": {
    "market-cmapi00072981": {
      "type": "streamableHttp",
      "baseUrl": "https://dashscope.aliyuncs.com/api/v1/mcps/...",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

详细配置说明请查看 CONFIG.md

---

🛠️ 开发指南

添加新工具

1. 在 tools/ 目录创建工具文件
2. 继承 BaseTool 类
3. 在 tools/__init__.py 中注册

添加新 Skill

1. 在 skills/ 目录创建文件夹
2. 创建 SKILL.md 文件（包含 YAML frontmatter）
3. 重启应用，系统会自动扫描

添加 MCP 服务

1. 在 config.json 中添加 mcpServers 配置
2. 创建对应的 Skill 文件
3. AI 会自动识别并调用

---

📊 技术栈

• 后端框架: FastAPI
• AI 框架: LangChain 1.x + LangGraph
• 向量数据库: ChromaDB
• 文本处理: tiktoken, jieba, rank-bm25
• 文档解析: PyPDF2, python-docx
• 包管理: uv
• 前端: 原生 HTML/CSS/JavaScript

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📄 许可证

MIT License

---

🙏 致谢

• LangChain - AI 应用开发框架
• FastAPI - 高性能 Web 框架
• ChromaDB - 向量数据库
• FastMCP - MCP 协议实现

---

Made with ❤️ by LLClaw Team