Skip to content
dsh marketplace

dsh-magpie

Verified

@zhiqiangme/dsh-magpie · v26.10.28 · MIT · Web UI

在 DSH 中管理 Magpie 模型列表，支持编辑排序、全量同步，以及 Magpie 程序下载升级。

Install

dsh plugin add @zhiqiangme/dsh-magpie

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Readme

@zhiqiangme/dsh-magpie

在 DSH「插件」页管理 Magpie 提供的模型，并把选中的模型写入 DSH 的 Magpie 模型分组。模型清单、名称、勾选、顺序、上下文、输出限额、图片输入和思考档位都由本插件保存。也可以从侧边栏左上角的 Magpie 入口打开同一张卡片（见「侧边栏入口」）。

可在卡片下载或升级 Windows 版 Magpie（升级时自动退出正在运行的 Magpie）；DSH 启动时若本机没有 Magpie 在运行，在后台（托盘）启动它，需要界面时点「打开 Magpie 界面」；可自动开启 Magpie 的轻量模式、在卡片切换防止休眠，可选退出 DSH 时关闭本机 Magpie。插件不迁移或卸载旧 OpenCode 插件。

卡片布局

  • 标题栏：网关状态（按已保存的地址每 15 秒检查一次 /api/hello）、已安装的 Magpie 版本（有新版本时提示，点击跳到「更新」页），以及「打开 Magpie 界面」。
  • 模型：「同步到 DSH」开关、搜索、「从 Magpie 同步」「手动添加模型」、全选与排序（默认排序、按模型排序、按供应商排序），以及模型列表。
  • 连接：网关地址、API 协议、网关 Key 与「检查连接」。
  • 偏好：Magpie 程序（启动时打开、退出时关闭）、Magpie 设置（自动开启轻量模式、防止休眠）、DSH（侧边栏入口）。
  • 更新：Magpie 程序的下载与升级、程序路径，以及插件自身更新。
  • 底栏：保存状态、「重新载入 / 放弃更改」和「保存并同步」，切换标签页时始终可见。

安装

从本仓库源码安装：先完全退出 DSH（包括托盘），在仓库根目录执行：

.\install-plugins.cmd --action install --plugins magpie --profiles desktop --yes

或者使用 DSH 自带的插件管理器：

dsh plugin --profile desktop add "file:<仓库绝对路径>\dsh-magpie"

npm 发布后可用 dsh plugin --profile desktop add @zhiqiangme/dsh-magpie。源码依赖是拷贝，更新源码后请重新运行安装脚本。

插件自身更新

「更新」页下半部分的「插件更新」管理 @zhiqiangme/dsh-magpie 的版本，与上半部分的「Magpie 程序」分开。

  • 显示当前运行版本与 npm 最新版本。沿用 WB 插件的检查机制，由宿主并行查询 npm 官方源和 npmmirror，取成功响应中的最高版本；成功结果缓存十分钟，点击「检查更新」可强制刷新。
  • 一键更新按宿主接口在不在选择途径，不写死 DSH 版本号，插件不自行执行包管理器或改写 profile：
    • 官方接口（DSH 的 pluginManager 有 listVersions/updateBundle）：先用 listBundles 核对本插件的 updatable，再用 listVersions 选最新的兼容、未弃用正式版，把精确版本和同一注册表交给 updateBundle。兼容性检查、锁、安装与失败时恢复旧版都归宿主；卡片展示核对、卸载、安装、恢复阶段，只有实际安装版本等于目标版本才显示成功，恢复失败或连接中断会提示去「插件」页核对。
    • dshmarket 兜底：已核对的 DSH 0.2.1-rc.3（目前最新的发布版）还没有 listVersions/updateBundle，这时检测到支持公开更新 API v1 的 dshmarket、且本插件从 npm / git 安装，就交给 dshmarket（传纯包名，由市场解析版本），显示进度、失败原因及实际安装版本；仅在发布冷却期或版本未变的失败之后提供「强制更新」。任务记在 sessionStorage，卡片重新挂载或插件热重载后接着轮询。
  • listVersions 每次要在宿主上跑一串 pnpm view，所以 npm 显示已是最新时不去列，列过的结果按已装版本缓存十分钟；「检查更新」两者都绕过。宿主的插件管理器每完成一次操作都会广播变更（包括在官方插件页里更新本插件），卡片据此静默重读实际安装状态。
  • 有新版本却没有一键更新时才说明原因：file: 本地目录安装需更新源码并重新运行安装脚本；由 DSH 统一管理、官方判定不可更新或没有兼容版本的安装通过宿主管理；旧宿主又没装 dshmarket 时提示安装它。
  • 设置页的两处卡片与侧栏页面共用一份更新状态，切换页面不重复提交。官方接口没有任务回查，整页刷新后只重新读取运行版本与实际安装状态，不把未知结果显示为成功。
  • 模型有未保存更改或当前操作未完成时，先保存或放弃更改、等待操作结束，再更新插件。更新成功后按结果提示重启 DSH 或刷新页面；只有 dshmarket 明确支持重启时才显示重启按钮，桌面版通常由桌面壳负责重启。

