跳转至

把安装交给 AI

命令不想自己敲，可以把这一摊交给 AI 执行：它查环境、装依赖、改配置，你只负责 回答问题、点确认。这一页既是交给它执行的规格，也是你最后验收时的对照表。

怎么用

把这一页的链接发给你正在用的 AI（Claude、ChatGPT、Cursor，或终端里的 agent）， 再附一句话：

按 https://docs.yuelibot.org/manual/ai-install/ 把我这台机器上的月璃装好。
那页写了硬约束和完成判据，照它做。
需要我本人操作或确认的地方停下来告诉我，别替我接受任何协议。

下面是规格正文。它按「先问什么、不许做什么、做到什么算完、按什么顺序、错了怎么判」 组织，你读一遍也就知道自己会被问哪些问题。

先问清楚，别猜

四件事必须从用户口中问到答案，猜错任何一件都会白装一遍：

系统与版本 —— Windows 还是 Linux，具体版本号。桌宠只在 Windows 10 / 11 上可用， 选错平台等于选错整条路线。

凭据 —— 模型厂商的 API Key（默认走阿里云百炼，形如 sk-xxxxxxxx）， 以及一个打算当机器人的 QQ 小号。必须是小号，不要用用户本人的主号。

装到哪个目录 —— 默认别放 C 盘，理由见下面的硬约束。

协议端用 NapCat 还是 SnowLuma 不用问：默认 NapCat，它支持的平台最多， 用户之后想换随时能改 config/adapter.toml 里的一行。

三条硬约束

用户协议由用户本人读、本人输入，不许代劳。 首次启动时终端会打印协议要点与正文位置，要求逐字输入「同意」。 把 AGREEMENT.md 的链接交给用户，让他自己决定。不要用 --accept-agreement 绕过这一步—— 那个参数只服务于确实无法交互的无头服务器，且必须由用户本人提出。

机器人号用小号，且与用户本人的号不同。 接入 QQ 可能导致账号被风控或限制。两个号填成同一个会被配置校验直接拒绝。

要桌宠，项目根就不能落在 C 盘。 桌面外壳启动时会拒绝把运行时文件写进系统盘，报错原文是 「拒绝把 YueLiBot 运行时文件写入 C 盘」。装到 D: 之类的位置，或用 YUELI_PROJECT_ROOT 显式指定一个非 C 盘目录。

做到什么算装完

别看「命令有没有报错」，看下面这几条是否真的成立：

  1. 后端终端出现「WebUI 已就绪」的信息框
  2. 浏览器能打开 http://127.0.0.1:7999，看得见面板
  3. 发一条消息后，面板的「会话观察」页里出现回复正文
  4. 接了 QQ 的话：用用户本人的 QQ 私聊机器人号，QQ 里真的收到回复

第 4 条单独列出来，是因为它和前三条不是一回事：面板上显示回复只证明模型出了结果， QQ 里收到气泡才证明出站动作被协议端接受。只做到第 3 条就宣布完成是错的。

按这个顺序做

安装 uv —— 先 uv --version 看有没有。没有就按系统装：

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

装完必须重开终端让 PATH 生效。不要另外装 Python：uv 会按 pyproject.toml 的声明自己准备 3.11 以上版本。

克隆仓库 —— git clone https://github.com/YueLi-and-Me/YueLiBot.git。 机器上没有 Git，就从 Releases 下源码包解压。 解压后目录里要能直接看到 pyproject.toml，多套一层会导致后面所有命令找不到项目。

安装依赖 —— 在项目根依次执行 uv sync、npm ci、npm run build。 前一条装后端，后两条装前端并构建管理面板与桌宠（产物在 out/）。 Node.js 要 22 以上；管理面板离不了构建产物，所以这两条不是可选项。

第一次启动 —— uv run bot.py。同意协议后它会生成五份带注释的 TOML 并主动退出，退出码是 1。这是设计如此，不要当成报错去修，也不要去改退出码出处。

填 Key —— 配置在项目目录下的 config/，改 providers.toml 里的 api_key 一行。 厂商地址与六个模型条目已按百炼预填，除非用户明确要换厂商，否则不要动模型 ID。

再启动 —— 再跑一次 uv run bot.py，直到出现「WebUI 已就绪」。 端口 7999 被占用时用 --port 换一个。

接 QQ —— 见 NapCat 接入 与 SnowLuma 接入。 协议端是独立程序，不要装进月璃的目录；月璃侧要改 config/adapter.toml 的 plugin 与插件目录下的 config.toml 两处。

出错时怎么判

现象 多半是 怎么办
找不到 uv 命令 装完没重开终端 关掉窗口重新打开
uv sync 长时间不动 访问 PyPI 或 GitHub 不畅 换网络环境重跑，已下载的部分会保留
第一次启动就退出 正常流程 去填 api_key 再启动，不要改代码
启动报 api_key 为空，或调用返回 401 / 403 Key 没填、填错，或没开通对应模型 回百炼控制台核对；不要靠换模型 ID「试试看」
外壳报「拒绝把运行时文件写入 C 盘」 项目在 C 盘 挪到其它盘，或设 YUELI_PROJECT_ROOT
面板空白、提示尚未构建 跳过了 npm run build 补跑一次，或从别的机器拷 out/webui
面板正常但 QQ 没反应 协议端未连上、白名单没写、或消息格式不是数组 按接入总览的三层逐项确认

不要用「加大超时」「加重连间隔」去治连不上的问题。 端口、令牌、账号错了， 等多久都连不上；那两个参数只影响网络抖动时的表现。

不要把 api_key、协议端访问令牌或面板 token 写进任何会提交的文件， 也不要贴进聊天窗口——那是能直接用的凭据。