v0.20.1

待发布草稿：记录当前候选改动，版本号以正式发布为准。此页面不表示 GitHub Release 已发布或实例已部署。

功能补齐

全局定时群总结开始生效：在 Bot 总结时区的配置时间，为没有逐群配置且最近 24 小时至少有 5 条符合角色过滤的消息的已知群执行总结。排除私聊、频道、退群和迁移旧群，沿用默认窗口、模型和提示词；逐群配置（包括关闭）优先。
全局调度使用独立持久执行记录，多个实例与重启共享 23 小时冷却；失败不自动补发，不创建隐式逐群配置。正常关停等待已接纳的总结和发送。

修复

Bot 交互、权限与模型能力

系统提示注入文件逐项隔离读取失败，单个文件不可读不再清空其他有效身份与设定内容；不缓存不完整读取结果，文件恢复后可在下一次加载重新读取，保留原优先级、预算和正常缓存规则。
AI 选择按钮校验原聊天、原消息及有效选项索引，拒绝跨消息和异常选项回调；被拒绝的异常回调不会消耗原选择。
定时器取消按钮重新校验点击者的管理员身份，避免其他群成员操作管理员展示的按钮；AI 取消工具仅操作当前聊天的任务，管理员仍可通过 /timers 管理其他聊天的定时器。
取消 AI 定时器会等待持久化成功，数据库失败不再误报成功；失败时保留本地任务供重试，取消与触发串行协调。已开始的投递不会被宣称撤销，AI 工具与面板使用一致的成功边界。
定时群总结按聊天隔离配置读取和执行异常，避免单个聊天失败阻断同批其他聊天；保留已登记任务的冷却，不自动重试或补发。
修复模型能力目录的解析层级，正确读取供应商下的模型数据；同名模型能力冲突时保留名称回退，图片能力优先依据输入模态，异常或空目录不会清空上次有效缓存。已有模型的手动能力配置保持不变。
模型能力目录返回 HTTP 错误时释放未读取的响应正文，继续保留上次有效缓存；正文释放失败不会掩盖原始 HTTP 状态。
Telegram 头像下载按分块执行 5 MB 上限，超限或 HTTP 错误立即取消读取并保留已有头像，避免缺失或低报 Content-Length 时先把整个响应读入内存；复用现有图片限量读取逻辑。
管理员确认动作已登记但尚未开始执行时，关闭 Bot 不再调起其执行回调；统一 AI 任务与管理员动作的限时结束等待，保留已执行任务的取消与超时结果。

MCP 连接与授权

通用 MCP 服务连接失败后保留连续重试次数，以指数退避最多自动重试 10 次；连接成功后重置，手动重连可开启新一轮。完整握手与工具发现限制为 30 秒，停用或删除服务后，过期连接结果不会重新激活服务。
MCP 请求取消或超时后，区分未发送、明确失败与结果未知。对于可能已执行的写操作，同一轮对话停止向该服务自动发送后续写入，仍允许只读核对；保留请求关联信息和脱敏后的远端错误原因。
图片 MCP 断开或重新授权后，旧 OAuth 回调和令牌刷新不能重新写入凭据、恢复旧连接或覆盖新的授权状态。
Bot 的 MCP 配置变更延迟重启绑定当前运行实例，连续修改合并处理；停止、显式重启和服务关停会收尾旧请求，避免旧任务再次影响新实例。重启尝试失败后，仍运行的实例可继续响应后续配置刷新。

以上 MCP 规则适用于面板中添加的通用 MCP 服务。取消请求不等于远端操作已撤销；结果未知时应先核对远端状态。此保护不提供跨进程去重或自动对账。

正常关停与后台维护

