dsh-magpie-bridge

dsh-magpie-bridge

独立的 DeepSeek Harness (DSH) 插件。在本地已安装、运行并登录 Magpie 的前提下，自动连接 Magpie 网关，动态发现并同步聊天模型到 DSH，同时接入 Codex 与 Gemini 生图接口，并可自动配置自媒体工作台的 HTTP 生图来源。

注意：本插件不会自动安装或启动 Magpie，不会代为登录第三方平台账号，不会擅自修改 DSH 的默认聊天模型，也不会在接入时自动发起试画消费生图额度。

---

运行环境与依赖

• Node.js：>=22.19.0
• DeepSeek Harness (DSH)：>=0.2.1-rc.2 <0.3.0
• 前置插件：已启用官方适配插件 @deepseek-ai/dsh-llm-pi-ai
• 外部依赖：已在本地安装、启动并完成登录的 Magpie（默认免密监听 http://127.0.0.1:3425）

---

安装与构建

插件尚未发布至 npm 仓库。获取源码后，可通过本地打包生成的 .tgz 进行安装：

# 在源码根目录下打包产出 tgz 文件
npm pack

# 通过 DSH 命令行添加插件（请将路径替换为实际打包文件路径）
dsh plugin --profile web add "路径/dsh-magpie-bridge-1.0.0.tgz"

安装完成后，确保 Magpie 正在运行，启动或刷新 DSH 即可自动建立连接。

---

核心特性

• 自动检测与模型发现：启动后即刻检测，随后默认每 30 秒轮询一次 /v1/models。实测可正常发现并载入（当前实测环境发现 21 个模型，具体数量取决于运行时 Magpie 实际登录的账号与平台，非硬编码固定值）。
• 三种原生协议智能路由：根据 Magpie 声明的 native_endpoints，将模型分别分发至三种协议提供方，确保原生兼容：
  • /v1/chat/completions -> magpie（OpenAI Completions 兼容）
  • /v1/responses -> magpie-responses（OpenAI Responses 原生）
  • /v1/messages -> magpie-anthropic（Anthropic Messages 原生）
• 元数据同步：自动匹配上下文窗口大小、最大输出上限、图片多模态输入以及受 DSH 支持的推理档位（reasoningEfforts）。
• 断线保护与容灾：当 Magpie 重启或暂时离线时，插件会保留最后一次成功的模型配置，避免 DSH 提供方丢失；待 Magpie 恢复后自动重连。
• 自媒体工作台无侵入集成：当检测到自媒体工作台（dsh-media-desk）存在且其生图配置为空白或已指向 Magpie 时，自动写入原版 HTTP 生图来源配置。若用户已配置其他生图来源则予以完整保留，无需对工作台源码打补丁。
• 非侵入式设计：不修改系统默认聊天模型，不改动配置前缀之外的其他模型提供方。停用或卸载插件仅停止同步进程，已写入的模型配置与工作台设置默认予以保留，用户可按需手动清理。

---

生图功能说明

生图模型通常不出现在 Magpie 的 /v1/models 聊天模型列表中，由插件配置独立管理。可选候选模型如下：

模型显示名称	模型 ID (imageModel)	验证状态
Codex GPT Image 2	codex/gpt-image-2	Magpie 接口实测出图成功
Codex GPT Image 2.5	codex/gpt-image-2.5	配置支持，未实测出图
Gemini Flash Image	antigravity-plugin/gemini-3.1-flash-image	插件实测出图成功

插件不会主动发起任何测试调用或预绘图，杜绝无意义的额度消耗。生图失败时不进行静默重试或模型降级。

---

工具与状态页

注册的 DSH 工具

• magpie_status：查看当前 Magpie 连接状态、BaseURL、已载入模型数及工作台配置状态；传入参数 { refresh: true } 可立即触发一次探测与同步。
• magpie_image_generate：通过 Magpie 已登录账号生成图片。参数包含 prompt（必填）、model、size、quality，生成成功后将文件以安全权限写入 $DSH_HOME/plugins/magpie-bridge/images/，并返回本地绝对路径。

Web 状态页面与接口

在已登录当前 DSH 的浏览器中访问：

http://<当前DSH地址>/magpie-bridge/

可直观查看连接状态、版本及模型数量，并支持手动点击重新连接。所有路由均集成 DSH 登录态及 Origin 校验：

• GET /magpie-bridge/status：获取当前连接状态 JSON。
• POST /magpie-bridge/refresh：立即触发探测并返回最新状态 JSON。
• POST /magpie-bridge/images/generations：接受 prompt、model、size、quality，返回 OpenAI 风格的 Base64 图片数据。

---

插件配置项

可通过 DSH 插件配置界面或配置文件调整以下参数：

配置字段	类型	默认值	说明
baseURL	string	""	Magpie 网关地址。留空则按优先级自动探测，亦可通过 MAGPIE_BASE_URL 环境变量指定
providerPrefix	string	"magpie"	管理的模型提供方名称前缀，仅影响以此为前缀的 3 个路由
apiKeyEnv	string	"MAGPIE_GATEWAY_KEY"	绑定的 DSH 凭据键名。本机免密模式下插件会自动填充占位凭据
pollIntervalSeconds	number	30	状态检测与模型列表同步周期，范围 5 - 3600 秒
connectMediaDesk	boolean	true	是否自动连接空白或现存 Magpie 的自媒体工作台生图来源
imageModel	string	"codex/gpt-image-2"	默认生图模型 ID

寻址优先级与凭据机制

1. 地址发现优先级：插件显式配置 baseURL > 环境变量 MAGPIE_BASE_URL > 上次成功连接地址 > 已有 Magpie 提供方地址 > 本机默认地址 http://127.0.0.1:3425/v1。
2. 认证说明：Magpie 默认在本机运行时免密，但底层的 @deepseek-ai/dsh-llm-pi-ai 强制要求非空凭据，插件会自动为 apiKeyEnv 注入 magpie-local 占位符；若连接远端网关或开启了 Magpie 认证，请在 DSH 凭据管理器中为该键名配置真实 API Key。

---

开发与测试

插件自带轻量 Mock 测试套件，执行测试完全无需消耗真实生图额度：

# 运行单元测试（包含 92 个离线测试用例）
npm test

---

开源许可证

本项目基于 MIT License 开源。