upstream/mi-gpt
1
0
Fork 0
mirror of https://github.com/idootop/mi-gpt.git synced 2025-04-06 19:41:30 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

refactor: 重构 docs 文档目录结构

Browse Source
This commit is contained in:
WJG 2024-06-10 16:39:34 +08:00
parent 8d3bbd2992
commit 46ff69d923
No known key found for this signature in database
GPG Key ID: 258474EF8590014A
8 changed files with 284 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

222
README.md
View File

@ -18,7 +18,7 @@
而小爱音箱就像是你的智能家居专属管家，全心全意为你服务，释放智能家居的真正潜力。
## ⚡️ 项目预览
## 🔥 项目预览
👉 查看完整演示视频：【[整活！将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手～](https://www.bilibili.com/video/BV1N1421y7qn/?share_source=copy_web&vd_source=5d4e78ff2a0dc6a661baa65f479199c1)】
@ -26,14 +26,14 @@
## ✨ 项目亮点
- **🎓 LLM 回答**。想象一下，你的小爱音箱变身聊天高手，可以使用 [ChatGPT](https://chat.openai.com) 等大模型来回答你的问题。
- **🎓 AI 问答**。想象一下，当小爱音箱接入大模型后，上知天文，下知地理，从“人工智障”秒变学霸。
- **🎭 角色扮演**。一秒调教小爱，无论是成为你的完美伴侣，还是那个能听你倾诉心事的贴心闺蜜，都不在话下。
- **💬 流式响应**。爱情来得太快就像龙卷风，而你的小爱音箱也是，对你的爱意秒回，爱你不会让你等太久。
- **🧠 长短期记忆**。小爱音箱现在能记住你们之间的每一次对话，越聊越默契，就像是你身边的老朋友。
- **🔊 自定义 TTS**。厌倦了小爱同学的语音？帮你解锁[「豆包」](https://doubao.com)同款音色，就像真人在回你的消息。
- **🤖️ 智能家居 Agent**。心情不好？小爱立刻懂你，自动帮你播放喜欢的音乐，调节灯光，逗你开心。_TODO_
## 🚀 启动项目
## ⚡️ 快速开始
`MiGPT` 有两种启动方式: [Docker](#docker) 和 [Node.js](#nodejs)。
@ -43,15 +43,13 @@
对于电脑小白或者不想自己配置代码运行环境（Node）的同学，可以使用 Docker 启动方式。
请先按照[「配置参数」](#%EF%B8%8F-配置参数)章节，配置好你的 `.env` 和 `.migpt.js` 文件，然后使用以下命令启动 docker：
请先按照 [⚙️ 参数设置](https://github.com/idootop/mi-gpt/blob/main/docs/settings.md) 相关说明，配置好你的 `.env` 和 `.migpt.js` 文件，然后使用以下命令启动 docker：
```shell
docker run -d --env-file $(pwd)/.env \
-v $(pwd)/.migpt.js:/app/.migpt.js \
idootop/mi-gpt:latest
docker run --env-file $(pwd)/.env -v $(pwd)/.migpt.js:/app/.migpt.js idootop/mi-gpt:latest
```
注意：在 Windows 终端下不支持使用 `$(pwd)` 获取当前工作路径，需要将配置文件路径替换为绝对路径。
注意：在 Windows 终端下需要将配置文件路径 `$(pwd)` 替换为绝对路径。
### Node.js
@ -63,7 +61,7 @@ docker run -d --env-file $(pwd)/.env \
npm install mi-gpt # 安装依赖
```
然后，创建并启动 `MiGPT` 实例。初始化参数的具体含义请看下面的[「配置参数」](#%EF%B8%8F-配置参数)章节。
然后，创建并启动 `MiGPT` 实例。初始化参数的具体说明请到 [⚙️ 参数设置](https://github.com/idootop/mi-gpt/blob/main/docs/settings.md) 查看。
```typescript
import { MiGPT } from "mi-gpt";
@ -82,199 +80,20 @@ async function main() {
main();
```
注意：此模式下并不会主动读取 `.env` 和 `.migpt.json` 中的配置信息，你需要自己初始化 Node 环境变量，
注意：此模式下并不会主动读取 `.env` 和 `.migpt.js` 中的配置信息，你需要手动初始化 Node 环境变量，并将 `.migpt.js` 中的参数作为 `MiGPT.create` 的初始化参数传入。👉 [示例代码](https://github.com/idootop/mi-gpt/blob/example/index.ts)
并将 `.migpt.json` 中的参数作为 `MiGPT.create` 的初始化参数传入。👉 [示例代码](https://github.com/idootop/mi-gpt/blob/example/index.ts)
## 📖 项目文档
## ⚙️ 配置参数
更多配置教程和使用说明，请参考下方文档。
### .migpt.js
- [⚙️ 参数设置](https://github.com/idootop/mi-gpt/blob/main/docs/settings.md)
- [💬 常见问题](https://github.com/idootop/mi-gpt/blob/main/docs/faq.md)
- [🛠️ 本地开发](https://github.com/idootop/mi-gpt/blob/main/docs/development.md)
- [💎 工作原理](https://github.com/idootop/mi-gpt/blob/main/docs/how-it-works.md)
- [✨ 更新日志](https://github.com/idootop/mi-gpt/blob/main/docs/changelog.md)
- [🚀 Roadmap](https://github.com/idootop/mi-gpt/blob/main/docs/roadmap.md)
重命名本项目根目录下的 [.migpt.example.js](https://github.com/idootop/mi-gpt/blob/main/.migpt.example.js) 文件为 `.migpt.js`。
然后，将里面的配置参数修改成你自己的，参数含义如下：
| 参数名称 | 描述 | 示例 |
| ---------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| **bot** | | |
| `name` | 对方名称（小爱音箱） | `"傻妞"` |
| `profile` | 对方的个人简介/人设 | `"性别女，性格乖巧可爱，喜欢搞怪，爱吃醋。"` |
| **master** | | |
| `name` | 主人名称（我自己） | `"陆小千"` |
| `profile` | 主人的个人简介/人设 | `"性别男，善良正直，总是舍己为人，是傻妞的主人。"` |
| **room** | | |
| `name` | 会话群名称 | `"魔幻手机"` |
| `description` | 会话群简介 | `"傻妞和陆小千的私聊"` |
| **speaker** | | |
| `userId` | [小米 ID](https://account.xiaomi.com/fe/service/account/profile)（注意：不是手机号或邮箱） | `"987654321"` |
| `password` | 账户密码 | `"123456"` |
| `did` | 小爱音箱 ID 或名称 | `"小爱音箱 Pro"` |
| `ttsCommand` | 小爱音箱 TTS 指令（[可在此查询](https://home.miot-spec.com)） | `[5, 1]` |
| `wakeUpCommand` | 小爱音箱唤醒指令（[可在此查询](https://home.miot-spec.com)） | `[5, 3]` |
| **speaker 其他参数（可选）** |
| `callAIKeywords` | 当消息以关键词开头时，会调用 AI 来响应用户消息 | `["请", "傻妞"]` |
| `wakeUpKeywords` | 当消息以关键词开头时，会进入 AI 唤醒状态 | `["召唤傻妞", "打开傻妞"]` |
| `exitKeywords` | 当消息以关键词开头时，会退出 AI 唤醒状态 | `["退出傻妞", "关闭傻妞"]` |
| `onEnterAI` | 进入 AI 模式的欢迎语 | `["你好，我是傻妞，很高兴认识你"]` |
| `onExitAI` | 退出 AI 模式的提示语 | `["傻妞已退出"]` |
| `onAIAsking` | AI 开始回答时的提示语 | `["让我先想想", "请稍等"]` |
| `onAIReplied` | AI 结束回答时的提示语 | `["我说完了", "还有其他问题吗"]` |
| `onAIError` | AI 回答异常时的提示语 | `["出错了，请稍后再试吧！"]` |
| `playingCommand` | 查询小爱音箱是否在播放中指令（[可在此查询](https://home.miot-spec.com)） | `[3, 1, 1]` |
| `streamResponse` | 是否启用流式响应（部分小爱音箱型号不支持查询播放状态，此时需要关闭流式响应） | `true` |
| `exitKeepAliveAfter` | 无响应一段时间后，多久自动退出唤醒模式（单位秒，默认 30 秒） | `30` |
### 环境变量
重命名本项目根目录下的 [.env.example](https://github.com/idootop/mi-gpt/blob/main/.env.example) 文件为 `.env`。
然后，将里面的环境变量修改成你自己的，参数含义如下：
| 环境变量名称 | 描述 | 示例 |
| ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
| **OpenAI** | | |
| `OPENAI_API_KEY` | OpenAI API 密钥 | `abc123` |
| `OPENAI_MODEL` | 使用的 OpenAI 模型 | `gpt-4o` |
| `OPENAI_BASE_URL` | 可选，OpenAI API BaseURL | `https://api.openai.com/v1` |
| `AZURE_OPENAI_API_KEY` | 可选，[Microsoft Azure OpenAI](https://www.npmjs.com/package/openai#microsoft-azure-openai) | `abc123` |
| **提示音效（可选）** | | |
| `AUDIO_SILENT` | 静音音频链接 | `"https://example.com/slient.wav"` |
| `AUDIO_BEEP` | 默认提示音链接 | `"https://example.com/beep.wav"` |
| `AUDIO_ACTIVE` | 唤醒提示音链接 | `"https://example.com/active.wav"` |
| `AUDIO_ERROR` | 出错提示音链接 | `"https://example.com/error.wav"` |
| **豆包 TTS（可选）** | | |
| `TTS_DOUBAO` | 豆包 TTS 接口 | `"https://example.com/tts.wav"` |
| `SPEAKERS_DOUBAO` | 豆包 TTS 音色列表接口 | `"https://example.com/tts-speakers"` |
## 💬 常见问题
**Q：支持哪些型号的小爱音箱？**
大部分型号的小爱音箱都支持，推荐小爱音箱 Pro（完美运行）。部分机型的 MioT 接口开放能力并不完整，比如小米音箱 Play 增强版（L05C），将会导致 `MiGPT` 部分功能异常，相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。
**Q：除了 OpenAI 还支持哪些模型，如何设置？**
理论上兼容 [OpenAI SDK](https://www.npmjs.com/package/openai) 的模型都支持，只需修改环境变量即可接入到 MiGPT。
比如：[通义千问](https://help.aliyun.com/zh/dashscope/developer-reference/compatibility-of-openai-with-dashscope/?spm=a2c4g.11186623.0.i1)、[零一万物](https://platform.01.ai/docs#making-an-api-request)、[Moonshot](https://platform.moonshot.cn/docs/api/chat)、[DeepSeek](https://platform.deepseek.com/api-docs/) 等，以 Moonshot 为例：
```shell
OPENAI_BASE_URL=https://api.moonshot.cn/v1
OPENAI_MODEL=moonshot-v1-8k
OPENAI_API_KEY=$MOONSHOT_API_KEY
```
**Q：什么是唤醒模式？**
`唤醒模式` 类似于小爱技能，可能让你在跟小爱互动的时候，无需每句话都要以“小爱同学”开头唤醒。
关于唤醒模式的更多细节，请查看这里：https://github.com/idootop/mi-gpt/issues/28
**Q：提示登录小米账号失败，无法正常启动**
1. **账号密码不正确**：小米 ID 并非手机号或邮箱，请在[「个人信息」-「小米 ID」](https://account.xiaomi.com/fe/service/account/profile)查看。
2. **网络环境异常**：如果你是在海外服务器等，非中国大陆网络环境下登录小米账号，需要先同意小米的「个人数据跨境传输」协议，然后按照提示验证手机号或邮箱，等待大约 30 分钟之后即可正常登录。[👉 相关教程](https://github.com/idootop/mi-gpt/issues/22#issuecomment-2150535622)
**Q：小爱音箱收到消息后，没有调用 AI 进行回复**
`MiGPT` 收到消息默认不会调用 AI 进行回复，只会回复以唤醒词开头的消息，比如：“请问 xxx”、“你 xxx” 等，你也可以自定义唤醒词（`callAIKeywords`）列表。
**Q：小爱音箱没有播放 AI 的回答，但控制台有打印 AI 的回复**
不同型号的小爱音箱 TTS 指令不同: [issues#5](https://github.com/idootop/mi-gpt/issues/5#issuecomment-2122881495)
请到 <https://home.miot-spec.com> 查询具体指令，并修改配置文件中的 `ttsCommand` 参数。
<details>
<summary>👉 查看教程</summary>
![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/search.jpg)
![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/command.jpg)
</details>
**Q：小爱音箱没有读完整个句子，总是戛然而止**
部分型号的小爱音箱不支持通过 Mina 获取设备播放状态，只能通过 MiOT 指令查询。
请到 <https://home.miot-spec.com> 查询具体指令，并修改配置文件中的 `playingCommand` 参数。
<details>
<summary>👉 查看教程</summary>
![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/playing.png)
</details>
如果修改参数后问题仍然存在，说明你的设备不支持通过开放接口查询播放状态（比如：小米音箱 Play 增强版），**此问题无解**。建议更换其他型号的小爱音箱（推荐小爱音箱 Pro），相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。
或者你也可以关闭配置文件中的流式响应（streamResponse）选项，确保小爱能够回复完整的句子。不过需要注意的是，关闭流式响应后，唤醒模式等功能将会失效。
**Q: 为什么小爱音箱会在 AI 回答之前抢话？**
与本项目的实现原理有关。本项目通过轮询小米接口获取最新的对话信息，当检测到小爱在回复的时候会通过播放静音音频等方式快速 mute 掉小爱原来的回复。
但是从小爱开始回复，到上报状态给小米服务云端，再到本项目通过小米云端接口轮训到这个状态变更，中间会有大约 1 -2 秒的延迟时间，无解。
这个问题，理论上需要通过刷机才能完美解决，可以参考下面的相关讨论：
- https://github.com/yihong0618/xiaogpt/issues/515#issuecomment-2121602572
- https://github.com/idootop/mi-gpt/issues/21#issuecomment-2147125219
**Q：启动 docker 提示 ERR_MODULE_NOT_FOUND，无法正常启动**
在 Windows 终端（比如：PowerShell、cmd）下，无法使用 `$(pwd)` 获取当前工作目录绝对路径，需要填写 `.env` 和 `.migpt.js` 文件的绝对路径。相关 [issue](https://github.com/idootop/mi-gpt/issues/26#issuecomment-2151381521)
<details>
<summary>👉 查看示例</summary>
请将下面的 `/绝对路径/` 替换为你当前目录的绝对路径：
```shell
docker run -d --env-file /绝对路径/.env \
-v /绝对路径/.migpt.js:/app/.migpt.js \
idootop/mi-gpt:latest
```
Windows PowerShell 终端
```shell
docker run -d --env-file $pwd\.env `
-v $pwd\.migpt.js:/app/.migpt.js `
idootop/mi-gpt:latest
```
Windows cmd 终端
```shell
docker run -d --env-file %cd%\.env ^
-v %cd%\.migpt.js:/app/.migpt.js ^
idootop/mi-gpt:latest
```
</details>
**Q：我 Clone 了这个仓库，但是本地启动失败**
如果你是通过 clone 本项目仓库的方式来运行，记得在 `start` 之前先 `build` 一下。
```shell
pnpm install && pnpm build && pnpm start
```
另外， `start` 命令默认没有注入 `.env` 文件里的环境变量。你可以在 VS Code 里按 F5 直接运行，会自动读取 `.env` ，或者将启动脚本改为：
```shell
node --env-file=.env app.js
```
**Q：怎样使用豆包的音色**
此功能需要豆包 TTS 接口支持，本项目暂不对外提供此服务。
**Q：我还有其他问题**
请在此处提交 [issue](https://github.com/idootop/mi-gpt/issues) 反馈，并提供详细的问题描述和相关错误截图。
> 提示：大多数的问题都可以在「[💬 常见问题](https://github.com/idootop/mi-gpt/blob/main/docs/faq.md)」中找到答案。
## 🚨 免责声明
@ -285,6 +104,7 @@ node --env-file=.env app.js
## ❤️ 鸣谢
- <https://github.com/yihong0618/xiaogpt>
- <https://github.com/inu1255/mi-service>
- <https://github.com/Yonsm/MiService>
- https://github.com/yihong0618/xiaogpt
- https://github.com/jialeicui/open-lx01
- https://github.com/inu1255/mi-service
- https://github.com/Yonsm/MiService

32
CHANGELOG.md → docs/changelog.md
View File

@ -1,72 +1,74 @@
# v3.0.1
# ✨ 更新日志
## v 3.0.1
- 修复 README 配置参数表格样式
# v3.0.0
## v 3.0.0
## ✨ 新功能 & 优化
### ✨ 新功能 & 优化
- 新增 `streamResponse` 流式响应控制开关，确保小爱的回复是完整的句子（[issue#20](https://github.com/idootop/mi-gpt/issues/20)）
- 添加其他 LLM 的配置教程（比如通义千问，moonshot 等）（[issue#11](https://github.com/idootop/mi-gpt/issues/11)）
- 添加对支持小爱音箱型号的说明（[issue#14](https://github.com/idootop/mi-gpt/issues/14)）
- 优化配置文件示例和使用教程（[issue#22](https://github.com/idootop/mi-gpt/issues/22)）
## 🐛 修复
### 🐛 修复
- 修复 AI 响应异常时未播放提示语/音的问题
- 修复提示音链接为空时自动播放音乐的问题
# v2.1.2
## v 2.1.2
- 修复小爱回复无法被终止的问题（[issue#5](https://github.com/idootop/mi-gpt/issues/5)）
# v2.1.1
## v 2.1.1
- 修复 DB 初始化失败的问题（[issue#17](https://github.com/idootop/mi-gpt/issues/17)）
- 优化版本号读取方式（import 静态导入）
# v2.1.0
## v 2.1.0
- 优化 Docker 镜像体积
- 新增 `playingCommand` 选项
- 修复小爱音箱回复戛然而止的问题（[issue#14](https://github.com/idootop/mi-gpt/issues/14)）
# v2.0.1
## v 2.0.1
- 新增 ARMv7 Docker 镜像（[issue#15](https://github.com/idootop/mi-gpt/issues/15)）
- 新增 debug 开关，用于调试（[issue#14](https://github.com/idootop/mi-gpt/issues/14)）
# v2.0.0
## v 2.0.0
## 🚨 Breaking changes
### 🚨 Breaking changes
- `callAIPrefix` 更名为 `callAIKeywords`
- `wakeUpKeywords`、`exitKeywords` 匹配规则由包含(includes)变更为起始(startsWith)
## ✨ 新功能 & 优化
### ✨ 新功能 & 优化
- 支持 Microsoft Azure OpenAI（[#7](https://github.com/idootop/mi-gpt/issues/7)）
- 新增 LLM 响应完毕提示语：onAIReplied
- 优化 `.mi.example.js` 配置参数实例
- 优化唤醒模式下播放状态检测间隔，限制最低为 500 ms
## 🐛 修复
### 🐛 修复
- 修复唤醒模式下 LLM 回复不发音或过短的问题（[#9](https://github.com/idootop/mi-gpt/issues/9)）
- 修复部分场景下 LLM 返回数据格式异常的问题
- 修复唤醒词配置格式，使其与原始文档行为一致（[#8](https://github.com/idootop/mi-gpt/issues/8)）
# v1.2.0
## v 1.2.0
- 新增小爱音箱 TTS 与唤醒指令选项
- 更新默认模型为 gpt-4o
# v1.1.0
## v 1.1.0
- 新增 Arm64 Docker 镜像
- 替换 Yarn 包管理工具为 Pnpm
# v1.0.0
## v 1.0.0
- 支持人物设定
- 支持连续对话

3
docs/development.md Normal file
View File

@ -0,0 +1,3 @@
# 🛠️ 本地开发
整理中，稍后更新。

129
docs/faq.md Normal file
View File

@ -0,0 +1,129 @@
# 💬 常见问题
### Q：支持哪些型号的小爱音箱？
大部分型号的小爱音箱都支持，推荐小爱音箱 Pro（完美运行）。部分机型的 MioT 接口开放能力并不完整，比如小米音箱 Play 增强版（L05C），将会导致 `MiGPT` 部分功能异常，相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。
### Q：除了 OpenAI 还支持哪些模型，如何设置？
理论上兼容 [OpenAI SDK](https://www.npmjs.com/package/openai) 的模型都支持，只需修改环境变量即可接入到 MiGPT。
比如：[通义千问](https://help.aliyun.com/zh/dashscope/developer-reference/compatibility-of-openai-with-dashscope/?spm=a2c4g.11186623.0.i1)、[零一万物](https://platform.01.ai/docs#making-an-api-request)、[Moonshot](https://platform.moonshot.cn/docs/api/chat)、[DeepSeek](https://platform.deepseek.com/api-docs/) 等，以 Moonshot 为例：
```shell
OPENAI_BASE_URL=https://api.moonshot.cn/v1
OPENAI_MODEL=moonshot-v1-8k
OPENAI_API_KEY=$MOONSHOT_API_KEY
```
### Q：什么是唤醒模式？
`唤醒模式` 类似于小爱技能，可能让你在跟小爱互动的时候，无需每句话都要以“小爱同学”开头唤醒。
关于唤醒模式的更多细节，请查看这里：https://github.com/idootop/mi-gpt/issues/28
### Q：提示登录小米账号失败，无法正常启动
1. ## 账号密码不正确：小米 ID 并非手机号或邮箱，请在[「个人信息」-「小米 ID」](https://account.xiaomi.com/fe/service/account/profile)查看。
2. ## 网络环境异常：如果你是在海外服务器等，非中国大陆网络环境下登录小米账号，需要先同意小米的「个人数据跨境传输」协议，然后按照提示验证手机号或邮箱，等待大约 30 分钟之后即可正常登录。[👉 相关教程](https://github.com/idootop/mi-gpt/issues/22#issuecomment-2150535622)
### Q：小爱音箱收到消息后，没有调用 AI 进行回复
`MiGPT` 收到消息默认不会调用 AI 进行回复，只会回复以唤醒词开头的消息，比如：“请问 xxx”、“你 xxx” 等，你也可以自定义唤醒词（`callAIKeywords`）列表。
### Q：小爱音箱没有播放 AI 的回答，但控制台有打印 AI 的回复
不同型号的小爱音箱 TTS 指令不同: [issues#5](https://github.com/idootop/mi-gpt/issues/5#issuecomment-2122881495)
请到 <https://home.miot-spec.com> 查询具体指令，并修改配置文件中的 `ttsCommand` 参数。
<details>
<summary>👉 查看教程</summary>
![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/search.jpg)
![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/command.jpg)
</details>
### Q：小爱音箱没有读完整个句子，总是戛然而止
部分型号的小爱音箱不支持通过 Mina 获取设备播放状态，只能通过 MiOT 指令查询。
请到 <https://home.miot-spec.com> 查询具体指令，并修改配置文件中的 `playingCommand` 参数。
<details>
<summary>👉 查看教程</summary>
![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/playing.png)
</details>
如果修改参数后问题仍然存在，说明你的设备不支持通过开放接口查询播放状态（比如：小米音箱 Play 增强版），## 此问题无解。建议更换其他型号的小爱音箱（推荐小爱音箱 Pro），相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。
或者你也可以关闭配置文件中的流式响应（streamResponse）选项，确保小爱能够回复完整的句子。不过需要注意的是，关闭流式响应后，唤醒模式等功能将会失效。
### Q: 为什么小爱音箱会在 AI 回答之前抢话？
与本项目的实现原理有关。本项目通过轮询小米接口获取最新的对话信息，当检测到小爱在回复的时候会通过播放静音音频等方式快速 mute 掉小爱原来的回复。
但是从小爱开始回复，到上报状态给小米服务云端，再到本项目通过小米云端接口轮训到这个状态变更，中间会有大约 1 -2 秒的延迟时间，无解。
这个问题，理论上需要通过刷机才能完美解决，可以参考下面的相关讨论：
- https://github.com/yihong0618/xiaogpt/issues/515#issuecomment-2121602572
- https://github.com/idootop/mi-gpt/issues/21#issuecomment-2147125219
### Q：启动 docker 提示 ERR_MODULE_NOT_FOUND，无法正常启动
在 Windows 终端（比如：PowerShell、cmd）下，无法使用 `$(pwd)` 获取当前工作目录绝对路径，需要填写 `.env` 和 `.migpt.js` 文件的绝对路径。相关 [issue](https://github.com/idootop/mi-gpt/issues/26#issuecomment-2151381521)
<details>
<summary>👉 查看示例</summary>
请将下面的 `/绝对路径/` 替换为你当前目录的绝对路径：
```shell
docker run -d --env-file /绝对路径/.env \
-v /绝对路径/.migpt.js:/app/.migpt.js \
idootop/mi-gpt:latest
```
Windows PowerShell 终端
```shell
docker run -d --env-file $pwd\.env `
-v $pwd\.migpt.js:/app/.migpt.js `
idootop/mi-gpt:latest
```
Windows cmd 终端
```shell
docker run -d --env-file %cd%\.env ^
-v %cd%\.migpt.js:/app/.migpt.js ^
idootop/mi-gpt:latest
```
</details>
### Q：我 Clone 了这个仓库，但是本地启动失败
如果你是通过 clone 本项目仓库的方式来运行，记得在 `start` 之前先 `build` 一下。
```shell
pnpm install && pnpm build && pnpm start
```
另外， `start` 命令默认没有注入 `.env` 文件里的环境变量。你可以在 VS Code 里按 F5 直接运行，会自动读取 `.env` ，或者将启动脚本改为：
```shell
node --env-file=.env app.js
```
### Q：怎样使用豆包的音色
此功能需要豆包 TTS 接口支持，本项目暂不对外提供此服务。
### Q：我还有其他问题
请在此处提交 [issue](https://github.com/idootop/mi-gpt/issues) 反馈，并提供详细的问题描述和相关错误截图。

3
docs/how-it-works.md Normal file
View File

@ -0,0 +1,3 @@
# 💎 工作原理
整理中，稍后更新。

32
docs/roadmap.md Normal file
View File

@ -0,0 +1,32 @@
# 🚀 Roadmap
> 以下是一些可以优化的地方或新功能，仅作记录之用，暂时没有开发计划。
## 🐛 修复
- 【重要】自动刷新小米账号登录凭证
- 小米账号登录凭证有效期 1 个月，到期后需要自动刷新（mi-service-lite）
## 💪 优化
- 自动识别设备型号
- 通过查询设备 miot spec 文件，自动获取指令参数
- 自动识别设备属性值是否有读取权限
- 添加镜像更新说明
- 添加 db 文件导入/出教程，用于备份恢复对话历史记录
## ✨ 新功能
- 增强对话系统
- 支持自定义对话系统 Prompt 模板
- 添加是否启用对话模式的开关
- 支持通过语音命令清除上下文
- MioT AI Agents
- 支持小爱音箱控制米家设备
- 通过 Agent 机制自动调用合适的工具（设备）
- RAG
- wikis embedding
- memory embedding
- 插件系统
- 自定义语音指令
- 联网查查询最新数据

59
docs/settings.md Normal file
View File

@ -0,0 +1,59 @@
# ⚙️ 配置参数
## .migpt.js
重命名本项目根目录下的 [.migpt.example.js](https://github.com/idootop/mi-gpt/blob/main/.migpt.example.js) 文件为 `.migpt.js`。
然后，将里面的配置参数修改成你自己的，参数含义如下：
| 参数名称 | 描述 | 示例 |
| ---------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| **bot** | | |
| `name` | 对方名称（小爱音箱） | `"傻妞"` |
| `profile` | 对方的个人简介/人设 | `"性别女，性格乖巧可爱，喜欢搞怪，爱吃醋。"` |
| **master** | | |
| `name` | 主人名称（我自己） | `"陆小千"` |
| `profile` | 主人的个人简介/人设 | `"性别男，善良正直，总是舍己为人，是傻妞的主人。"` |
| **room** | | |
| `name` | 会话群名称 | `"魔幻手机"` |
| `description` | 会话群简介 | `"傻妞和陆小千的私聊"` |
| **speaker** | | |
| `userId` | [小米 ID](https://account.xiaomi.com/fe/service/account/profile)（注意：不是手机号或邮箱） | `"987654321"` |
| `password` | 账户密码 | `"123456"` |
| `did` | 小爱音箱 ID 或名称 | `"小爱音箱 Pro"` |
| `ttsCommand` | 小爱音箱 TTS 指令（[可在此查询](https://home.miot-spec.com)） | `[5, 1]` |
| `wakeUpCommand` | 小爱音箱唤醒指令（[可在此查询](https://home.miot-spec.com)） | `[5, 3]` |
| **speaker 其他参数（可选）** |
| `callAIKeywords` | 当消息以关键词开头时，会调用 AI 来响应用户消息 | `["请", "傻妞"]` |
| `wakeUpKeywords` | 当消息以关键词开头时，会进入 AI 唤醒状态 | `["召唤傻妞", "打开傻妞"]` |
| `exitKeywords` | 当消息以关键词开头时，会退出 AI 唤醒状态 | `["退出傻妞", "关闭傻妞"]` |
| `onEnterAI` | 进入 AI 模式的欢迎语 | `["你好，我是傻妞，很高兴认识你"]` |
| `onExitAI` | 退出 AI 模式的提示语 | `["傻妞已退出"]` |
| `onAIAsking` | AI 开始回答时的提示语 | `["让我先想想", "请稍等"]` |
| `onAIReplied` | AI 结束回答时的提示语 | `["我说完了", "还有其他问题吗"]` |
| `onAIError` | AI 回答异常时的提示语 | `["出错了，请稍后再试吧！"]` |
| `playingCommand` | 查询小爱音箱是否在播放中指令（[可在此查询](https://home.miot-spec.com)） | `[3, 1, 1]` |
| `streamResponse` | 是否启用流式响应（部分小爱音箱型号不支持查询播放状态，此时需要关闭流式响应） | `true` |
| `exitKeepAliveAfter` | 无响应一段时间后，多久自动退出唤醒模式（单位秒，默认 30 秒） | `30` |
## 环境变量
重命名本项目根目录下的 [.env.example](https://github.com/idootop/mi-gpt/blob/main/.env.example) 文件为 `.env`。
然后，将里面的环境变量修改成你自己的，参数含义如下：
| 环境变量名称 | 描述 | 示例 |
| ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
| **OpenAI** | | |
| `OPENAI_API_KEY` | OpenAI API 密钥 | `abc123` |
| `OPENAI_MODEL` | 使用的 OpenAI 模型 | `gpt-4o` |
| `OPENAI_BASE_URL` | 可选，OpenAI API BaseURL | `https://api.openai.com/v1` |
| `AZURE_OPENAI_API_KEY` | 可选，[Microsoft Azure OpenAI](https://www.npmjs.com/package/openai#microsoft-azure-openai) | `abc123` |
| **提示音效（可选）** | | |
| `AUDIO_SILENT` | 静音音频链接 | `"https://example.com/slient.wav"` |
| `AUDIO_BEEP` | 默认提示音链接 | `"https://example.com/beep.wav"` |
| `AUDIO_ACTIVE` | 唤醒提示音链接 | `"https://example.com/active.wav"` |
| `AUDIO_ERROR` | 出错提示音链接 | `"https://example.com/error.wav"` |
| **豆包 TTS（可选）** | | |
| `TTS_DOUBAO` | 豆包 TTS 接口 | `"https://example.com/tts.wav"` |
| `SPEAKERS_DOUBAO` | 豆包 TTS 音色列表接口 | `"https://example.com/tts-speakers"` |

53
TODO.md → docs/todo.md
View File

@ -1,61 +1,48 @@
# TODOs
# v3.1.0
下一版本的更新计划
## 🔥 Hotfix
- 修复提示语和提示音链接都为空时，不播放提示音。https://github.com/idootop/mi-gpt/issues/30#issuecomment-2153786207
- 提示语列表为空时，不播放提示语。
- 提示语和提示音链接都为空时，不播放提示音。https://github.com/idootop/mi-gpt/issues/30#issuecomment-2153786207
- 修复因没有配置环境变量，而导致没有初始化成功 OpenAI 使程序崩溃。 https://github.com/idootop/mi-gpt/issues/30#issuecomment-2153753279
- 修复唤醒模式下，重新匹配唤醒词时，应该走询问 AI 的流程。([issues#25](https://github.com/idootop/mi-gpt/issues/25))
- 修复使用提示音链接时，小爱回答完毕后，仍然重复播放文字提示语的问题。
## 📒 文档 FAQ
## 💪 优化
- 优化 unWakeUp 小爱的流程，增加指令间的执行间隔，降低 ROM 端无响应问题的出现的概率。https://github.com/idootop/mi-gpt/issues/32
- 优化 debug 日志输出，添加 wakeUp、unWakeUp、env 等关键流程和核心数据的打印。
## 📒 文档 FAQ
- 优化关于 Azure OpenAI 配置的说明。https://github.com/idootop/mi-gpt/issues/7
- 优化找不到小爱设备的提示文案以及 FAQ 教程。https://github.com/idootop/mi-gpt/issues/28#issuecomment-2153645819
- 添加关于唤醒小爱、唤醒词、唤醒模式的说明和注意事项。
- 添加关于 clone 项目本地运行的相关配置教程。
- ✅ 添加关于 clone 项目本地运行的相关配置教程。
- 添加关于本地构建本项目 docker 镜像的说明。
- 添加关于 playingCommand 的详细说明，默认不需要配置。
- 添加常见小爱音箱型号的支持情况和参数列表。
- 添加关于 clone 项目本地运行提示找不到 bot 的相关说明。
- 添加国内设备代理配置相关的说明。https://github.com/idootop/mi-gpt/issues/29
- 添加国内设备使用 Docker 镜像配置镜像代理的说明。https://github.com/idootop/mi-gpt/issues/31
- 添加关于 OpenAI 401 账号 API_KEY 错误， 403 触发 IP 访问风控的说明。https://github.com/idootop/mi-gpt/issues/19，https://github.com/idootop/mi-gpt/issues/33
- 添加关于 Node 项目下 MiGPT.create 参数配置的说明。 https://github.com/idootop/mi-gpt/issues/27
- 添加关于 Widnows 下 docker 启动参数配置的说明。https://github.com/idootop/mi-gpt/issues/26
- ✅ 添加关于 Node 项目下 MiGPT.create 参数配置的说明。 https://github.com/idootop/mi-gpt/issues/27
- 【待更新】添加关于 Widnows 下 docker 启动参数配置的说明。https://github.com/idootop/mi-gpt/issues/26
## ❤️ 感谢
- @shaoyi1991 补充的关于项目启动和国内配置 docker 镜像的说明。 https://github.com/idootop/mi-gpt/issues/28
- @shog86 协助调试 Azure OpenAI 相关的配置参数
- @shog86 协助调试 Azure OpenAI 相关的配置参数 https://github.com/idootop/mi-gpt/pull/34
- @siseboy 提供群晖 docker 使用教程 https://github.com/idootop/mi-gpt/issues/41
- @moffefei 提供的 Windows 下 docker 启动命令的示例 https://github.com/idootop/mi-gpt/issues/45
# Roadmap
# v4.0.0
> 以下是一些可以优化的地方或新功能，仅作记录之用，暂时没有开发计划。
## 🐛 修复
- 【重要】自动刷新小米账号登录凭证
- 小米账号登录凭证有效期 1 个月，到期后需要自动刷新（mi-service-lite）
## 💪 优化
- 自动识别设备型号
- 通过查询设备 miot spec 文件，自动获取指令参数
- 自动识别设备属性值是否有读取权限
- 添加镜像更新说明
- 添加 db 文件导入/出教程，用于备份恢复对话历史记录
版本更新计划
## ✨ 新功能
- 添加是否启用对话模式的开关
- 支持通过语音命令清除上下文
- 支持自定义对话系统 Prompt 模板
- MioT AI Agents
- 支持小爱音箱控制米家设备
- 通过 Agent 机制自动调用合适的工具（设备）
- RAG
- wikis embedding
- memory embedding
- 插件系统
- 自定义语音指令
- 支持火山引擎 TTS 和音色切换能力
- 添加更详细的使用和配置视频教程