Undefined-bot 3.13.3__tar.gz → 3.14.0__tar.gz

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## v3.14.0 OneBot 本地文件三模式传输
+
+本版本为 Bot 本地文件新增统一传输层，支持 `local`、`url`、`stream` 三种发送方式并按投递快照热更新；默认保持 `local` 兼容旧部署，跨文件系统发送可显式启用 Runtime 临时链接或 NapCat Stream 分块上传。
+
+- 新增 `[onebot].file_send_mode`（`local` / `url` / `stream`）与 `[onebot].file_send_host`，环境变量为 `ONEBOT_FILE_SEND_MODE` / `ONEBOT_FILE_SEND_HOST`，WebUI 配置表单提供三种模式的下拉选择。两项均支持热更新，每次逻辑投递开始时取得独立快照，排队中与进行中的投递保持旧值。默认 `local`，旧配置及未显式指定模式的环境保持原有发送行为，`url` 和 `stream` 必须显式启用；`file_send_host` 仅用于 URL 模式，接受 IPv4、IPv6 或域名。
+- QQ 本地图片、语音、视频、文件与嵌套合并转发中的媒体统一经过新传输层，覆盖 CQ 字符串与消息段数组，文件消息段缺少 `name` 时自动补全文件名；已有 HTTP/HTTPS URL、Base64 和协议端资源标识原样通过，展示文件名、附件 UID 与历史来源保持不变。
+- `url` 模式复用 Runtime HTTP 监听，将本地文件复制为独立临时副本，新增 `GET` / `HEAD` `/api/v1/onebot/files/{file_id}?token=...` 路由：每个文件独立随机令牌、有效期 16 分钟、支持 Range 与重复读取；令牌只授权该文件，不能替代 `X-Undefined-API-Key` 调用其他 Runtime 接口；访问日志不记录查询串，正常停止清理本实例缓存，启动只回收本模块命名且已过期的遗留副本。删除源文件或切换发送模式不会提前使有效链接失效。
+- `stream` 模式通过既有 OneBot WebSocket 按 64 KiB 分块上传并逐块等待确认，完成后独立请求并校验协议端路径、大小与 SHA-256；同一 Bot 的 Stream 文件投递串行，纯文本不等待上传锁；失败只重置未完成的 Stream，不调用清空临时目录的接口；不支持零字节文件。协议端不支持扩展时明确报错并提示改用 `local` 或 `url`，不会静默回退。
+- 文件准备、实际发送与明确失败后的文件消息段回退共用 8 分钟预算，排队不计时；文件准备失败不计作已发送、不触发回退，也不会自动切换模式或重试上传。投递已发出但等待超时、被取消或连接中断时按结果未确认处理，禁止自动重发；`send_forward_msg` / `send_private_forward_msg` 纳入防重投递动作。
+- 文件上传失败的回退收敛到统一调用入口：仅协议端明确拒绝时才改用文件消息段，且回退请求同样经过传输层准备；`FileTransferError` 不再被私聊与群临时会话回退、附件派发和 Bilibili 发送链路吞掉，消息类工具把包含模式与阶段的可展示说明直接反馈给模型。
+- 加固日志与连接脱敏。WebSocket 客户端不再输出未经脱敏的 DEBUG 握手与原始帧，连接错误与 API 失败信息经脱敏后记录，新增 `chunk_data` 脱敏规则并修复脱敏替换未正确回填捕获组的问题；无法解析的消息只记录长度，接收循环停止时统一让挂起的请求失败退出，不再悬挂。
+
+---
+
 ## v3.13.3 回复精简、群活跃度统计与图片预览修复
 
 本版本减少对话中的重复解释，明确群成员活跃度统计的含义与数据范围，并修复 Chat 图片预览的键盘和焦点交互。

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Undefined-bot
-Version: 3.13.3
+Version: 3.14.0
 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

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/config.toml.example

@@ -73,6 +73,13 @@ ws_url = "ws://127.0.0.1:3001"
 # en: Access token (optional).
 token = ""
 
+# zh: 本地文件发送方式：local（共享路径，默认，兼容旧部署）/ url（Runtime 临时链接）/ stream（NapCat Stream API）。支持热更新。
+# en: Local file transport: local (shared paths, default for compatibility), url (temporary Runtime links), or stream (NapCat Stream API). Hot reload supported.
+file_send_mode = "local"
+# zh: 仅 URL 模式使用：OneBot 可访问的 Runtime 主机地址，支持 IPv4、IPv6 或域名，不包含协议、端口或路径；端口使用 Runtime 实际监听端口。
+# en: URL mode only: Runtime host reachable by OneBot, as IPv4, IPv6 or a domain without scheme, port or path. Uses the actual Runtime listening port.
+file_send_host = "127.0.0.1"
+
 [models]
 # zh: 对话模型配置（主模型，处理每一条消息）。
 # en: Chat model config (the main model, processing each message).

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/pyproject.toml

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

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

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/api/_openapi.py

