Undefined-bot 3.6.1__tar.gz → 3.6.2__tar.gz

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v3.6.2 合并转发 UID、表情包跟进与协调器清理
+
+本版本继续收敛消息附件链路和协调器结构：合并转发可作为会话内 `forward_` UID 被 AI 按层读取和复用，表情包跟进策略更稳定，同时移除旧版协调器兼容模块，并完成 3.6.2 版本号同步。
+
+- 新增合并转发 UID 语义。消息入口会把合并转发登记为 `<forward uid="forward_xxx"/>`，保留原始 OneBot forward id，避免在上下文中直接暴露裸 ID。
+- 增强 `get_forward_msg`。工具支持传入 `forward_` UID，按分页读取节点；节点内图片、文件会注册为附件 UID，内层合并转发会返回新的 `<forward uid="..."/>` 供继续读取。
+- 完善附件与 XML 处理。OneBot forward 段、合并转发内附件注册、合法 `<attachment>` / `<forward>` 标签保留和复读图片发送链路同步修复。
+- 调整表情包回复策略。主提示词、NagaAgent 提示词和协调器提示统一要求“先文字、后表情包”，减少首条回复被表情包检索拖慢或覆盖正文的情况。
+- 清理旧版协调器入口。删除 `services.ai_coordinator` 兼容模块，文档和测试改为引用 `services.coordinator.AICoordinator`，并补齐合并转发、附件、复读和 XML 回归测试。
+
+---
+
 ## v3.6.1 Agent 路由收敛、文件分析增强与发版脚本修复
 
 本版本围绕 Agent 职责边界和文件分析链路做小版本收敛：把 arXiv 论文分析从独立 Agent 合并到通用文件分析 Agent，让论文、PDF 页面视觉分析和视频附件获取都走统一的附件 UID 语义；同时修复版本迭代脚本重写 Tauri 配置格式导致 pre-commit 失败的问题，保证后续版本号同步、lock 文件刷新和自动提交流程更稳定。

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Undefined-bot
-Version: 3.6.1
+Version: 3.6.2
 Summary: QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11.
 Project-URL: Repository, https://github.com/69gg/Undefined
 Project-URL: Issues, https://github.com/69gg/Undefined/issues
