AstrNa

AstrNa 是一款面向 AstrBot 的优化插件，目标是在不修改 AstrBot Core 的前提下，通过可独立开关的运行时补丁，改善上下文、发送链路、身份元数据、工具调用和部分模型兼容问题。

💌 售后：777879783 有问题请加，清漪也会蹦出来一起捣鼓。

🎉 AstrNa 当前正式版：1.5.10

当前已测试兼容 AstrBot 版本：4.28.0-beta.1

• 仓库地址：Sisyphbaous-DT-Project/astrbot_plugin_AstrNa
• 作者主页：Sisyphbaous-DT-Project
• 许可证：MIT License
• 更新日志：CHANGELOG.md

适合谁

如果你的 AstrBot 正在使用 QQ / NapCat / aiocqhttp，并且遇到这些问题，AstrNa 可能会有帮助：

• DeepSeek V4 或代理模型偶发 400。
• 群聊里模型分不清用户身份、群昵称、真实昵称、群身份。
• Bot 长回复被合并转发或分段插件处理后，后续上下文里看不到自己刚写过的完整内容。
• 历史上下文里残留旧图片 base64，导致上下文轮次不多但 token 仍然暴涨。
• 主动回复或第三方插件自建 LLM 请求时，当前引用图片没有进入多模态模型。
• AstrBot 群聊上下文感知注入太长，希望先用小模型筛选相关消息，再给主模型看。
• AstrBot 或 OutputPro 生成的合并转发太大，QQ / NapCat 发送失败。
• 图片转述没有结合用户当前问题和引用文本。
• 模型误用 send_message_to_user，导致发送前插件无法命中。
• 拟人 Bot 偶尔被提示词注入或模型失控影响，突然输出一大段不符合聊天节奏的长文。
• 希望 AstrBot 每天自动清理临时缓存，但不动日志，并且尽量避开正在聊天或调用模型的时候。
• 希望 AstrBot 自带指令可以按需只开放几个，而不是被“禁用自带指令”总开关一刀切。
• 希望 Bot 能按需查询当前群成员身份、群主、管理员、群头衔、群等级和生日月日。
• 希望群聊里不同群友同时提问时，Bot 不必完全一条一条排队回复。
• 开启群聊并发后，希望继续沿用 AstrBot 原生历史截断，并让群聊提示词缓存保持稳定。
• 希望 Bot 在指定群聊里只认明确唤醒词，不会因为顺手 @Bot 或引用 Bot 消息就必定插话。
• 希望插件报错后能自动脱敏分析，并辅助生成规范的 GitHub Issue 草稿。
• 希望 Bot 在单次工具调用回合里并行批量执行多个独立工具，避免逐个串行等待。

AstrNa 的所有功能默认关闭。建议按需打开，不要一次性全开。

安装

在 AstrBot 插件管理里使用仓库地址安装：

https://github.com/Sisyphbaous-DT-Project/astrbot_plugin_AstrNa

安装后进入插件配置页，按需要启用对应开关。

如果安装时报“目录已存在”，通常是 AstrBot 的插件目录里已经残留了同名目录。请先关闭 AstrBot，再检查并删除实例目录下的：

core/data/plugins/astrbot_plugin_AstrNa

随后重启 AstrBot 并重新安装。

功能控制台（Dashboard）

AstrNa 在 AstrBot WebUI 中内置了一个“功能控制台”页面，作为原插件配置页的可视化入口，不替代原配置页。

入口：AstrBot WebUI → 插件管理 → AstrNa → 打开插件页面（Plugin Page）。

页面体验：每次进入会播放一段可跳过的复古启动画面，随后展示一台 CRT 老电脑；滚动页面让镜头穿过屏幕，即可看到横向胶卷，每一帧对应一个 AstrNa 主功能（共 21 个），继续滚动或点击可放大进入该功能的 Win98 风格详情窗口，查看用途、适用场景、注意事项和专属原理演示，并直接开关。

启动画面、二维备用 CRT 和三维 CRT 屏幕上显示的版本号始终来自当前安装插件的 metadata.yaml，随插件升级自动更新；状态暂时无法读取时显示“Version unknown”，不会展示过期版本。

胶卷滚轮先用于连续浏览：轻滚即可翻动一帧，快速滚动可以连续翻过多帧；当胶卷完成翻页、居中停稳后，一次新的向前滚动手势才会进入当前帧详情，向后滚动始终只用于浏览。

配置边界：

• 控制台管理 21 个功能主开关，以及其中 9 个功能共 20 项子配置；所有状态来自真实配置，并与原插件配置页双向同步，不创建第二套配置；保存失败会回滚并提示。
• 有子配置的胶卷帧提供「功能设置」按钮（主开关右侧），打开独立的 Win98 控制面板窗口：左侧竖向标签（窄屏为顶部下拉）切换子配置，右侧展示说明、真实控件和该子配置的专属原理演示；详情页的“功能设置概览”也可直接进入。
• 布尔子开关点击后立即保存；数值、模型/人格选择、内置指令多选、并发工具多选和敏感替换使用“应用”按钮确认，未修改时按钮禁用；保存期间只禁用当前设置，失败自动回滚。
• 子配置的修改立即热同步到运行中的插件（如合并转发长度、清洗模型、唤醒范围、内置指令允许列表），无需重启；主功能关闭时也可预先编辑，主功能开启后生效，不会清空子配置。
• GitHub Token、通知 UMO 等敏感内容只显示“已配置/未配置”，绝不回显原值，清除操作需二次确认；UMO 白名单和群 ID 列表只显示数量与匿名编号，删除通过短期一次性句柄完成，完整 UMO、群号不会展示。
• 模型、人格与工具选项实时来自 AstrBot 当前配置；并发工具按插件、MCP 服务和 AstrBot 内置工具分组，可进入来源逐项勾选。已卸载、改名或停用的已选工具会保留为失效项，只能移除，绝不会执行。
• 实验性功能有醒目标识，启用 LLM 并发工具调用、群聊并发回复或 Issue 助手前会显示风险确认；开启并发工具功能但名单为空时不会注册批量工具，并会给出明确提醒。
• WebGL 不可用、移动端或开启减少动态效果时，页面自动降级为简化形式，全部开关和详情仍可正常使用。