Bot Run 后台事件或终态写入失败时，由任务入口捕获并记录脱敏应用日志，避免未处理拒绝触发整个服务退出；不自动重试模型请求，也不保证数据库故障期间可写入终态，保留启动恢复处理。
修复 Bot Run 取消等待期间任务已完成时，旧请求仍覆盖完成状态、原因和时间的问题；无活动控制器时仅取消数据库中仍在运行的记录，已完成或已删除的运行不再误报取消成功。取消检查复用轻量状态查询，不再加载完整事件历史。
日志和 Bot Run 实时连接在认证等待期间断开时，认证结束后直接退出，不再创建事件流或启动其数据查询；保留原权限检查顺序。
已建立的实时连接断开后，停止推送迟到结果和同批剩余记录，已发出的查询返回后退出；保留日志范围与游标、Bot Run 事件续传及正常完成通知。任务取消仍由原操作控制。
SIGINT 与 SIGTERM 先后到达时共用同一次正常关停，避免重复停止服务和关闭数据库；保留原有关闭顺序。单个清理步骤失败后继续清理剩余服务，等待并行收尾全部结束，记录脱敏诊断并以非零状态退出。
定时提醒在正常关停时停止调度，等待投递结果和在途数据库操作后再关闭 AI 工具依赖，避免失败回调重新挂载重试；尚未发出的恢复提醒保留可恢复状态。
插件正常关停补齐应用自身的数据库准备与授权校验等待，避免活动会话登记前的查询在数据库关闭后继续；保留插件调用超时、晚到结果清理和已接纳配置修改的收尾。
群聊总结正常关停时停止接纳新任务，等待已有定时／手动总结（包括 Telegram /summary 成功回复）的执行和发送后关闭依赖；保留原有冷却、失败结果和暂停后恢复调度行为。
RSS 正常关停会等待已有抓取、摘要投递和检查点写入，并在此之前保留 AI 工具依赖；停止接纳新工作和后续调度。抓取超时、HTTP 错误及重定向不再遗留请求，保留现有 Feed 解析行为。
图片生成服务正常关停时停止接纳新的执行和供应商查询，取消后续轮询，并在关闭依赖前等待已接纳任务及其快照、投递回执收尾；管理员删除记录及随后的本地文件清理也纳入等待，关停后拒绝新的删除。后台数据库异常会被记录，避免未处理的 Promise 拒绝；关停不作为远端取消、退款或重发依据。
日志、Bot Run、非活跃记忆与互动样本上下文的定期清理在正常关停时等待已启动的数据库查询完成，避免数据库先关闭导致清理中断；保留周期和删除条件不变。
记忆整合在关停时不再开始处理下一 Bot，等待当前 Bot 的模型结果、用量结算、记忆及向量写入、租约释放后再关闭依赖。
图片保留清理在关停时等待文件删除、清理标记及其他仍在执行的并行查询，避免单项查询失败导致提前关闭数据库。
用量维护定时任务统一管理生命周期，关停时等待已启动的明细清理及预留回收，保持原周期和额度规则。
过期额度回收逐条隔离失败，避免已删除记录或单次事务异常阻塞同批其他预留；批次结束仍汇总报错，保留退款事务和幂等规则。
记忆整理的启动和定时查询失败会记录错误，后续周期继续重试，避免数据库暂时不可用导致未处理异常。
日志、记忆、图片和 Bot Run 清理器重复启动时不再产生遗留定时器，停止后可重新启动；应用关闭时同步停止 Bot Run 清理调度。
自动清理过期图片时，权限或存储故障会保留文件引用供后续重试，避免误记为已清理；其他记录仍继续处理。
RSS 调度停止时取消尚未触发的首次抓取；重复启动不再遗留重复定时器，停止后重新启动使用新的首次抓取延迟。
RSS 过期条目清理失败后在下一次正常轮询重试，不再误入一天的成功清理冷却；已成功清理时仍保留每日节流。
RSS 定时摘要按集合隔离异常，单个集合失败不再中断同批其他到期集合；日志记录失败集合 ID，保留原有时间、冷却和触发规则。

备份与文件管理

