@huui/cdx-switcher 1.8.7 → 1.9.0

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 (8) hide show
  1. package/API.md +239 -0
  2. package/README.md +17 -12
  3. package/account-switch-BDEmlyn5.mjs +1536 -0
  4. package/api.d.mts +129 -0
  5. package/api.mjs +164 -0
  6. package/cdx.d.mts +105 -0
  7. package/cdx.mjs +7 -1524
  8. package/package.json +8 -1
package/API.md ADDED
@@ -0,0 +1,239 @@
1
+ # cdx API 接口文档
2
+
3
+ 从 `1.9.0` 起，`@huui/cdx-switcher` 提供受限的脚本调用接口，用于读取本机已配置账号的状态、当前账号用量，以及按标签切换账号。
4
+
5
+ 此接口不提供登录、重新登录、OAuth 流程、密钥库读写或令牌读取能力。
6
+
7
+ ## 导入方式
8
+
9
+ ```js
10
+ import {
11
+ listAccounts,
12
+ getCurrentAccount,
13
+ getCurrentAccountUsage,
14
+ switchNextAccount,
15
+ switchToAccount,
16
+ } from "@huui/cdx-switcher/api";
17
+ ```
18
+
19
+ 所有接口均为异步函数，返回 `Promise<CdxApiResult<T>>`。不会写入终端、不会调用 `process.exit()`；调用方应自行处理返回值。
20
+
21
+ ## 通用返回结构
22
+
23
+ ### 成功
24
+
25
+ ```ts
26
+ {
27
+ ok: true;
28
+ data: T;
29
+ }
30
+ ```
31
+
32
+ | 字段 | 类型 | 含义 |
33
+ | --- | --- | --- |
34
+ | `ok` | `true` | 表示请求成功。 |
35
+ | `data` | `T` | 当前接口的成功数据，具体结构见各接口说明。 |
36
+
37
+ ### 失败
38
+
39
+ ```ts
40
+ {
41
+ ok: false;
42
+ error: {
43
+ code: CdxApiErrorCode;
44
+ message: string;
45
+ retryable: boolean;
46
+ };
47
+ }
48
+ ```
49
+
50
+ | 字段 | 类型 | 含义 |
51
+ | --- | --- | --- |
52
+ | `ok` | `false` | 表示请求失败。 |
53
+ | `error.code` | `CdxApiErrorCode` | 供程序稳定判断的错误代码；不要依赖 `message` 文本做分支。 |
54
+ | `error.message` | `string` | 适合日志或人工排查的脱敏说明。 |
55
+ | `error.retryable` | `boolean` | 为 `true` 时，可采用退避策略后重试；为 `false` 时通常需要调整配置、标签或重新登录。 |
56
+
57
+ ### 错误代码
58
+
59
+ | 错误代码 | 含义 | 是否建议重试 |
60
+ | --- | --- | --- |
61
+ | `CONFIGURATION_ERROR` | 无法读取或解析 cdx 账号配置。 | 否 |
62
+ | `CURRENT_ACCOUNT_UNAVAILABLE` | 当前账号索引无效，或当前账号不存在。 | 否 |
63
+ | `ACCOUNT_LABEL_REQUIRED` | 指定切换时未提供非空标签。 | 否 |
64
+ | `ACCOUNT_LABEL_NOT_FOUND` | 未找到指定标签对应的账号。 | 否 |
65
+ | `ACCOUNT_LABEL_DUPLICATED` | 多个账号使用了相同标签，无法确定切换目标。 | 否 |
66
+ | `SECRET_STORE_UNAVAILABLE` | 系统凭据库无法初始化。 | 否 |
67
+ | `CREDENTIAL_UNAVAILABLE` | 无法读取目标账号凭据，或无法写入目标工具认证文件。 | 是 |
68
+ | `AUTH_FAILED` | 当前账号认证失效，需要通过 CLI 登录或重新登录。 | 否 |
69
+ | `USAGE_UNAVAILABLE` | 上游用量接口不可用或返回格式无法解析。 | 是 |
70
+ | `NETWORK_ERROR` | 查询用量时发生网络错误。 | 是 |
71
+
72
+ ## 公共数据类型
73
+
74
+ ### `AccountSummary`
75
+
76
+ 账号的安全摘要；不会包含账号邮箱、内部账号 ID、访问令牌或刷新令牌。
77
+
78
+ | 字段 | 类型 | 含义 |
79
+ | --- | --- | --- |
80
+ | `label` | `string \| null` | 使用 `cdx label` 设置的账号标签；未设置时为 `null`。 |
81
+ | `displayName` | `string` | 供界面与日志使用的安全显示名称；未设置标签时显示为“未命名账号 N”。 |
82
+ | `isCurrent` | `boolean` | 该账号是否为当前已写入 Codex、OpenCode 与 Pi 认证文件的账号。 |
83
+
84
+ ### `UsageWindowData`
85
+
86
+ 单个用量限额周期的规范化数据。
87
+
88
+ | 字段 | 类型 | 含义 |
89
+ | --- | --- | --- |
90
+ | `kind` | `"primary" \| "secondary"` | 限额周期类别；分别表示主周期和辅助周期。 |
91
+ | `usedPercent` | `number` | 当前周期已使用百分比。 |
92
+ | `remainingPercent` | `number` | 当前周期剩余百分比，按 `100 - usedPercent` 计算。 |
93
+ | `limitWindowSeconds` | `number` | 限额周期总时长，单位为秒。 |
94
+ | `resetsAt` | `string` | 下次重置的 ISO 8601 时间。 |
95
+ | `resetsAtUnixMs` | `number` | 下次重置的 Unix 时间戳，单位为毫秒。 |
96
+ | `resetsInMs` | `number` | 相对于 `checkedAt` 的剩余时间，单位为毫秒；已到重置时间时为 `0`。 |
97
+
98
+ ## 接口
99
+
100
+ ### `listAccounts()`
101
+
102
+ 用途：查看所有已配置账号的安全摘要与当前启用状态，适合守护程序启动时建立账号视图。
103
+
104
+ | 参数 | 类型 | 是否必填 | 含义 |
105
+ | --- | --- | --- | --- |
106
+ | 无 | - | - | 此接口不接收参数。 |
107
+
108
+ 返回类型：`Promise<CdxApiResult<AccountListData>>`
109
+
110
+ 成功时的 `data`：
111
+
112
+ | 字段 | 类型 | 含义 |
113
+ | --- | --- | --- |
114
+ | `accounts` | `AccountSummary[]` | 已配置账号列表，顺序与 cdx 配置中的顺序一致。 |
115
+
116
+ ```js
117
+ const result = await listAccounts();
118
+ if (result.ok) {
119
+ console.log(result.data.accounts);
120
+ }
121
+ ```
122
+
123
+ ### `getCurrentAccount()`
124
+
125
+ 用途：查看当前已启用、且已写入目标开发工具认证文件的账号。
126
+
127
+ | 参数 | 类型 | 是否必填 | 含义 |
128
+ | --- | --- | --- | --- |
129
+ | 无 | - | - | 此接口不接收参数。 |
130
+
131
+ 返回类型：`Promise<CdxApiResult<CurrentAccountData>>`
132
+
133
+ 成功时的 `data`：
134
+
135
+ | 字段 | 类型 | 含义 |
136
+ | --- | --- | --- |
137
+ | `account` | `AccountSummary` | 当前启用账号的安全摘要。 |
138
+
139
+ ```js
140
+ const result = await getCurrentAccount();
141
+ if (result.ok) {
142
+ console.log(result.data.account.displayName);
143
+ }
144
+ ```
145
+
146
+ ### `getCurrentAccountUsage()`
147
+
148
+ 用途：查询当前启用账号的用量周期、已用比例与下次重置时间。适合自动切换守护程序据此决定下一次轮询时间或风险阈值。
149
+
150
+ | 参数 | 类型 | 是否必填 | 含义 |
151
+ | --- | --- | --- | --- |
152
+ | 无 | - | - | 此接口不接收参数。 |
153
+
154
+ 返回类型：`Promise<CdxApiResult<CurrentAccountUsageData>>`
155
+
156
+ 成功时的 `data`：
157
+
158
+ | 字段 | 类型 | 含义 |
159
+ | --- | --- | --- |
160
+ | `account` | `AccountSummary` | 被查询的当前启用账号。 |
161
+ | `checkedAt` | `string` | 本次查询完成时的 ISO 8601 时间。 |
162
+ | `planType` | `string \| null` | 账号套餐类型；上游未提供时为 `null`。 |
163
+ | `windows` | `UsageWindowData[]` | 主周期与辅助周期的用量数据；上游未提供某周期时不会包含对应元素。 |
164
+ | `credits` | `CreditsData \| null` | 账号额度信息；上游未提供时为 `null`。 |
165
+
166
+ `credits` 的字段：
167
+
168
+ | 字段 | 类型 | 含义 |
169
+ | --- | --- | --- |
170
+ | `hasCredits` | `boolean` | 账号是否拥有可用额度。 |
171
+ | `unlimited` | `boolean` | 额度是否不受余额限制。 |
172
+ | `balance` | `number \| null` | 可用余额；上游未提供时为 `null`。 |
173
+
174
+ ```js
175
+ const result = await getCurrentAccountUsage();
176
+ if (!result.ok) {
177
+ console.error(result.error.code, result.error.message);
178
+ } else {
179
+ for (const window of result.data.windows) {
180
+ console.log(window.kind, window.usedPercent, window.resetsAt);
181
+ }
182
+ }
183
+ ```
184
+
185
+ ### `switchNextAccount()`
186
+
187
+ 用途：按 cdx 配置中的账号顺序切换到下一个账号。只有一个账号时会重新写入该账号的认证文件，`changed` 为 `false`。
188
+
189
+ | 参数 | 类型 | 是否必填 | 含义 |
190
+ | --- | --- | --- | --- |
191
+ | 无 | - | - | 此接口不接收参数。 |
192
+
193
+ 返回类型：`Promise<CdxApiResult<AccountSwitchData>>`
194
+
195
+ ### `switchToAccount(input)`
196
+
197
+ 用途：按用户设置的唯一标签切换到指定账号。此接口不接受邮箱、内部账号 ID 或凭据。
198
+
199
+ 参数 `input`：
200
+
201
+ | 字段 | 类型 | 是否必填 | 含义 |
202
+ | --- | --- | --- | --- |
203
+ | `label` | `string` | 是 | 目标账号标签。标签不存在时返回 `ACCOUNT_LABEL_NOT_FOUND`；重复时返回 `ACCOUNT_LABEL_DUPLICATED`。 |
204
+
205
+ 返回类型：`Promise<CdxApiResult<AccountSwitchData>>`
206
+
207
+ ```js
208
+ const result = await switchToAccount({ label: "备用账号" });
209
+ if (result.ok) {
210
+ console.log(`已切换到 ${result.data.currentAccount.displayName}`);
211
+ }
212
+ ```
213
+
214
+ ### `AccountSwitchData`
215
+
216
+ `switchNextAccount()` 与 `switchToAccount()` 成功时的 `data` 结构：
217
+
218
+ | 字段 | 类型 | 含义 |
219
+ | --- | --- | --- |
220
+ | `previousAccount` | `AccountSummary` | 切换前当前启用账号。 |
221
+ | `currentAccount` | `AccountSummary` | 切换后当前启用账号。 |
222
+ | `changed` | `boolean` | 是否切换到另一个账号。 |
223
+ | `switchedAt` | `string` | 切换完成时的 ISO 8601 时间。 |
224
+ | `targets` | `AuthTargetWriteData` | 各目标工具认证文件的更新状态。 |
225
+
226
+ `targets` 的字段：
227
+
228
+ | 字段 | 类型 | 含义 |
229
+ | --- | --- | --- |
230
+ | `openCode` | `"written"` | OpenCode 认证文件已写入。 |
231
+ | `codex` | `"written" \| "cleared" \| "skipped"` | Codex CLI 认证文件状态：写入、因缺少 ID Token 清理、或跳过。 |
232
+ | `pi` | `"written"` | Pi Agent 认证文件已写入。 |
233
+
234
+ ## 使用约束
235
+
236
+ - 使用 `switchToAccount()` 前，应通过 CLI 的 `cdx label` 为每个需要指定切换的账号设置唯一标签。
237
+ - `switchNextAccount()` 与 `switchToAccount()` 会真实改写本机的 Codex、OpenCode 与 Pi 认证文件。
238
+ - 用量数据来自上游接口，调用方应处理 `USAGE_UNAVAILABLE` 与 `NETWORK_ERROR`，并按 `retryable` 做退避重试。
239
+ - API 不负责跨进程的任务暂停、切换锁、重试队列或自动切换策略；这些应由后续独立守护模块负责。
package/README.md CHANGED
@@ -4,17 +4,6 @@
4
4
 
