Yuki 3.5.3

Yuki 3.5.3 发布与升级说明

Yuki 3.5.3 为版本化 Docker 部署增加 Guided Setup。它不改变 Agent、Memory 或 Plugin API，
不新增数据库迁移；Alembic head 保持 0036，Genie-TTS Worker 内部版本保持 1.9.0。

首次安装

仅需 Docker Engine / Docker Desktop 与 Docker Compose v2。正式支持 linux/amd64。

1. 从 GitHub Release 下载 install.sh（Linux）或 install.ps1（Windows）。
2. Linux 执行 chmod +x install.sh && ./install.sh；Windows PowerShell 执行
   powershell -ExecutionPolicy Bypass -File .\install.ps1。
3. 安装器下载精确的 3.5.3 部署包并用 SHA256SUMS 校验，然后拉取 Bot 镜像。
4. 按向导填写管理员 QQ、主模型配置，并选择需要的扩展能力。
5. 安装器完成 Compose 启动和健康检查后，打开 http://127.0.0.1:6099 登录 NapCat。

默认安装目录是当前目录下的 yuki/。Linux 可传 --dir PATH，PowerShell 可传
-InstallDir PATH。机器人 QQ 号由 NapCat 实际登录账号决定。

向导行为

• 初次安装时 Flash、Embedding、Web、Vision、MCP、Plugin、Automation、Speech 全部默认关闭。
• API Key 和 MCP 敏感 Header 不回显，不进入摘要或日志；OneBot 与 NapCat Token 自动生成。
• OpenAI-compatible Chat Completions 主模型必须支持 Function Calling。
• DeepSeek Responses 可选择模型原生搜索；请求不会发送任何 tool_choice 字段。
• MCP 引导只支持 Streamable HTTP。stdio Server 需要自行维护包含进程依赖的定制镜像。
• 插件只读取 Manifest 并逐项请求批准，不会为了展示选项而导入插件代码。
• Speech 不会下载模型；只有检测到非空 GenieData 与合法声线档案时才能开启。
• 验证只检查 Settings、协议、Schema 和本地文件，不会调用模型、Tavily 或其他计费 API。
• 任意提示处输入 :back 返回上一逻辑页并丢弃当前页半成品；:quit、Ctrl+C 或输入流关闭
  会在确认写入前安全退出。两个命令必须输入开头的英文冒号。重跑时从第一个所选页面返回会
  回到编号式区块选择页。
• 重跑的区块选择默认是“一个也不改”，插件页默认保持每个插件当前状态；Manifest 或权限变化
  后旧批准不会自动沿用。
• 损坏的 .mcp.json 不再锁死向导：可以重新创建、重置并关闭，或关闭 MCP 后原样保留文件。

若终端不支持颜色，或设置了 NO_COLOR、TERM=dumb、CI，向导自动使用纯文本。也可直接
执行 qq-ai-bot-cli setup --no-color。

从 3.5.2 升级

升级前备份部署目录，尤其是 data/ 与 .env。

1. 在已有部署根目录运行 3.5.3 安装器。它会重新下载并校验精确版本部署包，只更新
   docker-compose.yml、.env.example、两个安装器和升级说明，并先备份这些 Release 管理文件。
   .env、config/、plugins/、data/ 与 napcat-* 不会被覆盖。
2. 安装器识别现有部署并直接重开向导，不创建嵌套目录。
3. 选择要修改的区块。未选择区块保持不变；明确关闭功能会保留旧密钥，只关闭开关。
4. 确认脱敏摘要。受影响配置写入前会备份到 .yuki/backups/<timestamp>/，保留最近 5 份。
5. 安装器更新 YUKI_VERSION=3.5.3，执行 Compose 拉取、重建和健康检查。

也可以完成向导后手动更新：

docker compose pull
docker compose up -d
docker compose ps

手动运行 Setup CLI

