@hyzyn/dsh-docker 0.9.6 → 0.10.0

package/lib/audit.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 能力使用审计（capability-use audit）：把「授权了」和「用了」接成闭环。
+ *
+ * ## 它解决什么
+ *
+ * 授权链已有完整审计（kit `elevation.ts` 的 begin / grant / expire / revoke / load 五行），但
+ * **授权之后能力被用来干了什么**此前没有台账（README 已知限制自认的一条）。本模块给每一次
+ * **过了能力闸**的变更 / exec 操作落一行结构化审计行，两条入口都覆盖：
+ *   - `source=http`（面板路由，`/action`、`/images/remove` 等 8 条）；
+ *   - `source=tool`（agent 工具 `docker_action` 等 5 个，走 DockerApi、不经 HTTP 路由，不会重复计数）。
+ *
+ * 行格式（对齐 kit elevation 审计行的 key=value 风格）：
+ *
+ *   [dsh-docker] capability-use: capability=allowMutations source=http action=container.remove target=web ref=shop-web-1 ok=true durationMs=123
+ *
+ * `capability` 刻意与能力开关同名（`allowMutations` / `allowExec`）：审计行必须能和 elevation 的
+ * 授权行对上号，这是本模块的全部意义。
+ *
+ * ## 「使用 = 过了闸」的单一语义
+ *
+ *   - **403 拒绝不记**：请求被闸挡回，能力没有被使用（也没有 docker 侧的任何后果）；
+ *     宿主侧授权状态的变化已由 elevation 五行覆盖。tier-gate 的 ask / deny 同样不记：
+ *     ask 只是询问、没有执行（不是使用），deny 的放行与否由宿主的 approval 日志兜着。
+ *   - **docker 报错也算一次使用**：`ok=false` + `detail=` 截断后的错误文案——「试过删一个容器
+ *     失败了」与「删成功了」同样是审计要回答的问题。错误按原路径 rethrow，不改调用方的错误处理。
+ *
+ * ## 脱敏与截断（硬规矩，helper 统一做，不靠调用点自觉）
+ *
+ * 日志会落盘（宿主的启动失败报告会带上最近日志），所以：
+ *   - exec 的 `command` 记进 `detail` 时**截断到 200 字符**（含 `…` 截断信号，与全仓「截断要有
+ *     信号」同一取向）、**控制字符转义成 `\n` 等字面量**——保证「一行就是一次事件」，命令里的
+ *     换行伪造不出第二行审计；错误文案同样处理。
+ *   - 刻意**不转义空格**：`detail` 是自由文本区（永远在行尾，解析器按字段序取前段不受它干扰），
+ *     `ref` 过了 assertRef / assertImageRef / assertName 白名单（无空格），`target` 是用户自己
+ *     配置的目标名——可读性优先于机器可解析。
+ *   - 与 elevation「nonce 绝不进日志」是同一类取舍的正面：这条**代价**（exec 命令截断 200 字符
+ *     进日志）已写进插件 README 的已知限制。
+ *
+ * ## 出口为什么是 console 而不是 ctx.logger（docker D162）
+ *
+ * 真机验收（2026-10-07，DSH 0.2.1-alpha.1）实测：插件经 `ctx.logger.info` 打的行**既不出现在
+ * 宿主 stdout、也找不到落盘文件**——能看到的 `[dsh-docker]` 行全部是 `console.log` 调用点
+ * （mounted / config applied / agent tools registered / tier-gate；tier-gate 的日志出口默认就是
+ * console，见 kit `tier-gate.ts`）。审计行走 ctx.logger 等于在真宿主上无处可查，而「出问题时翻
+ * 得到」正是审计存在的意义。所以出口固定走 `console.log`（前缀里已带 `[dsh-docker]`），
+ * **不做参数**：出口是本模块的取舍，不是调用方的选择。kit elevation 的授权行（begin / grant /
+ * expire / revoke / load）走的仍是 ctx.logger，同一问题记在根 ROADMAP 待办——修好后两类行同通道。
+ *
+ * ## 为什么在 docker 包、不在 kit
+ *
+ * 按 conventions 的 L0/L1 边界判据（改一个包就能做完 → L1）：目前只有 docker 一个插件需要使用
+ * 审计。**晋升条件**：当第二个插件（tty）也要接同一套「capability-use」行时，把本模块上提
+ * `@hyzyn/dsh-kit`，并把日志前缀做成参数（对齐 elevation 的 `logPrefix`）——在那之前不要提前抽象。
+ */
+/** 审计行挂的能力开关名：与授权行（elevation load/grant）对得上号。 */
+export type CapabilityName = 'allowMutations' | 'allowExec';
+/** 使用入口：面板路由（http）｜agent 工具（tool）。 */
+export type CapabilityUseSource = 'http' | 'tool';
+/**
+ * action 的**固定词表**：`<资源>.<动作>`（exec 自成一格）。新增变更操作时先来这里加词，
+ * 再接调用点——审计行的消费方（人 + 日志检索）靠词表稳定。
+ */
+export type CapabilityUseAction = 'container.start' | 'container.stop' | 'container.restart' | 'container.remove' | 'image.remove' | 'image.prune' | 'image.pull' | 'network.remove' | 'network.prune' | 'volume.remove' | 'volume.prune' | 'exec';
+/** 一次使用的基本字段（`audited` 的入参）。 */
+export interface CapabilityUseFields {
+    capability: CapabilityName;
+    source: CapabilityUseSource;
+    action: CapabilityUseAction;
+    /** 目标名（docker 目标的配置名）。 */
+    target: string;
+    /** 容器名/ID、镜像引用、网络/卷名；prune 这类无目标的操作省略。 */
+    ref?: string;
+}
+/** 一条完整审计行的字段（含结果侧）。 */
+export interface CapabilityUseLine extends CapabilityUseFields {
+    /** 操作本身成败：docker 报错也算一次使用（ok=false + detail）。 */
+    ok?: boolean;
+    /** 命令耗时（`audited` 计时；start 行没有）。 */
+    durationMs?: number;
+    /** 失败原因 / exec 退出码等补充（截断 + 转义）。 */
+    detail?: string;
+    /** 长流（pull 进度流）专用：开流 `start`、收尾 `end`——中途宿主挂掉时至少 start 行还在。 */
+    event?: 'start' | 'end';
+    /** end 行的收尾原因（与 SSE end 帧的 reason 同源）。 */
+    reason?: string;
+    /** end 行的 docker 退出码（被中止时为 null，省略）。 */
+    code?: number | null;
+}
+/** 字符串值统一截断上限（exec 命令、错误文案；硬规矩见文件头）。 */
+export declare const AUDIT_DETAIL_MAX_CHARS = 200;
+/**
+ * 统一的截断 + 转义：先按**原始字符数**截断（补 `…` 信号），再逐字符转义控制字符。
+ * 单次遍历、不存在二次转义；空格刻意保留（取舍见文件头「脱敏与截断」）。
+ */
+export declare function sanitizeAuditValue(text: string, maxChars?: number): string;
+/** 把一条使用审计行打到宿主 stdout（出口取舍见文件头「出口为什么是 console」，docker D162）。 */
+export declare function auditCapabilityUse(fields: CapabilityUseLine): void;
+/**
+ * 包一层变更 / exec 调用：计时 → try/catch → 审计（成功与失败都记）→ 失败原样 rethrow。
+ *
+ * 只该放在**能力闸判定之后**（403 分支之后）——「使用 = 过了闸」。`detailOf` 可选：exec / pull
+ * 这类「api 成功返回但带退出码」的操作用它组 detail——exec 记 `code=… cmd=…`（**命令会进日志**，
+ * 这是写进 README 的代价），pull 只记退出码；整段 detail 的 200 截断与控制字符转义由 emit 时的
+ * `sanitizeAuditValue` 统一做（单一出口，不在调用点各写一遍）。失败路径的 detail 是错误文案。
+ */
+export declare function audited<T>(fields: CapabilityUseFields, run: () => Promise<T>, detailOf?: (result: T) => string | undefined): Promise<T>;

