# XINGZIER AI

> 🤖 智能 AI 助手平台 - 支持多种 AI 模型、本地部署、飞书/Discord 等频道集成

---

## 🚀 快速上手指南（新手必读）

**📖 完整安装教程**：[docs/QUICKSTART.md](docs/QUICKSTART.md)

### 3 步快速开始

```bash
# 1. 安装
pip install xingzierai

# 2. 初始化
xingzierai init

# 3. 启动
xingzierai run
```

然后打开浏览器访问 http://localhost:8555

---

## ✨ 功能特性

- 🌐 **多模型支持** - OpenAI GPT-4、Anthropic Claude、Google Gemini、OpenRouter 等
- 💻 **本地模型** - 支持 llama.cpp、Ollama、Apple MLX (M1/M2/M3)
- 📱 **多频道集成** - 飞书、Discord、Telegram、微信企业版等
- 🖥️ **Web 控制台** - 友好的 Web 界面管理配置
- 🔄 **实时对话** - 支持流式输出、上下文记忆
- 🛡️ **安全可靠** - 本地部署，数据完全自主控制

---

## 📦 安装

### 基本安装

```bash
pip install xingzierai
```

### Apple Silicon Mac (M1/M2/M3)

```bash
pip install xingzierai[mlx]
```

### 完整安装（包含所有功能）

```bash
pip install xingzierai[full]
```

---

## 🆘 疑难解答

| 问题 | 解决方案 |
|------|----------|
| 安装报错 | [点击查看常见问题](docs/QUICKSTART.md#q1安装时报错-permission-denied) |
| 启动失败 | [点击查看解决方案](docs/QUICKSTART.md#q4启动报错-port-already-in-use) |
| API 配置 | [点击查看配置指南](docs/QUICKSTART.md#-首次配置) |

---

## 📚 完整文档

- [📖 新手安装指南](docs/QUICKSTART.md) - 500行详细安装教程
- [🔧 API 文档](docs/API.md) - 开发者 API 参考
- [📡 频道配置](docs/CHANNELS.md) - 飞书/Discord 等配置
- 💾 [本地模型](docs/LOCAL_MODELS.md) - llama.cpp/Ollama 配置

---

## 🖥️ 系统要求

| 项目 | 最低 | 推荐 |
|------|------|------|
| Python | 3.10 | 3.11/3.12 |
| 内存 | 4GB | 8GB+ |
| 系统 | Win10+, macOS 10.14+, Ubuntu 18.04+ | Win11, macOS 13+, Ubuntu 22.04+ |

---

## ⚙️ 配置

### 环境变量

```bash
# API 密钥
export XINGZIERAI_API_KEY=sk-or-v1-xxxxx

# CORS 配置（允许的前端域名）
export XINGZIERAI_CORS_ORIGINS=http://localhost:8555

# LLM 超时时间（秒）
export XINGZIERAI_LLM_TIMEOUT=300
```

---

## 🚀 启动

```bash
# 基本启动
xingzierai run

# 指定端口
xingzierai run --port 9000

# 后台运行
nohup xingzierai run > app.log 2>&1 &
```

访问 http://localhost:8555 打开 Web 控制台。

---

## 🛠️ 开发

```bash
# 克隆仓库
git clone https://github.com/your-repo/xingzierai.git
cd xingzierai

# 开发模式安装
pip install -e .

# 构建发布包
python -m build
```

---

## 📄 许可证

MIT License

---

## 🙏 致谢

- [AgentScope](https://github.com/modelscope/agentscope) - AI 模型框架
- [FastAPI](https://fastapi.tiangolo.com/) - Web 框架
- [React](https://react.dev/) - 前端框架

---

<p align="center">
  <strong>Made with ❤️ by XINGZIER AI Team</strong>
</p>
