@spzhongwin/skill-logger-plugin 1.0.2

package/src/reporter.ts

@@ -0,0 +1,298 @@
+/**
+ * 本地落盘 + 日志轮转 (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 type { PluginConfig, SkillEvent, UserInfoSnapshot } from "./types.ts";
+import type { PluginPaths } from "./paths.ts";
+import { GitIdentityProvider, type IdentityProvider } from "./identity.ts";
+import { defaultFetch } from "./http.ts";
+
+/** 注入 fetch 便于测试；默认用全局 fetch。 */
+type FetchLike = (url: string, init: RequestInit) => Promise<{ ok: boolean; status: number; json?: () => Promise<unknown> }>;
+
+const FLUSH_INTERVAL_MS = 3 * 60 * 1000;
+const BATCH_SIZE = 500;
+
+export type ReporterOptions = {
+  paths: Pick<PluginPaths, "eventsLogPath">;
+  /** 读取最新插件配置（上报地址/鉴权可能在 gateway_start 后才注入）。 */
+  getConfig: () => PluginConfig;
+  identityProvider?: IdentityProvider;
+  fetchImpl?: FetchLike;
+  now?: () => number;
+};
+
+export class Reporter {
+  private readonly paths: Pick<PluginPaths, "eventsLogPath">;
+  private readonly getConfig: () => PluginConfig;
+  private readonly identityProvider: IdentityProvider;
+  private readonly fetchImpl: FetchLike;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  /** 防止多次 flush 重入。 */
+  private flushing = false;
+
+  constructor(opts: ReporterOptions) {
+    this.paths = opts.paths;
+    this.getConfig = opts.getConfig;
+    this.identityProvider = opts.identityProvider ?? new GitIdentityProvider();
+    this.fetchImpl = opts.fetchImpl ?? defaultFetch();
+  }
+
+  private get isDebug(): boolean {
+    return this.getConfig().debugLogging !== false;
+  }
+
+  private async writeFallbackLog(level: "INFO" | "WARN" | "ERROR", ...args: any[]): Promise<void> {
+    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
+    }
+  }
+
+  private debug(...args: any[]): void {
+    if (this.isDebug) {
+      void this.writeFallbackLog("INFO", ...args);
+    }
+  }
+
+  /** 追加一行事件到 events.jsonl（目录不存在自动建）。失败不抛。 */
+  async appendEvent(event: SkillEvent): Promise<void> {
+    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(): void {
+    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(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    await this.flush();
+  }
+
+  private linesOf(content: string): string[] {
+    return content.split("\n").filter((l) => l.trim().length > 0);
+  }
+
+  private async resolveUserInfo(appKey: string, config: PluginConfig): Promise<UserInfoSnapshot> {
+    if (!config.reportBaseUrl) return {};
+
+    try {
+      const url = config.reportBaseUrl.replace(/\/$/, "") + "/skill_user/resolve";
+      const headers: Record<string, string> = { "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 as any).json === "function" ? await (res as any).json() : {};
+      return (data.user_info || data.userInfo || data.data || {}) as UserInfoSnapshot;
+    } catch (err) {
+      return { error_message: `resolve user info failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+
+  private async attachUserInfo(events: SkillEvent[], config: PluginConfig): Promise<SkillEvent[]> {
+    const appKeys = [...new Set(events.map((event) => event.app_key || "").filter(Boolean))];
+    if (appKeys.length === 0) return events;
+
+    const byAppKey = new Map<string, UserInfoSnapshot>();
+    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(): Promise<void> {
+    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: string[] = [];
+      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: SkillEvent[] = [];
+            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: Record<string, string> = { "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/src/sample-config.json

@@ -0,0 +1,72 @@
+{
+  "configs": [
+    {
+      "skillName": "model-usage",
+      "version": "0.0.0-stub",
+      "description": "查看各 provider 模型用量（本地静态桩）",
+      "functions": [
+        {
+          "id": "usage_current",
+          "name": "当前用量",
+          "description": "查看当前模型用量",
+          "match": {
+            "type": "script",
+            "script": "scripts/model_usage.py",
+            "argRules": [{ "flag": "--mode", "value": "current" }]
+          }
+        },
+        {
+          "id": "usage_all",
+          "name": "全部用量",
+          "description": "查看全部模型用量",
+          "match": {
+            "type": "script",
+            "script": "scripts/model_usage.py",
+            "argRules": [{ "flag": "--mode", "value": "all" }]
+          }
+        }
+      ]
+    },
+    {
+      "skillName": "openai-whisper-api",
+      "version": "0.0.0-stub",
+      "description": "Whisper 音频转写（本地静态桩）",
+      "functions": [
+        {
+          "id": "transcribe",
+          "name": "音频转写",
+          "match": { "type": "script", "script": "scripts/transcribe.sh" }
+        }
+      ]
+    },
+    {
+      "skillName": "mcporter",
+      "version": "0.0.0-stub",
+      "description": "MCP CLI 包装示例（本地静态桩）",
+      "functions": [
+        {
+          "id": "linear_list_issues",
+          "name": "列 Linear issue",
+          "match": { "type": "command", "command": "mcporter", "targetPattern": "call linear.list_issues" }
+        }
+      ]
+    },
+    {
+      "skillName": "linear-mcp",
+      "version": "0.0.0-stub",
+      "description": "MCP/SSE 工具直调 + HTTP 端点示例（本地静态桩）",
+      "functions": [
+        {
+          "id": "create_issue",
+          "name": "创建 issue（MCP工具直调）",
+          "match": { "type": "tool", "toolName": "linear_create_issue" }
+        },
+        {
+          "id": "transcribe_http",
+          "name": "转写 HTTP 端点",
+          "match": { "type": "http", "urlContains": "/v1/audio/transcriptions" }
+        }
+      ]
+    }
+  ]
+}

package/src/semver.test.ts

@@ -0,0 +1,23 @@
+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/src/semver.ts

@@ -0,0 +1,60 @@
+/**
+ * 轻量语义化版本比较（纯函数，无依赖）。
+ *
+ * 仅用于「本地 skill 版本 vs 平台最新版本」的过期判断，不追求完整 semver 规范：
+ *  - 容忍前缀 `v`/`V`（如 `v1.2.3`）；
+ *  - 比较 `主.次.修订…` 的数值段，缺省段按 0 补齐（`1.2` == `1.2.0`）；
+ *  - 预发布/构建元数据（`-beta`、`+build`）只取核心版本比较，忽略其后缀；
+ *  - 任一侧无法解析为「点分数字」时，退化为字符串相等判断。
+ */
+
+/** 解析核心数字段；非「点分数字」返回 null（触发字符串回退）。 */
+function parseCore(v: string): number[] | null {
+  const core = v.trim().replace(/^[vV]/, "").split(/[-+]/, 1)[0];
+  if (!core) return null;
+  const parts = core.split(".");
+  const nums: number[] = [];
+  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: string, b: string): -1 | 0 | 1 {
+  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: string | undefined, latest: string | undefined): boolean {
+  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/src/skill-version.ts

@@ -0,0 +1,22 @@
+/**
+ * 从 SKILL.md 文本中提取版本号（纯正则、不借助任何模型）。
+ *
+ * 兼容点：
+ *  - 键名：英文 `version` / `Version`（大小写不敏感）、中文 `版本号` / `版本`；
+ *  - 冒号：半角 `:` 或全角 `：`；
+ *  - 取值：去除包裹引号、行尾 ` # 注释`、首尾空白。
+ *
+ * 范围：在整篇 SKILL.md 内按「单独一行」匹配（frontmatter 在最前，故天然优先命中）。
+ * 因要求行首即键名（前面只允许空白），Markdown 标题 `## Version: x`（带 `#` 前缀）不会被误命中。
+ * 取不到返回 undefined（该 skill 不参与版本更新）。
+ */
+export function parseSkillVersion(content: string): string | undefined {
+  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/src/types.ts

@@ -0,0 +1,198 @@
+/**
+ * 全插件共享的数据类型。
+ *
+ * 设计要点：
+ * - `MatchRule` 是「判别联合」(discriminated union)：用 `type` 字段区分四种匹配策略，
+ *   TypeScript 能据此收窄到具体形状，matcher 里按 `rule.type` 分派。
+ * - 这些类型同时是「标准配置」的契约：用户平台返回的 JSON 必须符合 `SkillStandardConfig`。
+ */
+
+/** 脚本参数规则：用于在同一脚本下按参数细分功能点，如 `--mode current`。 */
+export type ArgRule = {
+  /** 参数名，含前缀，如 `--mode`。 */
+  flag: string;
+  /** 期望值；省略表示「只要出现该 flag 即命中」。 */
+  value?: string;
+};
+
+/**
+ * 脚本调用：模型通过 `exec` 跑某个 skill 自带脚本（.py/.sh/.js 等）。
+ * 识别时忽略解释器前缀（python/node/bash/uv run/./），用脚本路径后缀匹配。
+ */
+export type ScriptMatchRule = {
+  type: "script";
+  /** 相对 skill 根目录的脚本路径，如 `scripts/model_usage.py`。 */
+  script: string;
+  /** 可选：按参数细分功能点；全部命中才算命中。 */
+  argRules?: ArgRule[];
+};
+
+/**
+ * CLI 包装调用：模型通过 `exec` 调一个包装 CLI，如 `mcporter call linear.list_issues`。
+ * `command` 是命令头，`targetPattern` 是其后用于定位功能点的子串。
+ */
+export type CommandMatchRule = {
+  type: "command";
+  /** 命令名，如 `mcporter`。 */
+  command: string;
+  /** 命令后用于识别功能点的子串，如 `call linear.list_issues`。 */
+  targetPattern: string;
+};
+
+/** 参数谓词：判断某个工具参数是否等于期望值（支持点路径取嵌套字段）。 */
+export type WherePredicate = {
+  /** 参数键，支持 `a.b.c` 点路径。 */
+  param: string;
+  /** 期望值（严格相等比较，做 String 归一）。 */
+  equals: string;
+};
+
+/**
+ * 工具直调：模型直接调用一个「非 exec」工具（典型为注册进 openclaw 的 MCP/SSE 工具）。
+ * 按 `toolName` 匹配（精确 / 前缀 / 正则三选一），可加参数谓词进一步限定。
+ */
+export type ToolMatchRule = {
+  type: "tool";
+  /** 精确工具名。 */
+  toolName?: string;
+  /** 工具名前缀（如某 MCP server 的统一前缀）。 */
+  toolNamePrefix?: string;
+  /** 工具名正则（字符串形式，matcher 内编译）。 */
+  toolNameRegex?: string;
+  /** 可选参数谓词，全部满足才命中。 */
+  where?: WherePredicate[];
+};
+
+/**
+ * HTTP/SSE 端点调用：模型 `exec` 里 curl 某端点，或 fetch 类工具带 url 参数。
+ */
+export type HttpMatchRule = {
+  type: "http";
+  /** URL 子串匹配，如 `/v1/audio/transcriptions`。 */
+  urlContains?: string;
+  /** host 子串匹配，如 `api.openai.com`。 */
+  hostContains?: string;
+};
+
+export type MatchRule =
+  | ScriptMatchRule
+  | CommandMatchRule
+  | ToolMatchRule
+  | HttpMatchRule;
+
+/** 一个 skill 内的功能点定义。 */
+export type SkillFunction = {
+  /** 功能点唯一标识（skill 内唯一）。 */
+  id: string;
+  /** 人类可读名称。 */
+  name: string;
+  /** 功能点说明（可选）。 */
+  description?: string;
+  /** 匹配规则。 */
+  match: MatchRule;
+};
+
+/** skill 的标准配置：由用户平台定义、插件拉取并缓存。 */
+export type SkillStandardConfig = {
+  skillName: string;
+  /** 本次返回的配置对应的版本（按请求里的本地版本精确匹配）。 */
+  version: string;
+  /** 平台上该 skill 的最新版本（服务端附加，用于过期检测）；缺省时回退用 version。 */
+  latestVersion?: string;
+  description?: string;
+  functions: SkillFunction[];
+};
+
+/** matcher 命中后返回的结构。 */
+export type MatchResult = {
+  skillName: string;
+  skillVersion: string;
+  functionId: string;
+  functionName: string;
+  matchType: MatchRule["type"];
+  /** 从调用里解析出的参数（脚本 flag / mcporter k=v / http query 等）。 */
+  args: Record<string, unknown>;
+};
+
+/** 观测到的一次工具调用的最小描述（matcher 输入）。 */
+export type ToolCall = {
+  toolName: string;
+  params: Record<string, unknown>;
+};
+
+/** 上报身份；做成独立类型，便于将来替换来源（user_id 等）。 */
+export type Identity = {
+  user_id: string;
+  git_name: string;
+  git_email: string;
+  machine_id: string;
+};
+
+export type UserInfoSnapshot = {
+  user_id?: string;
+  user_name?: string;
+  emp_id?: string;
+  person_id?: string;
+  corp_id?: string;
+  avatar?: string;
+  deptList?: unknown[];
+  title?: string;
+  error_message?: string;
+};
+
+/** 落盘 / 上报的事件。两类：skill 触发、功能点调用。 */
+export type SkillEvent = {
+  event_id: string;
+  event_type: "skill_trigger" | "function_call";
+  skill_name: string;
+  skill_version?: string;
+  function_id?: string;
+  function_name?: string;
+  /** 命中的匹配策略类型（function_call 时有）。 */
+  match_type?: MatchRule["type"];
+  /** 触发方式：skill_trigger 为 inline/tool；function_call 为观测到的工具名（exec/mcp 工具…）。 */
+  invoke_mode?: string;
+  /** 观测到的工具名。 */
+  invoke_tool?: string;
+  /** exec 时的原始命令行。 */
+  command?: string;
+  args?: Record<string, unknown>;
+  /** success/error 来自 after_tool_call；unknown 表示 after 未到达（被中断/阻断）而由兜底补记。 */
+  status?: "success" | "error" | "unknown";
+  error_message?: string;
+  duration_ms?: number;
+  app_key?: string;
+  user_info?: UserInfoSnapshot;
+  session_id?: string;
+  agent_id?: string;
+  run_id?: string;
+  plugin_id?: string;
+  plugin_name?: string;
+  plugin_version?: string;
+  /** ISO 8601。 */
+  called_at: string;
+};
+
+/** 插件运行期配置（来自 manifest configSchema / pluginConfig）。 */
+export type PluginConfig = {
+  /** 插件唯一ID，用于区分不同网关或业务线的插件实例。 */
+  pluginId?: string;
+  /** 插件中文描述名称。 */
+  pluginName?: string;
+  /** 插件版本号（从 package.json 中读取）。 */
+  pluginVersion?: string;
+  /** 拉取标准配置的服务地址。缺失则用本地静态桩。 */
+  platformBaseUrl?: string;
+  /** 网关长连接中心服务地址（如 wss://api.aishuo.co/gateway/ws）。若缺失，尝试从 platformBaseUrl 推导。 */
+  wsServerUrl?: string;
+  /** 批量上报的服务地址。缺失则只落本地、不上报。 */
+  reportBaseUrl?: string;
+  /** 上报鉴权头的值（如 Bearer xxx）。 */
+  authToken?: string;
+  /** 是否记录「无法自信归属到功能点」的调用（默认 true）。 */
+  recordUnattributed?: boolean;
+  /** 是否开启插件内部的调试日志输出（默认 true，方便实战联调观察过程）。 */
+  debugLogging?: boolean;
+  /** 是否开启插件专属文件日志（落盘为 skill-logger.err），用于排查 WS 连接和指令运行情况 */
+  enableFileLog?: boolean;
+};