部署包内没有 Python 环境；应通过正式 Bot 镜像运行向导。安装器已经封装了该步骤。容器内可用
的维护入口为：

qq-ai-bot-cli setup
qq-ai-bot-cli setup validate
qq-ai-bot-cli setup apply-pending
qq-ai-bot-cli setup verify

apply-pending 仅应在 Bot 完成 0036 数据库迁移后运行。安装器会按此顺序执行，并且只在插件
状态实际变化时重启 Bot 一次。

数据与安全边界

• Setup 容器不挂载 Docker Socket，也不能自行编排宿主容器。
• 生产 Compose 仍完全使用版本化 GHCR 镜像，不包含 build:。
• .env 在 POSIX 使用 0600；Windows 安装器把配置与备份 ACL 限制为当前用户。
• 重跑不会删除数据库、QQ 登录数据、插件文件、语音模型或其他持久化目录。
• NapCat Token 只提示位于 .env，不会显示在最终状态摘要中。

Yuki 3.5.2

Yuki 3.5.2 发布与升级说明

Yuki 3.5.2 将正式部署入口改为版本化 Docker 镜像。本版本不改变 Agent、Memory、Plugin API
或数据库结构；Alembic head 仍为 0036，Plugin API 仍为 1.1。

新安装

1. 从 GitHub Release 下载 yuki-3.5.2-deploy.zip 或 yuki-3.5.2-deploy.tar.gz 并解压。
2. 进入解压目录，复制环境模板：cp .env.example .env。
3. 在 .env 中填写 OneBot、管理员和模型配置；保留 YUKI_VERSION=3.5.2。
4. 执行 docker compose up -d。
5. 打开 http://127.0.0.1:6099 完成 NapCat 登录，并检查 docker compose ps。

部署包不包含源码、数据库、密钥或本机配置。Bot 启动时会自动把空数据库迁移到 Alembic
0036。

从旧版本升级

不要把新部署包直接解压覆盖现有目录。升级前：

1. 备份整个 data/，并保留现有 config/、plugins/、napcat-data/、napcat-config/ 和
   napcat-plugins/。

2. 从 Release 单独下载新的 docker-compose.yml 和 .env.example，人工合并必要环境变量。

3. 把现有 .env 的 YUKI_VERSION 改为 3.5.2。

4. 执行：

   docker compose pull
   docker compose up -d
   docker compose ps

5. 检查 docker compose logs --tail 200 bot，并确认 /healthz 返回 status=ok、
   version=3.5.2 和 database=ok。

docker compose pull 只拉取 Compose 当前指定的镜像。正式部署应使用不可变版本号；latest
仅供快速体验，不是生产默认值。不要执行 docker compose down -v。

可选语音 Worker

GenieData 和声线仍由用户放在持久化语音目录中，不会打入镜像。准备完成后执行：

docker compose --profile speech up -d

Yuki 镜像标签为 3.5.2，但 Genie-TTS Worker 的内部组件版本继续保持 1.9.0。

本地源码开发

开发环境才使用构建覆盖：

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

生产 docker-compose.yml 不包含任何 build:。

Yuki-QQbot 3.5.1

Yuki-QQbot 3.5.1 发布说明

3.5.1 将长期记忆从“检索后直接注入”扩展为可观测、可衰减、可强化的自适应生命周期，同时
把自动召回、显式读取和写入变更拆成互斥路径。普通回复不再为记忆使用归因等待额外模型请求，
记忆修改也只能依据真实工具回执对外确认。

结构化意图与有界召回

• Planner 在既有一次调用中输出记忆访问方式、召回模式、目的、可信主体提示、实体、绝对时间
  范围、偏好类型和请求数量，不增加第二次 Planner 或 rerank 模型。
• 后端先解析真实发送者、当前群、回复、提及和 SELF 可见性；Planner 提示只参与软加分，不能
  产生新身份目标或扩大合法检索范围。