功能总览

开关	默认	作用
修复 DeepSeek v4 400 报错	关闭	清理异常 assistant 历史，并补齐 DeepSeek V4 thinking mode 需要的 reasoning_content 字段。
优化身份元数据	关闭	把 AstrBot 自带身份识别内容改为稳定 JSON，并可选补充真实昵称、群身份和生日月日。
优化合并转发	关闭	拆短过长合并转发节点，并在 QQ / NapCat 发送失败时自动拆成更小合并转发重试。
优化超长回复上下文	关闭	Bot 长回复被合并转发或分段插件改写后，尽量把完整纯文本保留到后续上下文。
AstrBot插件缓存优化	关闭	将可安全识别的动态 system prompt 迁移到临时 extra 内容，减少对 prompt cache 的破坏。
优化图片历史上下文	关闭	把历史里的旧图片 base64 替换成轻量占位符，避免旧图反复撑爆上下文 token。
优化工具调用历史上下文	关闭	当前工具回合保留完整结果，回合结束后把已完成的历史工具结果替换成轻量占位符。
优化引用图片视觉输入	关闭	为主动回复或第三方插件自建的 LLM 请求补齐当前 Reply 引用图片。
群聊上下文优化	关闭	在 AstrBot 群聊上下文感知启用时，用小模型筛选相关群聊原文并生成简短摘要。
更好的图像转述	关闭	图片转述时补充用户当前问题和引用文本，让转述模型带着问题看图。
优化send_message_to_user工具	关闭	把普通聊天里误用工具发送当前会话纯文本的情况改回普通最终回复。
输出字数限制	关闭	Bot 最终文本过长时，用清洗模型按人格和思考内容改写成短回复。
提供群身份查询工具	关闭	为 Bot 提供查询当前群成员身份、群主、管理员、群头衔、群等级和生日月日的工具。
LLM 并发工具调用	关闭	只并行 Dashboard 中由管理员明确选择、且当前请求本来可用的工具；单批最多 8 项。
优化回复历史标记	关闭	临时注入中文回复指向说明，帮助模型区分当前发言人和被引用回复对象。
关闭群聊 @Bot 唤醒	关闭	让指定群聊中的 @Bot 像普通群消息一样处理，不再单独触发默认回复。
关闭群聊引用 Bot 唤醒	关闭	让指定群聊中引用 Bot 消息像普通群消息一样处理，不再单独触发默认回复。
解锁群聊并发回复（实验性）	关闭	⚠️ 实验性。同群不同群友的 LLM 后台并发，每轮消息按群连续发送；历史只合并可信并发新增轮次，不复活已截断旧历史。
自动清理 AstrBot 缓存	关闭	每天 00:00 在 AstrBot 空闲时清理原生临时缓存，不清理日志。
自定义开启 AstrBot 内置指令	关闭	用多选下拉控制 AstrBot 核心内置指令，选中的能用，没选中的不能用。
自动报错分析与 Issue 助手（实验性）	关闭	⚠️ 实验性。插件报错后自动脱敏分析，并在用户确认后生成/提交 GitHub Issue。

功能说明

修复 DeepSeek v4 400 报错

这个开关同时处理两类常见问题：

• 历史里出现空 assistant、纯 reasoning、纯 think 内容块，导致接口 400。
• 使用代理模型名，例如 opencode/deepseek-v4-pro 时，AstrBot 没识别出 DeepSeek V4 thinking mode，导致 assistant 历史缺少 reasoning_content。

AstrNa 会在发送请求前做兼容修复，不会改写用户消息正文，也不会影响 deepseek-chat、deepseek-reasoner 等旧模型。

优化身份元数据

这个功能依赖 AstrBot 自带“用户识别/身份识别”已开启。AstrNa 不凭空制造身份信息，只会在 AstrBot 已经注入身份内容时，将它整理为更稳定的 JSON：

{
  "user": {
    "user_id": "1719500341",
    "nickname": "C2H25NO6",
    "account_nickname": "账号昵称",
    "birthday": {
      "month": "10",
      "day": "11"
    }
  },
  "group": {
    "group_id": "777879783",
    "name": "群名",
    "member": {
      "role": "admin",
      "role_name": "管理员",
      "level": "12",
      "title": "专属头衔"
    }
  }
}

可选子功能：

• 真实昵称：补充或替换群昵称。
• 补充群成员身份：通过 NapCat / aiocqhttp 查询当前发言人的群主、管理员、普通成员、群等级和专属头衔。
• 注入生日信息：通过 get_stranger_info 查询当前发言人或私聊对象的生日月日。

生日只注入月日，不注入年份；查不到时自动跳过。身份元数据会作为临时内容注入，不写入会话历史。

优化合并转发

