@twinsearth/dsh-master 3.2.10 → 3.3.0

package/README.md

@@ -84,12 +84,15 @@ dsh plugin add <package>  # 加载 dist-host/dist-worker
 - [Worker Agent Loop](docs/WORKER-AGENT-LOOP.md)
 - [SuperAgent v3.2.1 设计与契约](docs/SUPERAGENT.md)
 - [架构设计](docs/ARCHITECTURE.md)
+- [3.3.0 成本优化架构（总体架构 / 实施进度）](docs/DESIGN-v3.3.0-cost-optimization.md)
+- [第三方参考实现与移植边界](docs/THIRD-PARTY.md)
 - [路线图（3.2.0–3.4.0）](docs/ROADMAP.md)
 - [安全边界](docs/SECURITY.md)
 - [变更记录](docs/CHANGELOG.md)
 
 ## 状态
 
+- 3.3.0 M1+M2（dev，未发布）：成本优化系统层（ledger / budget / policy / audit）+ Worker 四个成本切点（observe-only）+ A1 工具输出紧凑化（默认 shadow，enforce 需白名单）；A2–A3 与决策复用 B1–B4 在 M3–M4 接入，详见 [3.3.0 架构设计](docs/DESIGN-v3.3.0-cost-optimization.md)。
 - 3.2.10 发布线：角色矩阵放宽——Router 进入母体（essence/mother），Worker 与 Worker Agent Loop 进入原身（fork/essence）；母体仍不接纳执行体，fork 仍不注册 Router。
 - 3.2.9 发布线：房主面板改注册到 `shell.overlay` 常驻浮层——点击面板之外不收起、侧栏「房主」按钮二次点击收起、正文独立滚动；新增无浏览器 hook 运行时行为测试（开关、无 outside-click 监听、滚动容器、SSE 失败不卸载面板）。
 - 3.2.8 发布线：与瓮城通过 fang-master contract 1.0 互联（local/http/file/legacy 四级保底）；GitHub Release + NPM public。

package/client.js

@@ -241,6 +241,55 @@ window.__ModuleLoader__.load({
       )
     }
 
