DevViking-Persike/dsh-docker

dsh-docker

用于 DeepSeek Harness 的 Docker 工具：智能体可以列出容器、读取日志、检查镜像，并驱动 Compose 项目，全部通过机器上已有的 Docker CLI 完成。

安装时不需要守护进程。每次调用时都会探测可达性，因此没有 Docker 的机器只会报告引擎不可达，而不会加载失败。

安装

dsh plugin --profile web add github:DevViking-Persike/dsh-docker

之后重启 dsh。只读工具会立即生效；参见 Compose 以启用生命周期工具。

工具

| 工具 | 作用 |
|---|---|
| docker_ps | 列出容器。默认仅列出运行中的容器；all: true 会包含已停止的容器，project 可筛选到某个 Compose 项目。 |
| docker_images | 列出本地镜像及其标签和大小。 |
| docker_logs | 读取容器最近的输出。保留最新的文本，并在较早条目被丢弃时予以报告。 |
| docker_compose_up | 以分离模式启动一个 Compose 项目，并等待其容器。需选择启用。 |
| docker_compose_down | 停止并移除某个 Compose 项目的容器。需选择启用。 |

Compose 生命周期

启动和停止容器会改变机器状态，因此这两个工具默认关闭。需要它们的部署应设置 compose: true：

- id: dsh-docker
name: 'dsh-docker'
config:
compose: true

配置

每个字段都是可选的。

| 字段 | 默认值 | 含义 |
|---|---|---|
| cli | docker | 可执行文件名或绝对路径。 |
| projectRoot | 进程 cwd | 调用的工作目录，也是相对 compose 路径解析所依据的根目录。 |
| compose | false | 注册 Compose 生命周期工具。 |
| inspectTimeoutMs | 30000 | 一次读取（ps、images、logs）的预算。 |
| composeTimeoutMs | 600000 | 一次 Compose 调用的预算；拉取镜像和等待健康检查通常比一次读取长一个数量级。 |
| maxOutputBytes | 2000000 | 一次调用所收集输出的上限。 |
| maxLogChars | 40000 | docker_logs 输出字符数的上限。 |
| defaultLogTail | 200 | 当请求未指定 tail 时读取的末尾行数。 |
| graceMs | 5000 | 交给子进程接缝的终止宽限期。 |

模型体验

只读工具会为模型上下文中的每个容器或镜像放入一行，而不是原始 CLI 输出：状态、状态描述、镜像、Compose 项目/服务以及已发布端口。空结果会明确说明，而不是返回空白文本，这样模型就不会把沉默解读为失败。

docker_logs 在必须截断时会保留最新的字符，因为日志的尾部才能解释刚刚发生的失败，并且它会标记截断位置，让模型知道自己看到的不是整个文件。
Compose 结果以已确定的项目状态开头，并将后端自身的输出放在其后——模型据此推断哪些容器处于运行状态，仅在诊断时才读取 CLI 文本。

安全性

- 参数以固定的 argv 形式传递给可执行文件，绝不经过 shell 解释，因此容器名称无法变成标志或 shell 片段。
- -- 在每个容器操作数之前终止标志解析，因此字面名为 --follow 的容器仍会作为操作数处理。
- docker_compose_down 绝不转发服务过滤器：down 会移除整个项目，而带过滤器的调用会显得比实际范围更窄。
- Compose 生命周期调用被标记为并发不安全，因为对同一项目的两次生命周期调用会在引擎内部产生竞态。

已知限制与推迟的工作

- 镜像大小从 CLI 的显示字符串（1.09GB）解析而来，因为 docker images --format json 不提供机器可读的大小。无法解析的值会读作 0，而不是让列表操作失败。
- 引擎可达性在每次调用时探测，而非缓存，因此已停止的守护进程会被立即发现，代价是每次工具调用多一次调用。
- 每次生命周期调用后，Compose 项目状态会通过第二次 docker ps 读回，因为 CLI 自身的输出不会报告已确定的容器。
- 没有 docker exec，没有镜像构建，也没有注册表操作。每一项都会显著扩大影响范围，且目前都没有使用者。

许可证

MIT——参见 LICENSE 和 NOTICE.md，以了解对本插件所遵循其约定的 DeepSeek Harness 项目的署名。