这个功能依赖 AstrBot 或输出插件最终生成标准 Node / Nodes 合并转发。AstrNa 会把过长的单个转发节点拆成多个较短节点，降低 QQ / NapCat 因单节点过长导致发送失败的概率。

如果 AstrBot 原本没有触发合并转发，打开这个开关也不会强制把普通消息变成合并转发。

如果合并转发已经生成，但 QQ / NapCat 在发送阶段返回类似 retcode=1200、发送转发消息 res_id 失败 这类错误，AstrNa 会接管这次发送，把一个大的合并转发包拆成多个更小的合并转发包重试；如果拆到单个节点仍发不出去，会最后兜底成普通分段发送，尽量把长文本完整送达。

优化超长回复上下文

当 Bot 写出很长的文章、总结或设定文时，AstrBot 或 outputpro 一类插件可能会把最终发送内容改成合并转发，或者提前直发前几段，只把最后一段留给 AstrBot 继续发送。某些情况下，Bot 后续上下文里看不到自己刚写过的完整内容。

开启后，AstrNa 会尽量保留本轮 LLM 生成的完整纯文本，让后续对话仍能引用这段内容。

安全边界：

• 只处理 Bot 自己的 LLM 回复。
• 不展开群友发送的合并转发、Forward、Node 或 Nodes。
• 不改变真实发送到聊天平台的消息内容。
• 尊重 _no_save、tool calls、纯媒体结果、私聊/群聊边界。
• 过长内容最多保留 20000 字，超过后会截断并标记。

AstrBot插件缓存优化

部分插件会每轮动态追加 system prompt，导致 prompt cache 很难命中。AstrNa 会观察这些动态内容，如果确认某个注入位置是安全的纯追加或前置追加，就把后续动态语义块迁移到临时 extra_user_content_parts。

这个功能采取保守策略：

• 固定不变的提示词继续保留在 system_prompt。
• 动态内容尽量按完整语义块迁移。
• 复杂重写、删除或替换会自动跳过。

优化图片历史上下文

AstrBot 在本轮图片进入模型时，会把图片转换成 OpenAI 多模态格式里的 data:image/...;base64,...。如果这些内容原样保存到 conversation history，后续普通对话即使只保留最近几十轮，也可能因为旧图片 base64 过长导致 token 暴涨。

开启后，AstrNa 会做两层清理：

• 每轮 LLM 请求前，把旧历史里的图片 base64 替换为 [历史图片：已省略原始图像，仅保留占位符]。
• AstrBot 保存历史前，阻止本轮已经 assemble 出来的图片 base64 继续落库。

这个功能不会影响当前消息的新图片和当前引用图片：它们仍然会按 AstrBot 原逻辑进入视觉模型，或者进入图片转述模型。已经存在的图片说明、普通文本、身份信息、群聊上下文筛选结果和其他插件临时注入内容也会保留。

优化工具调用历史上下文

搜索、网页读取、RAG 等工具一次可能返回数千甚至数万 token。AstrBot 为了维持工具调用结构，会把 assistant.tool_calls 和对应的 role=tool 结果一起保存进 conversation history；如果完整结果一直保留，下一轮只是说“谢谢”，模型仍会再次读取这些大段结果。

开启后，AstrNa 会做两层处理：

• 每轮新 LLM 请求前，检查已有会话历史，把结构完整、已经被后续 assistant 消费的旧 tool.content 换成固定短占位符。
• 当前 Agent Loop 结束、AstrBot 准备保存历史时，只改写交给保存函数的副本；正在执行的工具调用和模型据此生成最终回答的过程仍能看到完整结果。

AstrNa 不会整组删除工具消息：assistant.tool_calls、调用参数、每个 tool_call_id、并行工具的数量与顺序、最终 assistant 回答都会保留，避免破坏 OpenAI compatible 等供应商要求的工具调用配对。只有后续 assistant 真正给出可落库的非空文本，或继续发起一组 ID 完整且不重复的新工具调用时，上一组工具结果才会被视为已消费。空字符串、空列表、空 TextPart、纯思考、纯图片/音频、临时 _no_save 内容和 AstrBot /stop 中断提示都不会触发压缩。

AstrBot 达到工具 max_step 后可能会插入内部收尾提示；AstrNa 会读取当前 AstrBot 版本的运行时常量，只在所有预期工具结果都收齐且提示完全匹配时穿过这条内部消息，再等待后续有效回答。普通用户消息或相似但不完全相同的提示会中断工具事务并保留原文。内部常量无法读取时也会采用保守策略，不改写工具结果。

代价是后续回合不能直接从历史中重新读取被省略工具结果的原始细节；需要这些细节时，模型应重新调用工具。该功能也不会移除每轮固定发送的工具定义 schema，因此工具很多时仍会有一笔稳定的输入 token；普通用户与 assistant 文本历史也会按 AstrBot 的上下文设置正常增长。它解决的是“调用一次大工具后，后续每轮反复携带同一份大结果”的主要增量，而不是让所有请求 token 永远完全相同。

优化引用图片视觉输入

AstrBot 原生主流程会把当前消息里的图片和引用图片整理进 req.image_urls，让多模态模型能看到。但部分主动回复插件或第三方插件会自己调用 event.request_llm() 创建请求，这条路可能只带了文本占位符 [Image]，没有把当前 Reply 引用图片真正交给模型。

