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

{undefined_bot-3.16.1 → undefined_bot-3.17.1}/.gitignore

@@ -42,6 +42,11 @@ __pycache__/
 logs/*
 data/
 
+# 容器化部署的运行态：.env / STATE.json / compose.yaml / 各服务配置与数据
+# 均含凭据或运行时数据，全部不入库（模板在 src/Undefined/deploy/templates/）
+# 必须用前导 / 锚定到仓库根，否则会连 src/Undefined/deploy 一起忽略
+/deploy/
+
 #AGENTS.md
 .DS_Store
 .claude/

{undefined_bot-3.16.1 → undefined_bot-3.17.1}/ARCHITECTURE.md

@@ -868,6 +868,7 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 6. **技能系统层**：ToolRegistry (registry.py)、AgentRegistry、7个 Agents、13类 Toolsets
 7. **异步 IO 层**：统一 IO 工具 (utils/io.py)，包含 write_json、read_json、append_line、跨平台文件锁 (flock/msvcrt)
 8. **数据持久化层**：历史数据目录、FAQ 目录、Token 归档目录、记忆文件、总结文件、自动化文件、微信绑定/游标/隔离/审计状态
+9. **部署编排层**（`deploy/`，不参与运行时）：`uv run deploy` 把本体与 NapCat、可选自托管服务（SearXNG / Firecrawl / lxmusic2api）编排成一份 Docker Compose。`catalog.py` 是服务、端口与默认值的唯一事实来源（容器内端口固定、宿主端口可覆盖），`generate.py` 由包内 compose 片段与配置模板渲染出 `deploy/` 下的运行态，`config_patch.py` 只对 `config.toml` 做最小差异写入并把原文件备份到 `deploy/backup/`（**注意它是整份重排后原子替换，不是原地编辑**：注释会尽量保留，但不要指望行号与手工排版不变），`state.py` 定义 `deploy/` 运行态布局与 `STATE.json`（端口、绑定地址、服务选择跨次复用的来源），`images.py` 集中管理上游镜像 pin，`nagaagent.py` 负责子模块就绪与「只开问答能力、绝不改写 `[naga]`」的开关写入，`docker_cli.py` 是唯一的进程外调用边界，`runner.py` 实现 up/down/status/logs，`cli.py` 负责参数解析与交互向导。注意 `deploy/` 运行态目录不入库，模板随 wheel 分发；详见 [容器化一键部署](docs/docker-deploy.md)。
 
 ### 微信 iLink 路由边界
 

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

@@ -1,3 +1,36 @@
+## 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 构建与多架构发布。
+
+- 新增部署入口 `uv run deploy`（`up` / `down` / `status` / `logs`）。向导只问四件事：本体部署方式、额外部署哪些自托管服务、发布端口的绑定地址、是否拉取 NagaAgent 子模块；**默认不部署任何可选服务**，回车即「全不部署」（重跑时表示沿用上次选择）。`--yes` 走非交互默认值；`--dry-run` 只打印将写入的 `config.toml` 差异、生成的 compose/.env 与**将执行的命令**，不落盘、不建目录、不写备份。
+- 两种部署模式：`container`（默认）把本体也放进 compose，镜像入口是 WebUI 并由它托管 Bot 进程（写入 `[webui].autostart_bot = true`）；`host` 只用 Docker 跑依赖服务，本体仍在宿主机启动。
+- `container` 模式把**整个仓库目录**以可写方式挂到容器内的 `/data/Undefined`（`res/`、`img/` 只读覆盖同名目录，`deploy/data`、`deploy/logs` 嵌套为 `data/`、`logs/`）。`up` 写 `config.toml` 走「临时文件 + `os.replace`」原子替换，单文件 bind mount 绑的是替换前的 inode，容器会一直读旧配置而 compose 也不会因此重建容器；挂目录同时保证 WebUI 在线改配置（原地写）仍然可用。
+- 地址与端口按模式对齐：容器内走 compose 服务名与固定的容器内端口，`--port` 覆盖的是宿主机发布端口——`[webui].port` / `[api].port` 与映射目标始终一致，`[onebot].ws_url` 不会被宿主端口污染；`host` 模式下本体自己就是监听方，端口跟随 `--port`。`up` / `status` 输出的入口地址取同一份解析后的端口（`host` 模式不发布本体端口，只看 `.env` 会把覆盖过的端口印成默认值）。`--port-bind` 默认只绑 `127.0.0.1`，`0.0.0.0` 只作监听语义、不会被写成连接地址。
+- 凭据自动生成并复用已有值，重跑不会把已生效的 WebUI 密码、Runtime `auth_key`、NapCat token、SearXNG `secret_key`、Firecrawl 与 lxmusic2api 凭据换掉（`changeme` 与空值视为占位符，且占位值不会挡住下一个来源）。`[webui].password` 与 `[api].auth_key` 以 `config.toml` 里已生效的值为准（`.env` 只是留档，否则一份过期的 `.env` 会把用户手改过的密码改回去），其余凭据只认 `deploy/.env`；凭据文件权限 0600，`deploy/` 整体不入库。
+- 写入面严格限定在服务拓扑：模型端、访问控制与提示词一律不碰。NagaAgent 相关**只写** `[features].nagaagent_mode_enabled`，`[naga]` 整节（`enabled` / `api_url` / `api_key` / `mode`）原样保留——既不清空已填的凭据，也不会关掉你自己开着的网关。
+- NapCat 以 `MODE=ws` 作正向 WebSocket 服务端，端口与令牌由生成的 `deploy/napcat/ws.json` 只读覆盖镜像模板，容器每次启动重新写出；登录之后 NapCat 优先读账号级 `onebot11_<QQ>.json` 且没有 fs.watch，`up` 的输出会点名该文件并给出处置办法，不再一律报「已就绪」。
+- 自托管服务：SearXNG 自带 `search.formats: [html, json]`（缺 `json` 时 `web_search` 会收到 403）并关闭入口对挂载目录的 chown；Firecrawl 拉起 api / playwright / redis / rabbitmq / postgres 五个容器，`USE_DB_AUTHENTICATION=false` 时不校验 key，管理界面只有 `/admin/<BULL_AUTH_KEY>/queues`；lxmusic2api 上游没有镜像，由本项目在 CI 里 clone 固定 commit 构建，pin 必须是完整 sha。
+- `container` 模式下 `python_interpreter` / `code_delivery_agent` 通过挂载宿主 `/var/run/docker.sock` 走 DooD（不启 DinD），本体容器额外禁止提权；`down --purge` 会连同 `deploy/` 下的数据与凭据一并删除，不可恢复。
+- 发布流程新增镜像构建：amd64 与 arm64 分别在原生 runner 上构建并按 digest 推送，再由合并任务生成 manifest list，产出 `ghcr.io/<owner>/undefined-bot:<tag>` 与 `undefined-lxmusic2api:<短sha>`，顺序在版本发布之前。GHCR 包首次推送默认为 private，拉取前需要 `docker login ghcr.io` 或把包改为 public。
+- 部署过程本身按「失败可收拾」设计：`STATE.json` 在 `compose up` 之前落盘，任何失败之后 `down` / `status` / `logs` 仍然可用；镜像拉取超时按策略选择（首次部署用长超时）；NapCat WebUI 的容器内端口固定，覆盖宿主端口不会让它失联。
+
+---
+
 ## v3.16.1 自托管服务部署依赖说明
 
 本版本补齐部署文档中长期缺失的一块：除 Python 运行环境外，Undefined 还需要连接若干由部署方自行搭建的服务，此前这些依赖只散落在配置字段注释里，没有一处说明哪些是必需的、不部署会失去什么。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Undefined-bot
-Version: 3.16.1
+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,7 +137,8 @@ Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请
 
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
-- ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
+- ⚙️ **[安装与部署指南](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 控制与引导探针说明。
@@ -175,11 +165,15 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 
 ---
 
-## ⚡ 快速开始 (源码模式)
+## ⚡ 快速开始
+
+推荐优先采用源码部署；希望在 Linux 上自动搭建 Undefined、NapCat 和可选服务时，也可以选择 Docker 一键部署。两种方式任选其一，部署完成后可直接使用 WebUI，也可按本节末尾的说明下载独立客户端。
+
+<a id="-快速开始-源码模式"></a>
 
-> 👶 **新手必看**：如果您是首次部署此类项目或不熟悉 Git/环境配置，**强烈建议直接前往 [《详细安装与部署指南》](docs/deployment.md)** 阅读手把手教程，避免遇到常见报错。
+### 源码部署（推荐）
 
-以下步骤适合有一定开发经验、想快速跑起项目源码的用户。我们推荐使用现代 Python 构建工具 `uv`。
+使用 `uv` 安装依赖并启动管理控制台。首次部署还需要准备 QQ 协议端、模型 API 和帐号配置，完整步骤见 [源码部署指南](docs/deployment.md#源码部署推荐)。
 
 ```bash
 # 1. 完整克隆源码库（注意附带 NagaAgent 模块）
@@ -193,13 +187,48 @@ uv run playwright install  # 安装浏览器内核（用于页面截图等能力
 
 # 3. 启动管理控制台（推荐入口）
 uv run Undefined-webui
+```
+
+启动后，按终端显示的地址打开 WebUI，设置管理密码并填写模型与 QQ 配置；校验通过后，在页面中启动 Bot。后续配置、日志查看和 Bot 启停都可以在 WebUI 中完成。
+
+<a id="-docker-一键部署linux"></a>
+<a id="docker-一键部署linux"></a>
+
+### Docker 一键部署（Linux） · [完整部署指南](docs/docker-deploy.md)
+
+已安装 Docker Engine、`docker compose` 插件、Git 和 uv 后，在 Linux 上执行以下命令；未安装时先看 [开始前的准备](docs/docker-deploy.md#1-开始前的准备)。默认部署 Undefined + NapCat，其他服务按需选择：
 
-# 4. 在 WebUI 中补齐/校验配置，然后直接点击启动 Bot
-#    如需先手动准备配置，也可以再执行：
-# cp config.toml.example config.toml
+```bash
+git clone https://github.com/69gg/Undefined.git
+cd Undefined
+uv run deploy up
 ```
 
-> 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
+部署结束后，终端会显示 **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` |
+
+安装后，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.16.1 → 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,7 +86,8 @@ Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请
 
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
-- ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
+- ⚙️ **[安装与部署指南](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 控制与引导探针说明。
@@ -124,11 +114,15 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 
 ---
 
-## ⚡ 快速开始 (源码模式)
+## ⚡ 快速开始
+
+推荐优先采用源码部署；希望在 Linux 上自动搭建 Undefined、NapCat 和可选服务时，也可以选择 Docker 一键部署。两种方式任选其一，部署完成后可直接使用 WebUI，也可按本节末尾的说明下载独立客户端。
+
+<a id="-快速开始-源码模式"></a>
 
-> 👶 **新手必看**：如果您是首次部署此类项目或不熟悉 Git/环境配置，**强烈建议直接前往 [《详细安装与部署指南》](docs/deployment.md)** 阅读手把手教程，避免遇到常见报错。
+### 源码部署（推荐）
 
-以下步骤适合有一定开发经验、想快速跑起项目源码的用户。我们推荐使用现代 Python 构建工具 `uv`。
+使用 `uv` 安装依赖并启动管理控制台。首次部署还需要准备 QQ 协议端、模型 API 和帐号配置，完整步骤见 [源码部署指南](docs/deployment.md#源码部署推荐)。
 
 ```bash
 # 1. 完整克隆源码库（注意附带 NagaAgent 模块）
@@ -142,13 +136,48 @@ uv run playwright install  # 安装浏览器内核（用于页面截图等能力
 
 # 3. 启动管理控制台（推荐入口）
 uv run Undefined-webui
+```
+
+启动后，按终端显示的地址打开 WebUI，设置管理密码并填写模型与 QQ 配置；校验通过后，在页面中启动 Bot。后续配置、日志查看和 Bot 启停都可以在 WebUI 中完成。
+
+<a id="-docker-一键部署linux"></a>
+<a id="docker-一键部署linux"></a>
+
+### Docker 一键部署（Linux） · [完整部署指南](docs/docker-deploy.md)
+
+已安装 Docker Engine、`docker compose` 插件、Git 和 uv 后，在 Linux 上执行以下命令；未安装时先看 [开始前的准备](docs/docker-deploy.md#1-开始前的准备)。默认部署 Undefined + NapCat，其他服务按需选择：
 
-# 4. 在 WebUI 中补齐/校验配置，然后直接点击启动 Bot
-#    如需先手动准备配置，也可以再执行：
-# cp config.toml.example config.toml
+```bash
+git clone https://github.com/69gg/Undefined.git
+cd Undefined
+uv run deploy up
 ```
 
-> 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
+部署结束后，终端会显示 **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` |
+
+安装后，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.16.1 → 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.16.1 → undefined_bot-3.17.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.16.1"
+version = "3.17.1"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [
@@ -58,6 +58,7 @@ Issues = "https://github.com/69gg/Undefined/issues"
 [project.scripts]
 Undefined = "Undefined.main:run"
 Undefined-webui = "Undefined.webui:run"
+deploy = "Undefined.deploy:main"
 
 [[tool.uv.index]]
 url = "https://pypi.org/simple"

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

{undefined_bot-3.16.1 → 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.16.1 → 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,