前言¶

在 DeepSeek Harness（DSH）里接模型，常见做法是走云端 API 或本机推理。若你希望用自己选的开放权重、又要有独立 GPU 环境，可以在 Hugging Face 上搭一个 GPU Space，跑 OpenAI 兼容推理服务（例如 llama.cpp 的 llama-server）。难点在于：Space 按分钟计费，一直开着浪费；手动在网页上启停，又和 Harness 里的对话流脱节。

维护者 dev-bravelo 的 dsh-hf-spaces 把「你的 Space」接进 DSH：发消息时自动启动、界面里看进度和账单、空闲或到时限后暂停。插件当前为 alpha（0.1.0-alpha.9），尚未发布到 npm；README 写明 2026-10-31 已在真实私有 Space 上做过测试。

这是什么¶

dsh-hf-spaces 是 DSH 社区插件，分类为模型推理。它不托管模型、不代你建 Space，只驱动你已经配置好的 Hugging Face GPU Space：通过 Hugging Face API 启停虚拟机，把 Space 里的模型登记到 Harness 模型选择器，请求走 https://<subdomain>.hf.space 的 /v1 接口。

与「在 Harness 里填一个 OpenAI 兼容 base URL」相比，这个插件额外负责 Space 生命周期、启动进度、空闲/单次时长限制、以及侧边栏里的用量与启动记录。

端到端流程¶

 DeepSeek Harness（本机）                         Hugging Face（你的账号）
 ┌──────────────────────────────┐                 ┌─────────────────────────────┐
 │ 模型选择器里选 Space 下的模型   │                 │ GPU Space（虚拟机）          │
 │ 发消息 ──────────────────────┼── 是否在服务？ ──►│ 暂停 → 插件经 API 启动       │
 │ 会话头：「starting 42% · ~2 min」◄── 进度 ──────┤ 启动 → 拷贝并加载权重        │
 │ 回答流式返回 ◄─────────────────┼── 自有模型 ──────┤ 服务中 → OpenAI 兼容 API     │
 │ 空闲 30 分钟 / 单次 60 分钟 ───┼── 暂停 ─────────►│ 暂停 → 停止计费              │
 └──────────────────────────────┘                 └─────────────────────────────┘

下面按 README 归纳的步骤理解即可：先在 Harness 里选 Space 对应模型；若 Space 已暂停，插件会短提示并启动，进度显示在会话头；就绪后会自动续上你刚发的那条消息。关闭 Harness 后插件无法代你暂停，需在 Space 设置里配置 sleep time 作为兜底。

核心功能¶

以下能力均来自仓库 README，且与 package.json 中的 0.1.0-alpha.9 一致。

模型与路由¶

• 每个配置的 Space 在模型选择器里像一个 provider，展示你声明的模型名、上下文长度、输出上限和 reasoning 档位。
• 插件自带模型权重；Space 上跑什么开放权重由你在 Hugging Face 侧准备。

按需启停与计费感知¶

• 按需启动：向已暂停的 Space 发消息会触发启动；就绪后自动回答等待中的消息。README 举例：27B 模型在 A100 上首次冷启动约 3 分钟。
• 自动暂停：默认空闲 30 分钟无请求、或每次启动满 60 分钟（可配置、可延长）；也可在界面点 Stop 或发送 /space off。
• 用量展示：侧边栏「Hugging Face Spaces」标签页显示当日/当月 Space 账单、近期启动（时长、费用、结束原因）、最后一次启动的 run-log 尾部。账户余额 Hugging Face API 不提供，插件只展示已计费金额。

界面与手动控制¶

• 会话头指示器：状态、启动百分比与剩余时间，或服务中的停止时间；可打开侧边栏。
• 插件设置页：凭证、Space、manifest、模型、effort 档位等检查项及生效值来源。
• 斜杠命令：/space status | on | off | +N，以及 Start/Stop 按钮；这些操作不会向模型发对话内容。

架构要点¶

Host 跑在 Harness 后端（Node.js）：模型路由、Space 监管、Hugging Face API 客户端、本地 HTTP 路由。Client 跑在 Web UI：指示器、侧边栏、通知与设置页。对话与 token 仅发往 Hugging Face 与你的 Space 域名，README 说明插件不做遥测。

安装与启用¶

插件以 bundle 形式安装，没有 README 里写的 dsh plugin add github:... 一类命令。需要先拿到 dsh-hf-spaces-<version>.tgz（从 GitHub Releases 下载，或在源码目录用 Node.js 22+ 执行 npm pack），再在 Harness 会话里通过插件管理器 install_bundle 安装该文件的绝对路径。

环境要求（README Requirements + package.json）：

