@jack200714/mafw 4.5.2 → 4.10.1

package/gateway/dist/runtime/loader.js

@@ -54,6 +54,7 @@ class RuntimePluginLoader {
     meta = new Map();
     state = new Map();
     builtins = new Map();
+    packageEntries = new Map();
     constructor(pluginsDir) {
         this.pluginsDir = pluginsDir;
     }
@@ -69,7 +70,6 @@ class RuntimePluginLoader {
         if (!fs.existsSync(this.pluginsDir)) {
             fs.mkdirSync(this.pluginsDir, { recursive: true });
             fs.writeFileSync(path.join(this.pluginsDir, 'README.md'), README_CONTENT);
-            fs.writeFileSync(path.join(this.pluginsDir, 'example.js.disabled'), EXAMPLE_CONTENT);
             logger_1.log.info(`[RuntimePluginLoader] Created ${this.pluginsDir}`);
         }
     }
@@ -90,6 +90,10 @@ class RuntimePluginLoader {
                     this.factories.delete(prev.name);
                     this.meta.delete(prev.name);
                 }
+                if (prev?.alias) {
+                    this.factories.delete(prev.alias);
+                    this.meta.delete(prev.alias);
+                }
                 this.state.delete(file);
             }
         }
@@ -123,9 +127,22 @@ class RuntimePluginLoader {
             const external = mod.external !== false;
             this.factories.set(name, mod.createRuntime);
             this.meta.set(name, { capabilities, external });
-            this.state.set(file, { file, name, status: 'ok', capabilities });
             loadedNames.add(name);
-            logger_1.log.info(`[RuntimePluginLoader] Loaded ${file} (${name})`);
+            // Filename-stem alias: the plugin hub addresses runtime plugins by
+            // filename stem (statEntry baseName) while switch/createRuntime
+            // validate by module.exports.name — register both so hub "激活" works
+            // regardless of the declared name. The real module name always wins
+            // (unconditional set above overwrites an earlier stem alias), and an
+            // alias never shadows a builtin.
+            const stem = file.replace(/\.js$/, '');
+            let alias;
+            if (stem !== name && !this.factories.has(stem) && !this.builtins.has(stem)) {
+                this.factories.set(stem, mod.createRuntime);
+                this.meta.set(stem, { capabilities, external });
+                alias = stem;
+            }
+            this.state.set(file, { file, name, status: 'ok', capabilities, alias });
+            logger_1.log.info(`[RuntimePluginLoader] Loaded ${file} (${name})${alias ? ` [alias: ${alias}]` : ''}`);
         }
         catch (err) {
             const prev = this.state.get(file);
@@ -133,31 +150,55 @@ class RuntimePluginLoader {
             logger_1.log.warn(`[RuntimePluginLoader] ${file} load error: ${err.message}`);
         }
     }
+    /** PluginHost 推送的包贡献。查找顺序：legacy 文件 > 包 > 内置。scan() 不影响。 */
+    setPackageEntries(entries) {
+        this.packageEntries = new Map(entries.map((e) => [e.name, e]));
+    }
     /** 插件不存在或未通过校验时返回 undefined（调用方回退内置 opencode）。文件插件优先于内置。 */
     get(name) {
         const createRuntime = this.factories.get(name);
         const meta = this.meta.get(name);
         if (createRuntime && meta)
             return { createRuntime, ...meta };
+        const pkg = this.packageEntries.get(name);
+        if (pkg) {
+            return {
+                createRuntime: pkg.createRuntime,
+                capabilities: { ...(0, contract_1.minimalCapabilities)(), ...pkg.capabilities },
+                external: pkg.external,
+            };
+        }
         const builtin = this.builtins.get(name);
         if (builtin)
             return { createRuntime: builtin.factory, ...builtin };
         return undefined;
     }
+    /** 已注册内置件名（builtin 文件件不在其中，opencode 为恒等默认由 index.ts 注入 hub）。 */
+    getBuiltinNames() {
+        return [...this.builtins.keys()];
+    }
     getState() {
         for (const [name, b] of this.builtins) {
             this.state.set(`builtin:${name}`, { file: `builtin:${name}`, name, status: 'ok', capabilities: b.capabilities });
         }
+        for (const [name, p] of this.packageEntries) {
+            this.state.set(`package:${name}`, {
+                file: `package:${name}`, name, status: 'ok',
+                capabilities: { ...(0, contract_1.minimalCapabilities)(), ...p.capabilities },
+            });
+        }
         return [...this.state.values()];
     }
 }
 exports.RuntimePluginLoader = RuntimePluginLoader;
-function createRuntimePluginContext(credentials) {
+function createRuntimePluginContext(credentials, extra) {
     return {
         fetch: (url, opts) => fetch(url, { ...opts, signal: opts?.signal ?? AbortSignal.timeout(60000) }),
         log: logger_1.log,
         pluginConfig: (name) => config_1.config.raw?.runtime?.pluginConfig?.[name] ?? {},
         credentials,
+        projectDir: extra?.projectDir,
+        gatewayPort: extra?.gatewayPort,
     };
 }
 const README_CONTENT = `# Runtime Plugins
@@ -228,13 +269,3 @@ Capabilities declared here gate gateway features declaratively: missing
 capabilities disable the corresponding features (503 on gated endpoints,
 skipped event subscription) — they never crash.
 `;
-const EXAMPLE_CONTENT = `// Rename to example.js to activate
-module.exports = {
-  name: "example",
-  capabilities: { eventStream: false },
-  async createRuntime(ctx) {
-    ctx.log.info("[example-runtime] created");
-    throw new Error("example plugin: implement createRuntime before activating");
-  },
-};
-`;

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/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

@@ -32,6 +32,18 @@ function createServeSupervisor(deps) {
                 throw refused();
             if (instance && await deps.probe(instance.url))
                 return instance.url;
+            // Adopt: gateway startup may have adopted a healthy serve, or a
+            // user-managed opencode may already listen here — never killPort a
+            // healthy listener on this port (that would drop every SSE/desktop/TUI
+            // connection on a pi→opencode switch).
+            const candidateUrl = `http://${host}:${deps.port}`;
+            try {
+                if (await deps.probe(candidateUrl)) {
+                    instance = { url: candidateUrl, close: () => { } };
+                    return candidateUrl;
+                }
+            }
+            catch { /* not healthy → spawn below */ }
             if (starting)
                 return starting;
             starting = (async () => {

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,12 +110,25 @@ function creditsInWindow(rows, prices) {
   return { credits, perModel };
 }
 
-const ROLLING_WINDOWS = [
-  ['day', 'day', 24 * 3600e3],
-  ['week', '7d', 7 * 24 * 3600e3],
-  ['month', 'month', 30 * 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 天。
+function calendarMonthStart(now) {
+  const d = new Date(now);
+  return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+}
+
+function calendarMonthEnd(now) {
+  const d = new Date(now);
+  return new Date(d.getFullYear(), d.getMonth() + 1, 1).getTime();
+}
+
 module.exports = {
   name: 'gateway',
   type: 'token-plan',
@@ -85,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 = [];
@@ -104,22 +173,30 @@ module.exports = {
         used,
         limit: lim.credit,
         unit: 'credit',
-        pct: Math.round((used / lim.credit) * 100),
+        pct: Math.round((used / lim.credit) * 10000) / 100,
         remaining: Math.max(0, Math.round((lim.credit - used) * 100) / 100),
         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,
+    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[cfgKey],
+        limit: lim[w.cfg],
         unit: 'credit',
-        pct: Math.round((used / lim[cfgKey]) * 100),
-      });
+        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;