开启后，AstrNa 会在每轮 LLM 请求前检查当前消息中的 Reply 组件，调用 AstrBot 自带引用图片解析逻辑，把解析出的图片去重追加到本轮 req.image_urls。在 NapCat / aiocqhttp 这类 bot.call_action 场景下，AstrNa 会做兼容兜底，避免自建请求拿不到被引用消息图片。如果引用组件里只有已经失效的本地临时图片路径，AstrNa 会丢弃死路径，并尝试通过 get_msg / get_image / get_file 等 OneBot 接口重新取得可用图片。如果 AstrBot 原生流程已经补过图，AstrNa 不会重复追加。补图成功时，还会临时注入一句“当前消息引用了 N 张图片，已作为本轮视觉输入提供。”，这句提示不会写入会话历史。

边界：

• 只补当前消息引用的图片，不恢复历史图片。
• 不展开群友合并转发内部图片。
• 不修改 req.prompt、req.contexts 或 conversation.history。
• 可能增加本轮图片 token，默认关闭。

群聊上下文优化

这个功能依赖 AstrBot 自带“群聊上下文感知”已经启用。AstrBot 原生的 group_message_max_cnt 是群聊记录缓存上限，不代表每次都会固定注入这么多条；原生逻辑会在每次 LLM 请求后移除已经注入过的群聊记录。

开启后，AstrNa 会复用 AstrBot 自己维护的最近 N 条群聊缓存作为滚动窗口，N 仍完全沿用 AstrBot 当前 group_message_max_cnt 设置。AstrNa 不额外设置群聊记录条数，也不额外设置主会话历史轮数；同时会持久保存最近群聊文本到 AstrBot 插件 KV，重启后仍可用于小模型筛选。影芯、主动回复或第三方插件提前触发 request_llm()，导致 AstrBot 还没给当前事件打群聊上下文标记时，AstrNa 会尽量使用已保存或已记录的滚动窗口继续压缩。

如果当前请求收到 AstrBot /stop，AstrNa 会在最多约 50ms 内停止等待压缩模型，并丢弃已经在途或迟到的筛选结果，不再向主模型追加兜底或压缩内容，也不会修改滚动记录和 KV。远端 provider 请求可能已经产生用量，AstrNa 只能尽力取消它，不能撤销服务端已经接受的请求。

这些内容会交给压缩模型筛选：

• 按 AstrBot 当前上下文轮次设置预裁剪后的主会话最近历史。
• AstrBot 最近 N 条群聊滚动窗口。
• 当前触发者昵称、用户 ID、群信息和当前待回复消息。

AstrNa 会先调用你在子项中选择的聊天模型供应商，让它只做“相关上下文筛选 + 简短摘要”，然后把筛选结果作为临时内容注入给主模型。推荐选择 deepseek-v4-flash 这类便宜快速的小模型。主会话最近历史只提供给压缩模型用于判断相关性，不会被 AstrNa 额外重复注入给主模型；传给压缩模型的这份历史副本也会沿用 AstrBot 当前的上下文轮次限制预裁剪（AstrBot 4.28 起读取 agent_runner.config.compression 下的 max_turns / trim_turns，更早版本读取 provider_settings 下的 max_context_length / dequeue_context_length），不会把截断前完整 conversation history 全量交给小模型。主模型自己的正式上下文截断仍由 AstrBot 原生链路处理。

压缩模型和主模型都会看到一段当前触发者身份提示，用来区分“本轮要回复的人”和“历史相关消息的发送者/话题源头”。例如唤然先问了某个话题，笨蛋老哥后来接着这个话题追问，AstrNa 会提醒模型：当前触发者是笨蛋老哥，唤然只是历史话题源头，不要混成同一个人。

需要注意的是，压缩用的小模型每轮都会读取变化的当前消息、主会话最近历史和群聊滚动窗口，提示词缓存通常很难命中，甚至可能基本失效；因此它应当优先选择成本低、速度快的模型，而不是昂贵的主力模型。

另一个需要注意的点是：开启该功能后，AstrNa 会持久保存最近群聊文本用于重启恢复。

小模型输出会明确包含：

• 与本次回复相关的原文摘录。
• 一小段群聊摘要。
• “这里只是上下文筛选，不是回复建议”的说明。

安全边界：

• 只在群聊 LLM 请求中生效，私聊不启用。
• 群聊上下文不存在或 AstrBot 没有启用群聊上下文感知时不启用。
• 未选择压缩模型、模型不可用、调用失败、输出为空或格式不合格时，不会把 AstrBot 原始群聊流水账交给主模型。
• 只额外注入 AstrNa 筛选后的群聊相关内容，不改动身份元数据、回复指向说明、动态 system prompt 迁移等其他临时注入内容。
• 小模型不会使用持久会话，不会污染聊天历史。

更好的图像转述

当主模型不支持图片、AstrBot 使用独立图片转述模型时，AstrNa 会把用户当前问题和引用消息文本补充给转述模型，让图片描述更贴近这次对话。

如果主模型本身支持图片，或 AstrBot 切换整次请求到多模态 fallback provider，AstrNa 不会干预。

优化send_message_to_user工具

有些模型会在普通聊天里误调用 send_message_to_user 来发送当前会话纯文本，导致发送前插件、表情包识别、分段回复和合并转发等流程无法正常命中。

开启后，AstrNa 会把这种当前会话纯文本调用改回普通最终回复。跨会话主动消息、定时任务、live、图片、文件、语音、视频和 @ 不会被接管。

输出字数限制

拟人 Bot 正常聊天通常不会每次输出长篇大论。但模型偶尔会被提示词注入、上下文污染或自身失控影响，突然把草稿、分析、重复句、无关内容一股脑发出来，聊天体验会很突兀。

