@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/devops/docker-management/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: docker-management
+description: 管理 Docker 容器、镜像、卷、网络和 Compose 栈 — 包含生命周期操作、调试、清理和 Dockerfile 优化。
+version: 1.0.0
+author: sprmn24
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [docker, containers, devops, infrastructure, compose, images, volumes, networks, debugging]
+    category: devops
+    requires_toolsets: [terminal]
+---
+
+# Docker 管理
+
+使用标准的 Docker CLI 命令来管理 Docker 容器、镜像、卷、网络和 Compose 栈。除了 Docker 本身之外，不需要任何额外的依赖。
+
+## 何时使用
+
+- 运行、停止、重启、移除或查看容器
+- 构建、拉取、推送、打标签或清理 Docker 镜像
+- 使用 Docker Compose（多服务栈）
+- 管理卷或网络
+- 调试崩溃的容器或分析日志
+- 检查 Docker 磁盘使用情况或释放空间
+- 审查或优化 Dockerfile
+
+## 前置条件
+
+- 已安装并正在运行 Docker Engine
+- 用户已添加到 `docker` 组（或者使用 `sudo`）
+- Docker Compose v2（现代 Docker 安装中已包含）
+
+快速检查：
+
+```bash
+docker --version && docker compose version
+```
+
+## 快速参考
+
+| 任务 | 命令 |
+|------|---------|
+| 运行容器（后台） | `docker run -d --name NAME IMAGE` |
+| 停止 + 移除 | `docker stop NAME && docker rm NAME` |
+| 查看日志（跟踪） | `docker logs --tail 50 -f NAME` |
+| 进入容器 Shell | `docker exec -it NAME /bin/sh` |
+| 列出所有容器 | `docker ps -a` |
+| 构建镜像 | `docker build -t TAG .` |
+| 启动 Compose | `docker compose up -d` |
+| 停止 Compose | `docker compose down` |
+| 磁盘使用情况 | `docker system df` |
+| 清理悬空对象 | `docker image prune && docker container prune` |
+
+## 操作流程
+
+### 1. 确定领域
+
+弄清楚请求属于哪个领域：
+
+- **容器生命周期** → run, stop, start, restart, rm, pause/unpause
+- **容器交互** → exec, cp, logs, inspect, stats
+- **镜像管理** → build, pull, push, tag, rmi, save/load
+- **Docker Compose** → up, down, ps, logs, exec, build, config
+- **卷和网络** → create, inspect, rm, prune, connect
+- **故障排查** → 日志分析、退出代码、资源问题
+
+### 2. 容器操作
+
+**运行新容器：**
+
+```bash
+# 带有端口映射的后台服务
+docker run -d --name web -p 8080:80 nginx
+
+# 带有环境变量
+docker run -d -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=mydb --name db postgres:16
+
+# 带有持久化数据（命名卷）
+docker run -d -v pgdata:/var/lib/postgresql/data --name db postgres:16
+
+# 用于开发（绑定挂载源代码）
+docker run -d -v $(pwd)/src:/app/src -p 3000:3000 --name dev my-app
+
+# 交互式调试（退出时自动移除）
+docker run -it --rm ubuntu:22.04 /bin/bash
+
+# 带有资源限制和重启策略
+docker run -d --memory=512m --cpus=1.5 --restart=unless-stopped --name app my-app
+```
+
+关键标志：`-d` 后台运行，`-it` 交互式+tty，`--rm` 自动移除，`-p` 端口 (host:container)，`-e` 环境变量，`-v` 卷，`--name` 名称，`--restart` 重启策略。
+
+**管理正在运行的容器：**
+
+```bash
+docker ps                        # 运行中的容器
+docker ps -a                     # 所有容器（包括已停止的）
+docker stop NAME                 # 优雅停止
+docker start NAME                # 启动已停止的容器
+docker restart NAME              # 停止 + 启动
+docker rm NAME                   # 移除已停止的容器
+docker rm -f NAME                # 强制移除运行中的容器
+docker container prune           # 移除所有已停止的容器
+```
+
+**与容器交互：**
+
+```bash
+docker exec -it NAME /bin/sh          # shell 访问（如果可用，请使用 /bin/bash）
+docker exec NAME env                   # 查看环境变量
+docker exec -u root NAME apt update    # 以特定用户运行
+docker logs --tail 100 -f NAME         # 跟踪最后 100 行
+docker logs --since 2h NAME            # 最近 2 小时的日志
+docker cp NAME:/path/file ./local      # 从容器复制文件
+docker cp ./file NAME:/path/           # 向容器复制文件
+docker inspect NAME                    # 完整的容器详情 (JSON)
+docker stats --no-stream               # 资源使用情况快照
+docker top NAME                        # 运行中的进程
+```
+
+### 3. 镜像管理
+
+```bash
+# 构建
+docker build -t my-app:latest .
+docker build -t my-app:prod -f Dockerfile.prod .
+docker build --no-cache -t my-app .              # 清除缓存重新构建
+DOCKER_BUILDKIT=1 docker build -t my-app .       # 使用 BuildKit 加速
+
+# 拉取和推送
+docker pull node:20-alpine
+docker login ghcr.io
+docker tag my-app:latest registry/my-app:v1.0
+docker push registry/my-app:v1.0
+
+# 查看
+docker images                          # 列出本地镜像
+docker history IMAGE                   # 查看层
+docker inspect IMAGE                   # 完整详情
+
+# 清理
+docker image prune                     # 移除悬空（未打标签的）镜像
+docker image prune -a                  # 移除所有未使用的镜像（请谨慎操作！）
+docker image prune -a --filter "until=168h"   # 移除 7 天前的未使用镜像
+```
+
+### 4. Docker Compose
+
+```bash
+# 启动/停止
+docker compose up -d                   # 后台启动所有服务
+docker compose up -d --build           # 启动前重新构建镜像
+docker compose down                    # 停止并移除容器
+docker compose down -v                 # 同时移除卷（会销毁数据）
+
+# 监控
+docker compose ps                      # 列出服务
+docker compose logs -f api             # 跟踪特定服务的日志
+docker compose logs --tail 50          # 所有服务的最后 50 行
+
+# 交互
+docker compose exec api /bin/sh        # 进入运行中的服务的 shell
+docker compose run --rm api npm test   # 一次性命令（新容器）
+docker compose restart api             # 重启特定服务
+
+# 验证
+docker compose config                  # 验证并查看解析后的配置
+```
+
+**最小的 compose.yml 示例：**
+
+```yaml
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgres://user:pass@db:5432/mydb
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: mydb
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+### 5. 卷和网络
+
+```bash
+# 卷
+docker volume ls                       # 列出卷
+docker volume create mydata            # 创建命名卷
+docker volume inspect mydata           # 详情（挂载点等）
+docker volume rm mydata                # 移除（如果正在使用则会失败）
+docker volume prune                    # 移除未使用的卷
+
+# 网络
+docker network ls                      # 列出网络
+docker network create mynet            # 创建 bridge 网络
+docker network inspect mynet           # 详情（已连接的容器）
+docker network connect mynet NAME      # 将容器加入网络
+docker network disconnect mynet NAME   # 将容器移出网络
+docker network rm mynet                # 移除网络
+docker network prune                   # 移除未使用的网络
+```
+
+### 6. 磁盘使用情况与清理
+
+在清理之前，请务必先进行诊断：
+
+```bash
+# 检查占用空间的项目
+docker system df                       # 摘要
+docker system df -v                    # 详细明细
+
+# 定向清理（安全）
+docker container prune                 # 已停止的容器
+docker image prune                     # 悬空镜像
+docker volume prune                    # 未使用的卷
+docker network prune                   # 未使用的网络
+
+# 激进清理（请先与用户确认！）
+docker system prune                    # 容器 + 镜像 + 网络
+docker system prune -a                 # 同时包含未使用的镜像
+docker system prune -a --volumes       # 所有内容 — 包含命名卷
+```
+
+**警告：** 未经用户确认，切勿运行 `docker system prune -a --volumes`。这会移除可能包含重要数据的命名卷。
+
+## 常见问题
+
+| 问题 | 原因 | 解决方法 |
+|---------|-------|-----|
+| 容器立即退出 | 主进程已结束或崩溃 | 检查 `docker logs NAME`，尝试运行 `docker run -it --entrypoint /bin/sh IMAGE` |
+| “port is already allocated” | 端口被其他进程占用 | 使用 `docker ps` 或 `lsof -i :PORT` 查找占用进程 |
+| “no space left on device” | Docker 磁盘已满 | 运行 `docker system df` 然后进行定向清理 |
+| 无法连接到容器 | 应用在容器内绑定了 127.0.0.1 | 应用必须绑定到 `0.0.0.0`，检查 `-p` 映射 |
+| 卷上权限被拒绝 | 宿主机与容器的 UID/GID 不匹配 | 使用 `--user $(id -u):$(id -g)` 或修复权限 |
+| Compose 服务之间无法通信 | 网络或服务名称错误 | 服务应使用服务名作为主机名，检查 `docker compose config` |
+| 构建缓存无效 | Dockerfile 中的层顺序错误 | 将不常变动的层放在前面（源代码前的依赖项） |
+| 镜像过大 | 未使用多阶段构建，缺少 .dockerignore | 使用多阶段构建，添加 `.dockerignore` |
+
+## 验证
+
+执行任何 Docker 操作后，请验证结果：
+
+- **容器是否启动？** → `docker ps`（检查状态是否为 "Up"）
+- **日志是否正常？** → `docker logs --tail 20 NAME`（无错误）
+- **端口是否可访问？** → `curl -s http://localhost:PORT` 或 `docker port NAME`
+- **镜像是否构建？** → `docker images | grep TAG`
+- **Compose 栈是否健康？** → `docker compose ps`（所有服务处于 "running" 或 "healthy" 状态）
+- **磁盘是否释放？** → `docker system df`（对比操作前后）
+
+## Dockerfile 优化技巧
+
+在审查或创建 Dockerfile 时，建议进行以下改进：
+
+1. **多阶段构建** — 将构建环境与运行环境分开，以减小最终镜像的体积
+2. **层排序** — 将依赖项放在源代码之前，这样代码更改不会使缓存的层失效
+3. **合并 RUN 命令** — 层数越少，镜像越小
+4. **使用 .dockerignore** — 排除 `node_modules`、`.git`、`__pycache__` 等
+5. **固定基础镜像版本** — 使用 `node:20-alpine` 而不是 `node:latest`
+6. **以非 root 用户运行** — 添加 `USER` 指令以提升安全性
+7. **使用 slim/alpine 基础镜像** — 使用 `python:3.12-slim` 而不是 `python:3.12`