侧边栏入口

支持侧栏页面的 DSH 会在左上角「插件」一栏显示 Magpie 入口（排在「插件」「插件市场」之后、「自动化任务」之前），点击后在主区域打开与插件设置相同的管理卡片。「偏好」页的「侧边栏入口」可选：

  • 自动（默认）：模型清单为空时显示，方便首次配置；保存至少一个模型后隐藏。只看清单是否有模型，不看是否勾选同步。
  • 显示 / 隐藏：不论清单如何。

选择后立即生效；「自动」模式按已保存的清单判断，模型增删在「保存并同步」或「从 Magpie 同步」后才影响入口。正在查看 Magpie 页面时入口不会立刻收起，切换到其它页面后再按设置隐藏。入口隐藏后仍可在「插件」页打开卡片；没有侧栏页面的旧版 DSH 只保留插件页卡片。

哪些改动立即生效

卡片上的开关和分段选项（启动时打开 Magpie、退出时关闭 Magpie、自动开启轻量模式、防止休眠、侧边栏入口、同步到 DSH）改完立即保存并生效，不需要点「保存并同步」，也不会带上卡片里尚未保存的其他改动。连接设置（网关地址、API 协议、Key）、Magpie 程序路径和模型清单（增删、编辑、勾选、排序）仍需点击「保存并同步」。

打开 Magpie 界面

标题栏的「打开 Magpie 界面」打开 Magpie 的窗口。Magpie 同一时间只运行一个实例：已在托盘运行时，点击只会让该进程显示窗口，不会启动第二个网关；未运行时则启动带窗口的 Magpie。需要先下载并验证程序。

Magpie 设置：轻量模式与防止休眠

这两项直接读写 Magpie 自己的设置文件（~/.config/magpie/settings.json；设置了 XDG_CONFIG_HOME 时在其下），与 Magpie「设置 › 常规」中的同名选项相同，只改这几个字段。Magpie 第一次运行后才会生成该文件，之前这两项不可用。运行中的 Magpie 保存自己的设置前会重新读取文件，外部改动不会被覆盖（本机实测）。

  • 自动开启轻量模式（默认打开）：DSH 启动时，以及插件下载、升级或打开 Magpie 前，把 Magpie 的轻量模式设为开启：窗口关闭约一分钟后释放界面内存，网关和后台任务照常运行。取消勾选后插件不再改动这项设置，不会替你关闭它。
  • 防止休眠：关闭、开启、屏幕也常亮三档，选择后立即写入 Magpie 设置。

启动 DSH 时打开 Magpie

「偏好」页的「启动 DSH 时打开 Magpie」默认开启。插件激活时（DSH 启动、插件更新后重新加载）先检查本机：Magpie 端口已有服务应答，或已有 magpie.exe / 官方 Windows 产物名的进程（包括另装的 Magpie）在运行，都不再启动；否则以独立进程、托盘模式（magpie tray）打开「Magpie 程序路径」中的程序，不弹出窗口。程序必须能验证为 Magpie，未下载、无法验证、正在下载升级或网关地址不是本机时跳过。取消勾选后，下次启动 DSH 不再自动打开。

Magpie 也有完全无界面的 magpie serve（只运行网关，没有托盘）。插件没有用它：之后打开界面会另起一个 Magpie 进程，而它的网关已被 serve 占用，界面里看不到实时路由。托盘模式同样不弹窗口，需要时可由同一进程显示窗口。