• 召回顺序为 FTS / Semantic → RRF → Intent/Activation → MMR → Context Budget，精确命中
  和显式偏好继续保留，低 Activation 的高相关旧记忆仍可召回。
• 自动召回按 background、continuation、recall/verify/correct、overview 分别限制为 3、4、6、8
  条，每目标最多 4 条；显式工具读取和 Plugin/管理搜索不使用该自动注入限额。

Activation、归因与强化

• Episode、Fact、Preference 和 Explicit 默认半衰期分别为 14、60、120、365 天；读取时计算
  指数衰减，不后台改写真实性状态，也不以 Activation 作为硬过滤条件。
• Recall Receipt 记录 candidate、selected、injected、used、reinforced 阶段和数值分数，不保存
  用户问题、回复正文或记忆正文，并由维护任务按 30 天保留期清理。
• 主 Agent 不再暴露 report_memory_usage。正文或对应语音发送成功后，进程内 Worker 使用 Flash
  对本轮 Exposure 做白名单归因，再异步标记 used 并通过 revision CAS 强化。
• 新前台模型请求可抢占尚在推理的后台归因；队列满、超时、非法输出或重启只跳过本轮强化，
  不阻塞聊天，也不改变事实有效性。

读取与写入互斥

• Memory Access 分为 none / automatic / tool / mutation。自动召回首轮不暴露 Memory Scope，
  显式读取不自动注入，写入轮次只开放经过权限、来源和风险检查的 memory/write_state 能力。
• 创建、纠正、撤回和恢复由独立 mutation 完成门收束；未调用写工具、noop、contest、歧义或
  未找到时，模型正文不能覆盖真实结果，撤回只称为失效并保留审计记录。
• Locator 支持稳定 key、旧正文、分类和 fact ID。用户可见标签误填为内部 key 时，只返回最多
  三条合法候选供 fact ID 重试，不能跨人物、跨群、绕过 SELF 或执行模糊变更。
• DeepSeek 不支持 tool_choice，因此 Chat Completions 和 Responses 请求体始终省略该字段；
  正确性由能力隔离、事务回执和后端完成门保证。

数据库与兼容性

• Alembic 0035 将 last_used_at 原值迁移为 last_injected_at，新增 Activation State 和 Recall
  Receipt；0036 仅迁移后台归因配置键，不持久化归因任务或聊天正文。
• Plugin API 保持 1.1；Plugin Memory Facade、管理搜索、Dream、Evidence、Conflict、Mutation
  和基于 last_confirmed_at 的真实性生命周期保持既有语义。
• 升级前建议备份当前镜像和 data/qq_ai_bot.db，再执行 alembic upgrade head。

验证

• ruff format --check .、ruff check .、mypy src 通过。
• 全量测试 1111 passed、1 skipped；跳过项为需要显式外部凭据的 Qwen Embedding 在线测试。
• Memory Quality 18/18 cases、38/38 gates 通过，跨人和跨群污染门保持为 0。
• 生产环境完成 SQLite 备份与完整性检查、0036 迁移、Bot 健康和 OneBot 连接核验；真实测试覆盖
  创建、自动读取、显式工具读取、纠正、撤回及不存在目标，数据库状态与 mutation receipt 一致。

Yuki-QQbot 3.5.0

Yuki-QQbot 3.5.0 正式版发布说明

3.5.0 引入独立的 Memory Dream 层和 MMR 召回去重，让 Yuki 能在保留原始来源与回滚能力的前提下，整理已经形成的长期记忆。长 Episode 不再只能整段保留或粗暴拼接：Dream 可以按语义重新切分、压缩并形成可独立召回的经历。

Memory Dream

