前言¶
在 DeepSeek Harness（DSH）里做模型推理相关开发时，往往需要对接 GPU 集群：看节点与显卡余量、提交部署、跟实例状态、拉日志、做一次真实推理验收、再查用量。若只靠 curl 或手写脚本，上下文要在人和模型之间来回搬，密钥也容易混进对话记录。
dsh-plugin-gpustack 把 GPUStack v2 的 /docs 运维接口封装成 DSH 的 Agent 工具。安装并配置集群地址与 API Key 后，模型可以盘点集群、部署模型、查看实例日志、等待就绪、跑推理验收、查用量；其余 200+ 端点可通过通用请求工具覆盖。
这是什么¶
- 名称：
dsh-plugin-gpustack（npm 包名相同） - 维护者：zh-Littlebird（Hu Zhang）
- 分类：模型推理（社区目录归类）
- 版本：1.0.0（MIT 许可证）
- 定位：GPUStack v2 集群工具——模型部署与生命周期、Worker/GPU 盘点、实例日志、推理验收、用量统计与通用 API 调用；API Key 设计为留在模型会话之外。
插件以 dsh.bundle.patch 声明的组合包形式安装，依赖 DSH >=0.2.2-rc.1 <0.3.0、Node >=22.19.0。
核心功能¶
工具面¶
README 中列出的工具与用途如下（节选）：
| 工具 | 用途 |
|---|---|
gpustack_config |
查看/设置集群地址（不接收 Key） |
gpustack_test |
连通性与凭据自检（healthz、version、用户身份、推理模型数等） |
gpustack_inventory |
集群、Worker、GPU 设备盘点 |
gpustack_models |
模型列表或单个模型及实例详情 |
gpustack_deploy_model |
部署模型（POST /v2/models） |
gpustack_update_model |
修改副本、参数、env 等规格 |
gpustack_model_action |
重启、回滚、删除（删除需 confirm=true） |
gpustack_logs |
模型实例日志 |
gpustack_wait_model |
轮询直到 running/error 或超时 |
gpustack_chat |
OpenAI 兼容推理验收（真实 /v1/chat/completions） |
gpustack_usage |
用量汇总与明细 |
gpustack_request |
任意端点的通用通道 |
注意：gpustack_models 的 state 参数对应列表接口的就绪过滤（ready/not_ready/stopped）；若按 pending|partial|running|error 筛选，应使用 modelState。
安全与权限¶
- API Key 仅存在本机加密文件（AES-256-GCM），不进入工具参数、工具结果或会话记录。
- 写操作受
allowWrites总开关控制；delete需显式confirm=true。 - 每次调用写一行审计日志（不含请求体与查询串）。
- 设置页可按类别单独关闭部署、修改规格、重启回滚、删除、通用写、推理等权限。
安装与启用¶
插件装进当前 profile 即可。官方 README 给出的命令如下。
# 从 npm 安装
dsh plugin --profile desktop add dsh-plugin-gpustack
# 或先从源码克隆，再按目录安装
git clone https://github.com/zh-Littlebird/dsh-plugin-gpustack
dsh plugin --profile desktop add ./dsh-plugin-gpustack
Agent 场景可调用 plugin_manager 的 install_bundle，target 传包名 dsh-plugin-gpustack 或本地目录绝对路径。
安装后 gpustack_* 工具在下一个会话（或工具表刷新后）可用；设置页与插件行配置页重新加载页面后生效，重启 Harness 一定生效。
配置集群与凭据¶
图形界面（推荐）¶
打开「设置 → GPUStack」，或在「插件」页打开 dsh-plugin-gpustack 的配置页：
- 填写集群地址（可粘贴
/docs链接，会自动去掉后缀）与 API Key，点「保存」后立即生效。 - 使用「测试连接」分项查看 healthz/version、管理接口身份、推理接口模型数。
- 在「操作权限」中按类别开关写操作；可调整超时与组织 ID。
命令行等价操作¶
模型不参与、也看不到密钥输入：
cd 'dsh-plugin-gpustack'
node scripts/dsh-gpustack.mjs setup --base-url http://192.0.2.10:31901
node scripts/dsh-gpustack.mjs set --api-key # 隐藏输入，形如 gpustack_xxx
node scripts/dsh-gpustack.mjs status
node scripts/dsh-gpustack.mjs test # 探活 /healthz、/version、/v2/users/me
配置优先级：环境变量 > site.json（设置页/CLI 写入）> 插件配置（cordis.patch.yml 的部署默认值）。常用环境变量包括 GPUSTACK_BASE_URL、GPUSTACK_API_KEY、DSH_GPUSTACK_DATA_DIR（默认 $DSH_HOME/gpustack）。
非机密与审计数据落在 site.json、credentials.json + master.key、audit.log 等本地文件中，细节见 README 表格。
典型用法¶
部署并验收¶
gpustack_inventory— 确认 worker ready、卡型与余量。gpustack_deploy_model— 提交name/source/backend/replicas/...。gpustack_wait_model— 等到state=running（不要仅凭 200 认为成功）。gpustack_chat— 用模型名跑一次真实推理。gpustack_models modelId=<id>— 核对实例落在预期 worker/GPU。
排障¶
gpustack_models modelId=<id>— 查看state、state_message、实例状态。gpustack_logs modelId=<id>— 镜像/模型路径/OOM 等；重启过可加previous=true。- 修复后
gpustack_model_action action=restart，再gpustack_wait_model。
改配置¶
gpustack_update_model 只更新规格；改 backendParameters/env/镜像等时必须 restart=true（或随后单独 restart），否则进程仍跑旧参数。restart 整组重建且非幂等，restarting_since 未清空前再次调用可能返回 409。
适用场景与注意¶
适合谁：已在 GPUStack v2 上跑模型、又在 DSH 里用 Agent 做部署与运维对话的开发者；希望 Key 与写操作有明确边界和审计的团队。
运行边界：插件以当前 DSH 进程的权限访问本机配置与集群 API；安装前应自行审阅 源码 与 MIT 许可证。一个插件实例绑定一个集群（baseUrl）；多集群需切换地址或多份配置。
已知限制（摘自 README）：模型 zip 导入导出、部分看板端点等未做 typed 工具，可用 gpustack_request；压测类接口使用前需确认对线上流量的影响。
DSH 生态理念是「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-plugin-gpustack 把 GPUStack v2 的日常运维收成一组可编排的 Agent 工具，并在密钥、写权限与审计上做了分层约束。需要安装说明、配置字段与完整工具表时，以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/zh-Littlebird/dsh-plugin-gpustack
- GitHub：https://github.com/zh-Littlebird/dsh-plugin-gpustack