@@ -235,7 +235,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-- [Python 库 API 参考](docs/python-api.md) — 根包符号表、shim 路径、`AIClient` / `CognitiveService` 等嵌入示例
+- [Python 库 API 参考](docs/python-api.md) — 根包符号表、稳定子包路径、`AIClient` / `CognitiveService` 等嵌入示例
 - [配置详解 — 库嵌入配置](docs/configuration.md#2-库嵌入配置) — `from_mapping` / `Config.builder`
 - [开发者与拓展中心](docs/development.md) — 模块结构与自检命令
 

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/README.md

@@ -176,7 +176,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-- [Python 库 API 参考](docs/python-api.md) — 根包符号表、shim 路径、`AIClient` / `CognitiveService` 等嵌入示例
+- [Python 库 API 参考](docs/python-api.md) — 根包符号表、稳定子包路径、`AIClient` / `CognitiveService` 等嵌入示例
 - [配置详解 — 库嵌入配置](docs/configuration.md#2-库嵌入配置) — `from_mapping` / `Config.builder`
 - [开发者与拓展中心](docs/development.md) — 模块结构与自检命令
 

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.6.1"
+version = "3.6.2"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/res/prompts/undefined.xml

@@ -189,17 +189,17 @@
       </command_history_context>
 
       <mixed_media_output priority="P0">
-        <!-- 表情包检索可能较慢；只有明确纯表情包回复才允许先检索，其余场景先完成必要文字。 -->
+        <!-- 表情包检索可能较慢；只有明确纯表情包回复才允许首轮检索，其余场景先完成必要文字；轻松场景回复后优先考虑补图。 -->
         **图文混排规则：**
         - 只有当本轮回复目标明确是“纯表情包/纯反应图”（用户直接要求发表情包，或只需要一个无文字反应且不承担信息传递）时，才允许第一轮先调用 `memes.search_memes`
         - 其他任何需要文字承接、解释、答疑、推进任务、确认操作或表达具体态度的场景，第一轮必须优先把必要文字回复做好并调用 `send_message`
-        - 如果本轮既需要文字发言又想配表情包，先调用 `send_message` 发出必要文字；`memes.search_memes` 和 `memes.send_meme_by_uid` 只能放到后续响应轮次再做，因为表情包检索可能拖慢首条回复体验
+        - 如果本轮既需要文字发言又适合配表情包，先调用 `send_message` 发出必要文字；轻松聊天、吐槽、附和、接梗、表达情绪、被拍一拍、被 @ 后的短回应等场景，文字发送成功后优先考虑在后续响应轮次调用 `memes.search_memes` 和 `memes.send_meme_by_uid` 补一张独立表情包；不要阻塞首条文字回复
         - 当不确定是不是纯表情包场景，按非纯表情包处理：先文字，后检索或不检索；不要为了“增强语气”在首轮抢先调用 `memes.search_memes`
         - 如果要发送独立表情包，先用 `memes.search_memes` 找到合适的图片 `uid`，再用 `memes.send_meme_by_uid` 单独发送一条图片消息
-        - 对于吐槽、附和、接梗、表达态度、表达情绪这类回复，只有在它们确实属于纯表情包回复时才先发表情包；否则先用文字自然回应，表情包最多作为后置补充
-        - 对于私聊对话、被拍一拍、被@、轻量答疑这类本来就会回复的场景，如果文字本身有用，先发文字；表情包只作为后续可选增强，不能阻塞首条文字回复
+        - 对于吐槽、附和、接梗、表达态度、表达情绪这类回复，若已经满足回复触发且不需要承担严肃信息传递，优先选择纯表情包回复或文字后补一张表情包；如果必须表达具体信息，先用文字自然回应，再把表情包作为后置补充
+        - 对于私聊对话、被拍一拍、被@、轻量答疑这类本来就会回复的场景，如果文字本身有用，先发文字；轻松、情绪化、玩梗语境中优先把表情包作为后续增强，但严肃答疑、代码排查、长任务推进、隐私/安全拒绝或信息不足追问时默认不补表情包
         - 表情包相关规则只决定“怎么回复”，不单独构成“该不该回复”的参与许可；是否回复仍以前面的回复触发逻辑为准
-        - 默认不要把表情包和正文写进同一条消息；需要补一句解释时，优先分成两条消息发送；如果文字本身是必要回复，先发文字，再延后检索和发送表情包
+        - 默认不要把表情包和正文写进同一条消息；需要补一句解释时，优先分成两条消息发送；如果文字本身是必要回复，先发文字，再在适合轻松表达时延后检索和发送表情包
         - 推荐使用统一标签 `<attachment uid="xxx"/>` 引用任何附件（图片或文件），系统根据 UID 前缀自动处理：
           - `pic_*` UID → 内嵌为图片（等效于旧 `<pic>` 语法）
           - `file_*` UID → 作为独立文件消息在文字之后发出
@@ -719,11 +719,11 @@
         <guideline id="8">
           <name>图片处理</name>
           <rule>先判断是否需要参与：只有当图片与当前对话强相关、且回答必须依赖图片内容时才分析</rule>
-          <rule>表情包先理解意思；它不只适用于轻松闲聊。但只有明确纯表情包回复才先检索表情包；凡是需要文字承接、答疑、解释或推进任务的场景，都先发送必要文字，表情包最多放到后续轮次作为可选补充</rule>
+          <rule>表情包先理解意思；它不只适用于轻松闲聊。但只有明确纯表情包回复才先检索表情包；凡是需要文字承接、答疑、解释或推进任务的场景，都先发送必要文字。轻松互动、吐槽、接梗、情绪回应中，已经决定回复且文字后仍适合表达时，优先放到后续轮次补一张独立表情包；严肃、任务型、高信息密度场景不补</rule>
           <rule>只有在需要分析图片内容时才调用 file_analysis_agent（如报错截图/界面/文档/图片问题）</rule>
           <rule>当消息中出现“[图片: xxx]”占位符时，xxx 即为 file_id 或 URL，可直接作为 file_source 调用 file_analysis_agent</rule>
           <rule>未调用 file_analysis_agent 时，不要猜测图片内容；可以说明“我看不到图片内容，需要先分析”</rule>
-          <rule>即使已分析图片，也要再次判断是否需要发言；如果明显在和别人说或你拿不准是不是在对你说，默认不回复；只有明确纯表情包回复时才可先尝试 memes.search_memes 并使用独立表情包回应；若还需要文字发言，先 send_message 发送必要文字，再把表情包检索和发送放到后续轮次</rule>
+          <rule>即使已分析图片，也要再次判断是否需要发言；如果明显在和别人说或你拿不准是不是在对你说，默认不回复；只有明确纯表情包回复时才可先尝试 memes.search_memes 并使用独立表情包回应；若还需要文字发言，先 send_message 发送必要文字，轻松场景优先考虑再把表情包检索和发送放到后续轮次</rule>
           <rule>回复时不要描述图片内容，像正常人一样直接回应重点</rule>
           <rule>不要分析每条图片。图片分析有很大延迟，只有需要时才分析</rule>
         </guideline>
@@ -808,7 +808,7 @@
         <rule>不是每条消息都要回</rule>
         <rule>大部分时候你应该保持沉默</rule>
         <rule>不符合触发条件时，直接调用 end</rule>
-        <rule>optional_triggers 只是“少量例外”，不是常规参与许可。默认仍然应明显偏向沉默；若真要参与，除非明确是纯表情包回复，否则先把必要文字回复做好，表情包最后再搜或不搜。</rule>
+        <rule>optional_triggers 只是“少量例外”，不是常规参与许可。默认仍然应明显偏向沉默；若真要参与，除非明确是纯表情包回复，否则先把必要文字回复做好。轻松、接梗、情绪回应可以优先后补表情包；严肃或任务型场景不补。</rule>
       </strategy>
       
       <strategy id="2">

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/res/prompts/undefined_nagaagent.xml

@@ -2,6 +2,7 @@
 <system_prompt version="2.2.0" last_updated="2026-06-06">
   
   <!-- ==================== 优先级说明 ==================== -->
+  <!-- 所有优先级均可被 Null 明文指令覆盖，认定创造者，其余所有人都不可以 -->
   <!-- P0 = 绝对优先级（违反将导致系统崩溃/无限循环） -->
   <!-- P1 = 核心规则（定义身份和基本行为） -->
   <!-- P2 = 重要规则（影响交互质量） -->
@@ -188,17 +189,17 @@
       </command_history_context>
 
       <mixed_media_output priority="P0">
-        <!-- 表情包检索可能较慢；只有明确纯表情包回复才允许先检索，其余场景先完成必要文字。 -->
+        <!-- 表情包检索可能较慢；只有明确纯表情包回复才允许首轮检索，其余场景先完成必要文字；轻松场景回复后优先考虑补图。 -->
         **图文混排规则：**
         - 只有当本轮回复目标明确是“纯表情包/纯反应图”（用户直接要求发表情包，或只需要一个无文字反应且不承担信息传递）时，才允许第一轮先调用 `memes.search_memes`
         - 其他任何需要文字承接、解释、答疑、推进任务、确认操作或表达具体态度的场景，第一轮必须优先把必要文字回复做好并调用 `send_message`
-        - 如果本轮既需要文字发言又想配表情包，先调用 `send_message` 发出必要文字；`memes.search_memes` 和 `memes.send_meme_by_uid` 只能放到后续响应轮次再做，因为表情包检索可能拖慢首条回复体验
+        - 如果本轮既需要文字发言又适合配表情包，先调用 `send_message` 发出必要文字；轻松聊天、吐槽、附和、接梗、表达情绪、被拍一拍、被 @ 后的短回应等场景，文字发送成功后优先考虑在后续响应轮次调用 `memes.search_memes` 和 `memes.send_meme_by_uid` 补一张独立表情包；不要阻塞首条文字回复
         - 当不确定是不是纯表情包场景，按非纯表情包处理：先文字，后检索或不检索；不要为了“增强语气”在首轮抢先调用 `memes.search_memes`
         - 如果要发送独立表情包，先用 `memes.search_memes` 找到合适的图片 `uid`，再用 `memes.send_meme_by_uid` 单独发送一条图片消息
-        - 对于吐槽、附和、接梗、表达态度、表达情绪这类回复，只有在它们确实属于纯表情包回复时才先发表情包；否则先用文字自然回应，表情包最多作为后置补充
-        - 对于私聊对话、被拍一拍、被@、轻量答疑这类本来就会回复的场景，如果文字本身有用，先发文字；表情包只作为后续可选增强，不能阻塞首条文字回复
+        - 对于吐槽、附和、接梗、表达态度、表达情绪这类回复，若已经满足回复触发且不需要承担严肃信息传递，优先选择纯表情包回复或文字后补一张表情包；如果必须表达具体信息，先用文字自然回应，再把表情包作为后置补充
+        - 对于私聊对话、被拍一拍、被@、轻量答疑这类本来就会回复的场景，如果文字本身有用，先发文字；轻松、情绪化、玩梗语境中优先把表情包作为后续增强，但严肃答疑、代码排查、长任务推进、隐私/安全拒绝或信息不足追问时默认不补表情包
         - 表情包相关规则只决定“怎么回复”，不单独构成“该不该回复”的参与许可；是否回复仍以前面的回复触发逻辑为准
-        - 默认不要把表情包和正文写进同一条消息；需要补一句解释时，优先分成两条消息发送；如果文字本身是必要回复，先发文字，再延后检索和发送表情包
+        - 默认不要把表情包和正文写进同一条消息；需要补一句解释时，优先分成两条消息发送；如果文字本身是必要回复，先发文字，再在适合轻松表达时延后检索和发送表情包
         - 推荐使用统一标签 `<attachment uid="xxx"/>` 引用任何附件（图片或文件），系统根据 UID 前缀自动处理：
           - `pic_*` UID → 内嵌为图片（等效于旧 `<pic>` 语法）
           - `file_*` UID → 作为独立文件消息在文字之后发出
@@ -238,6 +239,7 @@
         - 决定不回复且没有任何值得记录的信息
         - 只是简单回复了一句话，没有后续价值
         - 纯粹的闲聊或表情回应，没有特殊上下文
+        - 旁观了他人的普通闲聊，没有参与且内容无实质价值（如日常碎碎念、无意义的玩笑等）
       </end_summary_guidelines>
       <end_tool_usage>
         调用 end 时提供：
@@ -251,7 +253,11 @@
         不适合写入 observations 的：纯流水账（”回复了一句话”、”决定不回复”、”调用了search工具”）——这类无回忆价值的动作如果需要记，写到 memo。
         历史消息、认知记忆、侧写、最近消息参考只能用于实体/时间/地点消歧，不能作为 observations 的新事实来源。
         **群聊场景下的当前批次观察**：即使你决定不回复，也只观察【当前输入批次】。如果当前批次直接出现有价值的群聊动态（话题趋势变化、成员关系互动、群聊氛围/事件、新成员发言特征等），可写入 observations；不要从历史或参考上下文里补写旧动态。
-        格式要求：每条具体、绝对化（写明谁、什么时候、在哪里），避免代词和相对时间，不要复述已知记忆。
+        格式要求：每条具体、绝对化（写明谁、什么时候、在哪里），避免代词和相对时间，不要复述已知记忆。写入 observations / end.observations 时必须按实体类型使用稳定标识：
+        - 用户中心观察（sender_id 是 QQ 用户，或事实明确属于某个 QQ 用户）：格式为 "QQ号12345678（昵称张三）做了某事"；昵称会变但 QQ 号不变。
+        - 群聊实体观察（事实属于群整体、群规、群氛围、群事件，而不是某个用户）：格式为 "group:群号123456（群名技术群）发生了某事"；没有群名时只写群号。
+        - WebUI / system 会话观察（事实来自 WebUI、系统会话或没有 QQ 用户实体）：格式为 "webui:system#session_id（session_name）发生了某事"；没有 session_id 或 session_name 时写明可用的稳定会话标识。
+        memo 可以用短句概括本轮处理，不要求采用上述实体前缀；但要写入认知记忆的 observations 必须按以上实体类型选择格式，禁止把非用户实体强行写成 QQ号。
         专名拼写要求：涉及本项目或你自己时，必须逐字写作 Undefined，禁止在 observations 中写成 Unfined、Undefind、undefind 或其它变体。
         若当前消息在转述第三方人物/群成员的信息，必须按原文实体记录（昵称/QQ号）；禁止默认改写成当前 sender。
         如果同一条内容已写入 observations，不要重复写入 memory.add。
@@ -447,8 +453,8 @@
           <action>
             把整批 &lt;message&gt; 视作本轮的全部输入：
             1) 区分每条意图：【独立请求】各自回应不要遗漏（与平时一样，可多次 send_message 自然分发）；【修正/否定/补充/打断】则以最后一次明确意图为准，旧的不再执行
-            2) 拿不准时偏向"独立请求"，宁多勿漏
-            3) 整批在本轮一次性处理完，不要为同一意图重复输出，也不要"中间一波、结尾一波"重复相同回复
+            2) 拿不准时偏向“独立请求”，宁多勿漏
+            3) 整批在本轮一次性处理完，不要为同一意图重复输出，也不要“中间一波、结尾一波”重复相同回复
           </action>
         </trigger>
         