面板单文件、批量删除及 AI 文件工具统一按解析后的路径保护注入文件，修复相对路径或重复分隔符绕过保护的问题；AI 工具不再误拦截其他目录中同名普通文件的删除。
初始化 Bot 文件模板时以独占创建保留已有文件，避免检查后并发创建的内容被默认模板覆盖；已有符号链接不写入，其他写入错误仍报告失败。
AI 文件删除工具以目标文件删除结果为准，父目录清理失败不再误报文件删除失败；并发新增文件会保留。
文件预览、下载和 AI 读取工具按实际读取字节执行大小限制，避免文件在预检查后增长时绕过上限；保留原有超限提示，文本接口返回实际字节数。
文件列表跳过读取期间已消失的条目，避免单个文件不存在导致整个目录误显示为空；保留其他文件、目录排序和注入配置。
数据库备份改为流式导出，移除子进程额外的 512 MiB 输出缓存上限；导出或写盘失败时回收进程并清理部分归档，避免残留任务和无效文件。
已完成的备份不再因后续保留策略读取或清理查询失败而误报失败、生成重复失败记录；清理异常写入日志，远端上传错误仍保留在备份记录中。
保留策略清理单条旧备份失败时记录备份 ID 和错误，便于定位并重试；继续清理其他旧备份，新备份仍保持完成状态。
删除本地备份时，权限或文件系统错误会保留记录并停止后续删除，避免文件残留后失去重试入口；文件已不存在时仍可正常清理记录。
备份文件名前缀禁止路径分隔符和控制字符，创建、下载、删除统一拒绝越界或异常文件名；中文和空格前缀继续支持，下载响应保留 UTF-8 原文件名。
WebDAV 上传与删除正确编码文件名中的 #、? 和百分号，保留已编码目录与查询参数，避免文件名被误作 URL 结构。
WebDAV 备份上传、删除及连接测试会释放未使用的响应正文；上传失败时关闭本地文件流，避免连接和文件资源滞留。
备份下载在认证、查询期间断开后不再启动文件读取，下载中取消也会关闭文件句柄；与目录 ZIP 共用认证前的取消信号初始化，保留原有下载内容、文件名和长度。
目录 ZIP 下载取消或读取失败时关闭正在读取的文件，停止打开后续文件；认证或目录扫描阶段已断开的请求也不会在之后启动文件读取。扫描失败不会遗留已启动的读流，文件并发删除产生的错误由下载流接管。保留原有文件筛选、内容、时间和权限元数据。
文件编辑接口对 null 等无效 JSON 内容返回明确的 400，避免误报服务器异常；校验失败不会写入文件。
修复文件页中含 %、#、? 等字符的文件无法读取、下载、编辑或删除的问题；按 URL 路径组件只解码一次，保留字面的编码字符并拒绝编码分隔符。
修复文件页下载中文文件或中文目录 ZIP 时出现的 404／500，文件与备份下载共用支持 UTF-8 文件名的响应头构造。

邮件与飞书通知

邮件转发处理 IMAP 连接错误与断线，避免单个邮箱异常退出整个服务或让监控停在失效连接上；停止后，旧抓取或解析任务不能再发起新的转发。
首次邮件快照中断时重新建立快照，避免把尚未记录的历史邮件误当作新邮件发送；连接恢复时保留当前运行周期内已成功转发的去重记录。
积压的历史未读、过滤不匹配或禁用事件邮件不再阻塞后续新邮件；读取完成后再标记已读，避免 IMAP 流式抓取与标记命令互相等待。处理中收到的新邮件通知会合并补查。
邮件历史排除与可清理的发送缓存分离，修复初始未读超过 5,000 封后误转发历史邮件的问题；同一邮箱标识下重连保留基线，邮箱重建后重新建立基线，不自动补发历史邮件。
飞书 Webhook 的异常 JSON、响应读取失败或错误字段类型会返回明确的失败结果，避免测试消息出现未处理异常，或邮件转发绕过原有失败计数；客户端不会因此自动重发请求。

Harness、Bridge 与编码集成

Harness 调度器关停时停止推进未开始的排队请求，等待已进入会话创建流程的请求保存结果，避免提前关闭 Bot 与数据库；不自动取消或重建远端会话。
修复 Lody Bridge 密钥变化后仍复用旧凭据的问题：新客户端按实际密钥失效缓存，短缺密钥继续本地拒绝，不自动重发已有请求。
校验 Bridge 执行响应字段，避免格式异常被误判为确定失败或成功；保留未知结果处理及合法扩展字段兼容。
Bridge 输出限制统一按 UTF-8 字节计算，修复中文和 emoji 按字符数检查时可能绕过客户端上限的问题，保持超限结果分类。
修复 Lody 命令输出与等待模式错误提示在 UTF-8 字符跨数据块时出现乱码的问题，保留输出上限和超时分类。
统一本地与 Bridge 等待模式的控制行长度校验，修复超长行因输出分块不同而被误识别为完成事件的问题。
修复 Bridge 守护进程监控在 CLI 启动失败时遗留超时定时器的问题，保持原有恢复周期。
Bridge 认证拒绝和等待池拒绝响应也及时释放未使用正文，释放失败不覆盖原有错误分类或等待模式回退规则。
Lody Bridge 执行接口及时关闭 HTTP 错误的未使用正文，保留未知执行结果判定，不因收尾失败自动重发请求。
Pi 编码 worker 的空响应或非法 HTTP 状态不再触发服务未捕获异常；响应中途断开会及时返回失败。已接受的任务仍要求新的 worker 启动身份，不自动重发任务。
断开 GitHub App 连接后，旧令牌或连接状态刷新不能重新写入缓存，也不会被后续请求复用；保留已开始请求的原调用结果，不把缓存清理等同于远端操作撤销。