+    /**
+     * §11：成本（只读）块。
+     *
+     * 只消费 `/dsh-master/api/superagent/cost` 的 `service` 段，**不写任何业务状态**、
+     * 不触发任何成本动作；A（单价项）与 B（跳过调用项）分列展示，绝不合并成一个数字。
+     */
+    function CostCard() {
+      const [cost, setCost] = React.useState(null)
+      const [failed, setFailed] = React.useState(false)
+
+      React.useEffect(() => {
+        let alive = true
+        const load = async () => {
+          try {
+            const response = await fetch('/dsh-master/api/superagent/cost', { headers: { accept: 'application/json' } })
+            const body = await response.json().catch(() => null)
+            if (!alive) return
+            setCost(response.ok && body ? body : null)
+            setFailed(!response.ok)
+          } catch { if (alive) setFailed(true) }
+        }
+        void load()
+        const timer = setInterval(load, 5000)
+        return () => { alive = false; clearInterval(timer) }
+      }, [])
+
+      const block = cost && cost.service ? cost.service : null
+      const columns = block && block.columns ? block.columns : null
+      const savings = block && block.savings ? block.savings : null
+      const fmt = (value) => (value === null || value === undefined ? '—' : Number(value).toLocaleString())
+
+      return h('div', { style: S.card, 'data-dsh-master': 'cost-block' },
+        h('div', { style: S.row },
+          h('span', { style: S.name }, '成本（只读）'),
+          tag(block ? '3.3.0' : '未启用', block ? undefined : '#B45309')),
+        failed ? h('div', { style: S.error }, '成本接口不可达') : null,
+        !block && !failed ? h('div', { style: S.desc }, '成本系统未装配（cost-optimizer 未启用或角色不匹配）') : null,
+        columns ? h('div', { style: S.desc },
+          '单价项 A：' + fmt(columns.unitPriceSaved) + ' · ',
+          '跳过调用 B：' + fmt(columns.skippedCallSaved) + '（' + fmt(columns.skippedCalls) + ' 次）') : null,
+        columns ? h('div', { style: S.desc },
+          'governance：' + fmt(columns.governanceTotal) + ' · 净节省：' + fmt(columns.netSaved)) : null,
+        columns && columns.netLossTasks && columns.netLossTasks.length > 0
+          ? h('div', { style: S.off }, '净亏任务：' + columns.netLossTasks.slice(0, 3).join(', '))
+          : null,
+        savings ? h('div', { style: S.desc }, '命中率：' + (block.hitRate === undefined || block.hitRate === null ? '—' : (Number(block.hitRate) * 100).toFixed(1) + '%')) : null,
+      )
+    }
+
     function MasterPanel() {
       const [status, setStatus] = React.useState(null)
       const [error, setError] = React.useState('')
@@ -283,6 +332,7 @@ window.__ModuleLoader__.load({
             h('div', { style: S.desc }, '运行：' + Math.max(1, Math.round((status.uptimeMs || 0) / 60000)) + ' 分钟'),
           ) : null,
           ...items.map((item) => h(SubpluginCard, { key: item.id, item })),
+          h(CostCard),
           h(FangCard, { cooperation: status && status.cooperation }),
           h(LiveFeed),
           h('div', { style: S.desc }, '3.2.10：角色矩阵放宽（Router→essence/mother，Worker/Loop→fork/essence）；面板常驻、按钮二次点击收起、正文可滚动；实时流（SSE）+ token 轮换/审计。'),

package/dist-host/cost/attribution.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 3.3.0 系统层 · attribution（归因，设计 §5.4）。
+ *
+ * 三条硬规则：
+ *   1. **每条 savedTokens 必须带 moduleId**（缺失 ⇒ `module-missing`，不猜、不默认）；
+ *   2. 差额进 `unattributed`，报表**单列**——未归因收益不得算作任何模块收益；
+ *   3. 归因算法（工具面）：`baselineOutputTokens(toolName, 长度) − actualOutputTokens`，
+ *      baseline 由 A1 固定拟合式给出（`worker/baseline-fit.ts`，参数在 docs §5.4.1 冻结）。
+ *
+ * 另守 §5.3 口径：`shadow` 只累计「本可节省」，`enforce` 才写入 execution 账本且
+ * `totalTokens=0`（不重复计入已消耗 token）。
+ */
+import { COST_MODULES } from "./types.js";
+function finiteNonNegative(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+/**
+ * @param {{ledger: {append: Function}, now?: () => number}} options
+ */
+export function createAttribution(options = {}) {
+    const ledger = options.ledger;
+    if (!ledger || typeof ledger.append !== 'function')
+        throw new Error('attribution requires a ledger');
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const allowed = new Set(COST_MODULES);
+    const modules = new Map();
+    const tasks = new Map();
+    const moduleRow = (module) => {
+        if (!modules.has(module))
+            modules.set(module, { module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 });
+        return modules.get(module);
+    };
+    const taskRow = (taskId, module) => {
+        const key = `${taskId ?? ''}|${module}`;
+        if (!tasks.has(key))
+            tasks.set(key, { key, taskId: taskId === undefined ? null : String(taskId), module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 });
+        return tasks.get(key);
+    };
+    /**
+     * @param {{taskId?: string, module: string, savedTokens: number, mode?: string, meta?: object,
+     *          forkId?: string, sessionId?: string}} input
+     */
+    function attribute(input = {}) {
+        const saved = finiteNonNegative(input.savedTokens);
+        if (saved === null)
+            return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' };
+        // §5.4-1：moduleId 必填，缺失不猜默认值。
+        if (input.module === undefined || input.module === null || String(input.module).trim() === '') {
+            return { ok: false, code: 'module-missing', message: 'every savedTokens must carry a moduleId' };
+        }
+        const module = String(input.module);
+        if (!allowed.has(module))
+            return { ok: false, code: 'module-invalid', message: `module must be one of ${COST_MODULES.join('/')}` };
+        const enforce = String(input.mode ?? 'shadow') === 'enforce';
+        const row = moduleRow(module);
+        const perTask = taskRow(input.taskId, module);
+        if (!enforce) {
+            row.events += 1;
+            row.projectedTokens += saved;
+            perTask.events += 1;
+            perTask.projectedTokens += saved;
+            return {
+                ok: true,
+                mode: 'shadow',
+                module,
+                projectedTokens: saved,
+                shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+                at: now(),
+            };
+        }
+        const appended = ledger.append({
+            account: 'execution',
+            module,
+            source: 'tool',
+            phase: 'tool',
+            taskId: input.taskId === undefined ? null : String(input.taskId),
+            forkId: input.forkId,
+            sessionId: input.sessionId,
+            step: input.step,
+            turn: input.turn,
+            totalTokens: 0,
+            savedTokens: saved,
+            meta: { kind: 'attribution', ...(input.meta && typeof input.meta === 'object' ? input.meta : {}), mode: 'enforce' },
+        });
+        if (!appended.ok)
+            return { ok: false, code: appended.code, message: appended.message };
+        row.events += 1;
+        row.enforceSavedTokens += saved;
+        perTask.events += 1;
+        perTask.enforceSavedTokens += saved;
+        return {
+            ok: true,
+            mode: 'enforce',
+            module,
+            savedTokens: saved,
+            ledger: { id: appended.entry.id },
+            shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+            at: now(),
+        };
+    }
+    /**
+     * §5.4-2：按「总额 − 各模块之和」结算，差额自动进 `unattributed`。
+     * 任何未提供 moduleId 的条目都会被拒绝（模块收益不得凭空出现）。
+     *
+     * @param {{taskId?: string, totalSavedTokens: number, items?: Array<{module: string, savedTokens: number}>,
+     *          mode?: string, forkId?: string, sessionId?: string}} input
+     */
+    function attributeTotal(input = {}) {
+        const total = finiteNonNegative(input.totalSavedTokens);
+        if (total === null)
+            return { ok: false, code: 'saved-tokens-invalid', message: 'totalSavedTokens must be a non-negative number' };
+        const items = Array.isArray(input.items) ? input.items : [];
+        let attributed = 0;
+        const applied = [];
+        for (const item of items) {
+            const out = attribute({
+                taskId: input.taskId,
+                module: item?.module,
+                savedTokens: item?.savedTokens,
+                mode: input.mode,
+                forkId: input.forkId,
+                sessionId: input.sessionId,
+                meta: { kind: 'module-share' },
+            });
+            if (!out.ok)
+                return out;
+            attributed += finiteNonNegative(item?.savedTokens) ?? 0;
+            applied.push({ module: String(item.module), savedTokens: finiteNonNegative(item?.savedTokens) ?? 0 });
+        }
+        if (attributed > total) {
+            return { ok: false, code: 'attribution-overflow', message: `attributed ${attributed} exceeds total ${total}` };
+        }
+        const residual = total - attributed;
+        if (residual > 0) {
+            const out = attribute({
+                taskId: input.taskId,
+                module: 'unattributed',
+                savedTokens: residual,
+                mode: input.mode,
+                forkId: input.forkId,
+                sessionId: input.sessionId,
+                meta: { kind: 'residual' },
+            });
+            if (!out.ok)
+                return out;
+        }
+        return { ok: true, totalSavedTokens: total, attributedTokens: attributed, unattributedTokens: residual, items: applied, at: now() };
+    }
+    function snapshot() {
+        const moduleRows = [...modules.values()]
+            .map((item) => Object.freeze({ ...item }))
+            .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens));
+        const taskRows = [...tasks.values()]
+            .map((item) => Object.freeze({ ...item }))
+            .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens));
+        const named = moduleRows.filter((row) => row.module !== 'unattributed');
+        const unattributed = moduleRows.filter((row) => row.module === 'unattributed');
+        const sum = (rows, key) => rows.reduce((total, row) => total + row[key], 0);
+        return Object.freeze({
+            ok: true,
+            modules: moduleRows,
+            tasks: taskRows,
+            /** 模块收益（不含 unattributed）——报表只能把这一项当「模块业绩」。 */
+            attributedSavedTotal: sum(named, 'enforceSavedTokens'),
+            attributedProjectedTotal: sum(named, 'projectedTokens'),
+            /** 未归因收益：单列，永不并入上面的模块业绩。 */
+            unattributedSavedTotal: sum(unattributed, 'enforceSavedTokens'),
+            unattributedProjectedTotal: sum(unattributed, 'projectedTokens'),
+            projectedTotal: sum(moduleRows, 'projectedTokens'),
+            enforceSavedTotal: sum(moduleRows, 'enforceSavedTokens'),
+        });
+    }
+    function reset() {
+        modules.clear();
+        tasks.clear();
+        return { ok: true };
+    }
+    return Object.freeze({ attribute, attributeTotal, snapshot, reset });
+}

