前言¶
在 DeepSeek Harness（DSH）裏接校園 GenAI gateway，常見做法是讓本機 OpenAI 兼容代理長期跑着：登錄時啓動、定時保活，即使用戶整天沒選 UM 模型，也會佔着 Python 進程和 headless Chrome。對桌面開發者來說，這是多餘的常駐開銷。
下面介紹社區插件 dsh-um-proxy-ondemand（維護者 TINGOD2006，分類爲模型推理）。它不改模型、不簽發 token，只管理 UM 發放的 um_opencode_setup.py 所啓動的那條本機代理（默認 http://127.0.0.1:8788）：DSH 真正用到 um-genai provider 時才喚醒，閒默認 15 分鐘無請求則關閉；並在 DSH 設定裏集中管理賬號、續期與狀態。
這是什麼¶
插件全名對應 npm 包 dsh-um-proxy-ondemand，倉庫爲 TINGOD2006/dsh-um-proxy-ondemand，目錄頁見 SkillHub 條目。
服務對象是澳門大學 GenAI 校園 gateway（https://chat.genai.um.edu.mo）。DSH 內建的 um-genai provider 把 baseURL 指到本機代理；插件通過監聽 llm/stream 瀑布事件，在 options.provider === 'um-genai' 時 ensureProxy()，否則完全不碰代理進程。插件本身不註冊 provider，模型菜單仍依賴 profile 裏的 @deepseek-ai/dsh-llm-pi-ai 配置。
代理腳本是 UM 校內向用戶發放的 um_opencode_setup.py；倉庫在 vendor/ 附帶一份副本，家目錄 ~/.um-opencode/um_opencode_setup.py 優先，兩邊都沒有才會失敗。
核心功能¶
按需生命週期：相對「登錄啓動 + 每 2 分鐘保活」的常駐方案，本插件改爲按需喚醒 + 閒默認 15 分鐘自動關閉（可在設定頁改「閒置分鐘」）。DSH 退出時會順帶關掉代理，避免孤兒進程。
設定與觀測：安裝後 DSH 設定 → 插件 →「UM 代理」分頁提供狀態、端口、常駐模式（alwaysOn）、Python/腳本路徑、UM 賬號（密碼不經命令行，寫入 um_opencode_setup.py set-credentials）、代理密鑰（UM_GENAI_API_KEY）等。狀態 API 示例路徑爲 /um-proxy-ondemand/api/status（GUI 端口以本機 DSH 爲準）。
模型菜單輔助：可通過設定頁「建立 um-genai provider」寫入 profile patch，並運行 scripts/um-models-sync.py --apply 從本機代理拉取 gateway 當前模型 id；代理未運行時會先被喚醒。
續期與登錄：資料說明代理依賴 UM 登錄 token，並支持隱藏桌面登錄（環境變量 UM_HIDDEN_LOGIN 默認爲 1）；401 等情形可參考 README 中的恢復腳本與續期看門狗說明。
安裝與啓用¶
前置條件¶
- 有效的 UM 賬號（無賬號則無可代理的上游）。
- Python 3.10 以上（建議 3.12）；Windows 安裝時建議把
python.exe加入 PATH，或在設定頁填pythonw.exe絕對路徑。 - Node.js 22 以上（DSH 宿主要求）。
- 代理腳本：優先
~/.um-opencode/um_opencode_setup.py，否則使用插件自帶的vendor/um_opencode_setup.py。
安裝命令¶
首選從 npm registry 安裝發佈快照（README 註明 latest 標籤當前爲 1.4.x 線；倉庫 package.json 可見更高版本號以 registry 實際解析爲準）：
dsh plugin --profile desktop add dsh-um-proxy-ondemand
若需跟蹤 GitHub main 最新 commit，改用：
dsh plugin --profile desktop add github:TINGOD2006/dsh-um-proxy-ondemand
安裝須使用桌面版內置的 dsh（profile desktop 由 Electron 獨佔）。裝完後需重啓 DSH 一次以加載新設定分頁；若 pnpm 因 DSH 佔用文件失敗，需完全退出 DSH 後在 %USERPROFILE%\.dsh\profiles\desktop 手動 pnpm add dsh-um-proxy-ondemand。
第一次配置¶
多數情況下插件會自動推導 Python、家目錄（UM_OPENCODE_HOME 未設則爲 ~/.um-opencode）與腳本路徑。需要覆蓋時，在設定頁修改，或在 profile 的 cordis.patch.yml 中寫入插件 config，例如：
- insert:
- id: dsh-um-proxy-ondemand
name: dsh-um-proxy-ondemand
config:
port: 8788
alwaysOn: true
# python: 'C:\Users\you\AppData\Local\Programs\Python\Python312\pythonw.exe'
# script: 'C:\Users\you\.um-opencode\um_opencode_setup.py'
um-genai 模型列表爲空時，在設定頁按「建立 um-genai provider」，或手動插入 README 中的 providers.um-genai 片段後執行：
python -B scripts/um-models-sync.py --apply
完成後重啓 DSH 使模型菜單重讀。
典型用法¶
- 完成 UM 賬號登錄與（如需要）API key 配置。
- 在 DSH 模型菜單選擇
um-genai下某一模型併發送消息；首次會冷啓動代理（數秒），之後走熱路徑。 - 驗證代理健康（需代理已被喚醒過，或
alwaysOn: true）：
curl.exe http://127.0.0.1:8788/health
期望 JSON 中含 "status":"ok" 與 "service":"um-opencode-proxy"。
- 查看插件狀態（將
<GUI埠>換成本機 DSH GUI 端口）：
curl.exe http://127.0.0.1:<GUI埠>/um-proxy-ondemand/api/status
設定頁「狀態」區塊會顯示 running、pid、idleTimerArmed、請求與喚醒計數等；host.script.path 爲實際將執行的腳本路徑，exists: false 表示家目錄與 vendor 均缺腳本。
移除插件：
dsh plugin --profile desktop remove dsh-um-proxy-ondemand
移除不會自動終止已在跑的代理；需另行對 um_opencode_setup.py 執行 stop（見 README）。
適用場景與注意¶
適合已有 UM GenAI 權限、在 DSH 桌面版中偶爾或按需使用 um-genai 模型的用戶，希望減少本機常駐 Chrome/Python 開銷，並希望在 GUI 內管理代理與 provider 補丁。
務必注意：插件以當前 DSH 進程權限運行，安裝前請閱讀 GitHub 源碼 與 MIT 許可證，自行評估賬號憑據與本地代理暴露面（默認監聽 127.0.0.1）。SkillHub 目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
常見故障如找不到腳本、Python 路徑 ENOENT、8788 端口占用、上游 502/503/504 或 401 token 過期等，README 中有對照表與 um-recover.ps1 等處理路徑；502/503/504 多屬 UM 後端暫時不可用，本地代理會有限次重試。
結尾¶
dsh-um-proxy-ondemand 把 UM GenAI 本機代理從「常開保活」收成「用時再開、閒時退出」，並與 DSH 的 um-genai 調用鏈對齊。進一步瞭解與 issue 反饋見 GitHub 倉庫，插件索引見 SkillHub 目錄頁。