@@ -18,6 +18,38 @@ def _build_openapi_spec(ctx: RuntimeAPIContext, request: web.Request) -> dict[st
     cfg = ctx.config_getter()
     naga_routes_enabled = _naga_routes_enabled(cfg, ctx.naga_store)
     paths: dict[str, Any] = {
+        "/api/v1/onebot/files/{file_id}": {
+            method: {
+                "summary": "Download a temporary OneBot file"
+                if method == "get"
+                else "Inspect a temporary OneBot file",
+                "description": "Process-internal registration only. A token authorizes one file for 16 minutes. Supports Range and repeated reads; does not authorize other Runtime APIs.",
+                "security": [{"OneBotFileToken": []}],
+                "parameters": [
+                    {
+                        "name": "file_id",
+                        "in": "path",
+                        "required": True,
+                        "schema": {"type": "string"},
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "File",
+                        "content": {
+                            "application/octet-stream": {
+                                "schema": {"type": "string", "format": "binary"}
+                            }
+                        },
+                    },
+                    "206": {"description": "Partial file"},
+                    "401": {"description": "Missing or invalid file token"},
+                    "404": {"description": "File missing or expired"},
+                    "416": {"description": "Invalid byte range"},
+                },
+            }
+            for method in ("get", "head")
+        },
         "/health": {
             "get": {
                 "summary": "Health check",
@@ -323,6 +355,7 @@ def _build_openapi_spec(ctx: RuntimeAPIContext, request: web.Request) -> dict[st
         ],
         "components": {
             "securitySchemes": {
+                "OneBotFileToken": {"type": "apiKey", "in": "query", "name": "token"},
                 "ApiKeyAuth": {
                     "type": "apiKey",
                     "in": "header",

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/api/app.py

@@ -15,6 +15,10 @@ from typing import Any, Awaitable, Callable
 from aiohttp import web
 from aiohttp.web_response import Response
 
+from Undefined.onebot.file_store import FILE_ROUTE, FILE_ROUTE_NAME, OneBotFileStore
+from Undefined.onebot.file_transport import OneBotFileTransport
+from .routes import onebot_files
+
 from ._context import RuntimeAPIContext
 from ._helpers import (
     _apply_cors_headers,
@@ -47,6 +51,8 @@ class RuntimeAPIServer:
         context: RuntimeAPIContext,
         host: str,
         port: int,
+        *,
+        file_store: OneBotFileStore | None = None,
     ) -> None:
         self._context = context
         self._host = host
@@ -56,21 +62,41 @@ class RuntimeAPIServer:
         self._background_tasks: set[asyncio.Task[Any]] = set()
         self._naga_state = NagaState()
         self._chat_job_manager = chat.ChatJobManager(context)
+        transport = getattr(context.onebot, "file_transport", None)
+        self._file_store = (
+            file_store
+            if file_store is not None
+            else (
+                transport.store if isinstance(transport, OneBotFileTransport) else None
+            )
+        )
 
     async def start(self) -> None:
         from Undefined.config.models import resolve_bind_hosts
 
         app = self._create_app()
-        self._runner = web.AppRunner(app)
-        await self._runner.setup()
-        for h in resolve_bind_hosts(self._host):
-            site = web.TCPSite(self._runner, host=h, port=self._port)
-            await site.start()
-            self._sites.append(site)
+        self._runner = web.AppRunner(
+            app, access_log_class=onebot_files.FileAccessLogger
+        )
+        try:
+            await self._runner.setup()
+            port = self._port
+            for h in resolve_bind_hosts(self._host):
+                site = web.TCPSite(self._runner, host=h, port=port)
+                await site.start()
+                self._sites.append(site)
+                port = int(self._runner.addresses[0][1])
+            if self._file_store is not None:
+                await self._file_store.start(port)
+        except BaseException:
+            await self.stop()
+            raise
         cfg = self._context.config_getter()
         logger.info("[RuntimeAPI] 已启动: %s", cfg.api.display_url)
 
     async def stop(self) -> None:
+        if self._file_store is not None:
+            self._file_store.unavailable()
         await self._chat_job_manager.stop()
 
         for task in self._background_tasks:
@@ -83,7 +109,12 @@ class RuntimeAPIServer:
             await self._runner.cleanup()
             logger.info("[RuntimeAPI] 已停止")
         self._runner = None
-        self._site = None
+        self._sites.clear()
+        if self._file_store is not None:
+            await self._file_store.stop()
+
+    async def _onebot_file_handler(self, request: web.Request) -> web.StreamResponse:
+        return await onebot_files.download(request, self._file_store)
 
     def _create_app(self) -> web.Application:
         @web.middleware
@@ -99,7 +130,9 @@ class RuntimeAPIServer:
             if request.path.startswith("/api/"):
                 cfg = self._context.config_getter()
                 is_naga_path = request.path.startswith("/api/v1/naga/")
-                skip_auth = is_naga_path and _naga_runtime_enabled(cfg)
+                skip_auth = (
+                    is_naga_path and _naga_runtime_enabled(cfg)
+                ) or onebot_files.is_file_request(request)
                 if not skip_auth:
                     expected = str(cfg.api.auth_key or "")
                     provided = request.headers.get(_AUTH_HEADER, "")
@@ -117,6 +150,7 @@ class RuntimeAPIServer:
             [
                 web.get("/health", self._health_handler),
                 web.get("/openapi.json", self._openapi_handler),
+                web.get(FILE_ROUTE, self._onebot_file_handler, name=FILE_ROUTE_NAME),
                 web.get("/api/v1/probes/internal", self._internal_probe_handler),
                 web.get("/api/v1/probes/external", self._external_probe_handler),
                 web.get("/api/v1/memory", self._memory_handler),

undefined_bot-3.14.0/src/Undefined/api/routes/onebot_files.py

@@ -0,0 +1,64 @@
+"""使用独立单文件令牌的 Runtime 下载路由。"""
+
+from urllib.parse import quote
+
+from aiohttp import web
+from aiohttp.web_log import AccessLogger
+
+from Undefined.onebot.file_store import (
+    FILE_ROUTE_NAME,
+    FileAuthorizationError,
+    OneBotFileStore,
+)
+
+
+class FileAccessLogger(AccessLogger):
+    """保留普通访问日志格式，专用文件路由只记录不带查询串的路径。"""
+
+    def log(
+        self, request: web.BaseRequest, response: web.StreamResponse, time: float
+    ) -> None:
+        if request.path.startswith("/api/v1/onebot/files/") or "token" in request.query:
+            self.logger.info(
+                "%s %s status=%d elapsed=%.3fs",
+                request.method,
+                request.path,
+                response.status,
+                time,
+            )
+        else:
+            super().log(request, response, time)
+
+
+def is_file_request(request: web.Request) -> bool:
+    return request.match_info.route.name == FILE_ROUTE_NAME and request.method in {
+        "GET",
+        "HEAD",
+    }
+
+
+async def download(
+    request: web.Request, store: OneBotFileStore | None
+) -> web.StreamResponse:
+    if store is None:
+        return web.Response(status=404)
+    try:
+        async with store.acquire(
+            request.match_info["file_id"], request.query.get("token", "")
+        ) as entry:
+            response = web.FileResponse(
+                entry.path,
+                headers={
+                    "Content-Type": entry.content_type,
+                    "Content-Disposition": f"attachment; filename*=UTF-8''{quote(entry.name, safe='')}",
+                    "Cache-Control": "private, no-store",
+                    "Referrer-Policy": "no-referrer",
+                    "X-Content-Type-Options": "nosniff",
+                },
+            )
+            # FileResponse 在 prepare 中发送文件，不能在仅构造响应后释放读者租约。
+            await response.prepare(request)
+            await response.write_eof()
+            return response
+    except FileAuthorizationError as exc:
+        return web.Response(status=exc.status)

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/attachments/render.py

@@ -301,6 +301,10 @@ async def dispatch_pending_file_sends(
                 continue
             dispatched_count += 1
         except Exception as exc:
+            if bool(getattr(exc, "file_transfer_error", False)):
+                # 携带失败前已成功派发数量，供调用方按部分成功处理，避免整批重发。
+                setattr(exc, "dispatched_file_count", dispatched_count)
+                raise
             if bool(getattr(exc, "delivery_uncertain", False)):
                 logger.warning(
                     "[文件发送] 投递结果未确认，停止继续派发以避免重复发送 "

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/bilibili/sender.py

@@ -398,6 +398,10 @@ async def send_bilibili_video(
 
     except Exception as exc:
         logger.exception("[Bilibili] 处理视频失败: %s", bvid)
+        if getattr(exc, "delivery_uncertain", False) or getattr(
+            exc, "file_transfer_error", False
+        ):
+            raise
         try:
             if video_info is None:
                 video_info = await get_video_info(bvid, cookie=cookie)

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/config/config_class.py

@@ -30,6 +30,7 @@ from .models import (
     WeixinConfig,
 )
 from .toml_io import _load_env, load_toml_data
+from .onebot import FileSendMode
 
 
 @dataclass
@@ -65,6 +66,8 @@ class Config:
     nagaagent_mode_enabled: bool
     onebot_ws_url: str
     onebot_token: str
+    onebot_file_send_mode: FileSendMode
+    onebot_file_send_host: str
     chat_model: ChatModelConfig
     vision_model: VisionModelConfig
     security_model_enabled: bool

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/config/env_registry.py

@@ -128,6 +128,8 @@ ENV_REGISTRY: Final[dict[tuple[str, ...], str]] = {
     ("messages", "use_proxy"): "MESSAGES_USE_PROXY",
     ("naga", "use_proxy"): "NAGA_USE_PROXY",
     ("onebot", "token"): "ONEBOT_TOKEN",
+    ("onebot", "file_send_mode"): "ONEBOT_FILE_SEND_MODE",
+    ("onebot", "file_send_host"): "ONEBOT_FILE_SEND_HOST",
     ("onebot", "ws_url"): "ONEBOT_WS_URL",
     ("render", "browser_executable_path"): "RENDER_BROWSER_EXECUTABLE_PATH",
     ("render", "long_image_default_padding"): "RENDER_LONG_IMAGE_DEFAULT_PADDING",

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/config/load_sections/core.py

@@ -16,6 +16,8 @@ from ..coercers import (
     _get_value,
 )
 
+from ..onebot import parse_file_send_host, parse_file_send_mode
+
 logger = logging.getLogger(__name__)
 
 
@@ -180,4 +182,10 @@ def load_core(
         "nagaagent_mode_enabled": nagaagent_mode_enabled,
         "onebot_ws_url": onebot_ws_url,
         "onebot_token": onebot_token,
+        "onebot_file_send_mode": parse_file_send_mode(
+            _get_value(data, ("onebot", "file_send_mode"), "ONEBOT_FILE_SEND_MODE")
+        ),
+        "onebot_file_send_host": parse_file_send_host(
+            _get_value(data, ("onebot", "file_send_host"), "ONEBOT_FILE_SEND_HOST")
+        ),
     }

undefined_bot-3.14.0/src/Undefined/config/onebot.py

@@ -0,0 +1,63 @@
+"""OneBot 本地文件传输配置与单次投递快照。"""
+
+from dataclasses import dataclass
+from ipaddress import ip_address
+import re
+from typing import Any, Literal, cast
+
+FileSendMode = Literal["local", "url", "stream"]
+DEFAULT_FILE_SEND_MODE: FileSendMode = "local"
+DEFAULT_FILE_SEND_HOST = "127.0.0.1"
+
+
+def parse_file_send_mode(value: Any) -> FileSendMode:
+    mode = (
+        str(value if value is not None else "").strip().lower()
+        or DEFAULT_FILE_SEND_MODE
+    )
+    if mode not in {"local", "url", "stream"}:
+        raise ValueError("onebot.file_send_mode 必须为 local、url 或 stream")
+    return cast(FileSendMode, mode)
+
+
+def parse_file_send_host(value: Any) -> str:
+    host = str(value or "").strip() or DEFAULT_FILE_SEND_HOST
+    if any(char in host for char in "/\\?#@%") or any(char.isspace() for char in host):
+        raise ValueError(
+            "onebot.file_send_host 必须为不带协议、端口、路径或作用域标识的主机地址"
+        )
+    if host.startswith("[") and host.endswith("]") and ":" in host:
+        host = host[1:-1]
+    try:
+        return str(ip_address(host))
+    except ValueError:
+        pass
+    try:
+        ascii_host = host.rstrip(".").encode("idna").decode("ascii")
+    except UnicodeError:
+        ascii_host = ""
+    if (
+        not ascii_host
+        or len(ascii_host) > 253
+        or any(
+            not re.fullmatch(r"[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?", label)
+            for label in ascii_host.split(".")
+        )
+    ):
+        raise ValueError(
+            "onebot.file_send_host 必须为 IPv4、IPv6 或域名，不包含协议、端口或路径"
+        )
+    return ascii_host
+
+
+@dataclass(frozen=True)
+class FileSendSettings:
+    mode: FileSendMode = DEFAULT_FILE_SEND_MODE
+    host: str = DEFAULT_FILE_SEND_HOST
+
+    @classmethod
+    def from_config(cls, config: Any) -> "FileSendSettings":
+        return cls(
+            parse_file_send_mode(getattr(config, "onebot_file_send_mode", None)),
+            parse_file_send_host(getattr(config, "onebot_file_send_host", None)),
+        )

{undefined_bot-3.13.3 → undefined_bot-3.14.0}/src/Undefined/main.py

@@ -183,7 +183,11 @@ async def main() -> None:
     _reranker: Any = None
     try:
         init_start = time.perf_counter()
-        onebot = OneBotClient(config.onebot_ws_url, config.onebot_token)
+        onebot = OneBotClient(
+            config.onebot_ws_url,
+            config.onebot_token,
+            config_getter=lambda: get_config(strict=False),
+        )
         memory_storage = MemoryStorage(max_memories=100)
         end_summary_storage = EndSummaryStorage()
         ai = AIClient(