@jack200714/mafw 4.5.1

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

@@ -0,0 +1,280 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginLoader = void 0;
+exports.validateConfigSchema = validateConfigSchema;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
+const plugin_context_1 = require("./plugin-context");
+const SCHEMA_TYPES = new Set(['number', 'string', 'boolean', 'select']);
+/** Fail-open: anything malformed → undefined (plugin still loads, no form UI). */
+function validateConfigSchema(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            return undefined;
+        const f = item;
+        if (typeof f.key !== 'string' || !/^[a-zA-Z0-9_]+$/.test(f.key))
+            return undefined;
+        if (typeof f.label !== 'string' || typeof f.type !== 'string' || !SCHEMA_TYPES.has(f.type))
+            return undefined;
+        if (f.type === 'select' && (!Array.isArray(f.options) || f.options.length === 0 || f.options.some(o => typeof o !== 'string')))
+            return undefined;
+        const field = { key: f.key, label: f.label, type: f.type };
+        if (Array.isArray(f.options))
+            field.options = f.options;
+        if (f.default !== undefined)
+            field.default = f.default;
+        out.push(field);
+    }
+    return out;
+}
+class PluginLoader {
+    pluginsDir;
+    builtinPluginsDir;
+    disabledPlugins;
+    state = new Map();
+    watcher;
+    debounceTimer;
+    builtinNames;
+    usageStats;
+    resolveInlineApiKey;
+    constructor(pluginsDir, builtinNames, opts) {
+        this.pluginsDir = pluginsDir;
+        this.builtinNames = new Set(builtinNames);
+        this.builtinPluginsDir = opts?.builtinPluginsDir;
+        this.disabledPlugins = new Set(opts?.disabledPlugins ?? []);
+        this.usageStats = opts?.usageStats;
+        this.resolveInlineApiKey = opts?.resolveInlineApiKey;
+    }
+    async init() {
+        this.ensureDir();
+        await this.scan();
+        this.startWatch();
+    }
+    ensureDir() {
+        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(`[PluginLoader] Created ${this.pluginsDir}`);
+        }
+    }
+    collectFiles() {
+        const files = [];
+        if (this.builtinPluginsDir && fs.existsSync(this.builtinPluginsDir)) {
+            for (const f of fs.readdirSync(this.builtinPluginsDir).filter(f => f.endsWith('.js')).sort()) {
+                files.push({ fullPath: path.join(this.builtinPluginsDir, f), file: f, builtin: true });
+            }
+        }
+        if (fs.existsSync(this.pluginsDir)) {
+            for (const f of fs.readdirSync(this.pluginsDir).filter(f => f.endsWith('.js')).sort()) {
+                files.push({ fullPath: path.join(this.pluginsDir, f), file: f, builtin: false });
+            }
+        }
+        return files;
+    }
+    async scan() {
+        const files = this.collectFiles();
+        const builtinNameSet = new Set(this.builtinNames);
+        const byName = new Map();
+        const errors = [];
+        for (const { fullPath, file, builtin } of files) {
+            try {
+                const cacheKey = require.resolve(fullPath);
+                delete require.cache[cacheKey];
+            }
+            catch { /* first load */ }
+            try {
+                const mod = require(fullPath);
+                const name = mod?.name;
+                if (!name || typeof name !== 'string') {
+                    errors.push({ file, builtin, error: 'missing name' });
+                    continue;
+                }
+                if (typeof mod.fetch !== 'function') {
+                    errors.push({ file, builtin, error: 'missing fetch()' });
+                    continue;
+                }
+                if (builtin)
+                    builtinNameSet.add(name);
+                const existing = byName.get(name);
+                if (existing) {
+                    if (builtin) {
+                        // builtin duplicates another loaded name (builtin or user) → error
+                        errors.push({ file, builtin, error: 'duplicate name' });
+                        continue;
+                    }
+                    if (!existing.builtin) {
+                        // two user files with same name → error on second
+                        errors.push({ file, builtin, error: 'duplicate name' });
+                        continue;
+                    }
+                    // user file overrides builtin
+                    byName.set(name, { file, builtin, mod });
+                    continue;
+                }
+                byName.set(name, { file, builtin, mod });
+            }
+            catch (err) {
+                errors.push({ file, builtin, error: err.message });
+            }
+        }
+        this.state.clear();
+        for (const [name, entry] of byName) {
+            const overridden = !entry.builtin && builtinNameSet.has(name);
+            const adapter = (0, plugin_context_1.makeAdapter)(entry.mod, entry.file, this.usageStats, this.resolveInlineApiKey);
+            const configSchema = validateConfigSchema(entry.mod.configSchema);
+            const disabled = this.disabledPlugins.has(name);
+            const pluginType = typeof entry.mod.type === 'string' ? entry.mod.type : undefined;
+            this.state.set(entry.file, { file: entry.file, name, status: 'ok', overridden, builtin: entry.builtin, adapter, configSchema, disabled, pluginType });
+            logger_1.log.info(`[PluginLoader] Loaded ${entry.file} (${name})${entry.builtin ? ' [builtin]' : ''}${overridden ? ' [overrides builtin]' : ''}${disabled ? ' [disabled]' : ''}`);
+        }
+        for (const e of errors) {
+            this.state.set(e.file, { file: e.file, status: 'error', error: e.error, overridden: false, builtin: e.builtin, disabled: false });
+            logger_1.log.warn(`[PluginLoader] ${e.file} load error: ${e.error}`);
+        }
+        // Persist discovered builtin names so isBuiltinName reflects directory
+        // findings even when production wiring declares none (index.ts passes []).
+        this.builtinNames = builtinNameSet;
+    }
+    getAdapters() {
+        const adapters = [];
+        for (const s of this.state.values()) {
+            if (s.status === 'ok' && s.adapter && !s.disabled)
+                adapters.push(s.adapter);
+        }
+        return adapters;
+    }
+    isBuiltinName(name) {
+        return this.builtinNames.has(name);
+    }
+    getState() {
+        return [...this.state.values()];
+    }
+    async reload() {
+        await this.scan();
+    }
+    startWatch() {
+        if (!fs.existsSync(this.pluginsDir))
+            return;
+        try {
+            this.watcher = fs.watch(this.pluginsDir, () => {
+                if (this.debounceTimer)
+                    clearTimeout(this.debounceTimer);
+                this.debounceTimer = setTimeout(async () => {
+                    if (!fs.existsSync(this.pluginsDir)) {
+                        logger_1.log.warn(`[PluginLoader] plugins dir deleted, stopping watch`);
+                        this.watcher?.close();
+                        this.watcher = undefined;
+                        return;
+                    }
+                    await this.scan();
+                }, 300);
+            });
+        }
+        catch (err) {
+            logger_1.log.warn(`[PluginLoader] watch failed: ${err.message}`);
+        }
+    }
+    stop() {
+        this.watcher?.close();
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+    }
+}
+exports.PluginLoader = PluginLoader;
+const README_CONTENT = `# Usage Provider Plugins
+
+Place \`.js\` files here to add custom usage providers. Each file exports:
+
+\`\`\`js
+module.exports = {
+  name: "my-provider",
+  type: "api",             // "api" (balance/limit) or "token-plan" (5h/7d/month windows)
+  plan: "My Plan",
+  async fetch(ctx) {
+    const key = ctx.apiKey("my-provider");
+    if (!key) return null;
+    const res = await ctx.fetch("https://api.example.com/usage", {
+      headers: { Authorization: \`Bearer \${key}\` },
+    });
+    const data = await res.json();
+    return {
+      name: "my-provider",
+      type: "api",
+      plan: "My Plan",
+      windows: [{
+        window: "balance",
+        used: data.used,
+        limit: data.limit,
+        unit: "$",
+        pct: Math.round((data.used / data.limit) * 100),
+      }],
+    };
+  },
+};
+\`\`\`
+
+**Types:**
+- \`api\` — credit/balance style (balance window)
+- \`token-plan\` — quota windows (5h / 7d / month)
+
+**ctx methods:**
+- \`ctx.apiKey(name)\` — read provider key from opencode auth.json
+- \`ctx.cookie(name)\` — read usage.cookies[name] from config
+- \`ctx.fetch(url, opts)\` — fetch with 10s timeout
+- \`ctx.pluginConfig(name)\` — read usage.pluginConfig[name] from config
+- \`ctx.usage.modelStats({ sinceMs?, provider? })\` — local trajectory per-model token stats
+  (rolling window; filter by providerID; returns [])
+- \`ctx.log\` — gateway logger
+
+Return \`null\` to hide provider. Builtin plugins live in the package
+\`dist/usage/builtin-plugins/\`; drop a file with the same \`name\` here to override,
+or add the name to \`usage.disabledPlugins\` in config to disable.
+`;
+const EXAMPLE_CONTENT = `// Rename to example.js to activate
+module.exports = {
+  name: "example",
+  type: "api",
+  plan: "Example Plan",
+  async fetch(ctx) {
+    return null; // Hide provider
+  },
+};
+`;