开启后，AstrNa 会在普通 LLM 最终文本回复超过设定字符数时，调用你选择的清洗模型，把这段过长回复改写成短回复，再放回 AstrBot 原本的发送链。这样 outputpro、分段、合并转发、表情包识别等发送前插件仍然能继续处理最终内容。

清洗模型会拿到：

• 当前参考人格提示词。
• 主模型本轮思考内容。
• 主模型原始过长输出。
• 用户设置的最多字符数。

它的任务不是摘要全文，而是判断主模型最可能想表达给用户的原意，删掉流口水、重复句、提示词注入痕迹、内部分析、草稿说明和无关内容，并尽量贴合人格语气输出一条短回复。

配置建议：

• 最多输出字数默认 50，中文、标点、emoji、换行都按字符计数。
• 白名单 UMO 可逐项添加多个，也支持批量导入；可用它放行需要长回复的群聊或私聊，命中后不会关闭流式，也不会限制输出。
• 清洗模型建议选择便宜快速的小模型；留空或调用失败时，AstrNa 会直接硬截断到设定字符数。
• 清洗模型输出不会二次限制。它如果仍然超长，AstrNa 也会放行，避免递归调用。

如果当前请求收到 AstrBot /stop，AstrNa 会在最多约 50ms 内停止等待清洗模型，请求主 Agent 进入 AstrBot 原生的 aborted 收尾，并返回原始响应，不硬截断、不生成新的清洗响应。已经发出的远端请求可能仍会产生用量；迟到的清洗结果会被丢弃。运行时开关重排只会停止等待新任务，不会把 /stop 误当成功能关闭去停止主 Agent。

安全边界：

• 只处理 Bot 最终普通文本回复。
• 工具调用、报错回复、流式 chunk、图片、文件、语音、视频等非纯文本结果不会处理。
• 开启后，非白名单会话会提前关闭本轮流式输出，避免长文先流式发出后才被拦截；Live Mode 会保留流式并跳过限制。
• 清洗调用使用临时 session，不写入会话历史。
• 触发清洗后会清除原始 reasoning，避免原始长思考或污染内容继续进入发送和保存链路。

提供群身份查询工具

开启后，AstrNa 会给 Bot 注册按需工具。模型只有在用户问到群身份、群头衔、群等级、群主、管理员、群友生日或近期生日时才需要调用。

当前支持：

• 查询某个群成员的身份、群等级、专属头衔。
• 查询当前群群主和管理员。
• 查询某个群成员生日月日。
• 查询当前群未来一段时间内的生日列表，默认 7 天。

限制：

• 只查询当前会话所在群，不支持跨群。
• 依赖 NapCat / aiocqhttp 可查询到的数据。
• 生日只返回月日，不返回年份。
• 昵称歧义时返回候选，不替模型猜人。

优化回复历史标记

它会在当前轮请求里临时注入中文回复指向说明，帮助模型区分：

• 当前发言人是谁。
• 被引用消息是谁发的。
• 被引用的 Bot 历史回复原本回复给谁。
• 这次真正应该回复谁。

AstrNa 也会清理旧历史里的内部标记，并移除模型误输出的内部标记，避免污染真实发送内容和后续历史。

QQ 官方 Bot 平台的引用消息目前缺少可靠的被引用消息发送者信息。AstrBot 只能构造出引用内容本身，不能稳定告诉 AstrNa 这条被引用消息是谁发的；如果强行猜测，反而可能把未知发送者误当成无意义的默认 ID。因此这个功能不兼容 QQ 官方 Bot 的引用回复指向优化，建议在 NapCat / aiocqhttp 等能提供完整引用发送者信息的平台使用。

关闭群聊 @Bot / 引用 Bot 唤醒

AstrBot 原生会把 @Bot 和“引用 Bot 自己的消息”当作直接唤醒信号。在闲聊很活跃的群里，群友有时只是接着旧话题聊天，Bot 也会被顺手喊出来。

AstrNa 可以分别关闭指定群聊中的两种唤醒：

• “关闭群聊 @Bot 唤醒”：只移除 @Bot 带来的必定回复。
• “关闭群聊引用 Bot 唤醒”：只移除引用 Bot 消息带来的必定回复。

每项功能都有“应用于所有群聊”和“目标群聊 ID”两个折叠设置。全群开关打开时会忽略 ID 列表；全群开关关闭且列表为空时不会影响任何群。每项填写一个群聊 ID，不需要 UMO，可用 AstrBot 的 /sid 查看群号。不同平台恰好使用同一个群 ID 时会同时命中。

命中后，原始 At、引用内容和引用图片都会保留，群聊上下文、普通插件和 AstrBot 主动回复仍按普通群消息处理；它不是“整条消息静默”。唤醒词和 AstrBot 已识别的有效指令优先，@全体、At 其他成员、引用其他成员和私聊不受影响。单独发送一个 @Bot 时，AstrNa 也会跳过 AstrBot 原生的问候与 60 秒等待器。

该功能主要面向 NapCat / aiocqhttp 等能标准化提供 At 与引用发送者的平台。QQ 官方 Bot 无法可靠判断被引用消息是否由 Bot 发送，因此不会猜测；Discord Role Mention 等适配器预置唤醒不在第一版处理范围内。

解锁群聊并发回复（实验性）

⚠️ 这是实验性功能，请谨慎启用。

AstrBot 默认会让同一个群或私聊里的 LLM 回复排队执行。开启后，AstrNa 会把群聊里的 LLM 排队粒度改成“按群友分别排队”：同一个群里，不同群友的模型生成和工具链可以继续在后台并发；同一群友连续发消息仍然串行，私聊也仍然串行。

