fix(docker): expose picobot CLI and document pairing

Dockerfile

@@ -91,10 +91,12 @@ COPY resources/templates/config.example.json /app/config.json.example
 
 # Create required directories
 RUN mkdir -p /app/.picobot/workspace /app/.picobot/media /app/.picobot/tmp && \
+    ln -sf /app/picobot /usr/local/bin/picobot && \
     chown -R app:app /app
 
 USER app
 ENV HOME=/app
+ENV PATH="/app:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
 
 # Environment variables for Chromium in containers
 ENV CHROME_BIN=/usr/bin/chromium

README.md

@@ -142,6 +142,14 @@ picobot pair
 
 在浏览器配对页输入输出的 8 位代码即可。配对码 5 分钟内有效且只能使用一次；浏览器凭据由 HttpOnly Cookie 保存。需要撤销全部浏览器和 CLI 客户端时运行 `picobot pair --revoke-all`，再用新代码重新配对。
 
+Docker 部署必须在 Gateway 容器内签发配对码，使请求来自容器自身回环地址并能读取映射目录中的管理密钥：
+
+```bash
+docker compose exec picobot picobot pair --gateway-url http://127.0.0.1:19876
+```
+
+不要从宿主机经发布端口直接调用签发接口；容器会把该连接识别为非回环来源并拒绝。`picobot` 已加入正式镜像的 `PATH`，可在容器 shell 中直接调用。
+
 WebUI 随二进制嵌入，不需要 Node.js、npm 或单独部署静态文件，提供：
 
 - 在线聊天、会话创建/切换、历史回放、流式 Markdown、独立思考区、实时工具状态、可折叠历史工具调用卡片，以及基于 Gateway 实时命令清单的 `/` 斜杠命令补全。

docker-compose.test.yml

@@ -0,0 +1,18 @@
+services:
+  picobot:
+    image: picobot:1.2.0
+    container_name: picobot-test
+    restart: unless-stopped
+    ports:
+      - "${PICOBOT_PUBLISH_HOST:-127.0.0.1}:${PICOBOT_GATEWAY_PORT:-19876}:${PICOBOT_GATEWAY_PORT:-19876}"
+    volumes:
+      - "${HOME}/.picobot:/app/.picobot"
+    environment:
+      RUST_LOG: "${RUST_LOG:-info}"
+      TZ: "${TZ:-Asia/Shanghai}"
+    command:
+      - gateway
+      - --host
+      - "${PICOBOT_GATEWAY_HOST:-0.0.0.0}"
+      - --port
+      - "${PICOBOT_GATEWAY_PORT:-19876}"

resources/skills/about-picobot/SKILL.md

@@ -17,7 +17,7 @@ PicoBot 是一个基于 Rust 的个人 AI 助手运行时，包含本地 Gateway
 | `references/db-schema.md` | 数据库表结构与运行约束：sessions、messages、memories、scheduled_jobs、job_runs、llm_calls、background_tasks |
 | `references/architecture.md` | 核心架构：消息并发、会话系统、持久化、生命周期、上下文压缩、记忆、MCP、子 Agent |
 | `references/faq.md` | 常见问题：模型切换、渠道添加、Skill 安装、历史查询、定时任务、MCP 等 |
-| `references/commands.md` | 常用命令：编译、启动网关、启动客户端、运行测试 |
+| `references/commands.md` | 常用命令：编译、启动网关、Docker/WebUI 设备配对、启动客户端、运行测试 |
 | `references/tools.md` | 内置工具名称、参数和重要使用约束 |
 | `assets/config.example.json` | config.json 完整示例 |
 

resources/skills/about-picobot/references/commands.md

@@ -22,6 +22,12 @@ picobot pair
 # 撤销全部设备并生成新配对码
 picobot pair --revoke-all
 
+# Docker 部署：必须在 Gateway 容器内执行，保证请求来自容器回环地址
+docker compose exec picobot picobot pair --gateway-url http://127.0.0.1:19876
+
+# 使用仓库测试 Compose 文件时
+docker compose -f docker-compose.test.yml exec picobot picobot pair --gateway-url http://127.0.0.1:19876
+
 # 修改 WebUI 后独立检查（Node.js 20+）
 cd webui
 npm ci
@@ -66,3 +72,5 @@ cargo test --test test_tool_calling -- --ignored
 `test_scheduler` 和 `test_request_format` 不需要 API Key，也没有标记 `#[ignore]`。只有会真实调用 Provider 的测试需要从 `tests/test.env.example` 创建 `tests/test.env` 后使用 `-- --ignored`。
 
 最终用户使用 WebUI 不需要单独构建；开发源码采用 Svelte 5、Vite 和 Bits UI，`cargo build` 会增量生成前端到 Cargo `OUT_DIR` 并嵌入二进制，生成产物不提交。WebUI 支持在线聊天、动态斜杠命令补全、日志、任务、记忆以及 `config.json`、`USER.md`、`AGENTS.md` 编辑。新设备默认必须配对，管理 API 与 WebSocket 共用设备鉴权；非回环部署仍需要 TLS。
+
+配对码签发接口同时校验真实回环来源和 `~/.picobot/web_admin_token`。Docker 发布端口上的宿主机请求在容器内不是回环连接，因此应使用 `docker compose exec` 在 Gateway 容器中运行 `picobot pair`；不要手工读取或传递管理密钥。配对码为 8 位、5 分钟有效且只能消费一次。

resources/skills/about-picobot/references/faq.md

@@ -22,6 +22,16 @@
 
 内置 Skill 只在目标目录不存在时释放，不会覆盖已安装目录。升级 PicoBot 后如需获取新版内置文档，应先备份自己的修改，再删除旧的 `~/.picobot/skills/about-picobot/` 并重启。也可把定制版放在 `{workspace}/skills/about-picobot/`，它的优先级更高。
 
+## Q: Docker 部署如何获取 WebUI 设备配对码？
+
+在 Gateway 容器内执行：
+
+```bash
+docker compose exec picobot picobot pair --gateway-url http://127.0.0.1:19876
+```
+
+使用 `docker-compose.test.yml` 时增加 `-f docker-compose.test.yml`。签发接口要求请求来自 Gateway 的真实回环地址，并校验 `/app/.picobot/web_admin_token`；因此不要从宿主机经发布端口直接请求，也不要复制或输出管理密钥。代码为 8 位、5 分钟有效且只能使用一次。
+
 ## Q: 数据库文件在哪里？
 
 默认 `{workspace}/picobot.db`，workspace 默认 `~/.picobot/workspace/`。