前言¶
在 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）：
- 环境变量
MAGPIE_LITE_CONFIG指向的文件 $MAGPIE_LITE_HOME/config.json- 指针文件
<DSH home>/magpie-lite.json（网关启动时写入，指向其config.json；网关运行中时为主要机制） <DSH home>/magpie-lite/config.json（网关未运行时的惯例路径）- 插件包旁自带的
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 分组。
典型用法¶
首次在网关侧启用模型¶
- 确保 gateway 已启动（默认管理地址
http://127.0.0.1:19998/admin）。 - 添加各上游 Provider 的 API Key，打开需要使用的模型开关。
- 在 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 核对模型是否注册成功。