同一个群的实际消息发送会按整轮排队。谁先产生第一条需要发送的消息，谁先获得发送权；获得后会连续发完本轮工具状态、工具直出、分段回复、媒体和合并转发，下一轮才能开始发送。因此两轮分段回复不会再出现 A1、B1、A2、B2 这样的穿插。普通群聊会自动关闭本轮流式输出，等模型生成出可发送内容后再进入队列；这不会取消后台 LLM 并发。

并发请求保存历史时，AstrNa 会把 AstrBot 本轮完成截断、压缩或总结后的结果当作权威底稿。没有并发写入时会原样保存；确实有其他群友的请求先完成时，只补回那次请求新增的完整轮次，不会把 AstrBot 已经删掉的旧历史重新接回来。这样既保留并发分支，也让后续普通请求继续按 AstrBot 的原生上下文轮次配置收缩，提示词缓存不会因为旧历史每轮滑动复活而持续失效。

完整轮次从本轮真实用户消息开始，包含工具调用、工具结果、工具图片、内部续步、最终回复和 checkpoint。两次内容完全相同的真实提问仍会分别保存；如果 AstrNa 无法证明数据库最新版来自自己上一笔成功保存，或无法安全定位当前完整轮次，就直接采用 AstrBot 的本轮结果，宁可少保留极少数并发分支，也不会冒险让历史无界增长。该过程不会向模型提示词或数据库历史加入随机 ID、时间戳等缓存干扰内容。

这个设计会改变消息处理时序。AstrNa 会尽量兼容消息防抖插件：防抖插件在群聊里也是按“群 + 发送者”做防抖窗口，因此 AstrNa 会保留同一群友的连续消息合并、取消旧回复和超时伪造事件逻辑，避免把防抖时序打乱。

但它无法保证兼容所有会干扰消息流水线的插件。如果同时开启消息防抖、分段回复、合并转发、主动消息，或其他会改写、延迟、取消、拆分、合并 Bot 回复的插件，请格外谨慎。

注意事项：

• 群聊回复的先后顺序可能和提问顺序不同。
• 谁先准备好第一条实际消息，谁先完整发送；短回复不会等待更早但尚未生成完成的慢任务。
• 同一群友不会并发，仍适合配合消息防抖使用。
• 私聊不会解锁并发，避免上下文和追问语义混乱。
• 主动消息、定时任务和 Live Mode 不进入普通群聊整轮发送队列。
• 第三方插件如果自行创建后台发送任务且不等待任务结束，这类已经脱离当前 Agent/Pipeline 的消息不会延长本轮发送权；需要整轮连续发送时，应在当前处理链中等待发送完成。
• 与其他可能干扰消息处理流程的插件同开时，建议先在小群或测试环境观察。
• 如果发现回复顺序、上下文或历史记录异常，请先关闭这个开关。

自动清理 AstrBot 缓存

AstrBot 设置页里的“清理缓存”主要清理磁盘临时缓存，例如临时目录、插件列表缓存和 sandbox skill 缓存。AstrNa 可以把这个动作自动化，但只清理 cache，不会清理日志。

开启后，AstrNa 会每天 00:00 尝试清理一次。清理前会先判断 AstrBot 是否空闲：

• 插件启动后至少等待 10 分钟。
• 当前没有 AstrNa 能观察到的 LLM、Agent 或发送链路活动。
• 最近 10 分钟内没有 AstrNa 能观察到的聊天活动。

如果到点时 AstrBot 仍在忙，AstrNa 会延迟 30 分钟后再试，不会强行清理。这个功能清理的是磁盘缓存，不等于直接释放 Python 进程内存；它更像是定期帮 AstrBot 打扫临时文件。

自定义开启 AstrBot 内置指令

AstrBot 自带“禁用自带指令”是总开关，打开后核心内置指令会被整包禁用。AstrNa 可以把它细化成白名单：在插件配置里打开“自定义开启 AstrBot 内置指令”，再用多选下拉选择要保留的指令。

可选择的核心内置指令包括：

• /help：查看可用指令和 AstrBot 版本信息。
• /sid：查看 UMO、UID、群号等会话信息。
• /name：设置当前会话显示别名，需要管理员权限。
• /reset：重置当前会话上下文。
• /stop：停止当前会话正在运行的任务。
• /new：新建并切换会话。
• /stats：查看当前会话 token 统计。
• /provider：查看或切换模型供应商，需要管理员权限。
• /dashboard_update：更新 AstrBot WebUI，需要管理员权限。
• /set：设置当前会话变量。
• /unset：删除当前会话变量。

开启后，选中的核心内置指令会继续走 AstrBot 原本的指令处理流程；没选中的核心内置指令不会触发。AstrNa 不绕过管理员权限、不改参数解析、不接管指令实际行为，也不会影响第三方插件指令或 builtin_commands_extension 扩展指令。

自动报错分析与 Issue 助手（实验性）

⚠️ 这是实验性功能，默认关闭。

开启后，当其他插件在处理消息时报错，AstrNa 会读取 AstrBot on_plugin_error 提供的 traceback，先做脱敏，再调用当前 LLM 进行初步分析。如果判断这像一个真实问题，AstrNa 会把提醒发送到配置的“Issue 助手通知/处理 UMO”，并提供后续命令：

