前言¶

在 DeepSeek Harness（DSH）里开发智能体时，模型来源往往分散：官方 Provider、自建网关、本地 Ollama 等各自一套配置。若你已经在本机跑 magpie-lite gateway，把 DeepSeek、GLM、Kimi、OpenRouter、Ollama 等统一成 OpenAI 兼容的 http://127.0.0.1:19998/v1，再在 DSH 里重复填 endpoint 和模型列表，既容易和网关控制台不一致，也不利于 Claude Code、Codex 与 DSH 共用同一套模型集。

下面介绍社区插件 dsh-magpie-lite（维护者 hualuo520-h）：它把本地 magpie-lite 网关注册为 DSH 的一个普通 Provider，模型选择器会出现 magpie-lite 分组，列出你在网关里启用的模型；网关侧改一次配置，各 Agent 共用。

这是什么¶

dsh-magpie-lite 是 DSH 的模型推理类插件，定位是「桥接层」而非网关本身：插件读取 magpie-lite 的 config.json，通过 @earendil-works/pi-ai 在 openAICompletionsApi 上构建 Provider，并向 DSH 注册 magpie-lite 适配器。请求体不经插件改写，协议转换、流式输出与工具调用均由 magpie-lite gateway 完成。

数据流可概括为：

DSH 模型选择器（如 magpie-lite/deepseek-chat）
        ↓
dsh-magpie-lite
        ↓ 定位 config.json，注册适配器
magpie-lite gateway  http://127.0.0.1:19998/v1
        ↓ 按 provider/model 前缀路由
DeepSeek / GLM / Kimi / OpenCode Zen / OpenRouter / Ollama / Pollinations 等

插件当前版本为 1.0.0（MIT 许可证），依赖 Node ^22.19.0 或 >=24.0.0。社区目录页：skillhub.cn/plugins/hualuo520-h/dsh-magpie-lite；源码与说明：GitHub - hualuo520-h/dsh-magpie-lite。目录站为社区生态站点，与 DeepSeek / 幻方无官方从属关系。

核心功能¶

模型分组与共用配置¶

安装后，DSH 模型选择器增加 magpie-lite 分组，条目对应你在网关控制台启用过的模型。网关的 config.json 是单一事实来源：改端口、gatewayKey 或增删模型后，插件会读取同一文件，无需在 DSH 里再维护一份模型表。

自动发现网关配置¶

不同机器上网关安装路径不固定，插件按以下顺序解析 config.json（<DSH home> 为环境变量 DSH_HOME，否则为 ~/.dsh）：

1. 环境变量 MAGPIE_LITE_CONFIG 指向的文件
2. $MAGPIE_LITE_HOME/config.json
3. 指针文件 <DSH home>/magpie-lite.json（网关启动时写入，指向其 config.json；网关运行中时为主要机制）
4. <DSH home>/magpie-lite/config.json（网关未运行时的惯例路径）
5. 插件包旁自带的 config.json

网关运行时指针保持最新；未运行时回退到惯例路径，并会提示预期位置，而不是静默显示零个模型。

配置热更新¶

插件监听 config.json 变更（约 400 ms 防抖）后重新注册模型，一般无需重启 DSH。若你在网关管理页增删模型或改 Provider，保存后即可在选择器中反映（仍以 config.json 中的列表为准，而非实时向上游查询）。

免费模型显示名¶

若某 Provider 在 config.json 中显式设置 "free": true，DSH 选择器中的显示名会带 （免费） 后缀（例如 openai（免费））；模型 id（provider/model）不变，路由与调用不受影响。未填 API Key 不会自动当作免费，避免误标 DeepSeek、智谱等需 Key 的 Provider。

安装与启用¶

安装前请确认：magpie-lite gateway 已安装且正在运行；本插件只做 DSH 侧桥接。至少在一个 Provider 上配置 Key 并打开开关，否则插件仍会加载，但分组为空（DSH 会隐藏空分组）。网关自启可参考网关目录下的 register-autostart.ps1。

插件市场（推荐）¶

DSH Settings → Plugin Marketplace → 搜索 dsh-magpie-lite → Install。该路径使用预构建的 npm 包，通常不需要 allowBuilds 审批。

命令行¶

dsh plugin --profile web add dsh-magpie-lite

手动安装¶

将仓库内容复制到用户目录下的 dsh-magpie-lite 插件路径，并在 profiles/desktop/package.json 的 dsh.profile.bundles 中加入 dsh-magpie-lite 后重启 DSH。从源码安装时 pnpm 可能拦截构建脚本，需在 profile 的 pnpm-workspace.yaml 中自行配置 allowBuilds；npm 包为预构建，无此步骤。具体复制命令见 README 中的 PowerShell 示例。

安装完成后重启或按 DSH 插件加载流程生效，在模型选择器中查看是否出现 magpie-lite 分组。

典型用法¶

首次在网关侧启用模型¶

1. 确保 gateway 已启动（默认管理地址 http://127.0.0.1:19998/admin）。
2. 添加各上游 Provider 的 API Key，打开需要使用的模型开关。
3. 在 DSH 中选择形如 magpie-lite/<provider>/<model> 的条目进行对话或 Agent 运行。

自定义 config 路径或安装目录¶

若 config.json 不在默认位置，设置环境变量后重启 DSH：

• 直接指向配置文件：MAGPIE_LITE_CONFIG=<你的 config.json 绝对路径>
• 指向网关套件根目录：MAGPIE_LITE_HOME=<网关目录>

独立诊断（不启动 DSH）¶

在 PowerShell 中执行（路径以 Windows 用户目录为例，Linux/macOS 请改为对应的 ~/.dsh 路径）：

node "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-magpie-lite\lib\bin.js"

输出包括实际使用的 config.json、路由、Key 指纹以及将注册的模型列表。数量为 0 时，问题通常在网关侧而非 DSH。网关日志可参考 <gateway-dir>\data\gateway.watch.log 与 data\boot.log。

适用场景与注意¶

适合谁： 已在本机使用 magpie-lite 统一多上游模型，并希望 DSH、Claude Code、Codex 等同享网关里那一套模型列表的开发者。

前置条件：

• 网关必须运行；插件不替代 gateway 安装与转发。
• config.json 中至少启用一个 Provider。
• Node 版本满足插件 engines 要求。

已知限制（摘自官方说明）：

• 模型列表来自 config.json，不是对上游的实时枚举。
• 插件仅声明文本模态；多模态是否可用取决于上游模型。
• stop 序列不受支持（pi-ai 层面的限制）。

安全与权限： DSH 插件在当前 DSH 进程权限下运行，会读取本机上的网关配置与环境变量。安装前建议在 GitHub 查看源码与 MIT 许可证，确认与你的工作区策略一致；勿在不可信环境直接复制未审阅的插件包。

结尾¶

dsh-magpie-lite 把本地 magpie-lite 网关以标准 Provider 形式接入 DSH：一处网关配置，选择器里统一的 magpie-lite 分组，配置变更可热更新。若你正在用 magpie-lite 聚合多模型，可按上文安装命令启用，并用独立诊断 CLI 核对模型是否注册成功。

• 社区目录：https://www.skillhub.cn/plugins/hualuo520-h/dsh-magpie-lite
• 源码与 README：https://github.com/hualuo520-h/dsh-magpie-lite