• 新增每日 05:00 Asia/Shanghai 运行的 Memory Dream，位于 Self Reflection 之后，专门治理既有长期记忆。
• 支持 keep、merge、synthesize、recompose、contest 和 resolve，Fact、Preference、Episode 的结果仍是同级正式记忆。
• 长 Episode 使用 focus + source_refs + content 进行语义重组；同一个来源可支持多个边界清楚的输出，每个输出只表达一个中心事件或长期主题。
• 新产物可继续参与未来 Dream，但内容、状态、Evidence 和版本签名未变化时会跳过，避免每天反复改写。
• 显式记忆保持不可变锚点，Dream 不会吞并、改写或推翻用户明确写入的记忆。

Evidence 与完整来源链

• memory_evidence 只保留直接支撑当前正文的有限证据，Confidence 不再因整段聊天消息数量虚高。
• Self Reflection 为每条 Episode 选择 1～8 条直接证据；Dream 每个来源最多继承 2 条代表证据，每个输出最多 12 条。
• 完整聊天窗口、Dream 来源 Fact、关系、Operation 和 Receipt 继续通过 provenance 保留，可分页追溯而不进入普通 Prompt。
• 新增可恢复的后台 Evidence Compaction；真实库完成 65 个 Fact 的压缩，直接证据由 2862 条降至 520 条，0 失败。

Preview、审计与回滚

• Dream Preview 现在持久化不可变 proposal；正式执行直接应用有效 Preview，不重复调用模型，正文与预览逐字一致。
• 来源签名变化时 Preview 自动标记为 stale，禁止覆盖新数据。
• 支持整轮和单 Operation 回滚；来源已有人工修改或后续依赖时拒绝危险覆盖。
• 新增 Dream run、cluster、operation、source snapshot、result、checkpoint 和健康统计，不伪造 chat_event。

MMR 召回去重

• 普通相关记忆注入采用 FTS + Semantic → RRF → MMR → Top-K。
• 显式偏好和精确词法命中优先保留，其余结果使用已有本地向量做多样化。
• MMR 不跨主体或可见性范围比较，不增加模型或 Embedding API 调用；缺少向量时自动维持原 RRF 结果。

长 Episode 真实验证

• 第一轮真实 Dream：30/30 个候选簇完成，0 失败。
• 长 Episode 专项抽样：8/9 个簇完成，将 22 条来源 Episode 重组为 17 条正式 Episode。
• 成功簇正文由 7787 字压缩至 3205 字，整体保留率 41.2%；来源与每条输出均有精确关系映射。
• 唯一 Schema 失败簇没有写入 Operation、没有生成新 Fact，也没有改变来源，可安全重试。

升级与验证

• Yuki 版本为 3.5.0，Plugin API 保持 1.1。
• Alembic head 升级到 0034；迁移只创建结构，历史 Evidence 由后台维护任务分批处理。
• 本地全量测试：1057 passed，1 项真实外部 Embedding 测试按配置跳过。
• GitHub Actions 的 Python、Memory Quality、Docker 和 Speech Worker 全部通过。
• 服务器真实库迁移与完整性检查通过，Bot 健康；NapCat、QQ 登录状态、Miniflux/MCP 和公网 8078 未受影响。

升级前建议备份 data/。只重建 Bot 可保留 NapCat 登录状态：

docker compose up -d --no-deps --force-recreate bot

Yuki-QQbot 3.4.6

Yuki-QQbot 3.4.6 正式版发布说明

3.4.6 聚焦复杂工具链、Memory V2 语义自由度和长 Episode 的持续生产能力。本版本让模型承担语义判断，让后端专注可信身份、证据、权限、范围、幂等与事务边界，并减少大型 MCP 结果和积压自省造成的重复调用。

MCP 大型结果与 Agent 工具链

• 增加通用结构化 Artifact 导航，保留 MCP JSON 的对象、数组和游标语义，不再依赖特定服务的硬编码摘要。
• read_tool_artifact 支持稳定分页、路径读取、搜索和幂等结果，复杂点单链路可在不创建订单的前提下连续浏览门店、菜单、套餐和规格。
• Agent 工具循环增加执行前去重、最终回复预算、成功副作用短路和可继续工具链判断，降低重复翻页与无效调用。
• 修复 Responses 与 OpenAI 兼容链路中结构化工具结果的传递边界。