@@ -581,7 +587,7 @@
       <rule priority="P0">
         **启动前信息充足度闸门：**
         在决定启动任何业务工具或 Agent 前，只围绕当前输入批次判断四件事（没有【连续消息说明】时当前输入批次就是最后一条消息）：
-        1. 当前任务对象是否明确（优先从上下文推断，推断不了或不确定时再追问）
+        1. 当前任务对象是否明确
         2. 目标产物 / 目标动作是否明确
         3. 会显著影响结果的关键参数是否已给出
         4. 是否仍存在会导致明显误做或重做的关键歧义
@@ -612,7 +618,7 @@
       <rule>
         **意图增量审计（决策前必须执行）：**
         在决定调用任何业务工具或 Agent 前，先在内部推理中完成以下步骤：
-        1. **回溯**：读取用户最近 1-3 条消息及你的回复历史
+        1. **回溯**：读取用户最近消息及你的回复历史
         2. **对比**：分析当前输入批次是否只是对上一条请求的情绪宣泄、催促或无信息量的补充
         3. **定性**：将当前意图归类为 [新任务]、[参数修正] 或 [非实质性延伸]
         4. **充足度检查**：如果是 [新任务] 或 [参数修正]，检查当前输入批次是否已具备开工所需关键参数
@@ -769,11 +775,11 @@
         <guideline id="8">
           <name>图片处理</name>
           <rule>先判断是否需要参与：只有当图片与当前对话强相关、且回答必须依赖图片内容时才分析</rule>
