快速开始

需要 Linux、Bun 1.3 以上、可用的 bubblewrap（run_js 沙箱，缺少则启动报错，见 docs/deploy.md）、至少一个 Discord bot 或 Telegram bot，以及一个模型 provider 的凭据。视频抽帧另需系统安装 ffmpeg（含 ffprobe）；没有也能运行，视频只剩 [视频] 占位。

macOS 开发机还需 brew install sqlite，供 Bun 加载 sqlite-vec 扩展。首次启动会下载约 96 MB 的默认中文 embedding 模型到 data/models（自定义 dataDir 时随之变化），需要网络；之后复用本地缓存。features.history 设为 false 时两者都不需要。消息检索的向量部分（相关条数、语义检索）总是使用这个模型；开启 events 时话题也共用它。

bash

git clone https://github.com/beiwater/jingmei.git
cd jingmei
bun install
bun run jingmei init

init 是推荐的配置方式：一个交互向导，生成 jingmei.config.json、.env 和 personas/<id>.md，不用手改 JSON。先选“推荐 / 最小 / 自定义”（推荐 = 核心功能全开、不加附加功能；最小 = 核心功能全关，不下载 embedding 模型；自定义 = 逐项选核心功能和附加功能，只对选中的附加功能追问参数），再依次选平台、填 bot token（输入不回显，并用与 bot 相同的调用实时验证、显示 bot 名字）、服务器 / 频道 ID（Telegram 为群 ID）、角色 id 和名字、模型（DeepSeek 填 DEEPSEEK_API_KEY，或之后用 bun run jingmei login）。ROUTING_SECRET 随机生成；secret 只写进权限 0600 的 .env，不进 JSON。已存在 jingmei.config.json 或 .env 时 init 拒绝运行，不覆盖任何文件；需要交互终端。结束时打印后续步骤（含 Discord 邀请链接）。

写完后：

编辑 personas/<id>.md，写下角色的身份、说话方式和边界。
bun run jingmei doctor：只读自检，检查配置、run_js 沙箱、模型凭据、bot token 与权限（Message Content Intent、privacy mode、群 ID）、按已启用功能检查 ffmpeg / 字体 / sqlite-vec / embedding 缓存，逐项给出 OK / WARN / FAIL 和修复提示。
启动：
bash
```
bun run start
```

想手动配置（或脚本化部署）也可以，向导做的事等价于下面的步骤：

bash

cp jingmei.config.example.json jingmei.config.json
cp .env.example .env
cp personas/template.zh.md personas/luna.md

编辑 personas/luna.md，写下角色的身份、说话方式和边界。
编辑 jingmei.config.json：填入 Discord 服务器 ID 和频道 ID。示例只有一个 Discord 角色；Telegram、语音、Jev 等见可选功能，字段见配置参考。
编辑 .env，填 bot token、ROUTING_SECRET（任意随机长字符串）和各项 API key。注意格式是 key: value，不是 KEY=value。
准备模型凭据，二选一：
- 示例角色使用 DeepSeek 的 deepseek-flash，只需在 .env 填 DEEPSEEK_API_KEY。启动时会在 data/pi-agent/models.json 写入这个模型的目录条目（不含密钥）。
- 其他 provider：订阅账号（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 等）用 bun run jingmei login 选 provider 走 OAuth 登录，凭据写进 <dataDir>/pi-agent/auth.json，bot 启动后直接使用并自动刷新 token；bun run jingmei logout 删除。服务器上没有浏览器时，在本机浏览器打开打印出的链接，再把最终跳转 URL 或授权码粘贴回终端。bun run jingmei model 列出所有已有凭据的模型。也可以把该 provider 的 API key 环境变量（如 OPENAI_API_KEY）放进进程环境。.env 只由本项目读取，除 DEEPSEEK_API_KEY 外不会转交给 Pi。
运行 bun run jingmei doctor 自检，再 bun run start 启动。

启动时会校验配置、验证每个 bot token、确认每个角色的模型存在且已认证。配置错误会一次列全；token 或模型不可用也会报错退出。之后去群里 @ 角色或回复它试试。

在终端前台启动时，准备期间会播放 fox-girl-loader 加载动画，就绪后显示 ✓ Ready，期间的启动日志在动画结束后补显示；systemd 等非终端环境不绘制动画，日志照常输出。

快速开始 ​

快速开始