Memory V2 模型语义

• 移除依据中文词形、关键词或 Bot 固定名字判断主体、意图和长期价值的语义正则。
• 自动记忆继续由模型输出主体依据、保留价值、来源风格和来源类型；后端只验证可信引用与结构边界。
• memory_change 支持明确的用户请求依据；普通姓名使用当前群身份进行唯一解析，模糊候选可交还主 Agent 选择或澄清。
• 保留伪造证据、跨群目标、越权操作、SELF protected key、版本链、receipt 和事务校验。

长 Episode 与统一时区

• Structured Self Reflection 对格式错误提供具体诊断和一次有界修复，Episode 不再因模型放错输出字段而静默丢失。
• 数据库存储、排序和比较统一保持 UTC；传给模型、工具及用户的时间统一转换到配置时区。
• Self Reflection 事件时间带明确时区偏移，Episode valid_from 使用明确 UTC，修复日期提前或滞后 8 小时的问题。
• 新系统提示词仍作为私有运行配置挂载，不进入公开源码与镜像层。

Self Reflection 积压调度

• 每批最多读取 100 条事件、8000 字符，继续采用连续且不重叠的水位窗口。
• 每轮最多 12 个批次，同一会话每轮最多连续处理 7 个批次，每日最多 36 次模型调用。
• 同一会话完成一批后可在同一调度轮继续推进；失败会话不会在本轮立即重试烧费模型。
• 调度仍为 04:00、12:00、20:00（Asia/Shanghai），并兼容旧的 MAX_SESSIONS_PER_RUN 环境变量。

升级与验证

• Yuki 版本为 3.4.6，Plugin API 保持 1.1。
• 本地与 GitHub Actions 均通过 Ruff format、Ruff lint、Mypy、Pytest、Prompt benchmark、模型路由、插件契约、Alembic fresh install、Memory migration matrix、Docker 和 Memory Quality。
• 本地测试结果：1040 passed，1 项真实外部 Embedding 测试按配置跳过。
• 服务器已从本地构建的合并提交镜像部署；Bot 健康，OneBot 已连接，NapCat 容器与 QQ 登录状态保留，网易云、Miniflux 和麦当劳 MCP 正常握手。

升级前建议备份 data/。只重建 Bot 可保留 NapCat 登录状态：

docker compose up -d --no-deps --force-recreate bot

Yuki-QQbot 3.4.5

Yuki-QQbot 3.4.5 正式版发布说明

3.4.5 正式版完善了 Memory V2 写入质量、Yuki 自主反思、Planner 首轮工具路由和主 Agent
短期历史身份。它以更可靠的证据归属减少错误记忆，同时保留 Yuki 通过统一变更服务自主修正
动态自我记忆的能力。

Memory V2 写入质量

• MemoryClaim 增加主体依据、保留价值和来源风格三个有限枚举。
• 主体归属与长期价值判断拆为确定性策略；第二人称、Yuki 主语、mention 接收者和普通姓名不再
  无条件回退给消息发送者。
• 不确定事实进入 7 天隔离候选区，不参与 Prompt、向量检索或正式事实查询。
• 非 SELF 候选至少需要两条独立可信证据才可晋升；SELF 候选只由 Self Reflection 决定。
• 正式写入仍统一经过 MemoryMutationService、版本链、状态事件和 mutation receipt。

Yuki Self Reflection

• 默认每日 04:00、12:00、20:00（Asia/Shanghai）运行，每日最多 9 次模型调用。
• 输入只使用真实聊天事件、确认投递的 Yuki 回复、可信工具回执和当前可见 SELF 事实。
• 支持 create / correct / merge / contest / invalidate / noop，并保护
  identity:* / core:* / safety:* / system:* / permission:* / runtime:*。