package/gateway/dist/usage/templates.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE_TEMPLATES = void 0;
+exports.renderTemplate = renderTemplate;
+const AUTH_FIELDS = [
+    { key: 'authMode', label: '认证方式', type: 'select', options: ['none', 'authKey', 'cookie', 'header'], hint: 'authKey=opencode 登录凭据；cookie=用量 cookies；header=自定义头（值存 pluginConfig.headerValue）' },
+    { key: 'authName', label: '认证名（auth provider 或 cookie 名）', type: 'string' },
+    { key: 'headerName', label: '自定义 header 名', type: 'string', hint: '仅 authMode=header 时使用' },
+];
+function jsValue(v) {
+    return JSON.stringify(v ?? null);
+}
+function pickFn() {
+    return [
+        'function pick(obj, path) {',
+        '  if (!path) return undefined;',
+        '  return path.split(".").reduce((acc, k) => (acc == null ? undefined : acc[k]), obj);',
+        '}',
+    ].join('\n');
+}
+function authBlock(name) {
+    return [
+        `  const pc = ctx.pluginConfig(${jsValue(name)}) || {};`,
+        '  const cfg = { ...CFG, ...pc };',
+        '  const headers = {};',
+        "  if (cfg.authMode === 'authKey') {",
+        '    const key = ctx.apiKey(cfg.authName);',
+        '    if (!key) return null;',
+        "    headers.Authorization = 'Bearer ' + key;",
+        "  } else if (cfg.authMode === 'cookie') {",
+        '    const cookie = ctx.cookie(cfg.authName);',
+        '    if (!cookie) return null;',
+        '    headers.Cookie = cookie;',
+        "  } else if (cfg.authMode === 'header') {",
+        "    headers[cfg.headerName || 'X-Api-Key'] = pc.headerValue || '';",
+        '  }',
+    ];
+}
+function renderBalanceApi(v) {
+    const name = v.name;
+    const schema = [
+        { key: 'endpoint', label: 'Endpoint URL', type: 'string', default: v.endpoint },
+        { key: 'usedPath', label: 'used 字段路径', type: 'string', default: v.usedPath },
+        { key: 'limitPath', label: 'limit 字段路径', type: 'string', default: v.limitPath },
+        { key: 'remainingPath', label: 'remaining 字段路径', type: 'string', default: v.remainingPath },
+    ];
+    return [
+        `// Generated by MAFW usage template 'balance-api'`,
+        `// 参数可在 Config → Usage 插件详情表单修改（存 usage.pluginConfig），或直接编辑本文件`,
+        `const CFG = ${jsValue({ name, displayName: v.displayName || name, authMode: v.authMode || 'none', authName: v.authName || '', headerName: v.headerName || '', endpoint: v.endpoint, usedPath: v.usedPath || '', limitPath: v.limitPath || '', remainingPath: v.remainingPath || '' })};`,
+        `const SCHEMA = ${jsValue(schema)};`,
+        pickFn(),
+        `async function main(ctx) {`,
+        ...authBlock(name),
+        '  const res = await ctx.fetch(cfg.endpoint, { headers });',
+        "  if (!res.ok) { ctx.log.warn('[' + CFG.name + '] HTTP ' + res.status); return null; }",
+        '  const data = await res.json();',
+        '  const used = pick(data, cfg.usedPath);',
+        '  const limit = pick(data, cfg.limitPath);',
+        '  const remaining = pick(data, cfg.remainingPath);',
+        '  if (limit === undefined && remaining === undefined) return null;',
+        '  const u = Number(used !== undefined ? used : (limit !== undefined && remaining !== undefined ? limit - remaining : 0));',
+        '  const l = Number(limit !== undefined ? limit : u + Number(remaining || 0));',
+        '  if (!isFinite(u) || !isFinite(l) || l <= 0) return null;',
+        "  return { name: CFG.name, type: 'api', plan: CFG.displayName, windows: [{ window: 'balance', used: u, limit: l, unit: '$', pct: Math.min(100, Math.round((u / l) * 100)), remaining }] };",
+        '}',
+        `module.exports = { name: ${jsValue(name)}, type: 'api', plan: ${jsValue(v.displayName || name)}, configSchema: SCHEMA, fetch: (ctx) => main(ctx) };`,
+    ].join('\n');
+}
+function renderTokenPlan(v) {
+    const name = v.name;
+    const schema = [
+        { key: 'endpoint', label: 'Endpoint URL', type: 'string', default: v.endpoint },
+        { key: 'listPath', label: '窗口列表字段路径', type: 'string', default: v.listPath },
+        { key: 'windowField', label: '窗口名字段', type: 'string', default: v.windowField || 'window' },
+        { key: 'pctField', label: '百分比字段', type: 'string', default: v.pctField || 'pct' },
+        { key: 'usedField', label: 'used 字段（可选）', type: 'string', default: v.usedField || '' },
+        { key: 'limitField', label: 'limit 字段（可选）', type: 'string', default: v.limitField || '' },
+        { key: 'resetAtField', label: 'resetAt 字段（可选）', type: 'string', default: v.resetAtField || '' },
+    ];
+    return [
+        `// Generated by MAFW usage template 'token-plan'`,
+        `// 参数可在 Config → Usage 插件详情表单修改（存 usage.pluginConfig），或直接编辑本文件`,
+        `const CFG = ${jsValue({ name, displayName: v.displayName || name, authMode: v.authMode || 'none', authName: v.authName || '', headerName: v.headerName || '', endpoint: v.endpoint, listPath: v.listPath || '', windowField: v.windowField || 'window', pctField: v.pctField || 'pct', usedField: v.usedField || '', limitField: v.limitField || '', resetAtField: v.resetAtField || '' })};`,
+        `const SCHEMA = ${jsValue(schema)};`,
+        pickFn(),
+        `async function main(ctx) {`,
+        ...authBlock(name),
+        '  const res = await ctx.fetch(cfg.endpoint, { headers });',
+        "  if (!res.ok) { ctx.log.warn('[' + CFG.name + '] HTTP ' + res.status); return null; }",
+        '  const data = await res.json();',
+        '  const list = pick(data, cfg.listPath);',
+        '  if (!Array.isArray(list)) return null;',
+        '  const windows = list.map((it) => {',
+        '    const w = {',
+        '      window: String(it[cfg.windowField] || "balance"),',
+        '      used: Number(cfg.usedField ? (it[cfg.usedField] || 0) : 0),',
+        '      limit: Number(cfg.limitField ? (it[cfg.limitField] || 0) : 0),',
+        '      unit: cfg.limitField ? "$" : "pct",',
+        '      pct: Math.round(Number(it[cfg.pctField] || 0)),',
+        '    };',
+        '    const resetAt = cfg.resetAtField ? it[cfg.resetAtField] : undefined;',
+        '    if (resetAt) w.resetAt = Number(resetAt);',
+        '    return w;',
+        '  });',
+        '  if (windows.length === 0) return null;',
+        `  return { name: CFG.name, type: 'token-plan', plan: CFG.displayName, windows };`,
+        '}',
+        `module.exports = { name: ${jsValue(name)}, type: 'token-plan', plan: ${jsValue(v.displayName || name)}, configSchema: SCHEMA, fetch: (ctx) => main(ctx) };`,
+    ].join('\n');
+}
+function renderClone(v, ctx) {
+    const src = ctx.readBuiltinSource(v.sourceName);
+    if (!src)
+        return { ok: false, error: `builtin plugin '${v.sourceName}' not found` };
+    const header = `// Cloned from builtin '${v.sourceName}' by MAFW — edit freely (this file overrides the builtin).\n`;
+    return { ok: true, content: header + src, name: String(v.sourceName) };
+}
+function renderBlank(v) {
+    const name = v.name;
+    return [
+        `// Created from MAFW usage template 'blank' — implement fetch(ctx) per the README in this directory.`,
+        `module.exports = {`,
+        `  name: ${jsValue(name)},`,
+        `  type: 'api',`,
+        `  plan: ${jsValue(name)},`,
+        `  // configSchema: [{ key: 'endpoint', label: 'Endpoint', type: 'string' }],`,
+        `  async fetch(ctx) {`,
+        `    return null; // return { name, type, plan, windows: [...] } or null to hide`,
+        `  },`,
+        `};`,
+    ].join('\n');
+}
+const TEMPLATES = [
+    {
+        id: 'balance-api',
+        label: '余额型 API',
+        description: '查询余额/额度（balance 窗口），填 endpoint + JSON 字段路径',
+        fields: [
+            { key: 'name', label: '插件名（providerID）', type: 'string', required: true, placeholder: 'my-gateway' },
+            { key: 'displayName', label: '显示名', type: 'string' },
+            ...AUTH_FIELDS,
+            { key: 'endpoint', label: 'Endpoint URL', type: 'string', required: true, placeholder: 'https://api.example.com/v1/balance' },
+            { key: 'usedPath', label: 'used 字段路径', type: 'string', placeholder: 'data.used' },
+            { key: 'limitPath', label: 'limit 字段路径', type: 'string', placeholder: 'data.limit' },
+            { key: 'remainingPath', label: 'remaining 字段路径', type: 'string', placeholder: 'data.remaining' },
+        ],
+        render: (v) => ({ ok: true, content: renderBalanceApi(v), name: String(v.name) }),
+    },
+    {
+        id: 'token-plan',
+        label: '套餐窗口型',
+        description: '5h/7d/month 等窗口配额，endpoint 返回窗口列表 JSON',
+        fields: [
+            { key: 'name', label: '插件名（providerID）', type: 'string', required: true, placeholder: 'my-plan' },
+            { key: 'displayName', label: '显示名', type: 'string' },
+            ...AUTH_FIELDS,
+            { key: 'endpoint', label: 'Endpoint URL', type: 'string', required: true },
+            { key: 'listPath', label: '窗口列表字段路径', type: 'string', placeholder: 'data.items', hint: '指向 JSON 数组' },
+            { key: 'windowField', label: '窗口名字段', type: 'string', placeholder: 'window' },
+            { key: 'pctField', label: '百分比字段', type: 'string', placeholder: 'pct' },
+            { key: 'usedField', label: 'used 字段（可选）', type: 'string' },
+            { key: 'limitField', label: 'limit 字段（可选）', type: 'string' },
+            { key: 'resetAtField', label: 'resetAt 字段（可选，epoch ms）', type: 'string' },
+        ],
+        render: (v) => ({ ok: true, content: renderTokenPlan(v), name: String(v.name) }),
+    },
+    {
+        id: 'local-stats',
+        label: '本地统计型',
+        description: '无外部 API——用量来自本地记账（trajectory），创建后与其他插件统一管理，可在源码里升级为余额查询',
+        fields: [
+            { key: 'name', label: '插件名（providerID，需与 opencode provider id 一致）', type: 'string', required: true },
+            { key: 'displayName', label: '显示名', type: 'string' },
+        ],
+        render: (v) => ({
+            ok: true,
+            name: String(v.name),
+            content: [
+                `// Generated by MAFW usage template 'local-stats'`,
+                `// fetch 返回 null：用量数据由 gateway 本地记账（trajectory）按同名 provider 供给。`,
+                `// 需要平台侧真实余额时，直接在 fetch 里实现查询即可升级（ctx.apiKey / ctx.fetch 可用）。`,
+                `module.exports = {`,
+                `  name: ${jsValue(v.name)},`,
+                `  type: 'local',`,
+                `  plan: ${jsValue(v.displayName || v.name)},`,
+                `  async fetch(ctx) {`,
+                `    return null;`,
+                `  },`,
+                `};`,
+            ].join('\n'),
+        }),
+    },
+    {
+        id: 'clone-builtin',
+        label: '克隆内置插件',
+        description: '拷贝一份内置适配器到用户目录（覆盖内置），可自由编辑',
+        fields: [
+            { key: 'sourceName', label: '选择内置插件', type: 'select', required: true },
+        ],
+        render: (v, ctx) => renderClone(v, ctx),
+    },
+    {
+        id: 'blank',
+        label: '空白自定义',
+        description: '空骨架，实现 fetch(ctx) 接口即可',
+        fields: [
+            { key: 'name', label: '插件名（providerID）', type: 'string', required: true },
+        ],
+        render: (v) => ({ ok: true, content: renderBlank(v), name: String(v.name) }),
+    },
+];
+exports.USAGE_TEMPLATES = TEMPLATES.map(({ id, label, description, fields }) => ({ id, label, description, fields }));
+function renderTemplate(id, values, ctx) {
+    const tpl = TEMPLATES.find(t => t.id === id);
+    if (!tpl)
+        return { ok: false, error: `unknown template '${id}'` };
+    const name = values?.name;
+    if (id !== 'clone-builtin' && (!name || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(String(name)))) {
+        return { ok: false, error: '插件名必填且只能含小写字母/数字/连字符' };
+    }
+    const missing = tpl.fields.filter(f => f.required && (values?.[f.key] === undefined || values?.[f.key] === ''));
+    if (id !== 'clone-builtin' && missing.length > 0) {
+        return { ok: false, error: `缺少必填字段: ${missing.map(f => f.label).join(', ')}` };
+    }
+    return tpl.render(values ?? {}, ctx);
+}

package/gateway/dist/usage/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });