前言¶
在 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 目录页。