• 群经历默认仅群可见，私聊经历默认仅私聊可见；只有去除人物隐私后的抽象原则或偏好才可全局化。

Planner 与工具成本

• 明确工具任务由 Planner 选择最小 scope，并输出规范化的“动作 + 对象” intent。
• Core 工具增加中文同义搜索标签，记录首轮工具命中、request_tools 使用和零结果指标。
• inherited 首批仍只提供最多 6 个相关工具；request_tools 是漏召回兜底，不是常规路由。
• 主 Agent 默认使用 12000 字符历史、8 次工具调用、6 次模型请求和 8000 字符工具结果上限。

主 Agent 历史信封

• 历史消息以稳定的 EventRecord.id 暴露本地事件引用，不再使用随窗口变化的临时消息编号。
• 人物身份直接使用事件发生时的群名片和原始 QQ；连续同一身份发言共享一个紧凑信封。
• reply 与 mention 关系仍保留为事件行元数据，Planner、自省和审计的输入格式不受影响。
• 输出清理器会剥离模型误复述的身份信封、事件号和关系元数据，不影响普通句子中的编号示例。

兼容性与升级

• Yuki 版本提升至 3.4.5，Plugin API 保持 1.1。
• Alembic head 提升至 0030；迁移保留已有事实，旧事实默认标记为 legacy_unreviewed 并继续检索。
• 本版本为 GitHub 正式 Release。升级前建议备份 data/，升级后可重点观察自动记忆归属、自省提案、
  Planner 首轮工具命中率、模型请求次数和群聊人物归属表现。
• 只重建 Bot 可保留 NapCat 容器和 QQ 登录状态：

docker compose up -d --build --no-deps bot

发布验证

• 970 项测试通过，1 项真实外部 Embedding 测试按配置跳过；Ruff、Mypy、迁移与 Docker 构建通过。
• 服务器部署验证包括 SQLite 完整性、Bot 健康、OneBot 重连、NapCat 登录状态保持、网易云 MCP
  继续运行和三轮自省调度启动。

Yuki-QQbot 3.4.4

Yuki-QQbot 3.4.4 发布说明

3.4.4 稳定了主 Agent 的 Prompt、历史窗口与工具定义，减少输入顺序或滚动边界变化导致的
缓存失效，并补齐缩短发送者身份头的输出清理。

Prompt 与历史缓存

• 历史消息位于动态运行时上下文之前，当前触发消息作为独立末尾输入。
• 历史窗口使用高低水位分块滚动；未达到上限时保持相同起点，达到上限后一次滚动到低水位。
• HISTORY_WINDOW_LOW_WATERMARK_RATIO 默认设为 0.67。
• Prompt 指标分别记录历史和当前消息字符数，并标记本轮是否发生窗口滚动。

工具与模型成本

• Core 与 MCP 首批工具采用宽松数量和 Schema Token 预算，未进入首批的工具仍可通过
  request_tools 按需加载。
• 工具定义、Flash 候选目录与筛选结果按规范工具名稳定排序，避免同一集合仅顺序不同便使
  Prompt 缓存失效。
• 默认推理深度由 max 调整为 high；需要更深推理时仍可显式选择 max。

输出可靠性

• 输出清理器现在能够剥离省略消息 ID、时间或两者的发送者身份头。
• 身份头与正文位于同一行时只移除内部元数据，保留用户可见正文。

兼容性与升级

• Yuki 版本提升至 3.4.4，Plugin API 保持 1.1。
• 本版本不新增数据库迁移，Alembic head 仍为 0029。
• 升级前建议备份 data/。只重建 Bot 可保留 NapCat 容器与 QQ 登录状态：

docker compose up -d --build --no-deps bot

发布验证

• Prompt、历史窗口、工具排序和输出清理均有单元测试覆盖。
• 本版本不包含语音识别功能。

Yuki-QQbot 3.4.3

