前言¶

在 DeepSeek Harness（DSH）中让智能体执行 GPU 任务时，常见的问题是：状态查询、选卡、命令执行、后台任务管理都要靠 shell 手工拼接。直接调用 nvidia-smi 或手动设置 CUDA_VISIBLE_DEVICES 也能工作，但多卡选择、后台作业和并发选卡逻辑会变得零散。

下面介绍 dsh-gpu。它是面向 DeepSeek Harness 的 GPU-aware execution layer：提供 gpu_status、gpu_exec、gpu_run_bg 三个工具，支持可选的 per-step GPU context injection，并自动处理 CUDA_VISIBLE_DEVICES 选卡。

这是什么¶

dsh-gpu 是 DeepSeek Harness 插件，定位为 GPU-aware execution layer for DeepSeek Harness。它把 GPU 状态查询、GPU 命令执行、GPU 后台作业封装到 DSH 工具层，许可证为 MIT。

仓库地址：

https://github.com/zytsyj/dsh-gpu

核心功能¶

gpu_status：一次查询所有 GPU 状态¶

gpu_status 用于一次查询所有设备，返回：

• memory used/total
• SM utilization
• temperature
• free/busy verdict

一个设备在以下任一条件满足时被视为 busy：

• memory used 达到或超过 80%
• utilization 达到或超过 50%

两个阈值均可配置。

gpu_exec：执行一次性 GPU 命令¶

gpu_exec 用于一次性命令。它会按当前选卡结果设置 CUDA_VISIBLE_DEVICES，并通过 DSH 挂载的 ctx.shell executor 执行命令。

它支持：

• 自动选择较空闲的卡
• 显式指定卡
• 为多 GPU 命令选择 count 张卡

gpu_run_bg：后台运行长时间 GPU 任务¶

gpu_run_bg 用于训练、推理服务、benchmark 等长时间任务。任务会作为 gpu job 注册到 ctx.jobs，并立即返回 job id。

之后可以：

• 用 job_output 读取输出
• 用 job_kill 停止任务

它需要 composition 中已经启用 jobs service：

@deepseek-ai/dsh-jobs
@deepseek-ai/dsh-tool-jobs

Per-step context：给 eligible steps 注入一行 GPU 快照¶

Per-step context 是可选能力，默认开启。它会为 eligible steps 注入一行 GPU snapshot，并且限速为每分钟一次 sample。

安装与启用¶

先确定要启用该插件的 DSH profile，再执行插件安装命令：

dsh plugin --profile <name> add dsh-gpu

这里的 <name> 是 profile 占位符，按当前 profile 名称替换。

加载顺序上，建议把 dsh-gpu 放在 execution-world 插件之后。例如，如果 DSH 通过 SSH provider 插件提供 shell seam，dsh-gpu 应放在该插件之后，确保它查询的是预期的 shell seam。

典型用法¶

下面是基于已核实能力整理的调用路径：

1. 先调用 gpu_status，查看当前 GPU 的 memory used/total、SM utilization、temperature 和 free/busy verdict。
2. 对一次性 GPU 命令调用 gpu_exec。插件会设置 CUDA_VISIBLE_DEVICES，并通过 ctx.shell executor 执行命令。
3. 对训练、推理服务、benchmark 等长任务调用 gpu_run_bg，拿到 job id 后，用 job_output 读取输出，用 job_kill 停止任务。
4. 如果需要每步看到 GPU 状态，保留默认的 per-step context，让它按每分钟一次 sample 的限速注入一行 GPU snapshot。

如果需要更强的确定性，可以在同一 step 内先读取 gpu_status，再显式 pin gpuIndex。

适用场景与注意¶

dsh-gpu 适合需要在 DSH 智能体中接入 GPU 执行逻辑的场景，例如：

• 查询 GPU 状态
• 执行一次性 GPU 命令
• 运行训练、推理服务、benchmark 等后台任务
• 在多卡环境中自动选择较空闲的卡

需要注意以下几点：

• nvidia-smi 会忽略 CUDA_VISIBLE_DEVICES，始终报告物理索引。gpu_exec 对 CUDA 程序的选卡仍按设计工作，但不要用 nvidia-smi 输出来验证 pinning。
• 选卡是 advisory，不是 reservation。两个并发 agent 仍可能选中同一张卡。需要独占判断时，应在同一 step 内从 gpu_status 读取并 pin gpuIndex。
• gpu_run_bg 依赖 jobs service。composition 中需要 @deepseek-ai/dsh-jobs 和 @deepseek-ai/dsh-tool-jobs。
• 在没有 NVIDIA GPU 的 host 上，gpu_status 会报告 clean no-gpu result，而不是失败。
• 插件会接入当前 DSH profile 的执行链路，并以当前 dsh 进程权限使用已挂载的 shell executor。安装前应检查源码和 MIT 许可证。

结尾¶

dsh-gpu 的价值在于把 GPU 状态查询、命令执行和后台作业收敛到 DSH 工具层，减少智能体手动查卡、拼环境变量、轮询后台任务的重复逻辑。

仓库地址：

https://github.com/zytsyj/dsh-gpu