@hyzyn/dsh-docker 0.13.3 → 0.13.5

package/README.md

@@ -11,7 +11,7 @@
 - **显式一键连接本机**：两个**非常驻**入口——一个目标都没有时是「还没有配置 Docker 目标」空态里的主按钮，已有别的目标时是**目标下拉的末一项** `＋ 连接本机`（工具条上**不挂**：常驻时它既占位又招人点，纯噪音）——一次点击（或选中该项）就把宿主所在机器加成本机目标并选中（已有本机目标则直接复用，不重复创建；SSH / 自定义目标原样保留），agent 侧同一条操作是 `docker_connect_local`。它**不**改空 `targets` 的语义、**不**凭空造隐式默认目标、**不**自动装 Docker / 起 daemon / 切 docker context，也不需要任何能力授权（只加一条指向插件自身的本机目标）。
 - **多目标聚合取数**：总览页对全部 `targets[]` 并行请求，单个目标不可达只污染自己那一格；agent 侧同一口径由 `docker_ps target:"*"` / `docker_attention target:"*"` 暴露，跨目标不互相阻塞。
 - **「需关注」读权威字段**：不健康 / 反复重启 / OOM 被杀 / 非零退出 / 僵死；OOM 与真实退出码由一次 `docker inspect` 补齐——`docker ps` 摘要里的 137 分不出 OOM 与手动 kill，只按摘要筛必然误报。
-- **四条 SSE 长流共用一套基建**：日志 FOLLOW、`docker stats`、`docker events`、`docker pull` 走同一个 `openSseStream`（心跳 / 活跃流登记 / 断开清理 / 管道起来后先发一帧 `ready`），差异只在收尾语义——日志与拉取自然结束，统计与事件由前端主动断。「连上了」与「在收数据」是两件事：客户端只认 `ready`，响应头到达不算（见「SSE 事件协议」）。多选聚合日志按 `--timestamps` 前缀还原跨容器真实时序，「暂停」只冻结渲染（流继续接收，恢复时一次性补齐）。
+- **四条 SSE 长流共用一套基建**：日志 FOLLOW、`docker stats`、`docker events`、`docker pull` 走同一个 `openSseStream`（心跳 / 活跃流登记 / 断开清理 / 管道起来后先发一帧 `ready`），差异只在收尾语义——日志与拉取自然结束，统计与事件由前端主动断。「连上了」与「在收数据」是两件事：客户端只认 `ready`，响应头到达不算（见「SSE 事件协议」）。多选 / Compose 项目的聚合日志把多个容器装进**一条** `/logs/stream?ids=…`（D168），按 `--timestamps` 前缀还原跨容器真实时序，「暂停」只冻结渲染（流继续接收，恢复时一次性补齐）。
 - **默认只读，能力开关分三级**：启停删 / exec / 镜像变更各自独立开关，未开启时 agent 工具**不注册**、HTTP 路由 403（能力不存在，而非调用后报错）；开关的**提权走两条带外通道**（启动环境变量 / 卡片里就地确认，见下条）；容器名与 ID 过白名单，命令一律 argv 构造 + 单引号转义，密码 / 口令以 `env:NAME` **凭据引用**（官方凭据层解析，缺失时退回环境变量）且永不回传浏览器。
 - **与 dsh-tty 数据级复用、代码级不耦合**：不 import 任何 tty 代码，tty 也无需改一行源码，两者可各自安装与升级；装了 tty 则消费三个可选扩展点——连接栏动作（`ttyConnbar`）、终端承载（`ttyTerminal`：标签 / dock 承载下经 `open` 新开标签，模态下经 `mount` 就地嵌入抽屉）、以及只在兜底路径用到的终端右侧 dock（`ttyPanel.mountPane`）；未装或版本不足逐项静默降级。
 