Yuki-QQbot 3.4.3 发布说明

3.4.3 重构了短期群聊上下文的身份来源，并修复 Planner 将当前消息重复注入模型输入的问题。
历史发言现在直接使用消息到达时写入 chat_events 的昵称和群名片，不再依赖后续批量人物查询。

会话身份

• chat_events 新增发送者昵称与群名片快照，保留发言发生时的身份事实。
• Agent 历史中的每条消息都明确携带发送者显示名、QQ、消息 ID，以及存在时的回复目标。
• 删除旧的 related_people 上下文和配置依赖；被提及、被回复人物的记忆检索继续使用独立的
  memory.max_referenced_targets 上限。
• 历史搜索工具同步返回事件快照中的昵称、群名片与显示名。

Prompt 与 Planner 修复

• 移除身份头中的逐条时间，减少近场历史的 Token 消耗；整体当前时间仍由运行时上下文提供。
• 输出清理器剥离模型复述的新旧内部身份头，并在历史装配时清理已经落库的旧污染文本。
• Planner 的 messages 现在只包含历史消息；当前触发消息仅出现在 current_message，不再因
  同一正文出现两次而误认为用户重复发送。
• Planner 的待处理数量、回复必要性和会话节奏仍基于完整事件窗口计算，不受去重影响。

实现与兼容性

• Yuki 版本提升至 3.4.3，Plugin API 保持 1.1。
• Alembic head 提升至 0029；迁移只为已有 chat_events 增加可空字符串身份快照列，不删除或
  重写已有聊天、记忆、关系、自动化及插件数据。
• 旧事件没有历史昵称或群名片时继续回退到 Yuki 或 QQ 号显示，不会进行批量补查。
• README 以端到端 Mermaid 流程图展示 OneBot、Planner、Memory、工具、自动化、插件、联网、
  多模态、输出及后台持久循环之间的真实边界。

升级

升级前建议备份 data/。只重建 Bot 可保留 NapCat 容器与 QQ 登录状态：

docker compose up -d --build --no-deps bot

Bot 启动时会自动把数据库从 0028 升级到 0029。

发布验证

• 全量测试、Ruff 与 Mypy 通过；
• Planner 回归测试确认当前消息不会同时出现在 messages 与 current_message；
• Bot 镜像构建和健康检查通过；
• NapCat 容器未重建，OneBot 登录和反向 WebSocket 连接保持可恢复。

Yuki-QQbot 3.4.2

Yuki-QQbot 3.4.2 发布说明

3.4.2 为 GitHub Monitor 的 Release 事件补齐中文 PNG 卡片。它沿用 3.4.1 Push 卡片的暗色
视觉体系和持久媒体投递链路，不改变 Plugin API，也不新增数据库迁移。

Release 卡片

• 展示仓库、发布者、北京时间和版本标签。
• 区分正式版、预发布与草稿，并展示目标分支和附件数量。
• 展示版本名称与最多三行发布说明；长文本按像素宽度安全换行和省略。
• 使用容器内中文字体本地渲染，不读取远程字体或图片。
• send_card=false 的目标仍只接收文本；其他 GitHub 事件的行为保持不变。

实现与兼容性

• GitHub Monitor 插件版本提升至 1.1.0。
• Release 事件归一化只保留渲染所需的有界字段，不向卡片链路传入完整原始响应。
• Push 与 Release 通过统一卡片分发入口进入已有媒体制品和通知 Outbox。
• Yuki 版本提升至 3.4.2，Plugin API 保持 1.1，Alembic head 保持 0028。

升级

升级前仍建议备份 data/。只重建 Bot 可以保留 NapCat 容器和 QQ 登录状态：

docker compose up -d --build --no-deps bot

现有 GitHub Monitor 仓库、目标、Token、cursor 和通知历史都会保留。插件权限未增加；若 Host
因源码或版本变化将插件标记为待批准，由超级管理员重新批准并启用即可。