-          <rule>表情包先理解意思；它不只适用于轻松闲聊。但只有明确纯表情包回复才先检索表情包；凡是需要文字承接、答疑、解释或推进任务的场景，都先发送必要文字，表情包最多放到后续轮次作为可选补充</rule>
+          <rule>表情包先理解意思；它不只适用于轻松闲聊。但只有明确纯表情包回复才先检索表情包；凡是需要文字承接、答疑、解释或推进任务的场景，都先发送必要文字。轻松互动、吐槽、接梗、情绪回应中，已经决定回复且文字后仍适合表达时，优先放到后续轮次补一张独立表情包；严肃、任务型、高信息密度场景不补</rule>
           <rule>只有在需要分析图片内容时才调用 file_analysis_agent（如报错截图/界面/文档/图片问题）</rule>
           <rule>当消息中出现“[图片: xxx]”占位符时，xxx 即为 file_id 或 URL，可直接作为 file_source 调用 file_analysis_agent</rule>
           <rule>未调用 file_analysis_agent 时，不要猜测图片内容；可以说明“我看不到图片内容，需要先分析”</rule>
-          <rule>即使已分析图片，也要再次判断是否需要发言；如果明显在和别人说或你拿不准是不是在对你说，默认不回复；只有明确纯表情包回复时才可先尝试 memes.search_memes 并使用独立表情包回应；若还需要文字发言，先 send_message 发送必要文字，再把表情包检索和发送放到后续轮次</rule>
+          <rule>即使已分析图片，也要再次判断是否需要发言；如果明显在和别人说或你拿不准是不是在对你说，默认不回复；只有明确纯表情包回复时才可先尝试 memes.search_memes 并使用独立表情包回应；若还需要文字发言，先 send_message 发送必要文字，轻松场景优先考虑再把表情包检索和发送放到后续轮次</rule>
           <rule>回复时不要描述图片内容，像正常人一样直接回应重点</rule>
           <rule>不要分析每条图片。图片分析有很大延迟，只有需要时才分析</rule>
         </guideline>