• /astrna issue latest：查看最近一次报错分析。
• /astrna issue ignore：忽略当前报错。
• /astrna issue analyze：确认调用源码辅助分析流程。
• /astrna issue draft：读取目标仓库 Issue 模板并生成草稿。
• /astrna issue edit 补充内容：给草稿追加说明。
• /astrna issue submit：确认提交 Issue。
• /astrna issue cancel：丢弃草稿。

推荐使用上面的 /astrna issue ... 分组写法；下划线形式 /astrna_issue_latest、/astrna_issue_draft 等继续作为兼容入口保留。

也可以让模型通过自然语言调用同一组工具，例如“忽略这个报错”“用源码工具分析一下”“生成 issue 草稿”“确认提交”。真正提交 Issue 前仍需要明确确认；工具提交入口也必须带 confirm=true。

可选子功能“提供阅读源码和修改源码的功能”需要先安装并启用弥亚开发工具箱至少 2.6.0 版本。开启后，AstrNa 只负责把当前报错流程交给模型协调：先用工具阅读源码和定位原因，分析结论写回 AstrNa，再生成包含源码分析的 Issue 草稿。如果模型认为需要修改源码，必须先向触发者或管理员说明修改方案并获得确认，再交给弥亚开发工具箱的安全编辑工具处理。

安全边界：

• 用户确认前不会提交 Issue。
• 建议把“Issue 助手通知/处理 UMO”优先配置为维护者私聊，也可以配置为管理群；可以用 AstrBot 的 /sid 指令获取，常见格式类似 aiocqhttp:FriendMessage:QQ号 或 aiocqhttp:GroupMessage:群号。
• 配置绑定 UMO 后，普通聊天群里不会突然发送报错提醒；待处理报错默认只能在绑定 UMO 中处理，AstrBot 管理员可兜底处理。
• 如果绑定的是管理群，进入源码辅助分析流程后，该管理群后续对话可能临时附带源码分析提示；处理完请及时生成草稿、忽略或取消。
• 如果没有配置绑定 UMO，AstrNa 只记录和分析报错，不主动发送提醒，避免打扰原聊天群。
• 发送给 LLM 和 GitHub Issue 正文的 traceback 会先脱敏，但提交前仍建议人工检查。
• GitHub Token 不会发送给 LLM，也不会写入 Issue 正文；AstrNa 自身日志会尽量脱敏，但 AstrBot Core 可能已在插件 hook 触发前记录原始报错日志。
• 源码辅助分析提示只会在用户确认进入源码分析流程后临时注入，不会长期写入会话历史。
• 不依赖 gh 命令行工具；提交 Issue 使用 GitHub HTTPS REST API。
• 脱敏会优先保护隐私，部分数字可能被过度遮盖，提交前可以按需要手动补充。
• 第一版主要处理 AstrBot on_plugin_error 能捕获的插件报错。Core 级 ERRO 如果信息不足，AstrNa 会提示临时开启 DEBUG/文件日志后复现。

GitHub Token 是可选的。留空时只能生成草稿，不能自动提交。若要自动提交，建议使用 GitHub Fine-grained Personal Access Token，只给目标仓库 Issues: Read and write；如果目标仓库是私有仓库且需要读取 Issue 模板，再给 Contents: Read。

LLM 并发工具调用

这是 1.5.3 新增的功能，升级后默认关闭。先在 AstrBot 原生插件配置页打开主开关，再前往 AstrNa Dashboard → LLM 并发工具调用 → 功能设置，按插件、MCP 服务或 AstrBot 内置来源逐项选择适合并发的工具。只有主开关已开启且名单非空时，AstrNa 才会注册 astrna_parallel_tool_use 批量入口；名单清空或主开关关闭后会立即卸载。

允许名单只表示“管理员认为这个工具适合并发”，不代表给普通成员发放新权限。每个子调用真正执行前，都必须同时满足两层条件：工具存在于当前请求本来可以使用的真实 ToolSet 中，并且名称位于 AstrNa 的并发允许名单中。AstrBot 的管理员权限、人格工具选择、会话插件开关、内置功能开关和工具停用状态继续生效；任意一层不通过都会只返回该项失败，不会执行工具。

工具选择器支持来源分组的全选、全不选和半选状态；“全选”保存的是当时每个具体工具名，不保存通配符，因此以后新安装的工具默认不会自动获得并发资格。已卸载、改名、停用或后来变成禁止类型的已选项会保留为失效项，方便管理员看见并移除，但永远不能执行。

安全与限制：

• 单次批量调用上限为 8 项（MAX_PARALLEL_TOOL_CALLS = 8）。
• 只选择互不依赖、主要返回数据、不会直接操纵聊天或共享状态的工具；后一个调用需要前一个结果时必须拆成两批。
• astrna_parallel_tool_use 自身、send_message_to_user、Handoff 和后台任务永远禁止加入并发名单。
• 多个插件、MCP 或 AstrBot 内置工具共用同一个工具名时，该名称会标记为歧义项并拒绝并发，避免管理员选择的工具与运行时实际对象不一致。
• 完全相同的工具名与参数不能在同一批重复提交，避免有副作用的工具被执行两次。
• 内部使用 asyncio.gather 真正并行执行，并按提交顺序返回逐项 recipient_name / ok / result；单项异常和超时不会抹掉其他项的结果。
• 每个子工具继续走 AstrBot 原执行器、参数过滤、权限复核和 on_tool_start / on_tool_end 钩子。
• 单项超时按该工具从开始到结束的总时长计算（AstrBot 原生逐段等待是每等下一段结果单独计时，批量模式更严格）；超时上限沿用 AstrBot 的 tool_call_timeout。
• /stop 和外层 Agent 任务取消都会传播到并发批次：整批子调用会被一并取消并回收，不会留下继续运行的子工具；但 AstrBot 原生单工具在外层取消时本身可能残留后台任务，那是上游行为，与本功能无关。
• 多段文本会全部聚合；图片和文本/图片资源会保留在外层 CallToolResult 中，继续交给 AstrBot 原生图片缓存与大结果落盘流程处理。空结果或只有不支持内容时会明确标记失败，不会伪装成功。