发布验证

• GitHub Monitor 事件、渲染、轮询和 Host 通知媒体测试通过；
• 插件 manifest、权限、入口、注册、启动和停止契约测试通过；
• 1200×630 中文 Release 卡片已实际渲染并检查长文本布局；
• Bot 镜像构建与健康检查通过，NapCat 容器和 QQ 登录状态保持不变。

Yuki-QQbot 3.4.1

Yuki-QQbot 3.4.1 发布说明

3.4.1 引入首个完整的后台通知插件 GitHub Monitor，并将 Plugin API 从 1.0 扩展到 1.1。
本版本新增非破坏性数据库迁移 0028，用于持久通知 Outbox、后台目标授权、媒体制品与受控
Agent 点评任务。现有聊天、记忆、关系、自动化和插件数据均会保留。

GitHub Monitor

• 可同时监控多个公开或私有 GitHub 仓库，并独立投递到多个 QQ 群或私聊。
• 支持 Push、PR、Issue、Comment、Review、Release、Discussion 等常见事件过滤。
• 首次同步默认只建立基线；稳定事件键、仓库 cursor 与条件请求避免重复推送。
• Push 事件通过 Compare API 补充提交、文件和增删行统计，并生成本地暗色 PNG 卡片。
• 中文摘要、持久 Outbox、失败退避、Rate Limit 感知和可选 Yuki 自然点评形成完整通知链路。
• 提供 /github 超级管理员直达命令，用于添加目标、暂停、恢复、同步、测试和诊断。

完整配置与命令见
plugins/github-monitor/README.md。

Plugin API 1.1

• 新增 notification.publish 与 notification.agent，由 Host 负责目标授权、幂等入库和受控
  主会话点评。
• 新增 media.artifact.create，插件可以创建有大小、类型和有效期边界的本地媒体制品。
• 新增 background.worker，后台服务使用统一生命周期、并发限制和失败重启策略。
• Host HTTP Facade 支持声明式 Secret credential 注入；插件无需读取或拼接真实 Token。
• 插件配置 JSON 序列化支持 Pydantic Model、set 与 frozenset，修复 GitHub 仓库添加命令的
  TypeError。
• 插件启用失败不再错误回复“已启用”，Planner 外部事件上下文也采用有界可信包络。

GitHub 卡片与中文字体

• 参考 GitHub 暗色信息层级重新设计 1200×630 Push 卡片：事件头、仓库与分支、四项指标、
  提交列表和北京时间页脚。
• Bot 运行镜像安装轻量开源文泉驿微米黑，解决 Linux 容器缺少中文字形导致的方框乱码。
• 卡片完全本地渲染，不读取远程字体或图片；过长仓库名、分支与提交说明按像素宽度省略。

升级

升级前仍建议备份 data/。只重建 Bot 可以保留 NapCat 容器和 QQ 登录状态：

docker compose up -d --build --no-deps bot

若使用 GitHub Monitor，在 .env 中配置：

PLUGIN_SYSTEM_ENABLED=true
PLUGIN_API_VERSION=1.1
PLUGIN_DIRECT_COMMAND_BINDINGS={"/github":"github-monitor:github"}
YUKI_PLUGIN__GITHUB_MONITOR__GITHUB_TOKEN=github_pat_replace_with_your_token

然后由超级管理员检查、批准并启用 github-monitor。Token 不应发送到 QQ、写入普通插件配置
或提交到 Git。

发布验证

• GitHub Monitor 契约、轮询、事件过滤与中文卡片测试通过；
• Host 插件配置、HTTP credential、外部通知、迁移 0028 与直达命令测试通过；
• Bot 镜像构建和健康检查通过，容器内中文卡片实际渲染正常；
• GitHub Token 鉴权、插件后台运行与 OneBot v11 反向 WebSocket 已实机验证；
• Bot 重建期间 NapCat 启动时间保持不变，QQ 登录状态保留。