@hyzyn/dsh-docker
中文 | English
DSH 侧边栏「容器」面板：本机与 SSH 主机的容器一屏巡检——读日志、看资源、进容器、启停删，默认只读。
特性
- 常驻会话右侧栏：面板作为会话右侧栏标签（
sidebar.right.pane.tab）与对话同屏——发完错误交给 Agent 后日志留在右边，不影响看它干活；折叠即退出视野、不占屏。面板级状态（目标 / 视图 / 过滤词 / 选中容器及它的页签）跨会话保留，而折叠会主动断流、把 SSH 通道还回去。拿不到右侧栏服务的老宿主自动退回原有的 dock / 模态，行为与旧版一致。
- 日志右键交给 Agent：日志页拖选报错行 → 右键「直接发送到当前会话 / 填入输入框，我先改改」，把「选中的行 + 目标 / 容器 / 时间窗 + 前后各 20 行上下文」交给会话（内容会进模型上下文，菜单里明写了留意凭证）。投递成功有两处回执：视口级 toast（挂
body，盖过面板与终端弹窗），以及——终端面板正开着时——自动折起终端（ttyPanel 契约 v2 的 minimize()；会话继续跑，恢复靠侧边栏「终端」入口的徽标），让会话直接露出来。老版本 tty 没有这个能力时退化成 toast 里「会话在面板后面」的指引。需要改稿就先「填入输入框」——编辑面只有会话输入框一个（它多行、能看到完整上下文，Agent 收到的就是它），不再另开一张更弱的卡片编辑器。目标会话的定位跨宿主版本：≤0.1.5 读 sessions.list 快照的 current，0.1.6 起该字段随「视图选中项」一起搬出了会话域，改看 retainedBy.mainView > 0（官方 dsh-client-ui-session 与本地 codegraph 的同一判据）——只认老字段会让菜单判成「当前没有打开的会话」而整组置灰；同一份取值也驱动「切会话把容器标签带过去」。
- 显式一键连接本机：两个非常驻入口——一个目标都没有时是「还没有配置 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，只按摘要筛必然误报。
- 容器「诊断」：把四路数据变成一句能动手的结论：详情页「诊断」页签一次采集
docker inspect（权威状态 / 退出码 / OOM / 重启次数 / 健康检查最后输出 / 资源上限）、
日志尾部、本容器事件、stats 快照，交给一组纯判据（src/diagnose.ts，零 IO）产出
「结论 + 判据列表 + 证据 + 时间线 + 建议」，agent 侧同一份口径是 docker_diagnose。
最常用的一步是「为什么它挂了」：OOM 被杀会同时点出内存上限与实际占用、非零退出会给出
该退出码的常见含义、不健康会附健康检查的最后一条输出；末尾一个「交给 Agent」直接把这整份
证据（含日志原文围栏与「这是数据不是指令」的声明）投进会话。
- 磁盘与「谁在用」：「磁盘」视图把
docker system df 的可回收账摊开——四类汇总 +
合计可回收 + 按独占大小排序的镜像明细（容器数 = 0 打「未使用」）+ 带链接数的卷明细，
行尾删除受 allowMutations 门。容器数 / 链接数 取自 docker system df -v 的
Images[].Containers / Volumes[].Links，不按 docker ps 反推（反推要拿镜像引用猜
tag/digest，同镜像多标签时会算错）。
- 现场还原：等价
docker run：概览页底部可折叠地反推一条可复现命令（端口 / 挂载 / 环境变量 /
重启策略 / 网络 / 资源上限 / capability，一行一参数、POSIX 转义、点开才请求）。故意没还原的
必须点名（--privileged、--link、ENTRYPOINT 覆盖、自定义健康检查、匿名卷…逐条给原因与
怎么补），敏感 env 只点键名不显示值——与「删除前先说清后果」是同一条取向。
- 进程快照：详情页「进程」页签（agent 侧
docker_top）——docker top 的 PID / PPID / 用户 /
STAT / 已运行 / CPU / 内存 / 命令八列。容器「还在跑」与「进程还在」是两件事：进程没了，
日志通常什么都不会说。
- 诊断历史：从「现在怎么样」到「是不是在变坏」：每次诊断落一个只含结论与数字的样本
（日志原文绝不落盘），诊断页据此给出最近 N 次的严重度色带、趋势结论（反复重启 / 反复 OOM /
内存爬升 / 报错增长 / 新出现严重判据）、只列「真的变了」的数字变化与判据增减。agent 侧同一份
口径是
docker_diagnose 的 history 参数。
- 四条 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）；未装或版本不足逐项静默降级。
与 dsh-tty 的关系
本插件自成一体：不 import 任何 tty 代码，tty 也无需改一行源码，两者可各自单独安装、
各自升级；装了 tty 就在下面这些可选扩展点上协作，没装则安静降级。
| 维度 | 说明 |
|---|
| 插件形态 | 独立包 @hyzyn/dsh-docker，不 import 任何 tty 代码，tty 也无需改一行源码；两者可各自单独安装、各自升级 |
| 连接簿 | SSH 目标可引用 tty 连接簿条目名（只读 ctx.settings.get('tty') 的 sshHosts）；tty 未安装时退化为「内联 host/username」或本机目标 |
| 主机指纹 | 本插件自持一份 hostKeys（TOFU），并优先以 tty 已记录的指纹作种子——同一主机不必在两处各确认一次 |
| 执行通道 | 自持池化 SSH exec（src/ssh-exec.ts），与 tty 的 PTY 会话完全独立，互不占名额 |
| 上下文入口 | tty ≥ 0.13.0 时可选消费其客户端服务 ttyConnbar，在 SSH 连接栏（SFTP 旁）插入「容器」按钮（注册即显示），目标在点击时按当前会话解析；本插件自己开的 exec 标签除外——那种标签正是从容器面板点进来的，再给一个回去的入口等于绕回原地（判定走 spawnSpec.command，用户手敲的 docker exec -it 不算）；tty 未装 / 版本过旧则静默跳过 |
| 面板承载 | 默认走会话右侧栏标签（sidebar.right.pane.tab）：面板与对话同屏，折叠即退出视野、不占屏；框架侧边栏的入口只负责打开或聚焦它，页类型在同一栏内去重，反复点不会开出第二个。终端连接栏的入口相反——它长在盖满视口的 tty 弹窗上，开标签会被挡住，所以那条走 ttyPanel.mountPane 停靠到终端右侧（入口决定承载）；投递日志给会话后经 ttyPanel.minimize()（契约 v2）折起终端，把舞台让给会话。拿不到右侧栏服务（老版本 DSH）、或把 localStorage['dsh-docker:carrier'] 置成 modal 时，侧边栏入口也回退到 dock（tty 开着时）或自带 backdrop 的全屏模态。三种承载是同一个组件，只是外壳与几何不同 |
| 终端承载 | 交互式终端由 tty 承载（它才是 PTY 的所有者）。右侧栏标签：面板全屏（sidebar.fullscreen）时经 ttyTerminal.mount 就地嵌入面板底部（宽度够、日志与 shell 同屏），否则经 ttyTerminal.open 在终端面板新开标签（同一容器重复点会聚焦已有标签，不再堆重复——tty 契约 v3 的 reuse）（栏太窄，硬塞两头难受）；dock 承载（面板已经长在 tty 里）一律开标签；模态承载就地嵌入。那两类命令标签（spawnSpec.command 非空）在 tty 侧不显示连接栏的扩展按钮区（SFTP / 隧道 / 第三方面板都作用于连接本身，挂在 docker exec 标签上会误导——SFTP 浏览的是宿主机，不是用户以为的容器内）；本插件另有一道版本无关的兜底：自己开的 exec 标签不给「容器」入口（按 spawnSpec.command 前缀判定）。未装 tty 或版本不足时复制命令兜底。本插件不实现 PTY / xterm / 重连栈 |
| 分工 | 交互式排障（docker exec -it、容器内 shell、TUI）由 tty 承载（抽屉内嵌或标签）；只读巡检与 agent 自动化用本插件自己的 exec 通道 |
数据级复用、代码级不耦合：连接簿与指纹种子是「读同一份 settings」，连接栏按钮是
「消费一个通用扩展点」，都不是「依赖 tty 的模块」，因此 tty 升级或卸载都不会连带
弄坏本插件。
安装
dsh plugin --profile web add @hyzyn/dsh-docker # npm 安装（发布后）
dsh plugin --profile web add link:$(pwd)/packages/docker # 仓库开发调试
聚合包 @hyzyn/dsh-all（或仓库根 bundle）已包含本插件，一次装齐时不必单独
add。装完重启 dsh web，侧边栏出现「容器」入口；「Docker 容器面板」卡片维护目标与开关，
保存即热生效（settings/updated
触发重解析，无需重启）。
已在 web profile 里装过 @hyzyn/dsh-all 或根 bundle 时不要再 add 本包，
否则插件行重复挂载，启动报 duplicate loader entry id。
使用
两个入口，同一个面板。默认承载是会话右侧栏标签——入口只负责打开或聚焦它，
面板与对话同屏：发完错误交给 Agent 后，日志留在右边、不影响看它干活。
右侧栏标签承载：会话与容器面板同屏、面板全高；折叠即退出视野，不占屏
- 侧边栏「容器」（总入口）：任何目标都能用，包括本机 docker 与多目标切换。
已打开则聚焦（页类型在同一栏内去重），不会开出第二个「Docker 容器」标签。
- 投递后去哪儿看：右侧栏标签承载下会话就在旁边；docked / 模态下发送成功后终端会自动
折起（会话照旧跑着，点侧边栏「终端」入口的徽标恢复），于是你直接落在会话里——不必对着
一个盖住会话的弹窗猜「点了没有反应」。
- SSH 连接栏「容器」按钮（上下文快捷方式，tty ≥ 0.13.0）：在 tty 终端面板的
SSH 标签里，连接栏 SFTP 按钮旁会出现「容器」——注册即显示，点击直接用
当前会话那台主机打开面板，不用再选目标。目标解析发生在点击时：会话来自
连接簿时按条目名匹配，否则按
host:port 匹配已解析的目标；没配到目标也不会
藏按钮——面板会带一条提示告诉你会话主机（含连接簿名）该去设置卡片怎么配。
这条路径走终端右侧的 dock，不开右侧栏标签——按钮长在 tty 弹窗上，而弹窗盖满
视口，开标签会被整个挡住、看着像「点了没反应」。目标照旧带进面板并重挂到那台主机。
于是规则是「入口决定承载」：框架侧边栏点 → 右侧栏标签（与对话同屏）；
终端弹窗里点 → 终端右侧 dock（与终端同屏）。
dock 面板归属点它的那个标签（tty ≥ 0.18.4）：切到别的 SSH 标签时整块收起
（React 树与轮询都保活，切回来恢复原样），关掉该标签则一并收掉；别的标签上再点
「容器」会用那台主机的目标重开一块。收起 ≠ 关掉：tty 不重挂，面板状态不丢。
承载形态
| 承载 | 何时用 | 行为 |
|---|
| 会话右侧栏标签（默认） | 宿主提供 sidebarRight / sidebarRightTabs | 与会话同屏；折叠=退出视野但不丢状态（面板级状态按模块保留，见下）；支持右侧栏的 fullscreen 铺满 |
| 终端右侧 dock | 从终端连接栏的「容器」按钮进来（按钮就在 tty 弹窗上，标签会被它挡住），或拿不到右侧栏服务 / localStorage['dsh-docker:carrier'] = 'modal' 且 tty ≥ 0.16 面板开着 | 挂在终端面板右侧（拖宽 / 折叠 / ✕ 由 tty 提供，终端继续可用）；同一时刻只挂一个，挂上去会收掉前一个（例如 tty 自己的 SFTP）；tty ≥ 0.18.4 起归属点它的那个标签：切走收起、切回恢复、标签关掉一并收掉（收起期间 React 树与轮询保活） |
| 全屏模态（兜底） | 上面两条都不成立 | 自带 backdrop、点击外部关闭；面板 z-index 高于 tty 弹窗 |
回滚到旧形态只要在控制台执行 localStorage.setItem('dsh-docker:carrier', 'modal')
（removeItem 恢复默认）。这个开关是临时灰度用的，所以刻意没进 settings——不值得为
它连带改宿主配置结构、设置卡片与文档。
状态保留：面板看的是主机、不是工作区，所以 view / 过滤词 / 选中容器（含概览-
日志-统计页签）/ 目标都是跨会话保留的；容器详情内部的日志过滤与 LINES 开关跟具体
容器绑定，不保留。折叠标签会断开全部实时流（把 SSH 通道还回去），展开时重连——
单容器与聚合建流本来就带 tail，历史会自己补回来。
跨会话粘性：DSH 右侧栏的标签记录本身是会话作用域的（sidebar.right.pane.tab 与
rightbar.session 都声明 scope: 'session'），A 会话开的标签在 B 会话里并不存在。可
容器面板看的是主机，「切个会话它就没了」是纯损失，所以插件额外记了一个「用户希望它开着」
的意图：切会话时自动在新会话里把标签重开，只有你点了标签的 ✕ 才停止——也就是
「面板跟人走，而不是跟会话走」。那个 ✕ 是宿主执行的（sidebarRight 自己摘标签），
所以「用户关掉了」这件事必须经 registerCloseHandler 登记才收得到：只靠面板自己的
onClose 会漏掉它，于是刚关掉的标签会在每次切会话时自己回来。
dock 兜底形态（终端右侧栏）：
docker 面板挂进终端面板右侧 dock：终端保持可见可用
这条路径打开的面板不会盖住终端：tty ≥ 0.16 时它挂在终端面板右侧的 dock 里
（可拖宽、可折叠成窄条、✕ 收起），终端照常敲命令。dock 模式下卡片「终端」按钮改为
在同一终端面板新开标签执行 docker exec -it（面板已经在一个终端里了，再嵌一层
没有意义）；同时不再渲染面板自己的头部——标题与 ✕ 由侧栏标题栏承担，刷新与只读
徽标并到工具条末尾并靠右（刷新中图标自己转，不再另挂 spinner）：左端留给目标 /
视图 / 搜索 / 筛选这些「过滤类」控件，刷新不会被当成第一个筛选项，位置也与非 dock
模式头部里一致；520px 窄栏里不会白留一条空行。
面板内：
容器列表：目标选择 / 搜索与状态筛选 / 卡片动作条（查看 · 变更两组）
-
切目标有过渡与保护：选择器一变，下方仍是上一个目标的卡片（远端一次往返最长 20s）。
过渡层的三条原则——不推版、有方向感、少灰：
- 面板正文顶部一条 2px 不定长流光进度条（绝对定位）给「正在取数」的全局信号；
- 正文顶部居中浮出一枚蓝色胶囊（与 dsh-rss 的加载胶囊同一套位置与配色语言）：
底色
color-mix(accent 12%, surface)、描边 accent 42%、文字与旋转图标走 --dk-accent；
可见文案只两段 ⟳ 正在切换到 目标2 · 当前显示：目标1（不写成一句话、不用引号裹目标名），
完整的「为什么点不动」放 title，需要时 hover 就有；
- 旧数据保持 82% + 轻度去色（不是压暗到看不清）并锁住指针：读起来是「另一批
内容」而不是「坏了」，同时避免照着旧列表操作——那会拿新目标当目标、用旧列表的容器
ID 发命令，真能停掉对端同名容器；
- 新数据 8px 上滑 + 淡入 200ms 落地，让「换了一批内容」看得见；动效尊重
prefers-reduced-motion。
以上全部绝对定位：切换过程中首卡位置与滚动高度实测完全不变（横幅方案会把内容整块
推下去）。切换失败则清空旧列表并归到新目标的错误态（不继续展示别的目标的数据），
空态文案也会区分「读取失败」与「筛选过窄」。
-
目标选择：面板先选目标（来自配置 targets，本机 / SSH）；只配置了一个
目标时默认选中它，agent 工具也可以省略 target 参数。
会记住上次选的目标（存浏览器 localStorage 的 dsh-docker:last-target，不落
配置、不进 settings）：下次打开面板自动选中它。优先级是连接栏指定 > 上次记住的
（且仍存在）> 列表第一个——记住的目标被删掉/改名后会自动退回第一个，不会停在
「未知目标」上；从终端连接栏的「容器」按钮进来时，当前会话主机优先于记忆值。换目标是整段上下文切换：
上一个目标还在飞的请求一律作废（列表写入闸），不会出现「选择器已经是目标2、卡片
还是目标1 的容器」这种串台，也不会让旧目标的超时横幅停在新目标的页面上。
-
多目标总览（只读）：目标选择器旁的 总览 pill（配了 ≥2 个目标才出现）——不选
目标，一屏看全部主机：上面一行计数卡（目标名 + 本机 / SSH 标识 + 运行中 /
已停止 / 不健康），下面异常容器置顶表（容器名 / 目标 / 状态 / 镜像；不健康排在
重启中之前，同级按目标在配置里的顺序，跨轮询不跳行）。取数是并行 + 渐进落地：
每个目标独立发一次 POST /containers（all:true，裸 docker ps 不返回 exited，
「已停止」会永远是 0），一个目标不可达只影响它自己那一格——卡片描红 + 顶部一条
「N 个目标不可达」横幅，其余目标的结果照常显示（刻意不用 Promise.all 汇总：
SSH 不可达要等 readyTimeout 20s，汇总等于让整页静默 20s）。点计数卡回到该目标的
常规容器列表，点异常行进该容器详情（返回落到该目标的容器列表）；总览不做任何
跨目标操作，异常表的行上没有动作按钮。进总览时会清掉「当前这个目标」遗留的
失败横幅：总览按目标归因（红卡 + 不可达横幅），不再叠一条单目标的「操作失败」——
同一个 SSH 超时被讲两遍，看着像两台机器都挂了。轮询复用工具条的「自动刷新」开关（默认关）：
这一页每轮是全 N 个目标各一次 docker ps，比任何单目标页都贵。没有异常显示
「一切正常」；还有目标没答完时，异常区显示「读取中…」、那张计数卡也进入读取态
（转圈 + 压暗，不出 0/0/0——「0 个容器」会被读成「这台机器没容器」，而它只是还没答）
（「还不知道」不等于「没问题」）。
-
容器列表：名称 / 状态 / 健康态 / 镜像 / 端口映射 / compose 项目与服务 /
短 ID；支持按名称或镜像搜索、按状态筛选（运行中 / 已停止 / 全部），
以及自动刷新（按 pollIntervalSec 轮询，切到镜像页会暂停且不显示该开关——
镜像变化慢，没必要每 5s 跑一次 ；切回容器页原设置照旧生效）。
工具条里「含已停止」与「自动刷新」是的两个开关，搜索框是其中唯一可伸缩的项：
宽面板下整条工具条收成一行，窄栏（dock 520px）里才按组换行——不会出现一行只有
一个复选框的孤行。
日志页：级别着色 + 常驻过滤框 + 行数统计
- 统计：
docker stats --no-stream 快照（CPU% / 内存用量与占比 / 网络 IO /
块 IO / PIDs），面板按 pollIntervalSec 轮询刷新。统计页还有 FOLLOW 实时
跟随：打开后切到 GET /api/dsh-docker/stats/stream（服务端跑不带
--no-stream 的 docker stats，每秒一行），浏览器侧留 60 个点的环形
缓冲画 CPU / 内存迷你趋势图（sparkline）。与日志流不同，这条流不会
自然结束，关闭语义是前端主动断 EventSource；docker stats 自己退出时
服务端发 end（reason=stats-exit），界面提示并自动切回快照轮询。
- Compose 项目视图：工具条第三段切换。把
composeProject / composeService
标签聚合成「项目 → 服务 → 容器」，每个项目一行看全运行数 / 不健康数 / 服务数与
各容器状态；点进项目可看服务表，或打开项目级聚合日志——一条
/logs/stream?ids=… 装下项目内所有容器（帧里带 id），客户端按 [service] 前缀
混流，带自动滚动开关与过滤框。混流是到达序，不保证跨容器严格时序。某个容器的子流
失败只标注「部分出错」，其余容器的日志照常收（连接不关）。
- 镜像：
docker images 列表（reference / 大小 / 创建时间 / 短 ID）；
<none>:<none> 的 dangling 镜像带 dangling 标记。搜索框与「N / M 个镜像」
计数固定在工具条里（不随列表滚走），表头列名在表体内吸顶。
每行有「详情 / 删除」两个动作：详情打开整栏视图（概览：大小 / 含父层 /
创建 / 平台 / 层数 / 入口与命令 / 暴露端口 / digest / 标签；构建历史：
docker history 的逐层命令与大小）。删除（需 allowMutations）二次确认
后执行 docker image rm（不带 -f，镜像被引用时会失败并给出「先删相关
容器」的提示）。
- 网络 / 卷：工具条分段扩到「容器 / 镜像 / Compose / 网络 / 卷」（最后一段是「磁盘」，见「磁盘与可回收」）
（窄栏里放不下时分段容器自己横向滚动，不做二级菜单）。两页都是「表格 + 整栏详情」
的同构布局：
- 网络：名称 / 驱动 / 范围 / internal 徽标 / ID，行点击进详情——概览（ID / 驱动 /
范围 / 创建 / 子网 / 网关 / internal·attachable·ingress·ipv6 / 选项 / 标签）与
「接入的容器」页签（容器 / IPv4 / IPv6 / MAC）。容器数刻意不进列表行：
docker network inspect 才能拿到接入列表，列表逐行 inspect 就是 N 次 docker 调用，
改成点进详情取一次。
- 卷：名称 / 驱动 / 范围 / 挂载点（超长路径限宽省略，title 给全量），详情为
名称 / 驱动 / 范围 / 挂载点 / 创建 / 选项 / 标签（卷没有反向索引，只有概览一页）。
- 详情页头部有删除按钮，两页工具条各有 prune 图标，都受
allowMutations
门控（未开启时置灰 + title 说明），点击后二次确认；删除失败（网络还有容器接着 /
卷还被占用 / 403）在详情页就地弹横幅，不会静默。
- 自动刷新与镜像页一致：这两页不轮询（清单变化慢，5s 一次 docker CLI 是白烧），
切页 / 切目标时才刷。
- 拉取镜像（SSE 进度流）：镜像页工具条的拉取图标（需
allowMutations）
打开拉取视图，输入引用后走 GET /api/dsh-docker/images/pull/stream
（服务端跑 docker pull）——逐层进度（Pulling fs layer / Downloading /
Extracting / Pull complete）实时出现；进度行按「层键」原地更新，TTY 下的
刷新也不会让缓冲区越滚越长。工具条上的「清理 dangling」执行
，（刻意不加 ，避免误删未
使用的普通镜像）。
镜像页：搜索框固定在工具条，表头吸顶
-
一次性 exec：allowExec 开启后可输入命令，等价
docker exec <容器> sh -c "<命令>"，返回退出码与 stdout/stderr（无 TTY）。
-
交互式终端（卡片第一个图标）：跑 docker exec -it '<容器>' sh。按 tty 能力
三级降级——
exec 终端抽屉 + 日志页共存：折叠只藏起来、会话保持运行
- 就地嵌入（tty ≥ 0.15，推荐）：在面板底部开一个终端抽屉，由 tty 的
ttyTerminal.mount 把终端挂进来。面板不收起，看着容器日志直接进容器敲命令，
上下文不断。抽屉会挤占正文高度，所以它可以让位而不结束会话：
折叠（标题栏右侧的箭头，或双击顶边）只把抽屉压成一条标题栏，会话照旧跑着；
拖拽顶边可调高度（上限为面板高度的 75%）。真正结束会话的动作只有两个——
抽屉上的 ✕，以及关闭面板；有活动会话时关闭面板会先弹确认，避免点 backdrop
空白处时误杀一个正在排障的容器 shell（全局终端面板也是「点空白 = 最小化」，同一取向）。
- 借 tty 弹窗开标签（tty ≥ 0.14）：tty 新开一个标签执行同一命令，随后收起本
面板（本面板 z-index 更高，不收起用户只会觉得「点了没反应」）。
- 复制命令：未装 tty / 版本过旧 / 内联目标用了 key·password 认证（浏览器端
没有凭证）时，退化为复制该命令并提示到终端面板粘贴。
本地目标开本地会话，SSH 目标按连接簿条目名（或 agent 认证的内联字段）走 SSH，
标签/抽屉标题为 <容器> · exec。能力判断走服务契约版本
（ttyTerminal.version >= 2 才有 mount），不是猜函数存不存在。
目标（本机 / SSH）
kind | 说明 |
|---|
local | 宿主所在机器上的 docker CLI（spawn 直接执行，不经 shell） |
ssh | 经 ssh2 连到远程主机，在远程执行 docker CLI（argv 经单引号转义） |
kind=ssh 有两种填法：
- 引用 tty 连接簿条目：
book 填条目名（在「终端面板」的
连接簿里维护），主机 / 端口 / 用户名 / 认证方式随之生效。设置卡片的下拉
只列出 tty 已保存的连接簿条目；tty 未安装或条目不存在时，该目标解析失败，
面板与 agent 工具都会给出明确错误。
- 内联字段：
host + username 必填，其余按需（port / auth /
keyPath / password / passphrase / agentForward）。
目标解析是每次操作现算的：在 tty 卡片里改了连接簿条目（换端口、改密码），
下一次操作立即用新值，无需重启。远端需要满足：装了 docker CLI，且当前账号
免 sudo 可用 docker（通常在 docker 组），否则 probe 会原样透出
permission denied while trying to connect to the Docker daemon socket
之类的错误。
连接本机（一键）
不想手填目标时，UI 里有两个入口，都不做常驻：
| 何时 | 入口在哪 |
|---|
| 一个目标都没有 | 面板正文的空态里一个 连接本机 主按钮（那时整块是空的，一键就是最短路径） |
| 已经有别的目标 | 目标下拉的末一项 ＋ 连接本机——就在你找机器的地方，点开才出现 |
两处互斥（不会同一个入口出现两次）：没有目标时走空态那个大按钮；有目标时下拉里才有那一项。
已经有本机目标时两处都不出现（选择器里已经有那台本机了，再列一项等于重复）。
agent 侧同一件事是 docker_connect_local 工具，HTTP 侧是 POST /connect-local——
所有入口共用宿主里同一份实现。
为什么不做成常驻的工具条按钮：常驻一个「连接本机」既占掉目标选择器右边的位置，又要靠
强调色招人点，而已经有可用目标时它是纯噪音（第一版就是常驻的，用户当场指出多余）。
但只留空态那一个入口又会漏掉「手上有几台 SSH、想再加一台本机」这种常见情况——所以
第二个入口放进下拉，只有在真的去找机器时才出现。
| 情况 | 行为 |
|---|
已有一条 kind=local 目标（无论叫什么名字） | 复用它（created:false），只切过去；不新建、不重写、不改名 |
| 没有本机目标 | 用稳定名 local 追加到列表末尾；local 已被别的目标占用时依次试 local-2、local-3…（确定性、不冲突、不覆盖） |
| 已有 SSH / 自定义目标 | 原样保留（含顺序与凭据）；只在末尾追加本机那条 |
| 重复点 / 并发点 | 幂等：最终只有一条本机目标 |
| 设置存储不可用 / 保存失败 | 明确报错（503 / 500 + 原因），不改内存配置——不会出现「界面上加上了、刷新就没了」 |
写盘成功之后顺带做一次只读探测（docker version），结果放进响应的 message：
daemon 可达时给出服务端版本；不可达时把成因说清楚——docker CLI 缺失（去装 Docker，
或把「docker CLI」改成正确路径）/ 探测超时（daemon 卡死，或 docker context 指向了
连不上的远端；用 docker context ls 看当前指向）/ daemon 未启动（Linux
systemctl start docker，macOS / Windows 启动 Docker Desktop）/ socket 无权访问
（账号加入 docker 组），而不是只回一句「没有容器」。探测失败不算这次操作失败
（目标确实加上了，reachable:false 单独表示），下次 daemon 起来就能直接用。
探测用的二进制就是设置卡片里的「docker CLI」（dockerBin，默认 docker）。
CLI 缺失时会只读地在 PATH 里找一下别的容器 CLI（docker → podman → nerdctl），
找到就在那句话里点名（「这台机器上装了 podman：把『docker CLI』填成 podman 就能用」）——
只提示，绝不替你改配置：静默改写 dockerBin 会违背本插件「不替用户决定」的取向，
而且 podman 与本插件输出格式的兼容性并未逐项验证（见「已知限制」）。比对候选时按
工具名（basename）而不是配置里的原字符串，所以 dockerBin 写成
/usr/local/bin/docker 时不会出现「把 docker 改成 docker」这种废话。
超时是独立一档：probe() 不只报退出码（code 为 null 时那句「退出码 null」对用户
零信息量），而是回 timedOut:true + 一句可执行的话。超时还会真的按时返回——
SIGKILL 只作用于直接子进程，dockerBin 指向包装脚本时孙进程仍握着管道，会把手上的
15 秒上限拖成分钟级（真机实测 3 秒上限拖到 60 秒），所以到点先杀、再给 500ms 收敛期，
仍不 close 就自行放掉管道收尾。
刻意不做的事（保守边界）：不自动安装 Docker、不启动 daemon、不切换 docker
context、不改任何环境变量；空 targets（= 用户没配）的语义不变，不产生隐式默认目标；
clearTargets 的防误清空逻辑一字未动。这条路径也与能力开关无关——它只写插件
自己的配置，不涉及任何需要授权的目标侧写操作。
聚合日志（多选 / Compose 项目）
多选容器或打开一个 Compose 项目，都能把多个容器的日志聚合成一条流：一条
/logs/stream?ids=… 装下全部容器（帧里带 id；宿主侧仍为每个容器各跑一条
docker logs -f），客户端按到达顺序混流。工具栏提供：
| 控件 | 语义 |
|---|
| 实时 / 已暂停 | 真暂停（见下） |
| 时间戳 | 显示每行时间戳。时间戳始终随流接收（timestamps=1），只影响显示 |
| 按到达 / 按时间 | 按到达：零延迟跟随；按时间：用每行的容器时间戳合并成一条真时间线 |
| 级别过滤 | 全部级别 / WARN+ / ERROR+。无级别前缀的行（堆栈等续行）继承上一条日志的级别，所以 ERROR+ 会连它的堆栈一起保留、INFO 的续行一起滤掉；窗口开头的孤儿续行（记录头在窗口外）无从判断，保留 |
| ⬇ .log / ⬇ .md | 导出当前显示内容：.log 是纯行文本（[服务] ISO时间 正文），.md 带来源容器 / 行数 / 导出时间表头，可直接当工单附件 |
按时间合并怎么做的：SSE 各容器建连有先后，A 的首屏历史可能整批先到、B 随后才到，
只对单批排序修不了跨批逆序。实现是回填最近 400 行——每批新行到达时把「最近 400 行 +
新行」整体按时间戳重排（docker logs --timestamps 的 RFC3339 前缀为排序依据，解析后从
正文里剥掉）。这样既不为了让首屏正确而先憋一段时间（不会开页白屏 1 秒），又能事后纠正
历史错序；代价是「按时间」模式下已在屏上的最近若干行可能轻微重排（正在跟随实时输出时
建议用「按到达」）。
聚合日志的「暂停」（真暂停）
多选容器 / Compose 项目的聚合日志有一个 实时 / 已暂停 开关。暂停是内容冻结，不只是停止自动滚动：
- 暂停期间新到的日志进入客户端缓冲，DOM 不再追加——读屏不会被顶走；也不会因为显示上限
（2000 行）裁掉前部而跳屏；
- 按钮上直接显示攒了多少行（
已暂停 +348）；
- 恢复时把缓冲一次性并入（沿用 5000 行环形上限）并回到底部。
只停「自动滚动」是不够的：标签写着「已暂停」而内容还在长，用户会以为开关坏了；日志量大时
画面还会因裁前部而自己跳。
总览（跨目标）与「需关注」口径
「总览」页一屏铺开全部目标：每个目标一张计数卡（运行中 / 已停止 / 不健康 / 需关注），
下方是跨目标的「需关注容器」表（容器名 / 目标 / 状态 / 原因 / 镜像，点行进详情、点卡切到
该目标的列表）。三条设计约束：
- 渐进落地 + 失败隔离：每个目标独立请求、独立落格；一台 SSH 不可达不会让整页静默，
不可达的目标单独出横幅，其余目标结果照常可用。
- 需关注口径以宿主为准：容器列表与
/attention 并行请求；后者额外做一次 docker inspect，
因此能识别 OOM（OOMKilled） 与真实退出码——ps 摘要里 Exited (137) 分不出是被 OOM
杀还是手动 kill。拿不到 /attention（老版本宿主 / 该目标失败）时退回摘要口径，并在
计数上标注「需关注（粗判）」。
- 排序：OOM > 僵死 > 不健康 > 反复重启 > 非零退出；同权重按「最近一次结束时间」倒序，
刚崩的排在最上面（行 hover 显示结束/启动时间、重启次数、退出码）。
容器诊断（「为什么不行」）
容器详情多一个诊断页签，agent 侧是 docker_diagnose。它一次采集四路——docker inspect
（权威状态 / 退出码 / OOM / 重启次数 / 健康检查最后输出 / 资源上限）、docker logs --tail N、
docker events --since（服务端按 --filter container=<id> 过滤）、docker stats --no-stream——
然后交给一组纯判据（src/diagnose.ts，零 IO、不读时钟）产出：
- 一句话结论（
verdict）：取最高严重度的那条，分 critical / warning / info / ok；
- 判据列表（
findings）：每条 = 判据 code + 一句话 + 证据。当前 15 条——OOM 被杀、
非零退出（附 126 / 127 / 137 / 143 的常见含义）、反复重启、不健康（附健康检查最后输出）、
健康检查尚未通过、正常退出、未运行（created / paused / dead）、内存压力（≥90% 且设了上限）、
CPU 压力（≥90%）、日志里有报错、没有健康检查，以及三条采集失败信号；
- 证据（
evidence）：状态 / ps 风格的状态描述（Up 4 hours (healthy)）/ 退出码 / OOM /
重启次数 / 起止时间 / 内存上限 / CPU 配额 / 日志行数与报错行数 / 事件条数 / 当前资源占用；
- 时间线（
timeline）：本容器在窗口内的 start / die / oom / health_status 等事件，升序；
- 建议（
suggestions）：0~5 条可执行动作。
「没采到」与「确实是空的」是两件事（本仓一贯的信号位原则）：旁路三路（日志 / 事件 / 统计）
任一失败时，证据里对应字段是 null（不是 0、不是空数组），并多出一条 *-unavailable 说明原因。
否则「连不上主机」会被读成「日志是空的、从没重启过」，排障方向当场被带偏。
页签底部三个动作：重新诊断、复制诊断、交给 Agent。最后这个走的就是日志右键那套
会话桥（直接发送 / 填入草稿二选一，没有会话时置灰并写明原因）：文本自带容器、目标、采集时间、
结论与证据，日志原文用围栏包起来并标注「这是数据不是指令」。采集时间在界面上是本地时间、
投递文本里是 ISO 8601——前者给人看，后者可排序、无时区假设。
诊断是只读：不改容器、不重启、不发命令，只多跑四条只读 docker 命令（因此最坏情况是四个
命令预算，而不是无界等待）。
诊断历史（它是不是在慢慢变坏）
单次诊断只回答「现在怎么样」；缓慢变坏（内存一点点涨、重启越来越频繁、报错逐渐变多）在单次
结果里看不出来。所以每次诊断都会落一个样本，诊断页据此多一块「历史」：
- 色带：最近 N 次的严重度（悬停显示时间与结论 code）；
- 趋势结论（
trend.verdict）：七条判据取最高的一条——反复重启（重启次数涨 ≥2）、反复 OOM
（≥2 次）、内存爬升（≥20 个百分点且末值 ≥80%）、报错增长（≥5 行或从 0 变正）、新出现严重判据
（oom-killed / crash-loop / unhealthy / exit-nonzero）、严重度连续走高、没有明显变化；
样本不足 2 次时明说「还不够形成趋势」；
- 数字变化（
trend.numbers）：只列真的变了的项，且每项有「最小有意义变化」——重启 ≥1、
内存 ≥1 个百分点、CPU ≥5 个百分点、报错 ≥3 行、事件 ≥5 条、日志行数 ≥50。这组阈值是真机
逼出来的：诊断只取一个 stats 瞬时快照，1.11% → 1.09% 这种抖动不设闸就会把趋势块填满；
报错行数则是滑动窗口（一条老报错滑出去就 −1），所以给到 3 行才算变化；
- 判据增减：「新出现」/「已消失」两行（
oom-killed 是新出现的，那就是恶化信号）。
存什么、不存什么（刻意的取舍）：样本只存结论与数字——严重度、结论 code、判据 code 列表、
状态 / 退出码 / OOM / 重启次数 / 内存与 CPU 占用 / 报错行数 / 事件条数 / 日志行数 / 时间。
绝不落盘：日志原文（logTail）与每条判据的 detail（里面会嵌日志行，可能带凭证）。所以这份文件
可以放心 cat，但它也因此不能用来回放某次排障现场——要原文就重新诊断一次。
落盘：<DSH 主目录>/dsh-docker/diagnosis-history.jsonl（目录 0700、文件 0600），一行一条。
上限：每个容器 50 条、整文件 2000 条，超了丢最旧并原子重写（临时文件 + rename）。
30 秒去重：同一容器、30 秒内、且严重度 + 结论 + 判据集合 + 重启次数完全相同时不追加
（连点「重新诊断」不该在趋势里制造假波动），界面会写明「本次与上次一致，30 秒内不重复记录」。
DSH_DOCKER_HISTORY_DIR 可覆写目录（测试 / 排障专用），空串视为未设。
三条已知边界：① 容器改名 = 开一段新历史（索引键是「目标 + 容器名」）——比让两段历史混在一起、
趋势说出没发生过的变化好；② 并发追加没加锁（两个诊断同时写可能丢一次更新），历史是辅助信息，
为它加文件锁不值；③ 写盘失败只降级不报错：诊断照常返回、recorded = false、宿主 stdout 留一行。
磁盘与可回收（存储治理）
磁盘是工具条分段的最后一段（容器 / 镜像 / Compose / 网络 / 卷 / 磁盘），agent 侧是 docker_disk_usage。
数据来自两条命令：docker system df（四类汇总）与 docker system df -v（逐项明细）。
- 四张汇总卡：镜像 / 容器 / 本地卷 / 构建缓存各自的条目数、活跃数、占用、可回收
（分类名保留 docker 原文，界面负责翻译）；
- 合计可回收：四类
reclaimable 的字节和（任一行解析不出就给 —，宁可不说也不给错数）；
- 镜像明细（按独占大小降序）：仓库:标签 / 大小 / 独占 / 容器数——
containers === 0
打「未使用」徽标，行尾删除图标（受 allowMutations 门、走既有确认框）；
- 卷明细（按大小降序）：名称 / 驱动 / 大小 / 链接数——
links === 0 同样打「未使用」。
三条刻意的取舍：
- 先排序再截断：真机实测 259 个卷里 258 个是 0B，先截断会把 100 个名额全给空卷，明细表
看起来「全是没用的」而真正占空间的反而没进来；
- 明细上限 100 行，超了在表头写「明细已截断，只显示前 100 行」（工具侧另按 20 行截，
两个
truncated 取或）——截断要留痕，不静默少列；
- 老 docker 只降级不报错：不支持
-v --format '{{json .}}'、或输出被截断/形状不对时，
degraded: true + 一句人话原因，汇总卡照常显示、明细表不渲染（渲染空表会让人以为「没有」）。
磁盘页不轮询（system df -v 比 docker images 贵），也没有 prune 按钮：逐行删除 +
确认框比「一键清空一类」安全，而那类入口已经在镜像 / 卷页的工具条上各有一个。
等价 docker run（现场还原）
概览页底部有一块可折叠的等价 docker run，agent 侧是 docker_run_command。它从 docker inspect
的原始行反推一条可复现命令——不扩 ContainerDetail，因为那会把 env 顺带灌进
docker_inspect 的模型上下文。覆盖：名称、重启策略、端口映射（没绑 hostPort 的用 --expose）、
bind / 命名卷 / tmpfs、非默认网络、环境变量、用户 / 工作目录 / 主机名（等于默认值时省略）、
内存与 CPU 上限、cap-add / cap-drop / device，以及镜像与命令本身。
点开才请求（折叠区展开才打 /run-command），一行一个参数、POSIX 单引号转义，可直接复制。
三条刻意的取舍：
- 环境变量原值保留（改写过就不是等价命令），命中
/(PASS|PWD|SECRET|TOKEN|KEY|CRED|AUTH|PRIVATE)/i 的键名收进 secretKeys：界面在命令上方
给一条「含疑似凭证」的警告，只点键名、不显示值；命令本身不脱敏——脱敏后的命令跑不起来，
而它的用途正是「拿出去跑」；
- 故意没还原的必须点名（
omitted）：--privileged、--link、非默认日志驱动、
--pid/--ipc/--uts、--sysctl、--add-host、--security-opt、特殊挂载类型、匿名卷、
ENTRYPOINT 覆盖、自定义健康检查——逐条给出「为什么没写」与「怎么自己补上」，绝不静默丢；
- compose 管理的容器只是近似：网络别名 / labels / depends_on 不在命令里，界面直说。
配置（保存即热生效）
未获宿主授权时，设置卡片里那两个开关点它会就地发起一次授权：面板给出一条「在宿主终端执行」
的命令，执行完十秒内自动解锁并替你打开开关（免重启）；面板里另有「另一种方式（最强）」说明
启动环境变量的做法。已授权时它们就是普通开关，关掉永远可用（宿主侧不拦降权）。
「配置开着但没授权」会显示「未生效：未获宿主授权」徽标——这个状态最容易被当成插件坏了，
所以必须有个名字。一个能力一行：开关后面跟这个能力自己的授权状态与授权时刻（已授权 · 2026-09-26 22:31:08），
撤销按钮右对齐——两个能力的授权是分开的，并排放会看不出哪个撤销管哪个能力。
两个能力的确认也能一次粘贴搞定：面板开着时再点另一个开关不会顶掉前一块面板（两个能力的
授权本来就互不影响），两块面板纵向堆叠，顶部多出一个「复制全部（N 条）」——它把仍 pending 的
命令按发起顺序用换行符连接后一次复制，用户去宿主终端粘贴一次即可：bash / zsh /
PowerShell / cmd 粘贴多行都逐行执行，所以刻意不用 &&（PowerShell 5.1 不认）或 ;（cmd 不认）
连接。某条过期后，合并按钮只复制仍 pending 的那些；全部解锁（或全部收起）后它自己消失。两个
challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后全部开关自动解锁」、不承诺同一时刻
——倒计时仍是逐面板显示，每块面板的复制 / 重新生成 / 收起也照旧只管自己那一个能力。
为什么显示时刻：带外授权是持久的——宿主重启后它直接生效、不再有任何一次确认。也就是说
「上个月授权的能力今天一开机就开着」这件事不会有任何提示，除非界面与日志说出来。所以宿主启动时会
逐条打一行 [dsh-docker] elevation: load capability=… via=file grantedAt=…（不含 nonce 与路径），
卡片上也把它显示出来。启动环境变量授权没有时刻（它就是启动环境的一部分，编一个假时间更糟），
那一行显示的是「由启动环境变量授权；要撤销需在启动环境里去掉它并重启宿主」。
设置卡片：目标 CRUD、能力开关与参数，保存即热生效
设置面在宿主里的位置随 DSH 版本变，但始终是同一份表单（同一个 settings 命名空间、
同一个写入通道），配置数据与行为逐字节相同：
| 宿主 | 设置面在哪 |
|---|
0.2.0-rc.1 起 | 插件详情页「说明」正下方（plugins.bundle.config，key = 本包自己的 bundle 包名）——设置就在详情页里，不必再点一次「>」进二级页 |
0.1.6 线 | 侧边栏「插件」→ 该 bundle 的行 → 「>」行详情（plugins.row.config） |
| 以上各版 | 设置 → 插件配置 里的同一条目（settings.kit.item，由 @hyzyn/dsh-kit-settings 提供） |
新宿主上 bundle 槽可用时不再注册本包那份 row 槽——同一份表单两个入口只会让人以为有两套设置；
旧宿主（bundle 槽不存在）自动回退到行详情，功能一点不减。聚合包 @hyzyn/dsh-all 例外：它的
plugins.bundle.config key 是所有插件共享的（重复注册会直接抛错），所以挂不了内联位，它在聚合
安装下继续走 row 入口。
配置落在 settings 命名空间 docker，即 ~/.dsh/settings.yaml 的 docker:
段（$DSH_HOME/settings.yaml；DSH 的 settings 文件由宿主 dsh-settings-file
提供）。插件行里的 composition 配置作为 schema base 打底，settings 层覆盖
它；HTTP POST /api/dsh-docker/config 是卡片的写入通道，只接受下表这些键
（未知键返回 400）。
| 项 | 默认 | 说明 |
|---|
enabled | true | 关闭整个插件（保存即热生效：工具立即注销、公告撤下、除 /config 外的数据路由 403；/config 始终可读写——设置卡片就是重新启用的入口。与 tty 不同：tty 是重启生效） |
announceToAgent | true | 是否向 agent 注入能力公告（systemPrompt section plugin:dsh-docker） |
dockerBin | docker | docker CLI 可执行名或路径（podman 可填 podman）；只允许字母、数字与 _ . / \ : - 及内部空格，且不能以 - 开头（Windows 盘符与 \ 必须放行，否则任何绝对路径都填不进来）。「连接本机」的探测用的就是它；填错（CLI 不存在）时那句话会点名 PATH 里找到的别的容器 CLI，但不会替你改这个值 |
allowMutations | false | 允许变更操作：容器 start / stop / restart / remove、镜像删除 / dangling 清理 / 拉取（面板按钮与 docker_action、docker_image_remove、docker_image_prune、docker_image_pull 工具；关闭时 /action、/images/remove、/images/prune、/images/pull/stream 返回 403，对应工具不注册） |
| —（能力授权） | 未授权 | allowMutations / allowExec 有两条提权通道：① 启动环境变量（DSH_DOCKER_ALLOW_MUTATIONS / DSH_DOCKER_ALLOW_EXEC，值为 1 / true / yes / on）——判定源是宿主的启动环境快照，只认继承来的 process 层：写项目 .env 或 ~/.dsh/env.yml 不算授权；② 就地提权（免重启）：在设置卡片点开关 → 面板给出一条「在宿主终端执行」的命令 → 执行后十秒内生效；两个能力各点一次后，面板组顶部会给一个「复制全部（N 条）」（仍 pending 的命令按发起顺序换行连接），终端粘贴一次即可全部解锁（各自探测周期内先后生效，不承诺同一时刻）。HTTP 侧永远可以关掉它们（紧急刹车不能依赖重启），但给 true 而无授权会被 400 拒绝并说清两条路。配置里的 true 不算授权（它与 HTTP 写进去的值存在同一个存储里，分不出来源）。升级影响：升级前靠界面打开的开关会变成关——设环境变量重启，或在卡片里就地确认。为什么：回环围栏与同源证明都拦不住跨站页面与页内脚本（它们能自己填 Sec-Fetch-Site: same-origin），而 docker socket 等价目标主机 root；细节（含拦不住谁）见 architecture.md § 7 |
数值越界会被夹到边界内，类型不符则回落到默认值。
targets[] 字段
| 字段 | 默认 | 说明 |
|---|
name | —（必填） | 目标展示名，唯一；空名或重名条目在保存时被丢弃（≤64 字符） |
kind | local | local 本机 / ssh 远程 |
book | '' | kind=ssh 时引用 tty 连接簿条目名（留空则用下面的内联字段） |
host | '' | 内联主机名或 IP（无 book 时必填） |
port | 22 | SSH 端口（1~65535，越界回落 22） |
username | '' | 内联 SSH 用户名（无 book 时必填） |
auth | agent | agent（走 SSH_AUTH_SOCK）/ key（用 keyPath）/ password（用 password，同时挂 keyboard-interactive） |
keyPath | '' | auth=key 的私钥路径（~ 开头会展开为 home） |
password | '' | auth=password 的密码；建议填 env:NAME 凭据引用 |
passphrase | '' | 私钥口令；建议填 env:NAME 凭据引用 |
agentForward | false | 是否转发本机 ssh-agent（SSH_AUTH_SOCK 存在时生效） |
password / passphrase 里的 env:NAME 是一个凭据引用（这正是官方模式：配置只持引用、
值归 provider），连接时才解析，顺序是：
- 官方凭据层（
ctx.credentials，由 @deepseek-ai/dsh-credentials 提供）——它会叠
file（$DSH_HOME/.credentials.yaml）/ env / project-env / user-env 各层，且
「每次操作重新解析」，所以改完下一个操作即生效、不必重启宿主；
- 服务不可用（老宿主 / 未装该 bundle）或它没有这个引用时，退回
process.env[NAME]。
两边都没有会明确报错并点名两个来源（服务报错也一并带上——否则"凭据服务坏了"会伪装成
"你没配"，那是最难查的一类）。这两个值永不回传浏览器：
配置快照里只给 passwordSet / passphraseSet 两个布尔位。
hostKeys[]（SSH 主机指纹，TOFU）
| 字段 | 说明 |
|---|
host | 主机名或 IP（必填） |
port | 端口，默认 22（按 host:port 唯一） |
fingerprints | 指纹集合（必填，至少一条）：hostHash: 'sha256' 回调收到的原样十六进制指纹。同一 host:port 可含多把主机密钥（rsa / ed25519 …），命中任意一条即视为匹配 |
fingerprint | 旧版单指纹字段（字符串）：只作迁移输入，清洗时并入 fingerprints，新配置不要再用 |
首次连接自动记录并落盘；之后每次连接必须匹配，指纹变更直接拒绝连接，
错误信息带「删除该主机记录再重连」的指引。记录列表在设置卡片里可删除重置
（删除会以显式的 hostKeysRemove: [{host, port}] 提交，不会被并集合并悄悄撤销）。
agent 工具
| 工具 | 注册条件 | 参数 | 作用 / 典型用法 |
|---|
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 / 启动 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_diagnose | 有目标即注册 | target?、id（必填）、logTail?（1500，默认 80）、since?（docker 语法，默认 1h）、history?（050，默认 10，0 = 不要历史） | 容器「为什么不行」：一次采集 inspect + 日志尾部 + 本容器事件（服务端 --filter container）+ stats 快照，产出 verdict（一句话结论）/ findings（判据表，每条带 code、severity、title、detail）/ evidence（退出码、OOM、重启次数、内存与 CPU 上限、日志与事件条数、当前占用）/ timeline / 。；「没采到」给 并附 判据，绝不写成 0。要更多日志 / 找关键词用 。返回里还带 （最近 N 个的样本 + 趋势结论 ）—— 就是「它是不是在慢慢变坏」那一句 |
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 /
docker_image_pull 归 write 类，docker_exec 归 exec 类，这两类在受限档（仅可查看 /
工作区内修改）下每次调用弹授权询问（人允许这一次才执行；无人值守即审批策略 never
时确定性拒绝），完全权限档零询问，Auto review 档不叠加（宿主的模型预审已在管）。宿主未组合
sandboxPolicy / approval 服务时不闸（行为与引入前一致），启动日志打一行
tier-gate: services absent (…), per-call gate disabled。它与上面两个静态开关是双层：
静态开关管注册（宿主级、持久授权），档位闸管已注册调用的放行（逐调用、随档位即时变）。
机制见 docs/permission-tier-plan.md。
- 推荐排障顺序：
docker_targets → docker_ps → docker_diagnose（一次拿到结论 + 判据 +
证据，多数「它为什么挂了 / 为什么不动」到这里就有方向了）→ docker_logs（尾部看不到成因就
docker_logs_grep 带 pattern / since / until 检索深处）→ docker_inspect（原始字段）→
docker_stats / docker_top（活着但不对劲：先看资源，再看进程还在不在）；镜像排查
docker_images → docker_image_inspect；要清磁盘先 docker_disk_usage（看 containers /
links 谁在用），再决定删什么。
announceToAgent 开启时，插件向 systemPrompt 注入一段精简公告：插件与面板位置、「默认
只读」与「docker socket ≈ 目标主机 root」的约束、「allowExec 只管一次性 exec 通道」的
边界（卡片「终端」按钮不受它门控）、target 的 * 适用范围，以及跨工具排障顺序；它不
逐条复述工具用法——那是各工具 description 的职责。
HTTP 路由（/api/dsh-docker 前缀，全部 loopback 围栏）
围栏校验 remoteAddress（整个 127/8 + ::1 + ::ffff: 映射）、Host（字面量环回、localhost，
或解析到本机的主机名 / /etc/hosts 别名，解析带 500ms 超时与 60s 缓存）、Origin 与 sec-fetch-site；
非本机请求一律 403 forbidden: loopback-only。请求体上限 1MB，响应统一 application/json +
referrer-policy: no-referrer。
除 loopback 之外还有一道「同源证明」：四条 SSE（/logs/stream、/stats/stream、/events/stream、
/images/pull/stream）与九条写子路由（/action、/images/remove|prune、/networks/remove|prune、
/volumes/remove|prune、/exec、/connect-local）要求请求带 Origin: <同源> 或 Sec-Fetch-Site: same-origin，
否则 403 缺少同源证明。这是为了挡住「恶意页面用 <img src=.../images/pull/stream> 触发一次真实拉取」
这类跨站副作用；curl / 老 Safari / 部分 WebView 不带这两个头时会撞上它（浏览器正常使用不受影响）。
只读路由不要求同源证明。
例外：桌面版靠宿主 Cookie 过闸（D139）。DeepSeek Harness 桌面版把页面发往
dsh-app://app/api/… 的请求转给真实宿主时会删掉 Origin 与 Sec-Fetch-Site、只重写
Cookie（app.asar/lib/main.js 的 forwardWebRequest），所以「两条证明都缺省」在桌面版是常态。
这类转发的判定条件是带着宿主会话 Cookie（桌面壳用启动 URL 换来的 set-cookie，缺它整条转发
直接 503）：没有 Origin、没有 Sec-Fetch-Site、但有 Cookie → 放行；两条都没有且无 Cookie
（裸 curl / 老 Safari）→ 仍 403。浏览器页面伪造不了 Cookie 头，而跨站请求一定带
sec-fetch-site: cross-site（loopback 围栏先拒），所以拒绝分支没有被放松。修复前桌面版的这十二条
路由全部 403——症状是日志 / 统计 / 活动 / 拉取四条流无限「连接中断，正在自动重连…」，而只读
路由照常可用。
| 路由 | 方法 | 请求体 | 返回 |
|---|
/config | GET | — | {ok:true, config}：配置快照（targets 只给 passwordSet / passphraseSet，另附只读的 ttyBooks / ttyAvailable / toolsRegistered / streamProtocol——最后这个是 SSE 帧协议版本，客户端据此决定「怎样才算已就绪」，见「SSE 事件协议」） |
/config | POST | 上表配置键的任意子集 | {ok:true, config}；未知键 400，非法 JSON 400 |
/targets | GET / POST | — | {ok:true, targets:[{name, kind, label?|error?}]} |
/connect-local | POST | {}（请求体被忽略） | 一键连接本机：复用或新建 kind=local 目标并返回 {ok:true, result:{name, kind, created, saved, reachable, serverVersion?, message}, config}；宿主没有 settings 服务时 503，保存失败时 500（都带原因且不改内存配置）。要求同源证明（它是写路径），但不需要 allowMutations / allowExec |
/probe | POST | {target?} | {ok:true, probe:{ok, bin, serverVersion, error, target}} |
/containers | POST | {target?, all?} | {ok:true, containers: ContainerSummary[]}；target:'*' 时返回 {ok:true, groups:[{target,label,ok,error?,data?}]}（跨目标并发聚合） |
/attention | POST | {target?, limit?} | 单目标 {ok:true, items: AttentionItem[], total, truncated, degraded}（limit 在过滤 + 严重度排序之后生效，默认 100、上限 500）；target:'*' 时 {ok:true, groups:[{target,label,ok,error?,data:{items,total,truncated,degraded}}]} |
/inspect | POST | {target?, id} | {ok:true, details: ContainerDetail[]} |
/stats | POST | {target?, ids?: string[]} | {ok:true, stats: ContainerStats[]} |
/logs | POST |
其余子路径 404（unknown route: ...）；/config、/targets、上述三条
*/stream 之外的 GET 返回 405；执行失败（docker 报错、目标解析失败等）返回
500 或 400 加 {error} 文本。
SSE 事件协议（/logs/stream、/stats/stream、/events/stream、/images/pull/stream）
四条长流共用同一份基建（openSseStream）：统一写头 + flushHeaders()、15s
一帧 : ping 心跳、活跃流登记（插件禁用 / 配置热更新 / 卸载时统一 end +
abort）、客户端断开静默中止，以及管道起来后先发一帧 ready（下表 + 客户端的
「绿点只认 ready」口径）。各自只差执行器与结束原因：
每帧一行 event: + 一行 JSON data:（JSON 单行封装：换行 / 引号被转义，
多字节字符不会被 SSE 行边界截断），随后空行：
| 事件 | data | 说明 |
|---|
ready | {} | 执行器真的起来了才发一帧（本机子进程 spawn / 远端通道已开 = StreamHandlers.onStart）：客户端据此才认为「在收数据」。响应头到达（onopen）不算——响应头由 flushHeaders() 立刻写出去，而建连（SSH acquire / 远端开通道）可能卡十几秒，目标不可达时干脆只有 error。起不来就没有 ready |
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, ...} | 执行器自然退出。日志流附容器退出码（多源时取按 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（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） | 前端离开拉取视图 |
- 响应头：
content-type: text/event-stream; charset=utf-8、cache-control: no-cache、connection: keep-alive，写头后立即 flushHeaders()（宿主 gzip
对 text/event-stream 显式跳过，不会缓冲）。
- 心跳：每 15s 一帧
: ping 注释（SSE 规范里客户端忽略）。
- 背压与溢出（D153）：客户端消费不过来时帧进内存队列（每条流 ≤ 8MB）；日志 / 拉取流溢出
时丢最旧的整帧、只留最新，并推一条
skip{frames,bytes}（skip 帧自身永不丢）——流不断；
skip 排队期间再发生丢弃时原地更新这条 skip 的账目（D156，两段缺口只报出一段就是少报）。
统计 / 事件流溢出时补 end{reason:output-limit} 收尾，由客户端重连。另外 write() 返回
false 只代表「越过高水位」，帧不会被重写（老实现的重复帧就是这里来的）。
- 分片合帧（D151）：日志流与拉取流把上游分片按 50ms 窗口合并后再推（同一通道严格保序、
stdout 先于 stderr、攒满 256KB 立刻推），所以
line 帧的 d / e 里可能有多行——
客户端本来就是按「任意分片」切行的，语义不变，只是「一个 stdout chunk 一帧」没了（话痨
容器每秒几千帧时，每帧的固定开销全砸在浏览器主线程上）。end 帧一定排在窗口里最后一批
line 之后。
- 清理：客户端断开 → 立即中止执行器（本机
SIGTERM，2s 未退再 SIGKILL；
SSH 关闭该 exec channel、连接池连接保留复用），不写任何帧；插件禁用 / 配置
热更新 / 卸载 → 服务端主动收尾（abort + end）。
- SSH 的长流会占用连接池里的连接（busy 计数），空闲回收（120s）不会误杀；
流结束后恢复回收。
- 「已就绪」的判据（客户端侧）：绿点 /「实时跟随中」只认宿主那帧
ready——响应头到了
不算。此外每条流还有一条「更硬的证据」兜底（收到它就等于管道在产数据）：事件流的第一条
真实事件、日志流的第一行、统计流的第一个采样、拉取流的第一帧进度。
开发档错位（宿主进程还跑着旧代码、浏览器却从磁盘读到新的 client.js）另有版本协商：
/config 的 streamProtocol < 2（或老到没有这个字段）说明该宿主从不发 ready，客户端
退回旧判据（响应头到了就算连上），并只重开一次那条流让回退判据生效——2026-10-11 实测：
旧宿主 + 新客户端原本会被钉死在「正在连接事件流…」（卡片能读到容器，活动条却在转）。
安全模型
docker socket ≈ 目标主机的 root 权限。 能访问 daemon 就能挂载宿主目录、
以特权模式起容器、读容器里的密钥——因此本插件按「只读优先」设计：
- 默认只读。
allowMutations 未开启时，/action、/images/remove、
/images/prune、/images/pull/stream 一律返回 403，面板的启停删 / 镜像
删除 / 清理 / 拉取不可用，docker_action、docker_image_remove、
docker_image_prune、docker_image_pull 工具根本不注册；allowExec
未开启时，/exec 返回 403，docker_exec 工具同样不注册。两个开关互相
独立，必须在设置卡片由用户显式打开。读取类路由（/logs/stream、
/stats/stream、/events/stream、/images/inspect）不受这两个开关影响。
allowExec 只管本插件的「一次性」exec 通道（/exec 路由、docker_exec
工具、容器详情抽屉「概览」页签的一次性命令框）——卡片上的**「终端」按钮跑的是 docker exec -it
交互式 shell，由 tty 承载、不经过这两个开关**，只读模式下也可用（见下面
「已知限制」里的边界说明：它不是漏了门，是刻意留的进入通道）。
- 破坏性操作要复述后果。
remove 映射为 docker rm（不带 -f），
agent 公告要求执行前向用户确认目标容器；运行中容器会报错并附
「容器仍在运行：先停止再删除」的提示，不会静默强删。
- 凭证不落明文（建议）。
password / passphrase 支持 env:NAME 凭据引用，
值存在官方凭据存储（$DSH_HOME/.credentials.yaml，由凭据层的 provider 托管）里，
避免明文写进 settings.yaml；不必依赖 env 插件当中间人。agent
认证（SSH_AUTH_SOCK）则完全不落盘。配置快照只回「是否已设置」。
- 主机指纹 TOFU 钉扎。首次连接记录 sha256 指纹，之后必须一致，变更即
拒绝连接（防中间人）；tty 已确认过的主机会被当作种子直接信任并复制进
本插件的记录。TOFU 的固有边界是「首次若已遭遇 MITM，记下的就是伪指纹」，
以及按 host:port 只存一条（同主机多密钥类型可能误报变更，删除记录重连
即可重新校准）。
- 命令一律 argv 构造，绝不做字符串拼接。容器名 / ID 先过白名单
assertRef（[A-Za-z0-9][A-Za-z0-9_.-]*，≤128 字符，拒绝空格、;、
$()、反引号等），镜像与容器引用同理；远程经 shJoin 逐参数单引号
转义后交给远端 shell，本机 spawn(bin, args) 不经 shell。
- 输出有上限。
maxOutputKb 限制单次命令的 stdout/stderr 字节数，超出
截断并标记，避免大日志撑爆内存或 agent 上下文。
- HTTP 只对本机开放。全部路由走 loopback 围栏，远程浏览器无法调用。
- 日志实时流是只读能力。
GET /logs/stream 与 /logs 一致：不受
allowMutations / allowExec 门控（它不改容器状态），但同样只放行 loopback、
id 过 assertRef 白名单、参数经同样的夹紧。与快照不同，长流没有
maxOutputKb 上限（跟随被截断就失去意义），内存防护由客户端的 5000 行
环形缓冲与 2000 行着色上限承担。
- 变更操作有逐条使用审计。kit elevation 的五行审计回答「授权了」，这里回答
「用了」：每一次的变更 / exec 都落一行
结构化审计行（出口是宿主 stdout），面板路由与 agent 工具两条入口都覆盖。行格式与
不记什么（403 / tier-gate ask）、以及「exec 命令会随行出现」这条代价，见「已知限制」
的使用审计条。
已知限制
-
没有交互式 TTY：exec 是一次性命令（docker exec <id> sh -c <cmd>，
不带 -i / -t），不能跑 vim / top / 交互式 shell，也不能喂 stdin 做
对话。交互排障请到 tty 面板执行 docker exec -it <容器> sh（本机与 SSH
目标都可以）。
-
allowExec 不是「进不了容器」的闸：卡片「终端」按钮（docker exec -it '<容器>' sh）经 tty 的 ttyTerminal 承载，不检查 allowExec，只读模式下
也照常可用——exec 被关时面板给的提示原文就是这么说的（「打开『允许 exec』，或
直接复制卡片上的 exec 命令到终端面板交互式进入容器」）。这是刻意的：只读巡检时
进容器看现场是最常用的一条路径，闸门管的是本插件自己那条一次性通道
（/exec 与 docker_exec：改本地状态、可被 agent 工具批量调用），交互式 shell
归 tty（用户主动操作、它自己才是 PTY 的所有者）。代价要说清：装上 tty 之后，
allowExec 对页内脚本（第三方插件的 client 半体 / XSS）本来就不是边界——它们
走 ttyTerminal.open 或 WS spawn 帧就能跑任意命令，比本插件的一次性 exec 还强。
这一层的威胁模型边界见 architecture.md § 7。
-
事件流有断线窗口：docker events 是「从现在开始」的推流，浏览器断线重连期间
发生的事件服务端已经推过、不会补发。客户端用「重连成功后先做一次全量列表刷新」
来补偿（状态对齐，不是把事件补回来）；活动条里缺的那几条只能靠刷新后的最终状态
推断。要精确的完整事件历史请用 docker_events 工具（带 --since 的快照）。
-
流式能力的四条边界：日志页 FOLLOW（SSE + docker logs -f）、统计页
FOLLOW（SSE + docker stats + 60 点 sparkline）、容器列表的事件流
（SSE + docker events，驱动活动条与列表防抖刷新）、镜像页拉取进度流
（SSE + docker pull）；但 agent 工具 docker_logs / docker_stats /
docker_image_pull 一律保持快照语义（单值返回模型不适合无界流）。流式
日志在浏览器侧只保留最近 5000 行（丢最旧并提示），统计只保留 60 个采样点。
SSH 长流会占住连接池中的该连接（busy），同一主机上的其它命令复用同一条连接——
但不是互不影响：通道额度是共享的，见下一条。统计流不会自然结束，关闭必须
由前端主动断 EventSource。
-
浏览器同源连接预算：docker 面板现在最多只占 1 条常驻流（D165 实测 + D168 收口）：
宿主是 HTTP/1.1（没有 h2 多路复用），浏览器对每个源只放这么几条 TCP，而
每条 EventSource 独占一条连接、且不会主动释放。吃满之后，同一个页面里
所有普通请求（列表刷新、/api/*、会话加载……）一起排队——用户看到的是
整个 DSH 页面卡住，不只是 docker 面板（实测：常驻流 0/4 条时页面请求正常，
5 条时 10 次全部超时；完整数据与现场见 DEFECTS.md 的 D165）。
docker 面板的常驻流：容器列表 = 活动条事件流；详情 =
日志 FOLLOW 或统计 FOLLOW（同一时刻只有一个页签）；聚合 / Compose 项目日志 =
多容器流；拉取 = 一条进度流。
（列表被整段替掉、活动条不可见），回列表时重连并补一次全量刷新（D168）。
：超了不是「慢一点」，是同页面所有请求一起失效。
想自己复核：在 devtools 里连开
到第 5 条，再打一次
普通请求即可看到它挂住；关掉就恢复。（WebSocket 占这份预算——tty 终端那条 WS
与 4 条 SSE 共存时页面仍正常，实测过。）
工作原理
浏览器半体 (client.js)
├─ 侧边栏「容器」入口 → 面板：目标选择 / 容器列表（搜索 + 状态筛选）/
│ 容器卡片（动作条分两组：查看=终端/日志/统计 ｜ 变更=启停/重启/删除）/
│ 容器列表「活动」条（事件驱动刷新）+「聚合选择」多选 → 临时聚合日志/
│ 多目标总览（全部目标并行取数 + 渐进落地；计数卡 / 异常置顶表；只读）/
│ Compose 项目视图（项目分组 / 服务表 / 项目级聚合日志）/
│ 镜像列表（行内详情 · 删除）+ 镜像详情（层 / 构建历史）+ 拉取进度 /
│ 网络列表 + 网络详情（子网 / 接入的容器）+ 卷列表 + 卷详情 / 一次性 exec
│ └─ 终端抽屉：tty ≥ 0.15 时经 ttyTerminal.mount 就地嵌入 tty 的终端
│ （面板不收起；折叠/拖拽只改尺寸，会话不中断；✕ 或关面板才 dispose，
│ 有活动会话时关面板先确认 → tty 那边结束会话并拆 DOM）
│ ├─ fetch → /api/dsh-docker/*（loopback 围栏）
│ ├─ FOLLOW → EventSource /logs/stream（SSE：5000 行 / 4MB 环形缓冲、150ms 合帧、
│ │ 行 id 稳定 key、显示不截断 / 自动贴底 /
│ │ 回到底部 / 断线自动重连 / 容器退出自动回快照）
│ ├─ 统计 FOLLOW → EventSource /stats/stream（SSE：60 点环形缓冲画
│ │ CPU / 内存 sparkline；**前端主动断**，docker stats 自己退出才收流）
│ ├─ 事件 → EventSource /events/stream（SSE：活动条环形缓冲 50 条 +
│ │ 500ms 防抖触发列表重取；重连成功后补一次全量刷新）
│ ├─ 拉取 → EventSource /images/pull/stream（SSE：逐层进度按层键 upsert）
│ └─ 聚合日志 → **一条** EventSource /logs/stream?ids=…（多容器共用；帧带 id，
│ 客户端按 [service] 混流；老宿主退回每容器一条）
├─ 可选消费 tty 的 ttyConnbar 服务 → SSH 连接栏「容器」按钮
│ （按 book 名 / host:port 匹配已配置目标，命中才出现）
├─ 可选消费 tty 的 ttyPanel 服务（0.16.0）→ 终端面板开着时挂右侧 dock
└─ 可选消费 tty 的 ttyTerminal 服务 → 卡片「终端」按钮直接开 docker exec 标签
（tty 不可用 / 凭证不在浏览器时退回复制命令）
宿主半体 (src/index.ts)
├─ settings 命名空间 docker（~/.dsh/settings.yaml）
│ DOCKER_SETTINGS_SCHEMA → normalizeConfig（夹紧 / 白名单键）
├─ 只读复用 tty settings 的 sshHosts（连接簿）与 hostKeys（指纹种子）
├─ resolveTarget：local → runLocal；ssh → book 查连接簿或内联字段
├─ 每目标一个 DockerApi（src/docker.ts）
│ ├─ argv 构造 + assertRef 白名单 + 输出上限（maxOutputKb）
│ └─ 解析容错：{{json .}} 逐行/数组、字段名大小写兼容、缺字段降级
├─ RemoteExec（src/ssh-exec.ts）
│ ├─ 懒连接池：同 user@host:port 复用一条连接，空闲 120s 回收
│ │ （每 30s 扫一次，连接超时 20s，keepalive 10s；busy>0 的长流跳过回收）
│ ├─ 非 PTY exec channel：一命令一 channel，收完 stdout/stderr 即关；
│ │ 长流（run()/stream()）不设总超时与输出上限，靠 AbortSignal 停止
│ ├─ shJoin 单引号转义（远端 shell 解析）；env:NAME 凭据解析（provider 优先 → 退回 env）
│ └─ hostVerifier TOFU 钉扎（首次记录、变更拒绝）
├─ runLocal / runLocalStream：spawn(dockerBin, args)（不经 shell，本机目标）
│ 停止阶梯：SIGTERM → 2s 未退出 SIGKILL
├─ 通用 SSE 长连接 openSseStream（src/index.ts，四条流共用一份基建）
│ ├─ loopback 围栏 + assertRef / assertImageRef + tail 夹紧（与快照路由一致）
│ ├─ 写头 + flushHeaders / 15s ping 心跳 / 活跃流登记 / 前端断开静默 abort
│ │ 管道起来后先发 ready{}（StreamHandlers.onStart：客户端只认它当「在收数据」）
│ ├─ /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 →
│ │ event{action,name,image,...}（白名单过滤）；daemon 侧结束则 end{events-exit}
│ ├─ /images/pull/stream（allowMutations）：docker pull → line{d|e} +
│ │ end{pull-exit,code,ref}；未开启变更时 403 且不建流
│ └─ 插件禁用 / 配置热更新 / 卸载 → 四条流统一 end + abort
├─ 镜像路由：/images/inspect（只读）· /images/remove · /images/prune（allowMutations）
├─ 网络 / 卷路由：/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_action / docker_image_remove / docker_image_prune / docker_image_pull
（allowMutations + 有目标）/ docker_exec（allowExec + 有目标）
开发与验收
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（本包 test/ 下的用例都在里面；项数以运行输出为准）
改了哪一半、怎么才生效（踩过两次的坑）：
client-src/*（浏览器半体）→ esbuild 出 client.js。宿主有 client HMR 轮询各插件的
client bundle，热更，刷新页面即见；src/*.ts（宿主半体）→ tsc 出 lib/。必须是新进程才生效：运行中的 dsh web
在启动时就把 lib/ 载进内存，之后 lib/ 再变它也不会重载。改完 pnpm build 记得
重启：dsh web --profile <name>。
忘了重启的症状很迷惑：客户端是对的、宿主是旧的，于是错误文案、重试、配额这类宿主侧
逻辑全都不生效，看起来像「改了没用」。判断依据是文案——宿主侧新增的提示语如果没出现，
那就是旧进程。
验证面分三层：三套离线 smoke（不需要 docker daemon）、本包的 vitest 套件、
以及真 daemon 的手工验收清单。逐项的覆盖范围、浏览器侧性能门槛与手工步骤见
docs/verification.md——README 只留「怎么跑」，清单不在这里重复
（同一事实两处全文是债，见 conventions § 文档分层）。
版本 / 许可证
@hyzyn/dsh-docker 0.3.1 · Apache License 2.0
