@xixka/dsh-hub 0.2.1-rc.9 → 0.2.3

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 (359) hide show
  1. package/README.md +60 -889
  2. package/lib/accio-adapter.d.ts.map +1 -1
  3. package/lib/accio-adapter.js +3 -1
  4. package/lib/accio-adapter.js.map +1 -1
  5. package/lib/account-pool.d.ts +128 -0
  6. package/lib/account-pool.d.ts.map +1 -1
  7. package/lib/account-pool.js +252 -15
  8. package/lib/account-pool.js.map +1 -1
  9. package/lib/aggregate-adapter.d.ts +38 -0
  10. package/lib/aggregate-adapter.d.ts.map +1 -1
  11. package/lib/aggregate-adapter.js +145 -12
  12. package/lib/aggregate-adapter.js.map +1 -1
  13. package/lib/aggregate-expiry.d.ts.map +1 -1
  14. package/lib/aggregate-expiry.js +4 -0
  15. package/lib/aggregate-expiry.js.map +1 -1
  16. package/lib/analyze-image.d.ts.map +1 -1
  17. package/lib/analyze-image.js.map +1 -1
  18. package/lib/astudio-adapter.d.ts.map +1 -1
  19. package/lib/astudio-adapter.js +3 -1
  20. package/lib/astudio-adapter.js.map +1 -1
  21. package/lib/buddy-adapter.d.ts.map +1 -1
  22. package/lib/buddy-adapter.js +22 -4
  23. package/lib/buddy-adapter.js.map +1 -1
  24. package/lib/buddy.d.ts +7 -2
  25. package/lib/buddy.d.ts.map +1 -1
  26. package/lib/buddy.js +7 -2
  27. package/lib/buddy.js.map +1 -1
  28. package/lib/canonical-models.d.ts.map +1 -1
  29. package/lib/canonical-models.js +20 -0
  30. package/lib/canonical-models.js.map +1 -1
  31. package/lib/chromium-session.d.ts +174 -0
  32. package/lib/chromium-session.d.ts.map +1 -1
  33. package/lib/chromium-session.js +418 -1
  34. package/lib/chromium-session.js.map +1 -1
  35. package/lib/client/jet-hub.js +287 -13918
  36. package/lib/codearts-credits.d.ts +176 -16
  37. package/lib/codearts-credits.d.ts.map +1 -1
  38. package/lib/codearts-credits.js +316 -34
  39. package/lib/codearts-credits.js.map +1 -1
  40. package/lib/codearts-vision.d.ts +95 -4
  41. package/lib/codearts-vision.d.ts.map +1 -1
  42. package/lib/codearts-vision.js +136 -5
  43. package/lib/codearts-vision.js.map +1 -1
  44. package/lib/codely-adapter.d.ts +36 -3
  45. package/lib/codely-adapter.d.ts.map +1 -1
  46. package/lib/codely-adapter.js +252 -11
  47. package/lib/codely-adapter.js.map +1 -1
  48. package/lib/codely-auth-service.d.ts +17 -0
  49. package/lib/codely-auth-service.d.ts.map +1 -1
  50. package/lib/codely-auth-service.js +40 -3
  51. package/lib/codely-auth-service.js.map +1 -1
  52. package/lib/codely-auth.d.ts.map +1 -1
  53. package/lib/codely-auth.js +23 -0
  54. package/lib/codely-auth.js.map +1 -1
  55. package/lib/codely-credits.d.ts.map +1 -1
  56. package/lib/codely-credits.js +18 -1
  57. package/lib/codely-credits.js.map +1 -1
  58. package/lib/codely-product.d.ts +10 -5
  59. package/lib/codely-product.d.ts.map +1 -1
  60. package/lib/codely-product.js +4 -2
  61. package/lib/codely-product.js.map +1 -1
  62. package/lib/credential-resolver.d.ts +41 -1
  63. package/lib/credential-resolver.d.ts.map +1 -1
  64. package/lib/credential-resolver.js +31 -6
  65. package/lib/credential-resolver.js.map +1 -1
  66. package/lib/image-budget.d.ts +3 -11
  67. package/lib/image-budget.d.ts.map +1 -1
  68. package/lib/image-budget.js +43 -5
  69. package/lib/image-budget.js.map +1 -1
  70. package/lib/image-data-cache.d.ts +87 -0
  71. package/lib/image-data-cache.d.ts.map +1 -0
  72. package/lib/image-data-cache.js +144 -0
  73. package/lib/image-data-cache.js.map +1 -0
  74. package/lib/index.d.ts +0 -51
  75. package/lib/index.d.ts.map +1 -1
  76. package/lib/index.js +290 -164
  77. package/lib/index.js.map +1 -1
  78. package/lib/jet-hub-rpc.d.ts +14 -19
  79. package/lib/jet-hub-rpc.d.ts.map +1 -1
  80. package/lib/jet-hub-rpc.js +812 -496
  81. package/lib/jet-hub-rpc.js.map +1 -1
  82. package/lib/jet-hub-store.d.ts +52 -0
  83. package/lib/jet-hub-store.d.ts.map +1 -1
  84. package/lib/jet-hub-store.js +52 -4
  85. package/lib/jet-hub-store.js.map +1 -1
  86. package/lib/llm-adapter.d.ts +96 -5
  87. package/lib/llm-adapter.d.ts.map +1 -1
  88. package/lib/llm-adapter.js +742 -62
  89. package/lib/llm-adapter.js.map +1 -1
  90. package/lib/lobsterai-adapter.d.ts.map +1 -1
  91. package/lib/lobsterai-adapter.js +54 -15
  92. package/lib/lobsterai-adapter.js.map +1 -1
  93. package/lib/login.d.ts +5 -13
  94. package/lib/login.d.ts.map +1 -1
  95. package/lib/login.js +75 -14
  96. package/lib/login.js.map +1 -1
  97. package/lib/loomy-adapter.d.ts +3 -0
  98. package/lib/loomy-adapter.d.ts.map +1 -1
  99. package/lib/loomy-adapter.js +11 -3
  100. package/lib/loomy-adapter.js.map +1 -1
  101. package/lib/loomy-auth.d.ts +64 -1
  102. package/lib/loomy-auth.d.ts.map +1 -1
  103. package/lib/loomy-auth.js +191 -22
  104. package/lib/loomy-auth.js.map +1 -1
  105. package/lib/loomy-credits.d.ts +17 -0
  106. package/lib/loomy-credits.d.ts.map +1 -1
  107. package/lib/loomy-credits.js +35 -2
  108. package/lib/loomy-credits.js.map +1 -1
  109. package/lib/loomy-oauth.d.ts +44 -0
  110. package/lib/loomy-oauth.d.ts.map +1 -1
  111. package/lib/loomy-oauth.js +48 -1
  112. package/lib/loomy-oauth.js.map +1 -1
  113. package/lib/loomy-sms-login.d.ts +61 -0
  114. package/lib/loomy-sms-login.d.ts.map +1 -0
  115. package/lib/loomy-sms-login.js +330 -0
  116. package/lib/loomy-sms-login.js.map +1 -0
  117. package/lib/loomy.d.ts +41 -0
  118. package/lib/loomy.d.ts.map +1 -1
  119. package/lib/loomy.js +29 -0
  120. package/lib/loomy.js.map +1 -1
  121. package/lib/magicrew-adapter.d.ts +201 -0
  122. package/lib/magicrew-adapter.d.ts.map +1 -0
  123. package/lib/magicrew-adapter.js +595 -0
  124. package/lib/magicrew-adapter.js.map +1 -0
  125. package/lib/magicrew-auth.d.ts +494 -0
  126. package/lib/magicrew-auth.d.ts.map +1 -0
  127. package/lib/magicrew-auth.js +951 -0
  128. package/lib/magicrew-auth.js.map +1 -0
  129. package/lib/magicrew-browser-login.d.ts +333 -0
  130. package/lib/magicrew-browser-login.d.ts.map +1 -0
  131. package/lib/magicrew-browser-login.js +740 -0
  132. package/lib/magicrew-browser-login.js.map +1 -0
  133. package/lib/magicrew-catalog.d.ts +19 -0
  134. package/lib/magicrew-catalog.d.ts.map +1 -0
  135. package/lib/magicrew-catalog.js +80 -0
  136. package/lib/magicrew-catalog.js.map +1 -0
  137. package/lib/magicrew-credits.d.ts +112 -0
  138. package/lib/magicrew-credits.d.ts.map +1 -0
  139. package/lib/magicrew-credits.js +319 -0
  140. package/lib/magicrew-credits.js.map +1 -0
  141. package/lib/magicrew-local-browser.d.ts +123 -0
  142. package/lib/magicrew-local-browser.d.ts.map +1 -0
  143. package/lib/magicrew-local-browser.js +321 -0
  144. package/lib/magicrew-local-browser.js.map +1 -0
  145. package/lib/magicrew-product.d.ts +127 -0
  146. package/lib/magicrew-product.d.ts.map +1 -0
  147. package/lib/magicrew-product.js +159 -0
  148. package/lib/magicrew-product.js.map +1 -0
  149. package/lib/magicrew-profile.d.ts +74 -0
  150. package/lib/magicrew-profile.d.ts.map +1 -0
  151. package/lib/magicrew-profile.js +148 -0
  152. package/lib/magicrew-profile.js.map +1 -0
  153. package/lib/magicrew.d.ts +185 -0
  154. package/lib/magicrew.d.ts.map +1 -0
  155. package/lib/magicrew.js +215 -0
  156. package/lib/magicrew.js.map +1 -0
  157. package/lib/model-catalog.d.ts +8 -0
  158. package/lib/model-catalog.d.ts.map +1 -1
  159. package/lib/model-catalog.js +127 -5
  160. package/lib/model-catalog.js.map +1 -1
  161. package/lib/models.d.ts +216 -32
  162. package/lib/models.d.ts.map +1 -1
  163. package/lib/models.js +500 -47
  164. package/lib/models.js.map +1 -1
  165. package/lib/modelscope-adapter.d.ts.map +1 -1
  166. package/lib/modelscope-adapter.js +7 -2
  167. package/lib/modelscope-adapter.js.map +1 -1
  168. package/lib/modelscope-product.d.ts +44 -6
  169. package/lib/modelscope-product.d.ts.map +1 -1
  170. package/lib/modelscope-product.js +98 -9
  171. package/lib/modelscope-product.js.map +1 -1
  172. package/lib/officeace-adapter.d.ts.map +1 -1
  173. package/lib/officeace-adapter.js +147 -21
  174. package/lib/officeace-adapter.js.map +1 -1
  175. package/lib/officeace-auth.d.ts +15 -0
  176. package/lib/officeace-auth.d.ts.map +1 -1
  177. package/lib/officeace-auth.js +99 -2
  178. package/lib/officeace-auth.js.map +1 -1
  179. package/lib/openai-gateway/tencent-fingerprint.d.ts.map +1 -1
  180. package/lib/openai-gateway/tencent-fingerprint.js +28 -3
  181. package/lib/openai-gateway/tencent-fingerprint.js.map +1 -1
  182. package/lib/opencode-adapter.d.ts +27 -0
  183. package/lib/opencode-adapter.d.ts.map +1 -1
  184. package/lib/opencode-adapter.js +57 -8
  185. package/lib/opencode-adapter.js.map +1 -1
  186. package/lib/opencode-bun-tls.d.ts +103 -0
  187. package/lib/opencode-bun-tls.d.ts.map +1 -0
  188. package/lib/opencode-bun-tls.js +212 -0
  189. package/lib/opencode-bun-tls.js.map +1 -0
  190. package/lib/opencode-messages.d.ts +0 -19
  191. package/lib/opencode-messages.d.ts.map +1 -1
  192. package/lib/opencode-messages.js +30 -33
  193. package/lib/opencode-messages.js.map +1 -1
  194. package/lib/opencode-official-prompt.d.ts +62 -0
  195. package/lib/opencode-official-prompt.d.ts.map +1 -0
  196. package/lib/opencode-official-prompt.js +119 -0
  197. package/lib/opencode-official-prompt.js.map +1 -0
  198. package/lib/opencode-official-tools.d.ts +27 -0
  199. package/lib/opencode-official-tools.d.ts.map +1 -0
  200. package/lib/opencode-official-tools.js +340 -0
  201. package/lib/opencode-official-tools.js.map +1 -0
  202. package/lib/opencode-product.d.ts.map +1 -1
  203. package/lib/opencode-product.js +3 -2
  204. package/lib/opencode-product.js.map +1 -1
  205. package/lib/opencode-stream.d.ts.map +1 -1
  206. package/lib/opencode-stream.js +8 -7
  207. package/lib/opencode-stream.js.map +1 -1
  208. package/lib/product.d.ts +15 -3
  209. package/lib/product.d.ts.map +1 -1
  210. package/lib/product.js +44 -11
  211. package/lib/product.js.map +1 -1
  212. package/lib/provider-credits.d.ts +2 -0
  213. package/lib/provider-credits.d.ts.map +1 -1
  214. package/lib/provider-credits.js +46 -17
  215. package/lib/provider-credits.js.map +1 -1
  216. package/lib/provider-expiry.d.ts.map +1 -1
  217. package/lib/provider-expiry.js +29 -0
  218. package/lib/provider-expiry.js.map +1 -1
  219. package/lib/provider-http-pool.d.ts +85 -0
  220. package/lib/provider-http-pool.d.ts.map +1 -0
  221. package/lib/provider-http-pool.js +224 -0
  222. package/lib/provider-http-pool.js.map +1 -0
  223. package/lib/provider-registry.d.ts.map +1 -1
  224. package/lib/provider-registry.js +73 -39
  225. package/lib/provider-registry.js.map +1 -1
  226. package/lib/qiniu-adapter.d.ts +276 -0
  227. package/lib/qiniu-adapter.d.ts.map +1 -0
  228. package/lib/qiniu-adapter.js +689 -0
  229. package/lib/qiniu-adapter.js.map +1 -0
  230. package/lib/qiniu-auth.d.ts +130 -0
  231. package/lib/qiniu-auth.d.ts.map +1 -0
  232. package/lib/qiniu-auth.js +234 -0
  233. package/lib/qiniu-auth.js.map +1 -0
  234. package/lib/qiniu-messages.d.ts +96 -0
  235. package/lib/qiniu-messages.d.ts.map +1 -0
  236. package/lib/qiniu-messages.js +97 -0
  237. package/lib/qiniu-messages.js.map +1 -0
  238. package/lib/qiniu-product.d.ts +126 -0
  239. package/lib/qiniu-product.d.ts.map +1 -0
  240. package/lib/qiniu-product.js +269 -0
  241. package/lib/qiniu-product.js.map +1 -0
  242. package/lib/qiniu-rpc.d.ts +119 -0
  243. package/lib/qiniu-rpc.d.ts.map +1 -0
  244. package/lib/qiniu-rpc.js +214 -0
  245. package/lib/qiniu-rpc.js.map +1 -0
  246. package/lib/qiniu.d.ts +145 -0
  247. package/lib/qiniu.d.ts.map +1 -0
  248. package/lib/qiniu.js +164 -0
  249. package/lib/qiniu.js.map +1 -0
  250. package/lib/raccoon-adapter.d.ts +52 -2
  251. package/lib/raccoon-adapter.d.ts.map +1 -1
  252. package/lib/raccoon-adapter.js +148 -29
  253. package/lib/raccoon-adapter.js.map +1 -1
  254. package/lib/raccoon-auth.d.ts +6 -0
  255. package/lib/raccoon-auth.d.ts.map +1 -1
  256. package/lib/raccoon-auth.js +9 -1
  257. package/lib/raccoon-auth.js.map +1 -1
  258. package/lib/raccoon-credits.d.ts +38 -5
  259. package/lib/raccoon-credits.d.ts.map +1 -1
  260. package/lib/raccoon-credits.js +127 -6
  261. package/lib/raccoon-credits.js.map +1 -1
  262. package/lib/raccoon.d.ts +14 -2
  263. package/lib/raccoon.d.ts.map +1 -1
  264. package/lib/raccoon.js +14 -2
  265. package/lib/raccoon.js.map +1 -1
  266. package/lib/service.d.ts +46 -6
  267. package/lib/service.d.ts.map +1 -1
  268. package/lib/service.js +104 -16
  269. package/lib/service.js.map +1 -1
  270. package/lib/session-balance.d.ts +203 -0
  271. package/lib/session-balance.d.ts.map +1 -0
  272. package/lib/session-balance.js +279 -0
  273. package/lib/session-balance.js.map +1 -0
  274. package/lib/sign.d.ts +97 -1
  275. package/lib/sign.d.ts.map +1 -1
  276. package/lib/sign.js +174 -2
  277. package/lib/sign.js.map +1 -1
  278. package/lib/token-ledger-store.d.ts.map +1 -1
  279. package/lib/token-ledger-store.js +121 -27
  280. package/lib/token-ledger-store.js.map +1 -1
  281. package/lib/trae-adapter.d.ts.map +1 -1
  282. package/lib/trae-adapter.js +3 -1
  283. package/lib/trae-adapter.js.map +1 -1
  284. package/lib/types.d.ts +75 -15
  285. package/lib/types.d.ts.map +1 -1
  286. package/lib/types.js.map +1 -1
  287. package/lib/usage-badge.d.ts +77 -7
  288. package/lib/usage-badge.d.ts.map +1 -1
  289. package/lib/usage-badge.js +190 -28
  290. package/lib/usage-badge.js.map +1 -1
  291. package/lib/webdav-auto-sync.d.ts +96 -0
  292. package/lib/webdav-auto-sync.d.ts.map +1 -0
  293. package/lib/webdav-auto-sync.js +0 -0
  294. package/lib/webdav-auto-sync.js.map +1 -0
  295. package/lib/webdav-sync-crypto.d.ts +18 -0
  296. package/lib/webdav-sync-crypto.d.ts.map +1 -0
  297. package/lib/webdav-sync-crypto.js +72 -0
  298. package/lib/webdav-sync-crypto.js.map +1 -0
  299. package/lib/webdav-sync-merge.d.ts +31 -0
  300. package/lib/webdav-sync-merge.d.ts.map +1 -0
  301. package/lib/webdav-sync-merge.js +0 -0
  302. package/lib/webdav-sync-merge.js.map +1 -0
  303. package/lib/webdav-sync.d.ts +43 -7
  304. package/lib/webdav-sync.d.ts.map +1 -1
  305. package/lib/webdav-sync.js +72 -11
  306. package/lib/webdav-sync.js.map +1 -1
  307. package/lib/zcode-adapter.d.ts +4 -2
  308. package/lib/zcode-adapter.d.ts.map +1 -1
  309. package/lib/zcode-adapter.js +132 -37
  310. package/lib/zcode-adapter.js.map +1 -1
  311. package/lib/zcode-upstream.d.ts +59 -0
  312. package/lib/zcode-upstream.d.ts.map +1 -1
  313. package/lib/zcode-upstream.js +137 -2
  314. package/lib/zcode-upstream.js.map +1 -1
  315. package/package.json +5 -4
  316. package/lib/stepcode-adapter.d.ts +0 -158
  317. package/lib/stepcode-adapter.d.ts.map +0 -1
  318. package/lib/stepcode-adapter.js +0 -318
  319. package/lib/stepcode-adapter.js.map +0 -1
  320. package/lib/stepcode-auth.d.ts +0 -154
  321. package/lib/stepcode-auth.d.ts.map +0 -1
  322. package/lib/stepcode-auth.js +0 -287
  323. package/lib/stepcode-auth.js.map +0 -1
  324. package/lib/stepcode-oauth.d.ts +0 -194
  325. package/lib/stepcode-oauth.d.ts.map +0 -1
  326. package/lib/stepcode-oauth.js +0 -496
  327. package/lib/stepcode-oauth.js.map +0 -1
  328. package/lib/stepcode-product.d.ts +0 -255
  329. package/lib/stepcode-product.d.ts.map +0 -1
  330. package/lib/stepcode-product.js +0 -256
  331. package/lib/stepcode-product.js.map +0 -1
  332. package/lib/stepcode.d.ts +0 -230
  333. package/lib/stepcode.d.ts.map +0 -1
  334. package/lib/stepcode.js +0 -300
  335. package/lib/stepcode.js.map +0 -1
  336. package/lib/teleagent-adapter.d.ts +0 -116
  337. package/lib/teleagent-adapter.d.ts.map +0 -1
  338. package/lib/teleagent-adapter.js +0 -293
  339. package/lib/teleagent-adapter.js.map +0 -1
  340. package/lib/teleagent-auth.d.ts +0 -279
  341. package/lib/teleagent-auth.d.ts.map +0 -1
  342. package/lib/teleagent-auth.js +0 -512
  343. package/lib/teleagent-auth.js.map +0 -1
  344. package/lib/teleagent-cdp-login.d.ts +0 -100
  345. package/lib/teleagent-cdp-login.d.ts.map +0 -1
  346. package/lib/teleagent-cdp-login.js +0 -402
  347. package/lib/teleagent-cdp-login.js.map +0 -1
  348. package/lib/teleagent-credits.d.ts +0 -120
  349. package/lib/teleagent-credits.d.ts.map +0 -1
  350. package/lib/teleagent-credits.js +0 -288
  351. package/lib/teleagent-credits.js.map +0 -1
  352. package/lib/teleagent-product.d.ts +0 -196
  353. package/lib/teleagent-product.d.ts.map +0 -1
  354. package/lib/teleagent-product.js +0 -212
  355. package/lib/teleagent-product.js.map +0 -1
  356. package/lib/teleagent.d.ts +0 -288
  357. package/lib/teleagent.d.ts.map +0 -1
  358. package/lib/teleagent.js +0 -450
  359. package/lib/teleagent.js.map +0 -1