package/dist-host/cost/audit.js

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 3.3.0 系统层 · audit（哈希链审计，设计 §5.5）。
+ *
+ * 结构约束：
+ *   * **只追加**：没有 update/delete/rewrite API，记录 `Object.freeze`；
+ *   * 每条记录含 `prevHash` 与自身 `hash`，任何篡改或截断都会在 `verify()` 断链；
+ *   * 每次替换写一条 `SubstitutionCert`（edgeId / toolName / schemaHash / guardExpr /
+ *     receiptDigest / replacedCallbackId / viaNativeDispatcher: true），
+ *     并与 ledger 事件用同一 `taskId + step` 关联 —— 报表可回放「这一省是怎么来的」。
+ */
+import crypto from 'node:crypto';
+/** SubstitutionCert 必填字段；缺任何一项都不得落链（否则证书无法复核）。 */
+const CERT_REQUIRED = Object.freeze([
+    'edgeId',
+    'toolName',
+    'schemaHash',
+    'guardExpr',
+    'receiptDigest',
+    'replacedCallbackId',
+    'taskId',
+]);
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : 'null';
+    if (value === undefined)
+        return 'null';
+    return JSON.stringify(value) ?? 'null';
+}
+function hashOf(seq, at, type, actor, payload, prevHash) {
+    const body = canonical([seq, at, type, actor, payload, prevHash]);
+    return `sha256:${crypto.createHash('sha256').update(body).digest('hex')}`;
+}
+/**
+ * @param {{now?: () => number, maxRecords?: number}} [options]
+ */
+export function createAuditChain(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const maxRecords = Math.max(1, Number(options.maxRecords ?? 2000) || 2000);
+    const records = [];
+    let seq = 0;
+    let dropped = 0;
+    function append({ type, actor = 'cost-system', payload = {} } = {}) {
+        seq += 1;
+        const at = now();
+        const prevHash = records.length > 0 ? records[records.length - 1].hash : '';
+        const record = Object.freeze({
+            seq,
+            at,
+            type: String(type ?? 'unknown'),
+            actor: String(actor ?? 'cost-system'),
+            payload: Object.freeze({ ...payload }),
+            prevHash,
+            hash: hashOf(seq, at, String(type ?? 'unknown'), String(actor ?? 'cost-system'), payload, prevHash),
+        });
+        records.push(record);
+        if (records.length > maxRecords) {
+            records.shift();
+            dropped += 1;
+        }
+        return record;
+    }
+    /**
+     * 写一条 SubstitutionCert（§5.5）。fail-closed：
+     *   * 必填字段缺失/空白 ⇒ 拒绝；
+     *   * `viaNativeDispatcher` 必须严格为 `true`（非原生派发不得替换）；
+     *   * `taskId + step` 是回放键，step 必须是非负整数。
+     */
+    function appendSubstitution(cert = {}) {
+        const missing = CERT_REQUIRED.filter((key) => {
+            const value = cert?.[key];
+            return value === undefined || value === null || String(value).trim() === '';
+        });
+        if (missing.length > 0) {
+            return { ok: false, code: 'cert-invalid', message: `substitution cert missing ${missing.join(',')}`, missing };
+        }
+        if (cert.viaNativeDispatcher !== true) {
+            return { ok: false, code: 'cert-not-native', message: 'substitution must be executed via the native dispatcher' };
+        }
+        const step = Number(cert.step);
+        if (!Number.isInteger(step) || step < 0) {
+            return { ok: false, code: 'cert-step-invalid', message: 'step must be a non-negative integer' };
+        }
+        const savedTokens = Number(cert.savedTokens ?? 0);
+        if (!Number.isFinite(savedTokens) || savedTokens < 0) {
+            return { ok: false, code: 'cert-saved-invalid', message: 'savedTokens must be a non-negative number' };
+        }
+        const payload = Object.freeze({
+            kind: 'substitution-cert',
+            edgeId: String(cert.edgeId),
+            toolName: String(cert.toolName),
+            schemaHash: String(cert.schemaHash),
+            guardExpr: String(cert.guardExpr),
+            receiptDigest: String(cert.receiptDigest),
+            replacedCallbackId: String(cert.replacedCallbackId),
+            /** M4：落链即代表「已经过原生派发器真的派发」；证书链核对直接读这一位。 */
+            dispatched: true,
+            viaNativeDispatcher: true,
+            taskId: String(cert.taskId),
+            step,
+            forkId: cert.forkId === undefined ? null : String(cert.forkId),
+            sessionId: cert.sessionId === undefined ? null : String(cert.sessionId),
+            ticketId: cert.ticketId === undefined ? null : String(cert.ticketId),
+            moduleId: cert.moduleId === undefined ? null : String(cert.moduleId),
+            savedTokens,
+        });
+        const record = append({ type: 'cost.substitution', actor: 'cost-ccs', payload });
+        return { ok: true, cert: payload, record };
+    }
+    function verify(source) {
+        const list = Array.isArray(source) ? source : records;
+        let prevHash = '';
+        let expectedSeq = 1;
+        for (const record of list) {
+            if (record.seq !== expectedSeq)
+                return { ok: false, count: list.length, brokenAt: record.seq, reason: 'seq-gap' };
+            if (record.prevHash !== prevHash)
+                return { ok: false, count: list.length, brokenAt: record.seq, reason: 'prev-hash-mismatch' };
+            const expected = hashOf(record.seq, record.at, record.type, record.actor, record.payload, record.prevHash);
+            if (record.hash !== expected)
+                return { ok: false, count: list.length, brokenAt: record.seq, reason: 'hash-mismatch' };
+            prevHash = record.hash;
+            expectedSeq += 1;
+        }
+        return { ok: true, count: list.length, brokenAt: null, reason: null };
+    }
+    function snapshot(limit = 50) {
+        const n = Math.max(1, Number(limit) || 50);
+        return Object.freeze({
+            ok: true,
+            count: records.length,
+            dropped,
+            verified: verify(),
+            records: records.slice(-n),
+        });
+    }
+    function reset() {
+        records.length = 0;
+        seq = 0;
+        dropped = 0;
+        return { ok: true };
+    }
+    /** 取某任务/步骤的证书（回放用；不改链）。 */
+    function substitutions(filter = {}) {
+        const taskId = filter.taskId === undefined ? null : String(filter.taskId);
+        const step = filter.step === undefined ? null : Number(filter.step);
+        const rows = records
+            .filter((record) => record.type === 'cost.substitution')
+            .filter((record) => (taskId === null ? true : record.payload.taskId === taskId))
+            .filter((record) => (step === null ? true : record.payload.step === step));
+        return Object.freeze(rows.map((record) => Object.freeze({ ...record.payload, seq: record.seq, at: record.at, hash: record.hash })));
+    }
+    // 只追加：对外**不暴露**任何修改/删除入口（records() 返回副本）。
+    return Object.freeze({ append, appendSubstitution, verify, snapshot, reset, records: () => records.slice(), substitutions });
+}

