前言¶

DeepSeek Harness（DSH）的插件化设计让智能体可以按需加载工具。但在涉及 GPU 的场景里，常见的做法是让外部脚本在本地执行，再把结果丢回 DSH。这样会引入进程管理、日志留存、资源监控等额外负担。dsh-cuda 插件把 GPU 调度、任务提交、日志与显存统计直接集成到 DSH 内部，让智能体可以像调用普通工具一样提交 Python 任务，并拿到设备状态、前台/后台运行状态与峰值显存等事实。

插件定位¶

• 名称：dsh-cuda
• 维护者：Void-LifeStream
• 分类：模型推理
• 核心价值：在 DSH 里直接运行本地 GPU 的 Python 任务，提供设备状态、前台/后台作业、持久化日志与峰值显存统计。

核心功能¶

插件提供三个工具和一个按需加载的技能：

• cuda_status：查看设备内存、利用率、GPU 进程列表、机器上所有支持 CUDA 的 Python 解释器，以及最近的任务。
• cuda_run：提交 Python 源代码（code=）或 .py 脚本（script=，配合 args=），支持前台或后台运行（background=true）。
• cuda_job：通过任务 ID、前缀或 latest 跟踪单个任务：查看日志、等待完成、终止或查看详情。
• skill cuda-compute：加载后提供本地 GPU 使用指南、代码示例与常见坑点，由模型按需读取。

每次运行会在 ~/.dsh/gpu-runs/<job-id>/ 下生成一个目录，包含：

• script.py：实际执行的脚本副本
• _runner.py：记录资源事实的包装脚本
• stdout.log：完整 stdout
• stderr.log：完整 stderr
• job.json：持久化记录，含 pid、cwd、argv、时间戳与状态
• result.json：由包装脚本写入，包含 ok、exit_code、elapsed_s 与 peak_alloc_MB（通过 torch.cuda.max_memory_allocated() 测量，非估算）

模型可以通过环境变量 DSH_CUDA_JOB_DIR 读取该目录，并在其中写入自定义产物，这些产物会自动上报给 DSH。

安装与启用¶

插件位于一个工作区目录中，通过 DSH 的插件管理器安装，而非手动编辑配置：

plugin_manager action: install_bundle target: <绝对路径到此目录>

安装或修改技能后需重启 DSH，工具才会生效。安装器的 applied 结果表示配置已写入且入口导入正常，并不代表工具在运行时立即可见。

配置与解释器¶

配置项的优先级为：显式插件配置 → 环境变量 → ~/.dsh/cuda.json → 内置发现。

常用环境变量：

~/.dsh/cuda.json 用于配置特定机器的解释器（嵌入式 Python、conda 环境等）：

{
  "pythonPath": "C:\\path\\to\\python.exe",
  "pythonCandidates": ["C:\\path\\to\\python.exe"],
  "runsDir": "D:\\gpu-runs"
}

格式错误会被忽略，不会导致启动失败。

解释器自动发现流程：

• 若未配置，则扫描 PATH 上的 python/python3 以及若干常见安装位置
• 优先选择带 CUDA 的 torch 的解释器
• 每个候选的解释器能力会通过 cuda_status 报告，包括 torch 版本、CUDA 可用性、设备型号与 bf16 支持
• 探测结果缓存一小时

运行要求¶

• DeepSeek Harness，Node 22+
• 任意支持 CUDA 的 NVIDIA GPU（模型与内存大小不影响插件，由运行时报告）
• Python 环境，安装有 torch（含 CUDA 版本）
• 驱动与 torch 的 CUDA 版本兼容：若 torch.cuda.is_available() 为 False，通常是驱动版本过低或使用了 CPU-only wheel；cuda_status 会在运行时同时显示驱动与解释器的 CUDA 可用性，便于排查

对于自定义内核，推荐使用 triton（若已安装）。numba.cuda 需要安装 CUDA Toolkit 并提供 libNVVM，否则会报 NvvmSupportError: libNVVM cannot be found。

设计要点¶

• 前台任务超过超时预算会被提升为后台任务，而非直接终止，避免因短暂等待导致任务失败。
• 后台任务是独立进程，可在 DSH 重启后继续运行，适合长时间计算。
• 后台任务的结果由其 result.json 决定完成状态，无需父进程记录。
• 技能通过借用 provider 注册，每次加载时重新读取文件，无需重启即可更新技能内容。
• 引擎不依赖 DSH 内部 API，可直接由 Node 运行测试。

测试与已知限制¶

测试套件包含 110 项检查，全部使用纯 Node 运行，不依赖 DSH 重启或测试框架：

node test/selftest.mjs    # 36 项：引擎，真实 GPU
node test/harness.mjs     # 46 项：插件，模拟 context
node test/lossless.mjs    # 28 项：工具值无损 JSON 检查

已知限制：

• Windows/WDDM：nvidia-smi 无法按进程显示显存，且图形进程会混入 GPU 进程列表，插件会如实报告。
• 并发：cuda_run 未标记为并发安全，DSH 会阻止同一时间运行多个任务；大量并发任务也会竞争显存。
• 无 CUDA Toolkit 集成：不调用 nvcc，保持零安装门槛。

适用场景与注意¶

适合在 DSH 中需要本地 GPU 计算的场景，例如科学计算、数值实验、深度学习推理与微调等。插件以当前 DSH 进程的权限运行，安装前建议查看源码与许可证。

小结¶

dsh-cuda 把 GPU 任务提交、作业跟踪、日志与显存统计集成到 DSH 工具链中，让智能体可以用统一的方式调度本地计算资源。更多细节与源码参见：

• 目录页
• GitHub 仓库