中文（默认） · English

Yuki 可以在 QQ 私聊和群聊中交流，记住人与共同经历，读取图片、语音和文件，并通过工具搜索资料、发送消息、执行代码和处理后台任务。人格、记忆和关系保存在自己的数据库中，切换 QQ 账号或网关时可以继续沿用。

当前正式版为 3.8.3。 当前代码包含持久工作环境、语音识别、统一主 Agent、子任务与持续恢复，以及工具合同清理。工作环境需要单独部署；WebUI 尚未提供。

Yuki 能做什么

这些能力取决于部署配置、模型能力和授权范围。任务被接纳、执行完成和消息发送分别有状态记录；调用工具不等于结果已经交付。

持久工作环境

启用后，Yuki 拥有全会话共用的 Linux 工作目录，可以保存下载文件、Git 项目、脚本与依赖。文件工具和终端操作同一份文件，普通工作文件不再按 24 小时过期。

• 预装 Bash、Python、Node.js、Git 和基础编译工具，支持 pip、npm，以及由 Manager 管理的 apt 安装和环境检查点。
• 终端支持交互输入、增量输出、取消和后台执行。可以先启动一个任务，继续处理消息，再回来看结果。
• Bot 或 Manager 重启时，环境进程可以继续运行；环境本身重启后，普通任务标记中断，已登记服务按策略恢复。
• 选定文件发布为不可变快照后，通过 QQ 发送链路交付；旧 artifact_id 保持兼容。

默认家目录容量 2 GiB，容器内存上限 512 MiB，最多一个主要执行任务、四个终端会话和两个内部服务。环境没有浏览器或桌面，也不挂载 Bot 数据库、QQ 凭据或宿主 Docker 控制接口。

这是一项单独部署的可选能力，需要 Linux 宿主、gVisor 和 Yuki Manager；普通 Bot 部署包不会自动安装。配置、资源限制与恢复方式见持久环境说明（English）。

记忆与跨会话连续性

长期记忆用于保存稳定事实、偏好和有意义的经历；普通自动提取会聚合消息，明确要求记住、纠正和删除时则即时处理。长会话通过 Rollup 压缩历史，原始历史仍有独立查询入口。

short_state 是全局共用、有界且会过期的短期记录区，用于暂存跨会话信息；它与长期记忆、持久文件分开。群聊和私聊不会自动拼成同一份完整聊天历史。

记忆读取仍有具体边界：历史共同群关系可以开放人物结构化事实，其中可能包含私聊来源的事实，但不开放他人的原始私聊或私有证据。部署前请阅读 Memory 的范围与权限。模型提取和回忆可能出错，重要信息应核对来源。

图片、语音、文件与联网

• 图片与视频：支持图片输入的模型可直接查看当前或引用图片。MP4/MOV 视频通过 FFmpeg 抽帧进入同一个主 Agent，不分析音轨，也不保证覆盖所有瞬间。
• 接收语音：私聊、符合回复策略的群聊及引用语音经 Qwen ASR 转写，进入聊天历史、搜索和 Rollup。可复用千问连接，与 Genie-TTS 语音发送独立配置。见语音识别说明。
• 文件阅读：支持文本、代码、CSV/JSON、PDF 文字、DOCX 和 XLSX 的有界提取。扫描 PDF 不做 OCR，表格公式不重算，宏和附件中的代码不会因阅读而执行。后续重新查看时可引用原附件。
• 联网：可配置 Provider 原生搜索或外部 web_search。外部搜索默认使用 Tavily，也可设置 WEB_MODE=tavily、WEB_SEARCH_BACKEND=deepseek_anthropic 使用 DeepSeek 搜索桥；此时 Tavily 密钥仅用于可选失败兜底。both 允许已配置的外部搜索和 Provider 支持的原生搜索，disabled 禁止联网。DeepSeek 主 Agent 的原生搜索能力当前由适配层关闭，搜索桥使用独立协议请求。

聊天、插件唤醒、自动化和任务续跑使用统一主 Agent 与完整工具声明。工具结构在部署内保持固定，执行时再检查权限与预算；这减少请求前缀变化，但不保证 Provider 的缓存命中率。

配置与启动

基础部署需要：

• Linux amd64，或运行 Linux 容器的 Windows Docker Desktop；
• Docker Engine 和 Docker Compose v2；
• 可用的模型服务配置，支持项目接入的 Chat Completions 或 Responses 协议；
• 至少一个 NapCat 或 SnowLuma QQ 网关及登录账号。

从 3.8.3 Release 下载部署包，解压后可以手动填写 .env 和模型配置，也可以使用配置向导。

Linux：

curl -fLO https://github.com/YuanYeYouTao/Yuki-QQbot/releases/download/v3.8.3/install.sh
chmod +x install.sh
./install.sh

Windows PowerShell：

Invoke-WebRequest -Uri https://github.com/YuanYeYouTao/Yuki-QQbot/releases/download/v3.8.3/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

向导只负责配置。 在空目录中下载并校验部署包，在已有部署中保留 Compose、插件和数据；确认后备份并写入配置。它不会停服、迁移数据库、启动服务或切换网关。

首次部署在配置完成后，进入部署目录执行：

docker compose config --quiet
docker compose pull
docker compose run --rm --no-deps --entrypoint qq-ai-bot-cli bot init-db
docker compose up -d

还需完成 QQ 登录，并按所选插件和语音组件的说明进行初始化。完整步骤见首次启动与升级指南。已有部署请直接按该指南升级，保留原项目名、Compose 覆盖文件和挂载配置。

正式镜像为 ghcr.io/yuanyeyoutao/yuki-qqbot:3.8.3；可选 TTS Worker 镜像为 ghcr.io/yuanyeyoutao/yuki-genie-tts-worker:3.8.3。发布包提供 SHA256SUMS。单独下载的环境模板附件名为 default.env.example，压缩包内仍为 .env.example。

升级与日常维护

当前源码使用 Plugin API 3.0，数据库目标由随包 Alembic 单一 head 决定；应用版本号不能替代数据库版本检查。3.8.2 发布包的历史目标为 0055。较旧的数据库必须先满足迁移前提，不能通过 stamp 跳过迁移。旧插件的 llm.generate / agent.run 已统一到主入口，依赖旧独立生成语义的插件需要适配。

升级前保存一致的数据库、配置、插件及文件备份；持久环境还需保存家目录与运行回执。暂停写入只涉及 Bot 和相关 Manager，不需要关闭整个 Docker 或 QQ 网关。回退时应先保全升级后的新消息、文件和回执，详见升级指南。

docker compose ps
docker compose logs --tail 200 bot
docker compose exec bot qq-ai-bot-cli gateway doctor --provider snowluma

使用 NapCat 时将最后一个参数改为 napcat；所有命令沿用部署时的 Compose 参数。同一 QQ 只允许一条活动连接，切换网关前需先停止旧连接。见 SnowLuma 部署与切换。

架构与开发

开发前阅读 共同架构约束 与
架构文档索引。历史任务书不替代现行合同。

一个数据库对应一个长期存在的 Yuki。人物、群空间、QQ 账号和网关连接分别建模，聊天历史与关系不绑定在某一次登录连接上。工具由后端执行权限、预算、幂等和审计检查。

目前提供 QQ 交互、CLI 和供管理界面复用的 Control Plane 业务层，尚未提供 Yuki 管理 WebUI 或管理 HTTP API。

uv sync --extra dev
uv run ruff format --check
uv run ruff check
uv run mypy src
uv run pytest

开发时按改动范围选择定向验证；发布流程还会验证迁移、镜像和无源码部署。

License

MIT