# dsh-magpie-connector [English](README.md) · 简体中文 ![模型选择器:按上游 provider 分组为 Magpie (Claude)、Magpie (Codex)、Magpie (Deepseek)](docs/model-picker.png) ![设置页:顶部连接线路,下方按 provider 分组的模型可见性、默认 effort 与用量卡片](docs/settings.png) *上:模型选择器,路由组单独成 Magpie (Routing) 分组,其余按上游 provider 分组;下:设置 → Magpie 的「路由组」分区(可见性、类型与默认推理强度)。截自隔离 DSH 宿主与本地 mock Magpie 网关,网关地址、模型和账号均为演示数据。* ![Magpie connector 架构:Web GUI 与 Host 插件、凭据与设置、Magpie 网关与上游 provider,可选经 Cloudflare Access](docs/architecture.zh.svg) **把自托管的 Magpie 网关接入 DeepSeek Harness,每个上游归属对应一个 provider route:原版 DSH 即按上游 provider 分组展示模型,附带用量卡片(可直接使用 Codex 重置卡)和会话级快速档。** Magpie 继续负责登录、账号、路由和厂商出站代理,本插件补齐 DSH 侧。 **产品方向:** 更好地展示 Magpie 用量,让 DSH 用户方便地使用网关已有的模型与路由入口;账号池和路由策略留在 Magpie。详见[产品定位与设计边界](docs/product-positioning.md#中文)。 ### 你会得到什么 | 能力 | 具体行为 | |---|---| | **Magpie 网关接入**(基础) | 每条线路只需地址和该线路的 key。模型目录来自网关 `GET /models`;支持 Responses 的模型走 Responses,其余走 Chat Completions。文本、工具往返、图片、usage、取消以及 DSH 统一重试都能正常工作。 | | **保存前检查线路**(0.4.0) | 每条线路卡片有「检查线路」:用当前填写的地址、接入方式与 key 发一次真实 `GET /models`(凭据留空则用该线路已保存的值),显示结果分类、耗时、模型数量,以及在宿主有缓存目录时与缓存相比多出/缺少的模型。它不改当前线路、不写凭据或设置、不触发目录同步,只是只读快照;差异基准是**缓存目录**,所以不会宣称「与当前线路一致」。 | | **多线路自动切换**(特色) | 通常一条线路(首次安装为空,最多 5 条),可添加备用线路并按序号自动选择:每次操作前对候选地址做 ≤600ms 的 TCP 可达探测(正缓存 10s / 负缓存 15s,不后台轮询),在家走局域网、在外自动落到公网。切换线路时模型目录继承不闪断、用量卡片清空并按新线路重读;单线路(通常一条)行为与旧版一致。 | | **按上游 provider 分组**(特色) | 原版 DSH 即可使用,无需 Host 扩展:插件按网关 `owned_by` 为每个归属注册一个真实 provider route(`dsh-magpie-connector-claude`、`-codex`、`-opencode-go` 等;缺失或不合法归入 `-other`),官方模型选择器因此显示 `Magpie (Claude)`、`Magpie (Codex)`、`Magpie (Opencode-go)`、`Magpie (Other)` 分组。设置页和用量卡片使用同一套分组,只出现在用量里的 provider 也不会被丢弃。 | | **路由组**(0.7.1) | Magpie 的路由入口——自定义组(`group/…`)与自动发现组(`auto/…`)——在选择器中单独成 `Magpie (Routing)` 分组,不再落在首个成员的厂商下;设置页最上方新增「路由组」分区:可见性(有自己的「恢复跟随网关列表」)、类型(自定义 / 自动)以及网关声明的默认推理强度。只按 id 前缀识别。插件原样发送组 id,由 Magpie 选择成员、厂商与账号(路由组的 effort 可能改变实际成员)。新建和编辑路由组请在 Magpie 中进行。 | | **线路面板与延迟** | 已配置的线路默认全部收起,点行头部展开编辑;上移 / 下移 / 删除是常驻的 DSH 产品图标按钮(带 tooltip)。打开设置页对每条已保存且地址可解析的线路做一次 TCP 建连测速(并行、单条 ≤600ms、不发 HTTP、不带凭据),用 4 格信号条 + 毫秒显示;超时显示「超时」,旧版宿主或失败显示「—」。只展示当时的网络质量,不参与自动选线、不持久化、不轮询。 | | **按线路的 Cloudflare Access** | 每条线路可单独选择「直连」或「Cloudflare Access」。启用后该线路的请求带上服务令牌两项并保留 bearer key;服务令牌永远不会发往明文 HTTP 线路。 | | **用量卡片** | 每个上游账号展示计划、到期时间、各窗口读数和 Codex 重置卡(网关提供时):折叠行「用量限制重置 · 可用 N 次」,展开逐张看到期时间与最早一张还剩多久(`N 天后过期`);按窗口发放的计划摘要显示「5 小时 N 次 · 每周 M 次」。打开设置页只读一次,之后只有点单张卡片的「刷新」才会重新读取;用量条超过 70% 变橙、达到 90% 变红。 | | **使用 Codex 重置卡**(0.6.3) | 最早到期的那张带「使用…」按钮。周用量 ≥ 80% 且读数新鲜时才可点;确认前后 host 都会重新读一次网关再校验。确认会消耗一次额度:60 秒一次性票据 + 对话框(账号、周用量、到期时间),必须先勾选才能提交。全插件同一时刻只允许一个;网关 4xx 说明没花掉;应答无法解析时该账号锁定到 host 重启(先去 Magpie 核对,不要重试)。需要完整权限的 gateway key;自建入口还需为 `POST /magpie/quotas/codex-reset` 放行。 | | **侧栏用量卡**(0.6.0) | 设置 → Magpie 新增「侧边栏用量」开关(host 持久化,默认关闭)与自动刷新间隔(分钟,`0` = 关闭,默认 5)。打开后左侧栏底部常驻一张密集卡片:默认每个上游一行显示周窗口(`7 days`),在「卡片显示的窗口」里勾上 5 小时窗口或月窗口(`30 days`)后,该上游变成「名称单独一行 + 每个档位一行」,每行都带到期时间(`11/20 11:00`,当年只给月/日与时间,跨年带年份)、读数与自己的进度条;只勾一个时仍是单行(名称后括号跟窗口名)。勾选的档位在该上游不存在时,退回它可用的窗口、网关自己的文字读数、「无限」或余额,不编造;网关没给某个窗口的重置时间时显示 `—`(不推算)。卡头只有刷新与展开;收起正文最高 320px,多出的在卡内滚动(不显示滚动条),底部提示带在还有内容时显示双下箭头、滚到底后只是隐藏箭头而保留占位(卡片不跳),展开明细同样适用。点标题行在手风琴里展开每个上游的全部窗口、重置时间/机会、余额与错误,占列表高度而不是盖住列表;侧栏收起时只剩一个 Magpie icon,点开是 320px 浮层。同一上游有多个账号时(0.7.2),上游名称只显示一次并附账号数,每个账号以 `user`(没有时为「账号 N」)和 plan 打头;读数是「无限」的窗口不画进度条;网关文字读数(如 `Unknown`)不在侧栏显示,只在设置页用量卡片中显示(0.7.4)。多账号时每个账号两行:账号(可截断)与完整 plan 一行,窗口、到期时间与读数一行;各账号窗口相同时窗口名只在组标题显示一次。读取复用现有用量接口,客户端 60s 缓存;自动刷新按配置的间隔向网关发一次真实刷新(网关的卡片读取只返回它上次读到的缓存、不会重读上游),页面隐藏时暂停。 | | **模型可见性与默认 effort** | 每个 provider 不设置可见性时跟随网关目录;保存过选择后只显示勾选项,新上架模型默认隐藏。每个模型可保存一个默认推理 effort,DSH 在下一次请求应用。 | | **会话级快速档** | 网关声明 `priority` 服务档的模型,输入框旁会出现标准/快速切换。选择按会话保存在 host 内存,快速档会给请求带上 `service_tier: "priority"`。 | ### 安装 ```sh dsh plugin --profile web add dsh-magpie-connector ``` 重启 DSH 并刷新页面。在 [ohmydsh](https://github.com/prgrmrwy/ohmydsh) 中也可以直接启用 local `dsh-magpie-connector` manifest 条目后重新构建。已验证 DSH `0.2.0-rc.2`、Web UI、Node.js `>=22.19`。 > **0.3.0 BREAKING 升级**:旧的单一 route `dsh-magpie-connector` 已退役。保存在它上面的会话与默认模型不再可用,请在 `Magpie (…)` 分组中重选模型。其它依赖精确 route id 的配置(例如子任务路由、出口豁免列表)需改成新的 `dsh-magpie-connector-`。 ### 配置 打开 **设置 → Magpie**。 1. 在**线路 1** 里填写**包含 `/v1`** 的网关 API 地址,例如 `http://192.168.1.20:3425/v1`,以及这条线路的 gateway key。地址、线路列表、可见性与默认 effort 保存在 `$DSH_HOME/plugins/dsh-magpie-connector/settings.json` —— key/Access 不会写入该文件,也不会被设置接口返回。 2. 需要多条线路时点「添加备用线路」,每条线路填写自己的地址与 key;用「上移/下移」调整优先级(序号 1 优先)。保存后打开设置页默认只展开当前生效线路,序号后的 4×4 绿色方块表示当前线路;点击 info 图标可查看优先级与自动回退说明。 3. 每条线路的**高级连接**里选择「直连」或「Cloudflare Access」。局域网与 Tailscale 都属于直连;Cloudflare Access 需要 HTTPS 线路,从 Access 切回直连并保存会清除该线路的两项 Access 凭据。Cloudflare 免费/Pro 套餐在源站 100 秒内没有响应时会返回 524。 4. 保存会同步模型目录;「刷新模型列表」可再次同步,插件不会定时轮询目录。 > **0.2.0 BREAKING 升级**:设置格式改为单一 `lines[]`,旧版单地址 `settings.json`(只有 `baseUrl`)与旧固定凭据引用(`MAGPIE_API_KEY` / `MAGPIE_ACCESS_*`)**不会被读取或迁移**,升级后需在设置页重新添加线路并填写每线路 key/Access。模型可见性与默认 effort 会保留;旧凭据记录可由你在 DSH credentials 中手动删除。升级前若要保留回滚能力,请备份 `settings.json` 与旧凭据引用。 还需要别的接入方式(自定义请求头、mTLS、其它零信任网关)?**欢迎提 issue 或 PR**,说明你的部署方式和网关版本。 ### 在哪里操作 | 位置 | 做什么 | |---|---| | **模型选择器** | 统一搜索覆盖分组标题、型号名和完整 id。每个分组是一个真实 route `dsh-magpie-connector-`;model id 保持网关完整 id,可见性键和默认 effort 不变。 | | **模型菜单分组** | `owned_by`(转小写,1–48 个 `a-z0-9._-` 字符)决定 route 和标题 `Magpie ()`(首字母大写)。缺失或不合法时归入 `Magpie (Other)`,不按模型名猜测。见过的归属记在 `settings.json` 的 `knownOwners`(最多 32 个;路由入口专用的 `routing` 在同一次同步中优先准入),重启后 route 立即存在,首次目录同步完成后模型才出现。归属下架后其 route 保留(空组自动隐藏)。手动清空 `knownOwners` 会让保存在被移除 route 上的选择失效。启动时若 route 注册失败(例如被别的插件占用),设置页会显示错误,排除后需重启 DSH。 | | **输入框速度控件** | 仅当前模型被网关声明为 `priority` 档时显示(当前 Magpie 上即 Codex/GPT 模型),切换模型后立即更新。悬停模型菜单可看 effort;官方选择器只显示一个 effort 值。 | | **设置 → Magpie** | 连接、接入方式、按 provider 分组的模型区(可见性复选框与默认 effort 选择器),以及该 provider 的用量卡片;每条线路卡片还有「检查线路」只读快照与「未配置」标记,保存结果只陈述当时的生效线路。 | | **用量卡片刷新** | 每张卡片有独立的「刷新」,请求 Magpie 重新读取这一个账号。网关冷启动可能没有任何卡片;此时连接面板提供「获取模型与用量」,先同步模型目录,再请 Magpie 读取全部账号一次。受限 held key 无法初始化空缓存,需要管理员先在 Magpie 中读取一次。 | ### 使用一张重置卡 ![Codex 用量卡片展开重置卡:最早到期的那张带「使用…」按钮,其余只显示到期时间](docs/reset-credits.png) 「用量限制重置」展开后逐张列出账号持有的重置卡。只有最早到期的那张带「使用…」:周口径达到 80% 之前它是灰的,确认后按两段确认消耗掉这一张。到期时间右对齐,条目与标题文字对齐。 ### 需要知道的行为 - **失败交给 DSH 重试,插件不重放请求。** 适配器声明与 `dsh-plugin-subscriptions` 相同的 `llm-retry` 策略(最多 10 次,1 秒起指数退避至 60 秒,±20% 抖动,429 时遵守 `Retry-After`)。`TIMEOUT`、`TRANSPORT`、`SERVER`、`RATE_LIMIT`、`EMPTY_RESPONSE` 会重试;401/403、额度用尽、上下文超限与其它 4xx 不重试。 - **默认输出预算为上下文压缩预留空间。** 网关的 `max_output_tokens` 是模型能力上限,不直接作为每次请求的默认预算。交给 DSH 的默认预算是 `min(能力上限, max(1, 窗口/4, 窗口/2 − 65536))`,给 DSH 的上下文压缩留出空间;显式设置的 `maxTokens` 不受影响。上下文窗口小于 104,026 token 的模型仍按同一公式计算,但不保证通过 DSH 的压缩检查。 - **只有持续静默才会结束流。** 响应头、SSE 事件和心跳都算有数据;连续 300 秒没有任何数据才以 `TIMEOUT` 结束(消息含 `MAGPIE_STREAM_TIMEOUT`)。只要网关还在发心跳,长时间推理不会被截断。 - **自动选线不会重放请求。** 每次操作开始前按序号做 TCP 可达探测并选线路;连接阶段失败只使该线路缓存失效、本次操作失败,下一次操作重新选择。生成请求从不被插件换线或重放,其它失败交给 DSH 重试策略。 - **切换线路与编辑线路语义不同。** 自动切换保留模型目录(不闪断)、清空用量卡片并以新线路重同步;编辑生效线路的地址/key/接入方式才会按换代清空目录;编辑非生效线路不影响当前目录。 - **更改连接不会中止正在进行的生成。** 新地址或新 key 会立即隐藏旧目录与旧卡片,但已 prepare 或正在运行的生成会用捕获到的旧地址与 key 跑完。用户取消与插件卸载仍会中止它们。 - **传输边界刻意收窄。** host 请求经私有 `undici` dispatcher 直连配置的网关,不经过全局代理 dispatcher;拒绝重定向;只允许 `GET /models`、`POST /responses`、`POST /chat/completions`、`GET /magpie/quotas/cards`、`POST /magpie/quotas/refresh`;从不调用 Magpie GUI 的 `/api/*` 管理接口。厂商出站代理在 Magpie 侧配置。 - **不支持:** 非空 `stop` 序列会在发请求前失败(`MAGPIE_STOP_UNSUPPORTED`),因为 Magpie 无法在所有上游协议转换中保留 stop。用量卡片本身只读;使用 Codex 重置卡是本插件唯一会写 Magpie 账号状态的操作——必须手动触发、两段确认、只用最早到期的那张,且从不调用账号管理端点。 - **密钥不会进入响应或日志。** 网关反射的文本在进入设置接口或日志之前会用当前 key 脱敏。写盘文件权限 `0600`;设置接口只报告 `configured` / `writable`。 - **界面跟随 DSH 语言。** 0.5.0 起设置页与速度菜单带中英文字典,按当前 DSH 界面语言渲染(`ctx.locale`);0.5.0 之前文案只有中文。宿主没有 locale 服务(或单测环境)时回退到中文参考集,已保存设置与行为不受影响。 ### 代码导览 入口:[index.ts](src/index.ts)。适配器与请求/流映射:[adapter.ts](src/host/adapter.ts)。路由:[routes.ts](src/host/routes.ts)。传输白名单:[transport.ts](src/host/transport.ts)。设置页:[SettingsPage.ts](src/client/SettingsPage.ts)。不含凭据的图源与仓库证据:[architecture.zh.json](docs/architecture.zh.json)。 ### 开发 在本仓库的独立检出中: ```sh npm install npm run typecheck npm test npm run build ``` 在 ohmydsh monorepo 里,在仓库根目录安装一次,后三条命令加上 `--workspace=dsh-magpie-connector`。测试使用本机 mock 网关和真实线协议库,不需要真实 key。构建产物不入库;`prepare` 与 `prepack` 都会执行 build。 ## 移除 ```sh dsh plugin --profile web remove dsh-magpie-connector ``` 重启 DSH 并刷新页面。dispose 只释放注册、计时器与连接,不删除凭据和设置。需要彻底清理时,通过 DSH credentials 管理删除各线路的 `MAGPIE_LINE__*` 凭据(以及升级前遗留的 `MAGPIE_API_KEY` / `MAGPIE_ACCESS_*`),并在确认安装版本的数据目录后删除插件设置文件。如果其它集成仍在使用某个凭据,不要删除。 在 [ohmydsh](https://github.com/prgrmrwy/ohmydsh) 中则把 manifest 条目设为 `enabled: false` 后重新构建。 ## 来源、许可与参与 本插件在 [ohmydsh](https://github.com/prgrmrwy/ohmydsh)(`packages/dsh-magpie-connector`)中持续开发,[本仓库](https://github.com/prgrmrwy/dsh-magpie-connector)是发布镜像,自动发布到 [npm](https://www.npmjs.com/package/dsh-magpie-connector) 与 [GitHub Releases](https://github.com/prgrmrwy/dsh-magpie-connector/releases)。当前行为见规范 [`openspec/specs/dsh-magpie-connector`](https://github.com/prgrmrwy/ohmydsh/blob/main/openspec/specs/dsh-magpie-connector/spec.md)。 采用 [MIT](LICENSE) 许可。`@earendil-works/pi-ai` 与 `undici` 是分别以 MIT 许可分发的依赖;鸟形图标来源与许可见 [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES)。欢迎到 [prgrmrwy/dsh-magpie-connector](https://github.com/prgrmrwy/dsh-magpie-connector/issues) 提 issue 和 PR;使用问题与配置经验欢迎发到 [Discussions](https://github.com/prgrmrwy/dsh-magpie-connector/discussions)。 如果这个插件对你有帮助,欢迎在 [GitHub](https://github.com/prgrmrwy/dsh-magpie-connector) 点个 ⭐,让更多 DSH + Magpie 用户发现它。