# @fish-under-sea/magpie-dragonapi 中文文档

规范地址：https://npmcn.com/package/%40fish-under-sea/magpie-dragonapi/

版本：1\.3\.0
npm 元数据更新时间：2026-11-12T18:33:50.043Z
中文译文更新时间：2026-11-14T20:29:16.705Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fish-under-sea/magpie-dragonapi
原文对照：https://npmcn.com/package/%40fish-under-sea/magpie-dragonapi/?lang=original
项目主页：https://github.com/Fish-under-sea/magpie-dragonapi#readme
源码仓库：https://github.com/Fish-under-sea/magpie-dragonapi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：856 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-11-10T13:05:25.622Z
- 最新版本发布：2026-11-12T18:33:49.691Z
- 近 30 天下载量：4005（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

DragonAPI for magpie:一个供应商插件,其模型,组和价格出自网站的公用/api/定价,其平衡和每个调用使用来自 sk-键,外加一个本地页面,列出市场(只读),显示使用,并且可以为一个用户提供薄荷新密钥

## 安装

```sh
npm install @fish-under-sea/magpie-dragonapi
```

也可以使用：`pnpm add @fish-under-sea/magpie-dragonapi`、`yarn add @fish-under-sea/magpie-dragonapi`、`bun add @fish-under-sea/magpie-dragonapi`

## README

# DragonAPI in Magpie

