@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/models/__tests__/budget.test.ts

@@ -0,0 +1,367 @@
+// 测试框架：vitest
+// 运行命令：npx vitest run src/orchestration/models/__tests__/budget.test.ts
+
+import { describe, expect, it } from "vitest";
+
+import {
+  Budget,
+  CACHE_READ_WEIGHT,
+  CACHE_WRITE_WEIGHT,
+  INPUT_WEIGHT,
+  OUTPUT_WEIGHT,
+  SOFT_MAX_AGENTS_WARNING,
+} from "../budget.js";
+import type { AgentUsage } from "../types.js";
+
+/** 构造合法 AgentUsage，未指定字段补 0。 */
+function usage(partial: Partial<AgentUsage>): AgentUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+    ...partial,
+  };
+}
+
+/**
+ * 构造"有毒" usage：刻意注入 undefined / NaN / Infinity，
+ * 模拟 provider 返回脏数据或 JSON 反序列化缺字段时的运行时场景。
+ *
+ * 单层 `as AgentUsage`：AgentUsage 全部必填字段（非全可选结构），
+ * 不触发 taste/no-unsafe-cast 的 structuralCast；此处刻意绕过类型系统
+ * 以验证 consume() 的运行时 NaN 守卫。
+ */
+function poisonedUsage(
+  overrides: Partial<Record<keyof AgentUsage, number | undefined>>,
+): AgentUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+    ...overrides,
+  } as AgentUsage;
+}
+
+// ── consume：加权公式 ────────────────────────────────────────
+
+describe("Budget.consume 加权公式", () => {
+  it(`纯 input → usedTokens = input × ${INPUT_WEIGHT}`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 100 }));
+    expect(b.usedTokens).toBe(100);
+  });
+
+  it(`纯 output → usedTokens = output × ${OUTPUT_WEIGHT}（自回归开销最高）`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ output: 100 }));
+    expect(b.usedTokens).toBe(200);
+  });
+
+  it(`纯 cacheRead → usedTokens = cacheRead × ${CACHE_READ_WEIGHT}（命中缓存，开销极低）`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ cacheRead: 100 }));
+    expect(b.usedTokens).toBe(2);
+  });
+
+  it(`纯 cacheWrite → usedTokens = cacheWrite × ${CACHE_WRITE_WEIGHT}（首次写缓存不计 budget）`, () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ cacheWrite: 100 }));
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("混合四项加权累加（input×1 + output×2 + cacheRead×0.02 + cacheWrite×0）", () => {
+    const b = new Budget({ maxTokens: 10000 });
+    b.consume(
+      usage({ input: 100, output: 50, cacheRead: 1000, cacheWrite: 500 }),
+    );
+    // 100×1 + 50×2 + 1000×0.02 + 500×0 = 100 + 100 + 20 + 0 = 220
+    expect(b.usedTokens).toBe(220);
+  });
+
+  it("cost 随 consume 累加", () => {
+    const b = new Budget();
+    b.consume(usage({ cost: 0.3 }));
+    expect(b.usedCost).toBe(0.3);
+  });
+
+  it("多次 consume 累加（retry 间如实记录，不减）", () => {
+    const b = new Budget();
+    b.consume(usage({ input: 100, cost: 0.1 }));
+    b.consume(usage({ input: 50, output: 50, cost: 0.2 }));
+    // tokens: 100×1 + (50×1 + 50×2) = 250
+    expect(b.usedTokens).toBe(250);
+    // 0.1 + 0.2 浮点误差，用 toBeCloseTo
+    expect(b.usedCost).toBeCloseTo(0.3);
+  });
+});
+
+// ── consume：NaN 守卫（TDD，预期主 agent 同步补源码守卫）──────
+//
+// 源码 consume() 当前无守卫：undefined/NaN/Infinity 进入加权公式会产出
+// NaN/Infinity 污染 usedTokens，导致后续 isExceeded/isThresholdReached 永远命中。
+// 以下测试断言「脏字段当 0 处理」——守卫补上前会失败，属预期临时状态。
+
+describe("Budget.consume NaN 守卫（undefined/NaN/Infinity 当 0 处理）", () => {
+  it("input=undefined → usedTokens 不变（不当 NaN）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ input: undefined }));
+    expect(b.usedTokens).toBe(0);
+    expect(Number.isNaN(b.usedTokens)).toBe(false);
+  });
+
+  it("output=undefined → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ output: undefined }));
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("input=NaN → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ input: Number.NaN }));
+    expect(b.usedTokens).toBe(0);
+    expect(Number.isNaN(b.usedTokens)).toBe(false);
+  });
+
+  it("output=NaN → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ output: Number.NaN }));
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("cacheRead=NaN / cacheWrite=NaN → usedTokens 不变", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(
+      poisonedUsage({ cacheRead: Number.NaN, cacheWrite: Number.NaN }),
+    );
+    expect(b.usedTokens).toBe(0);
+  });
+
+  it("input=Infinity → usedTokens 不变（Infinity 不烧穿预算）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(poisonedUsage({ input: Number.POSITIVE_INFINITY }));
+    expect(b.usedTokens).toBe(0);
+    expect(Number.isFinite(b.usedTokens)).toBe(true);
+  });
+
+  it("合法字段与脏字段混合 → 仅累加合法部分（脏字段当 0）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    // input=100（合法）+ output=undefined（脏，当 0）
+    b.consume(poisonedUsage({ input: 100, output: undefined }));
+    expect(b.usedTokens).toBe(100);
+  });
+
+  it("已有累计后再遇脏数据 → usedTokens 保持原值不退化", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 50 })); // usedTokens = 50
+    b.consume(poisonedUsage({ input: undefined }));
+    expect(b.usedTokens).toBe(50);
+  });
+
+  it("cost=undefined → usedCost 不当 NaN", () => {
+    const b = new Budget();
+    b.consume(poisonedUsage({ cost: undefined }));
+    expect(b.usedCost).toBe(0);
+    expect(Number.isNaN(b.usedCost)).toBe(false);
+  });
+});
+
+// ── incrementCallCount ───────────────────────────────────────
+
+describe("Budget.incrementCallCount", () => {
+  it("累加调用计数（每次 agent dispatch 后 +1）", () => {
+    const b = new Budget();
+    expect(b.totalCallCount).toBe(0);
+    b.incrementCallCount();
+    b.incrementCallCount();
+    b.incrementCallCount();
+    expect(b.totalCallCount).toBe(3);
+  });
+});
+
+// ── isExceeded ───────────────────────────────────────────────
+
+describe("Budget.isExceeded", () => {
+  it("maxTokens=1000, usedTokens=999 → 未超", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxTokens=1000, usedTokens=1000 → 超限（边界 >=）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1000 }));
+    expect(b.isExceeded()).toBe(true);
+  });
+
+  it("maxTokens=1000, usedTokens=1001 → 超限", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1001 }));
+    expect(b.isExceeded()).toBe(true);
+  });
+
+  it("maxTokens=0 → 视为不限制（守卫，首个 agent 完成不误判）", () => {
+    const b = new Budget({ maxTokens: 0 });
+    b.consume(usage({ input: 999999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxTokens undefined → 视为不限制", () => {
+    const b = new Budget();
+    b.consume(usage({ input: 999999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxCost 边界：usedCost >= maxCost → 超限", () => {
+    const b = new Budget({ maxCost: 1 });
+    b.consume(usage({ cost: 1 }));
+    expect(b.isExceeded()).toBe(true);
+  });
+
+  it("maxCost=0 → 视为不限制", () => {
+    const b = new Budget({ maxCost: 0 });
+    b.consume(usage({ cost: 999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("maxCost undefined → 视为不限制", () => {
+    const b = new Budget();
+    b.consume(usage({ cost: 999 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+
+  it("token 与 cost 均未达阈值 → 不超限", () => {
+    const b = new Budget({ maxTokens: 1000, maxCost: 10 });
+    b.consume(usage({ input: 50, cost: 0.5 }));
+    expect(b.isExceeded()).toBe(false);
+  });
+});
+
+// ── remaining ────────────────────────────────────────────────
+
+describe("Budget.remaining", () => {
+  it("正常：maxTokens - usedTokens", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 300 }));
+    expect(b.remaining()).toBe(700);
+  });
+
+  it("usedTokens > maxTokens → clamp 到 0（不返回负数）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1500 }));
+    expect(b.remaining()).toBe(0);
+  });
+
+  it("maxTokens=1000, usedTokens=1000（恰好用尽）→ 0", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 1000 }));
+    expect(b.remaining()).toBe(0);
+  });
+
+  it("maxTokens undefined → undefined（视为不限制）", () => {
+    const b = new Budget();
+    expect(b.remaining()).toBeUndefined();
+  });
+
+  it("maxTokens <= 0 → undefined（视为不限制）", () => {
+    const b = new Budget({ maxTokens: 0 });
+    expect(b.remaining()).toBeUndefined();
+  });
+});
+
+// ── isThresholdReached ───────────────────────────────────────
+
+describe("Budget.isThresholdReached", () => {
+  it("达到 90% 阈值（usedTokens >= maxTokens × 0.9）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 900 }));
+    expect(b.isThresholdReached(0.9)).toBe(true);
+  });
+
+  it("未达 90% 阈值", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 899 }));
+    expect(b.isThresholdReached(0.9)).toBe(false);
+  });
+
+  it("边界：恰好等于阈值 → true（>= 语义）", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 950 }));
+    expect(b.isThresholdReached(0.95)).toBe(true);
+  });
+
+  it("maxTokens=0 → false（守卫）", () => {
+    const b = new Budget({ maxTokens: 0 });
+    b.consume(usage({ input: 999999 }));
+    expect(b.isThresholdReached(0.9)).toBe(false);
+  });
+
+  it("maxTokens undefined → false", () => {
+    const b = new Budget();
+    b.consume(usage({ input: 999999 }));
+    expect(b.isThresholdReached(0.9)).toBe(false);
+  });
+
+  it("纯查询无状态——重复查询结果一致", () => {
+    const b = new Budget({ maxTokens: 1000 });
+    b.consume(usage({ input: 950 }));
+    expect(b.isThresholdReached(0.9)).toBe(true);
+    expect(b.isThresholdReached(0.9)).toBe(true);
+  });
+});
+
+// ── isSoftLimitReached ───────────────────────────────────────
+
+describe("Budget.isSoftLimitReached", () => {
+  it(`totalCallCount > ${SOFT_MAX_AGENTS_WARNING} 触发（> 严格语义）`, () => {
+    const b = new Budget();
+    for (let i = 0; i < SOFT_MAX_AGENTS_WARNING; i++) b.incrementCallCount();
+    expect(b.isSoftLimitReached()).toBe(false);
+    b.incrementCallCount(); // 501
+    expect(b.isSoftLimitReached()).toBe(true);
+  });
+
+  it("无状态——可重复查询（非一次性 flag）", () => {
+    const b = new Budget({ totalCallCount: SOFT_MAX_AGENTS_WARNING + 1 });
+    expect(b.isSoftLimitReached()).toBe(true);
+    expect(b.isSoftLimitReached()).toBe(true);
+  });
+});
+
+// ── 构造 ─────────────────────────────────────────────────────
+
+describe("Budget 构造", () => {
+  it("默认值全 0 / undefined", () => {
+    const b = new Budget();
+    expect(b.usedTokens).toBe(0);
+    expect(b.usedCost).toBe(0);
+    expect(b.totalCallCount).toBe(0);
+    expect(b.maxTokens).toBeUndefined();
+    expect(b.maxCost).toBeUndefined();
+    expect(b.maxTimeMs).toBeUndefined();
+  });
+
+  it("从持久化数据重建（保留全部字段）", () => {
+    const b = new Budget({
+      maxTokens: 5000,
+      maxCost: 2,
+      maxTimeMs: 60000,
+      usedTokens: 100,
+      usedCost: 0.3,
+      totalCallCount: 7,
+    });
+    expect(b.maxTokens).toBe(5000);
+    expect(b.maxCost).toBe(2);
+    expect(b.maxTimeMs).toBe(60000);
+    expect(b.usedTokens).toBe(100);
+    expect(b.usedCost).toBe(0.3);
+    expect(b.totalCallCount).toBe(7);
+  });
+});