• DeepSeek Harness Desktop 0.2.x，从 0.2.1-rc.3 起；engines.dsh 为 >=0.2.1-rc.3 <0.3.0-0。
• Node.js >= 22（仅当你从源码打包时需要）。
• Hugging Face 账号、已能对外提供 OpenAI 兼容 API 的 GPU Space，以及存入 Harness 凭证库的 token。

1、安装 bundle

在 Harness 里让 agent 使用 plugin_manager → install_bundle，传入 .tgz 的绝对路径。安装后应看到 dsh-hf-spaces 已启用。若显示 incompatible-version，说明当前 Harness 不在支持范围内，需对照 Compatibility 升级 Harness 或等待新版插件。

2、配置 HF_TOKEN（用户自行完成，勿在聊天里粘贴 token）

在 https://huggingface.co/settings/tokens 创建 token，权限见 README Credentials 表：推理至少需要 Space 读权限；启停需要写权限；可选单独 token 读账单。

写入 Harness 凭证库，默认名 HF_TOKEN。目录为 ~/.dsh，或环境变量 DSH_HOME 指向的路径。示例（~/.dsh/.credentials.yaml）：

version: 1
refs:
  HF_TOKEN: <your token>

也可在启动 Harness 前设置环境变量 HF_TOKEN，或写入 ~/.dsh/.env。

3、在 profile 的 patch 里登记 Space

编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml，在 YAML 列表中增加：

- id: hf-spaces
  name: dsh-hf-spaces
  config:
    spaces:
      - id: your-user/your-llm-space
        models:
          - id: your-model-id
            name: My model 27B
            reasoning: { "off": none, low: low, medium: medium, high: high }

id 须与 Space 内 GET /v1/models 列出的 id 一致。完整字段见仓库 examples/config.example.yml；若 Space 发布 dsh-hf-spaces.json manifest，可省略部分 models 声明。

4、重启 Harness，打开 Plugins → dsh-hf-spaces

各项检查应为 ok；「Models served」与「Effort levels」在首次启动前可能显示 later。若有 fix，按提示修改后再继续。

卸载时：从 patch 删除 hf-spaces 条目，并用插件管理器卸载 bundle；Space 本身仍在 Hugging Face 上，需自行在控制台暂停。

典型用法¶

经过上面的步骤后，用法与选其他模型类似：

1. 在模型选择器里选中你在配置里声明的 Space 模型。
2. 发送消息。Space 若处于暂停，会话头会显示启动进度；模型就绪后自动回答。
3. 用完后点会话头的 Stop，或发送 /space off，避免 GPU 空转计费。

需要查看状态时，打开侧边栏「Hugging Face Spaces」，或发送 /space status。延长单次运行上限可用 /space +N 或界面上的对应操作（README 在 time limit 通知里说明）。

适用场景与注意¶

适合谁

• 已在 Hugging Face 上维护 GPU Docker Space，并跑通 OpenAI 兼容推理（README 测试记录含 llama.cpp llama-server + 27B GGUF + A100）。
• 希望在 DSH 里把该 Space 当作普通模型源，同时由插件管理启停和用量展示，而不是长期开着 Space。

你需要先在 Hugging Face 完成的事

插件不会创建 Space、选 GPU 型号、安装推理引擎或上传权重。README 用表格区分：Space、硬件、推理引擎、权重路径、chat template、Space sleep time 均由你在 Hub 上配置；插件负责选择器登记、API 启停、进度与对话转发。

责任与合规

• 插件不提供内容过滤；你选用什么权重、什么 system prompt，由你负责。README 专设 Responsible use，并提醒开放权重许可与 Hugging Face 条款各自约束。
• GPU Space 与 PRO 计划、按分钟 GPU 计费、权重存储等要求见 README Requirements；定价以 Hugging Face 官方页面为准。

安全与权限

• 插件在 DSH 进程权限下运行，可访问你配置的凭证并调用 Hugging Face API。安装前应阅读仓库源码与 MIT 许可证；token 只应写入凭证库或环境变量，不应出现在 patch 配置或日志中。
• 私有 Space 仅持有 token 的调用方可访问；Harness 关闭后请依赖 Space 自带 sleep，以免虚拟机持续计费。

生态说明

DSH 采用「一切皆插件」的扩展方式；SkillHub 目录页是社区收录站点，与 DeepSeek / 幻方无官方从属关系，并非官方应用商店。

参考链接¶

• 社区目录：https://www.skillhub.cn/plugins/dev-bravelo/dsh-hf-spaces
• 源码与文档：https://github.com/dev-bravelo/dsh-hf-spaces
• 当前版本：0.1.0-alpha.9（alpha，未发 npm；Roadmap 中 Release 1.0 为下一步）

若你已经在 Hugging Face 上跑通自有权重推理，又希望把 GPU 账单压在「真正对话的那几段分钟」里，可以按 README 的安装链把 dsh-hf-spaces 接进 profile，从模型选择器开始试一轮启停与 /space 命令。