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

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

@@ -1,3 +1,16 @@
+## v3.6.3 合并转发快照、附件 UID 分析与 Release 下载说明
+
+本版本聚焦合并转发在协议端不可二次读取时的可用性：收到消息时先把可访问的转发树按会话保存为本地快照，后续工具读取优先复用快照，避免内层转发过期或回源失败导致 AI 看不到内容。同时补齐文件分析 Agent 对内部附件 UID 的直接解析能力，并澄清 Release 产物的下载选择。
+
+- 新增合并转发快照缓存。消息预处理阶段会递归保存当前可访问的合并转发树到 `data/cache/forward_snapshots/`，保留实时上下文中的 `<forward uid="..."/>` 语义；快照按会话隔离，并合并同一转发的并发抓取。
+- 改进 `messages.get_forward_msg`。工具支持 `forward_` UID 与原始 ID 优先读取本地快照，缺失时再回源 OneBot 并补写快照；协议端无法二次读取内层转发时，会返回明确诊断和可见原始字段，而不是只报空内容。
+- 修复合并转发当前轮上下文重复。Prompt 构建在剔除当前消息历史副本时优先匹配 `message_id`，避免历史中的递归展开文本与实时 `<forward uid="..."/>` 在同一轮重复注入。
+- 增强文件分析附件链路。`file_analysis_agent` 的 `analyze_multimodal` 可直接接收 `pic_` / `file_` UID，按当前会话作用域解析并本地化后再分析；Agent 提示同步明确不要改写或猜测附件 UID。
+- 澄清 Release 下载选择。README 与部署、构建、App 文档补充说明：部署 QQ Bot 通常不需要下载 Release 客户端安装包，Console / Chat 仅作为远程管理或原生聊天的可选组件。
+- 同步 3.6.3 版本号与测试覆盖。Python 包、Console、Chat、Tauri 与 lock 文件版本统一更新；新增合并转发快照、转发读取回退、多模态附件 UID 和当前消息去重回归测试。
+
+---
+
 ## v3.6.2 合并转发 UID、表情包跟进与协调器清理
 
 本版本继续收敛消息附件链路和协调器结构：合并转发可作为会话内 `forward_` UID 被 AI 按层读取和复用，表情包跟进策略更稳定，同时移除旧版协调器兼容模块，并完成 3.6.2 版本号同步。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Undefined-bot
-Version: 3.6.2
+Version: 3.6.3
 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
