ai-zero-token 1.0.8 → 1.0.9

package/README.md

@@ -21,9 +21,16 @@ AI Zero Token provides a local CLI, web console, and HTTP gateway that expose sa
 - Account JSON import/export, including selected batch export.
 - Apply a saved account to local Codex by backing up and updating `~/.codex/auth.json`.
 - `gpt-image-2` image generation and JSON image editing through the ChatGPT internal Responses path.
+- Optional quota-exhaustion auto switch to the next saved API account with available quota.
 - Optional upstream proxy configuration for OAuth, model refresh, and gateway forwarding.
 - Local model discovery from the Codex model cache with manual refresh support.
 
+## Architecture
+
+![AI Zero Token architecture](docs/images/architecture-diagram.png)
+
+AI Zero Token keeps account tokens and gateway settings in local state, exposes OpenAI-compatible HTTP endpoints, and forwards requests to the selected ChatGPT/Codex OAuth account. The web console reads the same local state, so account switching, Codex auth application, proxy settings, and automatic switching are all controlled from one local place.
+
 ## Quick Start
 
 ```bash
@@ -50,6 +57,7 @@ The web console is the recommended entry point:
 - Export one account or selected accounts.
 - Apply a saved account to local Codex.
 - Configure the default text model and upstream proxy.
+- Enable automatic account switching when the active API account has exhausted its recorded quota.
 - Test `models`, `responses`, `chat.completions`, `images.generations`, and `images.edits`.
 
 ![AI Zero Token admin dashboard](docs/images/admin-dashboard.jpg)
@@ -187,6 +195,8 @@ The persistent state directory can be overridden with:
 AI_ZERO_TOKEN_HOME=/path/to/home azt start
 ```
 
+The web console settings are persisted in the same local state directory. The quota auto-switch option is stored as `autoSwitch.enabled`; when enabled, the gateway uses the latest saved quota snapshot and moves API traffic away from the active account once that snapshot shows a quota window is exhausted.
+
 The default request body limit is `32 MiB`, which is intended to make JSON base64 image references practical for local image editing. You can override it with:
 
 ```bash

package/README.zh-CN.md

@@ -21,9 +21,16 @@ AI Zero Token 是一个本地优先的 OpenAI 兼容网关，用于把 ChatGPT/C
 - 支持账号 JSON 导入/导出，以及复选框选择后的批量导出。
 - 支持把已保存账号应用到本机 Codex，并自动备份 `~/.codex/auth.json`。
 - 支持 `gpt-image-2` 文生图和 JSON 图生图。
+- 支持 API 账号额度耗尽后自动切换到下一个仍有额度的账号。
 - 支持上游代理配置，覆盖 OAuth、模型刷新和接口转发。
 - 模型列表优先读取本机 Codex 模型缓存，并支持手动刷新。
 
+## 技术架构
+
+![AI Zero Token 技术架构图](docs/images/architecture-diagram.png)
+
+AI Zero Token 会把账号 token、网关配置和运行状态保存在本地，通过 OpenAI 兼容接口转发到当前选中的 ChatGPT/Codex OAuth 账号。管理页读取同一份本地状态，因此账号切换、应用到 Codex、代理配置和额度耗尽自动切换都可以在本地统一管理。
+
 ## 快速开始
 
 ```bash
@@ -50,6 +57,7 @@ http://127.0.0.1:8787/v1
 - 导出单个账号或勾选导出多个账号。
 - 将已保存账号应用到本机 Codex。
 - 配置默认文本模型和上游代理。
+- 开启当前 API 账号额度耗尽后的自动切换。
 - 测试 `models`、`responses`、`chat.completions`、`images.generations`、`images.edits`。
 
 ![AI Zero Token 管理页](docs/images/admin-dashboard.jpg)