package/src/orchestration/models/agent-call.ts

@@ -0,0 +1,76 @@
+/**
+ * Workflow Extension — AgentCall 实体
+ *
+ * 单次 agent 调用的数据 + 不变式守卫（D-12）。纯数据，无 execute 上帝方法——
+ * 执行编排（重试+预算+stale 检测）在 execute-agent-call.ts 的 free function。
+ *
+ * - 状态机：pending → running → done（不可逆）
+ * - markRunning 进入 running 并 attempts++（每次 retry 前调用）
+ * - markDone(result) 进入 done 并记录结果
+ * - traceNode 持有引用，但 AgentCall 不直接改其字段——trace 同步由
+ * Trace.update 负责（D-10 单一来源），AgentCall 只持有引用供 executeAgentCall 读取
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §5（字段/不变式/设计决策）。
+ */
+import type { AgentCallOpts, AgentResult, ExecutionTraceNode } from "./types.ts";
+
+/** AgentCall 生命周期状态。pending→running→done，不可逆。 */
+export type AgentCallStatus = "pending" | "running" | "done";
+
+/**
+ * AgentCall 实体（在 RunState.calls Map 内）。
+ *
+ * 不变式：
+ * - status 转换严格 pending→running→done，反向抛错
+ * - done 时 result 必须已设置（markDone(result) 前置保证）
+ * - attempts 反映 dispatch 次数（markRunning 累加，含首次）
+ * - **无 execute 方法**（D-12：执行编排由 Engine executeAgentCall 函数承担）
+ */
+export class AgentCall {
+  readonly id: number;
+  readonly opts: AgentCallOpts;
+  status: AgentCallStatus = "pending";
+  attempts = 0;
+  result?: AgentResult;
+ /** Pi subprocess session ID（uuidv7，G-017 归此）。 */
+  sessionId?: string;
+ /** 与 Trace 共享的节点引用（D-10 单源）。AgentCall 不直接改其字段。 */
+  readonly traceNode: ExecutionTraceNode;
+
+  constructor(id: number, opts: AgentCallOpts, traceNode: ExecutionTraceNode) {
+    this.id = id;
+    this.opts = opts;
+    this.traceNode = traceNode;
+  }
+
+ /**
+ * 标记进入 running 状态（dispatch 前）。attempts++（含首次）。
+ * @throws 若已 done（不可重启）
+ */
+  markRunning(): void {
+    if (this.status === "done") {
+      throw new Error(`AgentCall ${this.id} already done — cannot mark running`);
+    }
+    this.status = "running";
+    this.attempts += 1;
+  }
+
+ /**
+ * 标记完成（成功或失败均调用——result.error 区分）。
+ * @throws 若当前非 running（pending 不能直接跳 done，必须先 markRunning）
+ */
+  markDone(result: AgentResult): void {
+    if (this.status !== "running") {
+      throw new Error(`AgentCall ${this.id} must be running to mark done (was ${this.status})`);
+    }
+    this.result = result;
+    this.status = "done";
+  }
+
+ /** 记录 pi subprocess session ID（dispatch 成功后）。 */
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+  }
+}