图片与媒体处理

腾讯转写查询返回业务限流时继续轮询原任务，不再提前判定转写失败；只重试已有任务查询，付费提交、配额错误及识别终态失败仍不自动重试。
旧版 PixAI 图片存储与清理校验本地文件路径，拒绝任务 ID 中的目录跳转或非法路径，避免越出生成目录；正常任务文件名保持不变。
旧版 PixAI 生成图片下载遇到 HTTP 错误时释放未使用的响应正文，保留同批其他图片下载和原有失败日志，不自动重试失败请求。
yt-dlp 桥接退出时校验 UTF-8 解码尾部，避免完整结果后的不完整字节被忽略；正常分块字幕解码、超时和失败回退规则不变。
音频暂存即使遇到目标文件关闭失败，也会继续关闭源文件，避免异常路径遗留文件描述符。
通用图片下载及时关闭重定向和被拒绝的响应，避免错误状态、无效类型或超限声明的正文继续占用连接和带宽；正常图片下载与校验保持不变。
通用图片下载在 DNS 解析等待期间也能及时响应取消或超时；统一媒体 HTTP 与语音识别的取消等待逻辑，接住底层操作的迟到失败并清理监听。此行为只结束本地等待，不代表远端任务或系统 DNS 已停止。
云端转录成功后先保存结果，再清理签名音频；删除失败通过持久清理待办重试，不再把成功转录误报为失败。恢复中的供应商任务继续保留所需音频，旧 attempt 不清理新任务音频。

日志与内部结构

旧头像请求迟到失败时保留新档案的刷新间隔，避免档案重建并成功刷新后，下一条消息再次发起重复头像请求；当前失败请求的五分钟重试规则不变。
历史重复记忆清理按完整创建时间复核保留项，修复同毫秒内微秒时间与 ID 顺序相反时，预览可见但执行持续报冲突的问题；保留向量优先和原有加锁顺序。
记忆去重确认与编辑共用数据库单调递增版本，避免应用时钟回退或快速连续更新恢复旧编辑版本，保留内容与向量。
提示词记忆列表复用现有记忆检索的权限过滤，移除重复条件；用户与聊天隔离、有效期、排序和数量限制保持不变。
Embedding 供应商响应逐请求校验数量、索引和维度；乱序结果按索引归位，无效结果按生成失败降级，避免 SDK 分批拼接造成文本与向量错配。保留全部省略索引的兼容响应，不新增自动重试。
群聊消息补充识别内容时清除旧检索向量，在线及批量生成结果仅在所属 Bot、消息和完整内容仍匹配时写入；相同内容的重复保存保留已有向量，避免旧请求迟到污染新消息检索。
历史 Embedding 回填按固定 ID 上界和游标推进，避免生成失败后反复请求同一批记录；写入前核对原内容及空向量状态，不覆盖并发更新，分别报告保存、失败和跳过数量。每批供应商请求设 5 分钟上限，超时后继续下一批；数据库操作不受此上限约束。失败记录可人工重跑，新记录留待下次扫描；仅补充记忆向量时保留编辑版本和最近更新排序。
转写客户端按实际支持的字节上传或 URL 转录能力组织接口，移除未被生产调用的兼容包装；保留腾讯短音频直传、长音频 URL 转录及云任务恢复，腾讯 5 MiB 阈值由提交与执行路径共用。
音频存储移除仅被测试使用的整块 Buffer 读写接口，测试统一覆盖生产使用的文件暂存与流式读取；签名、有效期、文件校验和长音频背压行为保持不变。
移除视频缓存内部未使用的独立定时器接口，清理继续由视频下载服务统一调度；缓存保留期限、任务恢复和关闭等待行为不变。
全局未捕获异常与未处理拒绝在输出致命日志前脱敏，日志器自身失败也确保以状态码 1 退出；保留立即退出及外部进程管理器重启策略。
结构化诊断补齐错误名称的凭据脱敏和长度限制；Buffer、TypedArray、DataView 与 ArrayBuffer 仅保留类型和字节数，避免原始字节展开或长度信息丢失。
修复诊断文本中含空格、转义引号的凭据脱敏不完整问题，保留正常错误原因、JSON 结构和 token 用量信息；重复记录已脱敏内容时不再累积多余标记。
工具日志在截断前完成已知密钥脱敏，并贯通普通回复与后续回话的日志链路，避免密钥跨越截断点时留下前缀。
收拢 Bot 生命周期队列和会话保留调度，保持原有串行操作、清理节流与关闭等待行为，补充并发及失败恢复回归覆盖。
图片、RSS 和群聊总结共用运行中任务的登记与等待实现，集中维护后续子任务的收尾规则；各服务原有关闭、取消和错误处理行为保持不变。
分离共享文件类型常量与 Node 路径工具，消除面板构建时的 Node 模块兼容警告；文件类型、大小限制及路径校验行为保持不变。