@@ -0,0 +1,203 @@
1
+ /**
2
+ * 按 **sessionId** 做账号亲和 / 无 sessionId 时随机分摊的纯函数。
3
+ *
4
+ * ## 为什么需要它
5
+ *
6
+ * 账号池此前的 `getAvailableAccount()` 永远取「手动顺序第一个可用账号」:
7
+ * 只要 1 号没撞限额,全部流量都压在它身上。对 ZCode 这种「一个会话会连续
8
+ * 发很多轮请求」的 provider,用户希望:
9
+ *
10
+ * - **有 sessionId**:同一会话**优先**落到同一个账号(会话亲和),不同会话按
11
+ * sessionId 稳定分散到不同账号 —— ⚠️ 这个「优先」是有例外的:账号今日负载
12
+ * 达阈值后会被沉底,正在跑的会话**会迁移一次**(见
13
+ * `rankAccountsBySessionWithOverflow` 的长注释,2026-10-31 审计订正);
14
+ * - **没有 sessionId**(本地 OpenAI 网关等一次性调用):每次随机挑一个账号,
15
+ * 把请求分摊开。
16
+ *
17
+ * ## 为什么用 rendezvous 哈希而不是 `hash % N`
18
+ *
19
+ * `hash(sessionId) % 账号数` 在账号数变化时会**整体重排**:某个账号临时进入
20
+ * 限流(候选集从 5 个变 4 个)会让所有会话换号,限流恢复后又全部换回。
21
+ * rendezvous 哈希给每个 `(session, account)` 算一个稳定分数、按分数排序取最高,
22
+ * 账号集合变化时只有原本落在那个账号上的会话需要迁移,其余会话保持不动。
23
+ *
24
+ * ## 为什么随机回退用洗牌而不是「随机取一个」
25
+ *
26
+ * 随机取一个若刚好拿到凭据损坏 / 已被 `tried` 排除的账号,还要再抽一次;
27
+ * 直接洗牌后顺序尝试,既均匀又不重复。
28
+ */
29
+ /**
30
+ * 「ZCode 会话负载均衡」的开关环境变量。
31
+ *
32
+ * ## 默认与判据(与 `DSH_RATE_LIMIT_SINK` 同型,**别写成 falsy 判断**)
33
+ *
34
+ * 默认**开启**(用户 2026-10-30 的原始需求)。留这道开关是因为它改变了选号
35
+ * 语义:手动顺序不再决定谁先被用;若有人依赖「首位账号一直扛」的旧行为
36
+ * (例如想让额度最充足的号先烧完),显式设 `0` / `false` / `off` / `no`
37
+ * 即整体退回「手动顺序优先」的既有路径 —— 与关掉前逐字节同语义。
38
+ *
39
+ * ⚠️ 判据取「**显式写了** `0/false/off/no` 才算关」,未设置 / 空串 / 无法
40
+ * 识别的值一律按默认开启 —— `Boolean(env[...])` 会把「未设置」误判成关闭
41
+ * (`account-pool.ts` 的 `rateLimitSinkEnabled` 记过同型坑)。
42
+ *
43
+ * ⚠️ **与 `jet-hub-store.ts` 的 `sanitizeSessionBalanceEnabled` 是两套刻意
44
+ * 不同的判据,不要「统一」**:本函数是 **env 替身回落**(字符串宽松,`'false'`
45
+ * 算关 —— env 里没有类型,用户写了就是意图);store 那份是**落盘数据判据**
46
+ * (严格 `raw !== false` —— 脏字符串 ≠ 用户意图,宁可当启用)。生产路径恒走
47
+ * store 那份(见 `credential-resolver.ts` ③ 的 poolSwitch 优先级),本函数
48
+ * 只在「结构化替身池」可达。
49
+ */
50
+ export declare const DSH_ZCODE_SESSION_BALANCE = "DSH_ZCODE_SESSION_BALANCE";
51
+ /** 当前是否启用「ZCode 会话负载均衡」(见 {@link DSH_ZCODE_SESSION_BALANCE})。 */
52
+ export declare function sessionBalanceEnabled(env?: NodeJS.ProcessEnv): boolean;
53
+ /** 计算 `(scope, sessionId, accountId)` 的稳定分数(SHA-256 十六进制)。 */
54
+ export declare function sessionAccountScore(scope: string, sessionId: string, accountId: string): string;
55
+ /**
56
+ * 按 sessionId 给账号做 **rendezvous 哈希**排序(分数从高到低)。
57
+ *
58
+ * - 同一个 sessionId + 同一批账号 ⇒ 结果逐字稳定(跨进程、跨重启一致);
59
+ * - 不同 sessionId 会得到不同顺序,从而把会话分散到不同账号;
60
+ * - 账号集合增删时,只影响原本首选该账号的会话,其余顺序尽量保持。
61
+ *
62
+ * @param accounts - 候选账号(调用方已按 enabled / 模型限流 / tried 过滤)。
63
+ * @param sessionId - 非空会话标识。
64
+ * @param scope - 命名空间(传 provider id),避免不同 provider 的同名账号串味。
65
+ * @returns 新数组,不修改入参。
66
+ */
67
+ export declare function rankAccountsBySession<T extends {
68
+ id: string;
69
+ }>(accounts: readonly T[], sessionId: string, scope: string): T[];
70
+ /**
71
+ * Fisher–Yates 洗牌(不改入参)。
72
+ *
73
+ * `random` 可注入,供单测固定序列;生产缺省 `Math.random`。
74
+ */
75
+ export declare function shuffleAccounts<T>(accounts: readonly T[], random?: () => number): T[];
76
+ /**
77
+ * 「账号今日负载」读数(供溢出均衡用)。
78
+ *
79
+ * 只取选号真正需要的**一个**字段:今日请求笔数。
80
+ *
81
+ * ⚠️ 初版还带一个 `outputTokens`(「今日输出 token 合计」),但**全仓没有任何读点**
82
+ * —— 溢出的判据只看请求笔数。2026-10-31 审计实测它是死字段后删除:留着会让
83
+ * 「只取选号真正需要的两个字段」这句注释与实现不符,也会诱导后来者以为 token 量
84
+ * 参与排序。
85
+ *
86
+ * 数据源是 token-ledger 的日聚合(`readTokenLedgerDayMap()`),**纯内存读、
87
+ * 零网络请求** —— 选号在推理关键路径上,绝不能在这里发余额请求。
88
+ * 实测代价:真实 8 个桶 ≈ 0.9 µs/次,最坏 500 桶 ≈ 85 µs/次(与日键数量无关)。
89
+ */
90
+ export interface AccountLoadReading {
91
+ /** 该账号今日(UTC+8 日界)的请求笔数(含失败)。 */
92
+ requests: number;
93
+ }
94
+ /**
95
+ * 会话负载均衡的**溢出阈值**环境变量(账号今日请求数)。
96
+ *
97
+ * ## 它解决的问题(2026-10-31 用户报障「每个账号的负载并不太均衡」)
98
+ *
99
+ * 会话亲和的账号负载 ≈ **会话长度**(一个跑整天的会话把它哈希到的那个账号独自
100
+ * 吃满,没有会话落上的账号整天空闲)。本机真实账本实测:
101
+ * `2026-10-31` 六个有量账号为 `1233 / 459 / 8 / 7 / 7 / 7`(总量 1721,
102
+ * 单号占 **71.6%**,max/mean = **4.30**)。
103
+ *
104
+ * ## 语义:这是「**上限(cap)**」,不是「均衡器」,更不是「已有会话保持亲和」
105
+ *
106
+ * - 账号今日请求数 ≥ 阈值 ⇒ 在该次的排序里**整组沉底**;
107
+ * - 因此 **新会话**会落到未超载的账号上;
108
+ * - ⚠️ 但本模块**无状态**(见 `rankAccountsBySessionWithOverflow` 的长注释):
109
+ * 一个**正在跑的会话**,一旦它所在账号越过阈值,它的**下一次请求就会迁移**到
110
+ * 别的账号 —— 本修法正是靠这次迁移把长会话摊开的。**不要**在别处声称
111
+ * 「已有会话保持亲和 / 已开的会话不换号」。
112
+ * - 全员超载 ⇒ 退回纯哈希序(照常发请求让上游自己限流,不硬失败)。
113
+ *
114
+ * ## 为什么阈值是**绝对量**而不是「当日总量的相对量」(实测否决)
115
+ *
116
+ * 初版设想过 `max(下限, ceil(k × 当日累计 / 账号数))`,**实测否决**:
117
+ * 阈值随总量上涨会把「已超载」的账号重新变回 fresh ⇒ 会话反复弹回原号。
118
+ * 真实场景(8 号池 / 1691 请求 / 1 个超长会话 + 1 个中等会话)实测:
119
+ *
120
+ * | 策略 | max/mean | 会话中途换号 |
121
+ * |---|---|---|
122
+ * | 关闭溢出 | 5.83 | 0 |
123
+ * | 固定 300 | **1.42** | **5** |
124
+ * | 相对 `max(200, 1.2×均值)` | 1.20 | **204** |
125
+ * | 相对 `max(200, 1.5×均值)` | 1.50 | **428** |
126
+ *
127
+ * ⇒ 相对量用 8 倍以上的换号次数只换来一点点更平的分摊,**不划算**,故保留绝对阈值。
128
+ *
129
+ * ## 默认值 300 的来源(真实账本,不是拍脑袋)
130
+ *
131
+ * 固定上限 C 的最终比值上界是 `C ÷ 当日均匀量`。按本机有量的 4 天倒推:
132
+ * `10-25`(总量 759 / 4 号 / 峰值 412 / 错误率 13.3%)与 `10-31`(1721 / 峰值
133
+ * 1233)要压到 ≈1.5 以内 ⇒ `C ≤ 300`;而 `10-24`(峰值 398 / 均值 310)本就
134
+ * 接近均匀,300 只会引发极少量迁移。
135
+ *
136
+ * ⚠️ 初版默认 **600** 实测**几乎不生效**:4 天里 3 天峰值 < 600 ⇒ 一个号都不会
137
+ * 沉底 ⇒ 零效果;且 PR 正文举证的 `322/322/306/156/34`(峰值 322)同样 < 600
138
+ * ⇒ **对它自己描述的报障也零效果**。600 在 10-31 只把 max/mean 从 5.83 压到 2.84。
139
+ *
140
+ * ## 已知边界(如实登记,不掩饰)
141
+ *
142
+ * - **小池 + 高量**:2 个号各 850 次、阈值 300 ⇒ 两个号长期都超载 ⇒ `fresh` 为空
143
+ * ⇒ 退回哈希序 ⇒ **不生效**(此时不均衡度本身也只有 ≤2.0,可接受)。
144
+ * - **大池 + 高量**:20 个号均分 86 ⇒ 单号很难到 300 ⇒ **不生效**。
145
+ * 需要更激进时用环境变量下调(本仓库实测 5~8 号池最合适)。
146
+ * - 阈值按 **UTC+8 日界** 归零,跨日那一刻所有账号重新变 fresh。
147
+ */
148
+ export declare const DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS = "DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS";
149
+ /** 缺省溢出阈值(今日请求数)。取值依据见 {@link DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS}。 */
150
+ export declare const DEFAULT_OVERFLOW_REQUESTS = 300;
151
+ /** 当前生效的溢出阈值;`0` = 关闭溢出均衡(纯哈希亲和)。 */
152
+ export declare function overflowRequestsThreshold(env?: NodeJS.ProcessEnv): number;
153
+ /**
154
+ * 按账号 id 索引「今日负载」读数。
155
+ *
156
+ * @param days - token-ledger 日聚合表(`readTokenLedgerDayMap()` 的返回)。
157
+ * @param provider - provider id(只统计该渠道的桶)。
158
+ * @param day - UTC+8 日键(`utc8DayKey(Date.now())`,由调用方传入以便单测)。
159
+ */
160
+ export declare function accountLoadIndex(days: ReadonlyMap<string, ReadonlyMap<string, {
161
+ requests: number;
162
+ outputTokens: number;
163
+ }>>, provider: string, day: string): Map<string, AccountLoadReading>;
164
+ /**
165
+ * 带**溢出**的会话排序:负载达阈值的账号沉底,其余按 rendezvous 序不变。
166
+ *
167
+ * ## 语义(三条)
168
+ *
169
+ * 1. **未超载**的账号之间:rendezvous 哈希序不变(跨请求稳定);
170
+ * 2. **已超载**的账号整组沉到最后 ⇒ **新会话**落到未超载账号上(负载分摊);
171
+ * 3. **全员超载**时退回纯哈希序(照常发请求让上游自己限流,不硬失败)。
172
+ *
173
+ * ⚠️ 这是**软溢出**而非硬排除:超载账号仍在候选里(排最后)。硬排除会让
174
+ * 「5 个号全超载」时选不出号 —— 而此时正确动作是照常发请求让上游限流。
175
+ *
176
+ * ## ⚠️⚠️ 它**不是**「已有会话保持亲和」——这是初版的错误表述,已订正
177
+ *
178
+ * 本函数是**无状态纯函数**,而调用方(`AccountPool.getAvailableAccountForSession`)
179
+ * **每个请求**都会重跑一次;池里**没有** `sessionId → accountId` 的记忆
180
+ * (全库只有 provider 级的 `activeZcodeAccountId`,那是记账归属,不是亲和状态)。
181
+ *
182
+ * ⇒ **一个正在跑的会话,一旦它所在账号的今日请求数达阈值,它的下一次请求就会
183
+ * 被排到别的账号上。** 本修法正是靠这次迁移把长会话的负载摊开的。
184
+ *
185
+ * 实测(8 号池 / 会话连跑 / 阈值 600):第 **601** 次、第 **1201** 次各迁移一次;
186
+ * 阈值低于当日均匀量时还会出现两种退化:①「**为 1 次请求换号**」(如
187
+ * `a×148 → d×1 → e×37`),②「**越过阈值后又弹回原号**」(全员超载 ⇒ 退回哈希序)。
188
+ *
189
+ * 若将来确实需要硬亲和,必须新增 `Map<sessionId, accountId>` + TTL;而那样会让
190
+ * 本修法对「长会话独占一个号」**重新失效**(两个目标互斥)—— 2026-10-31 审计
191
+ * 记录在案:本 PR 选择了「摊平负载」,代价是会话跨越阈值时会迁移一次。
192
+ *
193
+ * @param accounts - 候选账号(调用方已按 enabled / 模型限流 / tried 过滤)。
194
+ * @param sessionId - 非空会话标识。
195
+ * @param scope - 命名空间(provider id)。
196
+ * @param loads - 账号今日负载索引(缺账号 = 今日没跑过 = 负载 0)。
197
+ * @param thresholdRequests - 溢出阈值(今日请求数);`0` = 关闭溢出。
198
+ * @returns 新数组,不修改入参。
199
+ */
200
+ export declare function rankAccountsBySessionWithOverflow<T extends {
201
+ id: string;
202
+ }>(accounts: readonly T[], sessionId: string, scope: string, loads: ReadonlyMap<string, AccountLoadReading>, thresholdRequests: number): T[];
203
+ //# sourceMappingURL=session-balance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-balance.d.ts","sourceRoot":"","sources":["../src/session-balance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AAEpE,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAMnF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAC5D,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,CAAC,EAAE,CAQL;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,GAAE,MAAM,MAAoB,GAAG,CAAC,EAAE,CASlG;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,2CAA2C,gDAAgD,CAAA;AAExG,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C,qCAAqC;AACrC,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAkBtF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;CACrB,CAAC,CAAC,EACH,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAejC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iCAAiC,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACxE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,iBAAiB,EAAE,MAAM,GACxB,CAAC,EAAE,CAyBL"}
@@ -0,0 +1,279 @@
1
+ /**
2
+ * 按 **sessionId** 做账号亲和 / 无 sessionId 时随机分摊的纯函数。
3
+ *
4
+ * ## 为什么需要它
5
+ *
6
+ * 账号池此前的 `getAvailableAccount()` 永远取「手动顺序第一个可用账号」:
7
+ * 只要 1 号没撞限额,全部流量都压在它身上。对 ZCode 这种「一个会话会连续
8
+ * 发很多轮请求」的 provider,用户希望:
9
+ *
10
+ * - **有 sessionId**:同一会话**优先**落到同一个账号(会话亲和),不同会话按
11
+ * sessionId 稳定分散到不同账号 —— ⚠️ 这个「优先」是有例外的:账号今日负载
12
+ * 达阈值后会被沉底,正在跑的会话**会迁移一次**(见
13
+ * `rankAccountsBySessionWithOverflow` 的长注释,2026-10-31 审计订正);
14
+ * - **没有 sessionId**(本地 OpenAI 网关等一次性调用):每次随机挑一个账号,
15
+ * 把请求分摊开。
16
+ *
17
+ * ## 为什么用 rendezvous 哈希而不是 `hash % N`
18
+ *
19
+ * `hash(sessionId) % 账号数` 在账号数变化时会**整体重排**:某个账号临时进入
20
+ * 限流(候选集从 5 个变 4 个)会让所有会话换号,限流恢复后又全部换回。
21
+ * rendezvous 哈希给每个 `(session, account)` 算一个稳定分数、按分数排序取最高,
22
+ * 账号集合变化时只有原本落在那个账号上的会话需要迁移,其余会话保持不动。
23
+ *
24
+ * ## 为什么随机回退用洗牌而不是「随机取一个」
25
+ *
26
+ * 随机取一个若刚好拿到凭据损坏 / 已被 `tried` 排除的账号,还要再抽一次;
27
+ * 直接洗牌后顺序尝试,既均匀又不重复。
28
+ */
29
+ import { createHash } from 'node:crypto';
30
+ /**
31
+ * 「ZCode 会话负载均衡」的开关环境变量。
32
+ *
33
+ * ## 默认与判据(与 `DSH_RATE_LIMIT_SINK` 同型,**别写成 falsy 判断**)
34
+ *
35
+ * 默认**开启**(用户 2026-10-30 的原始需求)。留这道开关是因为它改变了选号
36
+ * 语义:手动顺序不再决定谁先被用;若有人依赖「首位账号一直扛」的旧行为
37
+ * (例如想让额度最充足的号先烧完),显式设 `0` / `false` / `off` / `no`
38
+ * 即整体退回「手动顺序优先」的既有路径 —— 与关掉前逐字节同语义。
39
+ *
40
+ * ⚠️ 判据取「**显式写了** `0/false/off/no` 才算关」,未设置 / 空串 / 无法
41
+ * 识别的值一律按默认开启 —— `Boolean(env[...])` 会把「未设置」误判成关闭
42
+ * (`account-pool.ts` 的 `rateLimitSinkEnabled` 记过同型坑)。
43
+ *
44
+ * ⚠️ **与 `jet-hub-store.ts` 的 `sanitizeSessionBalanceEnabled` 是两套刻意
45
+ * 不同的判据,不要「统一」**:本函数是 **env 替身回落**(字符串宽松,`'false'`
46
+ * 算关 —— env 里没有类型,用户写了就是意图);store 那份是**落盘数据判据**
47
+ * (严格 `raw !== false` —— 脏字符串 ≠ 用户意图,宁可当启用)。生产路径恒走
48
+ * store 那份(见 `credential-resolver.ts` ③ 的 poolSwitch 优先级),本函数
49
+ * 只在「结构化替身池」可达。
50
+ */
51
+ export const DSH_ZCODE_SESSION_BALANCE = 'DSH_ZCODE_SESSION_BALANCE';
52
+ /** 当前是否启用「ZCode 会话负载均衡」(见 {@link DSH_ZCODE_SESSION_BALANCE})。 */
53
+ export function sessionBalanceEnabled(env = process.env) {
54
+ const raw = env[DSH_ZCODE_SESSION_BALANCE];
55
+ if (typeof raw !== 'string')
56
+ return true;
57
+ const value = raw.trim().toLowerCase();
58
+ if (value.length === 0)
59
+ return true;
60
+ return !(value === '0' || value === 'false' || value === 'off' || value === 'no');
61
+ }
62
+ /** 计算 `(scope, sessionId, accountId)` 的稳定分数(SHA-256 十六进制)。 */
63
+ export function sessionAccountScore(scope, sessionId, accountId) {
64
+ return createHash('sha256')
65
+ .update(scope)
66
+ .update('\0')
67
+ .update(sessionId)
68
+ .update('\0')
69
+ .update(accountId)
70
+ .digest('hex');
71
+ }
72
+ /**
73
+ * 按 sessionId 给账号做 **rendezvous 哈希**排序(分数从高到低)。
74
+ *
75
+ * - 同一个 sessionId + 同一批账号 ⇒ 结果逐字稳定(跨进程、跨重启一致);
76
+ * - 不同 sessionId 会得到不同顺序,从而把会话分散到不同账号;
77
+ * - 账号集合增删时,只影响原本首选该账号的会话,其余顺序尽量保持。
78
+ *
79
+ * @param accounts - 候选账号(调用方已按 enabled / 模型限流 / tried 过滤)。
80
+ * @param sessionId - 非空会话标识。
81
+ * @param scope - 命名空间(传 provider id),避免不同 provider 的同名账号串味。
82
+ * @returns 新数组,不修改入参。
83
+ */
84
+ export function rankAccountsBySession(accounts, sessionId, scope) {
85
+ return [...accounts].sort((a, b) => {
86
+ const sa = sessionAccountScore(scope, sessionId, a.id);
87
+ const sb = sessionAccountScore(scope, sessionId, b.id);
88
+ if (sa !== sb)
89
+ return sa < sb ? 1 : -1;
90
+ // 哈希碰撞在 SHA-256 下实际不可达;保留确定性的 id 次序,避免引擎排序不稳定。
91
+ return a.id.localeCompare(b.id);
92
+ });
93
+ }
94
+ /**
95
+ * Fisher–Yates 洗牌(不改入参)。
96
+ *
97
+ * `random` 可注入,供单测固定序列;生产缺省 `Math.random`。
98
+ */
99
+ export function shuffleAccounts(accounts, random = Math.random) {
100
+ const out = [...accounts];
101
+ for (let index = out.length - 1; index > 0; index -= 1) {
102
+ const swapIndex = Math.floor(random() * (index + 1));
103
+ const current = out[index];
104
+ out[index] = out[swapIndex];
105
+ out[swapIndex] = current;
106
+ }
107
+ return out;
108
+ }
109
+ /**
110
+ * 会话负载均衡的**溢出阈值**环境变量(账号今日请求数)。
111
+ *
112
+ * ## 它解决的问题(2026-10-31 用户报障「每个账号的负载并不太均衡」)
113
+ *
114
+ * 会话亲和的账号负载 ≈ **会话长度**(一个跑整天的会话把它哈希到的那个账号独自
115
+ * 吃满,没有会话落上的账号整天空闲)。本机真实账本实测:
116
+ * `2026-10-31` 六个有量账号为 `1233 / 459 / 8 / 7 / 7 / 7`(总量 1721,
117
+ * 单号占 **71.6%**,max/mean = **4.30**)。
118
+ *
119
+ * ## 语义:这是「**上限(cap)**」,不是「均衡器」,更不是「已有会话保持亲和」
120
+ *
121
+ * - 账号今日请求数 ≥ 阈值 ⇒ 在该次的排序里**整组沉底**;
122
+ * - 因此 **新会话**会落到未超载的账号上;
123
+ * - ⚠️ 但本模块**无状态**(见 `rankAccountsBySessionWithOverflow` 的长注释):
124
+ * 一个**正在跑的会话**,一旦它所在账号越过阈值,它的**下一次请求就会迁移**到
125
+ * 别的账号 —— 本修法正是靠这次迁移把长会话摊开的。**不要**在别处声称
126
+ * 「已有会话保持亲和 / 已开的会话不换号」。
127
+ * - 全员超载 ⇒ 退回纯哈希序(照常发请求让上游自己限流,不硬失败)。
128
+ *
129
+ * ## 为什么阈值是**绝对量**而不是「当日总量的相对量」(实测否决)
130
+ *
131
+ * 初版设想过 `max(下限, ceil(k × 当日累计 / 账号数))`,**实测否决**:
132
+ * 阈值随总量上涨会把「已超载」的账号重新变回 fresh ⇒ 会话反复弹回原号。
133
+ * 真实场景(8 号池 / 1691 请求 / 1 个超长会话 + 1 个中等会话)实测:
134
+ *
135
+ * | 策略 | max/mean | 会话中途换号 |
136
+ * |---|---|---|
137
+ * | 关闭溢出 | 5.83 | 0 |
138
+ * | 固定 300 | **1.42** | **5** |
139
+ * | 相对 `max(200, 1.2×均值)` | 1.20 | **204** |
140
+ * | 相对 `max(200, 1.5×均值)` | 1.50 | **428** |
141
+ *
142
+ * ⇒ 相对量用 8 倍以上的换号次数只换来一点点更平的分摊,**不划算**,故保留绝对阈值。
143
+ *
144
+ * ## 默认值 300 的来源(真实账本,不是拍脑袋)
145
+ *
146
+ * 固定上限 C 的最终比值上界是 `C ÷ 当日均匀量`。按本机有量的 4 天倒推:
147
+ * `10-25`(总量 759 / 4 号 / 峰值 412 / 错误率 13.3%)与 `10-31`(1721 / 峰值
148
+ * 1233)要压到 ≈1.5 以内 ⇒ `C ≤ 300`;而 `10-24`(峰值 398 / 均值 310)本就
149
+ * 接近均匀,300 只会引发极少量迁移。
150
+ *
151
+ * ⚠️ 初版默认 **600** 实测**几乎不生效**:4 天里 3 天峰值 < 600 ⇒ 一个号都不会
152
+ * 沉底 ⇒ 零效果;且 PR 正文举证的 `322/322/306/156/34`(峰值 322)同样 < 600
153
+ * ⇒ **对它自己描述的报障也零效果**。600 在 10-31 只把 max/mean 从 5.83 压到 2.84。
154
+ *
155
+ * ## 已知边界(如实登记,不掩饰)
156
+ *
157
+ * - **小池 + 高量**:2 个号各 850 次、阈值 300 ⇒ 两个号长期都超载 ⇒ `fresh` 为空
158
+ * ⇒ 退回哈希序 ⇒ **不生效**(此时不均衡度本身也只有 ≤2.0,可接受)。
159
+ * - **大池 + 高量**:20 个号均分 86 ⇒ 单号很难到 300 ⇒ **不生效**。
160
+ * 需要更激进时用环境变量下调(本仓库实测 5~8 号池最合适)。
161
+ * - 阈值按 **UTC+8 日界** 归零,跨日那一刻所有账号重新变 fresh。
162
+ */
163
+ export const DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS = 'DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS';
164
+ /** 缺省溢出阈值(今日请求数)。取值依据见 {@link DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS}。 */
165
+ export const DEFAULT_OVERFLOW_REQUESTS = 300;
166
+ /** 当前生效的溢出阈值;`0` = 关闭溢出均衡(纯哈希亲和)。 */
167
+ export function overflowRequestsThreshold(env = process.env) {
168
+ const raw = env[DSH_ZCODE_SESSION_BALANCE_OVERFLOW_REQUESTS];
169
+ if (typeof raw !== 'string')
170
+ return DEFAULT_OVERFLOW_REQUESTS;
171
+ const text = raw.trim();
172
+ if (text.length === 0)
173
+ return DEFAULT_OVERFLOW_REQUESTS;
174
+ /**
175
+ * ⚠️ **只认纯十进制整数**(`/^\d+$/`),不用 `Number.parseInt` 的宽松语义。
176
+ *
177
+ * 2026-10-31 对抗审计逐格实测的静默失效(两者都无日志):
178
+ * - `'1e3'`(用户想设 1000)⇒ `parseInt` 得 **1** ⇒ 每个号第一次请求就算超载
179
+ * ⇒ 全员超载 ⇒ 退回哈希序 ⇒ **等于没修**;
180
+ * - `'0x10'` / `'0b101'` ⇒ **0** ⇒ 把溢出整条**关掉**。
181
+ * 严格判据下这些值一律回落缺省(fail-safe 到 300),不会静默变成 1 或 0。
182
+ * `'0'` 仍然是合法的「关闭」值。
183
+ */
184
+ if (!/^\d+$/.test(text))
185
+ return DEFAULT_OVERFLOW_REQUESTS;
186
+ const parsed = Number.parseInt(text, 10);
187
+ return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_OVERFLOW_REQUESTS;
188
+ }
189
+ /**
190
+ * 按账号 id 索引「今日负载」读数。
191
+ *
192
+ * @param days - token-ledger 日聚合表(`readTokenLedgerDayMap()` 的返回)。
193
+ * @param provider - provider id(只统计该渠道的桶)。
194
+ * @param day - UTC+8 日键(`utc8DayKey(Date.now())`,由调用方传入以便单测)。
195
+ */
196
+ export function accountLoadIndex(days, provider, day) {
197
+ const index = new Map();
198
+ const buckets = days.get(day);
199
+ if (buckets === undefined)
200
+ return index;
201
+ for (const [key, bucket] of buckets) {
202
+ // 桶键 `channel|provider|account|model`(值里的 `|` 已转义成 `/`,split 恒 4 段)。
203
+ const parts = key.split('|');
204
+ if (parts.length !== 4)
205
+ continue;
206
+ const [, bucketProvider, accountId] = parts;
207
+ if (bucketProvider !== provider || accountId === undefined || accountId.length === 0)
208
+ continue;
209
+ const current = index.get(accountId) ?? { requests: 0 };
210
+ current.requests += bucket.requests ?? 0;
211
+ index.set(accountId, current);
212
+ }
213
+ return index;
214
+ }
215
+ /**
216
+ * 带**溢出**的会话排序:负载达阈值的账号沉底,其余按 rendezvous 序不变。
217
+ *
218
+ * ## 语义(三条)
219
+ *
220
+ * 1. **未超载**的账号之间:rendezvous 哈希序不变(跨请求稳定);
221
+ * 2. **已超载**的账号整组沉到最后 ⇒ **新会话**落到未超载账号上(负载分摊);
222
+ * 3. **全员超载**时退回纯哈希序(照常发请求让上游自己限流,不硬失败)。
223
+ *
224
+ * ⚠️ 这是**软溢出**而非硬排除:超载账号仍在候选里(排最后)。硬排除会让
225
+ * 「5 个号全超载」时选不出号 —— 而此时正确动作是照常发请求让上游限流。
226
+ *
227
+ * ## ⚠️⚠️ 它**不是**「已有会话保持亲和」——这是初版的错误表述,已订正
228
+ *
229
+ * 本函数是**无状态纯函数**,而调用方(`AccountPool.getAvailableAccountForSession`)
230
+ * **每个请求**都会重跑一次;池里**没有** `sessionId → accountId` 的记忆
231
+ * (全库只有 provider 级的 `activeZcodeAccountId`,那是记账归属,不是亲和状态)。
232
+ *
233
+ * ⇒ **一个正在跑的会话,一旦它所在账号的今日请求数达阈值,它的下一次请求就会
234
+ * 被排到别的账号上。** 本修法正是靠这次迁移把长会话的负载摊开的。
235
+ *
236
+ * 实测(8 号池 / 会话连跑 / 阈值 600):第 **601** 次、第 **1201** 次各迁移一次;
237
+ * 阈值低于当日均匀量时还会出现两种退化:①「**为 1 次请求换号**」(如
238
+ * `a×148 → d×1 → e×37`),②「**越过阈值后又弹回原号**」(全员超载 ⇒ 退回哈希序)。
239
+ *
240
+ * 若将来确实需要硬亲和,必须新增 `Map<sessionId, accountId>` + TTL;而那样会让
241
+ * 本修法对「长会话独占一个号」**重新失效**(两个目标互斥)—— 2026-10-31 审计
242
+ * 记录在案:本 PR 选择了「摊平负载」,代价是会话跨越阈值时会迁移一次。
243
+ *
244
+ * @param accounts - 候选账号(调用方已按 enabled / 模型限流 / tried 过滤)。
245
+ * @param sessionId - 非空会话标识。
246
+ * @param scope - 命名空间(provider id)。
247
+ * @param loads - 账号今日负载索引(缺账号 = 今日没跑过 = 负载 0)。
248
+ * @param thresholdRequests - 溢出阈值(今日请求数);`0` = 关闭溢出。
249
+ * @returns 新数组,不修改入参。
250
+ */
251
+ export function rankAccountsBySessionWithOverflow(accounts, sessionId, scope, loads, thresholdRequests) {
252
+ const ranked = rankAccountsBySession(accounts, sessionId, scope);
253
+ // 阈值 0 = 关闭;负数视同关闭(与 0 同语义,不抛错)。NaN 同样按关闭处理。
254
+ if (!Number.isFinite(thresholdRequests) || thresholdRequests <= 0)
255
+ return ranked;
256
+ /**
257
+ * ⚠️ 读数**归一**后再比较,不能直接用 `loads.get(id)?.requests`:
258
+ * 对抗审计实测,若某账号的读数是 `NaN` / 非数字,`x < T` 与 `x >= T`
259
+ * **两侧都为假** ⇒ 该账号会同时从 `fresh` 与 `overflowed` 里消失
260
+ * (即「从候选里凭空删掉一个可用账号」,比不均衡更糟)。
261
+ * 这里把「读不到 / 读不懂」一律按 0 处理,保证划分是**全覆盖且互斥**的。
262
+ */
263
+ const loadOf = (account) => {
264
+ const requests = loads.get(account.id)?.requests;
265
+ return typeof requests === 'number' && Number.isFinite(requests) && requests > 0 ? requests : 0;
266
+ };
267
+ const fresh = ranked.filter(a => loadOf(a) < thresholdRequests);
268
+ const overflowed = ranked.filter(a => loadOf(a) >= thresholdRequests);
269
+ /**
270
+ * ⚠️ 这条早退**删掉也和行为逐字节相同**(2026-10-31 对抗审计 5632 格穷举实测:
271
+ * `fresh` 为空时 `[...[], ...ranked] ≡ ranked`,`overflowed` 为空时同理)。
272
+ * 保留它只为「全员超载退回哈希序」这条语义在源码里可读,**不要**为它编用例
273
+ * 声称覆盖 —— 它是不可观测的,任何断言都只能证明它恒真。
274
+ */
275
+ if (fresh.length === 0 || overflowed.length === 0)
276
+ return ranked;
277
+ return [...fresh, ...overflowed];
278
+ }
279
+ //# sourceMappingURL=session-balance.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-balance.js","sourceRoot":"","sources":["../src/session-balance.ts"],"names":[],"mappings":"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"}
package/lib/sign.d.ts CHANGED
@@ -2,6 +2,102 @@
2
2
  export declare function sha256Hex(data: Uint8Array): Promise<string>;
