AstrBot

这是 AstrBot v4.19.2 中的一个已知 bug。原因：(1) qq_official 适配器缺少基于 message_id 的消息去重机制，因此 QQ Official webhook 的重试（如果未收到确认，Tencent 最多会重新发送通知 3 次）会被重复处理；(2) 在 UI 中禁用适配器时，适配器的事件处理器未被清理，导致重启后出现重复处理。修复方法：将 AstrBot 升级到最新版本——PR #6320 修复了由 QQ Official webhook 重试导致的重复消息处理问题。旧版本的临时解决方案：完全重启 AstrBot 进程/容器，而不是在 Web UI 中切换适配器开关，并避免频繁启用/禁用适配器。重复回复可能触发 API 频率限制封禁，因此强烈建议升级。

受影响版本：AstrBot 4.29.0-beta.1。后台任务的唤醒轮次会绕过正常的消息管道，仅当主 agent 调用 send_message_to_user 时才会投递输出。位于 astrbot/core/astr_agent_tool_exec.py:662 的旧警告仅在 llm_resp 为空时触发，因此当响应正常但未尝试投递时，完全没有任何提示。

修复方法：升级到包含 PR #10398 的 AstrBot 版本（该 PR 修复了 issue #10395）。在 Windows 桌面端，通过 AstrBotLauncher 更新并重启。对于 Git 部署：

cd AstrBot
git pull
# 根据你的部署情况安装/更新依赖
# 然后重启 AstrBot

使用以下命令验证修复：

grep -n "_has_send_oper" astrbot/core/astr_agent_tool_exec.py

该修复会在 runner.step_until_done() 和 get_final_llm_resp() 之后检查 cron_event._has_send_oper。如果后台任务产生了结果但未向当前会话投递任何内容，AstrBot 现在会记录一条包含 task_id 和 tool_name 的 WARNING 日志。该标志仅在成功投递后才会被设置，因此发送失败或发送到其他会话的情况也能被检测到。

此次未添加自动重发功能，因为模型可能是有意保持沉默。如果你需要保证投递，则必须额外实现一个回退逻辑：当 _has_send_oper 为 false 时，通过正常响应路径发送 llm_resp.completion_text；这会改变原有行为，应当谨慎测试。

旧版本的临时缓解措施：加强主 agent 的提示词，使已完成且产生了有意义结果的后台任务必须调用 send_message_to_user；或者在现有的 if not llm_resp 分支附近手动添加 _has_send_oper 的 WARNING 检查。任务结果并不会从 agent 状态中丢失——它会以 [BackgroundTask] ... Result: ... 的形式持久化在对话历史中——但用户不会收到通知。

这会影响 AstrBot v4.28.1。以根路径开头的插件 URL（例如 /api/v1/files/tokens/<token>）不会被识别为 URL。MediaResolver 会将其当作本地文件处理，且不检查文件是否存在，因此在 Windows 上它会被解析为 C:\api\v1\...；随后的读取操作失败，图片会被静默跳过。

永久修复方法：
1. 将 AstrBot 升级到包含针对 issue #10264 的 PR Fix/reject unresolvable image refs 的版本。框架现在会拒绝无法解析的媒体引用，而不是返回一个伪造的本地路径。
2. 修复生成该 URL 的插件——例如 astrbot_plugin_qqwebui v1.1.0——使其返回完整的绝对 HTTP URL，而不是以 / 开头的路径：

image.url = f'{PUBLIC_BASE_URL.rstrip("/")}/api/v1/files/tokens/{token}'
# 示例：http://127.0.0.1:6185/api/v1/files/tokens/<token>

有效的媒体输入包括 http(s)://...、已存在的本地文件路径、file://...、data:... 或有效的 Base64。

如果暂时无法升级，请修改 astrbot/core/utils/media_utils.py 中 _materialize_media_ref() 内的回退分支：

path = Path(media_ref)
if path.is_file():
    return _LocalMediaFile(path=path, mime_type=_guess_mime_type(path))
raise ValueError(f'Unresolvable media reference: {media_ref}')

修改后重启 AstrBot。旧的对话历史可能仍包含无效的 [Image Attachment: path ...] 占位符；请使用新发送的图片进行测试，包括引用和转发的图片，因为它们走的是相同的代码路径。

这是因为该插件在 main.py:52 中猴补丁了 aiocqhttp 的 call_action，但删除或卸载时没有在 terminate() 中还原。AstrBot 进程仍在运行时，内存中的 bot 对象还保留旧包装函数，所以调用栈会继续指向已删除的插件路径。解决方法是完整重启 AstrBot 进程；Docker 部署可执行 docker restart <AstrBot容器名>，原生部署则停止后重新启动服务。重启后确认 data/plugins/astrbot_plugin_temp_chat_fix 目录已删除即可。日志中的 retcode=100、no such temp session 表示 QQ 临时会话已失效，需要用户重新发起临时会话，这与插件残留报错不是同一个问题；应另行向 astrbot_plugin_temp_chat_fix 仓库反馈，让作者在 terminate() 中还原 call_action。

在 AstrBot v4.28.2 中，上下文压缩器在调用 text_chat() 时未传入 request_max_retries，因此 provider 会使用默认的 5 次总尝试次数，并采用指数退避。HTTP 429 会被重试，阻塞回复，直到所有尝试都失败。切换主模型无济于事，因为卡住的请求使用的是单独配置的摘要模型。回退逻辑也只调用一次 truncate_by_halving()，并且不会重新检查剩余历史记录是否仍能容纳。

修复方法：升级到包含 PR #10436 的 AstrBot 构建版本（commit 800fdcc 之后的 master）。该修复向摘要请求传入 request_max_retries=1——1 表示总共一次尝试，而非零次——随后立即回退到截断。它保留开头的系统消息，将剩余历史分割为完整的轮次，反复移除最旧的轮次，直到估算的上下文可以容纳为止，同时保留最新的轮次，并使 tool calls 与其 tool results 保持配对。

v4.28.2 上的临时解决方法：
1. 运行 /new 开始一个全新的对话；已确认此方法可以恢复回复。
2. 恢复摘要模型的配额/API 凭据，或配置一个可用的摘要模型。
3. 如果无法立即修复不可用的摘要模型，请禁用独立的 LLM 上下文压缩。

仅切换主聊天模型并不是有效的解决方法，因为它不会改变摘要模型。如果之后遇到经 API 确认且涉及 tool calls 的上下文溢出错误，还需使用包含 issue #7225 中成对弹出记录修复的构建版本。