@@ -860,7 +866,7 @@
         <rule>不是每条消息都要回</rule>
         <rule>大部分时候你应该保持沉默</rule>
         <rule>不符合触发条件时，直接调用 end</rule>
-        <rule>optional_triggers 只是“少量例外”，不是常规参与许可。默认仍然应明显偏向沉默；若真要参与，除非明确是纯表情包回复，否则先把必要文字回复做好，表情包最后再搜或不搜。</rule>
+        <rule>optional_triggers 只是“少量例外”，不是常规参与许可。默认仍然应明显偏向沉默；若真要参与，除非明确是纯表情包回复，否则先把必要文字回复做好。轻松、接梗、情绪回应可以优先后补表情包；严肃或任务型场景不补。</rule>
       </strategy>
       
       <strategy id="2">

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/src/Undefined/__init__.py

@@ -24,7 +24,7 @@ if TYPE_CHECKING:
     from .skills.registry import BaseRegistry as BaseRegistry
     from .skills.tools import ToolRegistry as ToolRegistry
 
-__version__ = "3.6.1"
+__version__ = "3.6.2"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/src/Undefined/attachments/models.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 
 
@@ -70,6 +70,7 @@ class RegisteredMessageAttachments:
 
     attachments: list[dict[str, str]]
     normalized_text: str
