前言¶
DSH 的插件模型会把本地能力拆成可安装、可调用的工具。对智能体流程来说，常见需求包括查询容器、查看日志、执行容器内命令、重启容器或清理容器。如果直接让 agent 拼 shell 命令，容易引入参数注入、误操作和审批缺失。
下面介绍 dsh-docker：一个 DSH 容器管理插件，走官方 subprocess 服务跑 Docker CLI，用 argv 数组避免 shell 注入，并对 docker_exec 保留默认审批门。
仓库为 STARDUSTLC666/dsh-docker，npm 包名为 @stardustlc/dsh-docker，许可证为 MIT。
这是什么¶
一句话定位：dsh-docker 是 DSH 的容器管理插件，提供六个 Docker 工具，覆盖容器列表、镜像列表、日志查看、容器详情、容器内执行和生命周期管理。
它主要解决“让 agent 安全地查看和操作本地 Docker 对象”的问题。
运行时要求如下：
- Node 版本：
>=22 - 本机装有 Docker，且
docker version能出结果 - 已验证于
@deepseek-ai/dsh@0.1.2-alpha.2（2026-08-31） - 零运行时依赖
如果 Docker 可执行文件不在 PATH 上，可以用 dockerPath 指定。
核心功能¶
dsh-docker 暴露六个工具：
| 工具 | 作用 | 说明 |
|---|---|---|
docker_ps |
列出容器 | 可过滤容器信息 |
docker_images |
列出本地镜像 | 可查看悬空镜像 |
docker_logs |
查看日志尾部 | 行数有钳制，可短时 follow |
docker_inspect |
查看容器详情 | 用于获取容器状态与详情 |
docker_exec |
在容器内执行命令 | 默认审批门，并有容器名校验 |
docker_manage |
容器生命周期管理 | 支持 start / stop / restart / rm |
所有 Docker CLI 调用都走官方 subprocess 服务，并使用 argv 数组传参，避免 shell 注入。
安装与启用¶
先确认本机 Docker 可用：
docker version
如果能输出结果，说明本机已有可用的 Docker CLI。
接着安装插件到 web profile：
dsh plugin --profile web add @stardustlc/dsh-docker
如果 docker 可执行文件不在 PATH 上，可以在插件配置中指定 dockerPath。例如：
dockerPath: <docker-executable>
这里的 <docker-executable> 应替换为当前环境中的 Docker CLI 路径。
卸载后需要重启 Web 服务。如需彻底清理，可再手动删除自己 profile 中 cordis.patch.yml 覆盖的插件行。
典型用法¶
下面是六个工具的基本调用示例：
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' }
docker_manage { container: web, action: restart }
几个关键点：
docker_exec默认启用审批门。- 在 headless 环境且没有审批通道时，
docker_exec会拒绝执行。 - 容器名校验只允许
[A-Za-z0-9][A-Za-z0-9_.:-]*。 - 单次操作超时被钳制在 5 秒到 10 分钟之间。
- follow 模式额外限制为 30 秒。
docker_logs的tail参数被限制在 1 到 2000 行之间。
适用场景与注意¶
这个插件适合本地已经安装 Docker、并且希望让 DSH 智能体流程直接查看容器状态的开发者或运维场景。
常见用法包括：
- 用
docker_ps快速确认哪些容器在运行。 - 用
docker_images检查本地镜像和悬空镜像。 - 用
docker_logs查看某个容器最近 200 行日志。 - 用
docker_inspect获取容器详情。 - 用
docker_manage执行restart或stop等生命周期操作。
需要注意边界：
- 插件会按当前 DSH 进程权限执行 Docker 命令，安装前应检查源码与许可证。
docker_exec会在容器内执行命令，默认需要审批。docker_manage的rm是破坏性操作，执行前需要确认目标容器。docker_exec在 headless 且无审批通道时会被拒绝，这是预期行为。
相关链接¶
- 社区目录页：https://www.skillhub.cn/plugins/STARDUSTLC666/dsh-docker
- GitHub：https://github.com/STARDUSTLC666/dsh-docker
