Lingchu Bot 入门

在本教程中，你将从零开始安装 Lingchu Bot，并通过本地运行验证安装是否成功。完成后，你将拥有一个可用的开发环境，随时可以连接平台适配器。

你将学到什么

• 如何克隆并安装 Lingchu Bot 的全部依赖。
• 如何准备 .env 配置文件。
• 如何启动机器人并确认看到 Application startup complete.。

本教程不会连接真实的 QQ 或 Telegram 账号——那是下一篇接入你的第一个适配器的内容。

前置条件

• Python 3.13
• uv — Python 包和项目管理器
• git
• Node.js 22+ 和 pnpm（仅当你也想构建文档站时需要）

获取代码

克隆仓库并进入项目目录：

git clone https://github.com/xinvxueyuan/lingchu-bot.git
cd lingchu-bot

安装依赖

项目提供了跨平台安装脚本，自动完成整个初始化流程：

chmod +x scripts/setup.sh
./scripts/setup.sh

脚本会检测操作系统、校验所需工具链（Python 3.13+、Node.js 20+、pnpm 9+、Git、uv）、安装所有依赖、生成环境配置文件（.env、.env.development、.env.test、.env.production），并配置 Git 钩子。使用 ./scripts/setup.sh --help 查看所有选项。

手动安装替代方案

如果偏好手动安装：

uv sync --frozen
pnpm install
pnpm exec husky
cp .env.example .env

配置环境变量

打开 .env 并设置必填字段。至少需要 LINGCHU_SUPERUSERS（一个将 Lingchu UID 映射到平台账号 ID 的 JSON 对象）：

LINGCHU_SUPERUSERS='{"admin":{"qq":123456789}}'
LINGCHU_LOCALE=zh_CN

完整映射格式参见配置超级用户身份。适配器连接字段暂时留空——你将在下一个教程中配置它们。

启动机器人

通过 NoneBot CLI 运行：

uvx --from nb-cli nb.exe run

等待日志显示：

INFO 06:31:21 | Application startup complete.

看到这一行，说明核心运行时已就绪。

布尔值

NoneBot 配置文件只接受标准 JSON 小写 true / false。写 True / False 会在启动时引发配置错误。

你学到了什么

• Lingchu Bot 通过 uv 和 scripts/setup.sh 安装。
• 配置存放在 .env 中，由 NoneBot 管理。
• 启动成功的标志是日志中出现 Application startup complete.。

下一步

接入你的第一个适配器

连接 NapCat 或 Telegram，发送你的第一条群管理命令。

命令

浏览完整命令参考。

故障排查

解决常见启动和连接问题。