码桶
发现社区成员的开源项目
README.md13.3 KB
# 奶狗 WeBot
> 一个跑在你自己服务器上的 **微信智能机器人**。基于微信 **iLink 开放平台**，内置 AI 智能助手、插件系统、技能 / MCP 工具、超级记忆、知识库、定时提醒等能力。**单用户、本地优先、数据自持**，开箱即用。
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[]()
---
## 💡 这是什么
奶狗 WeBot 是 [WeBot Plus](https://www.naigou.cn/contact/)（商业版）面向个人用户开源发布的精简版本，专注于「一个人 + 自己的微信号」的单机使用场景，未包含多用户、会员、积分、卡密售卖、后台管理等商业运营能力。
你可以用它：
- 把微信机器人接上大模型（OpenAI / 通义 / DeepSeek / 任意 OpenAI 兼容接口），让它替你聊天、查资料、写文案；
- 让 AI **自动记住你说过的账号、地址、纪念日、卡证**等（可随时查看 / 编辑 / 删除）；
- 一句话**设置提醒、订阅 RSS、生成图片、转写语音、检索你的知识库**；
- 安装社区 / 自己写的**插件**扩展能力；连接 **MCP 服务器**、安装**技能包**；
- 所有数据存在本地 SQLite，不依赖任何外部服务，**隐私可控**。
> 本版本所有高级能力（MCP / 技能 / 插件）**全部免费开放**，无会员门槛。
---
## ✨ 功能特性
### 核心
- **微信机器人绑定** — 控制台扫码即绑，自带聊天控制台（可收发图文 / 语音 / 文件）
- **AI 智能助手（smart）** — 自然语言交互，无需指令前缀，自动识别意图
- **插件系统** — 官方插件一键安装 / 启用 / 禁用；支持上传自己的插件
- **技能 & MCP** — 安装技能包、连接 MCP 服务器，扩展 AI 工具调用（均免费）
- **用户记忆（Memory）** — 自动沉淀重要信息，Markdown 可读写，隐私优先、可关闭
- **知识库 / IMA** — 检索与写入知识库、笔记，智能问答
- **定时提醒 / RSS / 每日简报 / 关键词回复** — 消息自动化
- **AI 图片生成、语音转文字、邮件** 等实用工具
### AI 智能助手细节
- 支持任意 **OpenAI 兼容** API（可自定义 endpoint、模型、Key）
- **Function Calling** 自动工具调用 + 多轮对话上下文（内存缓存 30 分钟）
- **微信语音自动转文字**：本地 Whisper（默认）或云端转写，识别后由 AI 理解回复
- **AI 图片生成**：独立图片接口（非对话接口），支持 base64 内联返回，国内服务器友好
- Token 用量统计与限额
### 与 WeBot Plus（商业版，需商业授权）的区别
| 能力 | 奶狗 WeBot（个人版） | WeBot Plus（商业版，需商业授权） |
|------|------|------|
| 适用场景 | 个人单机自用 | 团队 / 企业多账号运营 |
| 多用户 / 注册 | 单一管理员 | 支持 |
| 会员 / 积分 / 卡密体系 | 不提供 | 支持 |
| 管理后台 `/admin` | 不提供 | 提供 |
| 插件市场分享 / 挂售 | 仅自用安装 | 支持 |
| 登录方式 | 单一管理员（默认 `admin`/`admin123`） | 用户名 + 密码（多账号） |
| 智能助手模型 | 统一「AI 配置」全局模型 | 可逐机器人自定义 |
| 数据存储 | 内置 SQLite（零配置） | 可选 MySQL |
---
## 🧱 技术栈
| 层级 | 技术 |
|------|------|
| 运行时 | Node.js ≥ 20 |
| Web 框架 | Express 4 |
| 数据库 | SQLite（`node:sqlite`，无需额外安装） |
| 消息通道 | 微信 iLink OpenAPI |
| 前端 | React 18 + Vite 5 + TypeScript + Tailwind CSS + shadcn/ui + Radix + sonner |
| 本地推理 | `@huggingface/transformers` + `onnxruntime-node`（Whisper 语音识别） |
| 配置 | dotenv |
---
## 🚀 快速开始
### 环境要求
- **Node.js ≥ 20**（推荐 20 LTS 或 22）
- 一台能联网的普通机器（iLink 走云端通道，**无需公网 IP 或独立服务器**）
- 一台已安装 **微信** 的手机（用于扫码绑定机器人）
- （可选）一个 OpenAI 兼容的 AI 接口地址与 Key
### 1. 获取代码
```bash
git clone https://github.com/你的用户名/ngbot-open.git
cd ngbot-open
```
### 2. 安装依赖
```bash
npm install
```
> 仅服务端依赖。前端源码在 `web/`，已提供构建产物；如需自行改前端见下文「开发模式」。
### 3. 配置（可选但推荐）
复制 `.env.example` 为 `.env` 并按需修改：
```bash
cp .env.example .env
```
最简配置只需改两项（详见「配置说明」）：
```env
PORT=3000
SESSION_SECRET=请改成一段随机字符串
```
### 4. 启动
```bash
node server.js
```
看到日志输出监听端口即启动成功。浏览器访问 `http://你的服务器IP:3000`。
> 💡 生产环境可用 `pm2`：`pm2 start ecosystem.config.js`，项目已附带 `ecosystem.config.js`。
### 5. 登录
首次打开会跳到登录页。默认账号：
- **账号**：`admin`
- **密码**：`admin123`
登录后请到「个人中心」修改密码。
### 6. 绑定你的微信机器人
1. 左侧进入「控制台」；
2. 点击「创建机器人」，会生成一张二维码；
3. 用**手机微信**扫码（需微信内已具备 iLink 通道）完成绑定；
4. 状态变为「已绑定」后，即可在微信里给机器人发消息，或直接在控制台聊天框测试。
---
## ⚙️ 配置说明
配置文件为项目根目录 `.env`（不存在则使用默认值）。常用项：
| 变量 | 默认 | 说明 |
|------|------|------|
| `PORT` | `3000` | 服务端口 |
| `SESSION_SECRET` | `change-me-to-random-string` | **务必改成随机串**，否则会话可被伪造 |
| `WORKER_KEY` | `ilink_worker_2024` | `/worker?key=` 轮询密钥；仅本地轮询用，暴露在公网时请修改 |
| `ILINK_BASE` | `https://ilinkai.weixin.qq.com` | iLink 通道地址，一般无需改 |
| `ILINK_CDN` | `https://novac2c.cdn.weixin.qq.com/c2c` | 媒体 CDN 地址 |
| `CHANNEL_VERSION` | `2.0.0` | 通道版本 |
| `BASE_URL` | 空 | 公网可访问的基础地址（用于回调 / webhook），本地可留空 |
| `SQLITE_PATH` | `data/app.db` | SQLite 数据库文件路径 |
> 数据目录 `data/` 与日志目录 `logs/` 会在运行时自动创建，建议备份 `data/`。
---
## 🧭 使用指南
### AI 配置（最重要）
左侧「**AI 配置**」是**全局唯一的 AI 入口**，智能助手直接复用它：
- **对话接口**：填写 OpenAI 兼容的 `API Base` / `API Key` / 模型名；
- **图片生成**：独立接口（与对话分开），填图片接口 Base / Key / 模型 / 尺寸；
- **语音识别**：选择本地 Whisper 或云端转写；
- 保存后即时生效，无需重启。
### 智能助手（smart）
装好机器人后，直接在微信里对机器人说话即可，**不用加任何前缀**：
- 「帮我记一下我的快递单号是 SF123456」→ 写入记忆
- 「明天上午 9 点提醒我开会」→ 定时提醒
- 「今天有什么新闻 / 来份早报」→ 每日简报
- 「画一只在月亮上睡觉的猫」→ AI 图片生成
- 「我的记忆 / 导出记忆 / 关闭记忆」→ 记忆管理
### 插件
左侧「**插件市场**」→「系统插件」一键安装 / 启用；「用户插件」可上传自己的 `.js` 插件（仅你自己可用）。每个插件可调独立配置。
### 技能 & MCP
- **技能**：安装技能包（系统提示扩展 / 自定义工具 / 对话模板），增强 AI 行为。
- **MCP**：填写 MCP 服务器地址，工具会被自动发现并暴露给 AI 调用。
### 用户记忆（Memory）
「用户记忆」页可查看 / 在线编辑 / 下载 / 清除 AI 为你沉淀的信息。默认开启、隐私优先，可随时关闭。
### 控制台
「控制台」即聊天面板：可像微信一样收发消息，支持发送图片 / 文件 / 语音 / 视频，并实时显示插件处理事件日志，方便调试。
### 个人中心
修改登录密码、查看账号信息。
---
## 🔌 插件开发（简述）
插件是 `plugins/<id>/index.js`，导出 `meta` 与 `onMessage(msg, ctx)`：
```js
module.exports = {
meta: {
id: 'hello',
name: '示例插件',
description: '收到 hi 回复你好',
version: '1.0.0',
builtin: true,
},
async onMessage(msg, ctx) {
if (msg.content === 'hi') await ctx.sendText('你好呀！')
},
}
```
- `ctx.sendText(text)` / `ctx.sendMedia(path, mediaType, filename, playtime)` 发送消息；
- 用户配置通过 `meta.settingsSchema` 声明，前端自动生成表单；
- 改完插件需重启 `server.js` 生效。
完整文档见 `docs/插件开发指南.md`（控制台「文档」可在线查看）。
---
## 🗂️ 目录结构
```
ngbot-open/
├── server.js # 后端入口（Express + 静态托管 + SPA fallback）
├── config/ # 配置加载（合并 .env）
├── lib/ # 核心库：auth / db / plugins / stt ...
├── routes/ # HTTP 路由（api / skill / market ...）
├── plugins/ # 内置插件（smart / mcp / skill / memory / ima-knowledge ...）
├── services/ # worker 轮询、消息处理
├── web/ # 前端（React + Vite），构建产物在 web/dist
│ ├── src/ # 源码
│ └── dist/ # 构建产物（已由 npm run build 生成）
├── docs/ # 使用 / 插件开发文档
├── data/ # SQLite 数据库（运行时生成，建议备份）
├── logs/ # 运行日志（运行时生成）
├── .env.example # 配置样例
└── package.json
```
---
## 🛠️ 开发模式
改前端时需要重新构建：
```bash
cd web
npm install
npm run dev # 本地开发服务器 :5173，代理到后端
# 或仅构建产物：
npm run build # 输出到 web/dist，由 server.js 托管
```
> ⚠️ 改了 `web/src` 后**必须** `npm run build`，否则 `server.js` 仍提供旧的 `web/dist`。
---
## 🚢 部署建议
- **反向代理**：用 Nginx / Caddy 将域名反代到 `http://127.0.0.1:3000`，并配置 HTTPS；此时设 `BASE_URL=https://你的域名`。
- **进程守护**：`pm2 start ecosystem.config.js`（name `naigou-webot`）。
- **安全**：务必修改 `SESSION_SECRET`、登录密码；如对外暴露 `WORKER_KEY` 请一并修改。
- **备份**：定期备份 `data/app.db`。
---
## ❓ 常见问题
**Q：机器人收不到消息 / 消息不回复？**
A：确认控制台机器人状态为「已绑定」；检查服务端日志 `logs/` 是否有 iLink 拉取错误。
**Q：改了 AI Key 不生效？**
A：在「AI 配置」保存即生效（智能助手复用全局配置）。若仍无效，确认接口为 OpenAI 兼容且模型名正确。
**Q：语音消息没反应？**
A：默认本地 Whisper 首次会下载模型（缓存于 `data/stt-models`，可能较慢）；也可在「AI 配置」切到云端转写（需接口支持 `/v1/audio/transcriptions`）。
**Q：能多用户吗？**
A：奶狗 WeBot 为单管理员设计，无多用户 / 会员体系。需要多人或商业授权，请使用 WeBot Plus（商业版）。
---
## 📄 许可证
[MIT](LICENSE) — 可自由使用、修改、分发，但**不提供任何担保**。
---
## ☕ 致谢
本项目基于 WeBot Plus（商业版）裁剪而来，感谢所有插件 / 技能的贡献者。
---
## 💖 赞助支持
如果这个项目对你有帮助，欢迎扫码赞助我们 ☕ 你的支持是项目持续维护与迭代的动力！
> 赞助后可在 Issues 留言，或加入交流群获取优先支持。
---
## 📦 主要依赖
**后端（Node.js）**
- `express` · `express-session` · `session-file-store` — Web 服务与会话管理
- `cors` · `dotenv` · `multer` · `adm-zip` — 基础设施
- `axios` · `http-proxy-agent` · `socks-proxy-agent` — HTTP 请求与代理
- `bcryptjs` — 密码哈希
- `nodemailer` · `imapflow` · `mailparser` — 邮件收发与解析
- `silk-wasm` — 微信语音 silk 格式转码
- `@huggingface/transformers` · `onnxruntime-node` — 本地 Whisper 语音识别
**前端**：React 18 · Vite 5 · TypeScript · Tailwind CSS · shadcn/ui · Radix UI · sonner（详见上文「🧱 技术栈」）
## 🔗 参考项目与致谢
- [微信 iLink 开放平台](https://ilinkai.weixin.qq.com) — 机器人绑定与消息通道能力来源
- **WeBot Plus（商业版 / 多人版）** — 本项目的完整版前身，个人版由其裁剪而来（[商业授权](https://www.naigou.cn/contact/)）
- 前端基于 [shadcn/ui](https://ui.shadcn.com) · [Radix UI](https://www.radix-ui.com) · [Tailwind CSS](https://tailwindcss.com) · [Vite](https://vitejs.dev) 等开源生态构建
- 本地语音识别基于 [Hugging Face transformers.js](https://huggingface.co/docs/transformers.js) 与 [ONNX Runtime](https://onnxruntime.ai)
---
## 📚 更多文档
- [使用手册](./使用手册.md) — 从安装部署到各功能上手的逐步指南
- [开源说明](./开源说明.md) — 许可、开源范围、与商业版关系、贡献与免责
- 插件开发：`docs/插件开发指南.md`（控制台「文档」可在线查看）