@@ -187,6 +195,8 @@ AZT_CORS_ORIGIN=http://127.0.0.1:8124,http://localhost:3000 azt start
 AI_ZERO_TOKEN_HOME=/path/to/home azt start
 ```
 
+管理页里的配置会保存在同一个本地状态目录。额度耗尽自动切换会保存为 `autoSwitch.enabled`；开启后，网关会根据最近一次保存的额度快照判断当前 API 账号是否耗尽，并把 API 流量切到下一个仍有额度的账号。
+
 默认请求体上限是 `32 MiB`，用于让 JSON base64 图片在本地图片编辑场景里更实用。可以用下面的环境变量覆盖：
 
 ```bash

package/dist/core/providers/http-client.js

@@ -168,7 +168,7 @@ async function loadNetworkProxySettings() {
 }
 async function requestText(init) {
   const requestId = nextRequestId();
-  const proxy = await loadNetworkProxySettings();
+  const proxy = init.ignoreProxy ? void 0 : init.proxyOverride ?? await loadNetworkProxySettings();
   const useCurlOnly = process.env.OAUTH_DEMO_USE_CURL === "1";
   const useConfiguredProxy = !!proxy?.enabled && !!proxy.url.trim();
   const timeoutMs = init.timeoutMs;

package/dist/core/services/auth-service.js

@@ -53,6 +53,83 @@ class AuthService {
       isActive: profile.profileId === activeProfileId
     };
   }
