# Code Funhouse Mirror-sl

**Repository Path**: mr-song-sl/Code-Funhouse-Mirror

## Basic Information

- **Project Name**: Code Funhouse Mirror-sl
- **Description**: 代码哈哈镜是一个开源的个人 AI 助手平台，支持本地或云端部署。它能够通过多种渠道（钉钉、飞书、微信、Discord 等）与你交互，执行定时任务，处理文档，管理信息流。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 代码哈哈镜 (Code Funhouse Mirror)

<div align="center">

**一个可扩展的 AI 助手平台 - 本地部署，数据自主，能力无限**

[![Python Version](https://img.shields.io/badge/python-3.10%20~%20%3C3.14-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-red.svg)](LICENSE)

</div>

---

## 项目简介

**代码哈哈镜**是一个开源的个人 AI 助手平台，支持本地或云端部署。它能够通过多种渠道（钉钉、飞书、微信、Discord 等）与你交互，执行定时任务，处理文档，管理信息流。

### 核心特点

- **🏠 本地优先** - 数据完全掌控，可本地部署或自有服务器部署
- **🔌 能力扩展** - 通过 Skills 插件系统扩展功能，内置文档处理、定时任务、新闻摘要等
- **🤖 多智能体** - 支持创建多个独立 Agent，各司其职，协同工作
- **🔒 安全防护** - 多层安全机制：工具守卫、文件访问控制、技能安全扫描
- **💬 多渠道接入** - 支持钉钉、飞书、微信企业版、QQ、Discord、Telegram 等
- **🧠 记忆系统** - 长期记忆能力，从交互中学习，主动服务

---

## 技术架构

### 后端技术栈
- **语言**: Python 3.10-3.13
- **Web 框架**: FastAPI + Uvicorn
- **Agent 框架**: AgentScope + AgentScope Runtime
- **任务调度**: APScheduler
- **LLM 接入**: OpenAI SDK、Google GenAI、DashScope、Transformers
- **记忆系统**: reme-ai
- **安全**: cryptography + keyring

### 前端技术栈
- **框架**: React 18 + TypeScript 5.8
- **构建工具**: Vite 6
- **UI 组件**: Ant Design 5
- **状态管理**: Zustand 5
- **路由**: react-router-dom v7
- **国际化**: i18next

### 架构图

```
┌─────────────────────────────────────────────┐
│           浏览器 (Web Console)               │
│         http://127.0.0.1:8088/              │
└──────────────────┬──────────────────────────┘
                   │ HTTP / SSE
┌──────────────────▼──────────────────────────┐
│          Python 后端 (FastAPI)               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ REST API │  │ SSE 推送 │  │ 静态托管 │  │
│  └────┬─────┘  └─────┬────┘  └──────────┘  │
│       └──────────────┼─────────────         │
│  ┌───────────────────▼──────────────────┐   │
│  │     Agent 核心层 (AgentScope)        │   │
│  │  ┌────────┐ ┌────────┐ ┌─────────┐  │   │
│  │  │ ReAct  │ │ Memory │ │ Skills  │  │   │
│  │  │ Agent  │ │ System │ │ System  │  │   │
│  │  └────────┘ └────────┘ └─────────┘  │   │
│  └──────────────────────────────────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ 模型路由 │  │ 任务调度 │  │ MCP 客户 │  │
│  └─────┬────┘  └──────────┘  └──────────┘  │
└────────┼─────────────────────────────────────┘
         │
    ┌────▼────────────────────────────┐
    │      LLM 提供商                  │
    │  OpenAI / Gemini / Ollama / ... │
    └─────────────────────────────────┘

┌─────────────────────────────────────────────┐
│         多渠道接入层（并行运行）              │
│  钉钉 飞书 微信 QQ Discord Telegram ...     │
└─────────────────────────────────────────────┘
```

---

## 快速开始

### 方式一：Python 安装

```bash
# 安装依赖
pip install -e .

# 构建前端（首次运行必须）
cd console && npm ci && npm run build
cd ..

# 复制前端构建产物
mkdir -p src/qwenpaw/console
cp -R console/dist/. src/qwenpaw/console/

# 初始化配置
python -m qwenpaw.cli.main init --defaults

# 启动服务
python -m qwenpaw.cli.main app
```

然后打开浏览器访问 **http://127.0.0.1:8088/**

### 方式二：Docker Compose 部署

```bash
# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f
```

服务端口：
- 前端: http://127.0.0.1:18081
- 后端: http://127.0.0.1:18444

### 方式三：Docker 单容器部署

```bash
# 构建镜像
docker build -f deploy/Dockerfile -t code-funhouse-mirror:latest .

# 运行容器
docker run -p 127.0.0.1:8088:8088 \
  -v mirror-data:/app/working \
  -v mirror-secrets:/app/working.secret \
  -v mirror-backups:/app/working.backups \
  code-funhouse-mirror:latest
```

---

## 模型配置

### 支持的模型提供商

| 提供商 | 类型 | 说明 |
|--------|------|------|
| OpenAI | 云端 API | GPT-4o、GPT-4-turbo 等 |
| Google Gemini | 云端 API | Gemini Pro、Gemini Ultra |
| 阿里云 DashScope | 云端 API | 通义千问系列 |
| Ollama | 本地部署 | 需先安装 Ollama 服务 |
| LM Studio | 本地部署 | 需先安装 LM Studio 应用 |
| llama.cpp | 本地部署 | 内置支持，无需额外安装 |

### 配置方式

1. **Web Console 配置（推荐）**
   - 启动服务后访问 http://127.0.0.1:8088/
   - 进入 **设置 → 模型**
   - 选择提供商，输入 API Key，启用模型

2. **环境变量配置**
   - 创建 `.env` 文件或设置环境变量
   - 例如：`DASHSCOPE_API_KEY=your_api_key`

3. **本地模型（无需 API Key）**
   - 使用 Ollama、LM Studio 或 llama.cpp
   - 在 Web Console 中配置本地服务地址

---

## 目录结构

```
.
├── console/              # 前端代码 (React + TypeScript)
│   ├── src/             # 源代码
│   ├── public/          # 静态资源
│   └── dist/            # 构建产物
├── src/qwenpaw/         # 后端代码 (Python)
│   ├── agents/          # Agent 核心逻辑
│   ├── api/             # FastAPI 路由
│   ├── cli/             # 命令行工具
│   ├── config/          # 配置管理
│   ├── providers/       # 模型提供商
│   ├── security/        # 安全模块
│   └── channels/        # 消息渠道
├── deploy/              # 部署相关
│   ├── Dockerfile       # Docker 构建文件
│   └── config/          # 部署配置
├── tests/               # 测试代码
├── scripts/             # 工具脚本
├── pyproject.toml       # Python 项目配置
├── docker-compose.yml   # Docker Compose 配置
└── README.md           # 本文件
```

---

## 配置文件位置

### 工作目录

默认配置存储在用户目录下：

**Linux/macOS:**
```
~/.qwenpaw/              # 工作目录
~/.qwenpaw.secret/       # 敏感数据（API Keys）
```

**Windows:**
```
C:\Users\<用户名>\.qwenpaw\
C:\Users\<用户名>\.qwenpaw.secret\
```

### 目录结构

```
~/.qwenpaw/
├── config.json          # 全局配置
└── working/
    └── <agent_id>/
        ├── agent.json   # Agent 配置
        ├── memory/      # 记忆数据
        └── skills/      # 自定义技能

~/.qwenpaw.secret/
└── providers/
    ├── builtin/         # 内置提供商配置（含加密 API Key）
    ├── custom/          # 自定义提供商
    └── plugin/          # 插件提供商
```

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `QWENPAW_WORKING_DIR` | `~/.qwenpaw` | 工作目录 |
| `QWENPAW_SECRET_DIR` | `~/.qwenpaw.secret` | 敏感数据目录 |
| `QWENPAW_AUTH_ENABLED` | `false` | 是否启用 Web 认证 |
| `QWENPAW_AUTH_USERNAME` | - | Web 登录用户名 |
| `QWENPAW_AUTH_PASSWORD` | - | Web 登录密码 |

---

## 安全特性

### 多层防护机制

1. **工具守卫 (Tool Guard)**
   - 自动拦截危险的 Shell 命令
   - 防止 `rm -rf /`、fork 炸弹、反向 Shell 等

2. **文件访问控制**
   - 限制访问敏感路径（`~/.ssh`、系统目录等）
   - 沙箱化文件操作

3. **技能安全扫描**
   - 安装前自动扫描技能代码
   - 检测提示注入、命令注入、硬编码密钥等风险

4. **数据加密存储**
   - API Key 使用 cryptography 加密存储
   - 敏感配置独立存储在 `.secret` 目录

5. **Web 认证（可选）**
   - 支持为 Web Console 添加登录保护
   - 通过环境变量启用

---

## 开发指南

### 环境准备

```bash
# 安装开发依赖
pip install -e ".[dev,full]"

# 安装前端依赖
cd console && npm ci

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

### 运行测试

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

# 运行单元测试
pytest tests/unit

# 运行集成测试
pytest tests/integration

# 生成覆盖率报告
pytest --cov=src/qwenpaw --cov-report=html
```

### 代码规范

```bash
# Python 代码格式化
black src/ tests/

# Python 代码检查
flake8 src/ tests/
pylint src/

# 前端代码格式化
cd console && npm run format

# 前端代码检查
cd console && npm run lint
```

### 前端开发

```bash
cd console

# 启动开发服务器（需要后端同时运行）
npm run dev

# 构建生产版本
npm run build
```

---

## 扩展能力

### Skills 系统

通过 Skills 扩展 Agent 能力，内置技能包括：

- **文档处理**: PDF、Office 文档读取和摘要
- **定时任务**: Cron 定时执行任务
- **新闻摘要**: 定时推送热点新闻
- **文件管理**: 本地文件组织和搜索
- **网页操作**: 网页截图、内容提取

### 自定义 Skills

在 `~/.qwenpaw/working/<agent_id>/skills/` 目录下添加自定义技能：

```python
# my_skill.py
def my_function(arg1, arg2):
    """技能描述"""
    # 实现逻辑
    return result
```

Agent 启动时会自动加载。

### MCP 协议

支持 Model Context Protocol，可接入外部工具和服务。

---

## 多渠道接入

支持的消息平台：

- 钉钉 (DingTalk)
- 飞书 (Lark/Feishu)
- 微信企业版 (WeCom)
- QQ
- Discord
- Telegram
- Twilio (SMS)
- Matrix
- MQTT

配置方式：在 Web Console 的 **设置 → 渠道** 中配置各平台的 Token 和 Webhook。

---

## 常见问题

### 1. 如何更换模型？

在 Web Console 的 **设置 → 模型** 中切换活动模型。

### 2. 如何备份数据？

数据存储在 `~/.qwenpaw` 和 `~/.qwenpaw.secret`，直接备份这两个目录即可。

Docker 部署的数据在 volumes 中：`qwenpaw-data`、`qwenpaw-secrets`、`qwenpaw-backups`。

### 3. 如何升级版本？

```bash
# Python 安装
pip install -e . --upgrade

# Docker 部署
docker-compose pull
docker-compose up -d
```

### 4. 忘记 Web 登录密码？

如果启用了 Web 认证，可通过环境变量重置：

```bash
export QWENPAW_AUTH_PASSWORD=new_password
python -m qwenpaw.cli.main app
```

或删除配置文件重新初始化：

```bash
rm ~/.qwenpaw/config.json
python -m qwenpaw.cli.main init
```

---

## 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 如何贡献

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 开发规范

- 遵循 PEP 8 Python 代码规范
- 遵循 ESLint 前端代码规范
- 为新功能添加测试
- 更新相关文档

---

## 许可证

本项目基于 [Apache License 2.0](LICENSE) 开源协议。

---

## 致谢

本项目基于以下优秀的开源项目构建：

- [AgentScope](https://github.com/agentscope-ai/agentscope) - 多智能体框架
- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Python Web 框架
- [React](https://react.dev/) - 用户界面库
- [Ant Design](https://ant.design/) - 企业级 UI 设计语言

---

## 联系方式

如有问题或建议，欢迎提交 Issue 或 Pull Request。

---

**代码哈哈镜** - 让 AI 助手像哈哈镜一样，映射出你的需求，扭曲现实的限制，创造无限可能。