package/extensions/skills/optional/devops/hermes-s6-container-supervision/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: hermes-s6-container-supervision
+description: 修改、调试或扩展 Hermes Agent Docker 镜像中的 s6-overlay 监控树 —— 添加新服务、调试 profile 网关、理解架构 B 的主程序模式。
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux]
+environments: [s6]
+metadata:
+  hermes:
+    tags: [docker, s6, supervision, gateway, profiles]
+    related_skills: [hermes-agent, hermes-agent-dev]
+---
+
+# Hermes s6-overlay 容器监控
+
+## 何时使用此技能
+
+当你进行以下操作时，请加载此技能：
+- 在 Hermes Docker 镜像中添加或移除静态服务（即每次容器启动时都应被监控的服务，如 dashboard）
+- 诊断为什么某个 profile 网关无法启动、重启或在 `docker restart` 后保持运行
+- 了解为什么容器的 CMD 是 `/opt/hermes/docker/main-wrapper.sh`，以及以连字符开头的参数是如何传递给用户程序的
+- 修改 `cont-init.d` 引导脚本（UID 重映射、数据卷填充、profile 协调）
+- 更改每个 profile 网关渲染后的 run-script（Phase 4）
+
+如果你只是想运行 Hermes Agent 并使用 Docker，请参阅 `website/docs/user-guide/docker.md`。
+
+## 架构概览
+
+```
+/init                                  ← PID 1 (s6-overlay v3.2.3.0)
+├── cont-init.d                        ← oneshot setup, runs as root
+│   ├── 01-hermes-setup                ← docker/stage2-hook.sh
+│   │   ├── UID/GID remap
+│   │   ├── chown /opt/data
+│   │   ├── chown /opt/data/profiles (every boot)
+│   │   ├── seed .env / config.yaml / SOUL.md
+│   │   └── skills_sync.py
+│   └── 02-reconcile-profiles          ← hermes_cli.container_boot
+│       ├── chown /run/service (hermes-writable for runtime register)
+│       └── walk $HERMES_HOME/profiles/<name>/gateway_state.json
+│           → recreate /run/service/gateway-<name>/
+│           → auto-start only those with prior_state == "running"
+│
+├── s6-rc.d (static services, in /etc/s6-overlay/s6-rc.d/)
+│   ├── main-hermes/run                ← exec sleep infinity (no-op slot)
+│   └── dashboard/run                  ← if HERMES_DASHBOARD=1, runs `hermes dashboard`
+│
+├── /run/service (s6-svscan watches; tmpfs)
+│   ├── gateway-coder/                 ← runtime-registered per-profile
+│   │   ├── type        ("longrun")
+│   │   ├── run         ("#!/command/with-contenv sh ... exec s6-setuidgid hermes hermes -p coder gateway run")
+│   │   ├── down        (marker — present means "registered but don't auto-start")
+│   │   └── log/run     (s6-log → $HERMES_HOME/logs/gateways/coder/current)
+│   └── ...
+│
+└── CMD ("main program")               ← /opt/hermes/docker/main-wrapper.sh
+    └── routes user args: bare exec | hermes subcommand | hermes (no args)
+        — exec'd by /init with stdin/stdout/stderr inherited (TTY for --tui)
+```
+
+## 关键文件
+
+| 路径 | 作用 |
+| --- | --- |
+| `Dockerfile` | s6-overlay 安装 + cont-init.d 配置 + `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]` |
+| `docker/stage2-hook.sh` | “旧的 entrypoint 逻辑” —— UID 重映射、chown、数据填充、skills 同步。作为 cont-init.d/01-hermes-setup 运行。 |
+| `docker/cont-init.d/02-reconcile-profiles` | 每次启动时调用 `hermes_cli.container_boot`，从持久化数据卷中恢复 profile 网关插槽。 |
+| `docker/main-wrapper.sh` | 容器的 CMD。路由用户参数，通过 `s6-setuidgid` 降权到 hermes，exec 选定的程序。 |
+| `docker/s6-rc.d/main-hermes/run` | 空操作 `sleep infinity` —— 该插槽的存在是为了保证 s6-rc 用户 bundle 有效；主 hermes 作为 CMD 运行，而不是作为被监控服务。 |
+| `docker/s6-rc.d/dashboard/run` | 条件服务 —— 除非 `HERMES_DASHBOARD` 为真，否则执行 `exec sleep infinity`。 |
+| `docker/entrypoint.sh` | 向后兼容垫片，`exec` stage2 钩子。硬编码了旧 entrypoint 路径的外部脚本仍能正常工作。 |
+| `hermes_cli/service_manager.py` | `S6ServiceManager`：`register_profile_gateway`，`unregister_profile_gateway`，`start/stop/restart/is_running`，`list_profile_gateways`。 |
+| `hermes_cli/container_boot.py` | `reconcile_profile_gateways()` —— 遍历持久化的 profiles，重新生成 s6 插槽，输出 `container-boot.log`。 |
+| `hermes_cli/gateway.py::_dispatch_via_service_manager_if_s6` | 拦截 `hermes gateway start/stop/restart`，并在容器中运行时路由到 s6。 |
+
+## 为什么使用架构 B（CMD 作为主程序，而不是被 s6 监控）
+
+最初的计划（v1–v3）要求将主 hermes 作为一个受监控的 s6-rc 服务运行。但 s6-overlay v3 的两个实际机制阻碍了这一点：
+
+1. **cont-init.d 脚本不接收 CMD 参数** —— 因此 stage2 钩子无法解析 `docker run <image> chat -q "hi"` 来设置供服务 `run` 脚本使用的 `HERMES_ARGS`。
+2. **`/run/s6/basedir/bin/halt` 不会传播**写入到 `/run/s6-linux-init-container-results/exitcode` 的退出代码。无论写入什么，容器总是以 143 (SIGTERM) 退出。skarnet（s6 作者）在 [issue #477](https://github.com/just-containers/s6-overlay/issues/477) 中证实了这一点：_“如果你想要容器关闭，你需要让 CMD 退出；或者，如果你没有 CMD，写下你想要的容器退出代码然后调用 halt”_。
+
+因此，我们采用了 s6-overlay 原生的 CMD 模式：`ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]`。 /init 会自动将包装器添加到用户参数之前 —— 因此 `docker run <image> --version` 会变成 `/init main-wrapper.sh --version`，并且 `--version` 不会被 /init 的 POSIX shell 拦截。包装器通过 `s6-setuidgid` 降权到 hermes，然后 exec 选定的程序。程序的退出代码即为容器的退出代码，这与使用 s6 之前的 tini 契约完全一致。
+
+权衡：主 hermes 在 s6 下不受监控。这与它在 tini（使用 s6 之前的镜像）下的行为完全一致。Dashboard 监控是**唯一**的新增保障 —— 并且 `/run/service/` 下的每个 profile 网关都能获得完整的监控。
+
+## 快速操作指南
+
+### 验证运行中容器内的 s6 是否为 PID 1
+
+```sh
+docker exec <c> sh -c 'cat /proc/1/comm; readlink /proc/1/exe'
+# Expect: s6-svscan or init / /package/admin/s6/.../s6-svscan
+```
+
+### 检查 profile 网关服务
+
+```sh
+# /command/ isn't on docker-exec PATH — use absolute path
+docker exec <c> /command/s6-svstat /run/service/gateway-<name>
+# "up (pid …) … seconds"            → running
+# "down (exitcode N) … seconds, normally up, want up, …" → s6 wants it up but the process keeps exiting (crash loop)
+# "down … normally up, ready …"     → user stopped it
+```
+
+### 手动启动/停止服务
+
+```sh
+docker exec <c> /command/s6-svc -u /run/service/gateway-<name>   # up
+docker exec <c> /command/s6-svc -d /run/service/gateway-<name>   # down
+docker exec <c> /command/s6-svc -t /run/service/gateway-<name>   # SIGTERM (restart)
+```
+
+### 查看 cont-init 协调器日志
+
+```sh
+docker exec <c> tail -n 50 /opt/data/logs/container-boot.log
+# 2026-05-21T06:18:05+0000 profile=coder prior_state=running action=started
+# 2026-05-21T06:18:05+0000 profile=writer prior_state=stopped action=registered
+```
+
+### 添加新的静态服务
+
+1. 创建 `docker/s6-rc.d/<name>/type`，内容为 `longrun\n`，并创建 `docker/s6-rc.d/<name>/run`（使用 `#!/command/with-contenv sh` + `# shellcheck shell=sh`）。
+2. 在 run 的开头通过 `s6-setuidgid hermes` 降权到 hermes 用户（除非你明确需要 root 权限）。
+3. 创建空的 `docker/s6-rc.d/<name>/dependencies.d/base`，使其等待基础 bundle。
+4. 创建空的 `docker/s6-rc.d/user/contents.d/<name>`，使其加入用户 bundle。
+5. Dockerfile 中的 `COPY docker/s6-rc.d/` 会自动提取它 —— 无需其他更改。
+
+### 更改每个 profile 的网关运行命令
+
+编辑 `hermes_cli/service_manager.py` 中的 `S6ServiceManager._render_run_script`。该函数在引导协调期间也会被 `hermes_cli/container_boot.py::_register_service` 调用，因此它是唯一的真实数据源。请同步更新 `tests/hermes_cli/test_service_manager.py::test_s6_register_creates_service_dir_and_triggers_scan` 中相应的断言。
+
+### 运行 Docker 测试套件
+
+```sh
+docker build -t hermes-agent-harness:latest .
+HERMES_TEST_IMAGE=hermes-agent-harness:latest scripts/run_tests.sh tests/docker/ -v
+# Expect 19 passed, 0 xfailed against the s6 image
+```
+
+测试套件位于 `tests/docker/` 中，当 Docker 不可用时会跳过。单次测试的超时时间提升至 180 秒（见 `tests/docker/conftest.py`）。
+
+## 常见陷阱
+
+### 通过 `docker exec` 提示 "command not found"
+
+`/command/`（s6-overlay 存放其二进制文件的路径）仅在由监控树生成的进程（服务、cont-init.d、main-wrapper.sh）的 PATH 中可用。`docker exec <c> s6-svstat …` 会报错 "command not found" 而失败；请始终使用绝对路径 `/command/s6-svstat`。 `hermes` 二进制文件能正常工作，因为 Dockerfile 将 `/opt/hermes/.venv/bin` 添加到了运行时 `ENV PATH` 中。
+
+### Profile 目录所有权问题
+
+cont-init 协调器以 hermes 身份运行（`02-reconcile-profiles` 中的 `s6-setuidgid hermes`）。如果 profile 目录最终归 root 所有（例如因为 `docker exec <c> hermes profile create …` 默认以 root 身份运行），协调器将无法读取 SOUL.md 并报错 `PermissionError`。缓解措施：`stage2-hook.sh` 会在**每次**引导时以幂等方式将 `$HERMES_HOME/profiles` 的所有者更改为 hermes。不要移除该代码块。
+
+### 通过 `docker exec` 写入的文件归 root 所有
+
+`docker exec` 默认以 root 身份运行。请传递 `--user hermes`，或者等待下次重启时的 stage2 chown 扫描。不要以 root 身份手动在 `$HERMES_HOME/profiles/<name>/` 下写入文件 —— 下次协调过程会清理它们，但正在进行的操作可能会遇到权限错误。
+
+### 服务插槽存在，但 s6-svstat 显示 "s6-supervise not running"
+
+服务目录位于 tmpfs 上，并在容器重启时被清除。要么是 cont-init 协调器尚未运行（在 `docker restart` 后稍等片刻），要么是运行失败了。请检查 `docker logs <c> | grep '02-reconcile'`。
+
+### 网关启动后立即退出（svstat 显示 `down (exitcode 1)`）
+
+最可能的原因是该 profile 未配置模型或身份验证。服务插槽是正确的 —— 网关本身未进行配置。请先运行 `hermes -p <profile> setup`。s6 监控器会不断重启它；这是预期的行为（当你修复配置后，下一次尝试就会成功并保持运行）。
+
+### 协调器跳过了某个 profile
+
+协调器以 **`SOUL.md` 的存在**作为“真实 profile”的标记。`hermes profile create` 总会生成该文件。如果 profile 目录缺少 SOUL.md（如孤立的目录、不完整的恢复、正在进行备份），协调器会故意跳过它。添加一个 `SOUL.md`（即使是空的）即可重新将其纳入。
+
+### “救命，容器以 143 退出了！”
+
+检查是否有程序调用了 `s6-svscanctl -t` 或 `/run/s6/basedir/bin/halt` —— 两者都会导致 /init 开始阶段 3 的关闭，但会返回 143 (SIGTERM) 而不是期望的退出代码。这就是 Phase 2 架构从 A 转向 B 的原因。要使容器以真实的退出代码关闭，你必须让 CMD (main-wrapper.sh) 正常退出；**不要**试图从 finish 脚本控制退出。
+
+## 相关技能
+
+- `hermes-agent-dev`：常规的 hermes-agent 代码库导航
+- `hermes-tool-quirks`：特定的 Hermes 工具变通方案（sed/grep/等） —— 在调试 s6 栈与 hermes 内置工具的交互时加载。