使用与升级

公开指南集中说明 Bridge 密钥、输出与故障处理，并按后台任务列出正常关停的等待范围，保留原有章节链接。
部署验证脚本支持指定旧版本完整 Git SHA，验证升级、独立数据库和文件卷恢复、原账号登录、凭据解密及迁移内容一致性。
验证过程使用一次性隔离资源，并检查缺失或错误加密密钥；升级和恢复时关闭密码初始化，避免自动补建账号掩盖恢复问题。
更正文档中的密钥要求：所有环境均需配置 ENCRYPTION_KEY。升级及恢复应保留原密钥，并同时备份数据库与文件卷。详见备份与升级。

本候选版本新增数据库迁移 0069_hard_harpoon.sql，创建全局总结执行记录表，不修改已有逐群配置。启动新版本前应完成项目的正常数据库迁移流程。

已有全局总结时间将开始生效。 升级前请检查 Bot 总结开关、小时、分钟和时区；不希望向符合条件的群自动发送时，请关闭总结或清空全局时间。详见全局定时总结。升级前仍应备份，并保留上一版本镜像和配套备份。

备份前缀是文件名的一部分，不能用来指定子目录。已有含路径分隔符或控制字符的配置需先修改；不安全的历史记录不会通过下载或删除接口访问目录外文件，需由维护者核对后处理。

若旧 WebDAV 备份文件名含 #、? 或百分号，请核对远端实际对象名称；旧版本可能使用了截断或解码后的路径。本次不自动重命名旧对象，也不会猜测旧路径补删。

验证范围

本轮全局总结验证

本轮全局调度在一次性 PostgreSQL 17 上通过 18 项，包含执行生成的迁移、候选过滤、逐群配置优先、多实例与重启去重、过期续约、配置并发关闭、时区、失败冷却和关停等待。模型与 Telegram 发送使用替身，不代表真实群投递。

独立运行的集成验证

