Undefined-bot 3.17.0__tar.gz → 3.17.1__tar.gz

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/CHANGELOG.md

@@ -1,3 +1,18 @@
+## v3.17.1 交付体积边界收敛
+
+本版本收敛「内容一变大就发不出去」的两处交付边界：合并转发不再因为顶层节点塞满全文而被 QQ 拒收，长图不再因为页面自身更窄而右侧留白；同时补上图片消息段与 Agent 私有工具的静默丢失点。
+
+- 长图宽度自适应：`layout=long` 时 `width` 改为**上限**，渲染前探测页面自身布局宽度（`html` / `body` 盒宽与后代最大右边界），比设定宽度窄时把视口收缩到「内容宽度 + 2 × `padding`」（下限 320），两侧不再留白。只在页面自己更窄时收敛，铺满视口的响应式页面（含 Markdown 模板）宽度与旧版完全一致；探测失败只记日志并保持原视口，不影响渲染本身。`[render].long_image_default_width` 语义随之变为上限，缓存键补上收敛参数。
+- 合并转发预览收敛：NapCat packet 模式的转发卡片把**顶层节点**文本全部写进 `news` 预览，顶层文本量因此约等于卡片体积，约 14KB 会被 QQ 以 retcode=1200（`发送转发消息（res_id：… 失败`）拒收。`MessageSender` 在群聊与私聊发送前统一下沉：顶层直接文本合计超过 2000 字时，按文本量从大到小把节点内容改为 ≤1200 字的嵌套节点，嵌套节点段原样保留、不递归；发送被拒时以 error 级别记录节点数、顶层文本量、段数与图片数，便于定位。
+- Bilibili 图文正文改为按单节点 1200 字（`format.NODE_TEXT_BUDGET`）与单节点 9 张图切分，节点名形如 `正文 1/12`；正文超过一个节点时整体收进顶层 `正文` 节点的嵌套内容，让卡片体积与正文长度解耦，不再出现「图文越长越容易被拒收」。未超预算时仍是单个顶层 `正文` 节点，结构与旧版一致。
+- 图片消息段不再静默丢失：OneBot 图片段同时带 NapCat 的 `file` id 与可下载 `url`，先用 `get_image` 解析 `file`；解析失败或返回的既不是 HTTP URL 也不是本地路径时（典型是 NapCat 富媒体下载超时只给裸文件名），回落到段内 `url` 登记远程附件。
+- 修复 Agent 私有工具全部无法加载：随包技能的 handler 模块名一律以真实包根 `Undefined/skills` 计算，`agents/<agent>/tools/<tool>/handler.py` 不再被算成不存在的 `Undefined.skills.tools.<tool>`；此前这些工具会在注册阶段被记入 `load_error` 并从 schema 中排除。不随包的目录（测试或外部注入）保持原有上溯规则。
+- 裸数字不再误判为 Douyin aweme_id：只有不落在任何链接内的 16–25 位数字才算裸 ID，`bilibili.com/opus/933099353259638816` 这类链接里的数字不再让同一张图文链接同时触发抖音管线。
+- 部署后的首次启动改为手动：`uv run deploy up` 在 `container` 与 `host` 模式统一写入 `[webui].autostart_bot = false`，并在输出里给出「填配置 → NapCat 扫码 → WebUI 点启动机器人」的顺序，避免容器一起来就连不上未登录的协议端；文件发送同时从 `url` 改为 `stream`（`[onebot].file_send_mode = "stream"`），不再依赖共享发送目录或 Runtime 下载地址。
+- 文档重排：新增面向使用者的 [Docker 一键部署指南](docs/docker-deploy.md)（环境准备、向导选项、首次配置与 QQ 登录、远程访问、可选服务、日常管理与排查），README 与部署指南统一为「源码部署 → Docker 一键部署 → pip / uv tool」的推荐顺序，并补上镜像构建与维护说明。
+
+---
+
 ## v3.17.0 容器化一键部署
 
 本版本新增 `uv run deploy`：一条命令把本体、NapCat 与可选自托管服务编排成 Docker Compose，按部署模式自动对齐 `config.toml`、生成并复用凭据，最后输出全部管理入口与凭据；同时补上镜像的 CI 构建与多架构发布。

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Undefined-bot
-Version: 3.17.0
+Version: 3.17.1
 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
