前言¶
DeepSeek Harness（DSH）的会话能力依赖你在运行时选用的 LLM。若模型跑在本地 Magpie 网关后面，常见做法是单独维护一份模型列表、手写 OpenAI 兼容地址，或在 harness 外再挂一层代理。插件 dsh-magpie-connect（维护者 bitxeno，仓库 bitxeno/dsh-magpie-connect）把 Magpie 网关上的模型注册为 DSH 原生 LLM 适配器：装好后在 Web 端设置里填网关地址和 Key，模型会进入 DSH 模型选择器，无需为网关单独起进程或配系统代理。
这是什么¶
dsh-magpie-connect 是 DSH 社区插件目录中「模型推理」类插件，简介为：将 Magpie 网关模型快速接入 DeepSeek Harness。它在 DSH 内实现 MagpieAdapter（LlmAdapter），通过 OpenAI 兼容的 chat/completions 或 responses 流与网关通信；模型目录来自网关 GET {baseUrl}/models，并在本地缓存，网关不可达时还有编译期静态快照兜底。
状态与设置写在 ~/.dsh-magpie-connect/（含 settings.json、模型缓存、adapter-status.json）。插件以当前 dsh 进程权限运行，安装前建议在 GitHub 上查看源码与 MIT 许可证。
核心功能¶
以下能力均来自插件 README 与 package.json 说明：
- 模型自动同步 — 网关列出的模型可进入 DSH 模型选择器；具体显示哪些由白名单（
enabledModels）决定，语义与 DSH 自带「模型」设置一致。 - 图片识别 — 网关声明支持图片的模型可发图；纯文本模型收到图片会直接报错，不会静默丢弃。
- 思考档位 — 网关支持的思考档位（含
none、ultra）原样出现在选择器；none关闭思考，ultra直通网关，不在本地截断。 - 容错与刷新 — 启动即注册适配器，目录后台预热；可配置刷新间隔、重试与多种超时；暴露模型集合变化时会通知浏览器重读缓存。
安装与启用¶
环境要求：DSH 的 web profile、Node.js ≥ 20、运行 DSH 的环境能访问 Magpie 网关。package.json 中声明的 DSH 引擎范围为 >=0.2.0-rc.1 <0.2.1-0 或 >=0.2.1-alpha.1 <0.3.0-0（以你实际安装的 DSH 版本为准）。
官方安装命令如下：
dsh plugin --profile web add dsh-magpie-connect
安装后重启 dsh web。已安装时用同一条命令可更新到最新版本（npm 包当前版本为 0.4.1）。
典型用法¶
第一步：在设置页填网关地址和 Key¶
打开 设置 → Magpie 网关，确认两项后点「保存」：
- API 地址 — 须带版本段，默认
http://127.0.0.1:3425/v1；网关不在本机时改为实际地址。插件只在你填的 base URL 后接资源路径，不会自动补/v1。 - API Key — 必填；即使网关不校验 Key，也需要非空字符串才会生效。
保存后可点「测试连接」查看是否连通及网关上有多少模型。地址有默认值而 Key 没有，未填 Key 前模型选择器为空。
第二步：选择要显示的模型¶
点 获取可用模型，在弹窗中勾选需要的模型，再点「应用选择」。列表是白名单：网关新上架的模型不会自动出现，需在弹窗里勾选并应用；删掉的行会从列表和选择器一起移除，网关某条 lane 临时抖动也不会把已删模型偷偷加回。
恢复默认模型 会清掉自定义列表，回到直接使用网关完整目录；空列表 [] 与「继承网关目录」是两种不同状态——前者不提供任何模型，后者全量提供。
「获取可用模型」成功时会用网关当前目录整体替换本地目录，下架模型会同步消失；读取失败则不会清空本地目录，避免误清选择器。弹窗使用的是当前表单里的地址和 Key（即使尚未保存），便于换网关时一次试连。
模型增删会自动保存；地址和 Key 须点「保存」才生效。
用配置文件代替设置页（可选）¶
可在 profile 的 cordis.patch.yml 中写入插件配置，例如：
- id: dsh-magpie-connect
name: 'dsh-magpie-connect'
config:
providerId: dsh-magpie-connect
displayName: Magpie
baseUrl: http://127.0.0.1:3425/v1 # 带版本号的完整地址
apiKey: not-needed # 网关通常不校验，但必须非空
refreshSeconds: 300
maxRetries: 2
timeoutMs: 300000
firstEventTimeoutMs: 90000
idleTimeoutMs: 60000
优先级为：设置页 > cordis.patch.yml > 默认值；设置页只覆盖你保存过的字段。其余配置项（如 dataDir、各超时与 refreshSeconds）见 README 中的表格说明。
适用场景与注意¶
适合谁：已在用或计划用 Magpie 作为 LAN 网关、希望在 DSH Web 里统一选模型、并需要图片与思考档位与网关声明一致对齐的开发者。
常见问题（摘自文档）：
- 选择器为空 — 先确认地址（含
/v1等版本段）、Key 已保存，再「测试连接」。 - 发图失败 — 仅支持网关声明为可收图的模型；且图片需经 harness 附件服务读取，缺少该服务的组合也会失败。
- 从旧版升级 — 首次启动会把旧
hiddenModels转为enabledModels并写入~/.dsh-magpie-connect/settings.json，只执行一次。
DSH 生态强调「一切皆插件」；SkillHub 插件目录 是社区站点，与 DeepSeek / 幻方无官方从属关系。安装第三方插件前请自行审阅源码与权限影响。