3
3
  export declare function hmacSha256Hex(key: Uint8Array, data: Uint8Array): Promise<string>;
4
4
  export declare function buildCanonicalRequest(method: string, uri: string, query: string, headers: Map<string, string>, payloadHash: string): string;
5
- /** 签名一个华为请求;返回需合并到请求中的头映射。 */
5
+ /**
6
+ * query **值**是否落在「三种编码口径逐字节相同」的安全集内。
7
+ *
8
+ * ⚠️⚠️ 这是 `canonicalQueryOf` 的**配套护栏**(2026-10-30 审计 P2 D1):
9
+ * 在安全集内,原样 / `encodeURI` / `encodeURIComponent` 三种口径**逐字节相同**
10
+ * ⇒ 我们与服务端不可能分叉;出了安全集(`+`、空格、`&`、`=`、`%`)则
11
+ * **可能**分叉 ⇒ 应当**拒绝发这个请求**(宁可退化,也不要静默 401)。
12
+ *
13
+ * ⚠️ **安全集是「往返幂等」的那个集**(实测逐个形态核对):
14
+ *
15
+ * | wire 值 | decode → encode | 幂等? | 判据 |
16
+ * |---|---|---|---|
17
+ * | `abc` | `abc` | ✅ | 安全 |
18
+ * | `a%2Bb` | `a%2Bb` | ✅ | **安全**(`%2B` 解成 `+`、再编回 `%2B` ⇒ 逐字节相同) |
19
+ * | `a%20b` | `a%20b` | ✅ | **安全**(同上) |
20
+ * | `a+b` | `a%2Bb` | ❌ | **不安全**(裸 `+` 在表单语义下是空格 ⇒ 与服务端分叉) |
21
+ * | `a b` | `a%20b` | ❌ | **不安全**(裸空格) |
22
+ * | `a=b` | `a%3Db` | ❌ | **不安全**(`=` 会被重编码) |
23
+ * | `a&b` | `a%26b` | ❌ | **不安全**(`&` 会被重编码) |
24
+ * | `a%b` | `a%25b` | ❌ | **不安全**(畸形 `%` 序列;`safeDecode` 兜底返回原文) |
25
+ *
26
+ * ⇒ 判据 = 「**已百分号编码**的字符安全(`%XX` 形态),**裸**的
27
+ * `+` / 空格 / `&` / `=` / 裸 `%` 不安全」。
28
+ *
29
+ * ⚠️ **裸 `+` 是最危险的一个**:它在表单语义下是**空格**,而
30
+ * `decodeURIComponent` **不解** `+`(只解 `%XX`)⇒ 我们把它当字面加号、
31
+ * 服务端把它当空格 ⇒ 两侧算出**不同的 canonical** ⇒ `401 verify ak sk
32
+ * signature fail`。
33
+ */
34
+ export declare function isCanonicalQueryValueSafe(value: string): boolean;
35
+ /**
36
+ * 把 wire query 规范成 **key 排序** 的 canonical query(SDK-HMAC-SHA256 要求)。
37
+ *
38
+ * ## 为什么必须排序(2026-10-29 真机 2×2 实测定案)
39
+ *
40
+ * AgentCenter `/v1/agent-center/agents/useragents?offset=0&limit=100` 上,
41
+ * **唯一**失败的组合是「wire URL 按 offset,limit 顺序 + 签名也按该顺序」⇒
42
+ * `401 verify ak sk signature fail`;改成签名内排序后 200,且 wire URL 的
43
+ * 顺序无关(服务端按**自己收到的参数排序后**重算 canonical)。四轮重复 4/4
44
+ * 确定性。这符合华为云官方文档「CanonicalQuery 是按 key 字典序排列」的口径。
45
+ *
46
+ * ## 为什么现在才改 / 波及面(全部核对过)
47
+ *
48
+ * 本 signer 此前把 `url.search` **原样**拼进 canonical —— 对无 query 的请求
49
+ * (chat / builtin / gateway/config / benefit claim / ops delivery)是无操作;
50
+ * 对排序恰好等于字典序的请求也是无操作(`queue/status?model=X&task_id=Y`:m < t)。
51
+ * ⇒ 统一排序对既有调用方**零行为变化**,
52
+ * 只有 AgentCenter 这类「wire 顺序 ≠ 字典序」的多参数 GET 需要它。
53
+ *
54
+ * ⚠️ **更正**(2026-10-30 审计 P3 D9):原注释在这里列了
55
+ * `credit/usage?type=msg&id=…` 作为「已核对的既有调用方」——**本仓库没有这个
56
+ * 请求**(`grep -rn "credit/usage" src/` 只命中两处**注释**,零代码路径;
57
+ * 它是 IDE 侧的端点,本仓未实现)⇒ 它**不在波及面内**,也不构成「排序
58
+ * 与它无关」的证据。已删除该例。
59
+ *
60
+ * ⚠️ 只重排**签名里**的 query,wire URL 保持原样(调用方仍按原 URL 发请求)。
61
+ * 值的再编码用 `encodeURIComponent`:现网全部 query 值都在
62
+ * `[A-Za-z0-9_.-]` 安全集内(uuid、模型 id、`msg`、`DESKTOP`、数字),
63
+ * 三种编码口径(原样/encodeURI/encodeURIComponent)在此集合上逐字节相同。
64
+ *
65
+ * ⚠️ **安全集之外**(`+`、空格、`&`、`=`、`%`)⇒ canonical 可能与服务端
66
+ * 分叉 ⇒ **调用方必须先用 {@link isCanonicalQueryValueSafe} 校验**,
67
+ * 不安全就**不发这个请求**(见 `src/models.ts` 的 `fetchSignedGet`)。
68
+ */
69
+ export declare function canonicalQueryOf(search: string): string;
70
+ /**
71
+ * 一个 URL 的**全部 query 值**是否落在安全集内(见
72
+ * {@link isCanonicalQueryValueSafe})。
73
+ *
74
+ * ⚠️ **键也要查**:键同样参与 canonical 的编码往返,键出安全集一样会分叉。
75
+ * ⚠️ **裸键(无 `=`)也算安全**:服务端把它当空值 ⇒ canonical 侧也补 `=`
76
+ * ⇒ 两侧形态一致(实测 `?flag` → `flag=`)。
77
+ */
78
+ export declare function isSignedQueryValueSafe(url: string): boolean;
79
+ /**
80
+ * 签名一个华为请求;返回需合并到请求中的头映射。
81
+ *
82
+ * ⚠️⚠️⚠️ **query 值不在安全集内 ⇒ 抛错**(2026-10-30 第二轮审计 P1 N-3 修)。
83
+ *
84
+ * ⚠️ **为什么下沉到这一层**:安全集闸门原先只在 `src/models.ts` 的
85
+ * `fetchSignedGet` 里 ⇒ **4 条带 query 的签名 GET 只盖了 1 条**
86
+ * (`queue/status`、`ops/delivery`、benefit claim 那几条**不过闸门**)
87
+ * ⇒ 同一个 signer **两条腿两套防护口径**。
88
+ *
89
+ * ⇒ 现在判据在**签名器内部** ⇒ **所有**经它的请求都受保护
90
+ * (`src/models.ts` 的三个 GET + `src/codearts-credits.ts` 的两个 POST +
91
+ * `src/llm-adapter.ts` 的 chat 与 queue/status)。
92
+ *
93
+ * ⚠️ **抛错的后果**:调用方(`fetchSignedGet` / `signedSnapRequest`)的
94
+ * `try/catch` 会把它变成「这次请求没发出去」⇒ 目录/积分退化为**上一次成功
95
+ * 的值**或**空** ⇒ **静默降级**而非崩溃。⇒ 抛错是**安全**的方向
96
+ * (宁可少一个请求,也不要静默 401)。
97
+ *
98
+ * ⚠️ **现网不会触发**:本仓构造的 query 值全部在安全集内(实测 10/10 安全:
99
+ * `encodeURIComponent` 恒产安全集内的字符)⇒ 这道闸是**纯防御**,
100
+ * 防的是「上游改口径 / 用户手填特殊字符」。
101
+ */
6
102
  export declare function signRequestHuawei(ak: string, sk: string, securityToken: string, method: string, urlStr: string, body: Uint8Array, extraHeaders?: Readonly<Record<string, string>>): Promise<Map<string, string>>;
7
103
  //# sourceMappingURL=sign.d.ts.map
package/lib/sign.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGjE;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAItF;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,EAAE,MAAM,GAClB,MAAM,CAMR;AAED,8BAA8B;AAC9B,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC9C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgC9B"}
1
+ {"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGjE;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAItF;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,EAAE,MAAM,GAClB,MAAM,CAMR;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAWhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAavD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAc3D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC9C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyC9B"}