ng-webot

# 奶狗 WeBot 使用手册

> 奶狗 WeBot 是个人版微信智能机器人，基于微信 **iLink 开放平台**，内置 AI 智能助手、插件系统、技能 / MCP、用户记忆、知识库、定时提醒等能力。**单管理员、本地优先、数据自持**。
>
> 本手册面向「刚部署好、准备上手使用」的用户，按使用顺序逐步说明。

---

## 1. 安装与启动

### 环境要求
- **Node.js ≥ 20**（推荐 20 LTS 或 22）
- 一台能联网的普通机器（iLink 走云端通道，**无需公网 IP 或独立服务器**）
- 一台已安装 **微信** 的手机（用于扫码绑定机器人）
- （可选）一个 OpenAI 兼容的 AI 接口地址与 Key

### 获取代码
```bash
git clone https://github.com/你的用户名/ngbot-open.git
cd ngbot-open
```

### 安装依赖
```bash
npm install
```
> 仅服务端依赖。前端已提供构建产物（`web/dist`）；如需自行改前端，见文末「进阶：修改前端」。

### 配置（推荐）
复制 `.env.example` 为 `.env` 并按需修改：
```bash
cp .env.example .env
```
最简配置只需两项：
```env
PORT=3000
SESSION_SECRET=请改成一段随机字符串
```
> `SESSION_SECRET` **务必修改**，否则会话可被伪造。其余配置一般保持默认即可。

### 启动
```bash
node server.js
```
看到日志输出监听端口即启动成功。浏览器访问 `http://你的服务器IP:3000`。
生产环境可用 `pm2 start ecosystem.config.js`。

### 登录
首次打开会跳到登录页。默认账号：
- **账号**：`admin`
- **密码**：`admin123`

登录后请到「个人中心」修改密码。

---

## 2. 绑定你的微信机器人

1. 左侧进入「**控制台**」；
2. 点击「**创建机器人**」，会生成一张二维码；
3. 用**手机微信**扫码（需微信内已具备 iLink 通道）完成绑定；
4. 状态变为「**已绑定**」后，即可在微信里给机器人发消息，或直接在控制台聊天框测试。

> 绑定无需公网服务器：iLink 走云端通道，本地内网机器也能正常收发消息。

---

## 3. AI 配置（最重要的一步）

左侧「**AI 配置**」是**全局唯一的 AI 入口**，智能助手直接复用它：

- **对话接口**：填写 OpenAI 兼容的 `API Base` / `API Key` / 模型名；
- **图片生成**：独立接口（与对话分开），填图片接口 Base / Key / 模型 / 尺寸；
- **语音识别**：选择本地 Whisper 或云端转写；
- 保存后即时生效，无需重启。

没有 AI Key 之前，机器人与你对话会报错，请先配好。

---

## 4. 智能助手（自然语言交互）

装好机器人后，直接在微信里对机器人说话即可，**不用加任何指令前缀**，AI 会自动识别意图：

| 你想做的事 | 直接说 |
|------|------|
| 记点东西 | 「帮我记一下我的快递单号是 SF123456」 |
| 设提醒 | 「明天上午 9 点提醒我开会」 |
| 看新闻 | 「今天有什么新闻 / 来份早报」 |
| 画图 | 「画一只在月亮上睡觉的猫」 |
| 管记忆 | 「我的记忆 / 导出记忆 / 关闭记忆」 |
| 查资料 | 「帮我查一下 xxx 的最新消息」 |

- 支持任意 **OpenAI 兼容** API；
- 支持 **Function Calling** 自动工具调用 + 多轮对话上下文（内存缓存 30 分钟）；
- 微信语音会**自动转文字**后由 AI 理解回复；
- 支持 **Token 用量统计与限额**。

---

## 5. 插件

左侧「**插件市场**」：
- 「**系统插件**」一键安装 / 启用 / 禁用；
- 「**用户插件**」可上传自己的 `.js` 插件（仅你自己可用）；
- 每个插件可调独立配置。

> 本版本所有高级能力（MCP / 技能 / 插件）**全部免费开放**，无会员门槛。

---

## 6. 技能 & MCP

- **技能**：安装技能包（系统提示扩展 / 自定义工具 / 对话模板），增强 AI 行为。
- **MCP**：填写 MCP 服务器地址，工具会被自动发现并暴露给 AI 调用。

---

## 7. 用户记忆（Memory）

「**用户记忆**」页可查看 / 在线编辑 / 下载 / 清除 AI 为你沉淀的信息（如账号、地址、纪念日、卡证等）。

- 默认开启、隐私优先；
- 可随时关闭（发送「关闭记忆」或在该页操作）；
- 数据以 Markdown 形式存在本地，可读可改。

---

## 8. 消息自动化

- **定时提醒**：「明天上午 9 点提醒我开会」；
- **RSS 订阅**：订阅你关注的源，更新时主动推送；
- **每日简报**：「来份早报」获取每日新闻摘要；
- **关键词回复**：配置关键词触发固定回复。

---

## 9. 图片生成 / 语音转文字 / 邮件

- **AI 图片生成**：独立图片接口，支持 base64 内联返回（国内服务器友好）；
- **语音转文字**：本地 Whisper（首次会下载模型，可能较慢）或云端转写；
- **邮件**：内置邮件收发能力（需在「AI 配置」或相关设置中填写 SMTP / IMAP）。

---

## 10. 控制台

「**控制台**」即聊天面板：可像微信一样收发消息，支持发送图片 / 文件 / 语音 / 视频，并实时显示插件处理事件日志，方便调试。

---

## 11. 个人中心

修改登录密码、查看账号信息。

---

## 12. 常见问题

**Q：机器人收不到消息 / 消息不回复？**
A：确认控制台机器人状态为「已绑定」；检查服务端日志 `logs/` 是否有 iLink 拉取错误；确认「AI 配置」已正确填写且接口可用。

**Q：改了 AI Key 不生效？**
A：在「AI 配置」保存即生效（智能助手复用全局配置）。若仍无效，确认接口为 OpenAI 兼容且模型名正确。

**Q：语音消息没反应？**
A：默认本地 Whisper 首次会下载模型（缓存于 `data/stt-models`，可能较慢）；也可在「AI 配置」切到云端转写（需接口支持 `/v1/audio/transcriptions`）。

**Q：能多用户吗？**
A：奶狗 WeBot 为单管理员设计，无多用户 / 会员体系。需要多人或商业授权，请使用 WeBot Plus（商业版）。

**Q：数据存在哪？**
A：全部存在本地 SQLite（`data/app.db`），不依赖任何外部服务，建议定期备份 `data/` 目录。

---

## 13. 进阶：修改前端

改了 `web/src` 后**必须**重新构建，否则 `server.js` 仍提供旧的 `web/dist`：
```bash
cd web
npm install
npm run dev      # 本地开发服务器 :5173，代理到后端
# 或仅构建产物：
npm run build    # 输出到 web/dist，由 server.js 托管
```

---

*更多细节见 [README.md](./README.md) 与 [开源说明.md](./开源说明.md)。插件开发详见 `docs/插件开发指南.md`（控制台「文档」可在线查看）。*