@hyzyn/dsh-docker 0.9.5 → 0.10.0

package/lib/index.js

@@ -1,10 +1,42 @@
-import { join } from 'node:path';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, basename, join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { definePlugin, hasSameOriginProof, isLoopbackRequestStrict, originProofHint, plainConfig, readSettingsEntry, settingsEntryScope, suppressAutoSettingsPage } from '@hyzyn/dsh-kit';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { auditCapabilityUse, audited } from './audit.js';
 import { DockerApi, assertBin, assertImageRef, assertName, assertRef, assertSince, createRunner, parseImageHistoryJson, parseImageHistoryText, parseContainerEvent, parseEventsJson, parseImageInspectJson, parseInspectJson, parsePsJson, parseStatsJson, suggestContainerNames, } from './docker.js';
 import { RemoteExec, sanitizeJumpSpec, sanitizeProxyCommand, setCredentialResolver, sshTarget } from './ssh-exec.js';
-import { auditLoadedGrants, bindCapabilitySources, capabilityDeniedMessage, capabilityGrantAt, capabilityGranted, capabilityGrantVia, capabilityPaths, createElevationManager, dshHome, sharedGrantStore, } from '@hyzyn/dsh-kit';
+import { auditLoadedGrants, attachTierGate, bindCapabilitySources, capabilityDeniedMessage, capabilityGrantAt, capabilityGranted, capabilityGrantVia, capabilityPaths, createElevationManager, dshHome, sharedGrantStore, } from '@hyzyn/dsh-kit';
+/*
+ * 档位闸的分类表（docs/permission-tier-plan.md §2.1）：`read` 纯读 / 固定二进制探测
+ * （docker_connect_local 不在能力开关里，见 connectLocal 的注释）；`write` 容器与镜像的变更
+ * （docker_image_pull 是拉取非破坏，但改本地状态，且本就注册在 allowMutations 组里）；
+ * `exec` 容器内一次性命令。名单必须与 refreshTools 里 add() 注册的工集一一对应——对账由
+ * test/tier-gate.test.ts 从 add() 调用处现算（漏分类 → 红）。与 allowMutations / allowExec
+ * 的关系是**双层并存**：静态开关管注册（宿主级、持久授权），档位闸管已注册调用的放行
+ * （逐调用、会话级），谁也不取代谁。
+ */
+export const DOCKER_TIER_CLASS = {
+    docker_targets: 'read',
+    docker_connect_local: 'read',
+    docker_ps: 'read',
+    docker_attention: 'read',
+    docker_inspect: 'read',
+    docker_logs: 'read',
+    docker_stats: 'read',
+    docker_events: 'read',
+    docker_images: 'read',
+    docker_image_inspect: 'read',
+    docker_networks: 'read',
+    docker_volumes: 'read',
+    docker_action: 'write',
+    docker_image_remove: 'write',
+    docker_image_prune: 'write',
+    docker_image_pull: 'write',
+    docker_exec: 'exec',
+};
+/** 本插件 agent 工具的名单前缀（档位闸只听这些名字）。 */
+export const DOCKER_TIER_PREFIXES = ['docker_'];
 const TARGET_SCHEMA = z.object({
     name: z.string().required(),
     kind: z.union([z.const('local'), z.const('ssh')]).default('local'),
@@ -89,6 +121,14 @@ const MUTATION_SUBROUTES = new Set([
     '/elevate',
     '/elevate/status',
     '/elevate/revoke',
+    /*
+     * 一键连接本机（POST /connect-local）：它**会写插件配置**（加一个本机目标），
+     * 与其它写路径同一档，必须带同源证明——跨站页面不该有权替用户改目标列表。
+     * 注意它**不**在能力开关（allowMutations / allowExec）里：见 connectLocal 的注释。
+     * 客户端只在「一个目标都没有」的空态里给入口，但路由本身与调用方无关（agent 工具
+     * 在任何时候都能调），所以这条守卫不能省。
+     */
+    '/connect-local',
 ]);
 /** 「这条错误来自目标侧」的标记（见 guardTargetFailures）。 */
 const TARGET_FAILURE = Symbol('dsh-docker.target-failure');
@@ -132,7 +172,7 @@ function guardTargetFailures(api) {
 function isTargetFailure(error) {
     return error !== null && typeof error === 'object' && error[TARGET_FAILURE] === true;
 }
-const DOCKER_GUIDANCE = '本机已安装 dsh-docker 插件（Docker 容器面板）：Web GUI 侧边栏「容器」入口可查看各目标（本机 / SSH 主机）上的容器列表（含 Compose 项目视图、事件「活动」条）、状态、端口、日志（含实时跟随）与资源占用（含实时跟随 + 迷你趋势图），以及镜像列表与镜像详情（层 / 大小 / 构建历史、拉取进度流）、网络与卷（列表 + 详情；删除 / 清理同样在开关之后）；目标在 插件配置 → Docker 容器面板 里维护（SSH 目标可直接引用 tty 终端面板的连接簿条目）。**默认只读**：启动/停止/重启/删除容器、删除镜像 / 清理 dangling / 拉取镜像、docker exec，都需要用户在设置里显式打开「允许变更操作」「允许 exec」后才有对应工具与按钮。agent 侧配套只读工具 docker_targets（列目标）、docker_ps（列容器，含 compose 项目与服务；**target 传 `*` 可一次列出所有目标**；端口已按 IPv4/IPv6 双栈归并，`ports` 为空时看 `net`——host 网络容器的端口即宿主机端口）、docker_attention（**需关注汇总**：unhealthy / 反复重启 / OOM / 非零退出 / 僵死，同样支持 `*` 跨目标）、docker_inspect（容器详情）、docker_logs（日志快照）、docker_stats（CPU/内存/IO 快照）、docker_images（镜像列表）、docker_image_inspect（镜像详情 + 构建历史）、docker_events（容器事件快照，见面板容器列表的「活动」条）、docker_networks（网络列表）、docker_volumes（卷列表）；排障推荐顺序：不确定从哪台/哪个容器看起时先 docker_attention（可 `*` 跨目标）→ docker_ps → docker_logs → docker_inspect → docker_stats → docker_events，镜像排查用 docker_images → docker_image_inspect。docker_action（容器生命周期）、docker_image_remove（删镜像）、docker_image_prune（清理 dangling）、docker_image_pull（拉取镜像）、docker_exec 仅在用户打开对应开关后可用，执行前须确认目标，破坏性操作（容器 remove / 镜像删除与清理）要向用户复述后果。网络 / 卷的删除与 prune 目前只提供面板按钮（HTTP 端点），没有对应的 agent 工具——不要在 agent 侧绕过面板做这些变更。docker socket 等价于目标主机的 root 权限，不要在用户未明确要求时执行变更操作。';
+const DOCKER_GUIDANCE = '本机已安装 dsh-docker 插件（Docker 容器面板）：Web GUI 侧边栏「容器」入口可查看各目标（本机 / SSH 主机）上的容器列表（含 Compose 项目视图、事件「活动」条）、状态、端口、日志（含实时跟随）与资源占用（含实时跟随 + 迷你趋势图），以及镜像列表与镜像详情（层 / 大小 / 构建历史、拉取进度流）、网络与卷（列表 + 详情；删除 / 清理同样在开关之后）；目标在 插件配置 → Docker 容器面板 里维护（SSH 目标可直接引用 tty 终端面板的连接簿条目）。**默认只读**：启动/停止/重启/删除容器、删除镜像 / 清理 dangling / 拉取镜像、docker exec，都需要用户在设置里显式打开「允许变更操作」「允许 exec」后才有对应工具与按钮。agent 侧配套只读工具 docker_targets（列目标；没有任何目标时先调 docker_connect_local 一键加上本机目标）、docker_connect_local（把宿主所在机器加成本机目标并选中，复用已有的本机目标、不重复创建；顺带探测 daemon，失败会说明是 daemon 未启动 / CLI 缺失 / socket 无权访问）、docker_ps（列容器，含 compose 项目与服务；**target 传 `*` 可一次列出所有目标**；端口已按 IPv4/IPv6 双栈归并，`ports` 为空时看 `net`——host 网络容器的端口即宿主机端口）、docker_attention（**需关注汇总**：unhealthy / 反复重启 / OOM / 非零退出 / 僵死，同样支持 `*` 跨目标）、docker_inspect（容器详情）、docker_logs（日志快照）、docker_stats（CPU/内存/IO 快照）、docker_images（镜像列表）、docker_image_inspect（镜像详情 + 构建历史）、docker_events（容器事件快照，见面板容器列表的「活动」条）、docker_networks（网络列表）、docker_volumes（卷列表）；排障推荐顺序：不确定从哪台/哪个容器看起时先 docker_attention（可 `*` 跨目标）→ docker_ps → docker_logs → docker_inspect → docker_stats → docker_events，镜像排查用 docker_images → docker_image_inspect。docker_action（容器生命周期）、docker_image_remove（删镜像）、docker_image_prune（清理 dangling）、docker_image_pull（拉取镜像）、docker_exec 仅在用户打开对应开关后可用，执行前须确认目标，破坏性操作（容器 remove / 镜像删除与清理）要向用户复述后果。网络 / 卷的删除与 prune 目前只提供面板按钮（HTTP 端点），没有对应的 agent 工具——不要在 agent 侧绕过面板做这些变更。docker socket 等价于目标主机的 root 权限，不要在用户未明确要求时执行变更操作。';
 /**
  * SSE 帧封装：data 一律 `JSON.stringify` 成**单行**——换行 / 引号被转义，
  * 多字节字符也不会被 SSE 的 `\n` 行边界截断（客户端 JSON.parse 还原）。
@@ -279,6 +319,120 @@ export function sanitizeTargets(input) {
     }
     return out;
 }
+/** 一键连接本机时新建目标的基准名。刻意用稳定的小写 `local`（不是 `本机`）：它是可预测的 id，重名时另起 `local-2`…。 */
+export const LOCAL_TARGET_NAME = 'local';
+/** 目标列表里第一个 `kind=local` 的名称（没有则 undefined）——「连接本机」靠它判断该新建还是复用。 */
+export function findLocalTargetName(targets) {
+    return targets.find((item) => item.kind === 'local')?.name;
+}
+/**
+ * 新建本机目标时挑一个**确定性无冲突**的名称：`local` 被占就顺着 `local-2`、`local-3`… 找第一个空位。
+ *
+ * 为什么不做随机 / 时间戳后缀：同一个工作区里重复点「连接本机」应当**幂等**（第二次复用第一次那条），
+ * 而重名只可能来自用户自己配的其它 `local*`；顺序探测既确定又与用户已有的名字不冲突（不覆盖、不改名）。
+ * 上界 1000 是防御性截断（真到那时说明列表已经病态，宁可失败也不能无限循环）。
+ */
+export function nextLocalTargetName(taken) {
+    const used = new Set(taken);
+    if (!used.has(LOCAL_TARGET_NAME))
+        return LOCAL_TARGET_NAME;
+    for (let index = 2; index <= 1000; index += 1) {
+        const candidate = `${LOCAL_TARGET_NAME}-${String(index)}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * 「探不到 CLI」的判据（`runLocal` 的 ENOENT 抛错形态）。
+ *
+ * 抽出来当单一来源：文案分档与「要不要去找 podman」都用它，两处各写一遍正则
+ * 迟早会漂移——那时会出现「文案说 CLI 缺失、但不去找候选」或反过来。
+ */
+export function isLocalCliMissing(raw) {
+    return /ENOENT|not recognized as an internal|command not found/i.test(raw);
+}
+/** 本机容器 CLI 的候选（除 `dockerBin` 自己之外）：按这个顺序找第一个存在的。 */
+const LOCAL_CLI_ALTERNATIVES = ['docker', 'podman', 'nerdctl'];
+/**
+ * 在 PATH 里找**别的**容器 CLI（`dockerBin` 缺失时的候选），返回名字数组（可能为空）。
+ *
+ * 只读探测，**绝不改配置**：返回的候选交给文案去说「你可以把 docker CLI 改成它」，
+ * 改不改由用户在设置卡片决定。静默改写 `dockerBin` 会违背本插件「不替用户决定」的
+ * 一贯取向（何况 podman 与本插件的输出格式兼容性并未逐项验证，见 README）。
+ *
+ * `env` 可注入（测试用）；Windows 按 PATHEXT 补扩展名——本插件明确支持 Windows
+ * 盘符路径，不能只认无扩展名的 POSIX 查找。
+ */
+export function findAlternativeLocalCli(bin, env = process.env) {
+    const dirs = (env.PATH ?? '').split(delimiter).filter((item) => item !== '');
+    const win = process.platform === 'win32';
+    const exts = win ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter((item) => item !== '') : [''];
+    /*
+     * 比的是**工具名**（basename，Windows 再去掉扩展名），不是配置里的原字符串：
+     * `dockerBin` 常写成绝对路径（`/usr/local/bin/docker`），拿它直接比对候选名会
+     * 把「同一个 docker」当成可切换的候选，给出「把 docker CLI 改成 docker」这种废话。
+     */
+    const stem = (value) => {
+        const base = basename(value).toLowerCase();
+        return win ? base.replace(/\.[^.]+$/, '') : base;
+    };
+    const self = stem(bin);
+    const found = [];
+    for (const candidate of LOCAL_CLI_ALTERNATIVES) {
+        if (candidate === self)
+            continue;
+        const dir = dirs.find((item) => exts.some((ext) => {
+            try {
+                accessSync(join(item, candidate + ext), constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }));
+        if (dir !== undefined)
+            found.push(candidate);
+    }
+    return found;
+}
+/**
+ * 只读探测失败 → 用户能照着做的一句话。按**成因**分档（而不是原样甩 `exit status 1`）：
+ * CLI 不在（装 Docker / 改 `dockerBin`）、超时（daemon 卡死 / context 指错）、
+ * daemon 不可达、socket 无权、其它（原样透出）。
+ *
+ * `probe()` 的两条失败路径形状不同：`runLocal` 对 ENOENT 是**抛错**（`无法执行 docker：spawn docker ENOENT`），
+ * 而 daemon 连不上是 docker CLI 自己以非零退出 + stderr 文案返回；两条都要认得出。
+ */
+export function describeLocalProbeFailure(raw, bin = 'docker', hint = {}) {
+    const text = raw.trim();
+    if (isLocalCliMissing(text)) {
+        const head = `宿主上找不到 docker CLI（${bin}）：请先安装 Docker，或在设置卡片把「docker CLI」改成正确的可执行文件路径`;
+        // 有候选就点出来——只说「请先安装 Docker」会让 podman 用户以为要装一整套 Docker。
+        // 同时写明**面板不会替你改**：这是提示，不是自动切换（见 findAlternativeLocalCli）。
+        return hint.alternativeCli === undefined || hint.alternativeCli === ''
+            ? head
+            : `${head}。这台机器上装了 ${hint.alternativeCli}：把「docker CLI」填成 ${hint.alternativeCli} 就能用（面板不会替你改）`;
+    }
+    /*
+     * 超时单独一档（D159）：它和「daemon 没起」的可修动作完全不同，也不能落进下面
+     * 那句「退出码 null」。判据来自 `ProbeResult.timedOut` 而不是解析文案——CLI 的
+     * 超时输出里根本没有可认的字样。
+     */
+    if (hint.timedOut === true) {
+        return `${bin} version 15 秒没返回：daemon 可能卡死，或 docker context 指向了连不上的远端（用 docker context ls 看当前指向；Docker Desktop 卡死时重启它）`;
+    }
+    if (/ECONNREFUSED|ENOENT.*\.sock|\.sock.*(no such file|不是目录|No such)/i.test(text)) {
+        return `docker CLI 可用，但连不上 docker daemon：请确认 daemon 已启动（Linux: systemctl start docker；macOS/Windows: 启动 Docker Desktop）`;
+    }
+    if (/permission denied/i.test(text)) {
+        return `docker CLI 可用，但当前账号无权访问 docker socket：把运行宿主的账号加入 docker 组，或改用允许的 socket`;
+    }
+    if (/Is the docker daemon running|Cannot connect to the Docker daemon|error during connect/i.test(text)) {
+        return `docker CLI 可用，但连不上 docker daemon：请确认 daemon 已启动（Linux: systemctl start docker；macOS/Windows: 启动 Docker Desktop）`;
+    }
+    return `docker daemon 探测失败：${text === '' ? 'docker version 没有返回任何信息' : text}`;
+}
 /**
  * 清洗一份 hostKeys 输入（settings 存储 / 热更新 / 种子复制共用）。
  *
@@ -639,7 +793,7 @@ const plugin = definePlugin({
          * 刻意放在 `enabled` 判定**之前**：授权是宿主级的、与插件这次是否启用无关；插件这次是禁用态时
          * 反而更该说一句（「盘上有授权，但插件没开」与「点了没反应」是两回事）。
          */
-        auditLoadedGrants(grantStore, [CAP_MUTATIONS.env, CAP_EXEC.env], { info: (msg) => ctx.logger.info(msg), warn: (msg) => ctx.logger.warn(msg) }, '[dsh-docker]');
+        auditLoadedGrants(grantStore, [CAP_MUTATIONS.env, CAP_EXEC.env], '[dsh-docker]');
         // volatile 字段解析后是 `{ get() }` 引用，先还原成纯数据（见 @hyzyn/dsh-kit 的 plainConfig）。
         const config = plainConfig((rawConfig ?? {}));
         /*
@@ -667,6 +821,7 @@ const plugin = definePlugin({
         };
         /* ---------- 主机指纹（TOFU，本插件自持；tty 记录作种子） ---------- */
         let settingsScope;
+        let settingsForms;
         /**
          * 只读他人 entry（如 tty 的连接簿）：旧 `settings.get(ns)` 在新宿主已不存在，
          * 改走 `settings.describe()` 的 entry 查找（kit 的 readSettingsEntry）。settings
@@ -761,13 +916,19 @@ const plugin = definePlugin({
             }
             return resolveTarget(target, readTtyBooks(settingsApi));
         };
-        /** 取某个目标上的 DockerApi（Runner 每次新建，连接由 RemoteExec 池化）。 */
-        const apiFor = (name) => {
+        /**
+         * 取某个目标上的 DockerApi（Runner 每次新建，连接由 RemoteExec 池化）。
+         *
+         * `signal`（D161）只有**跨目标聚合**会传：它把「这一格的预算到点了」串到该目标
+         * **底层每一条命令**上（`createRunner` 绑到 Runner 上，见那边的注释）。其余调用点
+         * 不传，行为与之前完全一致。
+         */
+        const apiFor = (name, signal) => {
             const { resolved, error } = resolveByName(name);
             if (resolved === undefined)
                 return { error };
             try {
-                const runner = createRunner({ target: resolved, remote, logger });
+                const runner = createRunner({ target: resolved, remote, logger, ...(signal === undefined ? {} : { signal }) });
                 return { api: new DockerApi(runner, live.dockerBin, { timeoutMs: 30_000, maxBytes: live.maxOutputKb * 1024 }), resolved };
             }
             catch (error_) {
@@ -799,18 +960,185 @@ const plugin = definePlugin({
                 return { name: fallback };
             const list = targetsNow();
             if (list.length === 0)
-                return { error: '尚未配置任何 Docker 目标（插件配置 → Docker 容器面板）' };
+                return { error: '尚未配置任何 Docker 目标：可调 docker_connect_local 一键加上本机目标，或到 插件配置 → Docker 容器面板 添加' };
             return { error: 'target 必填（已配置多个目标：' + list.map((item) => item.name).join('、') + '）' };
         };
+        /* ---------- 一键连接本机（面板按钮 / HTTP 路由 / agent 工具共用这一份实现） ---------- */
+        /**
+         * 探测失败 → 给用户的一句话（这次探测的 bin 以**配置里的 `dockerBin`** 为准）。
+         *
+         * 只有「CLI 缺失」这一档才去 PATH 里找候选：那要 accessSync 若干次，其余档位全是
+         * 纯文本判断，不该无谓地跑文件系统。
+         */
+        const localProbeReason = (raw, timedOut = false) => {
+            const alternative = isLocalCliMissing(raw) ? findAlternativeLocalCli(live.dockerBin)[0] : undefined;
+            return describeLocalProbeFailure(raw, live.dockerBin, {
+                timedOut,
+                ...(alternative === undefined ? {} : { alternativeCli: alternative }),
+            });
+        };
+        /**
+         * 显式加一个本机目标并选中它，然后把只读探测结果一并回报。
+         *
+         * 四条不变量（缺任何一条都会变成另一种东西）：
+         *   - **幂等**：已有 `kind=local` 就复用它（`created:false`），绝不重复创建；重复点、并发点都落到同一条。
+         *   - **不改别人的**：SSH / 自定义目标原样保留，`targets` 顺序也只追加（`[...existing, 新建]`）——
+         *     不排序、不重写已存在的条目（重写会丢掉 `mergeTargetSecrets` 才补得回的密码）。
+         *   - **没有隐式默认目标**：只有本函数被显式调用才动 `targets`；空数组 / `clearTargets` 的既有语义一字不改。
+         *   - **落盘成功才算数**：settings 不可用或保存失败一律**明确报错且不改内存配置**（no-op），
+         *     绝不出现「界面显示已加上了、刷新就没了」。
+         *
+         * 权限：这条路径只写**本插件自己的配置**（加一个指向宿主自身的本机目标）+ 只读探测，
+         * 与服务端 root 等价的那两档能力（`allowMutations` / `exec`）无关，因此不要求任何授权；
+         * 也绝不自动装 Docker、起 daemon、切 docker context 或改 env。
+         */
+        const connectLocalOnce = async () => {
+            if (!live.enabled)
+                return { ok: false, code: 403, error: 'Docker 插件已禁用' };
+            const existing = targetsNow();
+            const found = findLocalTargetName(existing);
+            // Reusing an existing local target only probes it; it does not need a settings write.
+            if (found === undefined && settingsScope === undefined) {
+                return { ok: false, code: 503, error: '设置存储不可用（宿主未提供 settings 服务），无法保存本机目标；请稍后重试' };
+            }
+            const name = found ?? nextLocalTargetName(existing.map((item) => item.name));
+            if (name === undefined) {
+                return { ok: false, code: 400, error: `本机目标名冲突：已有 1000 个 local* 目标，请先删掉一些再试` };
+            }
+            let created = false;
+            if (found === undefined) {
+                /* 新条目只写展示名与 kind：其余字段交给 normalizeConfig / sanitizeTargets 的默认值（单一来源）。 */
+                const scope = settingsScope;
+                let entry;
+                try {
+                    entry = settingsForms?.describe().find((item) => item.ns === scope.ns);
+                }
+                catch {
+                    return { ok: false, code: 503, error: '无法读取当前目标配置，请稍后重试' };
+                }
+                if (entry === undefined)
+                    return { ok: false, code: 503, error: '当前设置条目不可用，请稍后重试' };
+                const rawTargets = entry.value?.targets;
+                const nextTargets = [...(Array.isArray(rawTargets) ? rawTargets : existing), { name, kind: 'local' }];
+                try {
+                    await settingsForms.update(scope.ns, { targets: nextTargets }, entry.revision);
+                }
+                catch (error) {
+                    return { ok: false, code: 500, error: '保存本机目标失败：' + (error instanceof Error ? error.message : String(error)) };
+                }
+                created = true;
+                /*
+                 * `scope.update` 之后必须自己应用一次：真实 loader 会发 `loader/volatile-update` 触发
+                 * applySection，但那个事件是**异步**的，单测 / 老宿主还可能完全不发。这里同步应用是幂等的
+                 * （applySection 用同一份 settings 值再归一化一次），而**不应用**的后果是「刚加上的目标
+                 * 在探测那一步还解析不到」。
+                 */
+                try {
+                    applySection({ targets: nextTargets });
+                }
+                catch (error) {
+                    return {
+                        ok: false,
+                        code: 500,
+                        error: '本机目标已保存但应用失败：' + (error instanceof Error ? error.message : String(error)),
+                    };
+                }
+            }
+            // 探测失败一律降级为 message（见 ConnectLocalResult 的注释），不是这次操作的失败
+            const built = apiFor(name);
+            if (built.api === undefined) {
+                return {
+                    ok: true,
+                    result: {
+                        name,
+                        kind: 'local',
+                        created,
+                        saved: true,
+                        reachable: false,
+                        message: `已${created ? '添加并选中' : '选中'}本机目标「${name}」，但无法构造执行通道：${built.error ?? '未知错误'}`,
+                    },
+                };
+            }
+            let reachable = false;
+            let serverVersion;
+            let reason = '';
+            try {
+                const probe = await built.api.probe();
+                reachable = probe.ok;
+                if (probe.serverVersion !== null)
+                    serverVersion = probe.serverVersion;
+                if (!probe.ok)
+                    reason = localProbeReason(probe.error ?? '', probe.timedOut);
+            }
+            catch (error) {
+                reason = localProbeReason(error instanceof Error ? error.message : String(error));
+            }
+            const head = `已${created ? '添加并选中' : '选中'}本机目标「${name}」`;
+            return {
+                ok: true,
+                result: {
+                    name,
+                    kind: 'local',
+                    created,
+                    saved: true,
+                    reachable,
+                    ...(serverVersion === undefined ? {} : { serverVersion }),
+                    message: reachable
+                        ? `${head}：docker daemon 可达${serverVersion === undefined ? '' : `（${serverVersion}）`}`
+                        // 连接失败必须说清**为什么**：daemon 没起 / CLI 缺失 / socket 权限，而不是只报「没有容器」
+                        : `${head}，但本机 docker 不可用——${reason === '' ? 'docker version 未返回可用信息' : reason}`,
+                },
+            };
+        };
+        // Serialize this read-modify-write across HTTP and tool callers. Rejections never poison the queue.
+        let localConnectQueue = Promise.resolve();
+        const connectLocal = () => {
+            const pending = localConnectQueue.then(connectLocalOnce);
+            localConnectQueue = pending.catch(() => { });
+            return pending;
+        };
         /**
          * 跨目标聚合（0.15.0）：所有目标的容器 / 需关注列表在面板与 agent 工具里共用同
          * 一套逻辑。三个必须的性质：
          *   - **并发上限**：ssh exec 扇出太多会互相挤（远端 sshd MaxStartups / 本机 fd）；
          *   - **单目标超时**：一台网络不通不能把整个聚合页拖住；
          *   - **错误隔离**：失败的组带上 error 照常返回，其余目标的结果照常可用。
+         *
+         * 第四个性质是 **D161 补上的**：单个目标超时的那一刻，**它底下正在跑的命令必须真的被
+         * 停掉**。旧写法只 `Promise.race` 出一个 `ok:false`，底层那条 SSH channel 继续跑完——
+         * 而它占着的正是 `MaxSessions` 的 session 槽（sshd 在子进程活着时不释放，见 D150）。
          */
         const AGG_CONCURRENCY = 4;
-        const AGG_TIMEOUT_MS = 45_000;
+        /**
+         * 单目标上**每一条**命令的内层预算（30s，DockerApi 构造时传下去的那一个）。
+         *
+         * 单独取个名字是为了让「外层兜底」与「内层真相」共用一个来源：D161 之前这里是
+         * `apiFor` 里的裸字面量 `30_000`，而外层是另一个裸字面量 `45_000`——两个数字各写各的，
+         * 谁也不知道它们的关系，于是 45s 那个到底会不会打断一条健康命令，没人说得清。
+         */
+        const AGG_CMD_TIMEOUT_MS = 30_000;
+        /**
+         * 单个目标那一格的**兜底**预算（D161）。
+         *
+         * 取舍（两种做法里选了后者）：
+         *   - ①「把外层提到大于单目标最坏序列耗时」——`attention()` 是 `listContainers` +
+         *     最多约 9 批 `inspect` 的**串行**序列（`ATTENTION_INSPECT_CAP 300 + 补捞 50`，
+         *     每批 ≤ 40），最坏 10 × 30s ≈ 300s。真按这个上界设，总览页等一台卡住的机器要
+         *     等五分钟，等于没有预算；
+         *   - ②**内层超时是唯一真相源，外层只做兜底** ← 选这个。30s/命令已经给每条命令兜了底，
+         *     外层存在的意义只是「内层没兜住时（连接获取 / 闸门排队 / 某个实现没遵守
+         *     timeoutMs）别把整页拖死」。所以它取 3 倍单条预算（90s）：大于 `attention` 的
+         *     典型两段（ps + 首批 inspect ≈ 60s），不会被健康命令序列撞上；又给异常留了一档
+         *     天花板。到点即 `abort()`——**这是这次修复的实质**，配置数字只是顺带对齐。
+         *
+         * `DSH_DOCKER_AGG_TIMEOUT_MS` 可覆盖，**只为测试与排障**（同 `DSH_DOCKER_SHORT_CHANNELS`
+         * 的口径）：90s 这条路径没法在单测里等，而「超时后底层有没有真的被取消」恰恰是本轮
+         * 的验收点——没有这个口子就只能测到「返回了 ok:false」，那正是修复前就恒绿的那条。
+         */
+        function aggTimeoutMs() {
+            const raw = Number(process.env.DSH_DOCKER_AGG_TIMEOUT_MS);
+            return Number.isFinite(raw) && raw > 0 ? raw : AGG_CMD_TIMEOUT_MS * 3;
+        }
         async function mapLimit(items, limit, run) {
             const results = new Array(items.length);
             let cursor = 0;
@@ -829,18 +1157,35 @@ const plugin = definePlugin({
         /** 在所有（或指定）目标上跑同一件事，返回按目标分组的「部分成功」结果。 */
         const aggregateAcrossTargets = async (names, run) => {
             return await mapLimit(names, AGG_CONCURRENCY, async (name) => {
-                const built = apiFor(name);
+                /*
+                 * 控制器必须建在 `run()` **之前**（D161）：Runner 是在 `apiFor` 里构造的，signal
+                 * 当场绑到 Runner 上（见 createRunner）。先跑再建的话，abort 时底层根本不知道
+                 * 自己被取消——那正是修复前的行为。
+                 */
+                const controller = new AbortController();
+                const budget = aggTimeoutMs();
+                const built = apiFor(name, controller.signal);
                 const resolved = built.resolved;
                 const label = resolved === undefined
                     ? name
                     : (resolved.kind === 'local' ? '本机' : sshTarget(resolved.spec));
-                if (built.api === undefined)
+                if (built.api === undefined) {
+                    controller.abort();
                     return { target: name, label, ok: false, error: built.error ?? '无法构造执行通道' };
+                }
                 const api = built.api;
                 let timer = null;
                 try {
                     const timeout = new Promise((_resolve, reject) => {
-                        timer = setTimeout(() => reject(new Error(`聚合超时（>${String(AGG_TIMEOUT_MS / 1000)}s）`)), AGG_TIMEOUT_MS);
+                        timer = setTimeout(() => {
+                            /*
+                             * 顺序是**先取消、后拒绝**（D161）：反过来的话调用方在 reject 的那一刻就拿到
+                             * `ok:false` 返回了，而底层（本地子进程 / SSH channel）还在跑——用户看到的是
+                             * 「这一格失败了」，实际那条 inspect 还占着远端的 session 槽，后续短命令被拒。
+                             */
+                            controller.abort();
+                            reject(new Error(`聚合超时（>${String(budget / 1000)}s）`));
+                        }, budget);
                         timer.unref?.();
                     });
                     const data = await Promise.race([run(api, name), timeout]);
@@ -852,6 +1197,12 @@ const plugin = definePlugin({
                 finally {
                     if (timer !== null)
                         clearTimeout(timer);
+                    /*
+                     * race 另一侧赢（命令正常跑完 / 抛错）时也要兜底取消：`abort()` 是幂等的，命令
+                     * 已 settle 时它是**无害的空操作**（监听器在收尾时已摘掉），但漏了这一句就会留下
+                     * 「signal 永不 abort、挂在它上面的闭包链不放」的尾巴。
+                     */
+                    controller.abort();
                 }
             });
         };
@@ -1548,6 +1899,41 @@ const plugin = definePlugin({
                     return { targets: rows };
                 },
             }));
+            add('docker_connect_local', defineTool({
+                name: 'docker_connect_local',
+                // 只读之外的唯一副作用是**写本插件自己的配置**，没有别的写路径；并发调用被 connectLocal 的幂等语义收敛
+                isConcurrencySafe: () => true,
+                description: '添加或复用本机 Docker 目标并探测 daemon，返回目标名、是否新建和连接状态及失败原因。保留已有 SSH 配置；不启动或安装 Docker，不改变 context 或能力授权。随后将返回的 name 作为 docker_ps 等工具的 target。',
+                parameters: {},
+                output: {
+                    schema: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            name: { type: 'string', required: true },
+                            kind: { type: 'string', required: true },
+                            created: { type: 'boolean', required: true },
+                            saved: { type: 'boolean', required: true },
+                            reachable: { type: 'boolean', required: true },
+                            message: { type: 'string', required: true },
+                            serverVersion: { type: 'string' },
+                        },
+                    },
+                    render: (_args, value) => {
+                        const row = value;
+                        return [{
+                                type: 'text',
+                                text: `${row.message}\n后续查询请传 target: ${JSON.stringify(row.name)}`,
+                            }];
+                    },
+                },
+                async execute() {
+                    const outcome = await connectLocal();
+                    if (!outcome.ok)
+                        throw new Error(outcome.error);
+                    return outcome.result;
+                },
+            }));
             add('docker_ps', defineTool({
                 name: 'docker_ps',
                 // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
@@ -2287,6 +2673,7 @@ const plugin = definePlugin({
                             throw new Error(picked.error ?? '无效的 target');
                         if (typeof input.id !== 'string')
                             throw new Error('id 必填');
+                        const id = input.id;
                         const action = input.action;
                         if (action !== 'start' && action !== 'stop' && action !== 'restart' && action !== 'remove') {
                             throw new Error('action 必须是 start / stop / restart / remove');
@@ -2294,7 +2681,7 @@ const plugin = definePlugin({
                         const { api } = apiFor(picked.name);
                         if (api === undefined)
                             throw new Error(resolveByName(picked.name).error ?? '无法构造执行通道');
-                        const result = await api.action({ action, id: input.id });
+                        const result = await audited({ capability: 'allowMutations', source: 'tool', action: `container.${action}`, target: picked.name, ref: id }, () => api.action({ action, id }));
                         return { target: picked.name, id: result.id, action: result.action, message: result.message };
                     },
                 }));
@@ -2329,10 +2716,11 @@ const plugin = definePlugin({
                             throw new Error(picked.error ?? '无效的 target');
                         if (typeof input.ref !== 'string' || input.ref.trim() === '')
                             throw new Error('ref 必填');
+                        const ref = input.ref;
                         const { api } = apiFor(picked.name);
                         if (api === undefined)
                             throw new Error(resolveByName(picked.name).error ?? '无法构造执行通道');
-                        const result = await api.imageRemove(input.ref);
+                        const result = await audited({ capability: 'allowMutations', source: 'tool', action: 'image.remove', target: picked.name, ref }, () => api.imageRemove(ref));
                         return { target: picked.name, ref: result.ref, message: result.message };
                     },
                 }));
@@ -2364,7 +2752,7 @@ const plugin = definePlugin({
                         const { api } = apiFor(picked.name);
                         if (api === undefined)
                             throw new Error(resolveByName(picked.name).error ?? '无法构造执行通道');
-                        const result = await api.imagePrune();
+                        const result = await audited({ capability: 'allowMutations', source: 'tool', action: 'image.prune', target: picked.name }, () => api.imagePrune());
                         return { target: picked.name, message: result.message };
                     },
                 }));
@@ -2403,11 +2791,12 @@ const plugin = definePlugin({
                             throw new Error(picked.error ?? '无效的 target');
                         if (typeof input.ref !== 'string' || input.ref.trim() === '')
                             throw new Error('ref 必填');
+                        const ref = input.ref;
                         const { api } = apiFor(picked.name);
                         if (api === undefined)
                             throw new Error(resolveByName(picked.name).error ?? '无法构造执行通道');
                         const timeoutSec = typeof input.timeoutSec === 'number' && Number.isInteger(input.timeoutSec) ? input.timeoutSec : 600;
-                        const result = await api.pull(input.ref, timeoutSec * 1000);
+                        const result = await audited({ capability: 'allowMutations', source: 'tool', action: 'image.pull', target: picked.name, ref }, () => api.pull(ref, timeoutSec * 1000), (row) => row.code === null ? undefined : `code=${String(row.code)}`);
                         return {
                             target: picked.name,
                             ref: result.ref,
@@ -2464,11 +2853,13 @@ const plugin = definePlugin({
                             throw new Error('id 必填');
                         if (typeof input.command !== 'string' || input.command.trim() === '')
                             throw new Error('command 必填');
+                        const id = input.id;
+                        const command = input.command;
                         const timeoutSec = typeof input.timeoutSec === 'number' && Number.isInteger(input.timeoutSec) ? input.timeoutSec : live.execTimeoutSec;
                         const { api } = apiFor(picked.name);
                         if (api === undefined)
                             throw new Error(resolveByName(picked.name).error ?? '无法构造执行通道');
-                        const result = await api.exec(input.id, input.command, timeoutSec * 1000);
+                        const result = await audited({ capability: 'allowExec', source: 'tool', action: 'exec', target: picked.name, ref: id }, () => api.exec(id, command, timeoutSec * 1000), (row) => `code=${String(row.code)} cmd=${row.command}`);
                         return {
                             target: picked.name,
                             id: result.id,
@@ -2480,6 +2871,13 @@ const plugin = definePlugin({
                     },
                 }));
             }
+            // 档位闸与工具同生命周期：refreshTools 幂等重建时随 toolDisposers 一起撤下/重挂
+            // （禁用热生效时工具与闸一起撤；机制见 kit 的 tier-gate.ts，方案见 docs/permission-tier-plan.md）。
+            toolDisposers.push(attachTierGate(ctx, {
+                pkg: 'docker',
+                prefixes: DOCKER_TIER_PREFIXES,
+                classify: (tool) => DOCKER_TIER_CLASS[tool],
+            }));
             if (failures.length > 0) {
                 console.warn(`[dsh-docker] ${String(failures.length)} 个 agent 工具注册失败（下次配置变更会重试）：${failures.join('；')}`);
             }
@@ -2842,6 +3240,8 @@ const plugin = definePlugin({
                 writeJson(res, 400, { error: built.error ?? '无法构造执行通道' });
                 return;
             }
+            // run 回调里 TS 不保留 picked.name 的属性窄化，先落局部 const
+            const targetName = picked.name;
             await openSseStream(res, {
                 reason: 'pull-exit',
                 // 同日志流：逐层进度是文本尾部流，积压时丢最旧而不是把整条流掐掉（D153）
@@ -2852,13 +3252,26 @@ const plugin = definePlugin({
                     const coalescer = createSseCoalescer({
                         emit: (channel, text) => sendEvent('line', channel === 'd' ? { d: text } : { e: text }),
                     });
+                    /*
+                     * 使用审计拆成 start / end 两行（capability-use 是逐次事件，不是逐行日志）：
+                     * 开流记 start（宿主中途挂掉时至少「有人拉过这个镜像」还在），收尾记 end——
+                     * 被中止时 runner 以 code=null 落定，end 行省略 code；抛错则 ok=false + detail。
+                     */
+                    const useFields = { capability: 'allowMutations', source: 'http', action: 'image.pull', target: targetName, ref: safeRef };
+                    const startedAt = Date.now();
+                    auditCapabilityUse({ ...useFields, event: 'start' });
                     try {
                         const result = await api.pullStream(safeRef, {
                             onStdout: (chunk) => coalescer.push('d', chunk),
                             onStderr: (chunk) => coalescer.push('e', chunk),
                         }, signal);
+                        auditCapabilityUse({ ...useFields, event: 'end', ok: true, durationMs: Date.now() - startedAt, reason: 'pull-exit', ...(result.code === null ? {} : { code: result.code }) });
                         return result.code;
                     }
+                    catch (error) {
+                        auditCapabilityUse({ ...useFields, event: 'end', ok: false, durationMs: Date.now() - startedAt, detail: error instanceof Error ? error.message : String(error) });
+                        throw error;
+                    }
                     finally {
                         coalescer.flush();
                         coalescer.dispose();
@@ -3039,6 +3452,29 @@ const plugin = definePlugin({
                             writeJson(res, 200, { ok: true, config: snapshot(), ...(warning === undefined ? {} : { warning }) });
                             return;
                         }
+                        /*
+                         * 一键连接本机：把「加一个 local 目标」从「先开设置卡片、手填名字、保存、再切回来」压缩成一下。
+                         * 为什么是显式按钮而不是隐式默认目标：空 `targets` 的语义（= 用户没配、面板给引导）不能被悄悄改掉。
+                         * 只读探测的结果作为 `message` 回传（含「daemon 未启动 / CLI 缺失」的成因），
+                         * 客户端拿它直接给提示，不必再单独发一次 /probe 往返。
+                         */
+                        if (sub === '/connect-local') {
+                            if (req.method !== 'POST') {
+                                writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                                return;
+                            }
+                            if (!hasSameOriginProof(req)) {
+                                writeJson(res, 403, { error: originProofHint(req) });
+                                return;
+                            }
+                            const outcome = await connectLocal();
+                            if (!outcome.ok) {
+                                writeJson(res, outcome.code, { error: outcome.error });
+                                return;
+                            }
+                            writeJson(res, 200, { ok: true, result: outcome.result, config: snapshot() });
+                            return;
+                        }
                         if (sub === '/targets') {
                             if (req.method !== 'GET' && req.method !== 'POST') {
                                 writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
@@ -3270,7 +3706,10 @@ const plugin = definePlugin({
                                         writeJson(res, 400, { error: 'ref 必填' });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.imageRemove(body.ref) });
+                                    // 能力闸之后包审计（「使用 = 过了闸」；403 不记）——下同；
+                                    // ref 先落局部 const：回调里 TS 不保留属性窄化
+                                    const ref = body.ref;
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: 'image.remove', target: picked.name, ref }, () => api.imageRemove(ref)) });
                                     return;
                                 }
                                 case '/images/prune': {
@@ -3278,7 +3717,7 @@ const plugin = definePlugin({
                                         writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.imagePrune() });
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: 'image.prune', target: picked.name }, () => api.imagePrune()) });
                                     return;
                                 }
                                 case '/networks': {
@@ -3302,7 +3741,8 @@ const plugin = definePlugin({
                                         writeJson(res, 400, { error: 'name 必填' });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.networkRemove(body.name) });
+                                    const name = body.name;
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: 'network.remove', target: picked.name, ref: name }, () => api.networkRemove(name)) });
                                     return;
                                 }
                                 case '/networks/prune': {
@@ -3310,7 +3750,7 @@ const plugin = definePlugin({
                                         writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.networkPrune() });
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: 'network.prune', target: picked.name }, () => api.networkPrune()) });
                                     return;
                                 }
                                 case '/volumes': {
@@ -3334,7 +3774,8 @@ const plugin = definePlugin({
                                         writeJson(res, 400, { error: 'name 必填' });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.volumeRemove(body.name) });
+                                    const name = body.name;
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: 'volume.remove', target: picked.name, ref: name }, () => api.volumeRemove(name)) });
                                     return;
                                 }
                                 case '/volumes/prune': {
@@ -3342,7 +3783,7 @@ const plugin = definePlugin({
                                         writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.volumePrune() });
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: 'volume.prune', target: picked.name }, () => api.volumePrune()) });
                                     return;
                                 }
                                 case '/action': {
@@ -3359,7 +3800,8 @@ const plugin = definePlugin({
                                         writeJson(res, 400, { error: 'action 必须是 start / stop / restart / remove' });
                                         return;
                                     }
-                                    writeJson(res, 200, { ok: true, result: await api.action({ action, id: body.id }) });
+                                    const id = body.id;
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowMutations', source: 'http', action: `container.${action}`, target: picked.name, ref: id }, () => api.action({ action, id })) });
                                     return;
                                 }
                                 case '/exec': {
@@ -3372,7 +3814,11 @@ const plugin = definePlugin({
                                         return;
                                     }
                                     const timeoutSec = typeof body.timeoutSec === 'number' && Number.isInteger(body.timeoutSec) ? body.timeoutSec : live.execTimeoutSec;
-                                    writeJson(res, 200, { ok: true, result: await api.exec(body.id, body.command, timeoutSec * 1000) });
+                                    const id = body.id;
+                                    const command = body.command;
+                                    // exec 的退出码是命令自己的结果（非 0 不是 docker 报错）：ok 只随 api 成败；
+                                    // 命令随行进日志（这是要写进 README 的代价）——截断与控制字符转义由 helper 统一做
+                                    writeJson(res, 200, { ok: true, result: await audited({ capability: 'allowExec', source: 'http', action: 'exec', target: picked.name, ref: id }, () => api.exec(id, command, timeoutSec * 1000), (row) => `code=${String(row.code)} cmd=${row.command}`) });
                                     return;
                                 }
                                 default: {
@@ -3408,6 +3854,7 @@ const plugin = definePlugin({
                 // 卡片是自定义页（plugins.row.config），别再让 DSH 为本 entry 自动生成一份。
                 const offAutoPage = suppressAutoSettingsPage(settingsCtx, ctx);
                 settingsScope = scope;
+                settingsForms = settingsCtx.settings;
                 settingsApi = { get: (ns) => readSettingsEntry(settingsCtx, ns) };
                 // 立刻读一次 resolved 值（schema 默认值 ← composition base ← 用户层）。
                 // 走 applySection 而不是直接 normalizeConfig：能力开关的**配置值**要一起记下来（见
@@ -3425,6 +3872,7 @@ const plugin = definePlugin({
                     off();
                     offAutoPage();
                     settingsScope = undefined;
+                    settingsForms = undefined;
                     settingsApi = undefined;
                 };
             }, 'dsh-docker: settings');