package/lib/audit.js

@@ -0,0 +1,140 @@
+/**
+ * 能力使用审计（capability-use audit）：把「授权了」和「用了」接成闭环。
+ *
+ * ## 它解决什么
+ *
+ * 授权链已有完整审计（kit `elevation.ts` 的 begin / grant / expire / revoke / load 五行），但
+ * **授权之后能力被用来干了什么**此前没有台账（README 已知限制自认的一条）。本模块给每一次
+ * **过了能力闸**的变更 / exec 操作落一行结构化审计行，两条入口都覆盖：
+ *   - `source=http`（面板路由，`/action`、`/images/remove` 等 8 条）；
+ *   - `source=tool`（agent 工具 `docker_action` 等 5 个，走 DockerApi、不经 HTTP 路由，不会重复计数）。
+ *
+ * 行格式（对齐 kit elevation 审计行的 key=value 风格）：
+ *
+ *   [dsh-docker] capability-use: capability=allowMutations source=http action=container.remove target=web ref=shop-web-1 ok=true durationMs=123
+ *
+ * `capability` 刻意与能力开关同名（`allowMutations` / `allowExec`）：审计行必须能和 elevation 的
+ * 授权行对上号，这是本模块的全部意义。
+ *
+ * ## 「使用 = 过了闸」的单一语义
+ *
+ *   - **403 拒绝不记**：请求被闸挡回，能力没有被使用（也没有 docker 侧的任何后果）；
+ *     宿主侧授权状态的变化已由 elevation 五行覆盖。tier-gate 的 ask / deny 同样不记：
+ *     ask 只是询问、没有执行（不是使用），deny 的放行与否由宿主的 approval 日志兜着。
+ *   - **docker 报错也算一次使用**：`ok=false` + `detail=` 截断后的错误文案——「试过删一个容器
+ *     失败了」与「删成功了」同样是审计要回答的问题。错误按原路径 rethrow，不改调用方的错误处理。
+ *
+ * ## 脱敏与截断（硬规矩，helper 统一做，不靠调用点自觉）
+ *
+ * 日志会落盘（宿主的启动失败报告会带上最近日志），所以：
+ *   - exec 的 `command` 记进 `detail` 时**截断到 200 字符**（含 `…` 截断信号，与全仓「截断要有
+ *     信号」同一取向）、**控制字符转义成 `\n` 等字面量**——保证「一行就是一次事件」，命令里的
+ *     换行伪造不出第二行审计；错误文案同样处理。
+ *   - 刻意**不转义空格**：`detail` 是自由文本区（永远在行尾，解析器按字段序取前段不受它干扰），
+ *     `ref` 过了 assertRef / assertImageRef / assertName 白名单（无空格），`target` 是用户自己
+ *     配置的目标名——可读性优先于机器可解析。
+ *   - 与 elevation「nonce 绝不进日志」是同一类取舍的正面：这条**代价**（exec 命令截断 200 字符
+ *     进日志）已写进插件 README 的已知限制。
+ *
+ * ## 出口为什么是 console 而不是 ctx.logger（docker D162）
+ *
+ * 真机验收（2026-10-07，DSH 0.2.1-alpha.1）实测：插件经 `ctx.logger.info` 打的行**既不出现在
+ * 宿主 stdout、也找不到落盘文件**——能看到的 `[dsh-docker]` 行全部是 `console.log` 调用点
+ * （mounted / config applied / agent tools registered / tier-gate；tier-gate 的日志出口默认就是
+ * console，见 kit `tier-gate.ts`）。审计行走 ctx.logger 等于在真宿主上无处可查，而「出问题时翻
+ * 得到」正是审计存在的意义。所以出口固定走 `console.log`（前缀里已带 `[dsh-docker]`），
+ * **不做参数**：出口是本模块的取舍，不是调用方的选择。kit elevation 的授权行（begin / grant /
+ * expire / revoke / load）走的仍是 ctx.logger，同一问题记在根 ROADMAP 待办——修好后两类行同通道。
+ *
+ * ## 为什么在 docker 包、不在 kit
+ *
+ * 按 conventions 的 L0/L1 边界判据（改一个包就能做完 → L1）：目前只有 docker 一个插件需要使用
+ * 审计。**晋升条件**：当第二个插件（tty）也要接同一套「capability-use」行时，把本模块上提
+ * `@hyzyn/dsh-kit`，并把日志前缀做成参数（对齐 elevation 的 `logPrefix`）——在那之前不要提前抽象。
+ */
+/** 字符串值统一截断上限（exec 命令、错误文案；硬规矩见文件头）。 */
+export const AUDIT_DETAIL_MAX_CHARS = 200;
+/**
+ * 统一的截断 + 转义：先按**原始字符数**截断（补 `…` 信号），再逐字符转义控制字符。
+ * 单次遍历、不存在二次转义；空格刻意保留（取舍见文件头「脱敏与截断」）。
+ */
+export function sanitizeAuditValue(text, maxChars = AUDIT_DETAIL_MAX_CHARS) {
+    let value = text;
+    let truncated = false;
+    if (value.length > maxChars) {
+        value = value.slice(0, maxChars);
+        truncated = true;
+    }
+    let out = '';
+    for (const char of value) {
+        if (char === '\\')
+            out += '\\\\';
+        else if (char === '\n')
+            out += '\\n';
+        else if (char === '\r')
+            out += '\\r';
+        else if (char === '\t')
+            out += '\\t';
+        else {
+            const code = char.codePointAt(0) ?? 0;
+            // 其余 C0/C1 控制字符（含 DEL）：十六进制字面量，保住「一行一次事件」
+            out += code < 0x20 || code === 0x7f ? `\\x${code.toString(16).padStart(2, '0')}` : char;
+        }
+    }
+    return truncated ? out + '…' : out;
+}
+/** 把一条使用审计行打到宿主 stdout（出口取舍见文件头「出口为什么是 console」，docker D162）。 */
+export function auditCapabilityUse(fields) {
+    const parts = [
+        `capability=${fields.capability}`,
+        `source=${fields.source}`,
+        `action=${fields.action}`,
+        `target=${sanitizeAuditValue(fields.target)}`,
+    ];
+    if (fields.ref !== undefined && fields.ref !== '')
+        parts.push(`ref=${sanitizeAuditValue(fields.ref)}`);
+    if (fields.event !== undefined)
+        parts.push(`event=${fields.event}`);
+    if (fields.ok !== undefined)
+        parts.push(`ok=${fields.ok ? 'true' : 'false'}`);
+    if (fields.durationMs !== undefined)
+        parts.push(`durationMs=${String(Math.max(0, Math.round(fields.durationMs)))}`);
+    if (fields.reason !== undefined)
+        parts.push(`reason=${sanitizeAuditValue(fields.reason)}`);
+    if (fields.code !== undefined && fields.code !== null)
+        parts.push(`code=${String(fields.code)}`);
+    if (fields.detail !== undefined)
+        parts.push(`detail=${sanitizeAuditValue(fields.detail)}`);
+    console.log(`[dsh-docker] capability-use: ${parts.join(' ')}`);
+}
+/**
+ * 包一层变更 / exec 调用：计时 → try/catch → 审计（成功与失败都记）→ 失败原样 rethrow。
+ *
+ * 只该放在**能力闸判定之后**（403 分支之后）——「使用 = 过了闸」。`detailOf` 可选：exec / pull
+ * 这类「api 成功返回但带退出码」的操作用它组 detail——exec 记 `code=… cmd=…`（**命令会进日志**，
+ * 这是写进 README 的代价），pull 只记退出码；整段 detail 的 200 截断与控制字符转义由 emit 时的
+ * `sanitizeAuditValue` 统一做（单一出口，不在调用点各写一遍）。失败路径的 detail 是错误文案。
+ */
+export async function audited(fields, run, detailOf) {
+    const startedAt = Date.now();
+    try {
+        const result = await run();
+        auditCapabilityUse({
+            ...fields,
+            ok: true,
+            durationMs: Date.now() - startedAt,
+            detail: detailOf?.(result),
+        });
+        return result;
+    }
+    catch (error) {
+        auditCapabilityUse({
+            ...fields,
+            ok: false,
+            durationMs: Date.now() - startedAt,
+            detail: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=audit.js.map

package/lib/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -20,9 +20,13 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { DockerApi, assertBin, assertImageRef, parseImageHistoryJson, parseImageHistoryText, parseImageInspectJson, parseInspectJson, parsePsJson, parseStatsJson } from './docker.js';
 import type { DockerTarget, ResolvedTarget } from './docker.js';
+import type { TierClass } from '@hyzyn/dsh-kit';
 import type { HostKeyRecord, SshSpec } from './ssh-exec.js';
 export type { HostKeyRecord } from './ssh-exec.js';
 export type { ContainerSummary, ContainerDetail, ContainerStats, ContainerEvent, ImageSummary, NetworkSummary, NetworkDetail, VolumeSummary, VolumeDetail, DockerTarget } from './docker.js';
+export declare const DOCKER_TIER_CLASS: Record<string, TierClass>;
+/** 本插件 agent 工具的名单前缀（档位闸只听这些名字）。 */
+export declare const DOCKER_TIER_PREFIXES: readonly ["docker_"];
 export interface Config {
     /** 关闭整个插件。默认开。 */
     enabled?: boolean;

package/lib/index.js

@@ -3,9 +3,40 @@ 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'),
@@ -762,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 ?? {}));
         /*
@@ -2642,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');
@@ -2649,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 };
                     },
                 }));
@@ -2684,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 };
                     },
                 }));
@@ -2719,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 };
                     },
                 }));
@@ -2758,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,
@@ -2819,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,
@@ -2835,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('；')}`);
             }
@@ -3197,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）
@@ -3207,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();
@@ -3648,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': {
@@ -3656,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': {
@@ -3680,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': {
@@ -3688,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': {
@@ -3712,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': {
@@ -3720,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': {
@@ -3737,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': {
@@ -3750,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: {