@stardustlc/dsh-docker 0.1.1 → 0.2.0

package/README.en.md

@@ -4,7 +4,7 @@
 
 > **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**.
+DSH (DeepSeek Harness) container-management plugin: runs the docker CLI through the official subprocess service with shell-free argv arrays, six tools including image listing, 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)
 
@@ -25,6 +25,7 @@ Requires Docker installed locally (`docker version` should work); use `dockerPat
   name: '@stardustlc/dsh-docker'
   config:
     # dockerPath: C:\Program Files\Docker\Docker\resources\bin\docker.exe
+    dockerPath: docker     # optional; or use the DSH_DOCKER_PATH env var
     timeoutMs: 60000       # per-operation timeout (default 60s, 5s - 10min)
     # execApproval: false  # disable the docker_exec approval gate (default true)
 ```
@@ -34,6 +35,7 @@ Requires Docker installed locally (`docker version` should work); use `dockerPat
 | Tool | Purpose | Safety |
 | :-- | :-- | :-- |
 | `docker_ps` | List containers (status/image/state, filterable) | — |
+| `docker_images` | List local images (repository/tag/size/created, dangling-only filter) | — |
 | `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 |
@@ -44,6 +46,7 @@ Requires Docker installed locally (`docker version` should work); use `dockerPat
 ```text
 docker_ps {}
 docker_ps { all: true, name: web }
+docker_images { dangling: true }
 docker_logs { container: web, tail: 200 }
 docker_inspect { container: web }
 docker_exec { container: web, command: 'df -h' }

package/README.md

@@ -2,7 +2,7 @@
 
 # dsh-docker
 
-> **你的 agent 会管容器了**：五个工具覆盖容器列表、日志、详情、容器内执行与生命周期管理。
+> **你的 agent 会管容器了**：六个工具覆盖容器/镜像列表、日志、详情、容器内执行与生命周期管理。
 
 DSH（DeepSeek Harness）容器管理插件：走官方 subprocess 服务跑 docker CLI，argv 数组无 shell 注入，`docker_exec` 默认审批门，**零运行时依赖**。
 
@@ -25,6 +25,7 @@ dsh plugin --profile web add @stardustlc/dsh-docker
   name: '@stardustlc/dsh-docker'
   config:
     # dockerPath: C:\Program Files\Docker\Docker\resources\bin\docker.exe
+    dockerPath: docker     # 可选；也可用环境变量 DSH_DOCKER_PATH
     timeoutMs: 60000       # 单次操作超时（默认 60 秒，5 秒 - 10 分钟）
     # execApproval: false  # 关闭 docker_exec 审批门（默认 true）
 ```
@@ -34,6 +35,7 @@ dsh plugin --profile web add @stardustlc/dsh-docker
 | 工具 | 作用 | 安全 |
 | :-- | :-- | :-- |
 | `docker_ps` | 列出容器（状态/镜像/运行态，可过滤）| — |
+| `docker_images` | 列出本地镜像（仓库/标签/大小/创建时间，可只看悬空镜像）| — |
 | `docker_logs` | 查看日志尾部（行数钳制，可短时 follow）| — |
 | `docker_inspect` | 容器详情（镜像/状态/端口）| — |
 | `docker_exec` | 容器内执行命令 | 审批门 + 容器名白名单校验 |
@@ -44,6 +46,7 @@ dsh plugin --profile web add @stardustlc/dsh-docker
 ```text
 docker_ps {}
 docker_ps { all: true, name: web }
+docker_images { dangling: true }
 docker_logs { container: web, tail: 200 }
 docker_inspect { container: web }
 docker_exec { container: web, command: 'df -h' }

package/lib/args.d.ts

@@ -7,6 +7,8 @@
 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[];
+/** 列出镜像（JSON 格式；dangling=true 只列悬空镜像）。 */
+export declare function imagesArgs(docker: string, dangling?: boolean): string[];
 /** 查看详情（docker inspect 原生 JSON）。 */
 export declare function inspectArgs(docker: string, container: string): string[];
 /** 容器内执行命令。 */

package/lib/args.js