@@ -88,6 +88,32 @@ Description-Content-Type: text/markdown
 
 [点击添加官方实例QQ](https://qm.qq.com/q/cvjJoNysGA)
 
+## Release 下载速查
+
+如果只是部署和运行 QQ Bot，通常**不需要**在 GitHub Release 的 Assets 里下载任何文件。推荐按下方[快速开始](#-快速开始-源码模式)使用源码部署；只想快速体验命令行入口时，可使用 `pip install -U Undefined-bot` 或 `uv tool install Undefined-bot`。
+
+Release 里的安装包是可选组件，不是 Bot 服务本体：
+
+| 目标 | 是否需要下载 Release | 选择 |
+| --- | --- | --- |
+| 部署 / 运行 QQ Bot | 不需要 | 源码部署，启动 `uv run Undefined-webui`；或使用 `pip` / `uv tool` 安装 Python 包 |
+| 远程管理已有实例 | 可选 | `Undefined-Console-*`，用于连接 Management API 并打开远程 WebUI |
+| 使用原生聊天客户端 | 可选 | `Undefined-Chat-*`，用于连接 Runtime API 聊天 |
+| 离线安装 / 镜像缓存 Python 包 | 可选 | `undefined_bot-*.whl` 或 `undefined_bot-*.tar.gz` |
+
+平台文件选择：
+
+| 平台 | 推荐下载 |
+| --- | --- |
+| Windows x64 | `*-windows-x64-setup.exe`；批量部署或系统管理场景可选 `.msi` |
+| macOS Apple Silicon | `*-macos-arm64.dmg` |
+| macOS Intel | `*-macos-x64.dmg` |
+| Debian / Ubuntu | `*.deb` |
+| 其他 Linux x64 | `*.AppImage` |
+| Android 常见手机 / 平板 | `*-android-arm64-v8a-release.apk`；旧 32 位设备选 `armeabi-v7a`，模拟器按需选 `x86_64` / `x86` |
+
+Console 和 Chat 都需要连接到已经运行的 Undefined 服务。首次部署请先启动 `Undefined-webui`，完成配置和 Bot 启动后，再按需使用这些客户端连接。
+
 ## ⚡ 核心特性
 
 - **Skills 架构**：全新设计的技能系统，将基础工具（Tools）与智能代理（Agents）分层管理，支持自动发现与注册。
@@ -185,7 +211,7 @@ uv run Undefined-webui
 # cp config.toml.example config.toml
 ```
 
-> 浏览器是默认入口；如果你下载了 Release 中的桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
+> 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
 
 ---
 

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

@@ -29,6 +29,32 @@
 
 [点击添加官方实例QQ](https://qm.qq.com/q/cvjJoNysGA)
 
+## Release 下载速查
+
+如果只是部署和运行 QQ Bot，通常**不需要**在 GitHub Release 的 Assets 里下载任何文件。推荐按下方[快速开始](#-快速开始-源码模式)使用源码部署；只想快速体验命令行入口时，可使用 `pip install -U Undefined-bot` 或 `uv tool install Undefined-bot`。
+
+Release 里的安装包是可选组件，不是 Bot 服务本体：
+
+| 目标 | 是否需要下载 Release | 选择 |
+| --- | --- | --- |
+| 部署 / 运行 QQ Bot | 不需要 | 源码部署，启动 `uv run Undefined-webui`；或使用 `pip` / `uv tool` 安装 Python 包 |
+| 远程管理已有实例 | 可选 | `Undefined-Console-*`，用于连接 Management API 并打开远程 WebUI |
+| 使用原生聊天客户端 | 可选 | `Undefined-Chat-*`，用于连接 Runtime API 聊天 |
+| 离线安装 / 镜像缓存 Python 包 | 可选 | `undefined_bot-*.whl` 或 `undefined_bot-*.tar.gz` |
+
+平台文件选择：
+
+| 平台 | 推荐下载 |
+| --- | --- |
+| Windows x64 | `*-windows-x64-setup.exe`；批量部署或系统管理场景可选 `.msi` |
+| macOS Apple Silicon | `*-macos-arm64.dmg` |
+| macOS Intel | `*-macos-x64.dmg` |
+| Debian / Ubuntu | `*.deb` |
+| 其他 Linux x64 | `*.AppImage` |
+| Android 常见手机 / 平板 | `*-android-arm64-v8a-release.apk`；旧 32 位设备选 `armeabi-v7a`，模拟器按需选 `x86_64` / `x86` |
+
+Console 和 Chat 都需要连接到已经运行的 Undefined 服务。首次部署请先启动 `Undefined-webui`，完成配置和 Bot 启动后，再按需使用这些客户端连接。
+
 ## ⚡ 核心特性
 
 - **Skills 架构**：全新设计的技能系统，将基础工具（Tools）与智能代理（Agents）分层管理，支持自动发现与注册。
@@ -126,7 +152,7 @@ uv run Undefined-webui
 # cp config.toml.example config.toml
 ```
 
-> 浏览器是默认入口；如果你下载了 Release 中的桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
+> 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
 
 ---
 

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

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

{undefined_bot-3.6.2 → undefined_bot-3.6.3}/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.2"
+__version__ = "3.6.3"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

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

@@ -10,6 +10,11 @@ from Undefined.attachments.models import (
     RegisteredMessageAttachments,
     RenderedRichMessage,
 )
+from Undefined.attachments.forward_snapshot import (
+    load_forward_snapshot,
+    save_forward_snapshot,
+    snapshot_forward_tree,
+)
 from Undefined.attachments.registry import AttachmentRegistry
 from Undefined.attachments.render import (
     dispatch_pending_file_sends,
@@ -40,8 +45,11 @@ __all__ = [
     "attachment_refs_to_xml",
     "build_attachment_scope",
     "dispatch_pending_file_sends",
+    "load_forward_snapshot",
     "register_message_attachments",
     "render_message_with_attachments",
     "render_message_with_pic_placeholders",
+    "save_forward_snapshot",
     "scope_from_context",
+    "snapshot_forward_tree",
 ]

undefined_bot-3.6.3/src/Undefined/attachments/forward_snapshot.py

@@ -0,0 +1,286 @@
+"""合并转发节点快照缓存。
+
+OneBot 协议端可能只允许在收到外层合并转发时读取内层内容；之后再用
+内层 ID 调 ``get_forward_msg`` 可能返回空。这里按会话作用域保存已见节点，
+供 ``messages.get_forward_msg`` 在协议端不可回源时回退。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+import hashlib
+import logging
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Mapping
+
+from Undefined.utils import io
+from Undefined.utils.paths import FORWARD_SNAPSHOT_CACHE_DIR
+
+logger = logging.getLogger(__name__)
+
+_MAX_RECURSIVE_SNAPSHOT_DEPTH = 3
+_MAX_RECURSIVE_SNAPSHOT_NODES = 50
+_snapshot_locks: dict[str, asyncio.Lock] = {}
+_snapshot_lock_users: dict[str, int] = {}
+_snapshot_inflight: dict[str, asyncio.Task[None]] = {}
+
+
+def _snapshot_key(scope_key: str, forward_id: str) -> str:
+    payload = f"{scope_key}\n{forward_id}".encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _snapshot_path(scope_key: str, forward_id: str) -> Path:
+    return FORWARD_SNAPSHOT_CACHE_DIR / f"{_snapshot_key(scope_key, forward_id)}.json"
+
+
+def _snapshot_lock(scope_key: str, forward_id: str) -> tuple[str, asyncio.Lock]:
+    key = _snapshot_key(scope_key, forward_id)
+    lock = _snapshot_locks.get(key)
+    if lock is None:
+        lock = asyncio.Lock()
+        _snapshot_locks[key] = lock
+    _snapshot_lock_users[key] = _snapshot_lock_users.get(key, 0) + 1
+    return key, lock
+
+
+def _release_snapshot_lock(key: str, lock: asyncio.Lock) -> None:
+    users = _snapshot_lock_users.get(key, 0) - 1
+    if users > 0:
+        _snapshot_lock_users[key] = users
+        return
+    _snapshot_lock_users.pop(key, None)
+    if _snapshot_locks.get(key) is lock and not lock.locked():
+        _snapshot_locks.pop(key, None)
+
+
+def _clean_json_value(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, Mapping):
+        cleaned: dict[str, Any] = {}
+        for raw_key, raw_value in value.items():
+            key = str(raw_key).strip()
+            if not key:
+                continue
+            cleaned[key] = _clean_json_value(raw_value)
+        return cleaned
+    if isinstance(value, (list, tuple)):
+        return [_clean_json_value(item) for item in value]
+    return str(value)
+
+
+def normalize_forward_nodes_for_snapshot(nodes: Any) -> list[dict[str, Any]]:
+    """把 OneBot 返回的合并转发节点清洗为可持久化列表。"""
+    if isinstance(nodes, Mapping):
+        messages = nodes.get("messages")
+        raw_nodes = messages if isinstance(messages, list) else []
+    elif isinstance(nodes, list):
+        raw_nodes = nodes
+    else:
+        raw_nodes = []
+
+    cleaned_nodes: list[dict[str, Any]] = []
+    for node in raw_nodes:
+        if not isinstance(node, Mapping):
+            continue
+        cleaned = _clean_json_value(node)
+        if isinstance(cleaned, dict):
+            cleaned_nodes.append(cleaned)
+    return cleaned_nodes
+
+
+async def save_forward_snapshot(
+    *,
+    scope_key: str,
+    forward_id: str,
+    nodes: Any,
+) -> bool:
+    """保存合并转发节点快照；无有效节点时不写入。"""
+    normalized_scope = str(scope_key or "").strip()
+    normalized_forward_id = str(forward_id or "").strip()
+    if not normalized_scope or not normalized_forward_id:
+        return False
+
+    normalized_nodes = normalize_forward_nodes_for_snapshot(nodes)
+    if not normalized_nodes:
+        return False
+
+    payload = {
+        "scope_key": normalized_scope,
+        "forward_id": normalized_forward_id,
+        "created_at": datetime.now().isoformat(timespec="seconds"),
+        "nodes": normalized_nodes,
+    }
+    await io.write_json(
+        _snapshot_path(normalized_scope, normalized_forward_id),
+        payload,
+        use_lock=True,
+    )
+    return True
+
+
+async def load_forward_snapshot(
+    *,
+    scope_key: str,
+    forward_id: str,
+) -> list[dict[str, Any]]:
+    """读取合并转发节点快照；不存在或格式不符时返回空列表。"""
+    normalized_scope = str(scope_key or "").strip()
+    normalized_forward_id = str(forward_id or "").strip()
+    if not normalized_scope or not normalized_forward_id:
+        return []
+
+    raw = await io.read_json(
+        _snapshot_path(normalized_scope, normalized_forward_id),
+        use_lock=False,
+    )
+    if not isinstance(raw, Mapping):
+        return []
+    if str(raw.get("scope_key", "") or "") != normalized_scope:
+        return []
+    if str(raw.get("forward_id", "") or "") != normalized_forward_id:
+        return []
+    return normalize_forward_nodes_for_snapshot(raw.get("nodes"))
+
+
+def _extract_forward_id(data: Mapping[str, Any]) -> str:
+    forward_id = data.get("id") or data.get("resid") or data.get("message_id")
+    return str(forward_id).strip() if forward_id is not None else ""
+
+
+def _normalize_message_segments(message: Any) -> list[Mapping[str, Any]]:
+    if isinstance(message, list):
+        return [item for item in message if isinstance(item, Mapping)]
+    if isinstance(message, Mapping):
+        return [message]
+    if isinstance(message, str):
+        return [{"type": "text", "data": {"text": message}}]
+    return []
+
+
+def _iter_nested_forward_ids(nodes: list[dict[str, Any]]) -> list[str]:
+    forward_ids: list[str] = []
+    seen: set[str] = set()
+    for node in nodes:
+        raw_message = (
+            node.get("content") or node.get("message") or node.get("raw_message")
+        )
+        for segment in _normalize_message_segments(raw_message):
+            if str(segment.get("type", "") or "").strip().lower() != "forward":
+                continue
+            raw_data = segment.get("data", {})
+            data = raw_data if isinstance(raw_data, Mapping) else {}
+            forward_id = _extract_forward_id(data)
+            if forward_id and forward_id not in seen:
+                seen.add(forward_id)
+                forward_ids.append(forward_id)
+    return forward_ids
+
+
+async def snapshot_forward_tree(
+    *,
+    scope_key: str,
+    forward_id: str,
+    get_forward_messages: Callable[[str], Awaitable[Any]],
+    max_depth: int = _MAX_RECURSIVE_SNAPSHOT_DEPTH,
+    max_nodes: int = _MAX_RECURSIVE_SNAPSHOT_NODES,
+) -> None:
+    """递归抓取并保存当前可访问的合并转发树。
+
+    同一 ``scope_key + forward_id`` 在进程内会合并并发抓取，避免多个消息或
+    工具调用同时触发同一层 OneBot 请求。
+    """
+    normalized_scope = str(scope_key or "").strip()
+    normalized_forward_id = str(forward_id or "").strip()
+    if not normalized_scope or not normalized_forward_id:
+        return
+    if max_depth < 0 or max_nodes <= 0:
+        return
+
+    root_key = _snapshot_key(normalized_scope, normalized_forward_id)
+    inflight = _snapshot_inflight.get(root_key)
+    if inflight is not None and not inflight.done():
+        await asyncio.shield(inflight)
+        return
+
+    async def _run() -> None:
+        visited: set[str] = set()
+        remaining = max_nodes
+
+        async def _walk(current_forward_id: str, depth: int) -> None:
+            nonlocal remaining
+            normalized_current_id = str(current_forward_id or "").strip()
+            if not normalized_current_id:
+                return
+            if depth > max_depth or remaining <= 0:
+                return
+            if normalized_current_id in visited:
+                return
+            visited.add(normalized_current_id)
+            remaining -= 1
+
+            lock_key, lock = _snapshot_lock(normalized_scope, normalized_current_id)
+            try:
+                async with lock:
+                    nodes: list[dict[str, Any]] = []
+                    try:
+                        nodes = await load_forward_snapshot(
+                            scope_key=normalized_scope,
+                            forward_id=normalized_current_id,
+                        )
+                    except Exception:
+                        logger.debug(
+                            "读取合并转发快照失败，将尝试回源: id=%s",
+                            normalized_current_id,
+                            exc_info=True,
+                        )
+                    if not nodes:
+                        try:
+                            raw_nodes = await get_forward_messages(
+                                normalized_current_id
+                            )
+                        except Exception:
+                            logger.debug(
+                                "递归缓存合并转发失败: id=%s",
+                                normalized_current_id,
+                                exc_info=True,
+                            )
+                            return
+                        nodes = normalize_forward_nodes_for_snapshot(raw_nodes)
+                    if not nodes:
+                        return
+                    try:
+                        await save_forward_snapshot(
+                            scope_key=normalized_scope,
+                            forward_id=normalized_current_id,
+                            nodes=nodes,
+                        )
+                    except Exception:
+                        logger.debug(
+                            "写入合并转发快照失败: id=%s",
+                            normalized_current_id,
+                            exc_info=True,
+                        )
+            finally:
+                _release_snapshot_lock(lock_key, lock)
+
+            if depth >= max_depth:
+                return
+            for nested_forward_id in _iter_nested_forward_ids(nodes):
+                if remaining <= 0:
+                    break
+                await _walk(nested_forward_id, depth + 1)
+
+        await _walk(normalized_forward_id, 0)
+
+    task = asyncio.create_task(_run())
+    _snapshot_inflight[root_key] = task
+
+    def _forget(done: asyncio.Task[None]) -> None:
+        if _snapshot_inflight.get(root_key) is done:
+            _snapshot_inflight.pop(root_key, None)
+
+    task.add_done_callback(_forget)
+    await asyncio.shield(task)

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

@@ -16,6 +16,10 @@ from urllib.parse import unquote, urlsplit
 
 import httpx
 
+from Undefined.attachments.forward_snapshot import (
+    load_forward_snapshot,
+    snapshot_forward_tree,
+)
 from Undefined.attachments.models import RegisteredMessageAttachments
 from Undefined.utils.paths import WEBUI_FILE_CACHE_DIR
 from Undefined.utils.xml import escape_xml_attr
@@ -362,6 +366,8 @@ async def register_message_attachments(
     | None = None,
     register_forward_refs: bool = False,
     expand_forward_attachments: bool = True,
+    snapshot_forward_messages: bool = False,
+    snapshot_nested_forward_messages: bool = False,
 ) -> RegisteredMessageAttachments:
     """扫描消息段并将图片/文件注册到 ``AttachmentRegistry``。
 
@@ -373,6 +379,8 @@ async def register_message_attachments(
         get_forward_messages: 可选，拉取合并转发子消息。
         register_forward_refs: 是否将顶层合并转发注册为 ``forward_`` 引用。
         expand_forward_attachments: 是否递归扫描合并转发内的附件。
+        snapshot_forward_messages: 是否读取合并转发并递归缓存可访问的节点快照。
+        snapshot_nested_forward_messages: 向后兼容参数；递归缓存已覆盖内层转发。
 
     Returns:
         已注册附件引用与归一化纯文本。
@@ -392,6 +400,22 @@ async def register_message_attachments(
         )
 
     visited_forward_ids: set[str] = set()
+    should_snapshot_forward_messages = (
+        snapshot_forward_messages or snapshot_nested_forward_messages
+    )
+
+    async def _fetch_forward_nodes(forward_id: str) -> list[Mapping[str, Any]]:
+        if get_forward_messages is None:
+            return []
+        try:
+            return _normalize_forward_nodes(await get_forward_messages(forward_id))
+        except Exception as exc:
+            logger.debug(
+                "[AttachmentRegistry] forward resolver failed: id=%s err=%s",
+                forward_id,
+                exc,
+            )
+            return []
 
     async def _collect_from_segments(
         current_segments: Sequence[Mapping[str, Any]],
@@ -543,6 +567,7 @@ async def register_message_attachments(
                 elif type_ == "forward":
                     # 合并转发递归展开，深度上限防止无限嵌套
                     forward_id = _extract_forward_id(data)
+                    forward_nodes: Sequence[Mapping[str, Any]] = []
                     if register_forward_refs and depth == 0 and forward_id:
                         register_forward = getattr(
                             registry,
@@ -559,26 +584,56 @@ async def register_message_attachments(
                             )
                             ref = record.prompt_ref()
 
+                    should_fetch_forward = (
+                        get_forward_messages is not None
+                        and forward_id
+                        and forward_id not in visited_forward_ids
+                        and (
+                            should_snapshot_forward_messages
+                            or (
+                                expand_forward_attachments
+                                and depth < _FORWARD_ATTACHMENT_MAX_DEPTH
+                            )
+                        )
+                    )
+                    if should_fetch_forward:
+                        assert get_forward_messages is not None
+                        visited_forward_ids.add(forward_id)
+                        if should_snapshot_forward_messages:
+                            try:
+                                await snapshot_forward_tree(
+                                    scope_key=scope_key,
+                                    forward_id=forward_id,
+                                    get_forward_messages=get_forward_messages,
+                                )
+                            except Exception:
+                                logger.debug(
+                                    "[AttachmentRegistry] forward snapshot failed: id=%s",
+                                    forward_id,
+                                    exc_info=True,
+                                )
+                            forward_nodes = await load_forward_snapshot(
+                                scope_key=scope_key,
+                                forward_id=forward_id,
+                            )
+                            if not forward_nodes:
+                                forward_nodes = await _fetch_forward_nodes(forward_id)
+                        else:
+                            forward_nodes = await _fetch_forward_nodes(forward_id)
+
                     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(
-                                await get_forward_messages(forward_id)
-                            )
-                        except Exception as exc:
-                            logger.debug(
-                                "[AttachmentRegistry] forward resolver failed: id=%s err=%s",
-                                forward_id,
-                                exc,
-                            )
-                            nodes = []
-                        for node_index, node in enumerate(nodes):
+                        if not forward_nodes:
+                            if forward_id not in visited_forward_ids:
+                                visited_forward_ids.add(forward_id)
+                                forward_nodes = await _fetch_forward_nodes(forward_id)
+                        if not forward_nodes:
+                            continue
+                        for node_index, node in enumerate(forward_nodes):
                             raw_message = (
                                 node.get("content")
                                 or node.get("message")

{undefined_bot-3.6.2 → undefined_bot-3.6.3}/src/Undefined/handlers/message_flow.py

@@ -299,6 +299,7 @@ class MessageHandler(PokeMixin, RepeatMixin, AutoExtractMixin):
             else None,
             register_forward_refs=True,
             expand_forward_attachments=False,
+            snapshot_forward_messages=True,
         )
         attachments = result.attachments
         # 命中表情库时为 AI 上下文补充 [表情包] 描述

{undefined_bot-3.6.2 → undefined_bot-3.6.3}/src/Undefined/skills/agents/file_analysis_agent/README.md

@@ -12,6 +12,7 @@
 运行机制：
 - 由 `AgentRegistry` 自动发现并注册
 - 通过 `prompt` 输入任务描述并调用内部工具
+- 内部附件 UID（`pic_xxx` / `file_xxx`）由工具按当前会话作用域解析；多模态分析可直接传 UID，其他解析工具先用 `download_file` 转成本地路径
 - PDF 文字提取走 `extract_pdf`；扫描版、图表、版式或指定页码范围视觉分析走 `describe_pdf_page`
 
 开发提示：

{undefined_bot-3.6.2 → undefined_bot-3.6.3}/src/Undefined/skills/agents/file_analysis_agent/prompt.md

@@ -6,7 +6,7 @@
 - 超大文件、乱码、缺页、格式损坏或工具无法解析时，如实说明影响，并尽量给出已能提取的部分。
 
 附件输入规则：
-- 用户上下文里有内部附件 UID（如 `pic_xxx` / `file_xxx`）时，优先直接使用该 UID。
+- 用户上下文里有内部附件 UID（如 `pic_xxx` / `file_xxx`）时，优先使用该 UID，不要改写成文件名或 URL。
 - 没有内部 UID 时，才使用显式 URL、legacy `file_id`、arXiv 标识或 Bilibili 标识。
 - 不要臆造、改写或猜测附件 UID。
 
@@ -15,6 +15,7 @@
 - 如果文件源是 Bilibili BV 号、AV 号、B 站视频链接或 b23.tv 短链，先调用共享工具 `bilibili_video`，设置 `output_mode="uid"`，拿到 `<attachment uid="file_xxx"/>` 后再按普通视频 UID 下载和分析。
 - 已经给出内部附件 UID 时，不要再调用 arXiv/Bilibili 获取工具。
 - 根据用户目标选择合适工具：文本读取、文件类型检测、PDF/Office/表格/代码/压缩包/多模态分析都按内容类型处理。
+- `analyze_multimodal` 支持直接传入内部附件 UID；其他需要本地路径的工具应先调用 `download_file` 将 UID 转成本地临时文件路径。
 - PDF 文本和元数据优先用 `extract_pdf`；扫描版、图表、版式、公式图、截图式页面或用户指定页码时，用 `describe_pdf_page` 做逐页视觉分析。
 - `describe_pdf_page` 支持页码范围，例如 `3`、`3-5`、`3,5,8-10`；单次最多 5 页，范围过大时请缩小。
 - 对图片和多模态文件，重点报告客观可见信息，例如文字、UI、场景、人物、角色、应用/游戏名称和关键元素。