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

{undefined_bot-3.16.0 → undefined_bot-3.17.0}/.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.0 → undefined_bot-3.17.0}/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.0 → undefined_bot-3.17.0}/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 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 还需要连接若干由部署方自行搭建的服务，此前这些依赖只散落在配置字段注释里，没有一处说明哪些是必需的、不部署会失去什么。
+
+- 部署文档新增「需要一并部署的自托管服务（概览）」，明确四项服务的必要性与影响面：OneBot V11 协议端（NapCat / Lagrange.Core）为必需项，QQ 消息的收发完全由协议端决定；SearXNG 只影响内置 `web_search`；Firecrawl 默认关闭，可用官方 keyless、官方 + 自己的 API Key 或自部署实例；lxmusic2api 不部署时整组 `music.*` 工具隐藏。每项给出配置位置与官方部署说明链接，不重复上游安装步骤。
+- 同一节补充宿主环境依赖：Docker（Code Delivery Agent，可 `enabled = false` 关闭）、FFmpeg（Bilibili 音视频合并、原生语音与微信侧 SILK 编码），以及本地子进程 MCP 服务器所需的运行时（`npx` 需要 Node.js，`uvx` 随 `uv` 一同安装，无需 Node.js）。概览放在源码部署的安装步骤之后、配置环境之前，pip/uv tool 部署同样适用。
+- 配置文档在 `[onebot]`、`[search]`、`[lxmusic2api]` 对应小节补充部署前提与可选性说明，`config.toml.example` 同步补注 SearXNG 与 Firecrawl 的自部署提示。
+- 首页 Release 下载速查压缩为一张三列表格（目标 / 文件 / 平台），去掉与正文重复的表述。
+
+---
+
 ## v3.16.0 Bilibili 图文（opus）提取
 
 本版本为 B 站内容自动提取补齐图文（opus / 动态）类型，命中图文链接后发送一次合并转发：第一条是图文元数据、第二条起是正文，文字与图片按原顺序混排，正文超长自动分段；正文里的图文与视频卡片各自成为嵌套转发节点；新增的 `bilibili_opus` 工具还支持按字数区间或关键词读取正文。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Undefined-bot
-Version: 3.16.0
+Version: 3.17.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
@@ -83,29 +83,16 @@ Description-Content-Type: text/markdown
 
 ## Release 下载速查
 