5
5
  > 非官方项目：本仓库基于 [bjesuiter/codex-switcher](https://github.com/bjesuiter/codex-switcher) 二次开发，遵循 MIT 许可证。原作者署名、许可证和本分叉声明见 [NOTICE](./NOTICE) 与 [LICENSE](./LICENSE)。本项目与原作者及 OpenAI 均不存在隶属、赞助或认可关系。
6
6
 
7
- ## 当前版本
8
-
9
- ### 1.8.7
10
-
11
- - 修复 Windows 上 OAuth 登录链接被 `cmd` 截断的问题，改用 Windows 系统 URL 协议处理器打开浏览器。
12
- - 更新 OAuth 请求的 scope、state 与 originator 兼容处理，并按当前 Codex CLI 的格式写入 `auth.json`。
13
- - 增加分叉来源说明、第三方依赖声明与发布前元数据检查。
14
- - 移除仅用于 PKCE 的第三方 OAuth 依赖，改用 Node 内置加密实现。
15
-
16
- 完整变更记录见 [CHANGELOG.md](./CHANGELOG.md)。
17
-
18
7
  ## 使用范围与安全边界
19
8
 
20
9
  - 仅使用你本人拥有或已获授权使用的账号；不要借此规避订阅、地区、用量、访问控制或服务条款限制。
@@ -73,6 +62,22 @@ bun cdx.ts status
73
62
  bun cdx.ts login
74
63
  ```
75
64
 
65
+ ## 脚本 API
66
+
67
+ 除 CLI 外，本包还提供用于脚本集成的受限 API，可查询账号列表、当前启用账号、当前账号用量，并按标签切换账号：
68
+
69
+ ```js
70
+ import {
71
+ listAccounts,
72
+ getCurrentAccount,
73
+ getCurrentAccountUsage,
74
+ switchNextAccount,
75
+ switchToAccount,
76
+ } from "@huui/cdx-switcher/api";
77
+ ```
78
+
79
+ API 不提供登录、重新登录、OAuth 或凭据读取能力，也不会输出 CLI 文本或终止调用进程。完整的参数、返回结构、错误码和使用约束见 [API.md](./API.md)。
80
+
76
81
  ## 快速操作流程
77
82
 
78
83
  ### 1. 添加第一个账号
@@ -85,7 +90,7 @@ cdx login
85
90
 
86
91
  Windows 若没有打开浏览器、错误打开文件夹，或自动页仍报认证参数错误：
87
92
 
88
- 1. 先确认运行的是本仓库发布的 1.8.7 或更高版本：`cdx --version`。
93
+ 1. 先确认运行的是本项目已发布的最新版本：`cdx --version`。
89
94
  2. 不要关闭运行 `cdx login` 的终端。
90
95
  3. 复制终端打印的**完整**授权链接，在正常浏览器地址栏重新打开；不要手动删改 `originator`、`state`、`scope`、`code_challenge` 等参数。
91
96
  4. 完成登录后，浏览器必须回跳到 `http://localhost:1455/auth/callback`，终端才会完成保存。