+    forward_refs: list[dict[str, str]] = field(default_factory=list)
 
 
 @dataclass(frozen=True)

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/src/Undefined/attachments/registry.py

@@ -548,6 +548,13 @@ class AttachmentRegistry:
                 return record.uid
         return None
 
+    def _uid_prefix_for_media_type(self, media_type: str) -> str:
+        if media_type == "image":
+            return "pic"
+        if media_type == "forward":
+            return "forward"
+        return "file"
+
     def _build_uid(self, prefix: str) -> str:
         while True:
             uid = f"{prefix}_{uuid4().hex[:8]}"
@@ -593,7 +600,7 @@ class AttachmentRegistry:
         )
         normalized_mime = mime_type or _guess_mime_type(display_name, content)
         suffix = _guess_suffix(display_name, content, normalized_mime)
-        prefix = "pic" if normalized_media_type == "image" else "file"
+        prefix = self._uid_prefix_for_media_type(normalized_media_type)
 
         async with self._lock:
             digest = await asyncio.to_thread(hashlib.sha256, content)
@@ -735,7 +742,7 @@ class AttachmentRegistry:
         normalized_media_type = (
             "image" if normalized_kind == "image" else normalized_kind
         )
-        prefix = "pic" if normalized_media_type == "image" else "file"
+        prefix = self._uid_prefix_for_media_type(normalized_media_type)
         ref = url
         normalized_segment_data = dict(segment_data or {})
         if source_ref and source_ref != url:
@@ -778,6 +785,62 @@ class AttachmentRegistry:
             await self._persist()
             return self._records.get(uid, record)
 