退出时关闭 Magpie

「偏好」页的「退出 DSH 时关闭 Magpie」默认关闭，打开即生效。开启后，正常退出 DSH 时结束本机目标 Magpie，包括托盘进程；停用、卸载或更新本插件不会触发关闭。

指定了「Magpie 程序路径」时只处理该完整路径的进程；未指定时，优先识别占用本机 Magpie 端口、文件名为 magpie.exe 或官方 Windows 产物名的进程，未找到则检查插件独立目录。远程 Magpie 不会被关闭，不按进程名称批量结束。Windows 之外暂不支持此联动；强制结束 DSH 进程无法保证执行退出回调。

下载与升级 Magpie

在「更新」页的「Magpie 程序」点击「检查更新」或「下载 Magpie」。已安装时显示当前版本和「升级 Magpie」；下载期间显示进度。下载或升级完成后自动以独立进程启动 Magpie：首次下载打开窗口，方便完成配置；升级后在托盘启动，不弹窗口。DSH 退出不会连带结束它（除非开启「退出 DSH 时同时关闭 Magpie」）；若该程序已在运行则不重复启动，启动失败只提示原因、不影响安装结果。

升级正在运行的 Magpie 时，插件先下载并校验新版本，替换前才结束目标程序（包括托盘进程及其插件宿主子进程），尽量缩短网关不可用的时间；正在进行的请求会中断。无法结束时不替换、提示手动退出；结束后若替换失败，插件会在后台重新打开原程序。

  • 默认安装到 <DSH_HOME>/magpie/backend/current/magpie.exe，未指定 DSH_HOME 时使用 ~/.dsh。Magpie 程序路径 可填写已有 exe 的绝对路径，留空恢复独立目录；通过「保存并同步」保存路径偏好。程序操作立即作用于填写的路径，但不会保存或覆盖模型草稿。
  • 下载中断后自动续传：连接 30 秒无数据即断开，从已下载的字节继续请求，最多尝试 5 次；仍失败时保留部分文件，再次点击「下载 Magpie」或「升级 Magpie」接着下载。部分文件以预期 SHA-256 命名，放在 <DSH_HOME>/magpie/cache/downloads，换了 Release 不会续到旧文件上；校验不符时删除并从头下载，安装成功后删除。
  • 使用官方 yetone/magpie-releases 的最新正式版，选择完整 GUI 产物 magpie-windows-amd64.exe / magpie-windows-arm64.exe。使用 GitHub 提供的 SHA-256 digest，缺少时读取同一 Release 的 SHA256SUMS；无有效校验值则拒绝安装。GITHUB_TOKEN / GH_TOKEN 可提高版本查询额度，界面不返回 token。
  • 下载、校验与暂存版本验证通过后才替换；升级后再次验证，失败自动恢复旧文件。旧版备份放在 <DSH_HOME>/magpie/backend/versions，每个目标保留最近三次成功升级的备份。并发安装通过操作锁保护，插件关闭取消下载。Magpie 自己的账号、插件和设置目录不会迁移或清理。
  • 下载升级目前支持 Windows x64 / ARM64；其他平台的模型管理照常使用。开发和测试可用 DSH_MAGPIE_BACKEND_ROOT 单独指定程序管理根目录。

自动更新 Magpie 程序

「更新」页的「自动更新 Magpie 程序」默认开启，开关立即保存。后台任务随插件启动，无需打开管理页面：启动约 10 秒后首次检查，之后每 5 分钟检查官方最新正式版。按 Release 的 published_at 计算，发布满 30 分钟才下载；已发现的新版本会在冷却时间到期时再次检查。缺失或无效的发布时间不会自动升级，未来时间继续等待。

下载和 SHA-256、程序版本校验可以在对话运行时进行。完成后，检查宿主所有工作区及子代理：全部空闲才退出目标 Magpie、替换 exe 并在托盘重新启动；有对话运行、执行工具或等待审批，或宿主运行状态暂不可用时，保留已校验文件，每 5 秒重试空闲检查。手动升级同样在替换前等待对话空闲，但不受 30 分钟发布等待限制。