+  getQuotaPercents(profile) {
+    const quota = profile.quota;
+    if (!quota) {
+      return [];
+    }
+    return [quota.primaryUsedPercent, quota.secondaryUsedPercent].filter(
+      (value) => typeof value === "number" && Number.isFinite(value)
+    );
+  }
+  isQuotaExhausted(profile) {
+    const percents = this.getQuotaPercents(profile);
+    return percents.length > 0 && percents.some((value) => value >= 100);
+  }
+  hasKnownAvailableQuota(profile) {
+    const percents = this.getQuotaPercents(profile);
+    return percents.length > 0 && percents.every((value) => value < 100);
+  }
+  getQuotaUsageScore(profile) {
+    const percents = this.getQuotaPercents(profile);
+    if (percents.length === 0) {
+      return 100;
+    }
+    return Math.max(...percents);
+  }
+  async maybeAutoSwitchProfile(profile, provider) {
+    const settings = await this.configService.getSettings();
+    if (!settings.autoSwitch.enabled || !this.isQuotaExhausted(profile)) {
+      return profile;
+    }
+    const [profiles, codexStatus] = await Promise.all([
+      listProfiles(),
+      getCodexAuthStatus()
+    ]);
+    const currentIndex = profiles.findIndex((item) => item.profileId === profile.profileId);
+    const codexAccountId = codexStatus.accountId;
+    const candidates = profiles.map((item, index) => ({
+      profile: item,
+      index,
+      distance: currentIndex >= 0 ? (index - currentIndex + profiles.length) % profiles.length : index + 1
+    })).filter((item) => item.profile.provider === provider && item.profile.profileId !== profile.profileId).filter((item) => this.hasKnownAvailableQuota(item.profile)).sort((left, right) => {
+      const leftCodexConflict = codexAccountId && left.profile.accountId === codexAccountId ? 1 : 0;
+      const rightCodexConflict = codexAccountId && right.profile.accountId === codexAccountId ? 1 : 0;
+      const codexDiff = leftCodexConflict - rightCodexConflict;
+      if (codexDiff !== 0) {
+        return codexDiff;
+      }
+      const distanceDiff = left.distance - right.distance;
+      if (distanceDiff !== 0) {
+        return distanceDiff;
+      }
+      const usageDiff = this.getQuotaUsageScore(left.profile) - this.getQuotaUsageScore(right.profile);
+      if (usageDiff !== 0) {
+        return usageDiff;
+      }
+      const leftCapturedAt = left.profile.quota?.capturedAt ?? 0;
+      const rightCapturedAt = right.profile.quota?.capturedAt ?? 0;
+      if (leftCapturedAt !== rightCapturedAt) {
+        return leftCapturedAt - rightCapturedAt;
+      }
+      return right.profile.expires - left.profile.expires;
+    }).map((item) => item.profile);
+    const nextProfile = candidates[0];
+    if (!nextProfile) {
+      return profile;
+    }
+    const activated = await setActiveProfile(nextProfile.profileId);
+    if (!activated) {
+      return profile;
+    }
+    console.info("[auth] auto switched active profile after quota exhaustion", {
+      provider,
+      fromProfileId: profile.profileId,
+      toProfileId: activated.profileId,
+      avoidedCodexAccount: Boolean(codexAccountId && activated.accountId !== codexAccountId)
+    });
+    return this.toManagedProfile(activated);
+  }
   async login(provider) {
     if (provider !== "openai-codex") {
       throw new Error(`\u6682\u4E0D\u652F\u6301 provider: ${provider}`);
@@ -151,8 +228,9 @@ class AuthService {
     }
     await removeProfile(profileId);
   }
-  async requireUsableProfile(provider = "openai-codex") {
-    const profile = await this.getActiveProfile(provider);
+  async requireUsableProfile(provider = "openai-codex", options) {
+    const activeProfile = await this.getActiveProfile(provider);
+    const profile = activeProfile ? options?.skipAutoSwitch ? activeProfile : await this.maybeAutoSwitchProfile(activeProfile, provider) : null;
     if (!profile) {
       throw new Error(`\u8FD8\u6CA1\u6709\u767B\u5F55 ${provider}\u3002\u5148\u8FD0\u884C azt login`);
     }
@@ -185,7 +263,9 @@ class AuthService {
   async syncActiveProfileQuota(provider = "openai-codex", options) {
     let profile;
     try {
-      profile = await this.requireUsableProfile(provider);
+      profile = await this.requireUsableProfile(provider, {
+        skipAutoSwitch: options?.skipAutoSwitch
+      });
     } catch (error) {
       if (options?.suppressErrors) {
         return;
@@ -203,10 +283,14 @@ class AuthService {
           text: { verbosity: "low" }
         }
       });
-      await this.updateProfileQuota(profile.profileId, result.quota, provider);
+      await this.updateProfileQuota(profile.profileId, result.quota, provider, {
+        skipAutoSwitch: options?.skipAutoSwitch
+      });
     } catch (error) {
       const quota = error.quota;
-      await this.updateProfileQuota(profile.profileId, quota, provider);
+      await this.updateProfileQuota(profile.profileId, quota, provider, {
+        skipAutoSwitch: options?.skipAutoSwitch
+      });
       if (!options?.suppressErrors) {
         throw error;
       }
@@ -217,11 +301,11 @@ class AuthService {
       });
     }
   }
-  async updateProfileQuota(profileId, quota, provider = "openai-codex") {
+  async updateProfileQuota(profileId, quota, provider = "openai-codex", options) {
     if (!quota) {
       return;
     }
-    await updateProfile(profileId, (profile) => {
+    const updated = await updateProfile(profileId, (profile) => {
       if (profile.provider !== provider) {
         return profile;
       }
@@ -230,6 +314,13 @@ class AuthService {
         quota
       };
     });
+    if (options?.skipAutoSwitch || !updated || updated.provider !== provider || !this.isQuotaExhausted(updated)) {
+      return;
+    }
+    const activeProfile = await this.getActiveProfile(provider);
+    if (activeProfile?.profileId === updated.profileId) {
+      await this.maybeAutoSwitchProfile(updated, provider);
+    }
   }
   async getStatus() {
     const [profile, profiles] = await Promise.all([

package/dist/core/services/config-service.js

@@ -42,8 +42,10 @@ class ConfigService {
     return next;
   }
   async setNetworkProxy(params) {
-    const url = params.url?.trim() ?? "";
-    const noProxy = params.noProxy?.trim() || "localhost,127.0.0.1,::1";
+    const settings = await this.getSettings();
+    const requestedUrl = params.url?.trim() ?? "";
+    const url = requestedUrl || (!params.enabled ? settings.networkProxy.url : "");
+    const noProxy = params.noProxy?.trim() || settings.networkProxy.noProxy || "localhost,127.0.0.1,::1";
     if (params.enabled) {
       if (!url) {
         throw new Error("\u542F\u7528\u4EE3\u7406\u65F6\u5FC5\u987B\u586B\u5199\u4EE3\u7406\u5730\u5740\u3002");
@@ -59,7 +61,6 @@ class ConfigService {
         throw new Error("\u4EE3\u7406\u5730\u5740\u4EC5\u652F\u6301 http\u3001https\u3001socks4\u3001socks4a\u3001socks5 \u6216 socks5h\u3002");
       }
     }
-    const settings = await this.getSettings();
     const next = {
       ...settings,
       networkProxy: {
@@ -71,6 +72,17 @@ class ConfigService {
     await saveSettings(next);
     return next;
   }
+  async setAutoSwitch(params) {
+    const settings = await this.getSettings();
+    const next = {
+      ...settings,
+      autoSwitch: {
+        enabled: params.enabled
+      }
+    };
+    await saveSettings(next);
+    return next;
+  }
   async getServerConfig() {
     const settings = await this.getSettings();
     return settings.server;

package/dist/core/services/version-service.js

@@ -56,19 +56,7 @@ class VersionService {
     const manifest = await readPackageManifest();
     const registryUrl = `https://registry.npmjs.org/${encodeURIComponent(manifest.name)}/latest`;
     try {
-      const response = await requestText({
-        method: "GET",
-        url: registryUrl,
-        timeoutMs: 5e3
-      });
-      if (response.status < 200 || response.status >= 300) {
-        throw new Error(`npm registry returned ${response.status}`);
-      }
-      const parsed = JSON.parse(response.body);
-      const latestVersion = typeof parsed.version === "string" && parsed.version ? parsed.version : void 0;
-      if (!latestVersion) {
-        throw new Error("npm registry did not return a version");
-      }
+      const latestVersion = await this.fetchNpmLatestVersion(registryUrl);
       const needsUpdate = compareSemver(manifest.version, latestVersion) < 0;
       return {
         packageName: manifest.name,
@@ -91,6 +79,23 @@ class VersionService {
       };
     }
   }
+  async fetchNpmLatestVersion(registryUrl) {
+    const response = await requestText({
+      method: "GET",
+      url: registryUrl,
+      timeoutMs: 5e3,
+      ignoreProxy: true
+    });
+    if (response.status < 200 || response.status >= 300) {
+      throw new Error(`npm registry returned ${response.status}`);
+    }
+    const parsed = JSON.parse(response.body);
+    const latestVersion = typeof parsed.version === "string" && parsed.version ? parsed.version : void 0;
+    if (!latestVersion) {
+      throw new Error("npm registry did not return a version");
+    }
+    return latestVersion;
+  }
 }
 export {
   VersionService

package/dist/core/store/settings-store.js

@@ -15,6 +15,9 @@ function createDefaultSettings() {
       url: "",
       noProxy: "localhost,127.0.0.1,::1"
     },
+    autoSwitch: {
+      enabled: false
+    },
     server: {
       host: "0.0.0.0",
       port: 8787
@@ -36,6 +39,9 @@ async function loadSettings() {
         url: parsed.networkProxy?.url ?? defaults.networkProxy.url,
         noProxy: parsed.networkProxy?.noProxy ?? defaults.networkProxy.noProxy
       },
+      autoSwitch: {
+        enabled: parsed.autoSwitch?.enabled ?? defaults.autoSwitch.enabled
+      },
       server: {
         host: parsed.server?.host ?? defaults.server.host,
         port: parsed.server?.port ?? defaults.server.port