codex-slot 0.1.19 → 0.1.20

package/dist/app/account-service.js

@@ -23,7 +23,7 @@ const text_1 = require("../text");
  * @throws 当源目录缺少必要认证文件或写入失败时抛出异常。
  */
 function importAccount(slotName, codexHome) {
-    const sourceHome = codexHome ? (0, config_1.expandHome)(codexHome) : process.env.HOME ?? "";
+    const sourceHome = codexHome ? (0, config_1.expandHome)(codexHome) : (0, config_1.getUserHomeDir)();
     const managedHome = (0, config_1.getManagedHome)(slotName);
     (0, account_store_1.cloneCodexAuthState)(sourceHome, managedHome);
     return {
@@ -104,22 +104,22 @@ function renameAccount(oldName, newName) {
     };
     config.accounts[index] = renamedAccount;
     (0, config_1.saveConfig)(config);
-    const state = (0, state_1.loadState)();
-    if (state.account_blocks[oldName]) {
-        state.account_blocks[newName] = state.account_blocks[oldName];
-        delete state.account_blocks[oldName];
-    }
-    if (state.usage_cache[oldName]) {
-        state.usage_cache[newName] = {
-            ...state.usage_cache[oldName],
-            accountId: newName
-        };
-        delete state.usage_cache[oldName];
-    }
-    if (state.scheduler_stats[oldName]) {
-        state.scheduler_stats[newName] = state.scheduler_stats[oldName];
-        delete state.scheduler_stats[oldName];
-    }
-    (0, state_1.saveState)(state);
+    (0, state_1.updateState)((state) => {
+        if (state.account_blocks[oldName]) {
+            state.account_blocks[newName] = state.account_blocks[oldName];
+            delete state.account_blocks[oldName];
+        }
+        if (state.usage_cache[oldName]) {
+            state.usage_cache[newName] = {
+                ...state.usage_cache[oldName],
+                accountId: newName
+            };
+            delete state.usage_cache[oldName];
+        }
+        if (state.scheduler_stats[oldName]) {
+            state.scheduler_stats[newName] = state.scheduler_stats[oldName];
+            delete state.scheduler_stats[oldName];
+        }
+    });
     return renamedAccount;
 }

package/dist/codex-auth.js

@@ -9,6 +9,7 @@ exports.deactivateManagedCodexAuth = deactivateManagedCodexAuth;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const account_store_1 = require("./account-store");
+const config_1 = require("./config");
 const state_1 = require("./state");
 /**
  * 返回默认的 Codex HOME 目录。
@@ -16,7 +17,7 @@ const state_1 = require("./state");
  * @returns 当前进程 HOME；未设置时返回空字符串。
  */
 function getDefaultCodexHome() {
-    return process.env.HOME ?? "";
+    return (0, config_1.getUserHomeDir)();
 }
 /**
  * 读取目标 HOME 下 `.codex/accounts` 目录中的所有 `.auth.json` 文件内容。

package/dist/codex-config.js

@@ -21,7 +21,7 @@ const PROVIDER_BLOCK_END_MARKER = "# <<< cslot provider:cslot <<<";
  * @returns 默认 `config.toml` 绝对路径。
  */
 function getDefaultCodexConfigPath() {
-    return node_path_1.default.join(process.env.HOME ?? "", ".codex", "config.toml");
+    return node_path_1.default.join((0, config_1.getUserHomeDir)(), ".codex", "config.toml");
 }
 /**
  * 原子方式写入目标文件，避免写入过程中留下半截配置。

package/dist/config.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUserHomeDir = getUserHomeDir;
 exports.generateServerApiKey = generateServerApiKey;
 exports.getCslotHome = getCslotHome;
 exports.getConfigPath = getConfigPath;
@@ -56,6 +57,14 @@ const configSchema = zod_1.z.object({
     }),
     accounts: zod_1.z.array(managedAccountSchema).default([])
 });
+/**
+ * 解析当前进程应使用的用户 HOME 目录，兼容 Windows 缺少 `HOME` 的场景。
+ *
+ * @returns 当前用户 HOME 目录；优先复用显式环境变量，兜底使用 `os.homedir()`。
+ */
+function getUserHomeDir() {
+    return process.env.HOME || process.env.USERPROFILE || node_os_1.default.homedir();
+}
 /**
  * 生成新的本地服务 API Key。
  *
@@ -74,7 +83,7 @@ function generateServerApiKey() {
  * @throws 当目录无法创建时抛出文件系统错误。
  */
 function getCslotHome() {
-    const home = node_path_1.default.join(node_os_1.default.homedir(), ".cslot");
+    const home = node_path_1.default.join(getUserHomeDir(), ".cslot");
     // 先创建 cslot 根目录，后续命令统一基于该目录读写状态。
     node_fs_1.default.mkdirSync(home, { recursive: true });
     node_fs_1.default.mkdirSync(node_path_1.default.join(home, "homes"), { recursive: true });
@@ -112,11 +121,12 @@ function getServiceLogPath() {
  * @returns 展开后的绝对或原始路径。
  */
 function expandHome(input) {
+    const homeDir = getUserHomeDir();
     if (input === "~") {
-        return node_os_1.default.homedir();
+        return homeDir;
     }
     if (input.startsWith("~/")) {
-        return node_path_1.default.join(node_os_1.default.homedir(), input.slice(2));
+        return node_path_1.default.join(homeDir, input.slice(2));
     }
     return input;
 }

package/dist/login.js

@@ -23,7 +23,8 @@ async function loginManagedAccount(accountId) {
         const child = (0, node_child_process_1.spawn)("codex", ["login"], {
             env: {
                 ...process.env,
-                HOME: managedHome
+                HOME: managedHome,
+                USERPROFILE: managedHome
             },
             stdio: "inherit"
         });

package/dist/proxy-retry-service.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proxyResponsesWithRetry = void 0;
+exports.createProxyRetryService = createProxyRetryService;
+const account_store_1 = require("./account-store");
+const config_1 = require("./config");
+const scheduler_1 = require("./scheduler");
+const state_repository_1 = require("./state-repository");
+const state_1 = require("./state");
+const text_1 = require("./text");
+const upstream_client_1 = require("./upstream-client");
+const upstream_error_policy_1 = require("./upstream-error-policy");
+const usage_sync_1 = require("./usage-sync");
+/**
+ * 为当前请求失败的账号设置临时熔断状态，避免短时间内被重复选中。
+ *
+ * @param accountId 账号标识。
+ * @param reason 本地状态中记录的失败原因。
+ * @param blockSeconds 熔断持续秒数。
+ * @returns 无返回值。
+ * @throws 当状态写入失败时透传底层异常。
+ */
+function markAccountFailure(dependencies, accountId, reason, blockSeconds) {
+    dependencies.setAccountBlock(accountId, Math.floor(Date.now() / 1000) + blockSeconds, reason);
+}
+/**
+ * 提取上游响应中允许透传给客户端的响应头。
+ *
+ * @param headers 上游响应头对象。
+ * @returns 可透传响应头。
+ * @throws 无显式抛出。
+ */
+function pickResponseHeaders(headers) {
+    const picked = {};
+    const contentType = headers["content-type"];
+    const cacheControl = headers["cache-control"];
+    if (typeof contentType === "string") {
+        picked["content-type"] = contentType;
+    }
+    if (typeof cacheControl === "string") {
+        picked["cache-control"] = cacheControl;
+    }
+    return picked;
+}
+/**
+ * 构造统一错误响应结果。
+ *
+ * @param statusCode HTTP 状态码。
+ * @param payload 响应体。
+ * @param headers 可选响应头。
+ * @returns 代理服务可直接写回的 send 结果。
+ * @throws 无显式抛出。
+ */
+function buildSendResult(statusCode, payload, headers) {
+    return {
+        type: "send",
+        statusCode,
+        payload,
+        headers
+    };
+}
+/**
+ * 对单个候选账号发送上游请求。
+ *
+ * @param picked 当前候选账号。
+ * @param accessToken 可用 access token。
+ * @param requestHeaders 原始请求头。
+ * @param requestBody 原始请求体。
+ * @returns 上游响应。
+ * @throws 当网络层或 undici 请求失败时透传底层异常。
+ */
+async function sendWithAccount(dependencies, picked, accessToken, requestHeaders, requestBody) {
+    const config = dependencies.loadConfig();
+    const auth = dependencies.readAuthFile(picked.account.codex_home);
+    return await dependencies.sendCodexResponsesRequest({
+        codexBaseUrl: config.upstream.codex_base_url,
+        requestHeaders,
+        accessToken,
+        accountIdHeader: auth?.tokens?.account_id,
+        body: requestBody
+    });
+}
+/**
+ * 创建代理重试服务。
+ *
+ * 业务含义：
+ * 1. 默认依赖绑定真实配置、账号、状态和上游请求。
+ * 2. 测试或未来扩展可注入替代依赖，避免业务重试逻辑硬绑 I/O 实现。
+ *
+ * @param overrides 可选依赖覆盖项。
+ * @returns 代理重试服务实例。
+ * @throws 无显式抛出。
+ */
+function createProxyRetryService(overrides) {
+    const dependencies = {
+        loadConfig: config_1.loadConfig,
+        listCandidateAccounts: scheduler_1.listCandidateAccounts,
+        readAuthFile: account_store_1.readAuthFile,
+        sendCodexResponsesRequest: upstream_client_1.sendCodexResponsesRequest,
+        refreshAccountTokens: usage_sync_1.refreshAccountTokens,
+        setAccountBlock: state_1.setAccountBlock,
+        recordAccountScheduleSuccess: state_repository_1.recordAccountScheduleSuccess,
+        ...overrides
+    };
+    return {
+        async proxyResponsesWithRetry(requestHeaders, requestBody) {
+            const candidates = dependencies.listCandidateAccounts();
+            if (candidates.length === 0) {
+                return buildSendResult(503, {
+                    error: {
+                        message: (0, text_1.bi)("当前没有可用账号", "No available account"),
+                        type: "no_available_account"
+                    }
+                });
+            }
+            let lastErrorPayload = {
+                error: {
+                    message: (0, text_1.bi)("所有账号都请求失败", "All accounts failed"),
+                    type: "all_accounts_failed"
+                }
+            };
+            let lastStatusCode = 503;
+            for (const picked of candidates) {
+                const auth = dependencies.readAuthFile(picked.account.codex_home);
+                let accessToken = auth?.tokens?.access_token;
+                if (!accessToken) {
+                    markAccountFailure(dependencies, picked.account.id, "invalid_account_auth", 10 * 60);
+                    lastStatusCode = 503;
+                    lastErrorPayload = {
+                        error: {
+                            message: (0, text_1.bi)(`账号 ${picked.account.id} 缺少 access_token`, `Account ${picked.account.id} is missing access_token`),
+                            type: "invalid_account_auth"
+                        }
+                    };
+                    continue;
+                }
+                let upstream;
+                try {
+                    upstream = await sendWithAccount(dependencies, picked, accessToken, requestHeaders, requestBody);
+                }
+                catch (error) {
+                    lastStatusCode = 503;
+                    if ((0, upstream_error_policy_1.isNetworkUnavailableError)(error)) {
+                        lastErrorPayload = (0, upstream_error_policy_1.buildNetworkUnavailablePayload)(picked.account.id, error);
+                        continue;
+                    }
+                    markAccountFailure(dependencies, picked.account.id, "request_failed", 60);
+                    lastErrorPayload = {
+                        error: {
+                            message: `账号 ${picked.account.id} 请求上游失败: ${error instanceof Error ? error.message : String(error)}`,
+                            type: "account_request_failed"
+                        }
+                    };
+                    continue;
+                }
+                if (upstream.statusCode === 401) {
+                    try {
+                        const refreshed = await dependencies.refreshAccountTokens(picked.account.id);
+                        accessToken = refreshed.tokens?.access_token ?? accessToken;
+                        upstream = await sendWithAccount(dependencies, picked, accessToken, requestHeaders, requestBody);
+                    }
+                    catch (error) {
+                        lastStatusCode = 503;
+                        if ((0, upstream_error_policy_1.isNetworkUnavailableError)(error)) {
+                            lastErrorPayload = (0, upstream_error_policy_1.buildNetworkUnavailablePayload)(picked.account.id, error);
+                            continue;
+                        }
+                        markAccountFailure(dependencies, picked.account.id, "token_refresh_failed", 10 * 60);
+                        lastErrorPayload = {
+                            error: {
+                                message: `账号 ${picked.account.id} 刷新 token 失败: ${error instanceof Error ? error.message : String(error)}`,
+                                type: "account_token_refresh_failed"
+                            }
+                        };
+                        continue;
+                    }
+                }
+                const responseHeaders = pickResponseHeaders(upstream.headers);
+                if (upstream.statusCode === 429 || upstream.statusCode === 403) {
+                    const errorText = await upstream.body.text();
+                    const block = (0, upstream_error_policy_1.resolveBlockWindow)(picked, errorText);
+                    dependencies.setAccountBlock(picked.account.id, block.until, block.reason);
+                    lastStatusCode = upstream.statusCode;
+                    lastErrorPayload = {
+                        error: {
+                            message: `账号 ${picked.account.id} 受限: ${errorText}`,
+                            type: "account_rate_limited"
+                        }
+                    };
+                    continue;
+                }
+                if (upstream.statusCode >= 400) {
+                    const errorText = await upstream.body.text();
+                    if ((0, upstream_error_policy_1.isUsageLimitErrorText)(errorText)) {
+                        const block = (0, upstream_error_policy_1.resolveBlockWindow)(picked, errorText);
+                        dependencies.setAccountBlock(picked.account.id, block.until, block.reason);
+                        lastStatusCode = upstream.statusCode;
+                        lastErrorPayload = {
+                            error: {
+                                message: `账号 ${picked.account.id} 命中额度限制: ${errorText}`,
+                                type: "account_usage_limited"
+                            }
+                        };
+                        continue;
+                    }
+                    if (upstream.statusCode >= 500) {
+                        markAccountFailure(dependencies, picked.account.id, "upstream_5xx", 60);
+                        lastStatusCode = upstream.statusCode;
+                        lastErrorPayload = {
+                            error: {
+                                message: `账号 ${picked.account.id} 上游异常: ${errorText}`,
+                                type: "account_upstream_failed"
+                            }
+                        };
+                        continue;
+                    }
+                    return buildSendResult(upstream.statusCode, errorText, {
+                        "content-type": responseHeaders["content-type"] ?? "application/json",
+                        ...responseHeaders
+                    });
+                }
+                dependencies.recordAccountScheduleSuccess(picked.account.id);
+                return {
+                    type: "proxy",
+                    statusCode: upstream.statusCode,
+                    headers: {
+                        ...responseHeaders,
+                        connection: "keep-alive"
+                    },
+                    body: upstream.body
+                };
+            }
+            return buildSendResult(lastStatusCode, lastErrorPayload);
+        }
+    };
+}
+exports.proxyResponsesWithRetry = createProxyRetryService().proxyResponsesWithRetry;

package/dist/scheduler-strategy.js

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSoftLocalBlocked = isSoftLocalBlocked;
+exports.rankAccountStatuses = rankAccountStatuses;
+const CRITICAL_WEEKLY_LEFT_PERCENT = 5;
+const LOW_WEEKLY_LEFT_PERCENT = 15;
+const FIVE_HOUR_WASTE_HORIZON_SECONDS = 5 * 60 * 60;
+const WEEKLY_WASTE_HORIZON_SECONDS = 7 * 24 * 60 * 60;
+const RECENT_USE_RECOVERY_SECONDS = 30 * 60;
+/**
+ * 判断账号当前是否仅命中可忽略的短期本地熔断。
+ *
+ * 业务含义：
+ * 1. 这类熔断通常来自瞬时请求失败、上游 5xx 或 token 短暂刷新失败。
+ * 2. 当所有候选账号都只剩这类熔断时，调度器允许兜底尝试，避免把网络抖动误判成无账号可用。
+ *
+ * @param status 账号运行时状态；必须来自当前调度快照，不能混用历史状态。
+ * @returns `true` 表示账号只存在可兜底忽略的短期熔断；否则返回 `false`。
+ * @throws 无显式抛出。
+ */
+function isSoftLocalBlocked(status) {
+    if (!status.localBlockUntil || status.localBlockUntil * 1000 <= Date.now()) {
+        return false;
+    }
+    return [
+        "request_failed",
+        "upstream_5xx",
+        "temporary_5m_limit",
+        "token_refresh_failed"
+    ].includes(status.localBlockReason ?? "");
+}
+/**
+ * 将账号额度百分比归一化成评分字段。
+ *
+ * 业务含义：
+ * 1. 百分比越高代表剩余额度越多。
+ * 2. 缺失值按中性值处理，避免因为远端 usage 暂时不可取就把账号完全打死。
+ *
+ * @param value 原始百分比；允许为空、缺失或非数字。
+ * @returns 0 到 1 之间的评分；缺失或非法值返回 0.5。
+ * @throws 无显式抛出。
+ */
+function normalizePercent(value) {
+    if (value === null || value === undefined || Number.isNaN(value)) {
+        return 0.5;
+    }
+    return Math.max(0, Math.min(1, value / 100));
+}
+/**
+ * 计算指定重置窗口的浪费紧迫度。
+ *
+ * 业务含义：
+ * 1. 越接近重置，当前剩余额度越容易浪费。
+ * 2. 超过观察窗口的重置时间只保留最低紧迫度，避免远期窗口主导当前调度。
+ *
+ * @param resetAt 重置时间，Unix 秒时间戳；缺失时代表无法确定重置时间。
+ * @param horizonSeconds 观察窗口秒数；必须大于 0。
+ * @param nowMs 当前时间毫秒数；调用方应在一次调度内传入同一个时间，保证评分一致。
+ * @returns 0 到 1 之间的紧迫度；已过期或无效时间返回 0。
+ * @throws 无显式抛出。
+ */
+function computeResetUrgency(resetAt, horizonSeconds, nowMs) {
+    if (!resetAt || horizonSeconds <= 0) {
+        return 0;
+    }
+    const secondsUntilReset = resetAt - Math.floor(nowMs / 1000);
+    if (secondsUntilReset <= 0) {
+        return 0;
+    }
+    return Math.max(0.05, Math.min(1, (horizonSeconds - secondsUntilReset) / horizonSeconds));
+}
+/**
+ * 计算 5 小时窗口的额度浪费压力。
+ *
+ * 业务含义：
+ * 1. 5 小时剩余额度越多，且越接近重置，越应该尽快消费。
+ * 2. 缺失重置时间时仅保留低权重余额信号，避免短窗口误导周窗口调度。
+ *
+ * @param status 账号运行时状态；必须包含当前 5 小时剩余额度与重置时间。
+ * @param nowMs 当前时间毫秒数；用于统一本次调度的时间基准。
+ * @returns 0 到 1 之间的 5 小时浪费压力评分。
+ * @throws 无显式抛出。
+ */
+function computeFiveHourWastePressure(status, nowMs) {
+    const leftScore = normalizePercent(status.fiveHourLeftPercent);
+    if (!status.fiveHourResetsAt) {
+        return leftScore * 0.2;
+    }
+    return leftScore * computeResetUrgency(status.fiveHourResetsAt, FIVE_HOUR_WASTE_HORIZON_SECONDS, nowMs);
+}
+/**
+ * 计算周窗口的额度浪费压力。
+ *
+ * 业务含义：
+ * 1. 周窗口是更大的不可累积额度窗口，快重置且剩余额度多时应优先使用。
+ * 2. 缺失周重置时间时仅保留低权重余额信号，避免未知数据压过明确窗口。
+ *
+ * @param status 账号运行时状态；必须包含当前周剩余额度与重置时间。
+ * @param nowMs 当前时间毫秒数；用于统一本次调度的时间基准。
+ * @returns 0 到 1 之间的周窗口浪费压力评分。
+ * @throws 无显式抛出。
+ */
+function computeWeeklyWastePressure(status, nowMs) {
+    const leftScore = normalizePercent(status.weeklyLeftPercent);
+    if (!status.weeklyResetsAt) {
+        return leftScore * 0.1;
+    }
+    return leftScore * computeResetUrgency(status.weeklyResetsAt, WEEKLY_WASTE_HORIZON_SECONDS, nowMs);
+}
+/**
+ * 计算 5 小时窗口调度时可借用的周额度承载系数。
+ *
+ * 业务含义：
+ * 1. 周额度越少，越不应该为了短窗口快重置继续打该账号。
+ * 2. 低于关键线时只保留极低短窗口权重，除非没有更健康的账号。
+ *
+ * @param status 账号运行时状态；必须包含当前周剩余额度。
+ * @returns 0 到 1 之间的周额度承载系数。
+ * @throws 无显式抛出。
+ */
+function computeWeeklyCapacityFactor(status) {
+    const weeklyLeft = status.weeklyLeftPercent;
+    if (weeklyLeft === null || weeklyLeft === undefined || Number.isNaN(weeklyLeft)) {
+        return 0.7;
+    }
+    if (weeklyLeft <= CRITICAL_WEEKLY_LEFT_PERCENT) {
+        return 0.05;
+    }
+    if (weeklyLeft < LOW_WEEKLY_LEFT_PERCENT) {
+        return 0.2;
+    }
+    if (weeklyLeft < 30) {
+        return 0.55;
+    }
+    return 1;
+}
+/**
+ * 计算周额度健康度。
+ *
+ * 业务含义：
+ * 1. 该分数不是“周额度多就绝对优先”，而是用于保护低周余额账号。
+ * 2. 低于保护线时非线性降权，避免个别账号提前打穿周窗口。
+ *
+ * @param status 账号运行时状态；必须包含当前周剩余额度。
+ * @returns 0 到 1 之间的周额度健康评分。
+ * @throws 无显式抛出。
+ */
+function computeWeeklyHealthScore(status) {
+    const weeklyLeft = status.weeklyLeftPercent;
+    if (weeklyLeft === null || weeklyLeft === undefined || Number.isNaN(weeklyLeft)) {
+        return 0.5;
+    }
+    if (weeklyLeft <= CRITICAL_WEEKLY_LEFT_PERCENT) {
+        return 0;
+    }
+    if (weeklyLeft < LOW_WEEKLY_LEFT_PERCENT) {
+        return normalizePercent(weeklyLeft) * 0.35;
+    }
+    return normalizePercent(weeklyLeft);
+}
+/**
+ * 计算账号使用分散度。
+ *
+ * 业务含义：
+ * 1. 成功次数更少的账号应获得更高分，保证长期均匀。
+ * 2. 最近刚使用的账号短时间内降权，减少连续命中同一账号。
+ *
+ * @param stats 当前账号的调度统计；缺失时按从未使用处理。
+ * @param minSuccessCount 当前候选池中的最小成功次数。
+ * @param maxSuccessCount 当前候选池中的最大成功次数。
+ * @param nowMs 当前时间毫秒数；用于统一本次调度的时间基准。
+ * @returns 0 到 1 之间的分散调度评分。
+ * @throws 无显式抛出。
+ */
+function computeSpreadScore(stats, minSuccessCount, maxSuccessCount, nowMs) {
+    const current = stats ?? {
+        success_count: 0,
+        last_success_at: null
+    };
+    const countRange = Math.max(1, maxSuccessCount - minSuccessCount);
+    const countScore = 1 - (current.success_count - minSuccessCount) / countRange;
+    if (!current.last_success_at) {
+        return Math.max(0, Math.min(1, countScore * 0.6 + 0.4));
+    }
+    const secondsSinceLastUse = (nowMs - new Date(current.last_success_at).getTime()) / 1000;
+    const recencyScore = Math.max(0, Math.min(1, secondsSinceLastUse / RECENT_USE_RECOVERY_SECONDS));
+    return Math.max(0, Math.min(1, countScore * 0.6 + recencyScore * 0.4));
+}
+/**
+ * 计算单个账号的调度评分与可解释分解。
+ *
+ * 业务含义：
+ * 1. 周窗口浪费压力是主权重。
+ * 2. 5 小时窗口必须经过周额度承载系数修正。
+ * 3. 周健康度、使用分散度与 5 小时余额只做辅助平衡。
+ *
+ * @param status 账号运行时状态；必须来自当前候选池。
+ * @param stats 当前账号调度统计；缺失时按从未使用处理。
+ * @param minSuccessCount 当前候选池中的最小成功次数。
+ * @param maxSuccessCount 当前候选池中的最大成功次数。
+ * @param nowMs 当前时间毫秒数；用于统一本次调度的时间基准。
+ * @returns 调度评分与分项 breakdown。
+ * @throws 无显式抛出。
+ */
+function computeScheduleScore(status, stats, minSuccessCount, maxSuccessCount, nowMs) {
+    const weeklyWaste = computeWeeklyWastePressure(status, nowMs);
+    const fiveHourWaste = computeFiveHourWastePressure(status, nowMs) * computeWeeklyCapacityFactor(status);
+    const weeklyHealth = computeWeeklyHealthScore(status);
+    const spread = computeSpreadScore(stats, minSuccessCount, maxSuccessCount, nowMs);
+    const fiveHourLeft = normalizePercent(status.fiveHourLeftPercent);
+    const breakdown = {
+        weeklyWaste,
+        fiveHourWaste,
+        weeklyHealth,
+        spread,
+        fiveHourLeft
+    };
+    return {
+        score: weeklyWaste * 0.6 +
+            fiveHourWaste * 0.2 +
+            weeklyHealth * 0.1 +
+            spread * 0.07 +
+            fiveHourLeft * 0.03,
+        breakdown
+    };
+}
+/**
+ * 根据评分分解生成可读的调度原因。
+ *
+ * @param breakdown 调度评分分解；必须来自同一次评分。
+ * @returns 当前账号最主要的调度原因。
+ * @throws 无显式抛出。
+ */
+function resolveScheduleReason(breakdown) {
+    const entries = Object.entries(breakdown);
+    const [primary] = entries.sort((left, right) => right[1] - left[1]);
+    if (!primary) {
+        return "综合评分最高";
+    }
+    return {
+        weeklyWaste: "周额度快重置且剩余额度可用，优先避免周窗口浪费",
+        fiveHourWaste: "周额度仍可承载，优先消耗快重置的 5 小时余额",
+        weeklyHealth: "周额度更健康，避免低周余额账号提前打穿",
+        spread: "近期使用更少，优先做多账号均匀分摊",
+        fiveHourLeft: "5 小时剩余额度更高，作为兜底排序优势"
+    }[primary[0]];
+}
+/**
+ * 计算单个候选池中的调度决策列表。
+ *
+ * @param statuses 候选账号状态列表；调用方应已完成可用性过滤。
+ * @param statsByAccountId 账号调度统计表；key 为账号 id。
+ * @param nowMs 当前时间毫秒数；用于统一本次调度的时间基准。
+ * @returns 按优先级从高到低排序后的调度决策。
+ * @throws 无显式抛出。
+ */
+function rankPool(statuses, statsByAccountId, nowMs) {
+    const successCounts = statuses.map((item) => statsByAccountId[item.id]?.success_count ?? 0);
+    const minSuccessCount = Math.min(...successCounts, 0);
+    const maxSuccessCount = Math.max(...successCounts, 0);
+    return statuses
+        .map((status) => {
+        const scored = computeScheduleScore(status, statsByAccountId[status.id], minSuccessCount, maxSuccessCount, nowMs);
+        return {
+            status,
+            score: scored.score,
+            breakdown: scored.breakdown,
+            reason: resolveScheduleReason(scored.breakdown)
+        };
+    })
+        .sort((left, right) => {
+        const scoreDiff = right.score - left.score;
+        if (Math.abs(scoreDiff) > Number.EPSILON) {
+            return scoreDiff;
+        }
+        const leftResetWeight = left.status.fiveHourResetsAt ?? Number.MAX_SAFE_INTEGER;
+        const rightResetWeight = right.status.fiveHourResetsAt ?? Number.MAX_SAFE_INTEGER;
+        if (leftResetWeight !== rightResetWeight) {
+            return leftResetWeight - rightResetWeight;
+        }
+        return (right.status.weeklyLeftPercent ?? -1) - (left.status.weeklyLeftPercent ?? -1);
+    });
+}
+/**
+ * 按防浪费、周额度保护与均匀使用策略排序候选账号。
+ *
+ * 业务含义：
+ * 1. 先保护周额度低于关键线的账号；除非所有账号都低，否则后置。
+ * 2. 主池内按周窗口浪费、受周额度约束的 5 小时浪费、健康度和使用分散度综合评分。
+ * 3. 返回完整决策对象，便于 CLI、server 或测试解释“为什么选这个号”。
+ *
+ * @param statuses 候选账号状态列表；调用方应已完成启用、登录态、限额与熔断过滤。
+ * @param statsByAccountId 账号调度统计表；key 为账号 id。
+ * @param nowMs 当前时间毫秒数；默认使用当前系统时间。
+ * @returns 按优先级从高到低排序后的调度决策。
+ * @throws 无显式抛出。
+ */
+function rankAccountStatuses(statuses, statsByAccountId, nowMs = Date.now()) {
+    const primaryPool = statuses.some((item) => item.weeklyLeftPercent === null ||
+        item.weeklyLeftPercent === undefined ||
+        item.weeklyLeftPercent > CRITICAL_WEEKLY_LEFT_PERCENT)
+        ? statuses.filter((item) => item.weeklyLeftPercent === null ||
+            item.weeklyLeftPercent === undefined ||
+            item.weeklyLeftPercent > CRITICAL_WEEKLY_LEFT_PERCENT)
+        : statuses;
+    const deferredPool = statuses.filter((item) => !primaryPool.includes(item));
+    return [
+        ...rankPool(primaryPool, statsByAccountId, nowMs),
+        ...rankPool(deferredPool, statsByAccountId, nowMs)
+    ];
+}