-如果只是部署和运行 QQ Bot，通常**不需要**在 GitHub Release 的 Assets 里下载任何文件。推荐按下方[快速开始](#-快速开始-源码模式)使用源码部署；只想快速体验命令行入口时，可使用 `pip install -U Undefined-bot` 或 `uv tool install Undefined-bot`。
+**部署 QQ Bot 本身不需要下载 Release**：Release 里都是可选组件。源码部署见下方[快速开始](#-快速开始-源码模式)，安装包用途与平台对应如下：
 
-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` |
+| 部署 / 运行 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 启动后，再按需使用这些客户端连接。
+Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请先启动 `Undefined-webui`，完成配置和 Bot 启动后再连接。
 
 ## ⚡ 核心特性
 
@@ -162,6 +149,7 @@ Console 和 Chat 都需要连接到已经运行的 Undefined 服务。首次部
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
 - ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
+- 🐳 **[容器化一键部署](docs/docker-deploy.md)**：`uv run deploy` 一条命令拉起本体 + NapCat 与按需自托管服务（SearXNG / Firecrawl / lxmusic2api），含端口、凭据、模式选择与排查。
 - 📦 **[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 控制与引导探针说明。
@@ -214,6 +202,28 @@ uv run Undefined-webui
 
 > 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
 
+---
+
+## 🐳 快速开始 (容器模式，Linux)
+
+不想手工装 Python 依赖、也不想自己起 NapCat / SearXNG 等服务？一条命令搞定（需要 Docker Engine，含 `docker compose` v2 插件）：
+
+```bash
+git clone --recursive 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 链接、各服务入口**一次性打印出来。
+
+后续：`uv run deploy status` 看状态与凭据、`uv run deploy logs` 看日志、`uv run deploy down` 停止（数据保留）。完整说明见 [容器化一键部署](docs/docker-deploy.md)。
+
+
 ---
 
 ## 作为 Python 库使用

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

@@ -32,29 +32,16 @@
 
 ## Release 下载速查
 
-如果只是部署和运行 QQ Bot，通常**不需要**在 GitHub Release 的 Assets 里下载任何文件。推荐按下方[快速开始](#-快速开始-源码模式)使用源码部署；只想快速体验命令行入口时，可使用 `pip install -U Undefined-bot` 或 `uv tool install Undefined-bot`。
+**部署 QQ Bot 本身不需要下载 Release**：Release 里都是可选组件。源码部署见下方[快速开始](#-快速开始-源码模式)，安装包用途与平台对应如下：
 
-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` |
+| 部署 / 运行 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 启动后，再按需使用这些客户端连接。
+Console 和 Chat 都需要连接已运行的 Undefined 服务：首次部署请先启动 `Undefined-webui`，完成配置和 Bot 启动后再连接。
 
 ## ⚡ 核心特性
 
@@ -111,6 +98,7 @@ Console 和 Chat 都需要连接到已经运行的 Undefined 服务。首次部
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
 - ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
+- 🐳 **[容器化一键部署](docs/docker-deploy.md)**：`uv run deploy` 一条命令拉起本体 + NapCat 与按需自托管服务（SearXNG / Firecrawl / lxmusic2api），含端口、凭据、模式选择与排查。
 - 📦 **[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 控制与引导探针说明。
@@ -163,6 +151,28 @@ uv run Undefined-webui
 
 > 浏览器是默认入口；如果你按上方 [Release 下载速查](#release-下载速查)下载了桌面端或 Android 安装包，也可以在完成首轮密码设置后，连接到同一个 Management API 地址进行远程管理。
 
+---
+
+## 🐳 快速开始 (容器模式，Linux)
+
+不想手工装 Python 依赖、也不想自己起 NapCat / SearXNG 等服务？一条命令搞定（需要 Docker Engine，含 `docker compose` v2 插件）：
+
+```bash
+git clone --recursive 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 链接、各服务入口**一次性打印出来。
+
+后续：`uv run deploy status` 看状态与凭据、`uv run deploy logs` 看日志、`uv run deploy down` 停止（数据保留）。完整说明见 [容器化一键部署](docs/docker-deploy.md)。
+
+
 ---
 
 ## 作为 Python 库使用

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

@@ -1270,7 +1270,9 @@ 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 不受影响。
 # 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.
 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.
@@ -1282,11 +1284,11 @@ firecrawl_search_enabled = false
 # zh: Firecrawl 搜索服务配置。
 # en: Firecrawl search service config.
 [search.firecrawl]
-# zh: Firecrawl API Key。为空时使用 Firecrawl keyless 搜索；填写后会发送 Authorization: Bearer。
-# en: Firecrawl API key. Leave empty for Firecrawl keyless search; when set, Authorization: Bearer is sent.
+# 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 基础地址。
-# en: Firecrawl API base URL.
+# 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).
 base_url = "https://api.firecrawl.dev"
 
 # zh: 代理设置（可选）。

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

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.16.0"
+version = "3.17.0"
 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.0 → undefined_bot-3.17.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.16.0"
+__version__: str = "3.17.0"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

undefined_bot-3.17.0/src/Undefined/deploy/__init__.py

@@ -0,0 +1,12 @@
+"""一次性容器化部署入口（``uv run deploy``）。
+
+本包只负责“把本体与依赖服务用 Docker Compose 跑起来”，不参与运行时逻辑。
+对外只暴露 :func:`main`，实现按职责拆分在 ``catalog`` / ``generate`` /
+``config_patch`` / ``nagaagent`` / ``state`` / ``docker_cli`` / ``cli`` 中。
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+__all__ = ["main"]

undefined_bot-3.17.0/src/Undefined/deploy/__main__.py

@@ -0,0 +1,8 @@
+"""支持 ``python -m Undefined.deploy``。"""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

undefined_bot-3.17.0/src/Undefined/deploy/catalog.py

@@ -0,0 +1,285 @@
+"""部署目录（唯一事实来源）。
+
+集中定义：可部署服务清单、端口、默认值、以及 ``config.toml`` 的写入目标。
+``generate`` / ``cli`` / ``state`` 都从这里取数据，避免同一事实散落多处。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+# --------------------------------------------------------------------------- #
+# 部署模式
+# --------------------------------------------------------------------------- #
+
+MODE_CONTAINER: Final[str] = "container"
+MODE_HOST: Final[str] = "host"
+DEPLOY_MODES: Final[tuple[str, ...]] = (MODE_CONTAINER, MODE_HOST)
+
+#: 进程退出码，供 cli 与 commands 共用。
+EXIT_OK: Final[int] = 0
+EXIT_ERROR: Final[int] = 1
+
+# --------------------------------------------------------------------------- #
+# 运行态目录（相对仓库根，随 .gitignore 忽略）
+# --------------------------------------------------------------------------- #
+
+DEPLOY_DIR_NAME: Final[str] = "deploy"
+STATE_FILE_NAME: Final[str] = "STATE.json"
+ENV_FILE_NAME: Final[str] = ".env"
+COMPOSE_FILE_NAME: Final[str] = "compose.yaml"
+COMPOSE_PROJECT_NAME: Final[str] = "undefined-deploy"
+
+# --------------------------------------------------------------------------- #
+# 端口与绑定地址
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True, slots=True)
+class PortSpec:
+    """一个需要发布的端口。
+
+    ``env_var`` 由 :func:`port_env_var` / :func:`bind_env_var` 生成，
+    模板与 ``.env`` 都用同一套命名，避免手写拼错。
+    """
+
+    key: str
+    default: int
+    label: str
+
+    @property
+    def env_var(self) -> str:
+        return "UNDEFINED_DEPLOY_PORT_" + self.key.upper()
+
+    @property
+    def bind_env_var(self) -> str:
+        return self.env_var + "_BIND"
+
+
+#: 所有部署端口默认只绑定回环地址；需要远程访问时由用户显式改成 0.0.0.0。
+DEFAULT_PORT_BIND: Final[str] = "127.0.0.1"
+
+# --------------------------------------------------------------------------- #
+# 容器内固定端口
+#
+# ``PortSpec.default`` 是**宿主机发布端口**，可被 ``--port`` 覆盖；容器内真正监听
+# 的端口必须是确定的，所以在这里固定下来，compose 一律写成
+# ``${BIND}:${HOST_PORT}:<容器端口>``。
+#
+# 本体的 WebUI / Runtime API 端口由 ``config.toml`` 决定，因此生成配置时会把
+# ``webui.port`` / ``api.port`` 同步成这里的值，保证「容器听什么」与
+# 「compose 把宿主端口映到哪」一致（旧实现两者同用一个变量，覆盖端口后必然错位）。
+# --------------------------------------------------------------------------- #
+
+BOT_WEBUI_CONTAINER_PORT: Final[int] = 8787
+BOT_API_CONTAINER_PORT: Final[int] = 8788
+NAPCAT_WS_CONTAINER_PORT: Final[int] = 3001
+NAPCAT_WEBUI_CONTAINER_PORT: Final[int] = 6099
+SEARXNG_CONTAINER_PORT: Final[int] = 8080
+FIRECRAWL_CONTAINER_PORT: Final[int] = 3002
+LXMUSIC2API_CONTAINER_PORT: Final[int] = 3000
+
+#: 端口键 -> 容器内端口。
+CONTAINER_PORTS: Final[dict[str, int]] = {
+    "bot_webui": BOT_WEBUI_CONTAINER_PORT,
+    "bot_api": BOT_API_CONTAINER_PORT,
+    "napcat_ws": NAPCAT_WS_CONTAINER_PORT,
+    "napcat_webui": NAPCAT_WEBUI_CONTAINER_PORT,
+    "searxng": SEARXNG_CONTAINER_PORT,
+    "firecrawl": FIRECRAWL_CONTAINER_PORT,
+    "lxmusic2api": LXMUSIC2API_CONTAINER_PORT,
+}
+
+
+def container_port(key: str) -> int:
+    """取容器内固定端口；未登记的键直接报错，避免拼错后静默取错值。"""
+    try:
+        return CONTAINER_PORTS[key]
+    except KeyError as exc:
+        known = ", ".join(sorted(CONTAINER_PORTS))
+        raise KeyError(f"未知端口键 {key!r}；可选：{known}") from exc
+
+
+# --------------------------------------------------------------------------- #
+# config.toml 写入目标
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigTarget:
+    """一条 ``config.toml`` 写入项。
+
+    ``key`` 使用 ``apply_patch`` 支持的 dotted path；``rendered`` 用于让用户
+    在 ``--dry-run`` / 汇总输出里看到将写入的值（敏感值由调用方脱敏）。
+    """
+
+    key: str
+    rendered: str
+    about: str
+
+
+# --------------------------------------------------------------------------- #
+# 服务清单
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True, slots=True)
+class Service:
+    """一个可部署的依赖服务。
+
+    ``key`` 是稳定标识：同时用于 CLI ``--with``、``STATE.json`` 与配置目标命名，
+    因此不要为了改名而改名。``compose_fragment`` 指向包内模板文件名。
+    """
+
+    key: str
+    label: str
+    about: str
+    compose_fragment: str
+    ports: tuple[PortSpec, ...] = ()
+
+
+NAPCAT: Final[Service] = Service(
+    key="napcat",
+    label="NapCat（OneBot V11 协议端）",
+    about="QQ 消息收发的唯一通道，必需；QQ 登录需扫码。",
+    compose_fragment="compose.napcat.yaml",
+    ports=(
+        PortSpec("napcat_ws", 3001, "OneBot 正向 WebSocket"),
+        PortSpec("napcat_webui", 6099, "NapCat WebUI"),
+    ),
+)
+
+SEARXNG: Final[Service] = Service(
+    key="searxng",
+    label="SearXNG（web_search）",
+    about="内置 web_search 工具的后端；不部署时该工具不可用。",
+    compose_fragment="compose.searxng.yaml",
+    ports=(PortSpec("searxng", 8080, "SearXNG WebUI / JSON API"),),
+)
+
+FIRECRAWL: Final[Service] = Service(
+    key="firecrawl",
+    label="Firecrawl（firecrawl_search）",
+    about="自带 api/playwright/redis/rabbitmq/postgres 五个容器，资源占用较高。",
+    compose_fragment="compose.firecrawl.yaml",
+    ports=(PortSpec("firecrawl", 3002, "Firecrawl API"),),
+)
+
+LXMUSIC2API: Final[Service] = Service(
+    key="lxmusic2api",
+    label="lxmusic2api（music.* 工具集）",
+    about="上游无官方镜像，由本项目构建；取音频直链需自备 LX 自定义音源脚本。",
+    compose_fragment="compose.lxmusic2api.yaml",
+    ports=(PortSpec("lxmusic2api", 3000, "lxmusic2api API / Swagger"),),
+)
+
+#: 可选的额外服务（NapCat 必需，单独处理，不在此列）。
+OPTIONAL_SERVICES: Final[tuple[Service, ...]] = (SEARXNG, FIRECRAWL, LXMUSIC2API)
+
+#: NapCat 是必装项。
+REQUIRED_SERVICES: Final[tuple[Service, ...]] = (NAPCAT,)
+
+#: key -> Service 的索引，供 CLI 与生成器查询。
+ALL_SERVICES: Final[dict[str, Service]] = {
+    service.key: service for service in (*REQUIRED_SERVICES, *OPTIONAL_SERVICES)
+}
+
+# --------------------------------------------------------------------------- #
+# 本体（Undefined）自身的端口；不是 Service，因为它随 mode 决定是否容器化
+# --------------------------------------------------------------------------- #
+
+BOT_PORTS: Final[tuple[PortSpec, ...]] = (
+    PortSpec("bot_webui", 8787, "Undefined WebUI"),
+    PortSpec("bot_api", 8788, "Runtime API"),
+)
+
+# --------------------------------------------------------------------------- #
+# 默认值
+# --------------------------------------------------------------------------- #
+
+#: 部署脚本会写入的容器固定路径。
+CONTAINER_REPO_ROOT: Final[str] = "/app"
+CONTAINER_DOCKER_SOCK: Final[str] = "/var/run/docker.sock"
+#: 未显式指定模型时输出给用户的提醒。
+MODEL_REMINDER: Final[str] = (
+    "config.toml 的 [models.*] 仍需填写模型端与 API Key，Bot 才能真正收发消息。"
+)
+
+DEFAULTS: Final[dict[str, object]] = {
+    "mode": MODE_CONTAINER,
+    "services": (),
+    "nagaagent": False,
+    "port_bind": DEFAULT_PORT_BIND,
+}
+
+
+def port_defaults() -> dict[str, int]:
+    """返回全部端口的默认值（含本体端口）。"""
+    ports: dict[str, int] = {}
+    for spec in BOT_PORTS:
+        ports[spec.key] = spec.default
+    for service in ALL_SERVICES.values():
+        for spec in service.ports:
+            ports[spec.key] = spec.default
+    return ports
+
+
+def port_specs() -> dict[str, PortSpec]:
+    """返回 key -> PortSpec 的索引（含本体端口）。"""
+    specs: dict[str, PortSpec] = {}
+    for spec in BOT_PORTS:
+        specs[spec.key] = spec
+    for service in ALL_SERVICES.values():
+        for spec in service.ports:
+            specs[spec.key] = spec
+    return specs
+
+
+def selected_service(key: str) -> Service:
+    """按键取服务；未知名直接报错，避免静默忽略用户输入。"""
+    try:
+        return ALL_SERVICES[key]
+    except KeyError as exc:
+        known = ", ".join(sorted(ALL_SERVICES))
+        raise KeyError(f"未知服务 {key!r}；可选：{known}") from exc
+
+
+__all__ = [
+    "ALL_SERVICES",
+    "BOT_API_CONTAINER_PORT",
+    "BOT_PORTS",
+    "BOT_WEBUI_CONTAINER_PORT",
+    "CONTAINER_PORTS",
+    "COMPOSE_FILE_NAME",
+    "COMPOSE_PROJECT_NAME",
+    "CONTAINER_DOCKER_SOCK",
+    "CONTAINER_REPO_ROOT",
+    "DEFAULT_PORT_BIND",
+    "DEFAULTS",
+    "DEPLOY_DIR_NAME",
+    "DEPLOY_MODES",
+    "ENV_FILE_NAME",
+    "FIRECRAWL",
+    "LXMUSIC2API",
+    "MODE_CONTAINER",
+    "FIRECRAWL_CONTAINER_PORT",
+    "LXMUSIC2API_CONTAINER_PORT",
+    "MODE_HOST",
+    "NAPCAT_WEBUI_CONTAINER_PORT",
+    "NAPCAT_WS_CONTAINER_PORT",
+    "MODEL_REMINDER",
+    "NAPCAT",
+    "OPTIONAL_SERVICES",
+    "PortSpec",
+    "REQUIRED_SERVICES",
+    "SEARXNG",
+    "SEARXNG_CONTAINER_PORT",
+    "STATE_FILE_NAME",
+    "Service",
+    "ConfigTarget",
+    "container_port",
+    "port_defaults",
+    "port_specs",
+    "selected_service",
+]