package/src/orchestration/models/budget.ts

@@ -0,0 +1,148 @@
+/**
+ * Workflow Extension — Budget 值对象
+ *
+ * Token / cost 预算值对象（D-12）。纯数据 + 不变式守卫，无副作用。
+ *
+ * 设计：
+ * - 无 onConsume 回调（值对象不应持可变回调）。
+ * - soft limit 通知由 lifecycle 层 consume 后查 isSoftLimitReached 发出（职责分离）。
+ * - 90% 预警用查询式 isThresholdReached（无状态，可重复查）。
+ * - maxTokens===0 视为不限制（守卫，避免首个 agent 完成误判 budget_limited）。
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §4（字段/不变式/操作）。
+ */
+import type { AgentUsage } from "./types.ts";
+
+/** Soft limit：总调用数超此值发预警（FR-7，从 ConcurrencyGate 迁入）。 */
+export const SOFT_MAX_AGENTS_WARNING = 500;
+
+/**
+ * Budget 加权系数（token 口径）。
+ *
+ * usedTokens 不再是四项原始 token 简单求和，而是加权后的「等效消耗」，
+ * 反映不同 token 桶的真实计费/处理开销差异：
+ * - input（非缓存新增）：首次见到、需完整处理的新内容，权重 1（基准）
+ * - cacheRead（命中缓存）：读取历史，开销极低，按 1/50 折算（权重 0.02）
+ * - cacheWrite（首次写入缓存）：本版本不计入 budget（权重 0）
+ * - output：模型自回归生成，开销最高，权重 2
+ *
+ * 这避免了长 session 中 cacheRead 随轮次单调累积导致 budget 被快速烧穿的失真
+ * （详见讨论：cacheRead 在 N 轮里被报 N 次，去重上下文只有一份）。
+ */
+export const INPUT_WEIGHT = 1;
+export const CACHE_READ_WEIGHT = 0.02;
+export const CACHE_WRITE_WEIGHT = 0;
+export const OUTPUT_WEIGHT = 2;
+
+/**
+ * Budget 值对象。
+ *
+ * 不变式（domain-models.md §4）：
+ * - maxTokens > 0 守卫：maxTokens===0 或 undefined 视为不限制
+ * - maxCost > 0 守卫：同上
+ * - consume 只累加，不减；isExceeded 只读
+ * - 无回调字段——所有副作用由调用方在 consume 后查询决定
+ */
+export class Budget {
+  readonly maxTokens?: number;
+  readonly maxCost?: number;
+  readonly maxTimeMs?: number;
+  usedTokens = 0;
+  usedCost = 0;
+ /** 总调用计数（soft limit 用，从 ConcurrencyGate.totalCallCount 迁入）。 */
+  totalCallCount = 0;
+
+  constructor(opts: {
+    maxTokens?: number;
+    maxCost?: number;
+    maxTimeMs?: number;
+    usedTokens?: number;
+    usedCost?: number;
+    totalCallCount?: number;
+  } = {}) {
+    this.maxTokens = opts.maxTokens;
+    this.maxCost = opts.maxCost;
+    this.maxTimeMs = opts.maxTimeMs;
+    this.usedTokens = opts.usedTokens ?? 0;
+    this.usedCost = opts.usedCost ?? 0;
+    this.totalCallCount = opts.totalCallCount ?? 0;
+  }
+
+ /**
+ * 累加一次 agent 调用的 usage（加权口径）。
+ *
+ * 四项 token 按各自权重（INPUT/CACHE_READ/CACHE_WRITE/OUTPUT_WEIGHT）折算后求和，
+ * 而非原始 token 数直接相加。retry 间的真实消耗如实记录，避免预算被低估。
+ * 详见上方权重常量的口径说明。
+ */
+  consume(usage: AgentUsage): void {
+    // NaN 守卫——非有限值当 0 处理，防 usedTokens 变 NaN 导致 isExceeded() 永远 false（预算限制失效）
+    const numOrZero = (v: number | undefined): number =>
+      typeof v === "number" && Number.isFinite(v) ? v : 0;
+    this.usedTokens +=
+      numOrZero(usage.input) * INPUT_WEIGHT +
+      numOrZero(usage.output) * OUTPUT_WEIGHT +
+      numOrZero(usage.cacheRead) * CACHE_READ_WEIGHT +
+      numOrZero(usage.cacheWrite) * CACHE_WRITE_WEIGHT;
+    this.usedCost += numOrZero(usage.cost);
+  }
+
+ /** 累加调用计数（每次 agent dispatch 后调用）。 */
+  incrementCallCount(): void {
+    this.totalCallCount += 1;
+  }
+
+ /**
+ * 是否超 token / cost 预算（FR-3）。
+ *
+ * maxTokens===0 或 undefined 视为不限制（守卫）；
+ * maxCost===0 或 undefined 视为不限制。
+ * 时间预算（maxTimeMs）不由本方法判断——它是 wall-clock 约束，需参照 startedAt，
+ * 由 lifecycle 层的 scheduleTimeBudget（runWorkflow/resumeRun 内 setTimeout）
+ * 独立调度，到期 abortRun(doneReason="time_limited")。
+ */
+  isExceeded(): boolean {
+    if (this.maxTokens !== undefined && this.maxTokens > 0 && this.usedTokens >= this.maxTokens) {
+      return true;
+    }
+    return this.maxCost !== undefined && this.maxCost > 0 && this.usedCost >= this.maxCost;
+  }
+
+ /**
+ * 是否达到 soft limit（FR-7）。
+ *
+ * totalCallCount > SOFT_MAX_AGENTS_WARNING（500）。
+ * 调用方（lifecycle）在 consume/incrementCallCount 后查询，
+ * 命中时发通知（无状态——可重复查询）。
+ */
+  isSoftLimitReached(): boolean {
+    return this.totalCallCount > SOFT_MAX_AGENTS_WARNING;
+  }
+
+ /**
+ * 剩余 token 预算。maxTokens 未设或 ≤0 时返回 undefined（视为不限制）。
+ *
+ * 嵌套 workflow() 调用时由 executeNestedWorkflow 消费：子 run 的 budgetTokens
+ * 继承父 run 的剩余预算，实现父子预算隔离下的总量约束。
+ */
+  remaining(): number | undefined {
+    if (this.maxTokens === undefined || this.maxTokens <= 0) return undefined;
+    return Math.max(0, this.maxTokens - this.usedTokens);
+  }
+
+ /**
+ * 是否达到 token 预算的给定比例阈值（如 0.9 = 90% 预警）。
+ *
+ * 纯查询，无状态——调用方负责去重（旧 _budgetWarningSent 语义由 lifecycle 层用
+ * 外部 Set 或 once-listener 实现）。maxTokens 未设或为 0 时返回 false。
+ */
+  isThresholdReached(ratio: number): boolean {
+    return (
+      this.maxTokens !== undefined &&
+      this.maxTokens > 0 &&
+      this.usedTokens >= this.maxTokens * ratio
+    );
+  }
+}