@@ -81,18 +81,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-## Release 下载速查
-
-**部署 QQ Bot 本身不需要下载 Release**：Release 里都是可选组件。源码部署见下方[快速开始](#-快速开始-源码模式)，安装包用途与平台对应如下：
-
-| 目标 | 文件 | 平台 |
-| --- | --- | --- |
-| 部署 / 运行 Bot | 不需要下载 Release；源码部署并启动 `uv run Undefined-webui` | 任意 |
-| 离线安装 / 镜像缓存 | `undefined_bot-*.whl` 或 `undefined_bot-*.tar.gz` | 任意 |
-| 远程管理已有实例 | `Undefined-Console-*`（连接 Management API 打开远程 WebUI） | Windows x64 `*-windows-x64-setup.exe`（批量部署可选 `.msi`）／macOS `*-macos-arm64.dmg`、`*-macos-x64.dmg`／Debian、Ubuntu `*.deb`／其他 Linux `*.AppImage` |
-| 原生聊天客户端 | `Undefined-Chat-*`（连接 Runtime API 聊天） | 同上；Android 为 `*-android-arm64-v8a-release.apk`（旧 32 位设备用 `armeabi-v7a`，模拟器按需 `x86_64` / `x86`） |
-
-Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请先启动 `Undefined-webui`，完成配置和 Bot 启动后再连接。
+> 🚀 **开始使用 Undefined**：从[快速开始](#-快速开始)了解部署步骤、首次配置和可选客户端的下载方式。
 
 ## ⚡ 核心特性
 
@@ -148,8 +137,8 @@ Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请
 
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
-- ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
-- 🐳 **[容器化一键部署](docs/docker-deploy.md)**：`uv run deploy` 一条命令拉起本体 + NapCat 与按需自托管服务（SearXNG / Firecrawl / lxmusic2api），含端口、凭据、模式选择与排查。
+- ⚙️ **[安装与部署指南](docs/deployment.md)**：首选源码部署；按源码、Docker、pip / uv tool 的推荐顺序介绍各安装方式。
+- 🐳 **[Docker 一键部署指南（Linux）](docs/docker-deploy.md)**：源码部署之外的推荐选择，自动部署 Undefined + NapCat，并按需添加搜索、音乐服务。
 - 📦 **[Python 库 API 参考](docs/python-api.md)**：根包 lazy re-export、`Config.from_mapping` / `set_config`、公共 API 符号表与嵌入示例。
 - 🖥️ **[WebUI 使用指南](docs/webui-guide.md)**：管理控制台功能一览——配置编辑、日志查看、认知记忆管理、表情包库、AI 对话与系统监控。
 - 🧭 **[Management API 与远程管理](docs/management-api.md)**：WebUI / App 共用的管理接口、认证、配置/日志/Bot 控制与引导探针说明。
@@ -176,11 +165,15 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 
 ---
 
-## ⚡ 快速开始 (源码模式)
+## ⚡ 快速开始
+
+推荐优先采用源码部署；希望在 Linux 上自动搭建 Undefined、NapCat 和可选服务时，也可以选择 Docker 一键部署。两种方式任选其一，部署完成后可直接使用 WebUI，也可按本节末尾的说明下载独立客户端。
 
-> 👶 **新手必看**：如果您是首次部署此类项目或不熟悉 Git/环境配置，**强烈建议直接前往 [《详细安装与部署指南》](docs/deployment.md)** 阅读手把手教程，避免遇到常见报错。
+<a id="-快速开始-源码模式"></a>
 
-以下步骤适合有一定开发经验、想快速跑起项目源码的用户。我们推荐使用现代 Python 构建工具 `uv`。
+### 源码部署（推荐）
+
+使用 `uv` 安装依赖并启动管理控制台。首次部署还需要准备 QQ 协议端、模型 API 和帐号配置，完整步骤见 [源码部署指南](docs/deployment.md#源码部署推荐)。
 
 ```bash
 # 1. 完整克隆源码库（注意附带 NagaAgent 模块）
@@ -194,35 +187,48 @@ uv run playwright install  # 安装浏览器内核（用于页面截图等能力
 
 # 3. 启动管理控制台（推荐入口）
 uv run Undefined-webui
-
-# 4. 在 WebUI 中补齐/校验配置，然后直接点击启动 Bot
-#    如需先手动准备配置，也可以再执行：
-# cp config.toml.example config.toml
 ```
 
-> 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
+启动后，按终端显示的地址打开 WebUI，设置管理密码并填写模型与 QQ 配置；校验通过后，在页面中启动 Bot。后续配置、日志查看和 Bot 启停都可以在 WebUI 中完成。
 
----
+<a id="-docker-一键部署linux"></a>
+<a id="docker-一键部署linux"></a>
 
-## 🐳 快速开始 (容器模式，Linux)
+### Docker 一键部署（Linux） · [完整部署指南](docs/docker-deploy.md)
 
-不想手工装 Python 依赖、也不想自己起 NapCat / SearXNG 等服务？一条命令搞定（需要 Docker Engine，含 `docker compose` v2 插件）：
+已安装 Docker Engine、`docker compose` 插件、Git 和 uv 后，在 Linux 上执行以下命令；未安装时先看 [开始前的准备](docs/docker-deploy.md#1-开始前的准备)。默认部署 Undefined + NapCat，其他服务按需选择：
 
 ```bash
-git clone --recursive https://github.com/69gg/Undefined.git
+git clone https://github.com/69gg/Undefined.git
 cd Undefined
-
-# 交互式向导：选“本体是否进容器”，以及要额外部署哪些自托管服务（默认全不选）
 uv run deploy up
-
-# 非交互式：只跑本体 + NapCat
-uv run deploy up --yes
 ```
 
-脚本会自动生成 compose 与各服务配置、按最小差异改好 `config.toml`（改前备份）、启动容器，最后把 **Undefined WebUI 密码、带 token 的 NapCat WebUI 链接、各服务入口**一次性打印出来。
+部署结束后，终端会显示 **Undefined WebUI 地址和密码、NapCat 登录链接**。打开 WebUI 填写模型 API、机器人 QQ 号和管理员 QQ 号，到 NapCat 扫码登录后，再返回 WebUI 点击“启动机器人”。部署配置默认关闭 Bot 自动启动，并使用 Stream 发送文件。完整步骤见 [部署后的首次配置](docs/docker-deploy.md#3-完成配置并登录-qq)。
+
+后续可用 `uv run deploy status` 查看入口与状态、`uv run deploy logs` 查看日志、`uv run deploy down` 停止服务并保留数据。
+
+### Release 下载速查
+
+完成上述部署后，可直接通过浏览器使用 WebUI。需要独立的管理或聊天客户端时，再前往 [GitHub Releases](https://github.com/69gg/Undefined/releases)，按用途选择组件：
+
+| 你需要的功能 | 下载组件 |
+| --- | --- |
+| 远程管理已有实例，编辑配置、查看日志、启停 Bot | **Undefined Console**：选择 `Undefined-Console-*` |
+| 使用独立的原生聊天界面 | **Undefined Chat**：选择 `Undefined-Chat-*` |
+
+选好 Console 或 Chat 后，在该组件的文件中选择适合设备的安装包：
+
+| 平台 | 安装包 |
+| --- | --- |
+| Windows x64 | `*-windows-x64-setup.exe`；批量部署可选 `*-windows-x64.msi` |
+| macOS | Apple Silicon 选 `*-macos-arm64.dmg`，Intel 选 `*-macos-x64.dmg` |
+| Linux | Debian / Ubuntu 选 `*.deb`，其他发行版可选 `*.AppImage` |
+| Android | 通常选 `*-android-arm64-v8a-release.apk`；旧 32 位设备选 `armeabi-v7a`，模拟器按架构选择 `x86_64` 或 `x86` |
 
-后续：`uv run deploy status` 看状态与凭据、`uv run deploy logs` 看日志、`uv run deploy down` 停止（数据保留）。完整说明见 [容器化一键部署](docs/docker-deploy.md)。
+安装后，Console 连接已部署实例的 Management API，Chat 连接 Bot 的 Runtime API；请使用该实例对应的地址和凭据。**两个客户端都需要已有的 Undefined 服务，部署 Bot 本身无需下载客户端安装包。**
 
+如需离线安装 Python 包或缓存安装文件，可下载 `undefined_bot-*.whl` 或 `undefined_bot-*.tar.gz`；安装方式见 [pip / uv tool 部署说明](docs/deployment.md#pipuv-tool-部署快速体验)。
 
 ---
 

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/README.md

@@ -30,18 +30,7 @@
 
 ---
 
-## Release 下载速查
-
-**部署 QQ Bot 本身不需要下载 Release**：Release 里都是可选组件。源码部署见下方[快速开始](#-快速开始-源码模式)，安装包用途与平台对应如下：
-
-| 目标 | 文件 | 平台 |
-| --- | --- | --- |
-| 部署 / 运行 Bot | 不需要下载 Release；源码部署并启动 `uv run Undefined-webui` | 任意 |
-| 离线安装 / 镜像缓存 | `undefined_bot-*.whl` 或 `undefined_bot-*.tar.gz` | 任意 |
-| 远程管理已有实例 | `Undefined-Console-*`（连接 Management API 打开远程 WebUI） | Windows x64 `*-windows-x64-setup.exe`（批量部署可选 `.msi`）／macOS `*-macos-arm64.dmg`、`*-macos-x64.dmg`／Debian、Ubuntu `*.deb`／其他 Linux `*.AppImage` |
-| 原生聊天客户端 | `Undefined-Chat-*`（连接 Runtime API 聊天） | 同上；Android 为 `*-android-arm64-v8a-release.apk`（旧 32 位设备用 `armeabi-v7a`，模拟器按需 `x86_64` / `x86`） |
-
-Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请先启动 `Undefined-webui`，完成配置和 Bot 启动后再连接。
+> 🚀 **开始使用 Undefined**：从[快速开始](#-快速开始)了解部署步骤、首次配置和可选客户端的下载方式。
 
 ## ⚡ 核心特性
 
@@ -97,8 +86,8 @@ Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请
 
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
-- ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
-- 🐳 **[容器化一键部署](docs/docker-deploy.md)**：`uv run deploy` 一条命令拉起本体 + NapCat 与按需自托管服务（SearXNG / Firecrawl / lxmusic2api），含端口、凭据、模式选择与排查。
+- ⚙️ **[安装与部署指南](docs/deployment.md)**：首选源码部署；按源码、Docker、pip / uv tool 的推荐顺序介绍各安装方式。
+- 🐳 **[Docker 一键部署指南（Linux）](docs/docker-deploy.md)**：源码部署之外的推荐选择，自动部署 Undefined + NapCat，并按需添加搜索、音乐服务。
 - 📦 **[Python 库 API 参考](docs/python-api.md)**：根包 lazy re-export、`Config.from_mapping` / `set_config`、公共 API 符号表与嵌入示例。
 - 🖥️ **[WebUI 使用指南](docs/webui-guide.md)**：管理控制台功能一览——配置编辑、日志查看、认知记忆管理、表情包库、AI 对话与系统监控。
 - 🧭 **[Management API 与远程管理](docs/management-api.md)**：WebUI / App 共用的管理接口、认证、配置/日志/Bot 控制与引导探针说明。
@@ -125,11 +114,15 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 
 ---
 
-## ⚡ 快速开始 (源码模式)
+## ⚡ 快速开始
+
+推荐优先采用源码部署；希望在 Linux 上自动搭建 Undefined、NapCat 和可选服务时，也可以选择 Docker 一键部署。两种方式任选其一，部署完成后可直接使用 WebUI，也可按本节末尾的说明下载独立客户端。
 
-> 👶 **新手必看**：如果您是首次部署此类项目或不熟悉 Git/环境配置，**强烈建议直接前往 [《详细安装与部署指南》](docs/deployment.md)** 阅读手把手教程，避免遇到常见报错。
+<a id="-快速开始-源码模式"></a>
 
-以下步骤适合有一定开发经验、想快速跑起项目源码的用户。我们推荐使用现代 Python 构建工具 `uv`。
+### 源码部署（推荐）
+
+使用 `uv` 安装依赖并启动管理控制台。首次部署还需要准备 QQ 协议端、模型 API 和帐号配置，完整步骤见 [源码部署指南](docs/deployment.md#源码部署推荐)。
 
 ```bash
 # 1. 完整克隆源码库（注意附带 NagaAgent 模块）
@@ -143,35 +136,48 @@ uv run playwright install  # 安装浏览器内核（用于页面截图等能力
 
 # 3. 启动管理控制台（推荐入口）
 uv run Undefined-webui
-
-# 4. 在 WebUI 中补齐/校验配置，然后直接点击启动 Bot
-#    如需先手动准备配置，也可以再执行：
-# cp config.toml.example config.toml
 ```
 
-> 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
+启动后，按终端显示的地址打开 WebUI，设置管理密码并填写模型与 QQ 配置；校验通过后，在页面中启动 Bot。后续配置、日志查看和 Bot 启停都可以在 WebUI 中完成。
 
----
+<a id="-docker-一键部署linux"></a>
+<a id="docker-一键部署linux"></a>
 
-## 🐳 快速开始 (容器模式，Linux)
+### Docker 一键部署（Linux） · [完整部署指南](docs/docker-deploy.md)
 
-不想手工装 Python 依赖、也不想自己起 NapCat / SearXNG 等服务？一条命令搞定（需要 Docker Engine，含 `docker compose` v2 插件）：
+已安装 Docker Engine、`docker compose` 插件、Git 和 uv 后，在 Linux 上执行以下命令；未安装时先看 [开始前的准备](docs/docker-deploy.md#1-开始前的准备)。默认部署 Undefined + NapCat，其他服务按需选择：
 
 ```bash
-git clone --recursive https://github.com/69gg/Undefined.git
+git clone https://github.com/69gg/Undefined.git
 cd Undefined
-
-# 交互式向导：选“本体是否进容器”，以及要额外部署哪些自托管服务（默认全不选）
 uv run deploy up
-
-# 非交互式：只跑本体 + NapCat
-uv run deploy up --yes
 ```
 
-脚本会自动生成 compose 与各服务配置、按最小差异改好 `config.toml`（改前备份）、启动容器，最后把 **Undefined WebUI 密码、带 token 的 NapCat WebUI 链接、各服务入口**一次性打印出来。
+部署结束后，终端会显示 **Undefined WebUI 地址和密码、NapCat 登录链接**。打开 WebUI 填写模型 API、机器人 QQ 号和管理员 QQ 号，到 NapCat 扫码登录后，再返回 WebUI 点击“启动机器人”。部署配置默认关闭 Bot 自动启动，并使用 Stream 发送文件。完整步骤见 [部署后的首次配置](docs/docker-deploy.md#3-完成配置并登录-qq)。
+
+后续可用 `uv run deploy status` 查看入口与状态、`uv run deploy logs` 查看日志、`uv run deploy down` 停止服务并保留数据。
+
+### Release 下载速查
+
+完成上述部署后，可直接通过浏览器使用 WebUI。需要独立的管理或聊天客户端时，再前往 [GitHub Releases](https://github.com/69gg/Undefined/releases)，按用途选择组件：
+
+| 你需要的功能 | 下载组件 |
+| --- | --- |
+| 远程管理已有实例，编辑配置、查看日志、启停 Bot | **Undefined Console**：选择 `Undefined-Console-*` |
+| 使用独立的原生聊天界面 | **Undefined Chat**：选择 `Undefined-Chat-*` |
+
+选好 Console 或 Chat 后，在该组件的文件中选择适合设备的安装包：
+
+| 平台 | 安装包 |
+| --- | --- |
+| Windows x64 | `*-windows-x64-setup.exe`；批量部署可选 `*-windows-x64.msi` |
+| macOS | Apple Silicon 选 `*-macos-arm64.dmg`，Intel 选 `*-macos-x64.dmg` |
+| Linux | Debian / Ubuntu 选 `*.deb`，其他发行版可选 `*.AppImage` |
+| Android | 通常选 `*-android-arm64-v8a-release.apk`；旧 32 位设备选 `armeabi-v7a`，模拟器按架构选择 `x86_64` 或 `x86` |
 
-后续：`uv run deploy status` 看状态与凭据、`uv run deploy logs` 看日志、`uv run deploy down` 停止（数据保留）。完整说明见 [容器化一键部署](docs/docker-deploy.md)。
+安装后，Console 连接已部署实例的 Management API，Chat 连接 Bot 的 Runtime API；请使用该实例对应的地址和凭据。**两个客户端都需要已有的 Undefined 服务，部署 Bot 本身无需下载客户端安装包。**
 
+如需离线安装 Python 包或缓存安装文件，可下载 `undefined_bot-*.whl` 或 `undefined_bot-*.tar.gz`；安装方式见 [pip / uv tool 部署说明](docs/deployment.md#pipuv-tool-部署快速体验)。
 
 ---
 

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/config.toml.example

@@ -1146,6 +1146,9 @@ use_proxy = false
 # zh: 远程附件自动下载并缓存的最大大小（MB）。超过上限或设为 0 时只保留 URL 引用，不下载文件内容。
 # en: Max remote attachment size (MB) to download into cache. Above the limit, or 0, keeps only a URL reference.
 remote_download_max_size_mb = 25
+# zh: 默认拒绝远程附件访问非公网地址。仅为信任的内网媒体服务添加精确 origin（协议、主机、端口），例如 ["http://media.internal:8080"]；不支持路径、凭据或通配符。支持热重载。
+# en: Remote attachments reject non-public destinations by default. Allow only trusted private media origins (scheme, host, port), e.g. ["http://media.internal:8080"]. Paths, credentials and wildcards are not supported. Hot-reloadable.
+remote_download_allow_private_origins = []
 # zh: 附件缓存文件总大小上限（MB）。0 表示不按总容量清理；达到上限时优先删除最旧的本地缓存副本，若记录有 URL 则保留 UID 与 URL 以便后续回源。
 # en: Total attachment cache file size limit (MB). 0 disables total-size pruning; when exceeded, oldest local cache copies are removed while URL-backed UIDs keep their URL for later re-download.
 cache_max_total_size_mb = 0
@@ -1270,15 +1273,15 @@ use_proxy = false
 # en: Search tool priority for web_agent. Disabled tools are hidden; enabled tools are preferred in this order by prompt guidance, not hard routing.
 priority = ["grok_search", "firecrawl_search", "web_search"]
 # zh: SearxNG 搜索服务地址，例如 http://127.0.0.1:8849。
-# zh: 该服务需自行部署（官方说明：https://docs.searxng.org/），本项目不提供；留空时内置 web_search 工具不可用，grok_search / firecrawl_search / crawl_webpage 不受影响。
+# zh: 可用 uv run deploy up --with searxng 一键部署，或连接已有实例（官方说明：https://docs.searxng.org/）；留空时内置 web_search 工具不可用，grok_search / firecrawl_search / crawl_webpage 不受影响。
 # en: SearxNG service URL, e.g. http://127.0.0.1:8849.
-# en: This service must be self-deployed (official guide: https://docs.searxng.org/); when empty the built-in web_search tool is unavailable while grok_search / firecrawl_search / crawl_webpage keep working.
+# en: Deploy with uv run deploy up --with searxng or connect to an existing instance (official guide: https://docs.searxng.org/); when empty the built-in web_search tool is unavailable while grok_search / firecrawl_search / crawl_webpage keep working.
 searxng_url = ""
 # zh: 是否在 web_agent 中启用 grok_search。关闭时该工具会从 web_agent 工具列表中隐藏。
 # en: Enable grok_search in web_agent. When disabled, this tool is hidden from the web_agent tool list.
 grok_search_enabled = false
-# zh: 是否在 web_agent 中启用 firecrawl_search。默认关闭；关闭时该工具会隐藏。
-# en: Enable firecrawl_search in web_agent. Disabled by default; when disabled, this tool is hidden.
+# zh: 是否在 web_agent 中启用 firecrawl_search。默认关闭；关闭时该工具会隐藏。无需自部署 Firecrawl，启用后可使用官方 keyless。
+# en: Enable firecrawl_search in web_agent. Disabled by default; when disabled, this tool is hidden. Self-hosting is optional; enable this to use official keyless search.
 firecrawl_search_enabled = false
 
 # zh: Firecrawl 搜索服务配置。
@@ -1287,8 +1290,8 @@ firecrawl_search_enabled = false
 # zh: Firecrawl API Key。为空时使用 Firecrawl keyless 搜索；填写后会发送 Authorization: Bearer；自部署实例通常也可留空。
 # en: Firecrawl API key. Leave empty for Firecrawl keyless search; when set, Authorization: Bearer is sent; self-hosted instances can usually leave it empty too.
 api_key = ""
-# zh: Firecrawl API 基础地址。可用官方地址配自己的 Key，也可改为自部署实例地址（自托管说明：https://docs.firecrawl.dev/contributing/self-host）。
-# en: Firecrawl API base URL. Use the official endpoint with your own key, or point it at a self-hosted instance (self-host guide: https://docs.firecrawl.dev/contributing/self-host).
+# zh: Firecrawl API 基础地址。官方地址支持 keyless（API Key 留空，受官方配额与限流限制）或自己的 Key，也可改为自部署实例地址（自托管说明：https://docs.firecrawl.dev/contributing/self-host）。
+# en: Firecrawl API base URL. Use the official endpoint with keyless access (empty API key, subject to official quotas and rate limits) or your own key, or point it at a self-hosted instance (self-host guide: https://docs.firecrawl.dev/contributing/self-host).
 base_url = "https://api.firecrawl.dev"
 
 # zh: 代理设置（可选）。
@@ -1325,8 +1328,8 @@ browser_max_concurrency = 0
 # zh: 可选的 Chrome/Chromium 可执行文件路径。留空时优先使用 Playwright 自带浏览器，缺失时再自动查找系统浏览器。
 # en: Optional Chrome/Chromium executable path. Empty prefers Playwright's bundled browser, then discovers an installed system browser if missing.
 browser_executable_path = ""
-# zh: render_html/render_markdown 的 long 布局未显式传 width 时使用的最终图片宽度（像素，320-2048）。
-# en: Final image width used by the long layout when width is omitted (pixels, 320-2048).
+# zh: render_html/render_markdown 的 long 布局未显式传 width 时使用的图片宽度上限（像素，320-2048）。页面自身布局更窄时按「内容宽度 + 2×padding」收敛，两侧不留空白。
+# en: Upper bound of the long-layout image width when width is omitted (pixels, 320-2048). When the page lays out narrower, the image shrinks to content width + 2×padding so no side whitespace is left.
 long_image_default_width = 900
 # zh: long 布局未显式传 padding 时使用的内边距（像素，0-160）。
 # en: Content padding used by the long layout when padding is omitted (pixels, 0-160).

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/pyproject.toml

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

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

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/src/Undefined/ai/client/setup.py

@@ -202,6 +202,9 @@ class ClientSetupMixin:
         self._meme_service: Any = None
         if self.runtime_config is not None:
             self.attachment_registry = AttachmentRegistry(
+                remote_download_allow_private_origins=(
+                    self.runtime_config.attachment_remote_download_allow_private_origins
+                ),
                 remote_download_max_bytes=_attachment_remote_download_max_bytes(
                     self.runtime_config
                 ),
@@ -625,6 +628,9 @@ class ClientSetupMixin:
 
     def apply_attachment_config(self, runtime_config: Config) -> None:
         self.attachment_registry.set_limits(
+            remote_download_allow_private_origins=(
+                runtime_config.attachment_remote_download_allow_private_origins
+            ),
             remote_download_max_bytes=_attachment_remote_download_max_bytes(
                 runtime_config
             ),

{undefined_bot-3.17.0 → undefined_bot-3.17.1}/src/Undefined/attachments/registry.py

@@ -20,13 +20,13 @@ from uuid import uuid4
 import httpx
 
 from Undefined.attachments.models import AttachmentRecord, _RemoteAttachmentTooLarge
+from Undefined.attachments.remote import RemoteURLPolicy, stream_remote_url
 from Undefined.attachments.segments import (
     display_name_from_source,
     is_http_url,
     media_kind_from_value,
     scope_from_context,
 )
-from Undefined.skills.http_config import build_httpx_client_kwargs
 from Undefined.utils import io
 from Undefined.utils.paths import (
     ATTACHMENT_CACHE_DIR,
@@ -129,6 +129,7 @@ class AttachmentRegistry:
         url_reference_max_records: int = _ATTACHMENT_URL_REFERENCE_MAX_RECORDS,
         url_max_length: int = _ATTACHMENT_URL_MAX_LENGTH,
         remote_download_max_bytes: int = _DEFAULT_REMOTE_DOWNLOAD_MAX_BYTES,
+        remote_download_allow_private_origins: list[str] | tuple[str, ...] = (),
         proxy_config: Any | None = None,
     ) -> None:
         self._registry_path = registry_path
@@ -140,6 +141,9 @@ class AttachmentRegistry:
         self._url_reference_max_records = max(0, int(url_reference_max_records))
         self._url_max_length = max(0, int(url_max_length))
         self._remote_download_max_bytes = max(0, int(remote_download_max_bytes))
+        self._remote_url_policy = RemoteURLPolicy.create(
+            remote_download_allow_private_origins, self._url_max_length
+        )
         self._proxy_config = proxy_config
         self._lock = asyncio.Lock()
         self._records: dict[str, AttachmentRecord] = {}
@@ -160,6 +164,9 @@ class AttachmentRegistry:
         self,
         *,
         remote_download_max_bytes: int | None = None,
+        remote_download_allow_private_origins: list[str]
+        | tuple[str, ...]
+        | None = None,
         max_cache_bytes: int | None = None,
         max_records: int | None = None,
         max_age_seconds: int | None = None,
@@ -167,7 +174,7 @@ class AttachmentRegistry:
         url_max_length: int | None = None,
         proxy_config: Any | None = None,
     ) -> None:
-        """批量更新注册表容量与 TTL 限制。"""
+        """批量更新注册表容量、TTL 限制与远程目标策略。"""
         if remote_download_max_bytes is not None:
             self._remote_download_max_bytes = max(0, int(remote_download_max_bytes))
         if max_cache_bytes is not None:
@@ -180,6 +187,14 @@ class AttachmentRegistry:
             self._url_reference_max_records = max(0, int(url_reference_max_records))
         if url_max_length is not None:
             self._url_max_length = max(0, int(url_max_length))
+        if remote_download_allow_private_origins is not None:
+            self._remote_url_policy = RemoteURLPolicy.create(
+                remote_download_allow_private_origins, self._url_max_length
+            )
+        else:
+            self._remote_url_policy = replace(
+                self._remote_url_policy, max_url_length=self._url_max_length
+            )
         if proxy_config is not None:
             self._proxy_config = proxy_config
 
@@ -767,6 +782,7 @@ class AttachmentRegistry:
         await self.load()
         if not self._normalized_url_ref(url):
             raise ValueError("远程附件 URL 为空或超过长度上限")
+        self._remote_url_policy.validate(url)
         normalized_kind = media_kind_from_value(kind)
         normalized_media_type = (
             "image" if normalized_kind == "image" else normalized_kind
@@ -901,9 +917,13 @@ class AttachmentRegistry:
                 description="远程附件未下载：remote_download_max_size_mb=0",
             )
 
-        async def _stream(client: httpx.AsyncClient) -> tuple[bytes, str]:
-            async with client.stream(
-                "GET", url, timeout=timeout, follow_redirects=True
+        async def _stream() -> tuple[bytes, str]:
+            async with stream_remote_url(
+                url,
+                policy=self._remote_url_policy,
+                timeout=timeout,
+                client=self._http_client,
+                proxy_config=self._proxy_config,
             ) as response:
                 response.raise_for_status()
                 mime_type = (
@@ -924,18 +944,9 @@ class AttachmentRegistry:
                 return b"".join(chunks), mime_type
 
         try:
-            if self._http_client is not None:
-                content, mime_type = await _stream(self._http_client)
-            else:
-                client_kwargs = build_httpx_client_kwargs(
-                    url,
-                    proxy_scope="attachments",
-                    timeout=timeout,
-                    follow_redirects=True,
-                    config=self._proxy_config,
-                )
-                async with httpx.AsyncClient(**client_kwargs) as client:
-                    content, mime_type = await _stream(client)
+            # DNS、连接、重定向与读取共用总时限，避免逐跳重置超时。
+            async with asyncio.timeout(_DEFAULT_REMOTE_TIMEOUT_SECONDS):
+                content, mime_type = await _stream()
         except _RemoteAttachmentTooLarge as exc:
             return await self.register_remote_reference(
                 scope_key,