把 [DragonAPI](https://newapi.dragon3api.com/) 接进 magpie：模型广场、余额、用量，外加一个能按分组建钥匙的本地界面。

> 当前版本 **0.3.0**。只做供应商插件 + 只读看板 + 密钥管理，不做「页面里点充值」。

## 它是什么

一个独立的 magpie 插件包，同时是两样东西：

| 身份 | 作用 |
| --- | --- |
| **供应商插件** | 把站点 `/api/pricing` 的目录折成 magpie 的模型表；`sk-` 钥匙直接读余额与逐条用量；视频模型走 magpie 的 `/v1/videos` 三件套 |
| **页面插件 + 本地服务** | magpie 的插件页是 `connect-src 'none'` 的沙箱，页面自己发不出请求。所以插件起一个只监听 `127.0.0.1` 的 HTTP 服务，页面导航过去，界面由服务提供 |

## 安装

包已发布到 npm：`@fish-under-sea/magpie-dragonapi`（[npm](https://www.npmjs.com/package/@fish-under-sea/magpie-dragonapi) · [GitHub](https://github.com/Fish-under-sea/magpie-dragonapi)）。

两种装法，任选其一：

| 方式 | 怎么做 |
| --- | --- |
| **Discover（推荐）** | magpie 窗口 → Discover → Unofficial。这个仓库打了 `magpie-plugin` topic，`package.json` 里也有已提交的 `magpie.page.file`，所以会按 `magpie.name` / `magpie.summary` 列出卡片，点它安装 |
| **命令行** | `magpie plugin add @fish-under-sea/magpie-dragonapi` |

npm 拉不到时（内网、镜像抽风）：到 [Releases](https://github.com/Fish-under-sea/magpie-dragonapi/releases) 下 `fish-under-sea-magpie-dragonapi-0.3.0.tgz`，解包成目录，再 `magpie plugin add <那个目录>` —— `plugin add` 认 `path`，和从文件夹加插件是同一条路。

装好后：Settings → Plugins 里出现 **DragonAPI** 行（带一张页面），供应商列表里出现 **DragonAPI**。

> 只装不配也能看到模型广场——目录走站点公开的 `/api/pricing`，不需要任何凭据。 要看余额、读用量、建钥匙，才需要下面的钥匙与 PAT。

## 为什么不照抄 NearToken

NearToken 那套「页面里点充值、点连接」依赖两个本站没有的东西：

1.  **设备授权**（`/api/dsh/device/*`）——那是 neartoken.cc 的私有补丁，DragonAPI 没有。本站登录要过人机校验，PAT 只能在浏览器会话里创建，插件代不了。
2.  **请求头切分组**（`x-neartoken-group`）——DragonAPI 不读这个头。它的分组是**钥匙的属性**：`TokenAuth` 里 `userGroup = tokenGroup`，一把钥匙绑死一个分组。

所以这里的做法是：

-   **分组 = 账号**。一个分组一把钥匙，magpie 里就是多个账号；每个账号的模型清单只列它那一组的模型，宿主自己会把请求送到对的账号（上游 magpie 的 `AccountServes` 保证）。
-   **登录 = 贴钥匙**，或**用 PAT 让插件替你建钥匙**。

## 三步接入

### 1\. 在站点建一把钥匙

到 [控制台 → API 密钥](https://newapi.dragon3api.com/console) 新建，**选好分组**（分组决定能调哪些模型、按什么倍率计费），复制 `sk-` 开头的钥匙。

### 2\. 在 magpie 里添加账号

打开供应商列表里的 **DragonAPI**，点「添加账号」，两种方式任选：

| 方式 | 做什么 | 适合 |
| --- | --- | --- |
| **DragonAPI API Key** | 把 `sk-…` 粘进去 | 最常见；一把钥匙一个分组 |
| **用访问令牌按分组自动建钥匙** | 插件调站点 API 建一把新钥匙并直接绑成账号 | 想少跑一趟控制台 |

第二种要先在插件页面里填**访问令牌（PAT）**，见下一节。它在 magpie 里表现为第二条登录方式，选完分组就自动建好并绑上。

### 3\. 需要多个分组就重复第 2 步

每个分组加一个账号。magpie 的供应商编辑器里会列出多个账号，每个账号只带它那一组的模型。

## 访问令牌（PAT）

建钥匙、看钥匙列表、看账户资料都要 PAT。它**只能在浏览器里创建**：

1.  登录控制台 → 头像 → **安全** → **访问令牌** → 新建；
2.  勾选权限：
    -   `profile:read` —— 读账户与可用分组（**建钥匙必填**）
    -   `api_key:read` —— 读钥匙列表
    -   `api_key:write` —— 建钥匙 / 删钥匙
    -   `api_key:reveal` —— 看钥匙完整明文
    -   `usage:read` —— 读用量流水
    -   `wallet:read` —— 读订阅、套餐与邀请（只读展示）
3.  复制 `nap-` 开头的令牌，粘到插件页面的「访问令牌」页。

> 旧版访问令牌已停用（站点返回 `ACCESS_TOKEN_LEGACY_RETIRED`），必须用新的 `nap-` 令牌。

**PAT 存在本地**：`<magpie 配置目录>/dragonapi-state.json`，权限 0600。它必须明文存——每次建钥匙都要用。文件里**不存任何 `sk-` 钥匙明文**，那些由 magpie 自己的 `plugin-auth.json` 保管。

保存 PAT 时插件会并行探四个只读端点（账户资料 / 钥匙列表 / 用量 / 订阅），每次最多等待 12 秒：

| 情况 | 行为 |
| --- | --- |
| 四个端点都说令牌无效（401/403） | 拒收，并说清是权限不够还是令牌失效 |
| 能用一个、缺另一个 | **照样存下**，提示缺哪一格、哪些功能会失败（例如只缺 `profile:read` 时建钥匙会失败，但读用量照常） |
| 站点连不上 / 返回验证页 | **照样存下**，标成「未验证」，稍后刷新即可再确认 |
| 写不进状态文件 | 直接报错并给出文件路径——不会出现「提示已保存、重启后消失」 |

## 界面里有什么

四个标签页：账户概览 / 模型广场 / 使用日志 / 访问令牌。整页限高——页头、标签、页脚固定不动， 超长内容在面板或卡片里滚动；账户页统一面板滚动，确保订阅、推荐和密钥始终可达。

| 页 | 内容 |
| --- | --- |
| **模型广场** | 左侧筛选（14 个分组带倍率与数量、11 家厂商带品牌图标）+ 右侧搜索、类型分段、分组横幅。**一张卡 = 一个模型**：站点把同一个模型在多个分组里各卖一份（189 行 / 125 个模型），卡片把它的**全部分组**都列出来（不省略、不折叠成「+N」），价格给跨分组的**区间**（如 `$0.12–0.32/M`）而不是只报最低价。卡内含供应商图标、名称/厂商、说明、计费方式、输入·输出·缓存价、分组、端点。**纯展示，没有启用/停用开关**——本站做不到 NearToken 那种按分组启停，所以这里不给假开关，也不伪造健康度数据 |
| **模型详情** | 点卡片上的「详情」打开（居中面板）：价签 → 概览 → 计费方式（把 `p/c/cr` 系数、`service_tier` 倍率翻成中文）→ 每一档的实际单价 → 按用量单价 → **按分组定价**（同型号横向比价，当前分组高亮）。站点原文的计费表达式收在折叠块里 |
| **账户概览** | 账户卡（余额、已用、绑定情况）+ 数据概览（日/周/月切换、消耗柱状图、按模型的调用与费用）+ **推荐计划**（待确认 / 总收入 / 邀请，链接可复制、累计奖励可转入余额）+ **API 密钥**表格（名称、状态、密钥、额度、分组、绑定、时间、过期、操作） |
| **新建密钥** | 从「+ 创建 API 密钥」打开的居中弹窗：基本信息（名称、分组）与额度设置（无限配额开关、额度），样式与模型详情面板一致 |
| **使用日志** | 对标 NearToken 的详细程度：日/周/月 + 模型名 / 分组 / 类型 / 令牌名 / 请求 ID 筛选，用量·请求·Token 统计条（带隐私遮罩），明细 9 列（时间、分组、模型、费用、请求体大小、流式吞吐、Token/缓存、首字·耗时、详情），分页与「载入更多」 |
| **访问令牌** | 填入/清除 PAT，说明需要哪些权限，并显示实际验到的 scope；健康与诊断记录 |

预览时可以加 `?demo` 用虚拟数据把四个页面都填满（订阅示例包括不限量、取消、到期与超额）。

仅设置 PAT、没有绑定 `sk-` 也能读取账户钱包与账户级用量。`profile:read` 用于账户资料与钱包余额，`usage:read` 用于账户日志；有 PAT 时默认只统计账户日志，不再叠加绑定钥匙日志。钱包余额与钥匙额度分别展示，不求和。

账户概览内置只读「订阅套餐」：我的订阅、到期、下次重置、额度与进度，以及站点返回的套餐列表。需要 `wallet:read`，不购买、不支付、不修改扣费偏好。套餐标价保留原币，quota 按站点参数换算。日志只取最近一批，页面会明确标注不完整，不能当作全量账单。

## 价格怎么算

站点有两种计费，插件分开处理，**算不准就明说「价格未知」，不编数字**：

| 计费方式 | 怎么折 | 可信度 |
| --- | --- | --- |
| 倍率计费 | `模型倍率 × 分组倍率 × 2` 美元/百万 token | 准 |
| 表达式计费（对话） | 从 `billing_expr` 取 `tier(...)` 里的 `p` / `c` / `cr` / `cc` 系数 | 准（多档时标注是哪一档） |
| 表达式计费（视频） | 取 `u("seconds")` / `u("resolution")` 的单价，给区间 | 区间价，实际以控制台为准 |
| 解析不出来 | 显示「价格未知」+ 原因 | —— |

`auto` 分组**不算单价**——它的费率取决于命中的通道，站点自己也这么说。

## 已知限制

| 限制 | 原因 | 影响 |
| --- | --- | --- |
| 页面里不能直接绑账号 | 页面跑在沙箱里，写不了 magpie 的账号表 | 绑定只能走 magpie 的「添加账号」；插件用第二条登录方式把「建钥匙 + 绑定」合成一步 |
| 没有设备授权 | 站点没有这个端点 | 每次都要贴钥匙，或先用 PAT 让插件建 |
| 一把钥匙一个分组 | 分组是钥匙的属性 | 多分组 = 多账号，账号列表会变长 |
| 视频按秒计费只能给区间 | 价格随分辨率/规格变 | 实际扣费以控制台为准 |
| `priceRate` 未验证 | 站点前端还有一个「充值价系数」，拿不到登录态确认不了 | 单价可能整体差一个系数；流水里的实际费用不受影响 |
| 独立服务拿不到绑定钥匙明文 | 钥匙只在插件进程内存里 | 钥匙额度显示「—」；已设置 PAT 的账户钱包与用量仍可读取 |

## 独立启动（插件宿主起不来时）

```powershell
node serve.mjs
```

会在 `127.0.0.1:3517` 起同一个服务，界面可用（绑定钥匙额度除外；PAT 账户钱包和日志可读取）。如果插件已经在跑，它会提示并退出，不会抢端口。

## 开发

```bash
node --test "tests/*.test.mjs"
```

测试用站点 2026-11-10 的真实快照（[证据-站点定价快照-2026-11-10.json](https://npmcn.com/package/%40fish-under-sea/magpie-dragonapi/%E8%AF%81%E6%8D%AE-%E7%AB%99%E7%82%B9%E5%AE%9A%E4%BB%B7%E5%BF%AB%E7%85%A7-2026-11-10.json)）当夹具，站点改了写法就会被发现。

### 本地实时预览（改界面时用这个）

```bash
node dev.mjs
```

```bash
node dev.mjs --sandbox
```

```bash
node dev.mjs --upstream http://127.0.0.1:3517
```

改 `ui/` 里任何文件（html / css / js）都会自动整页刷新，不需要装 magpie，也不用重装插件。

它起两个进程内的服务：内部服务（`3672`）是真的 `lib/service.mjs`，带真实站点目录与 `/api/*`； 开发服务（`3671`）只负责发静态文件、注入热刷新脚本、把 `/api/*` 反代过去。所以界面走的 还是生产那条请求路径，只是文件每次从磁盘现读。

**两种模式都要看一遍**，尤其是改请求、存储、导航的时候：

| 模式 | 地址 | 什么时候用 |
| --- | --- | --- |
| 顶层直开 | `/?theme=dark` | 日常改样式最快，devtools 干净 |
| 沙箱 iframe | `/__sandbox?theme=dark` | 和 magpie 里一致：`sandbox="allow-scripts"`，安全源不透明（`localStorage` 会抛 `SecurityError`） |

这个差异造成过真实事故：顶层一切正常，装进 magpie 后所有接口都「连不上本地服务」—— 不透明源里相对路径的 `fetch` 会被判 `Failed to fetch`。沙箱模式就是为了提前看见这类问题。

默认访问 `http://127.0.0.1:3671/?theme=dark`。默认独立模式写 `.dev-state/`（含 PAT，已进 `.gitignore`），与插件实际状态分离。只有 `--upstream` 模式代理到指定插件服务，才操作那个服务实际使用的状态；该模式不启动内部服务。

Node 22 若不支持 npm 脚本的测试隔离参数，可直接运行：

```bash
node --test "tests/*.test.mjs"
```

目录结构：

```text
index.mjs               供应商插件入口：config / auth / provider.models + 起本地服务
lib/site.mjs            站点客户端（sk- 与 PAT 两条通道分开，错误带 status/kind）
lib/pricing.mjs         两种计费规则的解析与降级；详情页用的 prices / multipliers / usageRows
lib/catalog.mjs         /api/pricing → magpie 模型表（分组×模型）
lib/catalog-source.mjs  目录的唯一所有者：缓存、条件请求、刷新、健康记录
lib/status-source.mjs   站点参数的唯一所有者：缓存与降级
lib/usage.mjs           日志解析、汇总、窗口
lib/store.mjs           本地状态（PAT、账号元数据），原子写 0600，写失败返回结构化结果
lib/service.mjs         本地 HTTP 服务 + 全部 API（只管呈现，不缓存）
page/                   带路页（把自己导航到本地服务）
ui/                     真正的界面
ui/model-agg.js         跨分组聚合（一张卡 = 一个模型）：纯函数、可单测
ui/vendor-icons/        厂商品牌图标（来自同期 magpie-neartoken 仓库，MIT）
serve.mjs               独立启动
dev.mjs                 本地实时预览（不打包进 npm）
```

### 两个「源」为什么单独存在

目录和站点参数各有一个 `*-source.mjs`，是因为它们**曾经各被缓存了两份**（插件一份、服务一份）， 结果页面点「刷新」刷的是另一份缓存，按钮点了没反应。现在只有一处持有缓存， `lib/service.mjs` 通过注入拿到它们，`tests/refresh.test.mjs` 钉住这条链路。

## 许可

MIT

## 常见问题

### @fish-under-sea/magpie-dragonapi 是什么？

DragonAPI for magpie:一个供应商插件,其模型,组和价格出自网站的公用/api/定价,其平衡和每个调用使用来自 sk-键,外加一个本地页面,列出市场\(只读\),显示使用,并且可以为一个用户提供薄荷新密钥

### 如何安装 @fish-under-sea/magpie-dragonapi？

在项目目录运行 npm install @fish-under-sea/magpie-dragonapi，或使用 pnpm add / yarn add / bun add。

### @fish-under-sea/magpie-dragonapi 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fish-under-sea\_\_magpie-dragonapi 是否存在。

### @fish-under-sea/magpie-dragonapi 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fish-under-sea/magpie-dragonapi 可以商用吗？

@fish-under-sea/magpie-dragonapi 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fish-under-sea/magpie-dragonapi 的下载量有多少？

根据 npm 官方下载统计，@fish-under-sea/magpie-dragonapi 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,005 次，日均约 134 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fish-under-sea/magpie-dragonapi 还在维护吗？

最新版本 1\.3\.0 发布于 2026/11/13（2 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/11/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。