@@ -43,8 +43,8 @@ dsh plugin --profile web add link:$(pwd)/packages/docker    # 仓库开发调试
 ```
 
 聚合包 `@hyzyn/dsh-all`（或仓库根 bundle）已包含本插件，一次装齐时不必单独
-add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 → 插件 →
-「Docker 容器面板」卡片维护目标与开关，**保存即热生效**（`settings/updated`
+add。装完重启 `dsh web`，侧边栏出现「容器」入口；「Docker 容器面板」卡片维护目标与开关，
+**保存即热生效**（`settings/updated`
 触发重解析，无需重启）。
 
 > 已在 web profile 里装过 `@hyzyn/dsh-all` 或根 bundle 时**不要**再 add 本包，
@@ -198,10 +198,11 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
   左侧出现勾选框，点卡片本体变成**勾选 / 取消**（不再进详情；动作条暂时收起，
   免得一边多选一边误点启停删），工具条与列表之间出现操作条：「已选 N 个容器」+
   `聚合日志` + `取消`。`聚合日志` 至少需要 2 个容器；选到第 3 个时给一条软提示，
-  超过 **3 个**按钮置灰并提示上限（**上限怎么来的见「已知限制」的浏览器同源连接预算**，
+  超过 **3 个**按钮置灰并提示上限（**上限怎么来的见「已知限制」的聚合上限**，
   操作条上也写着那句说明）。点 `聚合日志`
-  进入聚合视图：直接复用 Compose 项目视图那套聚合日志（每容器一条 `/logs/stream`，
-  按 `[service]` / 容器名前缀混流，带过滤与自动滚动），返回即退出选择态并清空。
+  进入聚合视图：直接复用 Compose 项目视图那套聚合日志（**一条** `/logs/stream?ids=…`
+  装下所有选中容器，帧里带 `id`，按 `[service]` / 容器名前缀混流，带过滤与自动滚动），
+  返回即退出选择态并清空。
   聚合视图的内容控制与**单容器日志完全对齐**（文本过滤 + 级别门槛 + `⬇ .log` / `⬇ .md`
   导出当前显示内容 + 行数统计），另有聚合独有的两项：**按时间 / 按到达**排序、**暂停**冻结
   （暂停时流继续接收、恢复一次性补齐）。
@@ -290,10 +291,10 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
   服务端发 `end`（reason=`stats-exit`），界面提示并自动切回快照轮询。
 - **Compose 项目视图**：工具条第三段切换。把 `composeProject` / `composeService`
   标签聚合成「项目 → 服务 → 容器」，每个项目一行看全运行数 / 不健康数 / 服务数与
-  各容器状态；点进项目可看服务表，或打开**项目级聚合日志**——对项目内每个容器各开
-  一条 `/logs/stream`，客户端按 `[service]` 前缀混流（宿主侧 `logsStream` 本
-  就支持任意容器，无需新接口），带自动滚动开关与过滤框。混流是到达序，不保证跨
-  容器严格时序。
+  各容器状态；点进项目可看服务表，或打开**项目级聚合日志**——**一条**
+  `/logs/stream?ids=…` 装下项目内所有容器（帧里带 `id`），客户端按 `[service]` 前缀
+  混流，带自动滚动开关与过滤框。混流是到达序，不保证跨容器严格时序。某个容器的子流
+  失败只标注「部分出错」，其余容器的日志照常收（连接不关）。
 - **镜像**：`docker images` 列表（reference / 大小 / 创建时间 / 短 ID）；
   `<none>:<none>` 的 dangling 镜像带 `dangling` 标记。搜索框与「N / M 个镜像」
   计数**固定在工具条里**（不随列表滚走），表头列名在表体内吸顶。
@@ -357,7 +358,7 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
 
 `kind=ssh` 有两种填法：
 
-1. **引用 tty 连接簿条目**：`book` 填条目名（在 设置 → 插件 → 终端面板 的
+1. **引用 tty 连接簿条目**：`book` 填条目名（在「终端面板」的
    连接簿里维护），主机 / 端口 / 用户名 / 认证方式随之生效。设置卡片的下拉
    只列出 tty 已保存的连接簿条目；tty 未安装或条目不存在时，该目标解析失败，
    面板与 agent 工具都会给出明确错误。
@@ -427,8 +428,9 @@ context、不改任何环境变量；空 `targets`（= 用户没配）的语义
 
 ### 聚合日志（多选 / Compose 项目）
 
-多选容器或打开一个 Compose 项目，都能把多个容器的日志聚合成一条流（每个容器一条
-`docker logs -f` SSE，客户端按到达顺序混流）。工具栏提供：
+多选容器或打开一个 Compose 项目，都能把多个容器的日志聚合成一条流：**一条**
+`/logs/stream?ids=…` 装下全部容器（帧里带 `id`；宿主侧仍为每个容器各跑一条
+`docker logs -f`），客户端按到达顺序混流。工具栏提供：
 
 | 控件 | 语义 |
 | --- | --- |
@@ -472,7 +474,7 @@ context、不改任何环境变量；空 `targets`（= 用户没配）的语义
 - **排序**：OOM > 僵死 > 不健康 > 反复重启 > 非零退出；同权重按「最近一次结束时间」倒序，
   刚崩的排在最上面（行 hover 显示结束/启动时间、重启次数、退出码）。
 
-## 配置（设置 → 插件 → Docker 容器面板，保存即热生效）
+## 配置（保存即热生效）
 
 未获宿主授权时，设置卡片里那两个开关**点它会就地发起一次授权**：面板给出一条「在宿主终端执行」
 的命令，执行完十秒内自动解锁并替你打开开关（免重启）；面板里另有「另一种方式（最强）」说明
@@ -504,7 +506,6 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 |---|---|
 | `0.2.0-rc.1` 起 | **插件详情页「说明」正下方**（`plugins.bundle.config`，key = **本包自己的** bundle 包名）——设置就在详情页里，不必再点一次「>」进二级页 |
 | `0.1.6` 线 | 侧边栏「插件」→ 该 bundle 的**行** → 「>」行详情（`plugins.row.config`） |
-| `≤0.1.5` | 设置 → 插件 → 该插件的可折叠卡片（`settings.plugin.item`） |
 | 以上各版 | 设置 → **插件配置** 里的同一条目（`settings.kit.item`，由 `@hyzyn/dsh-kit-settings` 提供） |
 
 新宿主上 bundle 槽可用时**不再注册本包那份 row 槽**——同一份表单两个入口只会让人以为有两套设置；
@@ -581,30 +582,36 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 | 工具 | 注册条件 | 参数 | 作用 / 典型用法 |
 | --- | --- | --- | --- |
 | `docker_targets` | 恒注册 | `probe?: boolean` | 列出目标（name / kind / label）；`probe:true` 逐个探测 docker 版本与 daemon 可达性（SSH 目标会建连接，较慢）。其他工具的 `target` 取自这里 |
-| `docker_connect_local` | 恒注册 | —（无参数） | **连接本机**：确保存在一条 `kind=local` 目标并选中它（已存在则复用，不重复创建；SSH / 自定义目标原样保留），随后只读探测 daemon：返回 `{name, kind, created, saved, reachable, serverVersion?}`。没有任何目标时 `docker_ps` 等会报「尚未配置任何 Docker 目标」，用它一步补上。**不需要任何能力授权**（只写插件自己的配置 + 只读探测）；不会安装 Docker / 启动 daemon / 切 context / 改环境变量。daemon 不可达时在结果文本里说清成因（CLI 缺失 / 探测超时 / daemon 未启动 / socket 无权；CLI 缺失时还会点名 PATH 里找到的别的容器 CLI，但不会替你改 dockerBin），不是只报空列表 |
-| `docker_ps` | 恒注册 | `target?`（**传 `*` = 全部目标**）、`all?: boolean` | 列容器（名称 / 状态 / 健康 / 镜像 / 端口 / compose 项目与服务 / 短 ID）；默认只列运行中，`all:true` 含已停止。`target:'*'` 时按目标分组返回，**单个目标不可达不影响其他目标**（该组带 `error`）。端口是 IPv4/IPv6 双栈归并后的映射（同一次 `-p` 不再出现两遍，D130）；`ports` 为空**不等于**没暴露端口——host 网络容器的端口即宿主机端口，这种情况会给 `net` 字段（D131）。排障第一步 |
-| `docker_attention` | 恒注册 | `target?`（支持 `*`）、`limit?: number` | **需关注汇总**：不健康 / 反复重启 / 被 OOM 杀 / 非零退出 / 僵死；每条带 `reasons`、`exitCode`、`oomKilled`、`restartCount`。OOM 与真实退出码来自一次 `docker inspect`（ps 摘要里 137 无法区分手动 kill）。排障入口：不确定从哪台/哪个容器看起时先调它 |
-| `docker_inspect` | 恒注册 | `target?`、`id`（必填） | `docker inspect` 的权威详情：状态 / 健康检查 / 退出码 / 重启次数 / 端口 / 挂载 / 网络 / 启动命令 |
-| `docker_logs` | 恒注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?`、`until?` | `docker logs --tail` 尾部；`since` / `until` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）圈时间窗；超上限标记 `truncated` |
-| `docker_logs_grep` | 恒注册 | `target?`、`id`、`pattern`（必填，≤512 字符）、`regexp?`、`ignoreCase?`、`since?`、`until?`、`context?`（0~20，默认 2）、`limit?`（1~500，默认 200）、`tail?`（缺省 = 扫全部历史）、`timestamps?`（默认开） | **日志服务端检索**：宿主侧逐行过滤（不碰远端 shell、不拼 `\| grep`），返回命中行 + 前后上下文，并如实报告 `matched`（全量命中数，即使没返回）/ `scanned` / `limited` / `truncated`——「只扫到这些」与「扫完了没更多」可区分；扫描窗口**对齐到行边界**（按字节截断处的半行不当作一行返回，所以 `lines` 里每一行都是完整的行）。与 `docker_logs` 的分工：报错就在最近尾部 → `docker_logs`（便宜）；埋在深处 / 特定时间窗 / 找关键词、异常码、请求 ID → 本工具。默认字面子串（grep -F 语义，零 ReDoS），`regexp: true` 才按 JS 正则 |
-| `docker_stats` | 恒注册 | `target?`、`ids?`（逗号分隔的容器名/ID） | `docker stats --no-stream` 快照：CPU% / 内存用量与占比 / 网络 IO / 块 IO / PIDs；`ids` 省略 = 全部运行中容器。实时跟随是面板能力（SSE），工具保持单值快照语义 |
-| `docker_images` | 恒注册 | `target?` | 镜像列表（仓库:标签 / 大小 / 创建时间 / 短 ID） |
-| `docker_events` | 恒注册 | `target?`、`since?`（docker `--since` 语法，默认 `10m`） | 容器事件快照（`docker events --since <d> --until <now>`，同样过服务端白名单）：start / die / stop / kill / oom / health_status / destroy / rename / update 九类，`exec_*` 等噪音已在服务端丢掉。要持续观察请让用户看面板容器列表的「活动」条 |
-| `docker_networks` | 恒注册 | `target?` | 网络列表（名称 / 驱动 / 范围 / 是否 internal / 短 ID）。接入的容器列表不进列表行——详情页会连坐 inspect，列表逐行 inspect 就是 N 次 docker 调用 |
-| `docker_volumes` | 恒注册 | `target?` | 卷列表（名称 / 驱动 / 范围 / 挂载点） |
-| `docker_image_inspect` | 恒注册 | `target?`、`ref`（必填） | `docker image inspect` + `docker history`：大小 / 含父层大小 / 创建时间 / 平台 / 层数与层列表 / 入口与命令 / 暴露端口 / digest / 构建历史（每步命令与大小） |
-| `docker_action` | 仅 `allowMutations` | `target?`、`action`（`start` \| `stop` \| `restart` \| `remove`）、`id` | 容器生命周期操作。`remove` 是破坏性的：删除容器配置与可写层（数据卷不在其中），执行前必须向用户确认目标容器 |
-| `docker_image_remove` | 仅 `allowMutations` | `target?`、`ref`（必填） | 删除镜像（`docker image rm`，不带 `-f`）。**破坏性**：被容器或子镜像引用时会失败；执行前须确认目标镜像并复述后果 |
-| `docker_image_prune` | 仅 `allowMutations` | `target?` | 清理 dangling（无标签）镜像（`docker image prune -f`）。刻意不加 `--all`，只删无标签镜像 |
-| `docker_image_pull` | 仅 `allowMutations` | `target?`、`ref`（必填）、`timeoutSec?`（10~1800，默认 600） | `docker pull` 快照形态（**可能耗时数分钟**）；交互式看逐层进度请让用户到面板镜像页的拉取图标看 SSE 进度流 |
-| `docker_exec` | 仅 `allowExec` | `target?`、`id`、`command`（必填，经容器内 `sh -c` 执行）、`timeoutSec?`（1~120，默认 `execTimeoutSec`） | 一次性 `docker exec`，返回退出码 / stdout / stderr；无 TTY，交互式排障请让用户到 tty 面板跑 `docker exec -it <容器> sh` |
+| `docker_connect_local` | 恒注册 | —（无参数） | **连接本机**：确保存在一条 `kind=local` 目标并选中它（已存在则复用，不重复创建；SSH / 自定义目标原样保留），随后只读探测 daemon：返回 `{name, kind, created, saved, reachable, serverVersion?}`。没有任何目标时其余工具不注册（见下方「零目标」那条），用它一步补上。**不需要任何能力授权**（只写插件自己的配置 + 只读探测）；不会安装 Docker / 启动 daemon / 切 context / 改环境变量。daemon 不可达时在结果文本里说清成因（CLI 缺失 / 探测超时 / daemon 未启动 / socket 无权；CLI 缺失时还会点名 PATH 里找到的别的容器 CLI，但不会替你改 dockerBin），不是只报空列表 |
+| `docker_ps` | 有目标即注册 | `target?`（**传 `*` = 全部目标**）、`all?: boolean`、`limit?`（1~500，默认 100）、`offset?`（默认 0） | 列容器（名称 / 状态 / 健康 / 镜像 / 端口 / compose 项目与服务 / 短 ID）；默认只列运行中，`all:true` 含已停止。`target:'*'` 时按目标分组返回，**单个目标不可达不影响其他目标**（该组带 `error`）。端口是 IPv4/IPv6 双栈归并后的映射（同一次 `-p` 不再出现两遍，D130）；`ports` 为空**不等于**没暴露端口——host 网络容器的端口即宿主机端口，这种情况会给 `net` 字段（D131）。排障第一步 |
+| `docker_attention` | 有目标即注册 | `target?`（支持 `*`）、`limit?: number` | **需关注汇总**：不健康 / 反复重启 / 被 OOM 杀 / 非零退出 / 僵死；每条带 `reasons`、`exitCode`、`oomKilled`、`restartCount`。OOM 与真实退出码来自一次 `docker inspect`（ps 摘要里 137 无法区分手动 kill）。排障入口：不确定从哪台/哪个容器看起时先调它 |
+| `docker_inspect` | 有目标即注册 | `target?`、`id`（必填） | `docker inspect` 的权威详情：状态 / 健康检查 / 退出码 / 重启次数 / 端口 / 挂载 / 网络 / 启动命令 |
+| `docker_logs` | 有目标即注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?`、`until?` | `docker logs --tail` 尾部；`since` / `until` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）圈时间窗；超上限标记 `truncated`；截断时（`truncated`）结果里会说明可传更小的 `tail`、加 `since`/`until`，或改用 `docker_logs_grep` |
+| `docker_logs_grep` | 有目标即注册 | `target?`、`id`、`pattern`（必填，≤512 字符）、`regexp?`、`ignoreCase?`、`since?`、`until?`、`context?`（0~20，默认 2）、`limit?`（1~500，默认 200）、`tail?`（缺省 = 扫全部历史）、`timestamps?`（默认开） | **日志服务端检索**：宿主侧逐行过滤（不碰远端 shell、不拼 `\| grep`），返回命中行 + 前后上下文，并如实报告 `matched`（全量命中数，即使没返回）/ `scanned` / `limited` / `truncated`——「只扫到这些」与「扫完了没更多」可区分；扫描窗口**对齐到行边界**（按字节截断处的半行不当作一行返回，所以 `lines` 里每一行都是完整的行）；返回行数另有上限：最多 4000 行（`MAX_RESULT_LINES`），超了截到上限并给 `truncatedForSize` 与 `notes`（缩小 `limit` / 减小 `context` / 加 `since`·`until` 圈时间窗），`matched` 仍报全量。与 `docker_logs` 的分工：报错就在最近尾部 → `docker_logs`（便宜）；埋在深处 / 特定时间窗 / 找关键词、异常码、请求 ID → 本工具。默认字面子串（grep -F 语义，零 ReDoS），`regexp: true` 才按 JS 正则 |
+| `docker_stats` | 有目标即注册 | `target?`、`ids?`（逗号分隔的容器名/ID） | `docker stats --no-stream` 快照：CPU% / 内存用量与占比 / 网络 IO / 块 IO / PIDs；`ids` 省略 = 全部运行中容器。实时跟随是面板能力（SSE），工具保持单值快照语义 |
+| `docker_images` | 有目标即注册 | `target?`、`limit?`（1~500，默认 100）、`offset?`（默认 0） | 镜像列表（仓库:标签 / 大小 / 创建时间 / 短 ID） |
+| `docker_events` | 有目标即注册 | `target?`、`since?`（docker `--since` 语法，默认 `10m`） | 容器事件快照（`docker events --since <d> --until <now>`，同样过服务端白名单）：start / die / stop / kill / oom / health_status / destroy / rename / update 九类，`exec_*` 等噪音已在服务端丢掉。要持续观察请让用户看面板容器列表的「活动」条 |
+| `docker_networks` | 有目标即注册 | `target?`、`limit?`（1~500，默认 100）、`offset?`（默认 0） | 网络列表（名称 / 驱动 / 范围 / 是否 internal / 短 ID）。接入的容器列表不进列表行——详情页会连坐 inspect，列表逐行 inspect 就是 N 次 docker 调用 |
+| `docker_volumes` | 有目标即注册 | `target?`、`limit?`（1~500，默认 100）、`offset?`（默认 0） | 卷列表（名称 / 驱动 / 范围 / 挂载点） |
+| `docker_image_inspect` | 有目标即注册 | `target?`、`ref`（必填） | `docker image inspect` + `docker history`：大小 / 含父层大小 / 创建时间 / 平台 / 层数与层列表 / 入口与命令 / 暴露端口 / digest / 构建历史（每步命令与大小） |
+| `docker_action` | `allowMutations` + 有目标 | `target?`、`action`（`start` \| `stop` \| `restart` \| `remove`）、`id` | 容器生命周期操作。`remove` 是破坏性的：删除容器配置与可写层（数据卷不在其中），执行前必须向用户确认目标容器 |
+| `docker_image_remove` | `allowMutations` + 有目标 | `target?`、`ref`（必填） | 删除镜像（`docker image rm`，不带 `-f`）。**破坏性**：被容器或子镜像引用时会失败；执行前须确认目标镜像并复述后果 |
+| `docker_image_prune` | `allowMutations` + 有目标 | `target?` | 清理 dangling（无标签）镜像（`docker image prune -f`）。刻意不加 `--all`，只删无标签镜像 |
+| `docker_image_pull` | `allowMutations` + 有目标 | `target?`、`ref`（必填）、`timeoutSec?`（10~1800，默认 600） | `docker pull` 快照形态（**可能耗时数分钟**）；交互式看逐层进度请让用户到面板镜像页的拉取图标看 SSE 进度流 |
+| `docker_exec` | `allowExec` + 有目标 | `target?`、`id`、`command`（必填，经容器内 `sh -c` 执行）、`timeoutSec?`（1~120，默认 `execTimeoutSec`） | 一次性 `docker exec`，返回退出码 / stdout / stderr；无 TTY，交互式排障请让用户到 tty 面板跑 `docker exec -it <容器> sh` |
 
 - `target` 省略时回落到**唯一**已配置目标；配置了多个目标则必填，错误信息会
   列出可用目标名。
+- **零目标时只有 `docker_targets` / `docker_connect_local` 注册**：其余工具没有可寻址对象，
+  注册了只会让模型白试一次；配好目标后**立即补注册**，无需重启。表中标「恒注册」的就是这两条。
+- **四条列表工具支持分页**：`docker_ps` / `docker_images` / `docker_networks` / `docker_volumes`
+  都接受 `limit`（1~500，默认 100）与 `offset`（默认 0），结果带 `total` / `truncated`，
+  截断时渲染文本会给出下一页的 `offset`。分页只解决「结果长到读不下去」，不改变单条
+  docker 命令 512KB 的上限（超了照旧报错）。
 - 两个开关变化会**立即重注册**工具：关掉 `allowMutations` / `allowExec` 后，
   对应工具（含三个镜像变更工具）从 agent 侧消失，无需重启。
-- **已注册的调用还受会话权限档位闸（tier gate）约束**：按类分——`read` 类（上表「恒注册」
-  的全部）全档放行；`docker_action` / `docker_image_remove` / `docker_image_prune` /
+- **已注册的调用还受会话权限档位闸（tier gate）约束**：按类分——`read` 类（上表
+  标「有目标即注册」的读工具）全档放行；`docker_action` / `docker_image_remove` / `docker_image_prune` /
   `docker_image_pull` 归 `write` 类，`docker_exec` 归 `exec` 类，这两类在受限档（仅可查看 /
   工作区内修改）下**每次调用弹授权询问**（人允许这一次才执行；无人值守即审批策略 `never`
   时确定性拒绝），完全权限档零询问，Auto review 档不叠加（宿主的模型预审已在管）。宿主未组合
@@ -616,8 +623,10 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
   `docker_logs_grep` 带 `pattern` / `since` / `until` 检索深处）→
   `docker_inspect` → `docker_stats`；镜像排查 `docker_images` →
   `docker_image_inspect`。
-- `announceToAgent` 开启时，插件向 systemPrompt 注入一段能力公告（含「默认
-  只读」「docker socket ≈ 目标主机 root」的约束提醒），让模型先列目标再动手。
+- `announceToAgent` 开启时，插件向 systemPrompt 注入一段精简公告：插件与面板位置、「默认
+  只读」与「docker socket ≈ 目标主机 root」的约束、「`allowExec` 只管一次性 exec 通道」的
+  边界（卡片「终端」按钮不受它门控）、`target` 的 `*` 适用范围，以及跨工具排障顺序；它不
+  逐条复述工具用法——那是各工具 description 的职责。
 
 ## HTTP 路由（`/api/dsh-docker` 前缀，全部 loopback 围栏）
 
@@ -655,7 +664,7 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 | `/inspect` | POST | `{target?, id}` | `{ok:true, details: ContainerDetail[]}` |
 | `/stats` | POST | `{target?, ids?: string[]}` | `{ok:true, stats: ContainerStats[]}` |
 | `/logs` | POST | `{target?, id, tail?, timestamps?, since?}` | `{ok:true, logs:{id, text, truncated}}` |
-| `/logs/stream` | GET | query：`target?`、`id`（必填）、`tail?`（**0**~5000；`0` = 不补历史只跟随，客户端重连用）、`timestamps?`（`1`/`true`）、`since?` | `200 text/event-stream` 长连接，事件协议见下；参数错误 / 未知目标 / 非 loopback 返回常规 JSON 错误 |
+| `/logs/stream` | GET | query：`target?`、`id`（单容器，与 `ids` 二选一）或 `ids`（逗号分隔的多个容器，**一条连接装下全部**，最多 32 个）、`tail?`（**0**~5000；`0` = 不补历史只跟随，客户端重连用）、`timestamps?`（`1`/`true`）、`since?` | `200 text/event-stream` 长连接，事件协议见下；参数错误 / 未知目标 / 非 loopback 返回常规 JSON 错误 |
 | `/stats/stream` | GET | query：`target?`、`ids?`（逗号分隔；省略 = 全部运行中） | `200 text/event-stream`：每秒一帧 `stats`（ContainerStats，形状与 /stats 快照一致）；不会自然结束，靠客户端断连收尾 |
 | `/events/stream` | GET | query：`target?` | `200 text/event-stream`：一帧 `event` 一个容器事件（服务端已过白名单，值缺失的字段省略）；不会自然结束，靠客户端断连收尾 |
 | `/images` | POST | `{target?}` | `{ok:true, images: ImageSummary[]}` |
@@ -691,17 +700,26 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
 | 事件 | data | 说明 |
 | --- | --- | --- |
 | `ready` | `{}` | **执行器真的起来了**才发一帧（本机子进程 `spawn` / 远端通道已开 = `StreamHandlers.onStart`）：客户端据此才认为「在收数据」。**响应头到达（`onopen`）不算**——响应头由 `flushHeaders()` 立刻写出去，而建连（SSH `acquire` / 远端开通道）可能卡十几秒，目标不可达时干脆只有 `error`。起不来就**没有** `ready` |
-| `line` | `{"d":"..."}` / `{"e":"..."}` | stdout / stderr 分片（不保证按行切，客户端自行拼行）。日志流与拉取流用 |
+| `line` | `{"d":"..."}` / `{"e":"..."}`；多源时 `{"id":"<容器 id>","d"\|"e":"..."}` | stdout / stderr 分片（不保证按行切，客户端自行拼行）。日志流与拉取流用。**`ids=` 多源时每帧带 `id`**，客户端按它把分片派回对应容器 |
+| `source-end` | `{"id":"<容器 id>","code":N\|null}` | **仅多源**：该容器的 `docker logs -f` 自然退出（容器停止）。整条连接**不关**——其余容器照常推；`end` 要等所有源都结束 |
+| `source-error` | `{"id":"<容器 id>","message":"..."}` | **仅多源**：该容器这一条子流失败（spawn 错 / 远端通道被拒）。整条连接也不关，其余容器继续；客户端标注「部分出错」 |
 | `stats` | `ContainerStats` | 统计流专用：每秒每个容器一帧，字段与 `/stats` 快照完全一致。服务端按**扁平 `{...}` 抽取**（`docker stats` 即便 stdout 是管道也走 TTY 渲染器，帧里混着 `ESC[H/ESC[K/ESC[J`，按行解析会整行丢掉）并折叠同一采样的重复渲染，客户端不必再解析 docker 的 PascalCase 字符串 |
 | `event` | `{action, name, image, composeProject?, time?, exitCode?}` | 事件流专用：一帧一个容器事件（白名单外的事件行在服务端就丢了；值为 null 的字段省略） |
-| `end` | `{"reason":"container-exit"\|"stats-exit"\|"events-exit"\|"pull-exit","code":N, ...}` | 执行器自然退出。日志流附容器退出码、统计流 reason=`stats-exit`、事件流 reason=`events-exit`、拉取流附 `ref` |
+| `end` | `{"reason":"container-exit"\|"stats-exit"\|"events-exit"\|"pull-exit","code":N, ...}` | 执行器自然退出。日志流附容器退出码（多源时取**按 `ids` 顺序最后一个非 null** 的退出码，各容器的真实退出码在各自的 `source-end` 里）、统计流 reason=`stats-exit`、事件流 reason=`events-exit`、拉取流附 `ref` |
 | `error` | `{"message":"..."}` | 参数 / 执行失败，随后关闭；连接层断路不会发这个事件 |
 
+**多容器单连接（`ids=`，D168）**：聚合日志（多选 / Compose 项目日志）把 N 个容器塞进
+**一条** SSE——宿主为每个容器各起一条 `docker logs -f`，帧里带 `id` 分流。这样聚合视图
+无论选几个容器都只占浏览器**一条**同源连接（旧实现是每容器一条 `EventSource`，叠加活动条
+的事件流会直接吃满 D165 实测出来的 4 条常驻流）。单源 `id=` 的形状**逐字节未变**：帧不带
+`id`、不发 `source-end`/`source-error`——老客户端仍按原协议解析。`/config` 的
+`streamProtocol` 因此升到 **3**：客户端据此决定走单连接还是退回「每容器一条」。
+
 四条流的差异只有「执行器 + 结束原因」：
 
 | 流 | 执行器 | 自然结束条件 | 关闭语义 |
 | --- | --- | --- | --- |
-| `/logs/stream` | `docker logs --follow` | 容器停止（`container-exit`） | 前端关 FOLLOW / 切页 / 关面板 |
+| `/logs/stream` | `docker logs --follow`（`ids=` 时每个容器各一条） | 容器停止（`container-exit`；多源时全部容器的流都结束） | 前端关 FOLLOW / 切页 / 关面板 |
 | `/stats/stream` | `docker stats`（**无** `--no-stream`） | 全部被统计容器退出（`stats-exit`） | **前端主动断**（这条流不会自己停） |
 | `/events/stream` | `docker events`（`--filter type=container`） | daemon 侧流结束（`events-exit`） | 切页 / 切目标 / 关面板 |
 | `/images/pull/stream` | `docker pull` | 拉取完成 / 失败（`pull-exit`） | 前端离开拉取视图 |
@@ -808,36 +826,40 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
   SSH 长流会占住连接池中的该连接（busy），同一主机上的其它命令复用同一条连接——
   但**不是互不影响**：通道额度是共享的，见下一条。**统计流不会自然结束**，关闭必须
   由前端主动断 `EventSource`。
-- **浏览器的同源连接预算是 4 条常驻流（这是聚合上限的真正依据，D165）**：
+- **浏览器同源连接预算：docker 面板现在最多只占 1 条常驻流（D165 实测 + D168 收口）**：
   宿主是 **HTTP/1.1**（没有 h2 多路复用），浏览器对**每个源**只放这么几条 TCP，而
   **每条 `EventSource` 独占一条连接、且不会主动释放**。吃满之后，同一个页面里
   **所有**普通请求（列表刷新、`/api/*`、会话加载……）一起排队——用户看到的是
-  **整个 DSH 页面卡住**，不只是 docker 面板。
-  实测（2026-10-08，真 Chrome + 真宿主，页内连打 10 次普通请求、2 秒超时）：
-
-  | 常驻流 | 页内请求 | 进程外请求（同一时刻） |
-  |---|---|---|
-  | 0 条 | 10/10 成功，中位 27ms | 26ms |
-  | 4 条 | 8/8 成功，中位 25ms | — |
-  | **5 条** | **0/10 全部超时** | **41ms（正常）** |
-
-  最后一列是关键：**堵在浏览器，不在宿主**。所以常驻流预算取 **4 条**；面板停在容器页时
-  活动条的事件流恒开（占 1 条），聚合日志因此只能用 **3 条**——这就是聚合上限
-  （`PICK_MAX = 4 − 1`）的由来，操作条上写着同一句说明。
+  **整个 DSH 页面卡住**，不只是 docker 面板（实测：常驻流 0/4 条时页面请求正常，
+  **5 条时 10 次全部超时**；完整数据与现场见 [DEFECTS.md](./DEFECTS.md) 的 D165）。
+  docker 面板的常驻流**在任何视图下都只有 1 条**：容器列表 = 活动条事件流；详情 =
+  日志 FOLLOW 或统计 FOLLOW（同一时刻只有一个页签）；聚合 / Compose 项目日志 =
+  **一条** `ids=` 多容器流；拉取 = 一条进度流。**进入详情 / 聚合视图时事件流会主动断开**
+  （列表被整段替掉、活动条不可见），回列表时重连并补一次全量刷新（D168）。
   **这不是「性能建议」而是硬约束**：超了不是「慢一点」，是同页面所有请求一起失效。
-  想自己复核：按上表形状在 devtools 里连开 `new EventSource('/api/dsh-docker/events/stream?target=<目标>')`
-  到第 5 条，再打一次普通请求即可看到它挂住；关掉就恢复。
-  （WebSocket **不**占这份预算——tty 终端那条 WS 与 4 条 SSE 共存时页面仍正常，实测过。）
+  想自己复核：在 devtools 里连开
+  `new EventSource('/api/dsh-docker/events/stream?target=<目标>')` 到第 5 条，再打一次
+  普通请求即可看到它挂住；关掉就恢复。（WebSocket **不**占这份预算——tty 终端那条 WS
+  与 4 条 SSE 共存时页面仍正常，实测过。）
+- **多标签页要按「全部插件加起来」算，不是 docker 一家**：那 6 条连接是整个页面共享的，
+  官方 `dsh-client-hmr`、其它插件的 SSE 都算在内。如果每个标签页里宿主自身就挂着 2 条
+  常驻 SSE，**3 个标签页 = 6 条**，已经到悬崖——这一层不是本插件能改的：真要治本得让
+  宿主换 WebSocket / h2，或让各插件共用一条多路复用连接。docker 这边已经把自家的账压到
+  1 条（见上一条），剩下的要按现场实际装了哪些插件去数。
+- **聚合上限是「可读性 + 宿主通道」的上限，不再是浏览器连接数（D168）**：聚合日志是一条
+  连接装下所有选中容器，所以 `PICK_MAX = 3` 不再由「4 条预算 − 1 条事件流」推出来；
+  保留 3 是因为一屏混三份以上日志会看不清，且每个被选容器在宿主侧仍各跑一条
+  `docker logs -f`（SSH 目标上就是一条 channel，见下一条的 8 条额度）。操作条上写着
+  同一句说明。
 - **SSH 目标上的通道额度是共享的（`MaxSessions`）**：一个目标只维持**一条** TCP 连接，
   所有长流与短命令共用这条连接上的通道，而 OpenSSH 的 `MaxSessions` 默认只有 10。
-  长流（日志 / 统计 / 事件）会一直占到用户关掉面板为止，聚合日志还能一次占 8 条——
-  正好把额度用光，于是紧接着一次「刷新列表」（短命令）就被远端拒绝，报的是
-  `(SSH) Channel open failure: open failed`。所以插件对每个 SSH 目标限制**同时最多
-  8 条长流**（= 10 − 2，留两条给刷新 / inspect 这类短命令），聚合日志在 **SSH 目标**
-  上的可选上限也从 8 收到 6（本地目标走子进程，不受影响）。超限与远端拒通道时给出的
-  都是带指向性的提示，而不是 ssh2 的原始文案。若你的 sshd 调过 `MaxSessions`
-  （`sshd -T | grep maxsessions`），当前上限是编译期常量，需要跟着改就提 issue。
-  折叠右侧栏标签会主动断流、把通道还回去。
+  长流（日志 / 统计 / 事件）会一直占到用户关掉面板为止，聚合日志里每个被选容器仍各占
+  **一条** channel（选中上限 3，所以最坏 3 条）——叠上刷新 / inspect 这类短命令就可能
+  逼近额度，于是远端拒绝时看到的是 `(SSH) Channel open failure: open failed`。所以插件
+  对每个 SSH 目标限制**同时最多 8 条长流**（= 10 − 2，留两条给刷新 / inspect 这类短命令），
+  聚合选择的上限也定在 3。超限与远端拒通道时给出的都是带指向性的提示，而不是 ssh2 的
+  原始文案。若你的 sshd 调过 `MaxSessions`（`sshd -T | grep maxsessions`），当前上限是
+  编译期常量，需要跟着改就提 issue。折叠右侧栏标签会主动断流、把通道还回去。
   （`D150`）这条约束另有两道补救：① **短命令按目标排队** —— 每条连接同时最多 2 条
   并发（`DSH_DOCKER_SHORT_CHANNELS` 可覆盖，仅测试 / 排障），多出来的等前一条收尾，
   不再出现「一次点击（概览 inspect + 日志快照 + 统计快照）就去撞 10 的硬上限」；
@@ -850,7 +872,7 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
   —— `AbortSignal` 触发时除了向远端 `KILL` + 关通道，还会**直接结束这条流**，不再等远端
   回话。原先只等远端的 `close` 事件：远端不确认（上面那种被拒的 KILL，或通道静默）时，
   那条流的 `busy` 计数**永远不会减**，累积到 8 之后该目标的每条长流都被配额拒绝，
-  且没有任何自愈路径（现场：248 上恒满 8/8，活动条点「重连」毫无反应）。同一类坑
+  且没有任何自愈路径（现场与完整因果见 [DEFECTS.md](./DEFECTS.md) 的 D164）。同一类坑
   `run()` 在 `D112` / `D161` 已经踩过两次，现在三条收尾路径统一成「自己 settle」。
   **根治办法在 sshd 一侧**：把那台主机的
   `MaxSessions` 调大 —— 例如 `/etc/ssh/sshd_config.d/10-dsh-maxsessions.conf` 写一行
@@ -956,7 +978,8 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
   │     ├─ 事件 → EventSource /events/stream（SSE：活动条环形缓冲 50 条 +
   │     │   500ms 防抖触发列表重取；重连成功后补一次全量刷新）
   │     ├─ 拉取 → EventSource /images/pull/stream（SSE：逐层进度按层键 upsert）
-  │     └─ 聚合日志 → 项目内每容器一条 /logs/stream，客户端按 [service] 混流
+  │     └─ 聚合日志 → **一条** EventSource /logs/stream?ids=…（多容器共用；帧带 id，
+  │        客户端按 [service] 混流；老宿主退回每容器一条）
   ├─ 可选消费 tty 的 ttyConnbar 服务 → SSH 连接栏「容器」按钮
   │   （按 book 名 / host:port 匹配已配置目标，命中才出现）
   ├─ 可选消费 tty 的 ttyPanel 服务（0.16.0）→ 终端面板开着时挂右侧 dock
@@ -984,7 +1007,8 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
   │   ├─ loopback 围栏 + assertRef / assertImageRef + tail 夹紧（与快照路由一致）
   │   ├─ 写头 + flushHeaders / 15s ping 心跳 / 活跃流登记 / 前端断开静默 abort
   │   │   管道起来后先发 ready{}（StreamHandlers.onStart：客户端只认它当「在收数据」）
-  │   ├─ /logs/stream：docker logs -f → line{"d"|"e"} + end{container-exit,code}
+  │   ├─ /logs/stream：docker logs -f → line{"d"|"e"} + end{container-exit,code}；
+  │   │   ids= 模式：一条连接 N 个执行器 → line{id,d|e} + 每容器 source-end/source-error
   │   ├─ /stats/stream（只读）：docker stats 逐行归一 → stats{ContainerStats}；
   │   │   不会自然结束，前端断连即 abort，docker stats 自退则 end{stats-exit}
   │   ├─ /events/stream（只读）：docker events --filter type=container →
@@ -996,9 +1020,9 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
   ├─ 网络 / 卷路由：/networks · /volumes 与各自的 inspect（只读）、remove / prune（allowMutations）
   └─ agent 工具：docker_targets / docker_ps / docker_inspect /
      docker_logs（快照语义不变）/ docker_logs_grep（服务端检索）/ docker_stats / docker_events / docker_images /
-     docker_image_inspect / docker_networks / docker_volumes（恒注册）
+     docker_image_inspect / docker_networks / docker_volumes（有目标即注册）
      + docker_action / docker_image_remove / docker_image_prune / docker_image_pull
-       （allowMutations）/ docker_exec（allowExec）
+       （allowMutations + 有目标）/ docker_exec（allowExec + 有目标）
 ```
 
 ## 开发与验收
@@ -1007,7 +1031,7 @@ abort）、客户端断开静默中止，以及**管道起来后先发一帧 `re
 pnpm --filter @hyzyn/dsh-docker build       # tsc → lib/（宿主半体）+ esbuild → client.js（浏览器半体）
 pnpm --filter @hyzyn/dsh-docker typecheck
 pnpm --filter @hyzyn/dsh-docker smoke       # 三套离线回归，都不需要 docker daemon（项数以脚本尾部自报为准）
-pnpm test                                    # 仓库级 vitest（含本包 config-route / current-session / session-target / logs-stream / streams / ssh-stream-budget / ssh-connect 共七套）
+pnpm test                                    # 仓库级 vitest（本包 test/ 下的用例都在里面；项数以运行输出为准）
 ```
 
 > **改了哪一半、怎么才生效**（踩过两次的坑）：
@@ -1022,235 +1046,10 @@ pnpm test                                    # 仓库级 vitest（含本包 conf
 > 逻辑全都不生效，看起来像「改了没用」。判断依据是**文案**——宿主侧新增的提示语如果没出现，
 > 那就是旧进程。
 
-`scripts/smoke.mjs`（读取 `lib/` 构建产物，项数以脚本尾部自报为准）覆盖纯逻辑：ps 解析（字段映射 /
-compose 标签 / 端口 / `State` 缺失推导 / 噪声行 / JSON 数组）、端口串解析与去重、
-stats 解析（百分比 / 内存 / IO / PIDs）、size 与 percent 的异常输入、images 解析
-（dangling）、**image inspect / history（JSON 与纯文本表格两条路径）解析**、
-inspect 解析（状态 / 健康 / 退出码 / 挂载 / 网络 / 端口 / 缺字段不抛异常）、
-`assertRef` / **`assertImageRef`（放行 registry/digest、拒绝 flag 与注入）** 注入
-拒绝、`assertBin`、`formatBytes`、`shJoin` 转义、`DockerApi` 的 argv 构造
-（ps / logs / action / exec / probe 成败 / **image inspect·rm·prune·pull·statsStream·pullStream**）、
-`normalizeConfig` 默认值与夹紧、`sanitizeTargets` / `sanitizeHostKeys`、
-`resolveTarget` 的四种路径、`mergeTargetSecrets` 的凭证保留语义。
-
-`scripts/route-smoke.mjs` 用**假 cordis ctx + 假 docker CLI 脚本**跑端到端：
-插件挂载（settings / 工具 / 路由 / 能力公告注册）、**27 条路由**的实际调用与返回
-（含 `/logs/stream`、`/stats/stream`、`/events/stream`、`/images/pull/stream` 四条 SSE
-的事件序列与参数校验，事件流另断噪音被白名单丢掉）、`docker_events` 工具的快照
-输出与 `since` 字符集校验、`/images/inspect` 的详情 + 构建历史、`/config` 凭证脱敏、未知配置键
-400、默认只读时 `/action`、`/exec` 与镜像变更（remove / prune / pull 流）403 且
-对应工具不注册、打开开关后（含 `settings/updated` 热更新路径）立即解锁、非
-loopback 403（含三条流路由）、容器名 / 镜像引用注入尝试被白名单拒绝、省略
-`target` 的回落与多目标报错、禁用后流路由 403。
-
-`scripts/client-smoke.mjs` 在 Node 里用最小 DOM / React 桩执行构建产物
-`client.js`：验证注册 id 与 factory 形状、只 require 平台 seed 提供的模块
-（`react` / `react/jsx-runtime` / `react-dom/client`）、`apply` 注册的 settings
-卡片 key 等于命名空间 `docker`、找不到宿主侧边栏时安静降级且卸载可重复调用，ttyConnbar 集成的四条路径（连接簿名命中 / host:port 命中 / 未配置主机不加按钮 / tty 未安装静默跳过），FOLLOW 的 SSE 订阅与「回到底部」交互（静态断言），**镜像详情 / 拉取流 / 删除 / prune 入口**、**统计 FOLLOW + sparkline 钩子**、**Compose 分组与聚合日志**、**「活动」条装配 + 事件环形缓冲 / 动作标签 / 防抖**（纯逻辑经 `__events` 测试缝），以及侧边栏折叠态（`data-sidebar-collapsed`）隐藏入口标签的样式规则。
-需要真 daemon 的验证走下面的手工清单。
-
-`test/logs-stream.test.ts`（例数不写死，`vitest run` 的输出是唯一真相源）覆盖日志实时流的四层：
-`logsStream` 的 argv 构造与 `assertRef` 白名单、SSE 帧的单行 JSON 封装（换行 /
-多字节）、本地流生命周期（假 spawn：跨 chunk 多字节、SIGTERM→SIGKILL 阶梯、
-close resolve、spawn error）与 SSH 长流的 busy 计数配对 / sweeper 跳过、以及
-路由层的事件序列 / 心跳 / 客户端断开静默中止 / 插件禁用统一收尾，以及
-**`ready` 只在 `spawn` 之后发**（响应头已 flush 也一帧不发，且排在第一条日志行前面）、
-**`tail=0` 只跟随不补历史**（D133）、**背压不重写已写过的帧**与**积压时丢最旧 + `skip` 通知、
-不掐流**（D153）、**skip 账目精确**（D156：skip 排队期间再丢弃，两段缺口都要报——
-46 块逐块对账「每一帧要么送达、要么被 skip 记账」）、
-**中止长流后 `busy` 必须归零**（D164：远端不确认关通道、累积 8 次都不会把目标钉死，
-且收尾后的分片不再投递）、
-以及**分片合帧**（D151：十个分片只出一个 `line` 帧；未到窗口就收尾时 `end` 仍排在
-这些行之后）、**`ready` 帧只在管道起来后发**（统计 / 事件 / 拉取三条路由各一例：
-`spawn` 之前一帧都没有——响应头已经 flush 了也不算；另两例钉住「`ready` 排在第一条
-数据帧前面」与「起不来（`spawn` 失败）不发 `ready`」）。合帧器本身的规则（窗口合并 /
-攒满即推 / flush 幂等 / dispose 停表）在 `test/sse-coalesce.test.ts`（6 例）。
-
-`test/log-window.test.ts`（17 例）覆盖**窗口化挂载的纯逻辑**（D152，`client-src/log-window.js`）：
-实测高度进缓存而没量过的行用估算、`layout` 非贴底时的窗口定位与上下垫高自洽、贴底时锚到
-列表尾部且下垫为 0（贴底判定精确的前提）、`reanchor` 只在锚点上方行高变化时产生等量补偿、
-`offsetOf` 与「淘汰头部后补偿量 = 被淘汰行总高」（D154 跨代锚点的数学）、
-缓存 FIFO 淘汰与空表边界。真 DOM 那一层（量高、锚点修正、贴底钉住）由性能门禁在真 Chrome
-里验证，离线侧另有 `scripts/client-smoke.mjs` 的 `__logWindow` 缝。
-
-`pnpm --filter @hyzyn/dsh-docker perf:logs`（`scripts/log-perf.mjs`）是**日志页的浏览器侧
-性能门禁**：用真 Chrome 量四个场景——「5000 行首屏耗时 / DOM 规模」、「FOLLOW 突发 20000 行
-的处理耗时与事件循环最大延迟」、「事件洪泛」（同一 6.2k 行/秒下每事件 1 行 vs 每事件 50 行，
-量的就是 D151 合掉的那笔每事件固定开销）、以及「**持续洪泛** 20k 行/秒 × 6s」的稳态
-（缓冲满了之后每帧都在淘汰 + 插入，这才是用户报的「日志一快整页就卡」），并**校验两件容易被误解的事**：① 快照被「输出上限（KB）」字节闸截断时**必须有**「已截断」黄色横幅
-（否则「LINES 选 1000 只回来 985 行」会被当成丢行——实测那 985 行是 docker 自己的记录粒度，不是丢行）；
-② 「上滚暂停跟随」只认**真手势**（wheel / 触摸 / 滚动条 / 键盘）：真手势上滚必须出现
-「回到底部」且点一下能恢复，没有手势的位置漂移（洪泛里的夹紧/抖动）**必须不停跟随**；
-③ **洪泛中驻留历史**（D154）：跟随流没停、缓冲还在淘汰最旧的行时驻留 1.2s，可见区顶行
-必须还是同一行（环形缓冲淘汰的位移没补偿的话，读历史会自动「倒带」）；**换代**
-（D155）：快照先刷成一代会折行的高行并扫位量进缓存、再刷回普通行，垫高必须由**这一代**
-的高度算出来（不作废缓存则滚动高虚高 35644px）；
-④ **校验窗口算得对**：
-快照内容是确定的，滚到顶第一行必须是 `seq=0`、滚到底最后一行必须是 `seq=4999`，洪泛结束后
-最后一行必须是最新行（贴底跟随还生效）。超预算即非零退出。D152 之后的实测：
-5000 行快照 179ms / **229 个正文节点**（此前 ~10000）、挂 53~57 行；突发 20k 行 933ms /
-最大延迟 **2ms**（此前 52~97ms）；事件洪泛 10ms vs 7ms；持续洪泛 20k 行/秒 × 6s
-最大延迟 **6ms**、>50ms 长帧 **0 个**（此前 70~97ms / 25~26 个）、213 节点。预算里另有一条
-「挂载行数 ≤ 200」——虚拟滚动失效会立刻变红。它依赖 tty 的预览夹具
-（`node packages/tty/scripts/preview.mjs` 生成），夹具或 Chrome 缺失时**跳过并 exit 0**
-—— 它是 npm script，不是 vitest 必跑项。
-
-`test/streams.test.ts`（46 例）覆盖**统计流 / 事件流 / 拉取流 / 网络卷 / 通用 SSE 基建**：
-`statsStream` 不带 `--no-stream`（与快照同一构造点）、`pullStream` 的
-`assertImageRef` 白名单、`/stats/stream` 把逐行 JSON（含跨 chunk 的半行）归一成
-`stats` 事件且形状与 `/stats` 快照一致、心跳、客户端断开静默中止、
-`eventsStream` 的 argv（无 `--since` / `--until`，带 `type=container` 过滤）与
-`events()` 快照的 `--since` + `--until`（不传 until 会永不退出）、
-`parseContainerEvent` 的白名单 / 坏行丢弃 / health_status 后缀 / 字段抽取 /
-`status` 老字段兼容、`/events/stream` 的事件序列与跨 chunk 半行、
-`/images/pull/stream` 的 allowMutations 门禁（403 不建流）/ `pull-exit` 收尾 /
-禁用时统一收尾、**`assertName` 的校验矩阵（`/` 与 `:` 必须被拒——这两条正是
-`assertImageRef` 会放行的）、网络 / 卷的 ls·inspect·rm·prune argv（prune 必带 `-f`）、
-network / volume 的 ls·inspect 解析容错（字符串布尔、缺 `Mountpoint` 的老版本、
-空输出 / 坏行）、`/networks` 与 `/volumes` 八条端点的门控（未开门 remove/prune 403、
-缺 name 400、非法名 500）**，以及 `formatBytes`。
-
-### 手工验收清单
-
-1. **本机目标**：加一条 `kind=local` 的 `本机`，`probe` 返回 server 版本；
-   容器列表与 `docker ps -a` 一致（含已停止容器）。
-2. **SSH 目标**：tty 连接簿里已有条目时，用 `book` 引用它 → 容器列表 / 详情 /
-   日志正常；首次连接日志里出现「已记录 host key 指纹（TOFU）」，第二次不再
-   提示；手动改掉 `hostKeys` 里的指纹后重连，应**被拒绝**并给出重置指引。
-3. **一键连接本机**（两处入口都要试）：
-   - **没有目标时**：把目标全部删空保存（或用一个全新 profile），打开面板 → 正文空态里
-     有一个「连接本机」主按钮，**下拉里不该重复列**这一项 → 点一下应当出现一条
-     `kind=local` 的 `local` 并立刻选中、容器列表出来；
-   - **已有别的目标时**：留着几台 SSH，打开目标下拉 → 末一项是 `＋ 连接本机`，
-     **工具条上不该有**任何常驻入口 → 选中该项，应当同样加上 `local` 并切过去，
-     且该项随即从下拉里消失（已经有本机目标了）。
-   两处都**不该**出现「同一个入口列了两次」；全程**不该**有任何 Docker 安装 / daemon 启动 /
-   context 切换动作。宿主上没有 docker 时，应当看到一句点名的原因（CLI 缺失 / 探测超时 /
-   daemon 未启动 / socket 无权访问），而不是一个空列表。
-   - **只有 podman 的机器**（把 PATH 里的 docker 拿掉、只留 podman）：那句话应当
-     **点名 podman** 并说明「把『docker CLI』填成 podman 就能用」，同时**不该**替你
-     改 `dockerBin`（回头去设置卡片看，值仍是 `docker`）。
-4. **只读拦截**：两个开关都关时，`/action`、`/exec`、`/images/remove`、
-   `/images/prune`、`/images/pull/stream` 全部 403；agent 侧恒注册 13 个只读工具
-   （`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` /
-   `logs_grep` / `stats` / `events` / `images` / `image_inspect` / `networks` / `volumes`，数量以工具表为准），
-   面板的启停删 / 镜像删除 / 清理 / 拉取按钮置灰。打开「允许变更操作」后这些
-   路由与工具立即出现（无需重启）。
-5. **日志 / 统计 / 镜像**：`tail` 与 `timestamps` / `since` 生效；统计显示
-   CPU、内存、网络与块 IO；镜像列表含 dangling 条目标记。
-6. **FOLLOW 实时日志流**：日志页打开 `FOLLOW` → 状态行先「正在连接」后
-   「实时跟随中」，`docker logs -f` 的新行即时出现（`docker run --rm alpine sh
-   -c 'i=0; while :; do echo line-$i; i=$((i+1)); sleep 1; done'` 可观察）；
-   高吞吐护栏：换成长行快速打印（如 `head -c 2000 /dev/zero | tr "\\0" x; echo` 循环）
-   页面应保持可交互、内存平稳，行数 / 字节超限时出现「已丢弃最早内容」提示；
-   开 FOLLOW 时 `AUTO REFRESH` 置灰、轮询停止；向上滚动出现「回到底部」、
-   点击回到底部并恢复自动贴底；关闭 FOLLOW 立即回到快照。停掉容器 → 流收到
-   `end` 提示「容器已退出（退出码 N）」并自动补一次快照。杀掉 `dsh web` 再拉起
-   （或热改插件配置）→ 状态行短暂「正在重连」后自愈，不弹错误横幅。SSH 目标
-   同样跑一遍，确认流跑着时同一主机的 `docker ps` 面板操作不受影响（连接复用），
-   且空闲回收（120s）不会掐断流。
-7. **统计实时跟随**：统计页打开 `FOLLOW` →「正在连接统计流…」→「实时跟随中
-   （docker stats）」，CPU / 内存 sparkline 每秒长一点（跑 `docker run --rm
-   alpine sh -c 'while :; do :; done'` 观察 CPU 起来）；关 FOLLOW 立即回快照并
-   恢复轮询。停掉被统计的容器 → 流收到 `end`（stats-exit）提示后自动回轮询。
-   注意**这条流不会自然结束**：切页 / 关面板必须断掉 `EventSource`（宿主侧应
-   看到 `docker stats` 被 SIGTERM）。
-8. **镜像详情 / 删除 / 清理**：镜像页点某行「详情」→ 概览里的层数与
-   `docker image inspect` 一致、构建历史与 `docker history` 一致（Docker ≥ 26
-   走 `--format`，老版本走纯文本表格兜底）；dangling 行用镜像 ID 查。点「删除」→
-   二次确认后执行 `docker image rm`；删除被容器引用的镜像应失败并给出提示。
-   「清理 dangling」只删无标签镜像，输出末尾带 `Total reclaimed space`。
-9. **拉取进度流**：镜像页工具条的拉取图标（悬停显示「拉取镜像」）→ 输入本地没有的小镜像（如 `alpine:3.20`）
-   → 逐层状态行实时出现且按层原地更新；完成后提示「拉取完成」并自动刷新列表。
-   拉取中点「停止」或离开视图 → `docker pull` 被 SIGTERM 结束，不残留进程。
-   未开启「允许变更操作」时该按钮置灰、直接访问 `/images/pull/stream` 返回 403。
-10. **Compose 项目视图**：用一份 compose 起两三个服务（`docker compose up -d`）→
-   工具条切到「Compose」→ 服务归到一个项目卡片下，运行数 / 服务数 / 状态正确；
-   点进项目看服务表，切「聚合日志」→ 各服务日志按 `[service]` 前缀混流出现
-   （`docker compose logs -f` 的等价物），过滤框可按服务名与内容过滤；关「自动
-   滚动」后新日志继续进缓冲但视图不跳。无 compose 标签的容器归入
-   「（非 compose 容器）」。
-11. **`allowMutations` 打开后**：stop / start / restart 成功；对运行中容器
-    remove 报错并附「先停止再删除」提示，先 stop 再 remove 成功。
-12. **`allowExec` 打开后**：`ls -la /app` 之类命令返回 stdout 与退出码；把命令
-    换成 `sleep 60`（`timeoutSec` 调小）应被中断并报超时；`command` 超过 8000
-    字符被拒绝。
-13. **exec 抽屉与正文共存**（tty ≥ 0.15）：卡片「终端」开抽屉后切到日志 / 统计 /
-   另一台容器的详情，抽屉与终端会话都必须活着；**折叠**（箭头或双击顶边）把抽屉
-   压成一条标题栏、会话继续跑（展开即回原样）；**拖拽顶边**能调高度且不超过面板
-   的 75%；此时点 backdrop 空白处或面板 ✕ 应弹「结束容器终端会话」确认，取消后
-   会话仍在，确认才结束（tty 侧收到 kill）。
-   离线回归：`node packages/tty/scripts/preview.mjs docker-exec-logs`
-   （无头 Chrome 跑真实客户端：抽屉 + 日志页 + 折叠展开，断言会话未被结束）。
-14. **从连接栏进容器面板（dock 模式，需 tty ≥ 0.16）**：tty 面板里开一个 SSH 标签 →
-   连接栏「容器」→ 容器面板应挂在**终端右侧**（不是全屏弹窗），终端仍可输入；
-   拖左边缘可调宽（上限面板宽 72%）、标题栏箭头折叠成窄条（终端拿回全部宽度、
-   容器面板不卸载）、✕ 收起面板且 SSH 标签不受影响；此时点卡片「终端」应在同一
-   终端面板**新开一个 `<容器> · exec` 标签**，而不是再嵌一个终端抽屉。
-   离线回归：`node packages/tty/scripts/preview.mjs docker-dock`
-   （断言 docked / 无 backdrop / 折叠后终端变宽 / 容器面板存活）。
-15. **多选聚合日志**：容器列表点 `聚合选择` → 卡片左侧出现勾选框、卡片动作条收起；
-   勾 2~3 个容器 → 操作条显示「已选 3 个容器」，点 `聚合日志` → 聚合视图标题为
-   「聚合日志 · 3 个容器」，三条流按 `[service]` / 容器名前缀混流出现；只勾 1 个时
-   按钮置灰并提示「至少选择 2 个容器」，勾到 9 个时置灰并提示最多 8 个；列表里
-   停掉其中一个容器 → 该条流走原有 `end` 语义结束，其余流不受影响。
-16. **Esc 退出选择态**：选择态下按 Esc → 回到普通列表、勾选清空、动作条消失；
-   再点一次 `聚合选择`（此时标签是 `退出选择`）效果相同；切目标 / 切分段 / 关面板
-   也都会把选择态和勾选一起清掉。
-17. **事件活动条**：容器列表头部出现「活动」条，状态点先黄后绿、文案「实时接收中
-   （docker events）」；执行 `docker restart <容器>` / `docker stop`+`start` → 1 秒内
-   列表状态跟着变，活动条出现 `stop` / `start`（异常退出显示 `die(137)` 这种带码
-   形式）；点标题可折叠（事件流不中断，展开后仍是累积的最新 8 条）；
-   `docker exec` 连续几次**不产生任何事件**（`exec_*` 已被服务端白名单丢掉）；
-   断网 / 重启 `dsh web` 后恢复时状态点短暂黄色并自动补一次全量列表刷新。
-   **不得出现假绿**（2026-10-11 现场）：把某个目标的 SSH 地址改成黑洞地址（或在目标
-   不可达时打开面板）→ 状态点必须是**黄色**的「正在连接事件流…」，只有宿主确认
-   `docker events` 起来（`ready` 帧）才转绿；连不上时最终落到红色的「事件流已断开」+
-   「重连」按钮。日志 / 统计 / 拉取三条流同理（建连期间各自停在「正在连接…」，不会
-   先说「实时跟随中 / 实时接收中 / 正在拉取」）。
-   另有一条**不许卡死**：宿主半体仍是旧代码（例如宿主进程还没重启、`/config` 里没有
-   `streamProtocol`）而浏览器已加载新 `client.js` 时，活动条必须退回旧判据并点亮——
-   不能永远停在「正在连接事件流…」。
-18. **网络 / 卷**：工具条分段出现「网络」「卷」。网络列表应含 `bridge` / `host` / `none`
-   与 compose 创建的项目网络；点某条进详情 → 概览里子网 / 网关与 `docker network
-   inspect` 一致、`internal` 网络带徽标，「接入的容器」页签列出容器名与 IPv4。
-   卷列表的挂载点与 `docker volume ls` 一致（超长路径省略、悬停看全量）。
-   未开「允许变更操作」时两个 prune 图标与详情里的删除键都是灰的；打开后：
-   删除一个没有容器接入的网络成功、删一个还在用的网络报错并给出提示；
-   卷清理会弹带「数据会一起删除」的确认框。**注意**：卷清理在 docker < 23 上会连
-   命名卷一起删，先在测试目标上确认为妙。
-
-19. **多目标总览**：配两个以上目标（本机 + 一台 SSH）→ 目标选择器旁出现 `总览` pill，
-   点进去一屏出现两张计数卡（各带「本机」/「SSH」徽标）与异常区；卡片数字与该目标
-   容器列表的口径一致。把其中一个目标的 SSH 地址改错（或停掉远端 docker）再刷新 →
-   只有那张卡描红、顶部出现「1 个目标不可达」，另一张卡照常显示结果，**页面不会**
-   等 SSH 超时才出内容（渐进落地）。点异常行 → 落到那台主机上该容器的详情，返回后是
-   **该目标**的容器列表而不是总览；点计数卡 → 该目标的容器列表。全部正常时异常区显示
-   「一切正常」；还有目标没答完时显示「读取中…」。打开「自动刷新」→ 按
-   `pollIntervalSec` 轮询全部目标（关掉即停）。
-20. **切目标不串台（列表写入闸）**：让 目标1（不可达的 SSH）先失败出「操作失败」横幅，
-   随即切到正常的目标2 → 横幅应**随切换立即消失**、列表是 目标2 的容器；再等 20s
-   让 目标1 的超时响应**在其之后**才回来 → 横幅不得重新出现、列表也不得被换成
-   目标1 的容器。从总览点 目标1 那张红色计数卡进去，同样不该看到上一个目标的失败。
-   反向验证：切到目标2 后立刻切回目标1（它仍然连不上）→ 横幅应写的是目标1 自己的
-   失败，而不是把目标2 的成功结果当成了目标1 的。
-21. **`docker_logs_grep` 服务端检索**（2026-10-09 真机实测的口径）：起一个日志内容已知的容器
-   （用本地已有镜像即可，不必联网）：
-   `docker run -d --rm --name dsh-grep-probe <本地镜像> sh -c 'echo "[boot] starting"; for i in 1 2 3 4 5; do echo "tick $i ok"; done; echo "FATAL request-id=REQ-7788"; echo "WARN disk 91%" >&2; sleep 3600'`
-   然后在会话里让 agent 用 `docker_logs_grep` 检索它，**逐项看原始返回值**（别接受转述）：
-   - 找 `FATAL` → 命中 1 行、「扫描 8 行」、命中行标 `>` 且带 ±2 行上下文；
-   - `tick [0-9]+` **不传** `regexp` → 0 命中；传 `regexp=true` → 5 命中（证明默认是**字面**匹配）；
-   - `fatal` 不传 `ignoreCase` → 0；传 `ignoreCase=true` → 1；
-   - `tick` + `limit=1` → 「命中 5 行」但只返回 1 组窗口，并出现「命中超过上限」提示（`limited`）；
-   - `since=1h` 命中 / `until=1h` 与 `since=1s` 各 0 命中**且「扫描 0 行」**（证明 `--since`/`--until` 真透传）；
-   - 找 `WARN` → 命中行的 stream 是 `[err]`；
-   - 检索不存在的容器 → 报 docker 原文错误，**不是**空结果。
-   `truncated` 只能用 **>8MB** 日志逼出来（扫描侧 8MB 硬下限，调小「输出上限（KB）」没用）：
-   让容器打 ~30 万行、探针分别写在**最开头**与**最末尾** → 全量扫时前者 0 命中 + 「扫描输出超过
-   字节上限」提示，后者命中 + 同一提示；加 `tail=5000` 后两者都不再出现该提示（证明它报的是
-   扫描侧**真溢出**，不是「日志大就恒 true」）。另外**返回的每一行都必须是完整行**（带时间戳
-   前缀）：字节闸的切口会切在行中间，`lineAlign` 负责丢掉那个半行（见 ROADMAP 的真机验收补正）
-   —— 看到 `g line 174798` 这种没时间戳的碎片，就是这条回归了。
+验证面分三层：**三套离线 smoke**（不需要 docker daemon）、**本包的 vitest 套件**、
+以及**真 daemon 的手工验收清单**。逐项的覆盖范围、浏览器侧性能门槛与手工步骤见
+[docs/verification.md](./docs/verification.md)——README 只留「怎么跑」，清单不在这里重复
+（同一事实两处全文是债，见 [conventions § 文档分层](../../docs/conventions.md#文档分层)）。
 
 ## 版本 / 许可证