前言¶

在 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 命令。