自动更新只处理已保存路径中能识别版本的本机程序，不自动首次安装、不降级；关闭插件总开关、关闭自动更新、切换远程网关或更改已保存程序路径后，尚未开始替换的自动任务会取消。下载失败保留断点缓存，后续检查重试；手动与自动升级共用安装锁、校验、备份与回滚。停用插件会停止计时并中止等待。界面显示下载、校验、等待对话空闲及升级结果。

模型管理

  1. 在插件卡片的「连接」页填 Magpie 地址，默认 http://127.0.0.1:3425，选择调用协议。 点击「从 Magpie 同步」会立即用当前 Magpie 目录覆盖保存清单并更新 DSH，无需再次点击保存。
  2. 点击「手动添加模型」，填写 Magpie 可识别的完整 ID，例如 workbuddy-ai/deepseek-v4.1-flash 或路由组 ID。显示名称可留空。
  3. 模型列表左侧勾选，显示名称右侧箭头展开详细配置；详情在列表原位展开，后续模型自动下移。按需编辑 ID、名称、上下文、输出限额、图片输入和思考档位，例如 low, high, max。思考档位只能使用 DSH 支持的 off、minimal、low、medium、high、xhigh、max，且不能只有 off；不支持思考的模型留空。未知能力留空，不按模型名称猜测。
  4. 勾选模型，拖动勾选框左侧的六点手柄调整顺序，打开「同步到 DSH」，点击「保存并同步」。选中的模型按清单顺序出现在 Magpie 分组（provider ID 仍为 dsh-magpie）。

管理列表与 DSH 模型选择器会在模型名后追加供应商简称，例如 DeepSeek V4.1 Flash WorkBuddy、Step-5-Preview WorkBuddy GL、DeepSeek V4.1 Flash Free OpenCode。workbuddy-ai 为国际版，显示为 WorkBuddy GL；workbuddy 为国内版，显示为 WorkBuddy。Qoder / Trae 国际版同样使用 GL。名称已带对应简称时不重复追加；手工名称、模型 ID 与排序保持不变，未知供应商或路由组不追加简称。

DeepSeek-Flash、Deepseek-V4.1-Flash 等写法统一显示为 DeepSeek V4.1 Flash，保留 Free、(Max) 等尾缀和供应商简称；搜索、快捷排序与 DSH 模型名称同步使用这一显示规则。此规则仅派生显示名称，不改写保存的名称或模型 ID，其他 DeepSeek 版本不受影响。

支持搜索、全选、取消全选、删除和离线编辑。批量勾选只影响当前搜索结果。保存只写 DSH 配置，不要求 Magpie 正在运行；模型 ID 是否可用，取决于 Magpie 和上游实际支持。

「默认排序」按 Magpie 目录（/v1/models）的顺序排列，需要 Magpie 正在运行；目录里没有的模型（例如手动添加的）保持原相对顺序排在后面。读取失败时显示原因，清单不变。「按模型排序」按模型名称升序排列，同名模型再按供应商简称排列；「按供应商排序」先按供应商简称升序分组，再按模型名称排列。排序忽略大小写，数字按自然顺序排列（例如 Model 2 在 Model 10 前），空名称或无供应商的条目排在后面；键值相同的条目保留相对顺序。有搜索条件时只重排匹配模型，隐藏条目的位置不变。勾选、编辑内容和展开状态一并保留，点击「保存并同步」后保存新顺序。

拖动六点手柄调整顺序时，其它模型会实时让出落点，松手后直接落位；拖出列表或取消拖动则各行滑回原位。手柄获得焦点时也可按 ↑ / ↓ 键逐个移动（有搜索条件时跳过隐藏模型）。排序、增删、展开和筛选后，各行从原位置平滑移到新位置；系统开启“减少动态效果”时不播放这些动画。

从 Magpie 同步时的顺序取决于最后一次对完整清单的排序：

  • 按模型排序（默认）：同步后按模型名称自动排好。
  • 默认排序：同步后沿用 Magpie 目录的顺序（卡片显示提示）。
  • 手动顺序：拖动排序、「按供应商排序」或只对部分搜索结果排序后，清单标记为手动顺序（卡片显示提示）。此后「从 Magpie 同步」保留现有顺序：仍在目录中的模型按原位置排列，新模型按名称排在末尾，上游已移除的模型被删除。不搜索时对完整清单点击「默认排序」或「按模型排序」并保存，即恢复对应的自动顺序。