@@ -14,6 +14,13 @@ export function psArgs(docker, all, filter) {
 export function logsArgs(docker, container, tail, follow) {
     return [docker, 'logs', follow ? '--follow' : '', '--tail', String(tail), container].filter((item) => item !== '');
 }
+/** 列出镜像（JSON 格式；dangling=true 只列悬空镜像）。 */
+export function imagesArgs(docker, dangling = false) {
+    const argv = [docker, 'images', '--format', 'json'];
+    if (dangling)
+        argv.push('--filter', 'dangling=true');
+    return argv;
+}
 /** 查看详情（docker inspect 原生 JSON）。 */
 export function inspectArgs(docker, container) {
     return [docker, 'inspect', container];

package/lib/config.d.ts

@@ -20,6 +20,6 @@ export interface ResolvedDockerConfig {
 /**
  * 解析并校验配置。
  */
-export declare function resolveConfig(config: DockerConfig | undefined | null): ResolvedDockerConfig;
+export declare function resolveConfig(config: DockerConfig | undefined | null, env?: NodeJS.ProcessEnv): ResolvedDockerConfig;
 /** 校验容器名/ID，防参数注入（只允许字母数字与 _-.:/ 之外的拒绝）。 */
 export declare function assertContainerRef(value: string): string;

package/lib/config.js

@@ -6,9 +6,9 @@
 /**
  * 解析并校验配置。
  */
-export function resolveConfig(config) {
+export function resolveConfig(config, env = process.env) {
     const cfg = config ?? {};
-    const dockerPath = typeof cfg.dockerPath === 'string' && cfg.dockerPath.trim() !== '' ? cfg.dockerPath.trim() : 'docker';
+    const dockerPath = typeof cfg.dockerPath === 'string' && cfg.dockerPath.trim() !== '' ? cfg.dockerPath.trim() : (env.DSH_DOCKER_PATH?.trim() || 'docker');
     let timeoutMs = 60000;
     if (cfg.timeoutMs !== undefined) {
         if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0)

package/lib/exec.js

@@ -25,14 +25,14 @@ export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
                     graceMs,
                     signal: controller.signal,
                 });
+                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 };
             }
             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

@@ -1,8 +1,8 @@
 /**
  * dsh-docker —— 容器管理工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册五个面向模型的工具（docker_ps / docker_logs /
- * docker_inspect / docker_exec / docker_manage）。进程执行走 DSH 官方 subprocess 服务
+ * 插件导出 apply(ctx, config)：注册六个面向模型的工具（docker_ps / docker_logs /
+ * docker_images / docker_inspect / docker_exec / docker_manage）。进程执行走 DSH 官方 subprocess 服务
  * （argv 数组、无 shell），docker_exec 默认走宿主审批门。零运行时依赖。
  *
  * @module dsh-docker
@@ -36,7 +36,7 @@ export interface DockerPluginContext {
     on?(event: string, listener: () => void): () => void;
 }
 /**
- * 插件入口：解析配置、封装执行器、注册五工具；docker_exec 注入审批门。
+ * 插件入口：解析配置、封装执行器、注册六工具；docker_exec 注入审批门。
  */
 export declare function apply(ctx: DockerPluginContext, config?: DockerConfig | null): void;
 export * from './args.js';

package/lib/index.js

@@ -1,8 +1,8 @@
 /**
  * dsh-docker —— 容器管理工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册五个面向模型的工具（docker_ps / docker_logs /
- * docker_inspect / docker_exec / docker_manage）。进程执行走 DSH 官方 subprocess 服务
+ * 插件导出 apply(ctx, config)：注册六个面向模型的工具（docker_ps / docker_logs /
+ * docker_images / docker_inspect / docker_exec / docker_manage）。进程执行走 DSH 官方 subprocess 服务
  * （argv 数组、无 shell），docker_exec 默认走宿主审批门。零运行时依赖。
  *
  * @module dsh-docker
@@ -13,7 +13,7 @@ import { buildDockerTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools。 */
 export const inject = ['subprocess', 'tools'];
 /**
- * 插件入口：解析配置、封装执行器、注册五工具；docker_exec 注入审批门。
+ * 插件入口：解析配置、封装执行器、注册六工具；docker_exec 注入审批门。
  */
 export function apply(ctx, config) {
     let cfg;

package/lib/parse.d.ts

@@ -13,5 +13,15 @@ export interface ContainerInfo {
 }
 /** docker ps --format json 的每一行解析。 */
 export declare function parsePsJson(text: string): ContainerInfo[];
+/** 镜像摘要。 */
+export interface ImageInfo {
+    id: string;
+    repository: string;
+    tag: string;
+    size: string;
+    createdSince: string;
+}
+/** docker images --format json 的每一行解析。 */
+export declare function parseImagesJson(text: string): ImageInfo[];
 /** docker inspect 的 JSON 摘要。 */
 export declare function parseInspectJson(text: string): Record<string, unknown>;

package/lib/parse.js

@@ -24,6 +24,27 @@ export function parsePsJson(text) {
     }
     return rows;
 }
+/** docker images --format json 的每一行解析。 */
+export function parseImagesJson(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 ?? ''),
+                repository: typeof raw.Repository === 'string' ? raw.Repository : String(raw.Repository ?? ''),
+                tag: typeof raw.Tag === 'string' ? raw.Tag : String(raw.Tag ?? ''),
+                size: typeof raw.Size === 'string' ? raw.Size : String(raw.Size ?? ''),
+                createdSince: typeof raw.CreatedSince === 'string' ? raw.CreatedSince : String(raw.CreatedSince ?? ''),
+            });
+        }
+        catch { /* 跳过坏行 */ }
+    }
+    return rows;
+}
 /** docker inspect 的 JSON 摘要。 */
 export function parseInspectJson(text) {
     const raw = JSON.parse(text);

package/lib/tools.js

@@ -3,9 +3,9 @@
  *
  * @module dsh-docker/tools
  */
-import { inspectArgs, logsArgs, manageArgs, execArgs, psArgs, splitCommand } from './args.js';
+import { imagesArgs, inspectArgs, logsArgs, manageArgs, execArgs, psArgs, splitCommand } from './args.js';
 import { assertContainerRef } from './config.js';
-import { parseInspectJson, parsePsJson } from './parse.js';
+import { parseImagesJson, parseInspectJson, parsePsJson } from './parse.js';
 function compileParameters(spec) {
     const properties = {};
     const required = [];
@@ -67,6 +67,11 @@ const execSchema = {
     properties: { container: { type: 'string' }, exitCode: { type: 'integer' }, stdout: { type: 'string' } },
     additionalProperties: true,
 };
+const imagesSchema = {
+    type: 'object',
+    properties: { count: { type: 'integer' }, dangling: { type: 'boolean' }, images: { type: 'array', items: { type: 'object', additionalProperties: true } } },
+    additionalProperties: true,
+};
 const manageSchema = {
     type: 'object',
     properties: { container: { type: 'string' }, action: { type: 'string' }, output: { type: 'string' } },
@@ -131,6 +136,34 @@ export function buildDockerTools(config, runner) {
         },
         timeoutMs: timeout,
     };
+    const dockerImages = {
+        name: 'docker_images',
+        description: '列出本地 Docker 镜像（仓库/标签/大小/创建时间）。dangling=true 时只列未被任何标签引用的悬空镜像。',
+        parameters: compileParameters({
+            dangling: { type: 'boolean', description: '是否只列出悬空镜像（默认 false）。' },
+        }),
+        output: {
+            schema: imagesSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const images = Array.isArray(rec.images) ? rec.images : [];
+                const lines = ['共 ' + images.length + ' 个镜像：'];
+                for (const item of images) {
+                    const image = asRecord(item);
+                    lines.push('- ' + image.repository + ':' + image.tag + '（' + image.size + '，' + image.createdSince + '）');
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const dangling = args.dangling === true;
+            const result = await runChecked(runner, imagesArgs(cfg.dockerPath, dangling), timeout, 'docker images');
+            const images = parseImagesJson(result.stdout);
+            return { count: images.length, dangling, images };
+        },
+        timeoutMs: timeout,
+    };
     const dockerInspect = {
         name: 'docker_inspect',
         description: '查看容器详情：镜像、运行状态、启动时间、端口映射。',
@@ -206,5 +239,5 @@ export function buildDockerTools(config, runner) {
         },
         timeoutMs: timeout,
     };
-    return [dockerPs, dockerLogs, dockerInspect, dockerExec, dockerManage];
+    return [dockerPs, dockerLogs, dockerImages, dockerInspect, dockerExec, dockerManage];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stardustlc/dsh-docker",
-  "version": "0.1.1",
-  "description": "DSH 容器管理插件：docker_ps/logs/inspect/exec/manage 五工具，走官方 subprocess 服务跑 docker CLI、argv 无 shell 注入、exec 审批门、零运行时依赖。",
+  "version": "0.2.0",
+  "description": "DSH 容器管理插件：docker_ps/logs/images/inspect/exec/manage 六工具，走官方 subprocess 服务跑 docker CLI、argv 无 shell 注入、exec 审批门、零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",