@fish-under-sea/magpie-neartoken 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +21 -84
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,8 @@
1
1
  # NearToken in Magpie
2
2
 
3
- 把 [NearToken](https://neartoken.cc) 接进 [magpie](https://github.com/yetone/magpie) 的一个**单包插件**：侧边栏「插件」一组里多一个 NearToken 页面，负责登录绑定、余额与代金券、消耗看板和充值；模型与路由交回 magpie 自己的供应商页。
3
+ 把 [NearToken](https://neartoken.cc) 接进 [magpie](https://github.com/yetone/magpie) 的**单包插件**：侧边栏「插件」一组里多一个 NearToken 页面，负责登录绑定、余额与代金券、消耗看板和充值；模型与路由交回 magpie 自己的供应商页。
4
4
 
5
- 它不预装、不编进 magpie 的安装包，也不占用 magpie 的内置页面：`@fish-under-sea/magpie-neartoken` 就是一个可以单独下载、单独安装、单独卸载的包。
6
-
7
- 这个仓库是一次**迁移**，不是兼容层：原先是 DSH（DeepSeek Harness）里的 `dsh-neartoken`，现在按 magpie 的插件体系重做——页面跑在 magpie 的窗口里，出站请求由 magpie 本体代发，供应商挂在 `providers.json` 上，magpie 的模型选择、路由、失败切换照常工作。
5
+ 它不预装、不编进 magpie 的安装包，也不占用 magpie 的内置页面：`@fish-under-sea/magpie-neartoken` 就是一个可以单独下载、单独安装、单独卸载的包。**这个仓库只放插件本身**，不含 magpie 的源码、补丁或改动。
8
6
 
9
7
  ## 下载
10
8
 
@@ -12,7 +10,7 @@
12
10
  | --- | --- |
13
11
  | npm（推荐） | `magpie plugin add @fish-under-sea/magpie-neartoken` |
14
12
  | GitHub 仓库 | `magpie plugin add github:Fish-under-sea/magpie-neartoken` |
15
- | 离线包 | 在 [Releases](https://github.com/Fish-under-sea/magpie-neartoken/releases) 下载 `magpie-neartoken-<版本>.tgz`，解包后把目录添进「插件」页 |
13
+ | 离线包 | 在 [Releases](https://github.com/Fish-under-sea/magpie-neartoken/releases) 下载 `fish-under-sea-magpie-neartoken-<版本>.tgz`，解包后把目录添进「插件」页 |
16
14
 
17
15
  装完在 magpie 的「插件」页打开 NearToken。卸载就是删掉这个包，magpie 的其它部分不受影响。
18
16
 
@@ -21,23 +19,22 @@
21
19
  | 页面上的事 | 数据从哪来 |
22
20
  | --- | --- |
23
21
  | 连接 NearToken | 站点的设备授权（RFC 8628 形状）：页面显示确认码，你在站点自己的页面登录并批准 |
24
- | 余额、已用、代金券 | `GET /api/dsh/device/wallet`，用插件签下来的密钥读 |
25
- | 消耗看板（日 / 周 / 月） | `GET /api/dsh/device/usage?range=…`，按模型堆叠 |
26
- | 充值 | `GET /api/dsh/device/topup/info` 与 `POST /api/dsh/device/topup`，支付页交给系统浏览器 |
27
- | 模型列表 | `GET /api/pricing`，写进 magpie 的供应商目录 |
28
-
29
- 页面本身一条 `fetch` 都发不出去（它跑在 `connect-src 'none'` 的沙箱帧里），所以上面每一件事都经 `magpie.call` 回到宿主执行。页面永远拿不到密钥：密钥只存在 `providers.json` 的 `neartoken` 那一条里。
22
+ | 余额、已用、代金券 | 站点钱包端点，用连接签下来的密钥读 |
23
+ | 消耗看板（日 / 周 / 月） | 站点用量端点，按模型堆叠 |
24
+ | 充值 | 站点充值端点，支付页交给系统浏览器 |
25
+ | 模型目录 | 站点 `/api/pricing`，写进 magpie 的 `neartoken` 供应商 |
30
26
 
31
- **账号只有一个。** 不支持手动粘贴密钥，也不支持多账号：连接由页面发起，断开在页面点，别的地方没有第二入口。
27
+ **账号只有一个。** 不支持手动粘贴密钥，也不支持多账号：连接由页面发起，断开在页面点。
32
28
 
33
- ## 宿主通道
29
+ 登录全在站点自己页面上完成——密码、GitHub、Discord、LinuxDo、OIDC、Telegram、微信、Passkey 都走站点原生流程；插件不收密码，也不存密码。
34
30
 
35
- `neartoken:*` 这几条调用属于**宿主能力**，不在插件包里：页面能做的每一次出站请求，都得由 magpie 本体执行。用到的是 magpie 的插件页调用通道（`POST /api/plugin-pages/call`），按插件 `package.json` 的 `magpie.calls` 白名单放行。
36
-
37
- 因此有两种 magpie：
31
+ ## 页面怎么用
38
32
 
39
- - **带 neartoken 通道的构建**：页面全套功能可用。补丁与构建脚本在本仓库 `patches/`、`host/`、`tools/` 下，见[自己给 magpie 加通道](#自己给-magpie-加通道)。
40
- - **官方原版**：页面照常出现、照常读得到站点与连接状态，但一点「连接」就会说明「这个 magpie 还没有插件页的调用通道」。不会静默失败，也不会假装成功。
33
+ 1. 装上包，侧边栏「插件」→「NearToken」。
34
+ 2. 点「连接 NearToken」，页面给一个确认码。
35
+ 3. 点「打开确认页」，用平时的方式登录站点，确认码一致后批准。
36
+ 4. 批准后自动接入：余额、代金券、看板、充值一次到齐；模型同时出现在 magpie 的供应商页。
37
+ 5. 断开连接会撤销站点上这把密钥，并删掉 magpie 里这一条供应商。
41
38
 
42
39
  ## 页面调用（`magpie.calls`）
43
40
 
@@ -52,85 +49,25 @@
52
49
  | `neartoken:usage` | `{range: day\|week\|month}` 的用量窗口 |
53
50
  | `neartoken:topup` | 不带 `amount` 读档位；带 `amount` 与 `paymentMethod` 下单并打开支付页 |
54
51
 
55
- `package.json` 必须原样声明这张表：magpie 按它放行，宿主再按同一份声明校验一次。
56
-
57
- ## 和 dsh-neartoken 的关系：只共用站点，不混用标识
58
-
59
- 这不是 dsh-neartoken 的兼容层，也没有复用它的代码、配置或令牌。两边的连接方式不一样：
60
-
61
- | | dsh-neartoken | 本插件 |
62
- | --- | --- | --- |
63
- | 宿主 | DSH | magpie |
64
- | 请求由谁发 | DSH Host | magpie 本体（`/api/plugin-pages/call`） |
65
- | 站点确认页上的称呼 | `DSH 插件` | `magpie` |
66
- | 请求的 UA | DSH 自己的 | `magpie-neartoken` |
67
- | 令牌 | 站点写的 `DSH` | 站点按 `magpie` 写 |
68
- | 供应商 | DSH 的 `neartoken` provider | magpie 的 `neartoken` 供应商 |
69
-
70
- 共用的只有站点已经实现的那批设备授权端点（`/api/dsh/device/authorize`、`/token`、`/revoke`）与钱包、用量、充值端点——那是站点自己的接口，不是哪一家的实现。作者的 `DSH` 标识原样留着：他的令牌、日志和授权记录仍然只认 `DSH`，我们的连接写 `magpie`，两边在站点后台一眼分得开。
71
-
72
- 站点对「只有 DSH 授权签发的钥匙能充值」这件事回的是 `DSH_TOKEN_REQUIRED`，那是站点的历史码；插件只按它分支，对外一律说「这把密钥不是本插件登录签发的」。
73
-
74
- ## 页面怎么用
75
-
76
- 1. 装上包，侧边栏「插件」→「NearToken」。
77
- 2. 点「连接 NearToken」，页面给一个确认码。
78
- 3. 点「打开确认页」，用平时的方式登录站点——密码、GitHub、Discord、LinuxDo、OIDC、Telegram、微信、Passkey 都在站点自己的页面上完成。
79
- 4. 批准后自动接入：余额、代金券、看板、充值一次到齐；模型同时出现在 magpie 的供应商页。
80
- 5. 断开连接会撤销站点上这把密钥，并删掉 magpie 里这一条供应商。
81
-
82
- ## 排错
83
-
84
- | 画面 / 报错 | 原因 | 怎么办 |
85
- | --- | --- | --- |
86
- | `NearToken doesn't ask for neartoken:state` | 宿主补丁的 `PageCalls` 里没有这八条。只写在 `package.json` 里会被 `callsKeeping` 静默丢掉，窗口那边就只剩一句「没问过」 | 重新打 `patches/magpie-neartoken.patch`（0.1.4 起含 `internal/plugin/page.go` 的改动），再重启 magpie |
87
- | 「这个 magpie 还没有插件页的调用通道」 | 官方原版 magpie，没有插件页调用通道 | 同上，需要带通道的构建 |
88
- | 插件列表里是灰书页 / 没有图标 | 包里的 `page/icon.png` 没装到 | 用 npm 装或 release 的 tgz，别只拷 `page/index.html` |
89
- | 页面空白，10 秒后变成「停止工作」 | 页面没应答 hello | 确认 magpie 版本，或看窗口日志 |
90
-
91
- 自证一遍（不用开窗口）：`magpie web` 会打印带一次性 key 的链接；用它换 cookie 后请求 `/api/plugin-pages`，那个页面的 `calls` 里应当有八条 `neartoken:*`。
52
+ 页面跑在 magpie 的沙箱帧里（`connect-src 'none'`），自己发不出网络请求，所以上面每一件事都经 `magpie.call` 由 magpie 本体代发。这几条调用属于宿主能力，由 magpie 侧提供；插件这边只负责声明它们，并按返回的数据画页面。
92
53
 
93
54
  ## 仓库结构
94
55
 
95
- 仓库根就是那个 npm 包（`package.json` 在根，`npm pack` 直接可用）；宿主的源码与脚本在旁边的目录里，不进包。
56
+ 仓库根就是那个 npm 包（`package.json` 在根，`npm pack` 直接可用）：
96
57
 
97
58
  ```
98
59
  /
99
60
  ├── package.json 插件清单：magpie.page / magpie.icon / magpie.calls
100
61
  ├── page/ 页面本体：index.html · app.js · style.css · icon.svg · icon.png
101
62
  ├── LICENSE
102
- ├── host/internal/ 宿主侧实现的源码（设备授权、钱包、用量、充值、目录）
103
- ├── patches/ 叠在 FISH 的 magpie 补丁之上的增量
104
- ├── tools/ 构建与打补丁的脚本
105
- └── docs/ 设计与契约
106
- ```
107
-
108
- ## 自己给 magpie 加通道
109
-
110
- 前提：magpie 源码已经是 `v0.1.2732` + FISH 的 `magpie-v0.1.2732+fish.9.patch`（那一版已经带了插件页调用通道），本仓库的补丁只往上再叠三件事：
111
-
112
- 1. `internal/neartoken`：设备授权、钱包、用量、充值、目录，以及把站点挂成供应商；
113
- 2. `internal/plugin/page.go` 的 `PageCalls`：补上 `neartoken:*` 八条——**两处都要列**，只写在 `package.json` 里会被 `callsKeeping` 静默丢掉，页面只会看到「NearToken doesn't ask for neartoken:state」；
114
- 3. `internal/gui/pluginpagecall.go` 里多一条 `neartoken:` 前缀的分派。
115
-
116
- ```powershell
117
- git -C ..\upstream-2732 apply patches\magpie-neartoken.patch
118
- pwsh -File tools\build.ps1 -Upstream ..\upstream-2732 -Out dist\magpie.exe
119
- ```
120
-
121
- 打完之后可以自证一遍：`magpie web` 打印的链接带一次性 key，用它换 cookie 后请求 `/api/plugin-pages`，那个页面的 `calls` 里应当有八条 `neartoken:*`；`POST /api/plugin-pages/call` 带 `{"name":"neartoken:state"}` 应当回 `configured:false`。
122
-
123
- `internal/neartoken` 的测试用 `httptest` 起一个假站点，不碰网络：
124
-
125
- ```powershell
126
- go test ./internal/neartoken/ -count=1
63
+ └── README.md
127
64
  ```
128
65
 
129
66
  ## 设计取舍
130
67
 
131
- - **登录用设备授权，不收密码。** 站点自己的登录页负责认证与 2FA，插件只轮询结果。插件签下来的密钥就是站点的一张普通令牌，与 `Authorization: Bearer` 完全一致。
132
- - **模型选择不重做。** magpie 已经有供应商、模型、路由、失败切换这一整套；插件只负责把站点目录写进供应商，剩下的交回窗口。
133
- - **金额口径只有一份。** 汇率来自 `/api/status` 的 `quota_per_unit` 与 `usd_exchange_rate`，钱包、看板、代金券都用它折算，三处数字不会互相打架。
68
+ - **登录用设备授权，不收密码。** 站点自己的登录页负责认证与 2FA，插件只轮询结果。连接签下来的密钥就是站点的一张普通令牌。
69
+ - **模型选择不重做。** magpie 已经有供应商、模型、路由、失败切换这一整套；插件只把站点目录写进供应商，剩下的交回窗口。
70
+ - **金额口径只有一份。** 汇率来自站点状态接口，钱包、看板、代金券都用它折算，三处数字不会互相打架。
134
71
  - **读不到就说不知道。** 站点没有用量端点时页面写「站点未提供用量统计」，不画一张空图——空图会被读成「这段时间没有消耗」。
135
72
 
136
73
  ## 许可
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fish-under-sea/magpie-neartoken",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "NearToken for magpie: sign in to neartoken.cc from a page of magpie's own window, see the balance, vouchers and spending, top up without leaving it, and let magpie pick the models as it does for any provider.",
5
5
  "type": "module",
6
6
  "license": "MIT",