本分组逐模型默认选择已配置档位中的最高档，按 off < minimal < low < medium < high < xhigh < max 排序。例如 Step 的 low, medium, high 默认 High，Flash 的 low, high, max 默认 Max。手动选择的档位继续生效；未声明推理能力的模型不补默认值。

当前 DSH 的 llm-pi-ai 只提供 provider 级默认配置。插件在宿主现有适配器的 resolveModel / prepareCall / stream 接口上仅补充 dsh-magpie 路由的逐模型默认值，沿用同一套模型元数据与协议实现。已有 provider 和模型 ID 保持不变，其它分组不受影响；适配器重载时重新附加，停用插件时撤销。

「从 Magpie 同步」先用 /api/hello 核对身份，再完整读取并校验 /v1/models。每次点击都以 Magpie 当前可用目录替换整个清单：名称、上下文、最大输出、图片能力和思考档位跟随上游，顺序默认按「按模型排序」的规则自动排好，选了「默认排序」时沿用 Magpie 目录顺序；手动排过序时保留现有顺序，新模型按名称接在末尾（见下文「排序」）；模型全部勾选，开启同步，并立即保存及更新 Magpie 分组。上游已关闭或删除的模型、本地手工添加或修改的模型都会被这次全量结果覆盖；上游目录合法为空时清空清单并移除分组。请求失败、目录异常或版本冲突时保留原配置；清单保存后 DSH 分组更新失败会明确提示，可再次同步。模型名称仍追加供应商简称，默认推理档位仍选最高档。上游档位中 DSH 不支持的值（例如 none）会被忽略，只剩 off 时视为不声明思考；上游最大输出不小于上下文时只省略该模型的最大输出，其余字段照常导入。

关闭「同步到 DSH」（立即生效），或取消全部模型勾选后保存，只移除本插件创建的 dsh-magpie provider；保存的清单仍可编辑。已引用该分组的会话需要重新选择可用模型。卸载插件遵循 DSH 的配置保留规则，需要移除分组时先关闭同步。

配置边界与 Key

  • 固定插件行 ID 和 provider ID 都是 dsh-magpie，不会修改 Magpie 原生的 magpie / magpie-responses / magpie-anthropic 分组、其它 provider、默认模型或其它 profile。
  • 模型写入经宿主 configEditor，按锁内最新配置合并；已被其他配置占用的同名 provider 拒绝覆盖。两个页面同时编辑时，旧页面保存或修改即时开关、选项均返回冲突并保留草稿，需要重新载入后操作，避免覆盖刚保存的清单。
  • 模型列表默认空，同步默认关闭。手动点击「从 Magpie 同步」才读取上游目录；普通保存和插件启动沿用已保存清单，不定时读取上游目录。
  • 本机 loopback 使用官方约定的 magpie-dsh 标识；它会写入凭据供 DSH 调用，但不算已保存的 Key，切到远程 Magpie 时也不会发出。远程 Magpie 需要有效的 gateway key；卡片保存到 DSH 凭据库的 DSH_MAGPIE_API_KEY，配置中只保存引用，状态接口不返回 Key。环境变量同名值优先且只读；输入框留空沿用已保存值。
  • 调用协议可选 Chat Completions、Responses、Anthropic Messages；前两者使用 Magpie 地址下的 /v1/，Anthropic 使用根地址。修改协议或地址后保存会同步更新 provider。
  • 清单保存成功但凭据或 provider 同步失败时，卡片明确显示失败原因；清单保留，修复后再保存同步。读取配置和检查连接不会发送推理请求。

配置示例（写在本插件行的 config 下）：

syncEnabled: true
baseURL: http://127.0.0.1:3425
api: openai-completions
models:
  - id: workbuddy-ai/deepseek-v4.1-flash
    name: DeepSeek V4.1 Flash
    enabled: true
    contextWindow: 1000000
    maxTokens: 128000
    input: [text, image]
    reasoningEfforts: [low, high, max]

开发与验证

只有 Node 内置模块，无安装依赖和构建步骤。node --test test/*.test.mjs 使用独立的宿主替身与本机假 Magpie 服务，不修改真实 DSH/Magpie 配置，不发送真实推理请求。

上游协议依据 Magpie 应用接入文档；模型能力与配额仍取决于实际账号和上游。

MIT，见 LICENSE。