@stardustlc/dsh-docker 0.1.0

package/README.en.md

@@ -0,0 +1,70 @@
+[中文](README.md)
+
+# dsh-docker
+
+> **Your agent can manage containers now**: five tools covering container listing, logs, inspection, in-container exec, and lifecycle management.
+
+DSH (DeepSeek Harness) container-management plugin: runs the docker CLI through the official subprocess service with shell-free argv arrays, an approval gate on `docker_exec`, and **zero runtime dependencies**.
+
+![npm version](https://img.shields.io/npm/v/dsh-docker?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-docker) ![license](https://img.shields.io/npm/l/dsh-docker) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-docker?style=social)
+
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+## Installation
+
+```bash
+dsh plugin --profile web add @stardustlc/dsh-docker
+```
+
+Requires Docker installed locally (`docker version` should work); use `dockerPath` when it is not on PATH.
+
+## Configuration
+
+```yaml
+- id: docker
+  name: '@stardustlc/dsh-docker'
+  config:
+    # dockerPath: C:\Program Files\Docker\Docker\resources\bin\docker.exe
+    timeoutMs: 60000       # per-operation timeout (default 60s, 5s - 10min)
+    # execApproval: false  # disable the docker_exec approval gate (default true)
+```
+
+## Tools
+
+| Tool | Purpose | Safety |
+| :-- | :-- | :-- |
+| `docker_ps` | List containers (status/image/state, filterable) | — |
+| `docker_logs` | Tail container logs (line clamp, short follow) | — |
+| `docker_inspect` | Container details (image/state/ports) | — |
+| `docker_exec` | Run a command inside a container | Approval gate + container-name validation |
+| `docker_manage` | start / stop / restart / rm | Destructive actions clearly labeled |
+
+### Examples
+
+```text
+docker_ps {}
+docker_ps { all: true, name: web }
+docker_logs { container: web, tail: 200 }
+docker_inspect { container: web }
+docker_exec { container: web, command: 'df -h' }
+docker_manage { container: web, action: restart }
+```
+
+## Safety
+
+- **No shell**: every argument is its own argv element — command injection is impossible
+- **Approval gate**: docker_exec asks first (mirroring dsh-email / dsh-sql); headless environments without an approval channel are denied
+- **Container-name validation**: only `[A-Za-z0-9][A-Za-z0-9_.:-]*` accepted — no argument injection
+- **Timeout clamps**: 5s - 10min per operation; follow mode capped at an extra 30s
+- **Log clamping**: tail 1-2000 lines
+
+## Development
+
+```bash
+pnpm install
+pnpm test       # build + 24 tests
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,70 @@
+[English](README.en.md)
+
+# dsh-docker
+
+> **你的 agent 会管容器了**：五个工具覆盖容器列表、日志、详情、容器内执行与生命周期管理。
+
+DSH（DeepSeek Harness）容器管理插件：走官方 subprocess 服务跑 docker CLI，argv 数组无 shell 注入，`docker_exec` 默认审批门，**零运行时依赖**。
+
+![npm version](https://img.shields.io/npm/v/dsh-docker?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-docker) ![license](https://img.shields.io/npm/l/dsh-docker) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-docker?style=social)
+
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+## 安装
+
+```bash
+dsh plugin --profile web add @stardustlc/dsh-docker
+```
+
+需要本机装有 Docker（`docker version` 能出结果即可）；不在 PATH 上时用 `dockerPath` 指定。
+
+## 配置
+
+```yaml
+- id: docker
+  name: '@stardustlc/dsh-docker'
+  config:
+    # dockerPath: C:\Program Files\Docker\Docker\resources\bin\docker.exe
+    timeoutMs: 60000       # 单次操作超时（默认 60 秒，5 秒 - 10 分钟）
+    # execApproval: false  # 关闭 docker_exec 审批门（默认 true）
+```
+
+## 工具一览
+
+| 工具 | 作用 | 安全 |
+| :-- | :-- | :-- |
+| `docker_ps` | 列出容器（状态/镜像/运行态，可过滤）| — |
+| `docker_logs` | 查看日志尾部（行数钳制，可短时 follow）| — |
+| `docker_inspect` | 容器详情（镜像/状态/端口）| — |
+| `docker_exec` | 容器内执行命令 | 审批门 + 容器名白名单校验 |
+| `docker_manage` | start / stop / restart / rm | 明确提示破坏性 |
+
+### 示例
+
+```text
+docker_ps {}
+docker_ps { all: true, name: web }
+docker_logs { container: web, tail: 200 }
+docker_inspect { container: web }
+docker_exec { container: web, command: 'df -h' }
+docker_manage { container: web, action: restart }
+```
+
+## 安全设计
+
+- **无 shell**：全部参数独立 argv 数组，命令注入不可能
+- **审批门**：docker_exec 默认弹审批（对齐 dsh-email / dsh-sql），headless 无审批通道时拒绝
+- **容器名校验**：只允许 `[A-Za-z0-9][A-Za-z0-9_.:-]*`，杜绝参数注入
+- **超时钳制**：单次操作 5 秒 - 10 分钟；follow 模式额外限 30 秒
+- **日志钳制**：tail 1-2000 行
+
+## 开发
+
+```bash
+pnpm install
+pnpm test       # 构建 + 24 个测试
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-docker 组合包补丁：把容器管理工具插件行插入 profile。
+# 本补丁按 id 覆盖；用户应在自己 profile 的 cordis.patch.yml 里覆盖本行的整个
+# config（见 README 的配置示例）。配置缺失时插件仍会加载（依赖 PATH 上的 docker）。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: docker
+#     name: '@stardustlc/dsh-docker'
+#     config:
+#       # dockerPath: C:\Program Files\Docker\Docker\resources\bin\docker.exe
+#       timeoutMs: 60000       # 单次操作超时（默认 60 秒，5 秒 - 10 分钟）
+#       # execApproval: false  # 关闭 docker_exec 的审批门（默认 true）
+#
+- insert:
+    - id: docker
+      name: '@stardustlc/dsh-docker'
+      config:
+        timeoutMs: 60000

package/lib/args.d.ts

@@ -0,0 +1,17 @@
+/**
+ * docker CLI argv 构建器：纯函数，argv 数组、无 shell。
+ *
+ * @module dsh-docker/args
+ */
+/** 列出容器（JSON 格式，全部或按名称过滤）。 */
+export declare function psArgs(docker: string, all: boolean, filter?: string): string[];
+/** 查看日志（tail 钳制）。 */
+export declare function logsArgs(docker: string, container: string, tail: number, follow: boolean): string[];
+/** 查看详情（docker inspect 原生 JSON）。 */
+export declare function inspectArgs(docker: string, container: string): string[];
+/** 容器内执行命令。 */
+export declare function execArgs(docker: string, container: string, command: string[]): string[];
+/** 生命周期管理：start/stop/restart/rm。 */
+export declare function manageArgs(docker: string, action: 'start' | 'stop' | 'restart' | 'rm', container: string): string[];
+/** 拆分 exec 的命令字符串（按空白，支持引号）。 */
+export declare function splitCommand(command: string): string[];

package/lib/args.js

@@ -0,0 +1,37 @@
+/**
+ * docker CLI argv 构建器：纯函数，argv 数组、无 shell。
+ *
+ * @module dsh-docker/args
+ */
+/** 列出容器（JSON 格式，全部或按名称过滤）。 */
+export function psArgs(docker, all, filter) {
+    const argv = [docker, 'ps', all ? '--all' : '', '--format', 'json'].filter((item) => item !== '');
+    if (filter !== undefined && filter !== '')
+        argv.push('--filter', 'name=' + filter);
+    return argv;
+}
+/** 查看日志（tail 钳制）。 */
+export function logsArgs(docker, container, tail, follow) {
+    return [docker, 'logs', follow ? '--follow' : '', '--tail', String(tail), container].filter((item) => item !== '');
+}
+/** 查看详情（docker inspect 原生 JSON）。 */
+export function inspectArgs(docker, container) {
+    return [docker, 'inspect', container];
+}
+/** 容器内执行命令。 */
+export function execArgs(docker, container, command) {
+    return [docker, 'exec', container, ...command];
+}
+/** 生命周期管理：start/stop/restart/rm。 */
+export function manageArgs(docker, action, container) {
+    const flags = action === 'rm' ? ['rm', '--force'] : [action];
+    return [docker, ...flags, container];
+}
+/** 拆分 exec 的命令字符串（按空白，支持引号）。 */
+export function splitCommand(command) {
+    const parts = [];
+    const matches = command.match(/"[^"]*"|'[^']*'|\S+/g);
+    if (matches === null)
+        return [];
+    return matches.map((part) => part.replace(/^["']|["']$/g, ''));
+}

package/lib/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-docker 配置解析：docker CLI 路径、超时与 exec 审批策略。
+ *
+ * @module dsh-docker/config
+ */
+/** 插件行配置（cordis.patch.yml 里的 config 段，可缺省）。 */
+export interface DockerConfig {
+    dockerPath?: string;
+    timeoutMs?: number;
+    graceMs?: number;
+    execApproval?: boolean;
+}
+/** 解析后的配置。 */
+export interface ResolvedDockerConfig {
+    dockerPath: string;
+    timeoutMs: number;
+    graceMs: number;
+    execApproval: boolean;
+}
+/**
+ * 解析并校验配置。
+ */
+export declare function resolveConfig(config: DockerConfig | undefined | null): ResolvedDockerConfig;
+/** 校验容器名/ID，防参数注入（只允许字母数字与 _-.:/ 之外的拒绝）。 */
+export declare function assertContainerRef(value: string): string;

package/lib/config.js

@@ -0,0 +1,34 @@
+/**
+ * dsh-docker 配置解析：docker CLI 路径、超时与 exec 审批策略。
+ *
+ * @module dsh-docker/config
+ */
+/**
+ * 解析并校验配置。
+ */
+export function resolveConfig(config) {
+    const cfg = config ?? {};
+    const dockerPath = typeof cfg.dockerPath === 'string' && cfg.dockerPath.trim() !== '' ? cfg.dockerPath.trim() : 'docker';
+    let timeoutMs = 60000;
+    if (cfg.timeoutMs !== undefined) {
+        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0)
+            throw new Error('timeoutMs 必须是大于 0 的数字（毫秒）。');
+        timeoutMs = Math.min(10 * 60 * 1000, Math.max(5000, Math.round(cfg.timeoutMs)));
+    }
+    let graceMs = 15000;
+    if (cfg.graceMs !== undefined) {
+        if (typeof cfg.graceMs !== 'number' || !Number.isFinite(cfg.graceMs) || cfg.graceMs <= 0)
+            throw new Error('graceMs 必须是大于 0 的数字（毫秒）。');
+        graceMs = Math.min(120000, Math.max(1000, Math.round(cfg.graceMs)));
+    }
+    const execApproval = cfg.execApproval !== false;
+    return { dockerPath, timeoutMs, graceMs, execApproval };
+}
+/** 校验容器名/ID，防参数注入（只允许字母数字与 _-.:/ 之外的拒绝）。 */
+export function assertContainerRef(value) {
+    const trimmed = value.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(trimmed)) {
+        throw new Error('容器名/ID 非法（只允许字母数字开头，后续可含 _ . : -）：' + value);
+    }
+    return trimmed;
+}

package/lib/exec.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 进程执行层：把 DSH 官方 subprocess 服务包装成 Promise 式 ProcessRunner（与 dsh-ffmpeg 同款）。
+ * 全程 argv 数组、无 shell 解释。
+ *
+ * @module dsh-docker/exec
+ */
+export interface RunResult {
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}
+export interface ProcessRunner {
+    run(argv: readonly string[], options?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+}
+export interface SubprocessHandleLike {
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    collected: {
+        stdout?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+        stderr?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+    };
+    terminate(): void;
+}
+export interface SubprocessSpawnLike {
+    (spec: {
+        argv: readonly string[];
+        cwd: string;
+        stdio: {
+            stdin: 'ignore';
+            stdout: {
+                maxBytes: number;
+            };
+            stderr: {
+                maxBytes: number;
+            };
+        };
+        graceMs: number;
+        signal?: AbortSignal;
+    }): SubprocessHandleLike;
+}
+/** 用 DSH subprocess 服务构造 ProcessRunner。 */
+export declare function createSubprocessRunner(spawn: SubprocessSpawnLike, graceMs: number, defaultTimeoutMs: number): ProcessRunner;

package/lib/exec.js

@@ -0,0 +1,38 @@
+/**
+ * 进程执行层：把 DSH 官方 subprocess 服务包装成 Promise 式 ProcessRunner（与 dsh-ffmpeg 同款）。
+ * 全程 argv 数组、无 shell 解释。
+ *
+ * @module dsh-docker/exec
+ */
+const COLLECT_BYTES = 4 * 1024 * 1024;
+/** 用 DSH subprocess 服务构造 ProcessRunner。 */
+export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
+    return {
+        async run(argv, options) {
+            const timeoutMs = options?.timeoutMs ?? defaultTimeoutMs;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new Error('docker operation timed out')), timeoutMs);
+            let handle;
+            try {
+                handle = spawn({
+                    argv,
+                    cwd: process.cwd(),
+                    stdio: {
+                        stdin: 'ignore',
+                        stdout: { maxBytes: COLLECT_BYTES },
+                        stderr: { maxBytes: COLLECT_BYTES },
+                    },
+                    graceMs,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const outcome = await handle.done;
+            const stdout = handle.collected.stdout?.readFrom(0).text ?? '';
+            const stderr = handle.collected.stderr?.readFrom(0).text ?? '';
+            return { exitCode: outcome.exitCode, signal: outcome.signal, stdout, stderr };
+        },
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * dsh-docker —— 容器管理工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（docker_ps / docker_logs /
+ * docker_inspect / docker_exec / docker_manage）。进程执行走 DSH 官方 subprocess 服务
+ * （argv 数组、无 shell），docker_exec 默认走宿主审批门。零运行时依赖。
+ *
+ * @module dsh-docker
+ */
+import { type DockerConfig } from './config.js';
+import { type SubprocessSpawnLike } from './exec.js';
+import { type DockerToolDefinition } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools。 */
+export declare const inject: string[];
+/** 审批服务最小面。 */
+export interface DockerApproval {
+    request(options: {
+        agent?: unknown;
+        toolName?: unknown;
+        callId?: unknown;
+        reason: string;
+        signal?: unknown;
+    }): Promise<'allowed-once' | 'cancelled' | 'unavailable' | string>;
+}
+/** 插件所需的最小 ctx 面。 */
+export interface DockerPluginContext {
+    subprocess: {
+        spawn: SubprocessSpawnLike;
+    };
+    tools: {
+        register(definition: DockerToolDefinition, options?: {
+            prepend?: boolean;
+        }): () => void;
+    };
+    get?(name: 'approval'): DockerApproval | undefined;
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：解析配置、封装执行器、注册五工具；docker_exec 注入审批门。
+ */
+export declare function apply(ctx: DockerPluginContext, config?: DockerConfig | null): void;
+export * from './args.js';
+export * from './config.js';
+export * from './exec.js';
+export * from './parse.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,70 @@
+/**
+ * dsh-docker —— 容器管理工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（docker_ps / docker_logs /
+ * docker_inspect / docker_exec / docker_manage）。进程执行走 DSH 官方 subprocess 服务
+ * （argv 数组、无 shell），docker_exec 默认走宿主审批门。零运行时依赖。
+ *
+ * @module dsh-docker
+ */
+import { resolveConfig } from './config.js';
+import { createSubprocessRunner } from './exec.js';
+import { buildDockerTools } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools。 */
+export const inject = ['subprocess', 'tools'];
+/**
+ * 插件入口：解析配置、封装执行器、注册五工具；docker_exec 注入审批门。
+ */
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-docker] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const runner = createSubprocessRunner(ctx.subprocess.spawn, cfg.graceMs, cfg.timeoutMs);
+    const tools = buildDockerTools(cfg, runner);
+    const disposers = [];
+    for (const definition of tools) {
+        if (definition.name === 'docker_exec' && cfg.execApproval) {
+            definition.gate = async (exec, next) => {
+                const approval = ctx.get?.('approval');
+                if (approval === undefined) {
+                    return { kind: 'deny', reason: 'docker_exec 需要确认，但当前环境没有审批通道（如 headless）。如确定安全，可在配置中设置 execApproval: false 后直接执行。' };
+                }
+                const record = (typeof exec === 'object' && exec !== null ? exec : {});
+                const args = (typeof record.args === 'object' && record.args !== null ? record.args : {});
+                const command = typeof args.command === 'string' ? args.command : '';
+                const container = typeof args.container === 'string' ? args.container : '';
+                const outcome = await approval.request({
+                    agent: record.agent,
+                    toolName: record.name,
+                    callId: record.callId,
+                    reason: '在容器 ' + container + ' 内执行：' + command.slice(0, 200),
+                    signal: record.signal,
+                });
+                if (outcome === 'allowed-once')
+                    return next();
+                if (outcome === 'cancelled')
+                    return { kind: 'deny', reason: '容器内执行确认被取消，命令未执行。' };
+                if (outcome === 'unavailable')
+                    return { kind: 'deny', reason: '容器内执行确认不可用（没有可用的审批界面），命令未执行。' };
+                return { kind: 'deny', reason: '容器内执行未获批准：要么你拒绝了，要么当前会话处于 Full Access（审批策略 never）。若在 Full Access：切到 Read Only / Write 再执行，或关闭 execApproval（自行承担风险）。' };
+            };
+        }
+        disposers.push(ctx.tools.register(definition, { prepend: true }));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}
+export * from './args.js';
+export * from './config.js';
+export * from './exec.js';
+export * from './parse.js';
+export * from './tools.js';

package/lib/parse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * docker 输出解析：ps JSON 行 → 容器列表；inspect JSON → 摘要。
+ *
+ * @module dsh-docker/parse
+ */
+/** 容器摘要。 */
+export interface ContainerInfo {
+    id: string;
+    name: string;
+    image: string;
+    status: string;
+    state: string;
+}
+/** docker ps --format json 的每一行解析。 */
+export declare function parsePsJson(text: string): ContainerInfo[];
+/** docker inspect 的 JSON 摘要。 */
+export declare function parseInspectJson(text: string): Record<string, unknown>;

package/lib/parse.js

@@ -0,0 +1,46 @@
+/**
+ * docker 输出解析：ps JSON 行 → 容器列表；inspect JSON → 摘要。
+ *
+ * @module dsh-docker/parse
+ */
+/** docker ps --format json 的每一行解析。 */
+export function parsePsJson(text) {
+    const rows = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const raw = JSON.parse(trimmed);
+            rows.push({
+                id: typeof raw.ID === 'string' ? raw.ID : String(raw.ID ?? ''),
+                name: typeof raw.Names === 'string' ? raw.Names : String(raw.Names ?? ''),
+                image: typeof raw.Image === 'string' ? raw.Image : String(raw.Image ?? ''),
+                status: typeof raw.Status === 'string' ? raw.Status : String(raw.Status ?? ''),
+                state: typeof raw.State === 'string' ? raw.State : String(raw.State ?? ''),
+            });
+        }
+        catch { /* 跳过坏行 */ }
+    }
+    return rows;
+}
+/** docker inspect 的 JSON 摘要。 */
+export function parseInspectJson(text) {
+    const raw = JSON.parse(text);
+    if (!Array.isArray(raw) || raw.length === 0)
+        return {};
+    const first = raw[0];
+    const config = (typeof first.Config === 'object' && first.Config !== null ? first.Config : {});
+    const networkSettings = (typeof first.NetworkSettings === 'object' && first.NetworkSettings !== null ? first.NetworkSettings : {});
+    const ports = Array.isArray(networkSettings.Ports) ? networkSettings.Ports : [];
+    const portList = ports.filter((port) => port.PublicPort !== undefined && port.PublicPort !== null);
+    return {
+        id: typeof first.Id === 'string' ? first.Id.slice(0, 12) : String(first.Id ?? '').slice(0, 12),
+        name: typeof first.Name === 'string' ? first.Name.replace(/^\//, '') : '',
+        image: typeof config.Image === 'string' ? config.Image : '',
+        state: (typeof first.State === 'object' && first.State !== null ? first.State.Status : '') ?? '',
+        running: (typeof first.State === 'object' && first.State !== null ? first.State.Running : false) === true,
+        startedAt: (typeof first.State === 'object' && first.State !== null ? first.State.StartedAt : '') ?? '',
+        ports: portList.map((port) => String(port.PublicPort) + '/' + String(port.Type ?? 'tcp')),
+    };
+}

package/lib/tools.d.ts

@@ -0,0 +1,24 @@
+import { type ResolvedDockerConfig } from './config.js';
+import { type ProcessRunner } from './exec.js';
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+export interface DockerToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    gate?(exec: unknown, next: () => Promise<unknown>): Promise<unknown>;
+    timeoutMs?: number;
+}
+/** 构建五个工具定义。 */
+export declare function buildDockerTools(config: ResolvedDockerConfig, runner: ProcessRunner): DockerToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,210 @@
+/**
+ * 五个面向模型的容器工具：docker_ps / docker_logs / docker_inspect / docker_exec / docker_manage。
+ *
+ * @module dsh-docker/tools
+ */
+import { inspectArgs, logsArgs, manageArgs, execArgs, psArgs, splitCommand } from './args.js';
+import { assertContainerRef } from './config.js';
+import { parseInspectJson, parsePsJson } from './parse.js';
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    return value;
+}
+async function runChecked(runner, argv, timeoutMs, label) {
+    const result = await runner.run(argv, { timeoutMs });
+    if (result.exitCode !== 0) {
+        const tail = result.stderr.trim().split(/\r?\n/).slice(-6).join(' | ');
+        throw new Error(label + '失败（退出码 ' + String(result.exitCode ?? 'null') + '）：' + (tail || '无错误输出') + '。请确认 docker 可用（docker version）。');
+    }
+    return result;
+}
+const containerSchema = {
+    type: 'object',
+    properties: { id: { type: 'string' }, name: { type: 'string' }, image: { type: 'string' }, status: { type: 'string' }, state: { type: 'string' } },
+    additionalProperties: true,
+};
+const psSchema = {
+    type: 'object',
+    properties: { count: { type: 'integer' }, all: { type: 'boolean' }, containers: { type: 'array', items: containerSchema } },
+    additionalProperties: true,
+};
+const logsSchema = {
+    type: 'object',
+    properties: { container: { type: 'string' }, tail: { type: 'integer' }, text: { type: 'string' } },
+    additionalProperties: true,
+};
+const inspectSchema = {
+    type: 'object',
+    properties: { container: { type: 'string' }, info: { type: 'object', additionalProperties: true } },
+    additionalProperties: true,
+};
+const execSchema = {
+    type: 'object',
+    properties: { container: { type: 'string' }, exitCode: { type: 'integer' }, stdout: { type: 'string' } },
+    additionalProperties: true,
+};
+const manageSchema = {
+    type: 'object',
+    properties: { container: { type: 'string' }, action: { type: 'string' }, output: { type: 'string' } },
+    additionalProperties: true,
+};
+/** 构建五个工具定义。 */
+export function buildDockerTools(config, runner) {
+    const cfg = config;
+    const timeout = cfg.timeoutMs;
+    const dockerPs = {
+        name: 'docker_ps',
+        description: '列出 Docker 容器（含状态/镜像/运行状态）。all=true 时包含已停止容器；name 可按容器名过滤。',
+        parameters: compileParameters({
+            all: { type: 'boolean', description: '是否包含已停止容器（默认 false）。' },
+            name: { type: 'string', description: '按容器名过滤（可选，子串匹配）。' },
+        }),
+        output: {
+            schema: psSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const containers = Array.isArray(rec.containers) ? rec.containers : [];
+                const lines = ['共 ' + containers.length + ' 个容器：'];
+                for (const item of containers) {
+                    const c = asRecord(item);
+                    lines.push('- ' + c.name + '（' + c.image + '，' + c.state + '）');
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const all = args.all === true;
+            const result = await runChecked(runner, psArgs(cfg.dockerPath, all, optionalString(args, 'name')), timeout, 'docker ps');
+            const containers = parsePsJson(result.stdout);
+            return { count: containers.length, all, containers };
+        },
+        timeoutMs: timeout,
+    };
+    const dockerLogs = {
+        name: 'docker_logs',
+        description: '查看容器日志尾部。container 必填；tail 为行数（1-2000，默认 100）；follow=true 时持续跟踪（受超时限制，一般用于短时观察）。',
+        parameters: compileParameters({
+            container: { type: 'string', required: true, description: '容器名或 ID（必填）。' },
+            tail: { type: 'integer', description: '日志行数 1-2000（默认 100）。' },
+            follow: { type: 'boolean', description: '是否持续跟踪（默认 false，受超时限制）。' },
+        }),
+        output: {
+            schema: logsSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                return [{ type: 'text', text: '容器 ' + rec.container + ' 最近日志：\n' + rec.text }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const container = assertContainerRef(requiredString(args, 'container', '容器名'));
+            const tailRaw = args.tail;
+            const tail = typeof tailRaw === 'number' && Number.isInteger(tailRaw) ? Math.min(2000, Math.max(1, tailRaw)) : 100;
+            const follow = args.follow === true;
+            const result = await runChecked(runner, logsArgs(cfg.dockerPath, container, tail, follow), follow ? Math.min(timeout, 30000) : timeout, 'docker logs');
+            return { container, tail, text: result.stdout };
+        },
+        timeoutMs: timeout,
+    };
+    const dockerInspect = {
+        name: 'docker_inspect',
+        description: '查看容器详情：镜像、运行状态、启动时间、端口映射。',
+        parameters: compileParameters({
+            container: { type: 'string', required: true, description: '容器名或 ID（必填）。' },
+        }),
+        output: {
+            schema: inspectSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const info = asRecord(rec.info);
+                return [{ type: 'text', text: '容器 ' + info.name + '（' + info.image + '）：' + (info.running === true ? '运行中' : '已停止') + '，端口：' + (Array.isArray(info.ports) ? info.ports.join(', ') : '无') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const container = assertContainerRef(requiredString(args, 'container', '容器名'));
+            const result = await runChecked(runner, inspectArgs(cfg.dockerPath, container), timeout, 'docker inspect');
+            return { container, info: parseInspectJson(result.stdout) };
+        },
+        timeoutMs: timeout,
+    };
+    const dockerExec = {
+        name: 'docker_exec',
+        description: '在容器内执行命令（默认走审批门）。command 为命令字符串（按空白拆分，支持引号）；返回退出码与 stdout（stderr 并入错误提示）。',
+        parameters: compileParameters({
+            container: { type: 'string', required: true, description: '容器名或 ID（必填）。' },
+            command: { type: 'string', required: true, description: '要执行的命令，如 ls -la 或 sh -c \'cat /etc/hosts\'（必填）。' },
+        }),
+        output: {
+            schema: execSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                return [{ type: 'text', text: '容器 ' + rec.container + ' 执行完成（退出码 ' + rec.exitCode + '）：\n' + rec.stdout }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const container = assertContainerRef(requiredString(args, 'container', '容器名'));
+            const command = splitCommand(requiredString(args, 'command', '命令'));
+            if (command.length === 0)
+                throw new Error('command 不能为空。');
+            const result = await runChecked(runner, execArgs(cfg.dockerPath, container, command), timeout, 'docker exec');
+            return { container, exitCode: result.exitCode, stdout: result.stdout };
+        },
+        gate(exec, next) {
+            return next();
+        },
+        timeoutMs: timeout,
+    };
+    const dockerManage = {
+        name: 'docker_manage',
+        description: '容器生命周期管理：start / stop / restart / rm（rm 强制删除）。注意 stop/restart/rm 会中断容器，谨慎使用。',
+        parameters: compileParameters({
+            container: { type: 'string', required: true, description: '容器名或 ID（必填）。' },
+            action: { type: 'string', required: true, description: '操作：start / stop / restart / rm（必填）。' },
+        }),
+        output: {
+            schema: manageSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                return [{ type: 'text', text: '容器 ' + rec.container + ' 已执行 ' + rec.action + '。' }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const container = assertContainerRef(requiredString(args, 'container', '容器名'));
+            const action = requiredString(args, 'action', '操作');
+            if (!['start', 'stop', 'restart', 'rm'].includes(action))
+                throw new Error('action 必须是 start / stop / restart / rm 之一（当前：' + action + '）。');
+            const result = await runChecked(runner, manageArgs(cfg.dockerPath, action, container), timeout, 'docker ' + action);
+            return { container, action, output: result.stdout.trim() };
+        },
+        timeoutMs: timeout,
+    };
+    return [dockerPs, dockerLogs, dockerInspect, dockerExec, dockerManage];
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@stardustlc/dsh-docker",
+  "version": "0.1.0",
+  "description": "DSH 容器管理插件：docker_ps/logs/inspect/exec/manage 五工具，走官方 subprocess 服务跑 docker CLI、argv 无 shell 注入、exec 审批门、零运行时依赖。",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "docker",
+    "container",
+    "devops"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-docker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-docker/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-docker#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}