@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/dist/reporter.js

@@ -0,0 +1,267 @@
+/**
+ * 本地落盘 + 日志轮转 (Log Rotation) + 每 3 分钟批量上报。
+ *
+ * 设计原则：
+ * - events.jsonl 是活跃的写入日志，通过 appendFile 追加。
+ * - 上报时，将其 rename 轮转为带有时间戳的文件，隔离写和读，根绝并发读写丢失数据的竞态条件。
+ * - 后台处理所有的轮转文件并上报，上报成功后通过 fs.unlink 清理文件。
+ * - 失败则保留待下次重试（因为底层 DB 依赖 INSERT IGNORE 处理重复 event_id，所以即使重试时存在部分重复上报也是安全的）。
+ * - 所有异常吞掉，绝不阻塞 agent / gateway。
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitIdentityProvider } from "./identity.ts";
+import { defaultFetch } from "./http.ts";
+const FLUSH_INTERVAL_MS = 3 * 60 * 1000;
+const BATCH_SIZE = 500;
+export class Reporter {
+    paths;
+    getConfig;
+    identityProvider;
+    fetchImpl;
+    timer;
+    /** 防止多次 flush 重入。 */
+    flushing = false;
+    constructor(opts) {
+        this.paths = opts.paths;
+        this.getConfig = opts.getConfig;
+        this.identityProvider = opts.identityProvider ?? new GitIdentityProvider();
+        this.fetchImpl = opts.fetchImpl ?? defaultFetch();
+    }
+    get isDebug() {
+        return this.getConfig().debugLogging !== false;
+    }
+    async writeFallbackLog(level, ...args) {
+        try {
+            const msg = args.map(a => (a instanceof Error) ? (a.stack || a.toString()) : (typeof a === "object" ? JSON.stringify(a) : String(a))).join(" ");
+            const ts = new Date().toISOString();
+            const logLine = `[${ts}] [${level}] [skill-logger-plugin] ${msg}\n`;
+            const logDir = path.dirname(this.paths.eventsLogPath);
+            await fs.mkdir(logDir, { recursive: true });
+            await fs.appendFile(path.join(logDir, "skill-logger.err.log"), logLine);
+            if (level === "INFO" && this.isDebug) {
+                console.log("[skill-logger-plugin/reporter]", ...args);
+            }
+            else if (level === "WARN" || level === "ERROR") {
+                console.warn("[skill-logger-plugin]", ...args);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    debug(...args) {
+        if (this.isDebug) {
+            void this.writeFallbackLog("INFO", ...args);
+        }
+    }
+    /** 追加一行事件到 events.jsonl（目录不存在自动建）。失败不抛。 */
+    async appendEvent(event) {
+        try {
+            // 防御：截断会导致 MySQL Data Truncation 宕机的超长字段
+            if (typeof event.error_message === "string" && event.error_message.length > 15000) {
+                event.error_message = event.error_message.substring(0, 15000) + "...(truncated)";
+            }
+            if (typeof event.command === "string" && event.command.length > 15000) {
+                event.command = event.command.substring(0, 15000) + "...(truncated)";
+            }
+            let line = "";
+            try {
+                line = JSON.stringify(event);
+                // 防御：防止整个 JSON 过大（如带有 base64 图片的 args）导致 Express 413 Payload Too Large
+                if (line.length > 100000) {
+                    const safeEvent = { ...event, args: { _warning: "args omitted due to excessive size" } };
+                    line = JSON.stringify(safeEvent);
+                }
+            }
+            catch {
+                return; // JSON 序列化失败直接丢弃
+            }
+            await fs.mkdir(path.dirname(this.paths.eventsLogPath), { recursive: true });
+            await fs.appendFile(this.paths.eventsLogPath, line + "\n");
+        }
+        catch (err) {
+            void this.writeFallbackLog("ERROR", "写事件日志失败", this.paths.eventsLogPath, err);
+        }
+    }
+    /** 启动 3 分钟定时上报。 */
+    startTimer() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.flush(), FLUSH_INTERVAL_MS);
+        // 不阻止进程退出
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    /** 停止定时器，并尽力做最后一次 flush。 */
+    async stopTimer() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await this.flush();
+    }
+    linesOf(content) {
+        return content.split("\n").filter((l) => l.trim().length > 0);
+    }
+    async resolveUserInfo(appKey, config) {
+        if (!config.reportBaseUrl)
+            return {};
+        try {
+            const url = config.reportBaseUrl.replace(/\/$/, "") + "/skill_user/resolve";
+            const headers = { "Content-Type": "application/json" };
+            if (config.authToken)
+                headers.Authorization = config.authToken;
+            const res = await this.fetchImpl(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ appKey }),
+            });
+            if (!res.ok) {
+                return { error_message: `resolve user info failed: HTTP ${res.status}` };
+            }
+            const data = typeof res.json === "function" ? await res.json() : {};
+            return (data.user_info || data.userInfo || data.data || {});
+        }
+        catch (err) {
+            return { error_message: `resolve user info failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    async attachUserInfo(events, config) {
+        const appKeys = [...new Set(events.map((event) => event.app_key || "").filter(Boolean))];
+        if (appKeys.length === 0)
+            return events;
+        const byAppKey = new Map();
+        await Promise.all(appKeys.map(async (appKey) => {
+            byAppKey.set(appKey, await this.resolveUserInfo(appKey, config));
+        }));
+        return events.map((event) => {
+            if (!event.app_key)
+                return event;
+            const userInfo = byAppKey.get(event.app_key);
+            if (!userInfo || Object.keys(userInfo).length === 0)
+                return event;
+            return { ...event, user_info: userInfo };
+        });
+    }
+    /**
+     * 读本地队列并分批 POST；每批成功后清理对应本地文件。
+     * 采用日志轮转（Rename）规避读写竞态条件。
+     * 未配置 reportBaseUrl → 直接返回（只落本地，不上报）。
+     */
+    async flush() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        try {
+            const config = this.getConfig();
+            if (!config.reportBaseUrl) {
+                void this.writeFallbackLog("WARN", "flush skipped: reportBaseUrl 没有配置！请检查 openclaw.json 插件配置是否正确加载。");
+                return;
+            }
+            const logDir = path.dirname(this.paths.eventsLogPath);
+            // 1. 重命名当前的活跃日志文件为时间戳格式（原子操作，解决读写冲突）
+            try {
+                await fs.access(this.paths.eventsLogPath);
+                const timestamp = Date.now();
+                const rotatedPath = path.join(logDir, `events.${timestamp}.jsonl`);
+                await fs.rename(this.paths.eventsLogPath, rotatedPath);
+                this.debug(`Rotated active log to ${path.basename(rotatedPath)}`);
+            }
+            catch {
+                // 文件不存在，跳过重命名
+            }
+            // 2. 扫描所有轮转的日志文件
+            let files = [];
+            try {
+                const dirEntries = await fs.readdir(logDir);
+                files = dirEntries
+                    .filter(f => f.startsWith("events.") && f.endsWith(".jsonl") && f !== "events.jsonl")
+                    .map(f => path.join(logDir, f));
+            }
+            catch {
+                return; // 目录不存在直接返回
+            }
+            if (files.length === 0) {
+                this.debug("No rotated log files found. flush finished.");
+                return;
+            }
+            this.debug(`Found ${files.length} rotated log files to process.`);
+            const identity = await this.identityProvider.getIdentity();
+            const url = config.reportBaseUrl.replace(/\/$/, "") + "/skill_report/batch";
+            // 3. 逐个处理文件上报
+            for (const filePath of files) {
+                try {
+                    const content = await fs.readFile(filePath, "utf-8");
+                    const lines = this.linesOf(content);
+                    if (lines.length === 0) {
+                        await fs.unlink(filePath); // 空文件直接删除
+                        continue;
+                    }
+                    let cursor = 0;
+                    let allSuccess = true;
+                    while (cursor < lines.length) {
+                        const slice = lines.slice(cursor, cursor + BATCH_SIZE);
+                        const events = [];
+                        for (const line of slice) {
+                            try {
+                                events.push(JSON.parse(line));
+                            }
+                            catch {
+                                // 跳过坏行
+                            }
+                        }
+                        if (events.length === 0) {
+                            cursor += slice.length;
+                            continue;
+                        }
+                        const eventsWithUserInfo = await this.attachUserInfo(events, config);
+                        const body = JSON.stringify({
+                            identity,
+                            ide: "openclaw",
+                            marketplace: "openclaw",
+                            events: eventsWithUserInfo,
+                        });
+                        const headers = { "Content-Type": "application/json" };
+                        if (config.authToken)
+                            headers.Authorization = config.authToken;
+                        const res = await this.fetchImpl(url, { method: "POST", headers, body });
+                        if (!res.ok) {
+                            const errBody = await res.text().catch(() => "无法读取响应体");
+                            await this.writeFallbackLog("ERROR", `批量上报失败 (文件 ${path.basename(filePath)}), HTTP`, res.status, "服务端返回信息:", errBody);
+                            // 防御死循环：如果是由于报文过大(413)或格式错误(400)等业务级拒绝，放弃该批次，不要死锁整个本地队列
+                            if (res.status === 400 || res.status === 413 || res.status === 422) {
+                                await this.writeFallbackLog("WARN", `报文被服务器永久拒绝，丢弃该批次以释放队列`);
+                                cursor += slice.length;
+                                continue;
+                            }
+                            allSuccess = false;
+                            break; // 其他网络或 500 错误：本文件终止处理，留待下轮重试
+                        }
+                        this.debug(`Successfully reported batch of ${events.length} events from ${path.basename(filePath)}`);
+                        cursor += slice.length;
+                    }
+                    // 如果该文件所有的 batch 都上报成功了，将其物理删除
+                    if (allSuccess) {
+                        await fs.unlink(filePath);
+                        this.debug(`Deleted fully processed file: ${path.basename(filePath)}`);
+                    }
+                    else {
+                        // 如果某一批次失败，文件保留。下轮 flush 会把前面成功批次的事件再报一次。
+                        // 但因为 DB 的 skill_logger_events 表 event_id 是唯一键且使用了 INSERT IGNORE，所以数据去重是绝对安全的。
+                        this.debug(`File ${path.basename(filePath)} partially failed. Keeping it for next flush.`);
+                    }
+                }
+                catch (err) {
+                    await this.writeFallbackLog("ERROR", `处理文件 ${path.basename(filePath)} 异常:`, err);
+                }
+            }
+        }
+        catch (err) {
+            await this.writeFallbackLog("ERROR", "flush 整体异常", err);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}

package/dist/reporter.test.js

@@ -0,0 +1,128 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { Reporter } from "./reporter.ts";
+const identityProvider = {
+    getIdentity: async () => ({ user_id: "", git_name: "n", git_email: "e", machine_id: "m" }),
+};
+function makeEvent(i) {
+    return { event_id: `id${i}`, event_type: "function_call", skill_name: "s", called_at: new Date().toISOString() };
+}
+let dir;
+let paths;
+beforeEach(async () => {
+    dir = path.join(os.tmpdir(), `slp-reporter-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await fs.mkdir(dir, { recursive: true });
+    paths = {
+        eventsLogPath: path.join(dir, "events.jsonl"),
+    };
+});
+afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+});
+/** 缺文件视为空，匹配轮转模型下「上报成功即删除」的形态。 */
+async function readEventsOrEmpty(p) {
+    try {
+        return await fs.readFile(p, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/** 列出已轮转、待上报的日志文件（排除活跃的 events.jsonl）。 */
+async function listRotated(d) {
+    try {
+        const entries = await fs.readdir(d);
+        return entries.filter((f) => f.startsWith("events.") && f.endsWith(".jsonl") && f !== "events.jsonl");
+    }
+    catch {
+        return [];
+    }
+}
+describe("Reporter.appendEvent", () => {
+    it("目录自动创建并追加写", async () => {
+        const r = new Reporter({ paths, getConfig: () => ({}), identityProvider });
+        await r.appendEvent(makeEvent(1));
+        await r.appendEvent(makeEvent(2));
+        const lines = (await fs.readFile(paths.eventsLogPath, "utf-8")).trim().split("\n");
+        assert.equal(lines.length, 2);
+        assert.equal(JSON.parse(lines[1]).event_id, "id2");
+    });
+});
+describe("Reporter.flush", () => {
+    it("未配置 reportBaseUrl 时不上报", async () => {
+        let called = 0;
+        const r = new Reporter({
+            paths,
+            getConfig: () => ({}),
+            identityProvider,
+            fetchImpl: async () => {
+                called++;
+                return { ok: true, status: 200 };
+            },
+        });
+        await r.appendEvent(makeEvent(1));
+        await r.flush();
+        assert.equal(called, 0);
+    });
+    it("成功上报后清理本地日志，再次 flush 不重复发", async () => {
+        const sent = [];
+        const config = { reportBaseUrl: "https://x" };
+        const r = new Reporter({
+            paths,
+            getConfig: () => config,
+            identityProvider,
+            fetchImpl: async (_url, init) => {
+                const body = JSON.parse(String(init.body));
+                sent.push(body.events.length);
+                return { ok: true, status: 200 };
+            },
+        });
+        await r.appendEvent(makeEvent(1));
+        await r.appendEvent(makeEvent(2));
+        await r.flush();
+        await r.flush(); // 无新事件
+        assert.deepEqual(sent, [2]);
+        // 轮转文件已全部上报并删除，活跃日志清空
+        assert.equal(await readEventsOrEmpty(paths.eventsLogPath), "");
+        assert.equal((await listRotated(dir)).length, 0);
+    });
+    it("保留 flush 期间新追加的事件（轮转隔离读写）", async () => {
+        let appendedDuringFlush = false;
+        const r = new Reporter({
+            paths,
+            getConfig: () => ({ reportBaseUrl: "https://x" }),
+            identityProvider,
+            fetchImpl: async () => {
+                if (!appendedDuringFlush) {
+                    appendedDuringFlush = true;
+                    await fs.appendFile(paths.eventsLogPath, JSON.stringify(makeEvent(2)) + "\n");
+                }
+                return { ok: true, status: 200 };
+            },
+        });
+        await r.appendEvent(makeEvent(1));
+        await r.flush();
+        const lines = (await readEventsOrEmpty(paths.eventsLogPath)).trim().split("\n").filter(Boolean);
+        assert.equal(lines.length, 1);
+        assert.equal(JSON.parse(lines[0]).event_id, "id2");
+    });
+    it("上报失败保留轮转文件，下轮重试成功后清空", async () => {
+        let ok = false;
+        const r = new Reporter({
+            paths,
+            getConfig: () => ({ reportBaseUrl: "https://x" }),
+            identityProvider,
+            fetchImpl: async () => ({ ok, status: ok ? 200 : 500 }),
+        });
+        await r.appendEvent(makeEvent(1));
+        await r.flush(); // 失败：轮转文件保留待重试
+        assert.equal((await listRotated(dir)).length, 1);
+        ok = true;
+        await r.flush(); // 成功：清空
+        assert.equal((await listRotated(dir)).length, 0);
+        assert.equal(await readEventsOrEmpty(paths.eventsLogPath), "");
+    });
+});

package/dist/semver.js

@@ -0,0 +1,64 @@
+/**
+ * 轻量语义化版本比较（纯函数，无依赖）。
+ *
+ * 仅用于「本地 skill 版本 vs 平台最新版本」的过期判断，不追求完整 semver 规范：
+ *  - 容忍前缀 `v`/`V`（如 `v1.2.3`）；
+ *  - 比较 `主.次.修订…` 的数值段，缺省段按 0 补齐（`1.2` == `1.2.0`）；
+ *  - 预发布/构建元数据（`-beta`、`+build`）只取核心版本比较，忽略其后缀；
+ *  - 任一侧无法解析为「点分数字」时，退化为字符串相等判断。
+ */
+/** 解析核心数字段；非「点分数字」返回 null（触发字符串回退）。 */
+function parseCore(v) {
+    const core = v.trim().replace(/^[vV]/, "").split(/[-+]/, 1)[0];
+    if (!core)
+        return null;
+    const parts = core.split(".");
+    const nums = [];
+    for (const p of parts) {
+        if (!/^\d+$/.test(p))
+            return null;
+        nums.push(Number(p));
+    }
+    return nums.length > 0 ? nums : null;
+}
+/**
+ * 比较 a 与 b：a<b 返回 -1，a>b 返回 1，相等返回 0。
+ * 两侧都能解析为点分数字时按数值逐段比较；否则退化为字符串比较。
+ */
+export function compareVersions(a, b) {
+    const na = parseCore(a);
+    const nb = parseCore(b);
+    if (na && nb) {
+        const len = Math.max(na.length, nb.length);
+        for (let i = 0; i < len; i++) {
+            const x = na[i] ?? 0;
+            const y = nb[i] ?? 0;
+            if (x < y)
+                return -1;
+            if (x > y)
+                return 1;
+        }
+        return 0;
+    }
+    // 字符串回退：仅区分相等/不等（不臆测大小关系）。
+    const sa = a.trim();
+    const sb = b.trim();
+    if (sa === sb)
+        return 0;
+    return sa < sb ? -1 : 1;
+}
+/**
+ * 本地版本是否「落后于」最新版本（即需要更新）。
+ *  - 两侧都是合法 semver：latest 数值更大才算过期；
+ *  - 无法数值比较时：字符串不相等即视为过期（保守，宁可多更新一次）。
+ * 任一侧为空 → 不判过期（缺版本号则不参与更新）。
+ */
+export function isOutdated(local, latest) {
+    if (!local || !latest)
+        return false;
+    const na = parseCore(local);
+    const nb = parseCore(latest);
+    if (na && nb)
+        return compareVersions(local, latest) < 0;
+    return local.trim() !== latest.trim();
+}

package/dist/semver.test.js

@@ -0,0 +1,21 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { compareVersions, isOutdated } from "./semver.ts";
+describe("compareVersions", () => {
+    it("数值逐段比较：1.10 > 1.9", () => assert.equal(compareVersions("1.10.0", "1.9.0"), 1));
+    it("缺省段按 0 补齐：1.2 == 1.2.0", () => assert.equal(compareVersions("1.2", "1.2.0"), 0));
+    it("容忍 v 前缀", () => assert.equal(compareVersions("v2.0.0", "2.0.0"), 0));
+    it("a < b", () => assert.equal(compareVersions("1.0.0", "1.0.1"), -1));
+    it("忽略预发布后缀（核心相等）", () => assert.equal(compareVersions("1.0.0-beta", "1.0.0"), 0));
+    it("非数字版本退化为字符串比较", () => assert.equal(compareVersions("abc", "abc"), 0));
+});
+describe("isOutdated", () => {
+    it("本地落后 → true", () => assert.equal(isOutdated("1.0.0", "1.1.0"), true));
+    it("本地更新 → false", () => assert.equal(isOutdated("2.0.0", "1.9.0"), false));
+    it("相等 → false", () => assert.equal(isOutdated("1.2.3", "1.2.3"), false));
+    it("1.9 vs 1.10：应判过期（数值语义）", () => assert.equal(isOutdated("1.9.0", "1.10.0"), true));
+    it("缺本地版本 → 不判过期", () => assert.equal(isOutdated(undefined, "1.0.0"), false));
+    it("缺最新版本 → 不判过期", () => assert.equal(isOutdated("1.0.0", undefined), false));
+    it("非 semver 且不同 → 过期（保守）", () => assert.equal(isOutdated("alpha", "beta"), true));
+    it("带预发布后缀核心相同 → 不过期", () => assert.equal(isOutdated("2026-01", "2026-02"), false));
+});

package/dist/skill-version.js

@@ -0,0 +1,23 @@
+/**
+ * 从 SKILL.md 文本中提取版本号（纯正则、不借助任何模型）。
+ *
+ * 兼容点：
+ *  - 键名：英文 `version` / `Version`（大小写不敏感）、中文 `版本号` / `版本`；
+ *  - 冒号：半角 `:` 或全角 `：`；
+ *  - 取值：去除包裹引号、行尾 ` # 注释`、首尾空白。
+ *
+ * 范围：在整篇 SKILL.md 内按「单独一行」匹配（frontmatter 在最前，故天然优先命中）。
+ * 因要求行首即键名（前面只允许空白），Markdown 标题 `## Version: x`（带 `#` 前缀）不会被误命中。
+ * 取不到返回 undefined（该 skill 不参与版本更新）。
+ */
+export function parseSkillVersion(content) {
+    const m = /(?:^|\r?\n)[ \t]*(?:version|版本号|版本)[ \t]*[:：][ \t]*(.+)/i.exec(content);
+    if (!m)
+        return undefined;
+    const v = m[1]
+        .replace(/\s+#.*$/, "") // 行尾注释
+        .trim()
+        .replace(/^["']|["']$/g, "") // 包裹引号
+        .trim();
+    return v || undefined;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * 全插件共享的数据类型。
+ *
+ * 设计要点：
+ * - `MatchRule` 是「判别联合」(discriminated union)：用 `type` 字段区分四种匹配策略，
+ *   TypeScript 能据此收窄到具体形状，matcher 里按 `rule.type` 分派。
+ * - 这些类型同时是「标准配置」的契约：用户平台返回的 JSON 必须符合 `SkillStandardConfig`。
+ */
+export {};