Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(provider-group): add quota-aware usage balancing

MagicLiziec988bf20a2a
diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.ts
index 198cf9e3f6..200e4ac638 100644
--- a/apps/desktop/src/main/maker-ipc/register.ts
+++ b/apps/desktop/src/main/maker-ipc/register.ts
@@ -47,6 +47,7 @@ import {
getProviderGroupRemoteGroups,
getProviderGroupRouter,
setProviderGroupLocalLoad,
+ setProviderGroupClaudeUsageReader,
setProviderGroupSessionGroupReader,
setProviderGroupTurnProbe,
} from '../provider-group/runtime.js';
@@ -5796,6 +5797,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
// device-link 由 dispatch 拦截直读注入的 reader(见 dispatch.ts 同名 setter 注释)。
setDeviceLinkRemoteXaiSubscriptionUsageReader(readXaiSubscriptionUsageSnapshotForDeviceLink);
setDeviceLinkRemoteClaudeSubscriptionUsageReader(readClaudeSubscriptionUsageSnapshotForDeviceLink);
+ setProviderGroupClaudeUsageReader(readClaudeSubscriptionUsageSnapshotForDeviceLink);
// device-link 远程 set-* 持久化回流:effort/permission/fastMode/extraDirs 等
// runtime-only handler 经这个注入写被控端 DB + 广播 patched。SET_MODEL 是例外:
diff --git a/apps/desktop/src/main/provider-group/__tests__/directory.test.ts b/apps/desktop/src/main/provider-group/__tests__/directory.test.ts
index e9d50f40dc..89f89434f2 100644
--- a/apps/desktop/src/main/provider-group/__tests__/directory.test.ts
+++ b/apps/desktop/src/main/provider-group/__tests__/directory.test.ts
@@ -7,7 +7,7 @@ import type { ProviderView } from '@cindy/model-providers';
import { describe, expect, it, vi } from 'vitest';
import type { DeviceLinkDeviceView } from '../../../shared/deviceLinkIpc';
-import type { ProviderGroupConfig } from '../../../shared/providerGroup';
+import type { ProviderGroupConfig, ProviderGroupMember } from '../../../shared/providerGroup';
import { createProviderGroupDirectory, type ProviderGroupDirectoryDeps } from '../directory';
const view = (id: string, name: string, patch: Partial<ProviderView> = {}): ProviderView => ({
@@ -100,6 +100,22 @@ describe('listCandidates', () => {
});
describe('resolveMembers', () => {
+ it('reads quota only for available Claude subscriptions on this account’s computers', async () => {
+ const readClaudeUsage = vi.fn(async (_member: ProviderGroupMember) => ({ updatedAt: 1_000, fiveHour: { utilization: 25 } }));
+ const directory = createProviderGroupDirectory(deps({ readClaudeUsage }));
+ const member = (kind: 'local' | 'device' | 'share', agentDeviceId: string | null, providerId: string) => ({
+ key: `${kind}:${agentDeviceId}:${providerId}`, kind, agentDeviceId, providerId, limit: 4, weight: 1, paused: false,
+ });
+ const members = [member('local', null, 'anthropic'), member('device', 'mini', 'anthropic-1a2b3c4d'),
+ member('device', 'mini', 'deepseek'), member('device', 'off', 'anthropic'), member('share', 'share:s1', 'anthropic')];
+ const result = await directory.resolveMembers('anthropic', { strategy: 'usage', autoSwitch: true, members });
+ expect(readClaudeUsage).toHaveBeenCalledTimes(2);
+ expect(readClaudeUsage).toHaveBeenCalledWith(members[0]);
+ expect(readClaudeUsage).toHaveBeenCalledWith(members[1]);
+ expect(result[0].claudeUsage?.fiveHour?.utilization).toBe(25);
+ expect(result[4]).not.toHaveProperty('claudeUsage');
+ });
+
it('reports each member with a state and reason', async () => {
const directory = createProviderGroupDirectory(deps({
listReceivedShares: () => [share('s1'), share('s2', { status: 'paused' })],
diff --git a/apps/desktop/src/main/provider-group/__tests__/router.usage.test.ts b/apps/desktop/src/main/provider-group/__tests__/router.usage.test.ts
new file mode 100644
index 0000000000..6c41494c5f
--- /dev/null
+++ b/apps/desktop/src/main/provider-group/__tests__/router.usage.test.ts
@@ -0,0 +1,103 @@
+/** Real directory → quota eligibility → scheduler → status projection, using only in-memory accounts. */
+import type { ProviderView } from '@cindy/model-providers';
+import { describe, expect, it, vi } from 'vitest';
+import type { ClaudeSubscriptionUsageSnapshot } from '../../../shared/claudeSubscriptionUsage';
+import { normalizeProviderGroupConfig, PROVIDER_GROUP_STRATEGIES, type ProviderGroupMember } from '../../../shared/providerGroup';
+import { createProviderGroupDirectory } from '../directory';
+import { createProviderGroupRouter } from '../router';
+
+const NOW = 1_000_000;
+const OPUS = 'claude-opus-5-5';
+const SONNET = 'claude-sonnet-5';
+const view = (id: string): ProviderView => ({
+ id, name: id, agents: ['claude-code'], connected: true, auth: { method: 'oauth', native: 'claude' },
+ models: { 'claude-code': [OPUS, SONNET].map((id) => ({ id, name: id, efforts: [], defaultEffort: null })) },
+ routing: { 'claude-code': {} },
+}) as unknown as ProviderView;
+const snapshot = (fiveHour: number, sevenDay: number): ClaudeSubscriptionUsageSnapshot => ({
+ updatedAt: NOW, fiveHour: { utilization: fiveHour, resetsAt: 3_000 }, sevenDay: { utilization: sevenDay, resetsAt: 80_000 },
+});
+
+function harness() {
+ let now = NOW;
+ const config = normalizeProviderGroupConfig({
+ strategy: 'usage', members: [{ kind: 'local' }, { kind: 'device', agentDeviceId: 'mini', providerId: 'anthropic' }],
+ }, 'anthropic')!;
+ const usage = new Map<string, ClaudeSubscriptionUsageSnapshot | null>();
+ const readUsage = vi.fn(async (member: ProviderGroupMember) => usage.get(member.key) ?? null);
+ const directory = createProviderGroupDirectory({
+ listLocalProviders: async () => [view('anthropic')], localDeviceName: () => 'local',
+ listDevices: async () => [{ deviceId: 'mini', name: 'mini', online: true, remoteControlEnabled: true, controlEnabled: true,
+ isSelf: false, platform: 'darwin', appVersion: null, lastSeenAt: null, busy: false }],
+ readDeviceProviders: async () => [view('anthropic')], listReceivedShares: () => [],
+ isMobilePlatform: () => false, readClaudeUsage: readUsage, now: () => now,
+ });
+ const writeCooling = vi.fn();
+ const router = createProviderGroupRouter({
+ directory, readGroup: () => config, listBindings: () => ({}), isTurnRunning: () => false,
+ coolingStore: { read: () => ({}), write: writeCooling }, now: () => now, random: () => 0,
+ });
+ const pick = (model = OPUS, reserveFor?: string) => router.pick({ providerId: 'anthropic', agentKind: 'claude-code', model, reserveFor });
+ return { config, usage, router, pick, writeCooling, readUsage, advance: (ms: number) => { now += ms; } };
+}
+
+describe('provider-group quota routing', () => {
+ it.each(PROVIDER_GROUP_STRATEGIES)('excludes an exhausted account for the %s strategy', async (strategy) => {
+ const h = harness();
+ h.config.strategy = strategy;
+ const remote = h.config.members[1].key;
+ h.usage.set('local', snapshot(100, 5));
+ h.usage.set(remote, snapshot(40, 60));
+ expect(await h.pick()).toMatchObject({ kind: 'member', member: { key: remote } });
+ expect((await h.router.view('anthropic')).members[0]).toMatchObject({ state: 'cooling', coolingUntil: 3_000_000 });
+ // Quota snapshots never overwrite error-derived cooldowns or turn a scoped limit into a persistent global one.
+ expect(h.writeCooling).not.toHaveBeenCalled();
+ h.usage.set('local', snapshot(5, 100));
+ expect(await h.pick()).toMatchObject({ kind: 'member', member: { key: remote } });
+ h.usage.set(remote, snapshot(100, 5));
+ expect(await h.pick()).toMatchObject({ kind: 'unavailable' });
+ });
+
+ it('balances eligible accounts by usage, reserving simultaneous assignments immediately', async () => {
+ const h = harness();
+ const remote = h.config.members[1].key;
+ h.usage.set('local', snapshot(20, 85));
+ h.usage.set(remote, snapshot(55, 40));
+ expect(await h.pick()).toMatchObject({ kind: 'member', member: { key: remote } });
+ h.usage.set('local', snapshot(20, 40));
+ h.usage.set(remote, snapshot(25, 43));
+ const assignments = await Promise.all([h.pick(OPUS, 's1'), h.pick(OPUS, 's2')]);
+ expect(assignments.map((p) => p.kind === 'member' ? p.member.key : p.kind)).toEqual(['local', remote]);
+ });
+
+ it('keeps model-specific limits out of the group-wide availability state', async () => {
+ const h = harness();
+ const remote = h.config.members[1].key;
+ h.usage.set('local', { ...snapshot(10, 20), scoped: [{ modelDisplayName: 'Opus', utilization: 100, resetsAt: 80_000 }] });
+ h.usage.set(remote, snapshot(40, 60));
+ expect(await h.pick(OPUS)).toMatchObject({ kind: 'member', member: { key: remote } });
+ expect(await h.pick(SONNET)).toMatchObject({ kind: 'member', member: { key: 'local' } });
+ expect((await h.router.view('anthropic')).members[0].state).toBe('available');
+ expect(h.router.coolingUntil('anthropic', 'local')).toBeNull();
+ });
+
+ it('does not promise an earlier recovery time when an exhausted window has no reset', async () => {
+ const h = harness();
+ h.usage.set('local', { ...snapshot(100, 20), fiveHour: { utilization: 100, resetsAt: null } });
+ h.router.markCooling('anthropic', 'local', NOW + 60_000);
+ const status = (await h.router.view('anthropic')).members[0];
+ expect(status.state).toBe('cooling');
+ expect(status.coolingUntil).toBeUndefined();
+ });
+
+ it('falls back for missing/failed data and releases old quota blocks after reset', async () => {
+ const h = harness();
+ h.usage.set('local', snapshot(100, 10));
+ const remote = h.config.members[1].key;
+ expect(await h.pick()).toMatchObject({ kind: 'member', member: { key: remote } });
+ h.advance(2_000_000);
+ expect(await h.pick()).toMatchObject({ kind: 'member', member: { key: 'local' } });
+ h.readUsage.mockRejectedValue(new Error('unreachable'));
+ expect(await h.pick()).toMatchObject({ kind: 'member', member: { key: 'local' } });
+ });
+});
diff --git a/apps/desktop/src/main/provider-group/__tests__/runtime.test.ts b/apps/desktop/src/main/provider-group/__tests__/runtime.test.ts
index f06a8f153b..f436945e78 100644
--- a/apps/desktop/src/main/provider-group/__tests__/runtime.test.ts
+++ b/apps/desktop/src/main/provider-group/__tests__/runtime.test.ts
@@ -1,24 +1,35 @@
/**
* 运行期单例按账号隔离:换账号后冷却、目录缓存不沿用上一个账号的。
*/
-import { describe, expect, it, vi } from 'vitest';
+import type { ProviderView } from '@cindy/model-providers';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { normalizeProviderGroupConfig } from '../../../shared/providerGroup.js';
let owner = 'owner-a';
+const io = vi.hoisted(() => ({
+ local: vi.fn(async () => [] as ProviderView[]),
+ devices: vi.fn(),
+ catalog: vi.fn(),
+ invoke: vi.fn(),
+}));
vi.mock('../../appSessionState.js', () => ({ activeOwnerScopeKey: () => owner }));
vi.mock('../../device-link/providerShareGuest.js', () => ({ getReceivedShares: vi.fn(() => []) }));
-vi.mock('../../device-link/ipc.js', () => ({ handleListDevices: vi.fn(async () => ({ devices: [] })), defaultDeps: vi.fn() }));
-vi.mock('../../device-link/index.js', () => ({ remoteBackgroundInvoke: vi.fn() }));
+vi.mock('../../device-link/ipc.js', () => ({ handleListDevices: io.devices, defaultDeps: vi.fn() }));
+vi.mock('../../device-link/index.js', () => ({ remoteBackgroundInvoke: io.invoke }));
vi.mock('../../device-link/controllerPlatform.js', () => ({ isMobilePlatform: () => false }));
vi.mock('../../device-link/deviceName.js', () => ({ deviceName: () => 'This computer' }));
vi.mock('../../maker-host/createDesktopProviderService.js', () => ({
- getDesktopProviderService: () => ({ listProviders: vi.fn(async () => []) }),
+ getDesktopProviderService: () => ({ listProviders: io.local }),
}));
-vi.mock('../../remote-agent/controller/deviceCatalog.js', () => ({ readDeviceProviderViews: vi.fn(async () => []) }));
+vi.mock('../../remote-agent/controller/deviceCatalog.js', () => ({ readDeviceProviderViews: io.catalog }));
vi.mock('../bindings.js', () => ({ listProviderGroupBindings: () => ({}) }));
vi.mock('../store.js', () => ({ readProviderGroup: () => null }));
+vi.mock('../coolingStore.js', () => ({ readProviderGroupCooling: () => ({}), writeProviderGroupCooling: vi.fn() }));
+
+const { getProviderGroupDirectory, getProviderGroupOwnerScope, getProviderGroupRouter, setProviderGroupClaudeUsageReader } = await import('../runtime.js');
-const { getProviderGroupDirectory, getProviderGroupOwnerScope, getProviderGroupRouter } = await import('../runtime.js');
+afterEach(() => setProviderGroupClaudeUsageReader(null));
describe('provider group runtime', () => {
it('keeps cooling and round state per account behind stable handles', () => {
@@ -47,3 +58,62 @@ describe('provider group runtime', () => {
expect(getProviderGroupOwnerScope().externalLoad.running('anthropic', 'local')).toBe(0);
});
});
+
+describe('provider group runtime quota account selection', () => {
+ let sequence = 0;
+ const usage = () => ({
+ updatedAt: Date.now(), fiveHour: { utilization: 25, resetsAt: Date.now() / 1000 + 3600 },
+ sevenDay: { utilization: 45, resetsAt: Date.now() / 1000 + 86400 },
+ });
+
+ function harness(providerId = 'anthropic-second') {
+ owner = `quota-owner-${++sequence}`;
+ const provider = (id: string) => ({ id, connected: true, auth: { method: 'oauth', native: 'claude' } }) as ProviderView;
+ io.local.mockResolvedValue([provider('anthropic-local')]);
+ io.catalog.mockResolvedValue([provider(providerId)]);
+ io.devices.mockResolvedValue({ devices: [{ deviceId: 'mini', name: 'mini', online: true,
+ remoteControlEnabled: true, controlEnabled: true, isSelf: false, platform: 'darwin' }] });
+ io.invoke.mockReset();
+ const config = normalizeProviderGroupConfig({ members: [{ kind: 'local' },
+ { kind: 'device', agentDeviceId: 'mini', providerId }] }, 'anthropic-local')!;
+ const read = () => getProviderGroupDirectory().resolveMembers('anthropic-local', config);
+ return { read };
+ }
+
+ it('uses each member’s provider ID through the injected reader and existing same-account channel', async () => {
+ const h = harness();
+ const local = vi.fn(async () => usage());
+ setProviderGroupClaudeUsageReader(local);
+ io.invoke.mockResolvedValue({ ok: true, result: { ...usage(), providerId: 'anthropic-second' } });
+ const resolved = await h.read();
+ expect(local).toHaveBeenCalledExactlyOnceWith('anthropic-local');
+ expect(io.invoke).toHaveBeenCalledExactlyOnceWith('mini', 'maker:usage:claude-subscription', ['anthropic-second'],
+ { preSend: expect.any(Function) });
+ expect(resolved.map((r) => r.claudeUsage?.sevenDay?.utilization)).toEqual([45, 45]);
+ });
+
+ it.each([
+ ['anthropic-second', undefined, false],
+ ['anthropic-second', 'anthropic', false],
+ ['anthropic', undefined, true],
+ ])('does not use an old peer’s default quota for %s (echo %s)', async (providerId, echoed, accepted) => {
+ const h = harness(providerId);
+ io.invoke.mockResolvedValue({ ok: true, result: { ...usage(), ...(echoed ? { providerId: echoed } : {}) } });
+ const resolved = await h.read();
+ expect(resolved[1].claudeUsage !== null).toBe(accepted);
+ });
+
+ it('guards the outgoing request and discards the reply when the owner account changes', async () => {
+ const h = harness();
+ let preSend!: () => void;
+ io.invoke.mockImplementation(async (_device, _channel, _args, options) => {
+ preSend = options.preSend;
+ preSend();
+ owner = 'next-owner';
+ return { ok: true, result: { ...usage(), providerId: 'anthropic-second' } };
+ });
+ const resolved = await h.read();
+ expect(resolved[1].claudeUsage).toBeNull();
+ expect(() => preSend()).toThrow('provider group account changed');
+ });
+});
diff --git a/apps/desktop/src/main/provider-group/__tests__/scheduler.test.ts b/apps/desktop/src/main/provider-group/__tests__/scheduler.test.ts
index 19ce0f52f9..63ace64149 100644
--- a/apps/desktop/src/main/provider-group/__tests__/scheduler.test.ts
+++ b/apps/desktop/src/main/provider-group/__tests__/scheduler.test.ts
@@ -1,5 +1,5 @@
/**
- * 组策略(provider-groups.md §5):只分给可用、未暂停、没试过的电脑;优先未满载;四种选择方式。
+ * 组策略(provider-groups.md §5):只分给可用、未暂停、没试过的电脑;优先未满载。
*/
import { describe, expect, it } from 'vitest';
@@ -45,4 +45,22 @@ describe('pickProviderGroupMember', () => {
expect(pickProviderGroupMember(members, 'weight', { random: () => 0.1 })).toBe('a');
expect(pickProviderGroupMember(members, 'weight', { random: () => 0.5 })).toBe('b');
});
+
+ it('balances current usage and spreads similar usage across idle computers', () => {
+ expect(pickProviderGroupMember([m('a', { usagePercent: 85 }), m('b', { usagePercent: 55, running: 2 })], 'usage')).toBe('b');
+ expect(pickProviderGroupMember([m('a', { usagePercent: 40, running: 2 }), m('b', { usagePercent: 45 })], 'usage')).toBe('b');
+ expect(pickProviderGroupMember([m('a', { usagePercent: 40, running: 2 }), m('b', { usagePercent: 46 })], 'usage')).toBe('a');
+ });
+
+ it('uses known usage first, with ordinary load balancing when no current usage is known', () => {
+ expect(pickProviderGroupMember([m('unknown'), m('known', { usagePercent: 80 })], 'usage')).toBe('known');
+ expect(pickProviderGroupMember([m('a', { running: 1 }), m('b', { usagePercent: null })], 'usage')).toBe('b');
+ expect(pickProviderGroupMember([m('a', { usagePercent: 10, usable: false })], 'usage')).toBeNull();
+ });
+
+ it('keeps concurrency limits ahead of usage ranking, including the all-full fallback', () => {
+ const full = m('low', { usagePercent: 10, running: 4 });
+ expect(pickProviderGroupMember([full, m('high', { usagePercent: 80 })], 'usage')).toBe('high');
+ expect(pickProviderGroupMember([full, m('other', { usagePercent: 5, running: 5 })], 'usage')).toBe('low');
+ });
});
diff --git a/apps/desktop/src/main/provider-group/__tests__/service.test.ts b/apps/desktop/src/main/provider-group/__tests__/service.test.ts
index 0ef1d4786b..a3f743ea03 100644
--- a/apps/desktop/src/main/provider-group/__tests__/service.test.ts
+++ b/apps/desktop/src/main/provider-group/__tests__/service.test.ts
@@ -8,6 +8,7 @@ import type { ProviderView } from '@cindy/model-providers';
import { describe, expect, it, vi } from 'vitest';
import type { ProviderGroupConfig, ProviderGroupMember } from '../../../shared/providerGroup';
+import type { ClaudeSubscriptionUsageSnapshot } from '../../../shared/claudeSubscriptionUsage';
import type { ProviderGroupBinding, ProviderGroupRef } from '../bindings';
import type { ProviderGroupDirectory, ResolvedMemberState, ResolvedProviderGroupMember } from '../directory';
import { createProviderGroupGuestSwitch, PROVIDER_GROUP_SWITCH_OFFER_TTL_MS } from '../guestSwitch';
@@ -53,6 +54,7 @@ function harness(options: {
autoSwitch?: boolean;
/** 这些组内电脑上的同名模型不能用于新会话(停用、退役、需要付费)。 */
unusableModel?: Record<string, Record<string, unknown>>;
+ usage?: Record<string, ClaudeSubscriptionUsageSnapshot>;
} = {}) {
let now = 1_000_000;
const config: ProviderGroupConfig = {
@@ -73,7 +75,7 @@ function harness(options: {
async resolveMembers(_providerId, current) {
return current.members.map((m): ResolvedProviderGroupMember => offline.has(m.key)
? { member: m, label: m.key, state: 'offline' }
- : { member: m, label: `${m.key}-name`, state: 'ok', view: view(m.providerId, options.unusableModel?.[m.key]) });
+ : { member: m, label: `${m.key}-name`, state: 'ok', view: view(m.providerId, options.unusableModel?.[m.key]), claudeUsage: options.usage?.[m.key] });
},
async listCandidates() {
return [];
@@ -1081,6 +1083,14 @@ describe('beforeSend', () => {
expect(h.deps.switchAgentLocation).not.toHaveBeenCalled();
});
+ it('moves before sending when the current account’s quota is already exhausted without a prior error', async () => {
+ const h = harness({ usage: { local: { updatedAt: 1_000_000, fiveHour: { utilization: 100, resetsAt: 3_000 }, sevenDay: { utilization: 10, resetsAt: 80_000 } } } });
+ h.bindings.set('s1', { providerId: 'anthropic', memberKey: 'local', at: 1_000_000 });
+ await h.service.beforeSend('s1');
+ expect(h.row.agentDeviceId).toBe('mini');
+ expect(h.router.coolingUntil('anthropic', 'local')).toBeNull();
+ });
+
it('moves a task off a computer that is cooling down', async () => {
const h = harness({ row: { sdkSessionId: 'native' } });
h.bindings.set('s1', { providerId: 'anthropic', memberKey: 'local', at: 1 });
diff --git a/apps/desktop/src/main/provider-group/__tests__/usage.test.ts b/apps/desktop/src/main/provider-group/__tests__/usage.test.ts
new file mode 100644
index 0000000000..d24323df97
--- /dev/null
+++ b/apps/desktop/src/main/provider-group/__tests__/usage.test.ts
@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { ClaudeSubscriptionUsageSnapshot } from '../../../shared/claudeSubscriptionUsage';
+import type { ProviderGroupMember } from '../../../shared/providerGroup';
+import {
+ createProviderGroupUsageReader, providerGroupUsageSnapshot, providerGroupUsageState,
+ PROVIDER_GROUP_USAGE_MAX_AGE_MS, PROVIDER_GROUP_USAGE_READ_TIMEOUT_MS,
+} from '../usage';
+
+const NOW = 1_000_000;
+const snapshot = (fiveHour = 20, sevenDay = 40): ClaudeSubscriptionUsageSnapshot => ({
+ updatedAt: NOW,
+ fiveHour: { utilization: fiveHour, resetsAt: (NOW + 3_600_000) / 1000 },
+ sevenDay: { utilization: sevenDay, resetsAt: (NOW + 86_400_000) / 1000 },
+});
+const member = (kind: ProviderGroupMember['kind'], agentDeviceId: string | null, providerId = 'anthropic'): ProviderGroupMember => ({
+ key: `${kind}:${agentDeviceId}:${providerId}`, kind, agentDeviceId, providerId, paused: false, limit: 4, weight: 1,
+});
+const REMOTE = member('device', 'mini');
+
+afterEach(() => vi.useRealTimers());
+
+describe('provider group quota eligibility', () => {
+ it.each([[100, 10], [10, 100]])('excludes exhausted windows before comparing usage (%s, %s)', (fiveHour, sevenDay) => {
+ expect(providerGroupUsageState(snapshot(fiveHour, sevenDay), 'opus', NOW).limited).toBe(true);
+ });
+
+ it('uses both windows and only the selected model’s weekly window', () => {
+ const value = { ...snapshot(), scoped: [{ modelDisplayName: 'Opus', utilization: 100, resetsAt: 3_000 }] };
+ expect(providerGroupUsageState(value, 'claude-opus-5-5', NOW).limited).toBe(true);
+ expect(providerGroupUsageState(value, 'claude-sonnet-5', NOW)).toMatchObject({ limited: false, usagePercent: 40 });
+ expect(providerGroupUsageState(value, null, NOW).limited).toBe(false);
+ expect(providerGroupUsageState(snapshot(85, 20), 'opus', NOW).usagePercent).toBe(85);
+ expect(providerGroupUsageState(snapshot(20, 85), 'opus', NOW).usagePercent).toBe(85);
+ });
+
+ it('waits for the last exhausted window and never borrows another window’s reset', () => {
+ expect(providerGroupUsageState(snapshot(100, 100), 'opus', NOW).resetAtMs).toBe(NOW + 86_400_000);
+ const unknownReset = { ...snapshot(100, 100), fiveHour: { utilization: 100 } };
+ expect(providerGroupUsageState(unknownReset, 'opus', NOW)).toMatchObject({ limited: true, resetAtMs: null });
+ });
+
+ it('does not keep blocking a reset window or score it as zero before fresh data arrives', () => {
+ const value = { ...snapshot(100, 20), fiveHour: { utilization: 100, resetsAt: NOW / 1000 } };
+ expect(providerGroupUsageState(value, 'opus', NOW)).toEqual({ limited: false, resetAtMs: null, usagePercent: null });
+ });
+
+ it('keeps unknown and stale data distinct from low usage', () => {
+ for (const raw of [null, {}, { ...snapshot(), updatedAt: null }, { ...snapshot(), updatedAt: NOW + 120_000 },
+ { ...snapshot(), fiveHour: null }, { ...snapshot(), sevenDay: { utilization: '0' } }]) {
+ expect(providerGroupUsageState(raw, 'opus', NOW)).toMatchObject({ limited: false, usagePercent: null });
+ }
+ expect(providerGroupUsageState(snapshot(100, 100), 'opus', NOW + PROVIDER_GROUP_USAGE_MAX_AGE_MS + 1))
+ .toMatchObject({ limited: false, usagePercent: null });
+ expect(providerGroupUsageState({ ...snapshot(), sevenDay: null, fiveHour: { utilization: 100 } }, 'opus', NOW).limited).toBe(true);
+ });
+
+ it('reuses the rejected-window check and sanitizes remote data without exposing account identity', () => {
+ const value = { ...snapshot(), rateLimitStatus: 'rejected', representativeClaim: 'five_hour',
+ accountFingerprint: 'private-account', scoped: [null, { modelDisplayName: 8, utilization: 100 }] };
+ expect(providerGroupUsageState(value, 'opus', NOW).limited).toBe(true);
+ expect(providerGroupUsageSnapshot(value, NOW)).not.toHaveProperty('accountFingerprint');
+ expect(providerGroupUsageSnapshot(value, NOW)?.scoped).toEqual([]);
+ });
+});
+
+describe('provider group usage reads', () => {
+ function harness() {
+ let now = NOW;
+ let current = true;
+ const readLocal = vi.fn(async (_providerId: string) => snapshot());
+ const readRemote = vi.fn(async (_device: string, _providerId: string) => snapshot());
+ const reader = createProviderGroupUsageReader({ readLocal, readRemote, now: () => now, isCurrent: () => current });
+ return { reader, readLocal, readRemote, advance: (ms: number) => { now += ms; }, leave: () => { current = false; } };
+ }
+
+ it('reads the correct device and provider, coalesces remote reads, and refreshes local snapshots', async () => {
+ const h = harness();
+ await Promise.all([h.reader.read(REMOTE), h.reader.read(REMOTE)]);
+ expect(h.readRemote).toHaveBeenCalledExactlyOnceWith('mini', 'anthropic');
+ await h.reader.read(REMOTE);
+ expect(h.readRemote).toHaveBeenCalledTimes(1);
+ await h.reader.read(member('device', 'mini', 'anthropic-second'));
+ expect(h.readRemote).toHaveBeenLastCalledWith('mini', 'anthropic-second');
+ await h.reader.read(member('local', null));
+ await h.reader.read(member('local', null));
+ expect(h.readLocal).toHaveBeenCalledTimes(2);
+ h.advance(15_001);
+ await h.reader.read(REMOTE);
+ expect(h.readRemote).toHaveBeenCalledTimes(3);
+ h.reader.invalidate();
+ await h.reader.read(REMOTE);
+ expect(h.readRemote).toHaveBeenCalledTimes(4);
+ });
+
+ it('never requests another person’s subscription quota', async () => {
+ const h = harness();
+ expect(await h.reader.read(member('share', 'share:s1'))).toBeNull();
+ expect(await h.reader.read(member('device', 'share:s1'))).toBeNull();
+ expect(h.readLocal).not.toHaveBeenCalled();
+ expect(h.readRemote).not.toHaveBeenCalled();
+ });
+
+ it('falls back on unsupported peers or failed reads without caching an invented zero', async () => {
+ const h = harness();
+ h.readRemote.mockRejectedValue(new Error('CHANNEL_NOT_ALLOWED'));
+ expect(await h.reader.read(REMOTE)).toBeNull();
+ expect(await h.reader.read(REMOTE)).toBeNull();
+ expect(h.readRemote).toHaveBeenCalledTimes(1);
+ });
+
+ it('bounds a slow read, keeps one request in flight and uses its eventual result', async () => {
+ vi.useFakeTimers();
+ const h = harness();
+ let complete!: (value: ClaudeSubscriptionUsageSnapshot) => void;
+ h.readRemote.mockImplementation(() => new Promise((resolve) => { complete = resolve; }));
+ const first = h.reader.read(REMOTE);
+ await vi.advanceTimersByTimeAsync(PROVIDER_GROUP_USAGE_READ_TIMEOUT_MS);
+ expect(await first).toBeNull();
+ const second = h.reader.read(REMOTE);
+ await vi.advanceTimersByTimeAsync(PROVIDER_GROUP_USAGE_READ_TIMEOUT_MS);
+ expect(await second).toBeNull();
+ expect(h.readRemote).toHaveBeenCalledTimes(1);
+ complete(snapshot(35, 45));
+ await vi.advanceTimersByTimeAsync(0);
+ expect(await h.reader.read(REMOTE)).toMatchObject({ fiveHour: { utilization: 35 } });
+ });
+
+ it('drops an in-flight snapshot when the Cindy account changes', async () => {
+ const h = harness();
+ h.readRemote.mockImplementation(async () => { h.leave(); return snapshot(); });
+ expect(await h.reader.read(REMOTE)).toBeNull();
+ expect(await h.reader.read(member('local', null))).toBeNull();
+ expect(h.readLocal).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/desktop/src/main/provider-group/directory.ts b/apps/desktop/src/main/provider-group/directory.ts
index 79caf140f7..6ab7aee234 100644
--- a/apps/desktop/src/main/provider-group/directory.ts
+++ b/apps/desktop/src/main/provider-group/directory.ts
@@ -21,6 +21,8 @@ import {
type ProviderGroupUnavailableReason,
} from '../../shared/providerGroup.js';
import type { DeviceLinkDeviceView } from '../../shared/deviceLinkIpc.js';
+import type { ClaudeSubscriptionUsageSnapshot } from '../../shared/claudeSubscriptionUsage.js';
+import { providerWeeklyQuotaSource } from '../../shared/providerQuotaSource.js';
import { isSameProvider } from './matching.js';
export interface ProviderGroupDirectoryDeps {
@@ -35,6 +37,9 @@ export interface ProviderGroupDirectoryDeps {
isMobilePlatform(platform: string | null): boolean;
/** 本机这个供应商正在运行一轮的任务数(localLoad.ts);不提供或读不到时为 null。 */
localRunning?(providerId: string): Promise<number | null>;
+ /** Same-account subscription snapshots only; absence/failure keeps the member usable. */
+ readClaudeUsage?(member: ProviderGroupMember): Promise<ClaudeSubscriptionUsageSnapshot | null>;
+ invalidateUsage?(): void;
now(): number;
}
@@ -53,6 +58,8 @@ export interface ResolvedProviderGroupMember {
* 分享来的电脑报来本账号(每台电脑)在那里的数。那台较旧给不出时没有。
*/
reportedRunning?: number;
+ /** Internal only: never included in the group wire projection or shared with guests. */
+ claudeUsage?: ClaudeSubscriptionUsageSnapshot | null;
/**
* 选电脑时到点还没读完(那台慢或不响应):这次按不能用算,不代表读到了离线;读取照常在后台完成、留在缓存里。
*/
@@ -265,6 +272,7 @@ export function createProviderGroupDirectory(deps: ProviderGroupDirectoryDeps):
async resolveMembers(_providerId, config, options) {
if (options?.fresh) {
devices = null;
+ deps.invalidateUsage?.();
for (const member of config.members) if (member.agentDeviceId) catalogs.delete(member.agentDeviceId);
}
const needsDevices = config.members.some((m) => m.kind === 'device');
@@ -273,10 +281,14 @@ export function createProviderGroupDirectory(deps: ProviderGroupDirectoryDeps):
// 无响应时选电脑会等它的完整网络超时,而不是三秒后继续(chatgpt-codex-connector P2,
// PR #5792 review)。
const deviceListPromise = needsDevices ? readDevices().catch(() => null) : Promise.resolve(null);
- const reads = config.members.map((member) => {
- if (member.kind === 'local') return resolveLocal(member);
- if (member.kind === 'share') return resolveShare(member);
- return deviceListPromise.then((deviceList) => resolveDevice(member, deviceList));
+ const reads = config.members.map(async (member) => {
+ const resolved = member.kind === 'local' ? await resolveLocal(member)
+ : member.kind === 'share' ? await resolveShare(member)
+ : await resolveDevice(member, await deviceListPromise);
+ if (member.kind === 'share' || resolved.state !== 'ok' || !resolved.view?.auth
+ || providerWeeklyQuotaSource(resolved.view) !== 'claude' || !deps.readClaudeUsage) return resolved;
+ const claudeUsage = await deps.readClaudeUsage(member).catch(() => null);
+ return { ...resolved, claudeUsage };
});
if (options?.quickMs === undefined) return Promise.all(reads);
return settleQuickly(config.members, reads, options);
@@ -380,6 +392,7 @@ export function createProviderGroupDirectory(deps: ProviderGroupDirectoryDeps):
},
invalidate(agentDeviceId) {
+ deps.invalidateUsage?.();
if (agentDeviceId === undefined) {
catalogs.clear();
devices = null;
diff --git a/apps/desktop/src/main/provider-group/router.ts b/apps/desktop/src/main/provider-group/router.ts
index 165e498f39..c7313f22db 100644
--- a/apps/desktop/src/main/provider-group/router.ts
+++ b/apps/desktop/src/main/provider-group/router.ts
@@ -18,6 +18,7 @@ import type { ProviderGroupConfig, ProviderGroupMember, ProviderGroupView } from
import type { ProviderGroupBinding } from './bindings.js';
import type { ProviderGroupDirectory, ResolvedProviderGroupMember } from './directory.js';
import { pickProviderGroupMember, type SchedulableMember } from './scheduler.js';
+import { providerGroupUsageState } from './usage.js';
/** 撞到用量上限但拿不到重置时刻时,默认冷却多久。 */
export const PROVIDER_GROUP_DEFAULT_COOLDOWN_MS = 30 * 60_000;
@@ -197,7 +198,8 @@ export function createProviderGroupRouter(deps: ProviderGroupRouterDeps): Provid
const config = deps.readGroup(input.providerId);
if (!config) return { kind: 'none' };
const usable = (r: ResolvedProviderGroupMember) =>
- offersModel(r, input.agentKind, input.model) && coolingUntil(input.providerId, r.member.key) === null;
+ offersModel(r, input.agentKind, input.model) && coolingUntil(input.providerId, r.member.key) === null
+ && !providerGroupUsageState(r.claudeUsage, input.model, deps.now()).limited;
const resolved = await deps.directory.resolveMembers(input.providerId, config, {
quickMs: PROVIDER_GROUP_PICK_QUICK_MS,
// 已经有一台能用、可以分的电脑(满载仍可接):不再等慢的那几台。未满优先由调度器决定。
@@ -213,6 +215,7 @@ export function createProviderGroupRouter(deps: ProviderGroupRouterDeps): Provid
running: memberRunning(input.providerId, r),
limit: r.member.limit,
weight: r.member.weight,
+ usagePercent: providerGroupUsageState(r.claudeUsage, input.model, deps.now()).usagePercent,
}));
const key = pickProviderGroupMember(schedulable, config.strategy, {
exclude: input.exclude,
@@ -241,13 +244,18 @@ export function createProviderGroupRouter(deps: ProviderGroupRouterDeps): Provid
providerId,
config,
members: resolved.map((r) => {
- const until = coolingUntil(providerId, r.member.key);
+ // General windows affect the whole account; a scoped model limit must not block other models.
+ const quota = providerGroupUsageState(r.claudeUsage, null, deps.now());
+ const remembered = coolingUntil(providerId, r.member.key);
+ const until = quota.limited && quota.resetAtMs === null ? null
+ : remembered === null ? quota.resetAtMs
+ : quota.resetAtMs === null ? remembered : Math.max(remembered, quota.resetAtMs);
const count = memberRunning(providerId, r);
const state = r.member.paused
? 'paused' as const
: r.state !== 'ok'
? r.state
- : until !== null
+ : until !== null || quota.limited
? 'cooling' as const
: count >= r.member.limit
? 'full' as const
diff --git a/apps/desktop/src/main/provider-group/runtime.ts b/apps/desktop/src/main/provider-group/runtime.ts
index 694d820758..f0de37d48e 100644
--- a/apps/desktop/src/main/provider-group/runtime.ts
+++ b/apps/desktop/src/main/provider-group/runtime.ts
@@ -7,6 +7,7 @@
* 调用方拿到的是固定的门面,每次调用按当前账号转发。
*/
import type { ProviderView } from '@cindy/model-providers';
+import type { ClaudeSubscriptionUsageSnapshot } from '../../shared/claudeSubscriptionUsage.js';
import { activeOwnerScopeKey } from '../appSessionState.js';
import { readProviderGroupSummary, type ProviderGroupSessionGroup } from '../../shared/providerGroup.js';
@@ -25,6 +26,7 @@ import { createProviderGroupRemoteClient, type ProviderGroupRemoteClient } from
import { createProviderGroupRouter, type ProviderGroupRouter } from './router.js';
import type { ProviderGroupRemoteGroups } from './service.js';
import { readProviderGroup } from './store.js';
+import { createProviderGroupUsageReader } from './usage.js';
interface OwnerRuntime {
owner: string;
@@ -37,10 +39,30 @@ let current: OwnerRuntime | null = null;
let isTurnRunning: (sessionId: string) => boolean = () => false;
let localLoad: (() => Promise<ReadonlyMap<string, number>>) | null = null;
let sessionGroupReader: ((sessionId: string) => Promise<ProviderGroupSessionGroup>) | null = null;
+let claudeUsageReader: ((providerId: string) => Promise<ClaudeSubscriptionUsageSnapshot | null>) | null = null;
function runtimeForActiveOwner(): OwnerRuntime {
const owner = activeOwnerScopeKey();
if (current?.owner === owner) return current;
+ const usage = createProviderGroupUsageReader({
+ readLocal: (providerId) => claudeUsageReader?.(providerId) ?? Promise.resolve(null),
+ readRemote: async (deviceId, providerId) => {
+ const result = await remoteBackgroundInvoke(deviceId, 'maker:usage:claude-subscription', [providerId], {
+ preSend: () => {
+ if (activeOwnerScopeKey() !== owner) throw new Error('provider group account changed');
+ },
+ });
+ if (!result.ok) return null;
+ const raw = result.result;
+ if (!raw || typeof raw !== 'object') return null;
+ const echoedProvider = (raw as { providerId?: unknown }).providerId;
+ // Old peers may ignore account selection: never mistake their default account for a named one.
+ if (echoedProvider !== undefined ? echoedProvider !== providerId : providerId !== 'anthropic') return null;
+ return raw;
+ },
+ isCurrent: () => activeOwnerScopeKey() === owner,
+ now: () => Date.now(),
+ });
const directory = createProviderGroupDirectory({
listLocalProviders: () => getDesktopProviderService().listProviders({ allowSideEffects: false }),
localDeviceName: () => deviceName(),
@@ -49,6 +71,8 @@ function runtimeForActiveOwner(): OwnerRuntime {
listReceivedShares: () => getReceivedShares(),
isMobilePlatform: (platform) => isMobilePlatform(platform),
localRunning: async (providerId) => (await readProviderRunningTurnsByProvider())?.get(providerId) ?? null,
+ readClaudeUsage: (member) => usage.read(member),
+ invalidateUsage: () => usage.invalidate(),
now: () => Date.now(),
});
const externalLoad = createProviderGroupExternalLoad({ now: () => Date.now() });
@@ -178,6 +202,11 @@ export function setProviderGroupLocalLoad(probe: (() => Promise<ReadonlyMap<stri
localLoad = probe;
}
+/** Reuse the CLI-backed subscription reader without importing the IPC adapter into routing. */
+export function setProviderGroupClaudeUsageReader(reader: typeof claudeUsageReader): void {
+ claudeUsageReader = reader;
+}
+
/** 这台电脑上每个供应商正在运行一轮的任务数;还没装配或读不到时返回 null(调用方照旧只算经组的)。 */
export async function readProviderRunningTurnsByProvider(): Promise<ReadonlyMap<string, number> | null> {
if (!localLoad) return null;
diff --git a/apps/desktop/src/main/provider-group/scheduler.ts b/apps/desktop/src/main/provider-group/scheduler.ts
index 96becdd3ab..d7e16f0c06 100644
--- a/apps/desktop/src/main/provider-group/scheduler.ts
+++ b/apps/desktop/src/main/provider-group/scheduler.ts
@@ -11,6 +11,8 @@ export interface SchedulableMember {
running: number;
limit: number;
weight: number;
+ /** Higher of the current 5-hour / weekly usage percentages; unknown stays null. */
+ usagePercent?: number | null;
}
export interface PickOptions {
@@ -36,6 +38,13 @@ export function pickProviderGroupMember(
const open = eligible.filter((m) => m.running < m.limit);
if (open.length === 0) return leastBusy(eligible).key;
switch (strategy) {
+ case 'usage': {
+ const known = open.filter((m) => typeof m.usagePercent === 'number' && Number.isFinite(m.usagePercent));
+ if (known.length === 0) return leastBusy(open).key;
+ const lowest = Math.min(...known.map((m) => m.usagePercent!));
+ // Small quota differences should not send every simultaneous task to the same computer.
+ return leastBusy(known.filter((m) => m.usagePercent! <= lowest + 5)).key;
+ }
case 'order':
return open[0].key;
case 'round': {
diff --git a/apps/desktop/src/main/provider-group/service.ts b/apps/desktop/src/main/provider-group/service.ts
index 13eedca26a..31904d0b6e 100644
--- a/apps/desktop/src/main/provider-group/service.ts
+++ b/apps/desktop/src/main/provider-group/service.ts
@@ -42,6 +42,7 @@ import {
import type { ProviderGroupBinding, ProviderGroupRef } from './bindings.js';
import type { ProviderGroupDirectory } from './directory.js';
import type { ProviderGroupGuestSwitch } from './guestSwitch.js';
+import { providerGroupUsageState } from './usage.js';
import {
PROVIDER_GROUP_DEFAULT_COOLDOWN_MS,
PROVIDER_GROUP_FAILURE_COOLDOWN_MS,
@@ -366,7 +367,7 @@ interface GroupSource {
/** 组的状态里这台现在冷却中(组所在电脑记着它账号的问题)。 */
isKnownDown(providerId: string, memberKey: string): Promise<boolean>;
/** 发送前:这台现在该不该换掉;null = 读不到,照常发送。 */
- shouldMoveAway(providerId: string, config: ProviderGroupConfig, memberKey: string): Promise<{ reason: string } | false | null>;
+ shouldMoveAway(providerId: string, config: ProviderGroupConfig, memberKey: string, model: string): Promise<{ reason: string } | false | null>;
invalidate(member: ProviderGroupMember): void;
/** 任务记录里 Agent 的位置对应组里哪一项(组所在电脑视角的键);不对应任何组员返回 null。 */
memberKeyOf(groupProviderId: string, row: ProviderGroupSessionRow): Promise<string | null>;
@@ -677,11 +678,12 @@ export function createProviderGroupService(deps: ProviderGroupServiceDeps): Prov
async isKnownDown(providerId, memberKey) {
return router.coolingUntil(providerId, memberKey) !== null;
},
- async shouldMoveAway(providerId, config, memberKey) {
+ async shouldMoveAway(providerId, config, memberKey, model) {
const resolved = await withTimeout(deps.directory.resolveMembers(providerId, config), PROVIDER_GROUP_BEFORE_SEND_TIMEOUT_MS);
const state = resolved?.find((r) => r.member.key === memberKey);
if (!state) return null;
- const cooling = router.coolingUntil(providerId, memberKey) !== null;
+ const cooling = router.coolingUntil(providerId, memberKey) !== null
+ || providerGroupUsageState(state.claudeUsage, model, deps.now()).limited;
if (state.state === 'ok' && !cooling) return false;
return { reason: cooling ? 'cooling' : state.state };
},
@@ -1638,7 +1640,7 @@ export function createProviderGroupService(deps: ProviderGroupServiceDeps): Prov
const current = await verifyBinding(sessionId, source, binding, config, row);
// 暂停分配只影响新任务,已在那台的任务不挪走。
if (!current || current.paused) return;
- const cached = await source.shouldMoveAway(binding.providerId, config, current.key);
+ const cached = await source.shouldMoveAway(binding.providerId, config, current.key, row.model);
if (cached === null) return;
let reason = cached ? cached.reason : null;
const currentRoute = source.routeOf(current, row.providerId);
diff --git a/apps/desktop/src/main/provider-group/usage.ts b/apps/desktop/src/main/provider-group/usage.ts
new file mode 100644
index 0000000000..c53a588660
--- /dev/null
+++ b/apps/desktop/src/main/provider-group/usage.ts
@@ -0,0 +1,122 @@
+/** Subscription snapshots used for group eligibility and balancing, never credentials or token estimates. */
+import {
+ matchScopedWindowForModel,
+ type ClaudeSubscriptionUsageSnapshot,
+ type ClaudeUsageWindow,
+} from '@cindy/maker-shared/subscription-usage';
+
+import { claudeAccountUsageLimit } from '../../shared/accountUsageLimit.js';
+import type { ProviderGroupMember } from '../../shared/providerGroup.js';
+import { isProviderShareAgentDeviceId } from '../../shared/providerShare.js';
+
+export const PROVIDER_GROUP_USAGE_MAX_AGE_MS = 10 * 60_000;
+export const PROVIDER_GROUP_USAGE_READ_TIMEOUT_MS = 1_500;
+const REMOTE_USAGE_CACHE_MS = 15_000;
+const MAX_CACHED_ACCOUNTS = 512;
+
+function record(value: unknown): Record<string, unknown> | null {
+ return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function windowOf(raw: unknown): ClaudeUsageWindow | null {
+ const value = record(raw);
+ if (!value || typeof value.utilization !== 'number' || !Number.isFinite(value.utilization) || value.utilization < 0) return null;
+ return {
+ utilization: Math.min(100, value.utilization),
+ resetsAt: typeof value.resetsAt === 'number' && Number.isFinite(value.resetsAt) && value.resetsAt > 0 ? value.resetsAt : null,
+ };
+}
+
+/** Old/malformed snapshots are unknown, not a claim of zero usage or a permanent cooldown. */
+export function providerGroupUsageSnapshot(raw: unknown, now: number): ClaudeSubscriptionUsageSnapshot | null {
+ const value = record(raw);
+ if (!value || typeof value.updatedAt !== 'number' || !Number.isFinite(value.updatedAt)
+ || value.updatedAt <= 0 || now - value.updatedAt > PROVIDER_GROUP_USAGE_MAX_AGE_MS
+ || value.updatedAt - now > 60_000) return null;
+ return {
+ updatedAt: value.updatedAt,
+ fiveHour: windowOf(value.fiveHour),
+ sevenDay: windowOf(value.sevenDay),
+ scoped: (Array.isArray(value.scoped) ? value.scoped : []).flatMap((rawWindow) => {
+ const item = record(rawWindow);
+ const window = windowOf(rawWindow);
+ if (!window || typeof item?.modelDisplayName !== 'string') return [];
+ return [{ ...window, modelDisplayName: item.modelDisplayName, modelId: typeof item.modelId === 'string' ? item.modelId : null }];
+ }),
+ rateLimitStatus: typeof value.rateLimitStatus === 'string' ? value.rateLimitStatus : null,
+ representativeClaim: typeof value.representativeClaim === 'string' ? value.representativeClaim : null,
+ };
+}
+
+/** Check exhaustion first. A score requires both current windows, so missing data cannot win as 0%. */
+export function providerGroupUsageState(raw: unknown, model: string | null | undefined, now: number) {
+ const snapshot = providerGroupUsageSnapshot(raw, now);
+ const limit = claudeAccountUsageLimit(snapshot, model, now);
+ const current = (w: ClaudeUsageWindow | null | undefined) =>
+ w && (!w.resetsAt || w.resetsAt * 1000 > now) ? w.utilization : null;
+ const fiveHour = current(snapshot?.fiveHour);
+ const sevenDay = current(snapshot?.sevenDay);
+ const scoped = matchScopedWindowForModel(snapshot?.scoped, model);
+ const scopedUsage = current(scoped);
+ const usagePercent = fiveHour !== null && sevenDay !== null && (!scoped || scopedUsage !== null)
+ ? Math.max(fiveHour, sevenDay, scopedUsage ?? 0) : null;
+ return { limited: limit?.limited ?? false, resetAtMs: limit?.resetAtMs ?? null, usagePercent };
+}
+
+export interface ProviderGroupUsageReaderDeps {
+ readLocal(providerId: string): Promise<unknown>;
+ readRemote(deviceId: string, providerId: string): Promise<unknown>;
+ isCurrent(): boolean;
+ now(): number;
+}
+
+/** Per-owner, bounded remote reads. A slow/old peer cannot stall routing or multiply in-flight requests. */
+export function createProviderGroupUsageReader(deps: ProviderGroupUsageReaderDeps) {
+ const cached = new Map<string, { at: number; snapshot: ClaudeSubscriptionUsageSnapshot | null }>();
+ const pending = new Map<string, Promise<ClaudeSubscriptionUsageSnapshot | null>>();
+
+ async function bounded(promise: Promise<ClaudeSubscriptionUsageSnapshot | null>) {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await Promise.race([promise, new Promise<null>((resolve) => {
+ timer = setTimeout(() => resolve(null), PROVIDER_GROUP_USAGE_READ_TIMEOUT_MS);
+ })]);
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+
+ return {
+ async read(member: ProviderGroupMember): Promise<ClaudeSubscriptionUsageSnapshot | null> {
+ if (!deps.isCurrent() || member.kind === 'share'
+ || (member.agentDeviceId && isProviderShareAgentDeviceId(member.agentDeviceId))) return null;
+ const key = JSON.stringify([member.agentDeviceId, member.providerId]);
+ const previous = cached.get(key);
+ if (member.kind !== 'local' && previous && deps.now() - previous.at < REMOTE_USAGE_CACHE_MS) {
+ return providerGroupUsageSnapshot(previous.snapshot, deps.now());
+ }
+ let request = pending.get(key);
+ if (!request) {
+ if (pending.size >= MAX_CACHED_ACCOUNTS) return null;
+ request = Promise.resolve().then(async () => {
+ if (!deps.isCurrent()) return null;
+ const raw = member.kind === 'local'
+ ? await deps.readLocal(member.providerId)
+ : await deps.readRemote(member.agentDeviceId!, member.providerId);
+ return deps.isCurrent() ? providerGroupUsageSnapshot(raw, deps.now()) : null;
+ }).catch(() => null).then((snapshot) => {
+ pending.delete(key);
+ if (deps.isCurrent() && member.kind !== 'local') {
+ if (cached.size >= MAX_CACHED_ACCOUNTS) cached.delete(cached.keys().next().value!);
+ cached.set(key, { at: deps.now(), snapshot });
+ }
+ return snapshot;
+ });
+ pending.set(key, request);
+ }
+ const snapshot = await bounded(request);
+ return deps.isCurrent() ? providerGroupUsageSnapshot(snapshot, deps.now()) : null;
+ },
+ invalidate() { cached.clear(); },
+ };
+}
diff --git a/apps/desktop/src/main/usage/accountUsageLimit.ts b/apps/desktop/src/main/usage/accountUsageLimit.ts
index 5db253d8f6..7e8001a843 100644
--- a/apps/desktop/src/main/usage/accountUsageLimit.ts
+++ b/apps/desktop/src/main/usage/accountUsageLimit.ts
@@ -11,13 +11,18 @@
import { matchCodexBucketForModel } from '@cindy/maker-shared/codex-usage-buckets';
import {
isXaiWeeklyUsageCurrent,
- matchScopedWindowForModel,
} from '@cindy/maker-shared/subscription-usage';
import {
NATIVE_SUBSCRIPTION_DEFAULT_PROVIDER_IDS,
type NativeSubscriptionAuth,
} from '@cindy/model-providers';
-import type { ClaudeSubscriptionUsageSnapshot } from '../../shared/claudeSubscriptionUsage.js';
+import {
+ accountUsageLimitFromWindows as fromWindows,
+ claudeAccountUsageLimit,
+ type AccountUsageLimit,
+ type UsageWindow,
+} from '../../shared/accountUsageLimit.js';
+export { claudeAccountUsageLimit, type AccountUsageLimit } from '../../shared/accountUsageLimit.js';
import type { XaiSubscriptionUsageSnapshot } from '../../shared/xaiSubscriptionUsage.js';
import { getActiveCatalog } from '../maker-host/active-catalog.js';
import {
@@ -29,38 +34,6 @@ import {
} from '../usageBroadcaster.js';
import { readSubscriptionAccountUsage } from './subscriptionAccountUsage.js';
-export interface AccountUsageLimit {
- /** 快照里有仍在有效期内的窗口显示已用满。 */
- limited: boolean;
- /**
- * 受限时的重置时刻(unix ms):用满窗口里最晚的(宁晚勿早);任一用满窗口缺重置时刻
- * 则为 null(拿别的窗口顶替会提前醒来)。未受限时恒为 null——未用满窗口的重置与限流无关。
- */
- resetAtMs: number | null;
-}
-
-interface UsageWindow {
- usedPercent: number;
- resetsAtSec: number | null | undefined;
-}
-
-function hasReset(w: UsageWindow): w is UsageWindow & { resetsAtSec: number } {
- return typeof w.resetsAtSec === 'number' && Number.isFinite(w.resetsAtSec) && w.resetsAtSec > 0;
-}
-
-/**
- * 只认具体窗口显示用满,不认快照级「已触顶」标记(Codex `rateLimitReachedType` 等):
- * 标记说不清由哪个窗口触发,还混有余额耗尽(`credits_depleted`,要充值、不会重置)。
- */
-function fromWindows(windows: readonly UsageWindow[], nowMs: number): AccountUsageLimit {
- // 已过重置点的窗口在快照之后已经翻篇,快照里的用量不再成立。
- const live = windows.filter((w) => !hasReset(w) || w.resetsAtSec * 1000 > nowMs);
- const exhausted = live.filter((w) => w.usedPercent >= 100);
- if (exhausted.length === 0) return { limited: false, resetAtMs: null };
- if (exhausted.some((w) => !hasReset(w))) return { limited: true, resetAtMs: null };
- return { limited: true, resetAtMs: Math.max(...exhausted.map((w) => w.resetsAtSec as number)) * 1000 };
-}
-
function codexWindows(snapshot: RateLimitSnapshot | null | undefined): UsageWindow[] {
if (!snapshot) return [];
return [snapshot.primary, snapshot.secondary]
@@ -94,35 +67,6 @@ export function codexAccountUsageLimit(
return fromWindows(windows, nowMs);
}
-const CLAUDE_REJECTED_CLAIM_TO_WINDOW = {
- five_hour: 'fiveHour',
- seven_day: 'sevenDay',
-} as const;
-
-/** Claude 订阅:总窗口 + 仅当前模型的专属周窗口(别的模型的专属窗口用满不影响本会话)。 */
-export function claudeAccountUsageLimit(
- snapshot: ClaudeSubscriptionUsageSnapshot | null,
- modelId?: string | null,
- nowMs = Date.now(),
-): AccountUsageLimit | null {
- if (!snapshot) return null;
- const scoped = matchScopedWindowForModel(snapshot.scoped, modelId);
- const windows: UsageWindow[] = [snapshot.fiveHour, snapshot.sevenDay, scoped]
- .filter((w): w is NonNullable<typeof w> => !!w && typeof w.utilization === 'number')
- .map((w) => ({ usedPercent: w.utilization, resetsAtSec: w.resetsAt }));
- // headers 源被拒时只报状态和「最紧窗口」名,不带用量;把那个窗口视为已用满。
- const rejectedKey =
- snapshot.rateLimitStatus === 'rejected' && snapshot.representativeClaim
- ? CLAUDE_REJECTED_CLAIM_TO_WINDOW[
- snapshot.representativeClaim as keyof typeof CLAUDE_REJECTED_CLAIM_TO_WINDOW
- ]
- : undefined;
- const rejectedWindow = rejectedKey ? snapshot[rejectedKey] : null;
- if (rejectedWindow) windows.push({ usedPercent: 100, resetsAtSec: rejectedWindow.resetsAt });
- if (windows.length === 0) return null;
- return fromWindows(windows, nowMs);
-}
-
/**
* SuperGrok 只有周窗口。快照是 cached-first、后台刷新,超过有效期(或已过重置点)的不用,
* 与用量面板同一判定。
diff --git a/apps/desktop/src/renderer/features/provider-group/ProviderGroupSection.tsx b/apps/desktop/src/renderer/features/provider-group/ProviderGroupSection.tsx
index 2ad4435aae..be58c74b2c 100644
--- a/apps/desktop/src/renderer/features/provider-group/ProviderGroupSection.tsx
+++ b/apps/desktop/src/renderer/features/provider-group/ProviderGroupSection.tsx
@@ -26,6 +26,7 @@ import { Select } from '@/components/ui/select';
import { Switch } from '@/components/ui/switch';
import { Tip } from '@/components/ui/tooltip';
import { useOptionalAuthDeviceId } from '@/contexts/AuthContext';
+import { useProviders } from '@/hooks/useProviders';
import { toast } from '@/lib/toast';
import { cn } from '@/lib/utils';
import { mapIpcErrorToI18nKey } from '@/utils/ipcError';
@@ -41,6 +42,7 @@ import {
} from '../../../shared/providerGroup';
import { providerShareComputerName, useProviderShareOwnerNameOf } from '../provider-share/providerShareNames';
import { GroupMemberQuota, groupMemberQuotaTarget } from './GroupMemberQuota';
+import { providerWeeklyQuotaSource } from '../../../shared/providerQuotaSource';
import { ProviderGroupAddDialog } from './ProviderGroupAddDialog';
import { useProviderGroup } from './useProviderGroup';
@@ -51,6 +53,9 @@ export function ProviderGroupSection({ providerId, providerName }: { providerId:
const { t } = useTranslation();
const { confirm } = useConfirmDialog();
const group = useProviderGroup(providerId, { live: true });
+ const { providers } = useProviders();
+ const provider = providers.find((entry) => entry.id === providerId);
+ const supportsUsage = provider && providerWeeklyQuotaSource({ ...provider, connected: true, suspended: false }) === 'claude';
const [addOpen, setAddOpen] = useState(false);
const [saving, setSaving] = useState(false);
const config = group.view?.config ?? null;
@@ -173,7 +178,7 @@ export function ProviderGroupSection({ providerId, providerName }: { providerId:
value={config.strategy}
onValueChange={(strategy: ProviderGroupStrategy) => void save({ ...config, strategy })}
aria-label={t('providerGroup.strategy.label')}
- options={PROVIDER_GROUP_STRATEGIES.map((value) => ({
+ options={PROVIDER_GROUP_STRATEGIES.filter((value) => value !== 'usage' || supportsUsage || config.strategy === 'usage').map((value) => ({
value,
label: t(`providerGroup.strategy.${value}`),
disabled: saving,
diff --git a/apps/desktop/src/renderer/features/provider-group/__tests__/ProviderGroupSection.test.tsx b/apps/desktop/src/renderer/features/provider-group/__tests__/ProviderGroupSection.test.tsx
index bf6314ba55..be04bc35f6 100644
--- a/apps/desktop/src/renderer/features/provider-group/__tests__/ProviderGroupSection.test.tsx
+++ b/apps/desktop/src/renderer/features/provider-group/__tests__/ProviderGroupSection.test.tsx
@@ -4,23 +4,30 @@
* 再次打开时先显示已知的组,不从「读取中」重来。
*/
import { act, cleanup, fireEvent, render, renderHook, screen, waitFor, within } from '@testing-library/react';
+import { createInstance } from 'i18next';
import type { ReactNode } from 'react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import type { ProviderGroupConfig, ProviderGroupView } from '../../../../shared/providerGroup';
+import zhCN from '../../../i18n/locales/zh-CN/common.json';
import { memberStatusText, ProviderGroupSection } from '../ProviderGroupSection';
import { __testing as localGroupsTesting, useLocalProviderGroupsState } from '../useLocalProviderGroups';
import { __testing as groupViewTesting } from '../useProviderGroup';
+let realLocale: ReturnType<typeof createInstance> | null = null;
+const providerState = vi.hoisted(() => ({ providers: [
+ { id: 'anthropic', connected: true, auth: { method: 'oauth', native: 'claude' } },
+] }));
vi.mock('react-i18next', () => ({
initReactI18next: { type: '3rdParty', init: () => undefined },
- useTranslation: () => ({
+ useTranslation: () => realLocale ? { t: realLocale.t, i18n: realLocale } : ({
t: (key: string, options?: Record<string, unknown>) =>
options && Object.keys(options).length > 0 ? `${key}:${JSON.stringify(options)}` : key,
i18n: { language: 'en' },
}),
}));
vi.mock('@/lib/toast', () => ({ toast: { success: vi.fn(), error: vi.fn(), info: vi.fn() } }));
+vi.mock('@/hooks/useProviders', () => ({ useProviders: () => providerState }));
const confirmSpy = vi.hoisted(() => vi.fn(async () => true));
vi.mock('@/components/ui/confirm-dialog-provider', () => ({ useConfirmDialog: () => ({ confirm: confirmSpy }) }));
// Radix 的浮层要 ResizeObserver,jsdom 里没有;行内「更多操作」菜单只需要验证菜单项的行为,
@@ -89,6 +96,8 @@ function viewOf(config: ProviderGroupConfig | null): ProviderGroupView {
}
beforeEach(() => {
+ realLocale = null;
+ providerState.providers = [{ id: 'anthropic', connected: true, auth: { method: 'oauth', native: 'claude' } }];
stored = null;
running = null;
localGroupsTesting.reset();
@@ -198,6 +207,8 @@ describe('ProviderGroupSection', () => {
await screen.findAllByTestId('provider-group-member');
fireEvent.click(screen.getByRole('radio', { name: 'providerGroup.strategy.round' }));
await waitFor(() => expect(stored?.strategy).toBe('round'));
+ fireEvent.click(screen.getByRole('radio', { name: 'providerGroup.strategy.usage' }));
+ await waitFor(() => expect(stored?.strategy).toBe('usage'));
fireEvent.click(screen.getByRole('switch', { name: 'providerGroup.autoSwitch.label' }));
await waitFor(() => expect(stored?.autoSwitch).toBe(false));
});
@@ -210,6 +221,26 @@ describe('ProviderGroupSection', () => {
await waitFor(() => expect(stored?.members.map((m) => m.key)).toEqual(['local']));
expect(confirmSpy).toHaveBeenCalledWith(expect.objectContaining({ confirmVariant: 'destructive' }));
});
+
+ it('shows the actual Chinese usage-balancing option and saves it for a disconnected subscription', async () => {
+ realLocale = createInstance();
+ await realLocale.init({ lng: 'zh-CN', resources: { 'zh-CN': { translation: zhCN } }, interpolation: { escapeValue: false } });
+ providerState.providers[0].connected = false;
+ stored = { strategy: 'least', autoSwitch: true, members: [LOCAL] };
+ render(<ProviderGroupSection providerId="anthropic" providerName="Claude" />);
+ const option = await screen.findByRole('radio', { name: '用量均衡' });
+ fireEvent.click(option);
+ await waitFor(() => expect(stored?.strategy).toBe('usage'));
+ expect(await screen.findByText('按5小时和每周用量分配')).toBeTruthy();
+ });
+
+ it('does not offer subscription balancing for an API key connection', async () => {
+ providerState.providers[0].auth.method = 'api-key';
+ stored = { strategy: 'least', autoSwitch: true, members: [LOCAL] };
+ render(<ProviderGroupSection providerId="anthropic" providerName="Anthropic" />);
+ await screen.findAllByTestId('provider-group-member');
+ expect(screen.queryByRole('radio', { name: 'providerGroup.strategy.usage' })).toBeNull();
+ });
});
describe('ProviderGroupSection reopened', () => {
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 82019c9eee..23491a6227 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -443,11 +443,13 @@
"round": "Round Robin",
"order": "In Order",
"weight": "By Weight",
+ "usage": "Usage Balancing",
"description": {
"least": "Goes to the least busy one",
"round": "Rotates across computers",
"order": "Earlier in the list first",
- "weight": "Split by weight"
+ "weight": "Split by weight",
+ "usage": "Balance 5-hour and weekly usage"
}
},
"autoSwitch": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index 06dfced78d..478d3e5359 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -440,11 +440,13 @@
"round": "順番に",
"order": "並び順",
"weight": "重み付け",
+ "usage": "使用量で分散",
"description": {
"least": "空いているパソコンへ",
"round": "順番に割り当て",
"order": "上のパソコンを優先",
- "weight": "重みの比率で"
+ "weight": "重みの比率で",
+ "usage": "5時間・週間の使用量で分散"
}
},
"autoSwitch": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 94bd506dd4..fc65ad8061 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -440,11 +440,13 @@
"round": "순환",
"order": "순서대로",
"weight": "가중치",
+ "usage": "사용량 균형",
"description": {
"least": "가장 여유로운 컴퓨터로",
"round": "차례대로 배정",
"order": "목록 앞쪽 우선",
- "weight": "가중치 비율로"
+ "weight": "가중치 비율로",
+ "usage": "5시간·주간 사용량에 따라 배정"
}
},
"autoSwitch": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index d87aa77c41..8e03fca5d5 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -440,11 +440,13 @@
"round": "轮询",
"order": "按顺序",
"weight": "按权重",
+ "usage": "用量均衡",
"description": {
"least": "给最闲的那台",
"round": "依次轮流",
"order": "排前面的优先",
- "weight": "按权重比例"
+ "weight": "按权重比例",
+ "usage": "按5小时和每周用量分配"
}
},
"autoSwitch": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 97b22b6400..570dddcd53 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -440,11 +440,13 @@
"round": "輪詢",
"order": "依順序",
"weight": "依權重",
+ "usage": "用量均衡",
"description": {
"least": "給最閒的那臺",
"round": "依序輪流",
"order": "排前面的優先",
- "weight": "依權重比例"
+ "weight": "依權重比例",
+ "usage": "按5小時和每週用量分配"
}
},
"autoSwitch": {
diff --git a/apps/desktop/src/shared/__tests__/providerGroup.test.ts b/apps/desktop/src/shared/__tests__/providerGroup.test.ts
index 8490e7aa62..b46f32d447 100644
--- a/apps/desktop/src/shared/__tests__/providerGroup.test.ts
+++ b/apps/desktop/src/shared/__tests__/providerGroup.test.ts
@@ -19,6 +19,11 @@ describe('providerGroupMemberKey', () => {
});
describe('normalizeProviderGroupConfig', () => {
+ it('round-trips the opt-in usage strategy without changing the default', () => {
+ expect(normalizeProviderGroupConfig({ strategy: 'usage', members: [{ kind: 'local' }] }, 'anthropic')?.strategy).toBe('usage');
+ expect(normalizeProviderGroupConfig({ members: [{ kind: 'local' }] }, 'anthropic')?.strategy).toBe('least');
+ });
+
it('keeps valid members, fills defaults and pins the local member to the group provider', () => {
const config = normalizeProviderGroupConfig({
strategy: 'round',
diff --git a/apps/desktop/src/shared/accountUsageLimit.ts b/apps/desktop/src/shared/accountUsageLimit.ts
new file mode 100644
index 0000000000..ba4d20e223
--- /dev/null
+++ b/apps/desktop/src/shared/accountUsageLimit.ts
@@ -0,0 +1,43 @@
+/** Pure quota checks shared by automatic continuation and provider-group routing. */
+import { matchScopedWindowForModel, type ClaudeSubscriptionUsageSnapshot } from '@cindy/maker-shared/subscription-usage';
+
+export interface AccountUsageLimit {
+ limited: boolean;
+ /** Latest reset among exhausted windows; null if any exhausted window has no reset. */
+ resetAtMs: number | null;
+}
+
+export interface UsageWindow {
+ usedPercent: number;
+ resetsAtSec: number | null | undefined;
+}
+
+function hasReset(w: UsageWindow): w is UsageWindow & { resetsAtSec: number } {
+ return typeof w.resetsAtSec === 'number' && Number.isFinite(w.resetsAtSec) && w.resetsAtSec > 0;
+}
+
+/** Expired windows cannot keep an account blocked; unknown resets cannot borrow another window's reset. */
+export function accountUsageLimitFromWindows(windows: readonly UsageWindow[], nowMs: number): AccountUsageLimit {
+ const live = windows.filter((w) => !hasReset(w) || w.resetsAtSec * 1000 > nowMs);
+ const exhausted = live.filter((w) => w.usedPercent >= 100);
+ if (exhausted.length === 0) return { limited: false, resetAtMs: null };
+ if (exhausted.some((w) => !hasReset(w))) return { limited: true, resetAtMs: null };
+ return { limited: true, resetAtMs: Math.max(...exhausted.map((w) => w.resetsAtSec as number)) * 1000 };
+}
+
+/** Only this model's scoped weekly window can restrict the selected model. */
+export function claudeAccountUsageLimit(
+ snapshot: ClaudeSubscriptionUsageSnapshot | null,
+ modelId?: string | null,
+ nowMs = Date.now(),
+): AccountUsageLimit | null {
+ if (!snapshot) return null;
+ const scoped = matchScopedWindowForModel(snapshot.scoped, modelId);
+ const windows: UsageWindow[] = [snapshot.fiveHour, snapshot.sevenDay, scoped]
+ .filter((w): w is NonNullable<typeof w> => !!w && typeof w.utilization === 'number')
+ .map((w) => ({ usedPercent: w.utilization, resetsAtSec: w.resetsAt }));
+ const claim = snapshot.rateLimitStatus === 'rejected' ? snapshot.representativeClaim : null;
+ const rejectedWindow = claim === 'five_hour' ? snapshot.fiveHour : claim === 'seven_day' ? snapshot.sevenDay : null;
+ if (rejectedWindow) windows.push({ usedPercent: 100, resetsAtSec: rejectedWindow.resetsAt });
+ return windows.length === 0 ? null : accountUsageLimitFromWindows(windows, nowMs);
+}
diff --git a/apps/desktop/src/shared/providerGroup.ts b/apps/desktop/src/shared/providerGroup.ts
index a2fa3a53a2..4d17b6b8a7 100644
--- a/apps/desktop/src/shared/providerGroup.ts
+++ b/apps/desktop/src/shared/providerGroup.ts
@@ -14,8 +14,8 @@ export const PROVIDER_GROUP_IPC = {
CHANGED: 'provider-group:changed',
} as const;
-export type ProviderGroupStrategy = 'least' | 'round' | 'order' | 'weight';
-export const PROVIDER_GROUP_STRATEGIES: readonly ProviderGroupStrategy[] = ['least', 'round', 'order', 'weight'];
+export type ProviderGroupStrategy = 'least' | 'round' | 'order' | 'weight' | 'usage';
+export const PROVIDER_GROUP_STRATEGIES: readonly ProviderGroupStrategy[] = ['least', 'round', 'order', 'weight', 'usage'];
export type ProviderGroupMemberKind = 'local' | 'device' | 'share';
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 49933b8d59..d05a903700 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -872,6 +872,24 @@ B 上的 Worker 是一条普通任务,`sessions.orca_remote_lead`(migration 01
`service.ts` 的组来源);回归见同目录 `__tests__/remoteGroup.test.ts`、`remoteHandler.test.ts`、`leaseReporter.test.ts`,
`device-link/__tests__/providerShareDispatch.test.ts`(受邀者拒绝与不泄露组摘要)。
+## 供应商组:Claude 订阅额度筛选与用量均衡(2026-10-12)
+
+产品规则见 [`provider-groups.md`](../product-rules/provider-groups.md) §5。选电脑仍由组所在电脑完成:先排除额度耗尽的成员,
+再按所选策略分配;新策略 `usage` 只用于 Claude Code 订阅组。
+
+- **可选策略枚举扩展**:本地组配置与同账号组摘要的 `strategy` 增加 `usage`,原默认 `least` 不变。
+ 旧版桌面读取未知策略时归一化为 `least`,旧版手机不依赖这个字段;远程 `pick` 仍由组所在电脑执行,因此
+ 旧控制端连接新组所在电脑也能使用新策略。组所在电脑降级后按 `least` 分配,旧版再次保存组设置会写回 `least`。
+- **复用已有同账号通道**:向成员电脑调用 `maker:usage:claude-subscription`,参数 `[member.providerId]`;本机走同一
+ 订阅 reader。只信与请求一致的 `providerId` 回显;旧端未回显时仅允许默认 `anthropic`,具名账号按未知用量处理,
+ 避免旧端忽略参数后拿默认账号的额度代替。通道不可用、失败、超时或快照过期时按未知处理,分配照常进行。
+- **隐私与状态**:额度快照只留在组所在电脑的内部目录中,不加入 `ProviderGroupView` 或供应商目录,不传给受邀者;
+ 分享来的成员不调用此通道。同账号 `view` 仅复用已有 `cooling` / `coolingUntil` 表达总窗口耗尽,当前模型专属
+ 周窗口只用于选路,不改变其他模型的可用性。账号切换时丢弃旧读取,不扩大 allowlist 或凭证访问。
+- 不新增 channel,不改 relay、服务器、数据库或持久冷却格式。实现:`provider-group/usage.ts`、`directory.ts`、
+ `runtime.ts`、`router.ts`、`scheduler.ts`;额度判定与自动继续复用 `shared/accountUsageLimit.ts`。回归见
+ `provider-group/__tests__/usage.test.ts`、`router.usage.test.ts`、`runtime.test.ts` 与 `scheduler.test.ts`。
+
## 供应商组:受邀者经组所在电脑中转(P2b)
产品规则见 [`provider-groups.md`](../product-rules/provider-groups.md) §4「分享的人(中转)」、§8、§9。受邀者 G 用组所在电脑 O
diff --git a/docs/product-rules/provider-groups.md b/docs/product-rules/provider-groups.md
index 4a049f026f..88325651ee 100644
--- a/docs/product-rules/provider-groups.md
+++ b/docs/product-rules/provider-groups.md
@@ -133,7 +133,7 @@
## 5. 组策略
- **选择方式**:最少占用(默认,选正在运行任务最少的那台)、轮询、按顺序(排在前面的优先,前面的不可用才用后面的)、
- 按权重。
+ 按权重、用量均衡(Claude Code 订阅组)。已有组与新组的默认仍为最少占用。
- **并发上限**:每台组内电脑单独设置,默认 4,最多 16(远程 Agent 对每个控制端的上限);只统计经本组分到这台的任务,
包括同账号其他电脑经本组直连过去的任务:它们由任务所在的电脑在每一轮开始、结束时报告,运行期间每分钟再报一次,
组所在电脑 150 秒收不到就不再计入;刚选中、还没报告的任务先按占用记 30 秒,同时开的几个任务不会全落到同一台。
@@ -151,6 +151,22 @@
- **只分给可用的电脑**:在线;对方仍允许远程控制,且仍对这个供应商允许被远程调用;分享未暂停、未删除;
不在冷却中;提供所选模型;未被设为「暂停分配」。优先分给未达到并发上限的;都满了时分给相对最空的一台,
并发上限只用来分摊,不因满载拒绝消息。
+- **先排除额度耗尽,再比较用量**(2026-10-12 用户确认):所有组策略都复用上面的可用性筛选;本机与同账号电脑上的
+ Claude Code 订阅另读已有的订阅用量快照,5 小时、总周额度或当前模型专属周额度任一用完,就不再分给它,
+ 不必先运行失败一次。重置时刻与 [用量上限自动继续](usage-limit-auto-continue.md) 共用判定;已过重置时刻的旧窗口不再阻塞。
+ 组状态把总窗口耗尽显示为冷却中;模型专属周额度只影响对应模型,不能把其他模型一起封住。快照判断不写入持久冷却,
+ 原来由实际错误产生的冷却照旧保留。
+ - **用量均衡**:先做上述排除,再从未达到并发上限的候选中比较 5 小时、总周与当前模型专属周窗口的
+ **最高已用百分比**,越低越优先;与最低值相差不超过 5 个百分点时,选正在运行任务少的那台。
+ 两个总窗口都有效且已知才参与比较;有对应模型的专属窗口时,它也必须有效。缺失值不当成 0%;
+ 有可信用量的候选优先,没有时回退最少占用。全部达到并发上限时也回退最少占用。
+ - **取数与兜底**:复用原生 CLI 的订阅用量读取,不读凭证、不新增订阅 API 请求;每台按自己的供应商账号读取。
+ 同账号远端快照短缓存 15 秒,同账号同一请求在途去重;单次最多等待 1.5 秒,超时或旧端不支持时按未知用量继续,
+ 后台晚到结果供后续分配使用。快照超过 10 分钟或时间异常时不用于排除与排序;已重置但还没刷新的窗口也不当成零用量。
+ 重试选电脑时清掉短缓存。账号切换后丢弃旧账号的读取结果。
+ - **分享边界**:不读取别人分享来的电脑的订阅配额,按未知用量处理,仍复用现有可用性与失败后换电脑;
+ 组所在电脑为受邀者选电脑时可以使用自己组内的同账号配额,但不向受邀者返回配额。
+ - 正常运行的任务不因用量差距而迁移;新任务和需要换电脑时才按此策略分配。
- **冷却**:组内电脑上的任务报用量上限时,这台电脑进入冷却,不再接新任务。重置时刻按
[用量上限自动继续](usage-limit-auto-continue.md) 的口径取(不采用不带时区的钟点);取不到时默认冷却 30 分钟。
冷却不主动迁移这台电脑上正在运行的其他任务;它们自己撞到上限时再按 §6.1 换电脑。
@@ -436,7 +452,8 @@
这个账号的订阅配额(5 小时 / 每周剩余等),与供应商详情页底部的用量卡、任务底部的用量条同一份数据;
紧贴在这一行下方、与电脑名左对齐,不再出卡片的「Claude · 套餐」标题行(行本身已说明是哪台电脑)。
本机读本机账号,我的其他电脑经设备互联读那台的账号;别人分享来的电脑不读(分享者的配额不对受邀者开放),
- 只写「别人分享的电脑不显示配额」;不在线的电脑不去读。只在展开时读,收起的行不读任何电脑。
+ 只写「别人分享的电脑不显示配额」;不在线的电脑不去读。展示组件只在展开时读,收起时停止展示读取;
+ 组状态与分配所需的 Claude 订阅额度另按 §5 读取,不依赖这一行是否展开。
另一台电脑上的组的只读列表同样可以展开。这是剩余配额,不是 §7 的经组运行的用量统计(P3)。
- **添加电脑**:弹窗分「已经能用的」与「分享链接」两页:前者把你的其他电脑和别人分享给你的放在同一个列表里勾选;分享链接沿用申请与配对码流程,
供应商不一致(§3 口径)、链接属于自己账号、链接失效时给出对应提示。
@@ -511,7 +528,9 @@
## 13. 验收
1. 链接的供应商与组不是同一个(§3 口径)、链接属于自己账号、链接失效时不发送申请,并给出对应提示。
-2. 组所在电脑、同账号其他电脑、分享的人三种使用都按组策略分配,组内电脑离线、冷却、暂停分配、满载或不提供所选模型时不会被选中。
+2. 组所在电脑、同账号其他电脑、分享的人三种使用都按组策略分配;离线、冷却、暂停分配、不提供所选模型,或可信快照显示
+ 所需 Claude 订阅额度已耗尽的电脑不会被选中。优先未满载的,全部满载时仍选运行任务最少的。用量均衡遵守 §5 的
+ 两步筛选、5 个百分点内按占用分摊与未知用量兜底,重置后的旧窗口不再阻塞。
3. 正常运行的任务固定在原电脑;原电脑因 §6.1 列出的原因失败时,自动交接到组内另一台继续这一轮,消息流显示换电脑的
活动记录;同一轮每台最多试一次,全部失败才报错并逐台列出原因;其中有撞上限的,等最早恢复的一台自动继续。
4. 用户停止、权限被拒、上下文超限、请求无效、内容被拒、工具出错时不换电脑;其余失败都换(含认不出的)。「故障 × 阶段」的判定表
diff --git a/i18n/GLOSSARY.md b/i18n/GLOSSARY.md
index 08cf4049b6..a57b3d8da8 100644
--- a/i18n/GLOSSARY.md
+++ b/i18n/GLOSSARY.md
@@ -309,7 +309,7 @@ Chat Server 的群角色,可由人或伙伴担任;不要与伙伴主人或
### Group Strategy
-供应商组为新任务选择组内电脑的规则:最少占用、轮询、按顺序、按权重。只决定新任务分到哪台,已开始的任务不迁移。
+供应商组为新任务选择组内电脑的规则:最少占用、轮询、按顺序、按权重、用量均衡。只决定新任务分到哪台,正常运行的任务不因均衡迁移。
### Harness
@@ -585,6 +585,10 @@ Cindy 里的**持久 AI 助手实体**(原名 Bot):有长期身份、自
客户端日志上报后返回给用户的短标识, 用户报障时口述给我们。zh-CN 取「编号」而不是「码」——它是一次上报的检索标识, 不是验证码或错误码, 「上传码」容易被读成验证码。proposed: 日志上报是新链路, 等实际排障流程跑一段后再固化。
+### Usage Balancing
+
+Claude 订阅供应商组的分配策略:先排除5小时或周配额耗尽的账号,再优先分给用量较低的可用账号;不迁移正常运行的任务。
+
### Use my browser logins
设置 → 自动操作里,把系统 Chrome / Edge / Brave 当前 profile 的 cookie 与保存的密码快照到 Agent 专用浏览器。不是接管日常窗口。不要译成 real profile / 真实配置文件。
diff --git a/i18n/glossary.json b/i18n/glossary.json
index bb361b481f..5ba884f917 100644
--- a/i18n/glossary.json
+++ b/i18n/glossary.json
@@ -2383,7 +2383,20 @@
"ko": "그룹 배정 방식"
},
"checkCase": false,
- "note": "供应商组为新任务选择组内电脑的规则:最少占用、轮询、按顺序、按权重。只决定新任务分到哪台,已开始的任务不迁移。"
+ "note": "供应商组为新任务选择组内电脑的规则:最少占用、轮询、按顺序、按权重、用量均衡。只决定新任务分到哪台,正常运行的任务不因均衡迁移。"
+ },
+ {
+ "id": "usage-balancing",
+ "status": "proposed",
+ "en": "Usage Balancing",
+ "translations": {
+ "zh-CN": "用量均衡",
+ "zh-TW": "用量均衡",
+ "ja": "使用量で分散",
+ "ko": "사용량 균형"
+ },
+ "checkCase": false,
+ "note": "Claude 订阅供应商组的分配策略:先排除5小时或周配额耗尽的账号,再优先分给用量较低的可用账号;不迁移正常运行的任务。"
},
{
"id": "pairing-code",