@jack200714/mafw 4.8.0 → 4.10.2

package/gateway/dist/runtime/normalize.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMalformedEvent = isMalformedEvent;
 exports.normalizeOpencodeEvent = normalizeOpencodeEvent;
 /**
  * 事件归一化器 —— 把 runtime 原生事件翻译成 EventFacets（正交切面）。
@@ -13,6 +14,18 @@ exports.normalizeOpencodeEvent = normalizeOpencodeEvent;
  * 与现 handleOpencodeEvent 的多路消费行为逐点等价。
  */
 const step_inject_1 = require("../recall/step-inject");
+/**
+ * 畸形事件判定：类型与属性全空 = 归一化后无任何可消费信息。
+ * handleOpencodeEvent 入口据此做限频 warn——runtime 插件发坏事件时
+ * 给出可定位诊断，而不是静默穿过下发到桌面/TUI。
+ */
+function isMalformedEvent(evt) {
+    if (!evt || typeof evt !== 'object')
+        return true;
+    const type = evt.payload?.type || evt.type;
+    const props = evt.payload?.properties || evt.properties;
+    return !type && (!props || (typeof props === 'object' && Object.keys(props).length === 0));
+}
 function normalizeOpencodeEvent(evt) {
     const payload = evt?.payload || {};
     const type = payload?.type || evt?.type || '';

package/gateway/dist/runtime/opencode-runtime.js

@@ -259,7 +259,9 @@ async function createOpencodeRuntime(config) {
             },
         },
         getBaseUrl() {
-            return process.env.MAFW_SERVER_SERVE_URL || config_1.config.server.serveUrl;
+            // 地址归 runtime 所有：bootstrap 取配置，spawnServe 吸收 sidecar 实际
+            // URL 后（含动态端口），gateway 一律经此读取，不直连配置。
+            return process.env.MAFW_SERVER_SERVE_URL || config.baseUrl;
         },
         async healthCheck() {
             try {
@@ -325,7 +327,21 @@ async function createOpencodeRuntime(config) {
     // Gateway core never hardcodes agent-specific spawn details.
     if (!rt.external) {
         rt.agentProcess = {
-            spawnServe: (opts) => (0, serve_sidecar_1.startServeSidecar)(opts),
+            spawnServe: async (opts) => {
+                // host/port 缺省由 runtime 自定（serve 端口是实现细节，gateway 不传）
+                const sidecar = await (0, serve_sidecar_1.startServeSidecar)({
+                    host: opts.host ?? config_1.config.server.serveHost ?? '127.0.0.1',
+                    port: opts.port ?? config_1.config.server.servePort,
+                    timeoutMs: opts.timeoutMs,
+                    onOutput: opts.onOutput,
+                    onExit: opts.onExit,
+                });
+                // 吸收 sidecar 报告的实际地址（可能与请求端口不同，如动态分配）：
+                // 之后 getBaseUrl/healthCheck/adapter 请求全部跟随实际 URL。
+                config.baseUrl = sidecar.url;
+                return sidecar;
+            },
+            killServe: () => (0, serve_sidecar_1.killServePort)(config_1.config.server.servePort),
             async restart() {
                 logger_1.log.info('[Runtime] agentProcess.restart() — killing serve (gateway orchestrates respawn)');
                 (0, serve_sidecar_1.killServePort)(config_1.config.server.servePort);

package/gateway/dist/runtime/pi/pi-approval-bridge.js

@@ -8,15 +8,25 @@ class ApprovalBridge {
     constructor(timeoutMs = 300_000) {
         this.timeoutMs = timeoutMs;
     }
-    request(requestId) {
+    request(requestId, meta) {
         return new Promise((resolve) => {
             const timeout = setTimeout(() => {
                 this.pending.delete(requestId);
                 resolve(false);
             }, this.timeoutMs);
-            this.pending.set(requestId, { resolve, timeout });
+            this.pending.set(requestId, { resolve, timeout, meta });
         });
     }
+    /** 待审批请求列表（gateway session.permissionList 契约的 pi 实现）。 */
+    listPending() {
+        return [...this.pending.entries()].map(([id, req]) => ({
+            id,
+            sessionID: req.meta?.sessionID,
+            permission: req.meta?.permission,
+            patterns: req.meta?.patterns,
+            metadata: req.meta?.metadata,
+        }));
+    }
     /** 三值回复；兼容旧 boolean 调用（true→once / false→reject）。 */
     reply(requestId, decision, message) {
         const req = this.pending.get(requestId);

package/gateway/dist/runtime/pi/pi-approval-extension.js

@@ -6,7 +6,7 @@ const DEFAULT_POLICY = {
     autoApprove: ['read', 'grep', 'ls', 'find', 'glob'],
     autoDeny: [],
 };
-function createMafwApprovalExtension(bridge, emitEvent, policy = DEFAULT_POLICY) {
+function createMafwApprovalExtension(bridge, emitEvent, policy = DEFAULT_POLICY, gatewaySessionId) {
     return {
         name: 'mafw-approval',
         on: (emitter) => {
@@ -19,7 +19,9 @@ function createMafwApprovalExtension(bridge, emitEvent, policy = DEFAULT_POLICY)
                     return { block: true, reason: 'auto-denied by policy' };
                 }
                 const requestId = (0, crypto_1.randomUUID)();
-                const sessionID = ctx.sessionId;
+                // pi 原生 ctx.sessionId 与 gateway 生成的 pi_* 注册 id 不同——事件
+                // 必须携带 gateway id，否则 permissionReply 按 id 查 bridge 404。
+                const sessionID = gatewaySessionId;
                 emitEvent({
                     payload: {
                         type: 'permission.asked',
@@ -32,7 +34,13 @@ function createMafwApprovalExtension(bridge, emitEvent, policy = DEFAULT_POLICY)
                         },
                     },
                 });
-                const approved = await bridge.request(requestId);
+                // permissionList 元数据：PendingMeta 与 permission.asked 事件同源
+                const approved = await bridge.request(requestId, {
+                    sessionID,
+                    permission: toolName,
+                    patterns: [],
+                    metadata: { args: event.input, risk: 'medium' },
+                });
                 const record = bridge.lastDecision(requestId);
                 const decision = record?.decision ?? (approved ? 'once' : 'reject');
                 const message = record?.message;

package/gateway/dist/runtime/pi/pi-session.js

@@ -25,7 +25,12 @@ class PiSessionRegistry {
         const id = `pi_${(0, crypto_1.randomUUID)().slice(0, 8)}`;
         const bridge = new pi_approval_bridge_1.ApprovalBridge();
         this.approvalBridges.set(id, bridge);
-        const approvalExtension = (0, pi_approval_extension_1.createMafwApprovalExtension)(bridge, this.emitEvent, this.policy);
+        // 'always' allowlist 必须是会话私有副本：共享引用会把一次 "always" 扩散到
+        // 全部 pi 会话（契约语义是 session 级动态 allowlist）。
+        const sessionPolicy = this.policy
+            ? { autoApprove: [...(this.policy.autoApprove ?? [])], autoDeny: [...(this.policy.autoDeny ?? [])] }
+            : undefined;
+        const approvalExtension = (0, pi_approval_extension_1.createMafwApprovalExtension)(bridge, this.emitEvent, sessionPolicy, id);
         // Compaction listener: pi fires session_before_compact / session_compact to
         // extensions; re-emit as normalized runtime events (compaction facet).
         const compactionExtension = this.makeCompactionExtension(id);
@@ -219,6 +224,16 @@ class PiSessionRegistry {
             return false;
         return bridge.reply(requestId, reply, message);
     }
+    /** 全部 session 的待审批请求（ApprovalBridge pending map 汇总）。 */
+    listPendingPermissions() {
+        const out = [];
+        for (const [sessionID, bridge] of this.approvalBridges) {
+            for (const item of bridge.listPending()) {
+                out.push({ ...item, sessionID: item.sessionID ?? sessionID });
+            }
+        }
+        return out;
+    }
     async abort(id) {
         const s = this.sessions.get(id);
         if (s) {
@@ -244,9 +259,12 @@ class PiSessionRegistry {
         const file = sm.createBranchedSession(leafId);
         if (!file)
             throw new Error(`pi fork failed: createBranchedSession returned nothing for leaf ${leafId}`);
-        const bridge = new pi_approval_bridge_1.ApprovalBridge();
-        const approvalExtension = (0, pi_approval_extension_1.createMafwApprovalExtension)(bridge, this.emitEvent, this.policy);
         const newId = `pi_${(0, crypto_1.randomUUID)().slice(0, 8)}`;
+        const bridge = new pi_approval_bridge_1.ApprovalBridge();
+        const forkPolicy = this.policy
+            ? { autoApprove: [...(this.policy.autoApprove ?? [])], autoDeny: [...(this.policy.autoDeny ?? [])] }
+            : undefined;
+        const approvalExtension = (0, pi_approval_extension_1.createMafwApprovalExtension)(bridge, this.emitEvent, forkPolicy, newId);
         const compactionExtension = this.makeCompactionExtension(newId);
         const mediaExtension = this.makeMediaExtension(newId);
         try {

package/gateway/dist/runtime/plugins/pi-runtime.js

@@ -123,7 +123,9 @@ async function createPiRuntime(ctx, deps = {}) {
         }
         return mrPromise;
     }
-    const eventStream = new pi_events_1.PiEventStream((session) => undefined);
+    // Resolver maps a live pi AgentSession to its registry id — without it the
+    // event stream drops EVERY pi event (no session.idle / step-finish / deltas).
+    const eventStream = new pi_events_1.PiEventStream((session) => registry.sessionIdFor(session));
     const registry = new pi_session_1.PiSessionRegistry({
         createSession: async (opts) => {
             const pi = await imp('@earendil-works/pi-coding-agent');
@@ -162,7 +164,7 @@ async function createPiRuntime(ctx, deps = {}) {
     }, { sessionTtlMs: cfg.sessionTtlMs, emitEvent: (evt) => eventStream.push(evt), policy: cfg.approvalPolicy });
     const sessionAPI = {
         create: async (opts) => {
-            const { id } = await registry.create(opts?.directory ?? config_1.config.raw.paths.projectDir, { model: { provider, modelID } });
+            const { id } = await registry.create(opts?.directory ?? ctx.projectDir ?? config_1.config.raw.paths.projectDir, { model: { provider, modelID } });
             return { id };
         },
         promptAsync: async (opts) => {
@@ -194,6 +196,7 @@ async function createPiRuntime(ctx, deps = {}) {
             return (0, pi_session_storage_1.listByDirectory)(directory, limit);
         },
         permissionReply: (sessionID, requestId, reply, message) => registry.permissionReply(sessionID, requestId, reply, message),
+        permissionList: async () => registry.listPendingPermissions(),
         fork: async (opts) => registry.fork(opts.sessionID, opts.messageID),
         revert: async (opts) => registry.revert(opts.sessionID, opts.messageID),
     };
@@ -269,7 +272,7 @@ async function createPiRuntime(ctx, deps = {}) {
             },
         },
         registry,
-        getBaseUrl: () => `http://127.0.0.1:${config_1.config.server.apiPort ?? 3000}`,
+        getBaseUrl: () => `http://127.0.0.1:${ctx.gatewayPort ?? config_1.config.server.apiPort ?? 3000}`,
         healthCheck: async () => { try {
             await modelRuntime();
             return true;

package/gateway/dist/runtime/serve-sidecar.js

@@ -61,7 +61,10 @@ function killServePort(port) {
     try {
         if (process.platform === 'win32') {
             const out = childProcess.execSync(`netstat -ano | findstr :${port}`, { windowsHide: true }).toString();
-            const match = out.match(/LISTENING\s+(\d+)/);
+            // findstr ":4096" also matches ":40960" etc. — require the exact local
+            // port followed by whitespace on a LISTENING line before trusting the PID.
+            const line = out.split(/\r?\n/).find((l) => new RegExp(`:${port}\\s`).test(l) && /LISTENING/i.test(l));
+            const match = line ? line.match(/LISTENING\s+(\d+)/) : null;
             const pid = match ? Number(match[1]) : null;
             if (pid)
                 process.kill(pid);

package/gateway/dist/runtime/serve-supervisor.js

@@ -1,42 +1,43 @@
 "use strict";
 /**
- * Serve 进程唯一所有者：kill / spawn / 就绪等待 / 健康探测。
+ * Serve 进程唯一编排者：adopt / kill / spawn / 就绪等待。
  * 从 index.ts 下沉（原 killProcessOnPort + startServe + isServeHealthy 的动作段）。
- * kill 与 spawn 都是 runtime 契约原语（killServePort / agentProcess.spawnServe），
- * 本模块只做通用编排；gateway 编排层（recoverServe/watchdog）在其上叠加事件流重订。
- * deps 全部注入以便单测；生产装配见 index.ts。
+ * 原则：gateway 只编排，不实现——健康检测经 runtime 契约（health()）、
+ * 地址归 runtime（baseUrl()）、kill/spawn 都是 runtime 原语，gateway 不传
+ * host/port（serve 端口是 runtime 实现细节）。deps 全部注入以便单测。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServeSupervisor = createServeSupervisor;
 function createServeSupervisor(deps) {
-    const host = deps.host ?? '127.0.0.1';
     const probeIntervalMs = deps.probeIntervalMs ?? 500;
     const probeTimeoutMs = deps.probeTimeoutMs ?? 60_000;
     let instance;
     let starting;
-    const refused = () => new Error('external agent process is not managed by the gateway');
+    const refused = () => new Error('unmanaged runtime: gateway holds no start/stop primitives');
     const spawnAndWait = async () => {
-        instance = await deps.spawn({ host, port: deps.port, timeoutMs: probeTimeoutMs });
+        instance = await deps.spawn({ timeoutMs: probeTimeoutMs });
         const deadline = Date.now() + probeTimeoutMs;
         while (Date.now() < deadline) {
-            if (await deps.probe(instance.url))
-                return instance.url;
+            if (await deps.health())
+                return deps.baseUrl();
             await new Promise(r => setTimeout(r, probeIntervalMs));
         }
-        throw new Error(`serve did not become healthy within ${probeTimeoutMs}ms`);
+        throw new Error(`runtime did not become healthy within ${probeTimeoutMs}ms`);
     };
     return {
-        get owned() { return !deps.external; },
+        get owned() { return deps.managed(); },
         async ensureStarted() {
-            if (deps.external)
+            if (!deps.managed())
                 throw refused();
-            if (instance && await deps.probe(instance.url))
-                return instance.url;
+            // Adopt：runtime 健康（含用户自管/已有监听）直接收养，绝不 kill——
+            // 健康判定来自 runtime 契约，gateway 不构造候选 URL。
+            if (await deps.health())
+                return deps.baseUrl();
             if (starting)
                 return starting;
             starting = (async () => {
                 try {
-                    deps.killPort(deps.port);
+                    deps.killServe();
                     instance = undefined;
                     return await spawnAndWait();
                 }
@@ -47,13 +48,13 @@ function createServeSupervisor(deps) {
             return starting;
         },
         async restart() {
-            if (deps.external)
+            if (!deps.managed())
                 throw refused();
             if (starting)
                 return starting;
             starting = (async () => {
                 try {
-                    deps.killPort(deps.port);
+                    deps.killServe();
                     instance?.close();
                     instance = undefined;
                     return await spawnAndWait();
@@ -65,9 +66,7 @@ function createServeSupervisor(deps) {
             return starting;
         },
         async health() {
-            if (!instance)
-                return false;
-            return deps.probe(instance.url);
+            return deps.health();
         },
         close() {
             try {

package/gateway/dist/runtime/validate.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRuntimeShape = validateRuntimeShape;
+const SESSION_REQUIRED_BY_SESSION_API = ['create', 'promptAsync', 'prompt', 'messages'];
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function validateRuntimeShape(rt, source) {
+    if (!isObject(rt))
+        return [`${source}: runtime must be an object (got ${typeof rt})`];
+    const issues = [];
+    const caps = rt.capabilities;
+    if (typeof rt.name !== 'string' || !rt.name) {
+        issues.push(`${source}: runtime.name must be a non-empty string (got ${typeof rt.name})`);
+    }
+    if (!isObject(caps)) {
+        issues.push(`${source}: runtime.capabilities must be an object (got ${typeof caps})`);
+        return issues;
+    }
+    if (caps.sessionApi) {
+        if (!isObject(rt.session)) {
+            issues.push(`${source}: declares sessionApi but session is missing`);
+        }
+        else {
+            for (const method of SESSION_REQUIRED_BY_SESSION_API) {
+                if (typeof rt.session[method] !== 'function') {
+                    issues.push(`${source}: declares sessionApi but session.${method} is missing (not a function)`);
+                }
+            }
+        }
+    }
+    if (caps.eventStream) {
+        const ev = rt.global;
+        if (!isObject(ev) || typeof ev.event !== 'function') {
+            issues.push(`${source}: declares eventStream but global.event is missing (not a function)`);
+        }
+    }
+    return issues;
+}

package/gateway/dist/skills/manager-identity.js

@@ -8,4 +8,9 @@ Constraints:
   - goal 状态只能从工具查询获得，不许凭记忆回答进度
   - 用户没有问进度时，不主动汇报中间态，只在完成/失败/被阻塞时发言
   - 不确定是否为任务时先澄清，创建 goal 前必须复述确认
-  - 需要重启或自更新 gateway 时，加载 mafw-gateway-restart skill 并按流程执行（改码→build→写令牌→等通知→续跑）`;
+  - 需要重启或自更新 gateway 时，加载 mafw-gateway-restart skill 并按流程执行（改码→build→写令牌→等通知→续跑）
+Goal charter 写法（mafw_create_goal / mafw_set_goal 的 charter，超出单轮能做的 goal 适用）:
+  - charter 是一张地图而非仓库，分五段：## Destination（终点长什么样，一两行，一切条目向它对齐）/ ## Plan（执行计划）/ ## Decisions so far（决策索引：一行 gist + 记忆 id，绝不复制详情）/ ## Not yet specified（已知的未知：还不能精确陈述、暂不成条目的问题；frontier 推进后毕业为正式条目并从此段清除）/ ## Out of scope（明确排除项，防范围蔓延；排除是划界动作，不计入路线）
+  - 每个决策用 mafw_add_memory（semantic，cueAnchors 带 goalId 与主题实体）记录，charter 与 state 只存指针 id——记忆可跨会话检索，state 只是索引
+  - 给用户看的列表与汇报里按名引用（用标题），不用裸 goalId 刷屏；id 放在名字后的括号里
+  - 一个 decision 没弄清楚前不要急着进 EXECUTING；规划阶段的产出是决策，不是交付物`;

package/gateway/dist/usage/builtin-plugins/gateway.js

@@ -1,35 +1,89 @@
 // Builtin usage plugin: 蓝区统一网关（providerID: gateway）
-// credit 总量 + day/7d/month 滚动窗口。限额由用户手配（usage.pluginConfig.gateway），
-// 消耗 = 本地 trajectory tokens × per-model credit 价格（GET {baseURL}/models，5min 缓存）。
+// credit 总量 + day/7d/month 窗口。限额由用户手配（usage.pluginConfig.gateway）。
+// day/7d/month 优先走网关权威用量（GET {baseURL}/usage/by-model?window=today|week|month，
+// BlueRegionUsage 链路，2026-09-16 实测生产可用）：逐日 tokens × /models credit_history
+// 当日生效系数（区间语义 [from, 下一条 from)）÷ 1e6，端点失败逐窗口回退本地 trajectory 估算。
+// balance（credit 总量）网关无全历史端点（retention 31 天），始终用本地全历史估算。
+// /models 价格 5min 缓存。
 const DEFAULT_BASE_URL = 'https://st8tp3ajl0df3n8b8l8qu.apigateway-cn-beijing.volceapi.com/v1';
 const PRICE_CACHE_MS = 5 * 60 * 1000;
-let priceCache = { at: 0, prices: null };
+let priceCache = { at: 0, catalog: null };
 
-async function loadPrices(ctx, baseURL, key) {
+async function loadCatalog(ctx, baseURL, key) {
   const now = Date.now();
-  if (priceCache.prices && now - priceCache.at < PRICE_CACHE_MS) return priceCache.prices;
+  if (priceCache.catalog && now - priceCache.at < PRICE_CACHE_MS) return priceCache.catalog;
   try {
     const res = await ctx.fetch(baseURL.replace(/\/+$/, '') + '/models', {
       headers: { Authorization: 'Bearer ' + key },
     });
     if (!res.ok) {
       ctx.log.warn('[GatewayPlugin] /models HTTP ' + res.status);
-      return priceCache.prices;
+      return priceCache.catalog;
     }
     const data = await res.json();
     const prices = {};
+    const hist = {};
     for (const m of (data && data.data) || []) {
-      const c = Number(m && m.credit);
-      if (m && m.id && Number.isFinite(c)) prices[m.id] = c;
+      if (!m || !m.id) continue;
+      const c = Number(m.credit);
+      if (Number.isFinite(c)) prices[m.id] = c;
+      if (Array.isArray(m.credit_history)) hist[m.id] = m.credit_history;
     }
-    priceCache = { at: now, prices };
-    return prices;
+    priceCache = { at: now, catalog: { prices, hist } };
+    return priceCache.catalog;
   } catch (err) {
     ctx.log.warn('[GatewayPlugin] /models failed: ' + ((err && err.message) || err));
-    return priceCache.prices;
+    return priceCache.catalog;
   }
 }
 
+// 网关权威用量：by-model 逐日明细。失败/契约不符返回 null（调用方回退本地估算）。
+async function fetchGatewayByModel(ctx, baseURL, key, gwWindow) {
+  try {
+    const res = await ctx.fetch(baseURL.replace(/\/+$/, '') + '/usage/by-model?window=' + gwWindow, {
+      headers: { Authorization: 'Bearer ' + key },
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    const rows = (data && data.data) || [];
+    if (!Array.isArray(rows)) return null;
+    // 契约校验：by-model 行必须含 model + daily 逐日明细（防 /models 形状误入）
+    if (rows.some((r) => !r || typeof r.model !== 'string' || !Array.isArray(r.daily))) return null;
+    return rows;
+  } catch (err) {
+    return null;
+  }
+}
+
+// date 当日生效系数：取 from <= date 的最后一条；date 早于首条时用首条系数
+function creditForDate(hist, date) {
+  if (!Array.isArray(hist) || hist.length === 0) return null;
+  let cur = null;
+  let first = null;
+  for (const e of hist) {
+    if (!e || typeof e.credit !== 'number') continue;
+    if (first === null) first = e.credit;
+    if (typeof e.from === 'string' && e.from <= date) cur = e.credit;
+  }
+  return cur !== null ? cur : first;
+}
+
+function gatewayCredits(rows, hist, prices) {
+  let credits = 0;
+  for (const r of rows) {
+    const h = hist ? hist[r.model] : null;
+    for (const d of r.daily) {
+      if (!d) continue;
+      const tok = Number(d.total_tokens != null ? d.total_tokens : (Number(d.req_tokens) || 0) + (Number(d.rsp_tokens) || 0));
+      if (!Number.isFinite(tok) || tok <= 0) continue;
+      // 无 credit_history 的模型回退 /models 当前系数（官方面板同款降级）
+      const coef = creditForDate(h, d.date) ?? (prices ? prices[r.model] : null);
+      if (coef != null) credits += (tok * coef) / 1e6;
+    }
+  }
+  return credits;
+}
+
 function rowTokens(r) {
   const t = (r && r.tokens) || {};
   const cache = t.cache || {};
@@ -56,9 +110,12 @@ function creditsInWindow(rows, prices) {
   return { credits, perModel };
 }
 
-const ROLLING_WINDOWS = [
-  ['day', 'day', 24 * 3600e3],
-  ['week', '7d', 7 * 24 * 3600e3],
+// day/week/month 窗口表：gw = 网关权威窗口（UTC+8 日历对齐），localSince = 回退本地估算起点。
+// day 本地回退为滚动 24h，week 为滚动 7d，month 为自然月——仅网关端点不可达时生效。
+const WINDOWS = [
+  { cfg: 'day', label: 'day', gw: 'today', localSince: (now) => now - 24 * 3600e3, resetAt: null },
+  { cfg: 'week', label: '7d', gw: 'week', localSince: (now) => now - 7 * 24 * 3600e3, resetAt: null },
+  { cfg: 'month', label: 'month', gw: 'month', localSince: () => calendarMonthStart(Date.now()), resetAt: () => calendarMonthEnd(Date.now()) },
 ];
 
 // 月度刷新 = 自然月（每月 1 号 00:00 本地时区重置），非滚动 30 天。
@@ -95,7 +152,9 @@ module.exports = {
     };
     if (lim.credit <= 0 && lim.day <= 0 && lim.week <= 0 && lim.month <= 0) return null;
     const baseURL = typeof cfg.baseURL === 'string' && cfg.baseURL.trim() ? cfg.baseURL.trim() : DEFAULT_BASE_URL;
-    const prices = await loadPrices(ctx, baseURL, key);
+    const catalog = (await loadCatalog(ctx, baseURL, key)) || { prices: null, hist: {} };
+    const prices = catalog.prices;
+    const hist = catalog.hist || {};
     const stats = (opts) => (ctx.usage && ctx.usage.modelStats ? ctx.usage.modelStats(opts) : []);
 
     const windows = [];
@@ -119,29 +178,25 @@ module.exports = {
         detailLines,
       });
     }
-    for (const [cfgKey, win, ms] of ROLLING_WINDOWS) {
-      if (lim[cfgKey] <= 0) continue;
-      const { credits } = creditsInWindow(stats({ provider: 'gateway', sinceMs: Date.now() - ms }), prices);
-      const used = Math.round(credits * 100) / 100;
-      windows.push({
-        window: win,
-        used,
-        limit: lim[cfgKey],
-        unit: 'credit',
-        pct: Math.round((used / lim[cfgKey]) * 10000) / 100,
-      });
-    }
-    if (lim.month > 0) {
-      const { credits } = creditsInWindow(stats({ provider: 'gateway', sinceMs: calendarMonthStart(Date.now()) }), prices);
-      const used = Math.round(credits * 100) / 100;
-      windows.push({
-        window: 'month',
+    for (const w of WINDOWS) {
+      if (lim[w.cfg] <= 0) continue;
+      // 权威路径：网关逐日明细 × credit_history 当日系数；失败逐窗口回退本地估算
+      const rows = await fetchGatewayByModel(ctx, baseURL, key, w.gw);
+      let used = null;
+      if (rows !== null) used = Math.round(gatewayCredits(rows, hist, prices) * 100) / 100;
+      if (used === null) {
+        const { credits } = creditsInWindow(stats({ provider: 'gateway', sinceMs: w.localSince(Date.now()) }), prices);
+        used = Math.round(credits * 100) / 100;
+      }
+      const win = {
+        window: w.label,
         used,
-        limit: lim.month,
+        limit: lim[w.cfg],
         unit: 'credit',
-        pct: Math.round((used / lim.month) * 10000) / 100,
-        resetAt: calendarMonthEnd(Date.now()),
-      });
+        pct: Math.round((used / lim[w.cfg]) * 10000) / 100,
+      };
+      if (w.resetAt) win.resetAt = w.resetAt();
+      windows.push(win);
     }
     if (windows.length === 0) return null;
     return { name: 'gateway', type: 'token-plan', plan: '蓝区统一网关', windows };

package/gateway/dist/usage/plugin-context.js

@@ -40,6 +40,37 @@ function severityFromPct(pct) {
         return 'mid';
     return 'low';
 }
+/** 字段级 windows 校验（插件作者可定位：windows[i].<key> must be <type> (got <got>)）。 */
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function validateWindowsShape(windows) {
+    for (let i = 0; i < windows.length; i++) {
+        const w = windows[i];
+        const at = `windows[${i}]`;
+        if (!w || typeof w !== 'object' || Array.isArray(w)) {
+            return `${at} must be an object (got ${typeName(w)})`;
+        }
+        if (typeof w.window !== 'string')
+            return `${at}.window must be string (got ${typeName(w.window)})`;
+        for (const key of ['used', 'limit']) {
+            if (typeof w[key] !== 'number')
+                return `${at}.${key} must be number (got ${typeName(w[key])})`;
+        }
+        for (const key of ['pct', 'unit', 'label']) {
+            if (w[key] === undefined)
+                continue;
+            const expected = key === 'pct' ? 'number' : 'string';
+            if (typeof w[key] !== expected)
+                return `${at}.${key} must be ${expected} (got ${typeName(w[key])})`;
+        }
+    }
+    return null;
+}
 function makeAdapter(mod, file, usageStats, resolveInlineApiKey) {
     return {
         name: mod.name,
@@ -59,8 +90,17 @@ function makeAdapter(mod, file, usageStats, resolveInlineApiKey) {
                 const result = await mod.fetch(ctx);
                 if (result === null)
                     return null;
-                if (!result.name || !Array.isArray(result.windows)) {
-                    logger_1.log.warn(`[PluginLoader] ${file}: invalid return structure`);
+                if (!result.name) {
+                    logger_1.log.warn(`[PluginLoader] ${file}: result.name must be string (got ${typeName(result.name)})`);
+                    return null;
+                }
+                if (!Array.isArray(result.windows)) {
+                    logger_1.log.warn(`[PluginLoader] ${file}: result.windows must be array (got ${typeName(result.windows)})`);
+                    return null;
+                }
+                const shapeErr = validateWindowsShape(result.windows);
+                if (shapeErr) {
+                    logger_1.log.warn(`[PluginLoader] ${file}: ${shapeErr}`);
                     return null;
                 }
                 const maxPct = result.windows.length > 0 ? Math.max(...result.windows.map((w) => w.pct ?? 0)) : 0;

package/gateway/dist/usage/plugin-loader.js

@@ -74,6 +74,7 @@ class PluginLoader {
     builtinNames;
     usageStats;
     resolveInlineApiKey;
+    packageEntries = [];
     constructor(pluginsDir, builtinNames, opts) {
         this.pluginsDir = pluginsDir;
         this.builtinNames = new Set(builtinNames);
@@ -173,18 +174,47 @@ class PluginLoader {
         this.builtinNames = builtinNameSet;
     }
     getAdapters() {
+        const packageNames = new Set(this.packageEntries.map((e) => e.mod.name));
         const adapters = [];
         for (const s of this.state.values()) {
-            if (s.status === 'ok' && s.adapter && !s.disabled)
+            if (s.status === 'ok' && s.adapter && !s.disabled && !packageNames.has(s.name))
                 adapters.push(s.adapter);
         }
+        for (const e of this.packageEntries) {
+            if (this.disabledPlugins.has(e.mod.name))
+                continue;
+            adapters.push((0, plugin_context_1.makeAdapter)(e.mod, e.source, this.usageStats, this.resolveInlineApiKey));
+        }
         return adapters;
     }
     isBuiltinName(name) {
         return this.builtinNames.has(name);
     }
     getState() {
-        return [...this.state.values()];
+        const out = [...this.state.values()].map((s) => ({ ...s }));
+        const packageNames = new Set(this.packageEntries.map((e) => e.mod.name));
+        for (const s of out) {
+            if (s.name && packageNames.has(s.name))
+                s.overridden = true;
+        }
+        for (const e of this.packageEntries) {
+            out.push({
+                file: e.source,
+                name: e.mod.name,
+                status: 'ok',
+                overridden: false,
+                builtin: false,
+                adapter: undefined,
+                configSchema: validateConfigSchema(e.mod.configSchema),
+                disabled: this.disabledPlugins.has(e.mod.name),
+                pluginType: typeof e.mod.type === 'string' ? e.mod.type : undefined,
+            });
+        }
+        return out;
+    }
+    /** PluginHost 推送的包贡献。同名包覆盖 legacy 文件与内置；disabledPlugins 同样生效。 */
+    setPackageEntries(entries) {
+        this.packageEntries = entries ?? [];
     }
     async reload() {
         await this.scan();