Bot Run 取消在一次性 PostgreSQL 17 上通过 4 项，验证旧请求不能覆盖已完成终态、已删除记录不误报成功，以及正常取消、重复取消和 Bot 隔离；未访问生产数据。
记忆版本与历史重复清理在一次性 PostgreSQL 17 上通过 5 项，包含微秒保留项排序、相同创建时间的 ID 决胜、微秒版本兼容、并发编辑拒绝及应用时钟回退后的去重版本单调递增；未访问生产数据。
Embedding 响应边界新增 14 项真实 SDK 与网络替身回归，覆盖乱序、无索引兼容、无效响应及多批索引与数量；另补充单条及并行分批请求的 2 项取消传播回归；均未调用真实供应商，已包含在上述全量计数中。
会话存储在一次性 PostgreSQL 17 上通过 8 项，包含内容更新后的旧请求迟到、新生成失败、批量写入、跨 Bot 和已删除记录保护，以及既有列表搜索；合成向量存入文本列，不代表 pgvector 检索或真实供应商验证。
历史 Embedding 回填在一次性 PostgreSQL 17 上通过 16 项，覆盖记忆编辑版本保留、批次超时后继续、失败跨批推进、人工重跑、并发内容/向量变化、扫描上界及数据库写入失败；使用合成向量和文本存储列验证 SQL 行为，不代表 pgvector 检索或真实供应商调用。
音频转录任务以一次性 PostgreSQL 17 通过 67 项集成测试，包含成功结果持久化后清理失败的重启重试、完成落库失败、供应商任务恢复和旧 attempt 隔离；不代表真实供应商识别验证。
视频下载服务在移除缓存闲置调度接口后，以一次性 PostgreSQL 17 重跑 13 项集成测试，覆盖任务恢复、清理重试和停用下载时的过期缓存清理；未访问真实视频服务。
插件生命周期在一次性 PostgreSQL 17 上通过 23 项，包含关停期间已接纳的配置修改仍能返回持久化结果。主机准备查询及工具前后授权另有受控并发测试；未运行真实外部插件或生产关停。
定时器在一次性 PostgreSQL 17 和隔离测试表上通过 3 项，覆盖关停后的成功／失败状态持久化、失败提醒恢复，以及两个注册表并发领取；不代表真实 Telegram 投递验证。
较早分组补跑的 153 项数据库测试全部通过，覆盖会话、记忆、素材库、图片授权存储、插件、媒体与视频任务及 Harness 存储。媒体任务测试夹具使用显式迁移列表，避免加载无关图片迁移导致整组未执行。
yt-dlp 输出校验另通过固定版真实提取器的 6 项测试，使用临时 Python 环境和合成平台响应，未访问真实视频内容。
ZIP 和备份通过本机真实 HTTP 断开和后续正常下载探针，文件内容及 CRC 验证通过；认证等待和 Bot 查询使用替身，未连接生产身份服务或数据库。
数据库导出使用一次性 PostgreSQL 17 容器、真实 pg_dump 和合成数据验证导出及恢复，未读取生产备份。
模型目录使用只读下载的真实公开响应验证解析，未调用模型推理接口。
MCP 生命周期和未知写结果通过本地模拟服务验证；图片 OAuth 断开竞态通过真实授权模块配合内存存储及网络替身验证。
IMAP 故障、停止竞态和大邮箱推进通过连接替身及真实 SDK 无网络探针验证，未连接真实邮箱或执行真实外部服务写操作。

临时容器、数据与 Python 环境已清理。上述集成测试在不同修复阶段分别运行，部分测试组存在重叠，不能相加视为单次全量零跳过，也不代表生产数据库或真实外部服务验证。

容器验证及限制

此前候选通过了隔离 Docker 全新安装、从 v0.19.1 升级，以及两条路径各自的独立数据库与文件卷恢复。原账号登录、合成凭据解密、迁移历史及内容、文件内容、文档访问和错／缺密钥检查均通过。四个一次性项目的容器、卷、网络与专用镜像标签均已清理并另行核对。

本次容器复验包含转写接口收敛、Embedding 响应校验与回填、会话向量内容保护、记忆过滤复用及版本和历史清理修复，也包含最近的头像刷新间隔、管理员删除关停、实时事件流断开及认证等待期间取消修复。

该轮也已纳入 Bot Run 取消竞态修复及状态查询收敛、后台持久化错误隔离、诊断序列化保护和全局致命日志脱敏；具体取消竞态另由真实 PostgreSQL 回归验证，诊断保护由定向测试验证。

本轮另以候选提交 42455cbadc9c544685d38d6f14d3d501e1ea9594，从基线 9230b4886fab79f2cbec47208b13e0bb2023a578 重新通过隔离升级与独立恢复，包含全局总结和 0069 迁移。原账号、合成凭据、数据库与文件内容保留，错／缺密钥检查通过；两个临时项目已清理。此后补充的验证说明属于文档修改，不将其描述成另一次运行镜像验收。

早期测试镜像包含未提交的工作区改动；最新升级复验使用上述已提交候选。部署版本字段仍使用完整 Git SHA，测试通过不等于正式发版或生产部署。容器结果只证明该快照的安装、升级和恢复兼容性，具体异常与并发行为由定向回归验证。以上不代表真实 Bot、外部插件或模型供应商的端到端验证，也不代表 CI、GitHub Release 或生产部署。