mirror of
https://github.com/SMNETSTUDIO/WeChat-AI.git
synced 2026-08-12 22:23:42 +08:00
143 lines
7.7 KiB
Markdown
143 lines
7.7 KiB
Markdown
<div align="center">
|
||
|
||
# WeChat-AI
|
||
|
||
**自托管微信角色扮演对话服务** · Self-hosted WeChat roleplay chatbot service
|
||
|
||
直连腾讯 **iLink**，数据存 **远端 Redis**，登录用 **LINUX DO OAuth**。
|
||
Connects directly to Tencent **iLink**, stores data in **remote Redis**, and authenticates via **LINUX DO OAuth**.
|
||
|
||
[功能 Features](#功能-features) · [架构 Architecture](#架构-architecture) · [快速开始 Quick Start](#快速开始-quick-start) · [文档 Docs](#文档-docs) · [许可证 License](#许可证-license)
|
||
|
||
[](https://linux.do/) [](https://t.me/smnet_group/105727)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 功能 Features
|
||
|
||
| 中文 | English |
|
||
|------|---------|
|
||
| LINUX DO OAuth 登录（用户 / 管理员） | LINUX DO OAuth login (user / admin) |
|
||
| 用户中心：扫码添加/删除微信机器人、批准私聊用户、分配人设 | User center: scan-QR add/remove WeChat bots, approve chat peers, assign personas |
|
||
| 用户对话：绑定 LINUX DO 后微信内 `@用户名` 请求对话，对方 `/同意` 后双向中继 | P2P chat: after binding, `@username` in WeChat to request a chat, peer replies `/agree` to relay messages both ways |
|
||
| 管理后台：数据面板、Token 用量、用户与机器人、部署节点、表情包审核 | Admin dashboard: stats, token usage, users & bots, deploy nodes, sticker moderation |
|
||
| 表情包广场：投稿 / 我的库 / 公开需审核；恶意图过滤 | Sticker square: submit / my library / public needs review; malicious-image filtering |
|
||
| 回复文字与图片表情（主人表情库 → 模型引用 slug → iLink CDN 发图） | Text + image sticker replies (owner sticker library → model references slug → sent via iLink CDN) |
|
||
| 输入状态指示（getconfig + sendtyping，回复送达即消失） | Typing indicator (getconfig + sendtyping, disappears when reply is delivered) |
|
||
| 入站图片理解（`VISION_ENABLED`，默认关闭；caption 模式人设模型无需视觉） | Inbound image understanding (`VISION_ENABLED`, off by default; `caption` mode needs no vision-capable roleplay model) |
|
||
| 入站语音转写（微信自带转写，默认开启） | Inbound voice transcription (WeChat built-in STT, on by default) |
|
||
| 远端 Redis 存储（bot token 与表情包均在 Redis） | Remote Redis storage (bot tokens & stickers in Redis) |
|
||
| OpenAI 兼容 LLM + 按日 Token 统计 | OpenAI-compatible LLM + daily token stats |
|
||
| 用户自定义模型 + 联网搜索（经 HF 工具网关出站，主站不直连用户 API） | User custom models + web search (egress only via HF tools gateway) |
|
||
| Chatflow：可视化编排（`/chatflow`），人设可选 prompt / chatflow 模式 | Chatflow: visual orchestration (`/chatflow`), personas support prompt / chatflow mode |
|
||
| 多节点同构部署 + Cloudflare Worker 负载均衡 | Multi-node homogeneous deployment + Cloudflare Worker LB |
|
||
| OTA 增量更新（文件差量 + 自动重启） | OTA incremental updates (file diff + auto restart) |
|
||
|
||
## 架构 Architecture
|
||
|
||
```
|
||
微信用户 ──► 腾讯 iLink ──► 本系统多节点 (收消息 / 人设+记忆 / LLM / 回消息)
|
||
WeChat user ──► Tencent iLink ──► multi-node system (receive / persona+memory / LLM / reply)
|
||
|
||
浏览器 ──► 主域名 CF Worker LB ──► Node-1…N (同一镜像, 共享 Redis)
|
||
Browser ──► main domain CF Worker LB ──► Node-1…N (same image, shared Redis)
|
||
```
|
||
|
||
## 快速开始 Quick Start
|
||
|
||
### 本地开发 Local Development
|
||
|
||
```bash
|
||
pnpm install
|
||
cp .env.example .env
|
||
# 必填 Required: REDIS_URL（Upstash 用 rediss://）、LLM_API_KEY（平台）、LINUXDO_* 、LINUXDO_ADMIN_IDS
|
||
# 用户自定义 LLM / 联网搜索：部署 huggingface/wechat-ai-tools，配置 TOOLS_BASE_URL + TOOLS_API_KEY
|
||
|
||
pnpm db:seed
|
||
pnpm diag
|
||
pnpm dev
|
||
```
|
||
|
||
页面 / Pages：
|
||
|
||
| 路径 Path | 说明 Description |
|
||
|-----------|------------------|
|
||
| `/` | 功能落地页 + OG 分享图 Landing page |
|
||
| `/app` | 用户中心 User center (LINUX DO login) |
|
||
| `/docs` | 使用文档 Documentation |
|
||
| `/admin` | 管理后台 Admin dashboard |
|
||
| `/chatflow` | Chatflow 编辑器 Chatflow editor |
|
||
|
||
### Docker 一键部署 One-Click Deploy
|
||
|
||
```bash
|
||
# 配置好 .env 后 After configuring .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
详见 / See `docs/docker.md`。
|
||
|
||
### 多节点 Multi-Node
|
||
|
||
每台服务器运行**同一镜像**，共享同一个 Upstash Redis，用户只访问主域名。Cloudflare Worker 负责健康检查与轮询分流，源站地址只写在 Worker 的 `ORIGINS` 中。详见 / See `cloudflare-worker/README.md`。
|
||
|
||
Each server runs the **same image**, shares one Upstash Redis; users only visit the main domain. A Cloudflare Worker handles health checks and round-robin, origin addresses live only in the Worker's `ORIGINS`.
|
||
|
||
## 文档 Docs
|
||
|
||
| 文档 Doc | 内容 Content |
|
||
|----------|-------------|
|
||
| [docs/upstash-redis.md](docs/upstash-redis.md) | Upstash Redis 配置 Redis setup |
|
||
| [docs/oauth-linuxdo.md](docs/oauth-linuxdo.md) | LINUX DO OAuth 配置 |
|
||
| [docs/docker.md](docs/docker.md) | Docker / 多节点部署 Multi-node deploy |
|
||
| [docs/cloudflare.md](docs/cloudflare.md) | Cloudflare 缓存 Cache |
|
||
| [cloudflare-worker/README.md](cloudflare-worker/README.md) | CF Worker 多源站 LB |
|
||
| [docs/ai-gateway.md](docs/ai-gateway.md) | AI 网关（主站 ↔ HF）AI gateway |
|
||
| [docs/chatflow.md](docs/chatflow.md) | Chatflow 编排 |
|
||
| [docs/admin-api.md](docs/admin-api.md) | 管理 API |
|
||
| [docs/runbook.md](docs/runbook.md) | 运维手册 Ops runbook |
|
||
| [docs/e2e-checklist.md](docs/e2e-checklist.md) | 真机验收清单 E2E checklist |
|
||
|
||
## 仓库结构 Repository Structure
|
||
|
||
```
|
||
apps/api # REST + iLink worker + Admin/App/Chatflow UI (public/*.html)
|
||
packages/ilink # iLink HTTP 客户端 iLink HTTP client
|
||
packages/db # Redis 仓储 / seed / 人设与模型连接 Redis repos / seed
|
||
packages/llm # OpenAI 兼容 chat + tools 网关客户端
|
||
packages/core # 会话、人设、记忆、路由、chatflow 引擎
|
||
huggingface/ # wechat-ai-tools：唯一外网 AI/搜索出口（可独立部署）
|
||
cloudflare-worker # 主域名负载均衡 Cloudflare Worker LB
|
||
docs/ # runbook、E2E 清单、ADR
|
||
scripts/ # 构建 / 打包 / 验收脚本 build / pack / accept scripts
|
||
```
|
||
|
||
## 验收 Acceptance
|
||
|
||
```bash
|
||
pnpm accept # 离线自动化门禁 offline automated gate
|
||
```
|
||
|
||
真机清单 / Real-device checklist：`docs/e2e-checklist.md` · 状态 / Status：`docs/ACCEPTANCE.md`
|
||
|
||
## 合规与风险 Compliance & Risk
|
||
|
||
- 使用腾讯 **微信 ClawBot / iLink** 能力，须遵守相关使用条款。
|
||
Using Tencent **WeChat ClawBot / iLink** capabilities requires compliance with the applicable terms.
|
||
- 个人 Bot 存在限流与处置风险；默认 **白名单用户** 才可对话。
|
||
Personal bots face rate-limit and takedown risks; by default only **approved users** can chat.
|
||
- 角色扮演内容会经 LLM API 出机；请自行评估隐私。
|
||
Roleplay content leaves the machine via LLM APIs; assess your own privacy posture.
|
||
- iLink 协议以实测为准，字段可能变更；适配层见 `packages/ilink`。
|
||
The iLink protocol is based on observed behavior and may change; the adapter lives in `packages/ilink`.
|
||
|
||
## 许可证 License
|
||
|
||
[Apache-2.0 with Commons Clause](LICENSE)
|
||
|
||
**禁止商用与转卖**：仅允许个人/非商业使用；不得以任何形式收取费用、提供付费托管/咨询服务，或将本代码用于商业产品转售。详见 [LICENSE](LICENSE)。
|
||
|
||
**No commercial use / no resale**: personal & non-commercial use only. You may not charge fees, offer paid hosting/support, or resell the code in commercial products. See [LICENSE](LICENSE).
|