前言¶
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