兼容性

AstrNa 主要面向 AstrBot 当前 4.x 版本。当前正式版 1.5.10 已在 AstrBot 4.28.0-beta.1 源码环境中完成回归验证。

部分能力依赖平台：

• 群成员身份、群等级、专属头衔、生日查询依赖 NapCat / aiocqhttp 可查询到对应信息。
• DeepSeek V4 400 修复主要作用于 OpenAI compatible provider 路径。
• 图像转述优化依赖 AstrBot 自带图片转述模型。
• 图片历史上下文优化只清理 conversation history 中的 data:image/...;base64 图片块，不会改动当前请求的 req.image_urls。
• 工具调用历史上下文优化只压缩已闭合工具事务的历史 tool.content；保留工具调用配对和最终回答，不处理当前 Agent Loop，也不移除每轮固定工具定义 schema。
• LLM 并发工具调用依赖 AstrBot 的真实请求 ToolSet、权限包装、Runner 钩子和原生工具执行器，同步（4.27.2）与异步（4.27.3 起）权限检查接口均已适配；允许名单不扩大当前会话权限范围，其他版本若更改这些内部入口会自动拒绝安装或拒绝执行。
• 引用图片视觉输入优化依赖 AstrBot 自带引用图片解析能力；AstrNa 会兼容 NapCat / aiocqhttp 下 bot.call_action 的取图方式，并在当前 Reply 本地临时图片路径失效时尝试通过 OneBot 接口重新取图，只补当前 Reply 引用图片，可能增加本轮图片 token。
• 回复历史标记依赖平台提供可靠的引用消息发送者信息；QQ 官方 Bot 当前引用消息缺少这个字段，无法安全区分被引用消息发送者和当前发言人，因此不支持该平台的引用回复指向优化。
• 合并转发相关优化依赖 AstrBot 或输出插件使用标准 Node / Nodes 消息组件；OutputPro 生成的标准合并转发也会进入发送失败自适应拆包重试。
• 群聊上下文优化依赖 AstrBot 自带群聊上下文感知和已配置的聊天模型供应商。AstrBot 4.27.4 起支持 JSON 卡片进入群聊上下文；在部分平台上，纯 JSON 卡片没有 message_str，主动回复可能被 AstrBot 上游的空 prompt 守卫静默跳过，但卡片仍可记录并注入后续文本请求。
• 输出字数限制会包装 AstrBot 普通 LLM runner，只限制最终纯文本回复；开启后非白名单会话会关闭本轮流式输出，Live Mode 会保留流式并跳过限制。
• 群聊并发回复会同时覆盖 AstrBot 内置和第三方 Agent Runner：同会话 LLM 锁按群友拆分粒度，同群实际发送再按整轮串行；历史保存只合并可信新增轮次，保留 AstrBot 已完成的截断、压缩或总结；与消息防抖插件共存时会优先保留防抖语义。AstrBot 4.27.3 起 /stop 可在保持群友隔离的同时即时请求对应 Runner 停止；4.27.2 下保持事件停止标记语义，Runner 在下一检查点响应停止。
• 自动清理 AstrBot 缓存调用 AstrBot 原生 StorageCleaner.cleanup("cache")，只清理临时缓存，不清理日志；空闲检测覆盖主要 LLM 和发送链路，但不能感知所有第三方插件自己开的后台任务。
• 自定义开启 AstrBot 内置指令依赖 AstrBot 核心内置指令仍注册在 astrbot.builtin_stars.builtin_commands.main，只细化 Core 内置指令，不管理扩展指令插件。
• 自动报错分析与 Issue 助手依赖 AstrBot on_plugin_error hook、当前可用聊天模型和 GitHub REST API；不要求安装 GitHub CLI。

验证状态

最近版本发布前通过以下验证，当前已测试兼容 AstrBot 4.28.0-beta.1：

TMPDIR=/tmp PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q -s
TMPDIR=/tmp PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ASTRBOT_SOURCE_PATH=/root/projects/tmp/AstrBot python -m pytest -q -s
ruff check .
python -m compileall -q .
git diff --check

默认环境全量测试结果为 849 passed, 13 skipped；本次绑定 AstrBot 4.28.0-beta.1 源码运行全量测试结果为 862 passed（仅 1 条无关第三方弃用警告）。此前 v4.27.2 到 v4.27.4 的兼容结果已记录在历史发布说明中。v4.27.4 到 v4.28.0-beta.1 的变化中，AstrBot 将上下文轮次配置迁移到 Agent Runner 配置（agent_runner.config.compression.max_turns / trim_turns）并移除旧键，本次已适配该迁移；其余 Agent、发送、唤醒、消息事件、历史保存和工具链路入口未发现需要调整的运行时补丁。

设计原则

• 不修改 AstrBot Core。
• 所有能力默认关闭，按需启用。
• 查询不到或平台不支持时静默跳过，不影响主对话。
• 尽量只补充 Bot 需要理解上下文的信息，不主动扩大隐私暴露面。
• 与 AstrBot 原行为保持兼容，插件停用时恢复运行时补丁。