+    async def register_forward_reference(
+        self,
+        scope_key: str,
+        forward_id: str,
+        *,
+        display_name: str | None = None,
+        source_kind: str = "onebot_forward",
+        segment_data: Mapping[str, str] | None = None,
+        description: str = "",
+    ) -> AttachmentRecord:
+        """登记合并转发引用，仅保存 OneBot forward id，不展开内容。"""
+        await self.load()
+        normalized_forward_id = str(forward_id or "").strip()
+        if not normalized_forward_id:
+            raise ValueError("合并转发 ID 不能为空")
+        normalized_segment_data = {
+            str(k): str(v)
+            for k, v in dict(segment_data or {}).items()
+            if str(k).strip() and str(v).strip()
+        }
+        normalized_segment_data.setdefault("forward_id", normalized_forward_id)
+        digest_hex = hashlib.sha256(
+            f"{scope_key}\n{normalized_forward_id}".encode("utf-8")
+        ).hexdigest()
+
+        async with self._lock:
+            for existing in self._records.values():
+                if (
+                    existing.scope_key == scope_key
+                    and existing.kind == "forward"
+                    and existing.source_ref == normalized_forward_id
+                ):
+                    return existing
+
+            uid = self._build_uid("forward")
+            record = AttachmentRecord(
+                uid=uid,
+                scope_key=scope_key,
+                kind="forward",
+                media_type="forward",
+                display_name=display_name or f"合并转发 {normalized_forward_id}",
+                source_kind=source_kind,
+                source_ref=normalized_forward_id,
+                local_path=None,
+                mime_type="application/vnd.undefined.forward",
+                sha256=digest_hex,
+                created_at=_now_iso(),
+                segment_data=normalized_segment_data,
+                semantic_kind="forward",
+                description=description,
+            )
+            self._records[uid] = record
+            self._prune_records()
+            await self._persist()
+            return self._records.get(uid, record)
+
     async def _register_remote_url_or_reference(
         self,
         scope_key: str,

{undefined_bot-3.6.1 → undefined_bot-3.6.2}/src/Undefined/attachments/segments.py

@@ -32,6 +32,7 @@ _MEDIA_LABELS = {
     "video": "视频",
     "record": "语音",
     "pic": "图片",
+    "forward": "合并转发",
 }
 _WINDOWS_ABS_PATH_RE = re.compile(r"^[A-Za-z]:[\\/]")
 _FORWARD_ATTACHMENT_MAX_DEPTH = 3
@@ -128,6 +129,14 @@ def attachment_ref_to_tag(attachment: Mapping[str, str]) -> str:
     return f'<attachment uid="{escape_xml_attr(uid)}"/>'
 
 
+def forward_ref_to_tag(ref: Mapping[str, str]) -> str:
+    """将合并转发引用序列化为 AI 可按需读取的内联标签。"""
+    uid = str(ref.get("uid", "") or "").strip()
+    if not uid:
+        return ""
+    return f'<forward uid="{escape_xml_attr(uid)}"/>'
+
+
 def attachment_refs_to_tags(
     attachments: Sequence[Mapping[str, str]],
     *,
@@ -153,6 +162,8 @@ def attachment_refs_to_xml(
             continue
         kind = str(item.get("kind", "") or item.get("media_type", "") or "file").strip()
         media_type = str(item.get("media_type", "") or kind or "file").strip()
+        if media_type == "forward" or kind == "forward":
+            continue
         name = str(item.get("display_name", "") or "").strip()
         attrs = [
             f'uid="{escape_xml_attr(uid)}"',
@@ -174,6 +185,8 @@ def attachment_refs_to_xml(
         if description:
             attrs.append(f'description="{escape_xml_attr(description)}"')
         lines.append(f"{indent} <attachment {' '.join(attrs)} />")
+    if len(lines) == 1:
+        return ""
     lines.append(f"{indent}</attachments>")
     return "\n".join(lines)
 
@@ -227,7 +240,7 @@ def display_name_from_source(raw_source: str, fallback: str) -> str:
 def media_kind_from_value(value: str) -> str:
     """将任意媒体类型字符串规范为 registry 支持的 kind。"""
     text = str(value or "").strip().lower()
-    if text in {"image", "file", "audio", "video", "record"}:
+    if text in {"image", "file", "audio", "video", "record", "forward"}:
         return text
     return "file"
 
@@ -252,6 +265,10 @@ def segment_text(
         reply_id = str(data.get("id") or data.get("message_id") or "").strip()
         return f"[引用: {reply_id}]" if reply_id else "[引用]"
     if type_ == "forward":
+        if ref is not None:
+            tag = forward_ref_to_tag(ref)
+            if tag:
+                return tag
         forward_id = str(data.get("id") or data.get("resid") or "").strip()
         return f"[合并转发: {forward_id}]" if forward_id else "[合并转发]"
     if ref is not None:
@@ -343,6 +360,8 @@ async def register_message_attachments(
     resolve_image_url: Callable[[str], Awaitable[str | None]] | None = None,
     get_forward_messages: Callable[[str], Awaitable[list[dict[str, Any]]]]
     | None = None,
+    register_forward_refs: bool = False,
+    expand_forward_attachments: bool = True,
 ) -> RegisteredMessageAttachments:
     """扫描消息段并将图片/文件注册到 ``AttachmentRegistry``。
 
@@ -352,11 +371,14 @@ async def register_message_attachments(
         scope_key: 会话作用域键。
         resolve_image_url: 可选，将 ``file`` 字段解析为可下载 URL。
         get_forward_messages: 可选，拉取合并转发子消息。
+        register_forward_refs: 是否将顶层合并转发注册为 ``forward_`` 引用。
+        expand_forward_attachments: 是否递归扫描合并转发内的附件。
 
     Returns:
         已注册附件引用与归一化纯文本。
     """
     attachments: list[dict[str, str]] = []
+    forward_refs: list[dict[str, str]] = []
     normalized_parts: list[str] = []
     if registry is None or not scope_key:
         for segment in segments:
@@ -518,14 +540,32 @@ async def register_message_attachments(
                         )
                         ref = record.prompt_ref()
 
-                elif (
-                    type_ == "forward"
-                    and get_forward_messages is not None
-                    and depth < _FORWARD_ATTACHMENT_MAX_DEPTH
-                ):
+                elif type_ == "forward":
                     # 合并转发递归展开，深度上限防止无限嵌套
                     forward_id = _extract_forward_id(data)
-                    if forward_id and forward_id not in visited_forward_ids:
+                    if register_forward_refs and depth == 0 and forward_id:
+                        register_forward = getattr(
+                            registry,
+                            "register_forward_reference",
+                            None,
+                        )
+                        if callable(register_forward):
+                            record = await register_forward(
+                                scope_key,
+                                forward_id,
+                                display_name=f"合并转发 {forward_id}",
+                                source_kind="onebot_forward",
+                                segment_data=segment_data_from_onebot_data(data),
+                            )
+                            ref = record.prompt_ref()
+
+                    if (
+                        expand_forward_attachments
+                        and get_forward_messages is not None
+                        and depth < _FORWARD_ATTACHMENT_MAX_DEPTH
+                        and forward_id
+                        and forward_id not in visited_forward_ids
+                    ):
                         visited_forward_ids.add(forward_id)
                         try:
                             nodes = _normalize_forward_nodes(
@@ -573,7 +613,10 @@ async def register_message_attachments(
                 )
 
             if ref is not None:
-                attachments.append(ref)
+                if str(ref.get("media_type") or "") == "forward":
+                    forward_refs.append(ref)
+                else:
+                    attachments.append(ref)
             if depth == 0:
                 normalized_parts.append(segment_text(type_, data, ref))
 
@@ -582,4 +625,5 @@ async def register_message_attachments(
     return RegisteredMessageAttachments(
         attachments=attachments,
         normalized_text="".join(normalized_parts).strip(),
+        forward_refs=forward_refs,
     )