package/dist-host/cost/budget.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 3.3.0 系统层 · budget（预算闸，设计 §5.2）。
+ *
+ * 规格要点：
+ *   * 规则：`unit(task|fork|day) + limitTokens? + limitCost? + onExhaust(hard-stop|degrade)`；
+ *   * **检查点只在 ① beforeModelCall**（`authorize()` 即该检查点，其它地方不得自行扣减）；
+ *   * 超限返回 `masterError('budget-exhausted', …)` 形状 + 结构化 `remaining`；
+ *   * **fail-closed**：额度不足不得「先跑着看」——拒绝时**不扣额度**、不放行；
+ *   * `degrade` 档只允许降级到**已在白名单**的廉价模型，绝不引入新 provider。
+ *
+ * 成本维度（`limitCost`）需要调用方给出本次预估成本（`cost` 字段）；
+ * 未提供成本时成本维度不可判定，会显式标 `costTracked: false`，而不是假装达标。
+ */
+import { DEFAULT_BUDGET_LIMITS } from "./types.js";
+const UNITS = ['task', 'fork', 'day'];
+const EXHAUST_ACTIONS = ['hard-stop', 'degrade'];
+/** 与 kernel.masterError 同形状（host 侧不反向依赖 kernel，避免子系统耦合）。 */
+function masterError(code, message, detail) {
+    const out = { ok: false, code: String(code), error: String(message ?? code) };
+    if (detail !== undefined)
+        out.detail = detail;
+    return out;
+}
+function positiveLimit(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+function keyOf(unit, key) {
+    return `${unit}:${String(key ?? 'default')}`;
+}
+/**
+ * @param {{
+ *   limits?: Array<{unit:string, limitTokens?:number, limitCost?:number, onExhaust?:string, degradeTo?:string}>,
+ *   degradeModels?: string[],   // degrade 允许的廉价模型白名单（不在此列表 ⇒ 一律 hard-stop）
+ *   now?: () => number,
+ * }} [options]
+ */
+export function createBudget(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const source = Array.isArray(options.limits) && options.limits.length > 0 ? options.limits : DEFAULT_BUDGET_LIMITS;
+    const degradeModels = Object.freeze((Array.isArray(options.degradeModels) ? options.degradeModels : [])
+        .map((item) => String(item ?? '').trim())
+        .filter(Boolean));
+    const limits = [];
+    const invalid = [];
+    for (const item of source) {
+        const unit = String(item?.unit ?? '');
+        const limitTokens = item?.limitTokens === undefined ? null : positiveLimit(item.limitTokens);
+        const limitCost = item?.limitCost === undefined ? null : positiveLimit(item.limitCost);
+        if (!UNITS.includes(unit) || (limitTokens === null && limitCost === null)) {
+            // 既无 token 上限也无成本上限的规则没有意义：配置错误必须显式暴露（fail-closed）。
+            invalid.push({ unit, limitTokens: item?.limitTokens, limitCost: item?.limitCost });
+            continue;
+        }
+        if (limits.some((rule) => rule.unit === unit)) {
+            // 同一 unit 只能有一条规则（先注册先得），否则判定口径不确定。
+            invalid.push({ unit, reason: 'duplicate-unit' });
+            continue;
+        }
+        const onExhaust = EXHAUST_ACTIONS.includes(String(item?.onExhaust)) ? String(item.onExhaust) : 'hard-stop';
+        const degradeTo = item?.degradeTo === undefined ? null : String(item.degradeTo);
+        // degrade 档必须在白名单内，否则等于开了个后门：降级为 hard-stop。
+        const effective = onExhaust === 'degrade' && degradeTo !== null && degradeModels.includes(degradeTo)
+            ? 'degrade'
+            : 'hard-stop';
+        if (onExhaust === 'degrade' && effective !== 'degrade') {
+            invalid.push({ unit, degradeTo, reason: 'degrade-model-not-allowlisted' });
+        }
+        limits.push(Object.freeze({
+            unit,
+            limitTokens,
+            limitCost,
+            onExhaust: effective,
+            degradeTo: effective === 'degrade' ? degradeTo : null,
+        }));
+    }
+    const limitOf = (unit) => limits.find((item) => item.unit === unit) ?? null;
+    const consumed = new Map();
+    const used = (unit, key) => consumed.get(keyOf(unit, key)) ?? { tokens: 0, cost: 0 };
+    /**
+     * ① beforeModelCall 的唯一检查点。
+     * @param {{unit: string, key?: string, tokens?: number, cost?: number}} input
+     */
+    function authorize(input = {}) {
+        const unit = String(input.unit);
+        const key = String(input.key ?? 'default');
+        const requested = Number(input.tokens ?? 0);
+        const requestedCost = Number(input.cost ?? 0);
+        if (!Number.isFinite(requested) || requested < 0) {
+            return masterError('tokens-invalid', 'tokens must be a non-negative number');
+        }
+        if (!Number.isFinite(requestedCost) || requestedCost < 0) {
+            return masterError('cost-invalid', 'cost must be a non-negative number');
+        }
+        const limit = limitOf(unit);
+        if (!limit) {
+            return { ok: true, unlimited: true, unit, key, requested, remaining: null, costTracked: false, at: now() };
+        }
+        const current = used(unit, key);
+        const remainingTokens = limit.limitTokens === null ? null : Math.max(0, limit.limitTokens - current.tokens);
+        const remainingCost = limit.limitCost === null ? null : Math.max(0, limit.limitCost - current.cost);
+        const tokenExhausted = limit.limitTokens !== null && requested > remainingTokens;
+        const costExhausted = limit.limitCost !== null && requestedCost > remainingCost;
+        const costTracked = limit.limitCost === null ? false : Number(input.cost) > 0;
+        if (tokenExhausted || costExhausted) {
+            const reason = tokenExhausted ? 'tokens' : 'cost';
+            // degrade 档：只降级到白名单里的廉价模型；否则一律 fail-closed。
+            if (limit.onExhaust === 'degrade' && limit.degradeTo && degradeModels.includes(limit.degradeTo)) {
+                return {
+                    ok: true,
+                    degraded: true,
+                    action: 'degrade',
+                    unit,
+                    key,
+                    model: limit.degradeTo,
+                    reason,
+                    limitTokens: limit.limitTokens,
+                    limitCost: limit.limitCost,
+                    consumedTokens: current.tokens,
+                    consumedCost: current.cost,
+                    remainingTokens,
+                    remainingCost,
+                    requested,
+                    requestedCost,
+                    costTracked,
+                    onExhaust: 'degrade',
+                    at: now(),
+                };
+            }
+            // fail-closed：拒绝且**不扣额度**，绝不「先跑着看」。
+            return masterError('budget-exhausted', `预算不足：${unit}/${key} 剩余 ${remainingTokens ?? '∞'} token`, {
+                unit,
+                key,
+                reason,
+                limitTokens: limit.limitTokens,
+                limitCost: limit.limitCost,
+                consumedTokens: current.tokens,
+                consumedCost: current.cost,
+                remainingTokens,
+                remainingCost,
+                requested,
+                requestedCost,
+                costTracked,
+                onExhaust: limit.onExhaust,
+                /** 剩余信息同时平铺在顶层，便于调用方不需解 detail。 */
+                remaining: { tokens: remainingTokens, cost: remainingCost },
+                at: now(),
+            });
+        }
+        const nextTokens = current.tokens + Math.floor(requested);
+        const nextCost = current.cost + requestedCost;
+        consumed.set(keyOf(unit, key), { tokens: nextTokens, cost: nextCost });
+        return {
+            ok: true,
+            unit,
+            key,
+            requested,
+            requestedCost,
+            consumedTokens: nextTokens,
+            consumedCost: nextCost,
+            limitTokens: limit.limitTokens,
+            limitCost: limit.limitCost,
+            remainingTokens: limit.limitTokens === null ? null : limit.limitTokens - nextTokens,
+            remainingCost: limit.limitCost === null ? null : limit.limitCost - nextCost,
+            costTracked,
+            at: now(),
+        };
+    }
+    function refund({ unit, key = 'default', tokens = 0, cost = 0 } = {}) {
+        const n = Number(tokens);
+        const c = Number(cost);
+        if (!Number.isFinite(n) || n < 0 || !Number.isFinite(c) || c < 0 || (n === 0 && c === 0)) {
+            return masterError('refund-invalid', 'refund requires positive tokens and/or cost');
+        }
+        const k = keyOf(String(unit), key);
+        const current = consumed.get(k) ?? { tokens: 0, cost: 0 };
+        const next = { tokens: Math.max(0, current.tokens - Math.floor(n)), cost: Math.max(0, current.cost - c) };
+        consumed.set(k, next);
+        return { ok: true, unit: String(unit), key: String(key), consumedTokens: next.tokens, consumedCost: next.cost, at: now() };
+    }
+    function state() {
+        const rows = [];
+        for (const limit of limits) {
+            for (const [k, value] of consumed.entries()) {
+                const prefix = `${limit.unit}:`;
+                if (!k.startsWith(prefix))
+                    continue;
+                rows.push(Object.freeze({
+                    unit: limit.unit,
+                    key: k.slice(prefix.length),
+                    consumedTokens: value.tokens,
+                    consumedCost: value.cost,
+                    limitTokens: limit.limitTokens,
+                    limitCost: limit.limitCost,
+                    remainingTokens: limit.limitTokens === null ? null : Math.max(0, limit.limitTokens - value.tokens),
+                    remainingCost: limit.limitCost === null ? null : Math.max(0, limit.limitCost - value.cost),
+                    onExhaust: limit.onExhaust,
+                }));
+            }
+        }
+        return Object.freeze({ ok: true, limits, invalid, degradeModels: degradeModels.slice(), rows, at: now() });
+    }
+    function reset() {
+        consumed.clear();
+        return { ok: true };
+    }
+    return Object.freeze({ authorize, refund, state, reset, limits: () => limits.slice(), degradeModels: () => degradeModels.slice() });
+}