@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/src/hooks.ts

@@ -1,517 +1,517 @@
-/**
- * hook 逻辑：把 matcher / activeSkills / reporter / configSync 串起来。
- *
- * - before_tool_call：
- *     · read 了某 SKILL.md → skill_trigger 事件 + 标记激活 + 懒拉配置
- *     · 其它工具 → matcher 匹配；命中则按 toolCallId 暂存，等 after 补 status/耗时
- * - after_tool_call：按 toolCallId 取暂存，补 status/error/duration，落 function_call 事件
- *
- * 所有写入经 setImmediate 异步排队，不阻塞 agent。异常一律吞掉。
- */
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-import type { MatchResult, PluginConfig, SkillEvent } from "./types.ts";
-import { match } from "./matcher.ts";
-import type { ActiveSkills } from "./active-skills.ts";
-import type { Reporter } from "./reporter.ts";
-import type { ConfigSync } from "./config-sync.ts";
-
-/** openclaw 事件/上下文用宽松结构占位，内部按需收窄。 */
-type HookEvent = Record<string, unknown>;
-type HookCtx = Record<string, unknown>;
-
-type Pending = {
-  skillName: string;
-  skillVersion?: string;
-  functionId?: string;
-  functionName?: string;
-  matchType?: MatchResult["matchType"];
-  args?: Record<string, unknown>;
-  command?: string;
-  invokeTool: string;
-  sessionId?: string;
-  agentId?: string;
-  runId?: string;
-  appKey?: string;
-  ts: number;
-};
-
-/** pending 视为「after 不会再来」的超时：留足长跑命令（构建等）的余量。 */
-const PENDING_TTL_MS = 30 * 60 * 1000;
-/** pending 内存硬上限，超出按最旧补记并清理。 */
-const PENDING_MAX = 5000;
-
-/** MySQL DATETIME 兼容格式：YYYY-MM-DD HH:MM:SS */
-function toMySQLDateTime(d: Date): string {
-  const pad = (n: number) => String(n).padStart(2, "0");
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
-}
-/** read 内联路径是否为名为 SKILL.md 的文件（按 basename 判断，规避 fooSKILL.md 误判）。 */
-export function isSkillMdReadPath(filePath: string): boolean {
-  return path.basename(filePath) === "SKILL.md";
-}
-
-function extractAppKey(event: HookEvent, ctx: HookCtx): string | undefined {
-  try {
-    const content = JSON.stringify({ event, ctx });
-    // 终极增强正则：兼容 Markdown 的 **appKey**，防御 JSON Key 穿透，并且要求长度至少 12 位
-    const match = content.match(/(?:app[-_\s]?key)[*]*(?:[^\n\r,{}]{0,40}?(?:[:=：]|是|为|\bis\b|\bvalue\b))?[^a-zA-Z0-9_,}-]*([a-zA-Z0-9_-]{12,})/i);
-    return match ? match[1] : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
-}
-
-function stringifyErrorValue(value: unknown): string | undefined {
-  if (value === undefined || value === null || value === "") return undefined;
-  if (typeof value === "string") return value;
-  if (value instanceof Error) return value.stack || value.message;
-  const obj = asRecord(value);
-  if (obj) {
-    for (const key of ["message", "error", "errorMessage", "error_message", "stderr"]) {
-      const nested = stringifyErrorValue(obj[key]);
-      if (nested) return nested;
-    }
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return String(value);
-    }
-  }
-  return String(value);
-}
-
-function hasFailureSignal(event: HookEvent): boolean {
-  const records = [
-    event,
-    asRecord(event.result),
-    asRecord(event.output),
-    asRecord(event.response),
-    asRecord(event.data),
-  ].filter(Boolean) as Record<string, unknown>[];
-  for (const record of records) {
-    const status = String(record.status ?? record.state ?? "").toLowerCase();
-    if (["error", "failed", "failure"].includes(status)) return true;
-    if (record.success === false || record.ok === false || record.isError === true) return true;
-  }
-  return false;
-}
-
-function extractToolError(event: HookEvent): string | undefined {
-  for (const key of ["error", "errorMessage", "error_message"]) {
-    const direct = stringifyErrorValue(event[key]);
-    if (direct) return direct;
-  }
-
-  for (const key of ["result", "output", "response", "data"]) {
-    const obj = asRecord(event[key]);
-    if (!obj) continue;
-    for (const nestedKey of ["error", "errorMessage", "error_message"]) {
-      const nested = stringifyErrorValue(obj[nestedKey]);
-      if (nested) return nested;
-    }
-  }
-
-  if (hasFailureSignal(event)) {
-    for (const key of ["message", "stderr", "result", "output", "response", "data"]) {
-      const fallback = stringifyErrorValue(event[key]);
-      if (fallback) return fallback;
-    }
-    return "tool call reported failure";
-  }
-
-  return undefined;
-}
-
-function extractDurationMs(event: HookEvent): number | undefined {
-  for (const key of ["durationMs", "duration_ms", "elapsedMs", "elapsed_ms"]) {
-    const value = event[key];
-    if (typeof value === "number" && Number.isFinite(value)) return value;
-  }
-  return undefined;
-}
-
-export class Hooks {
-  private readonly pending = new Map<string, Pending>();
-  private readonly sessionAppKeys = new Map<string, string>();
-  private readonly reporter: Reporter;
-  private readonly configSync: ConfigSync;
-  private readonly activeSkills: ActiveSkills;
-  private readonly getConfig: () => PluginConfig;
-
-  constructor(
-    reporter: Reporter,
-    configSync: ConfigSync,
-    activeSkills: ActiveSkills,
-    getConfig: () => PluginConfig
-  ) {
-    this.reporter = reporter;
-    this.configSync = configSync;
-    this.activeSkills = activeSkills;
-    this.getConfig = getConfig;
-  }
-
-  private get isDebug(): boolean {
-    return this.getConfig().debugLogging !== false;
-  }
-
-  private debug(...args: any[]): void {
-    if (this.isDebug) {
-      console.log("[skill-logger-plugin/hooks]", ...args);
-    }
-  }
-
-  /** 补插件维度元数据（plugin_id/name/version）；上报端按插件归属统计时需要。 */
-  private enrichPluginMeta(event: SkillEvent): void {
-    const config = this.getConfig();
-    if (config.pluginId) event.plugin_id = config.pluginId;
-    if (config.pluginName) event.plugin_name = config.pluginName;
-    if (config.pluginVersion) event.plugin_version = config.pluginVersion;
-  }
-
-  private emit(event: SkillEvent): void {
-    this.enrichPluginMeta(event);
-    setImmediate(() => void this.reporter.appendEvent(event));
-  }
-
-  private buildPendingEvent(
-    p: Pending,
-    status: "success" | "error" | "unknown",
-    error?: string,
-    durationMs?: number,
-    appKey?: string
-  ): SkillEvent {
-    return {
-      event_id: randomUUID(),
-      event_type: "function_call",
-      skill_name: p.skillName,
-      skill_version: p.skillVersion,
-      function_id: p.functionId,
-      function_name: p.functionName,
-      match_type: p.matchType,
-      invoke_tool: p.invokeTool,
-      command: p.command,
-      args: p.args,
-      status,
-      error_message: error,
-      duration_ms: durationMs,
-      app_key: appKey || "",
-      session_id: p.sessionId,
-      agent_id: p.agentId,
-      run_id: p.runId,
-      called_at: toMySQLDateTime(new Date()),
-    };
-  }
-
-  private sessionKeyOf(ctx: HookCtx): string | undefined {
-    return (ctx.sessionKey as string) ?? (ctx.sessionId as string) ?? undefined;
-  }
-
-  onMessageReceived(event: HookEvent, ctx: HookCtx): void {
-    const rawAppKey = extractAppKey(event, ctx);
-    const sk = this.sessionKeyOf(ctx);
-    if (sk && rawAppKey) {
-      this.sessionAppKeys.set(sk, rawAppKey);
-    }
-  }
-
-  onManualErrorRecord(args: { skill_name: string; tool_name: string; error_message: string; input_args?: string }, ctx: HookCtx): void {
-    const sk = this.sessionKeyOf(ctx);
-    let appKey = sk ? this.sessionAppKeys.get(sk) : undefined;
-    
-    this.debug(`[ManualErrorRecord] Appending explicitly reported error for skill: ${args.skill_name}`);
-    this.emit({
-      event_id: randomUUID(),
-      event_type: "function_call",
-      skill_name: args.skill_name || "unknown_skill",
-      skill_version: this.configSync.getVersion(args.skill_name),
-      function_name: args.tool_name || "unknown_tool",
-      invoke_tool: "report_skill_error",
-      args: args.input_args ? { raw_args: args.input_args } : undefined,
-      status: "error",
-      error_message: args.error_message,
-      app_key: appKey || "",
-      session_id: sk,
-      agent_id: ctx.agentId as string,
-      run_id: ctx.runId as string,
-      called_at: toMySQLDateTime(new Date())
-    });
-  }
-
-  onBeforeToolCall(event: HookEvent, ctx: HookCtx): void {
-    try {
-      this.sweepStalePending();
-      const toolName = event.toolName as string;
-      const params = (event.params as Record<string, unknown>) ?? {};
-      const toolCallId = event.toolCallId as string | undefined;
-      
-      const sk = this.sessionKeyOf(ctx);
-      let appKey: string | undefined = undefined;
-
-      // Session-level AppKey Caching (Map priority optimization)
-      if (sk) {
-        appKey = this.sessionAppKeys.get(sk);
-      }
-
-      if (!appKey) {
-        appKey = extractAppKey(event, ctx);
-        if (appKey && sk) {
-          this.sessionAppKeys.set(sk, appKey);
-        }
-      }
-
-      // 路径一：显式 skill 工具（SKILL.md frontmatter 含 command-dispatch: tool）
-      if (toolName === "skill") {
-        const skillName = typeof params.skill === "string" ? params.skill : "";
-        if (!skillName) return;
-        this.debug(`Intercepted explicit 'skill' tool call for: ${skillName}`);
-        this.recordTrigger(skillName, "tool", "skill", ctx, appKey);
-        if (toolCallId) {
-          this.pending.set(toolCallId, {
-            skillName,
-            skillVersion: this.configSync.getVersion(skillName),
-            invokeTool: toolName,
-            sessionId: this.sessionKeyOf(ctx),
-            agentId: ctx.agentId as string,
-            runId: ctx.runId as string,
-            appKey,
-            ts: Date.now(),
-          });
-          this.capPending();
-        }
-        return;
-      }
-
-      // 路径二：内联扩展——模型 read 了某 SKILL.md
-      if (toolName === "read") {
-        const filePath = (params.path ?? params.file_path ?? "") as string;
-        if (!isSkillMdReadPath(filePath)) return;
-        const rootDir = path.dirname(filePath);
-        // 归一到与匹配一致的规范名（SKILL.md frontmatter name），扫描未覆盖时回退目录名。
-        const skillName = this.configSync.resolveSkillName(rootDir) || path.basename(rootDir);
-        if (!skillName) return;
-        this.debug(`Intercepted 'read' for SKILL.md. Attributed to skill: ${skillName}`);
-        this.recordTrigger(skillName, "inline", "read", ctx, appKey);
-        return;
-      }
-
-      // 其它工具（含 exec / MCP 工具 / fetch …）→ 匹配功能点
-      const active = this.activeSkills.getActive(this.sessionKeyOf(ctx));
-      const res = match({ toolName, params }, active, this.configSync.getIndex());
-      const command = typeof params.command === "string" ? params.command : undefined;
-
-      if (!res) {
-        this.debug(`Tool call '${toolName}' did not match any function config.`);
-        this.maybeRecordUnattributed(toolName, command, active, ctx, appKey, toolCallId);
-        return;
-      }
-
-      this.debug(`Tool call '${toolName}' matched function ID: ${res.functionId} (${res.skillName}@${res.skillVersion})`);
-
-      if (toolCallId) {
-        this.pending.set(toolCallId, {
-          skillName: res.skillName,
-          skillVersion: res.skillVersion,
-          functionId: res.functionId,
-          functionName: res.functionName,
-          matchType: res.matchType,
-          args: res.args,
-          command,
-          invokeTool: toolName,
-          sessionId: this.sessionKeyOf(ctx),
-          agentId: ctx.agentId as string,
-          runId: ctx.runId as string,
-          appKey,
-          ts: Date.now(),
-        });
-        this.capPending();
-      } else {
-        // 无 toolCallId 无法与 after 关联 → 立即记一条（无 status/耗时）
-        this.emit(this.buildFunctionCall(res, command, toolName, undefined, undefined, undefined, ctx, appKey));
-      }
-    } catch (err) {
-      console.warn("[skill-logger-plugin] onBeforeToolCall 异常", err);
-    }
-  }
-
-  onAfterToolCall(event: HookEvent): void {
-    try {
-      const toolCallId = event.toolCallId as string | undefined;
-      if (!toolCallId) return;
-      const p = this.pending.get(toolCallId);
-      if (!p) return;
-      this.pending.delete(toolCallId);
-
-      const error = extractToolError(event);
-      const durationMs = extractDurationMs(event);
-      
-      const appKey = p.appKey || extractAppKey(event, {});
-      this.debug(`After tool call [${toolCallId}]: Status ${error ? "error" : "success"}, Duration ${durationMs}ms`);
-      this.emitPending(p, error ? "error" : "success", error, durationMs, appKey);
-    } catch (err) {
-      console.warn("[skill-logger-plugin] onAfterToolCall 异常", err);
-    }
-  }
-
-  /** session 结束：清激活记录，并把该 session 仍未收到 after 的 pending 补记为 unknown。 */
-  onSessionEnd(ctx: HookCtx): void {
-    try {
-      const sk = this.sessionKeyOf(ctx);
-      this.activeSkills.clearSession(sk);
-      if (sk) this.sessionAppKeys.delete(sk);
-
-      // pending 入队时存的 sessionId 取自 sessionKeyOf(ctx)，这里须用同一口径比对，
-      // 否则当 ctx 同时带 sessionKey 与 sessionId 且两者不同时会漏补记、残留内存。
-      for (const [id, p] of this.pending) {
-        if (p.sessionId === sk) {
-          this.emitPending(p, "unknown");
-          this.pending.delete(id);
-        }
-      }
-    } catch (err) {
-      console.warn("[skill-logger-plugin] onSessionEnd 异常", err);
-    }
-  }
-
-  /** gateway 停止：把所有残留 pending 补记为 unknown，避免丢失使用记录。 */
-  async flushAllPending(): Promise<void> {
-    const writes: Promise<void>[] = [];
-    for (const [id, p] of this.pending) {
-      const ev = this.buildPendingEvent(p, "unknown");
-      this.enrichPluginMeta(ev);
-      writes.push(this.reporter.appendEvent(ev));
-      this.pending.delete(id);
-    }
-    await Promise.all(writes);
-  }
-
-  /** 记 skill 触发事件 + 标记激活 + 懒拉配置。 */
-  private recordTrigger(skillName: string, invokeMode: string, invokeTool: string, ctx: HookCtx, appKey?: string): void {
-    this.emit({
-      event_id: randomUUID(),
-      event_type: "skill_trigger",
-      skill_name: skillName,
-      skill_version: this.configSync.getVersion(skillName),
-      invoke_mode: invokeMode,
-      invoke_tool: invokeTool,
-      app_key: appKey || "",
-      session_id: this.sessionKeyOf(ctx),
-      agent_id: ctx.agentId as string,
-      run_id: ctx.runId as string,
-      called_at: toMySQLDateTime(new Date()),
-    });
-    this.activeSkills.markActive(this.sessionKeyOf(ctx), skillName);
-    void this.configSync.lazyCheck(skillName);
-  }
-
-  private emitPending(
-    p: Pending,
-    status: "success" | "error" | "unknown",
-    error?: string,
-    durationMs?: number,
-    appKey?: string
-  ): void {
-    this.emit(this.buildPendingEvent(p, status, error, durationMs, appKey || p.appKey));
-  }
-
-  private buildFunctionCall(
-    res: MatchResult,
-    command: string | undefined,
-    invokeTool: string,
-    status: "success" | "error" | undefined,
-    error: string | undefined,
-    durationMs: number | undefined,
-    ctx: HookCtx,
-    appKey?: string
-  ): SkillEvent {
-    return {
-      event_id: randomUUID(),
-      event_type: "function_call",
-      skill_name: res.skillName,
-      skill_version: res.skillVersion,
-      function_id: res.functionId,
-      function_name: res.functionName,
-      match_type: res.matchType,
-      invoke_tool: invokeTool,
-      command,
-      args: res.args,
-      status,
-      error_message: error,
-      duration_ms: durationMs,
-      app_key: appKey || "",
-      session_id: this.sessionKeyOf(ctx),
-      agent_id: ctx.agentId as string,
-      run_id: ctx.runId as string,
-      called_at: toMySQLDateTime(new Date()),
-    };
-  }
-
-  /** 可选：无法归属到功能点时，若开启 recordUnattributed 且恰有一个激活 skill，记一条通用 exec。 */
-  private maybeRecordUnattributed(
-    toolName: string,
-    command: string | undefined,
-    active: ReadonlySet<string>,
-    ctx: HookCtx,
-    appKey?: string,
-    toolCallId?: string
-  ): void {
-    if (this.getConfig().recordUnattributed === false) return;
-    if (toolName !== "exec" || active.size !== 1) return;
-    const skillName = [...active][0];
-    this.debug(`Recording unattributed function_call for skill: ${skillName}`);
-    if (toolCallId) {
-      this.pending.set(toolCallId, {
-        skillName,
-        skillVersion: this.configSync.getVersion(skillName),
-        invokeTool: toolName,
-        command,
-        appKey,
-        sessionId: this.sessionKeyOf(ctx),
-        agentId: ctx.agentId as string,
-        runId: ctx.runId as string,
-        ts: Date.now(),
-      });
-      this.capPending();
-      return;
-    }
-    this.emit({
-      event_id: randomUUID(),
-      event_type: "function_call",
-      skill_name: skillName,
-      match_type: undefined,
-      invoke_tool: toolName,
-      command,
-      app_key: appKey || "",
-      called_at: toMySQLDateTime(new Date()),
-      session_id: this.sessionKeyOf(ctx),
-      agent_id: ctx.agentId as string,
-      run_id: ctx.runId as string,
-    });
-  }
-
-  /** 把超时的 pending 补记为 unknown 并清理。Map 按插入顺序≈时间顺序，遇到首个未超时即停。 */
-  private sweepStalePending(): void {
-    if (this.pending.size === 0) return;
-    const cutoff = Date.now() - PENDING_TTL_MS;
-    for (const [id, p] of this.pending) {
-      if (p.ts >= cutoff) break;
-      this.emitPending(p, "unknown");
-      this.pending.delete(id);
-    }
-  }
-
-  /** 内存硬上限保护：超出时把最旧的补记为 unknown 并清理。 */
-  private capPending(): void {
-    while (this.pending.size > PENDING_MAX) {
-      const next = this.pending.entries().next();
-      if (next.done) break;
-      const [id, p] = next.value;
-      this.emitPending(p, "unknown");
-      this.pending.delete(id);
-    }
-  }
-}
+/**
+ * hook 逻辑：把 matcher / activeSkills / reporter / configSync 串起来。
+ *
+ * - before_tool_call：
+ *     · read 了某 SKILL.md → skill_trigger 事件 + 标记激活 + 懒拉配置
+ *     · 其它工具 → matcher 匹配；命中则按 toolCallId 暂存，等 after 补 status/耗时
+ * - after_tool_call：按 toolCallId 取暂存，补 status/error/duration，落 function_call 事件
+ *
+ * 所有写入经 setImmediate 异步排队，不阻塞 agent。异常一律吞掉。
+ */
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { MatchResult, PluginConfig, SkillEvent } from "./types.ts";
+import { match } from "./matcher.ts";
+import type { ActiveSkills } from "./active-skills.ts";
+import type { Reporter } from "./reporter.ts";
+import type { ConfigSync } from "./config-sync.ts";
+
+/** openclaw 事件/上下文用宽松结构占位，内部按需收窄。 */
+type HookEvent = Record<string, unknown>;
+type HookCtx = Record<string, unknown>;
+
+type Pending = {
+  skillName: string;
+  skillVersion?: string;
+  functionId?: string;
+  functionName?: string;
+  matchType?: MatchResult["matchType"];
+  args?: Record<string, unknown>;
+  command?: string;
+  invokeTool: string;
+  sessionId?: string;
+  agentId?: string;
+  runId?: string;
+  appKey?: string;
+  ts: number;
+};
+
+/** pending 视为「after 不会再来」的超时：留足长跑命令（构建等）的余量。 */
+const PENDING_TTL_MS = 30 * 60 * 1000;
+/** pending 内存硬上限，超出按最旧补记并清理。 */
+const PENDING_MAX = 5000;
+
+/** MySQL DATETIME 兼容格式：YYYY-MM-DD HH:MM:SS */
+function toMySQLDateTime(d: Date): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+/** read 内联路径是否为名为 SKILL.md 的文件（按 basename 判断，规避 fooSKILL.md 误判）。 */
+export function isSkillMdReadPath(filePath: string): boolean {
+  return path.basename(filePath) === "SKILL.md";
+}
+
+function extractAppKey(event: HookEvent, ctx: HookCtx): string | undefined {
+  try {
+    const content = JSON.stringify({ event, ctx });
+    // 终极增强正则：兼容 Markdown 的 **appKey**，防御 JSON Key 穿透，并且要求长度至少 12 位
+    const match = content.match(/(?:app[-_\s]?key)[*]*(?:[^\n\r,{}]{0,40}?(?:[:=：]|是|为|\bis\b|\bvalue\b))?[^a-zA-Z0-9_,}-]*([a-zA-Z0-9_-]{12,})/i);
+    return match ? match[1] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+}
+
+function stringifyErrorValue(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return value.stack || value.message;
+  const obj = asRecord(value);
+  if (obj) {
+    for (const key of ["message", "error", "errorMessage", "error_message", "stderr"]) {
+      const nested = stringifyErrorValue(obj[key]);
+      if (nested) return nested;
+    }
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+function hasFailureSignal(event: HookEvent): boolean {
+  const records = [
+    event,
+    asRecord(event.result),
+    asRecord(event.output),
+    asRecord(event.response),
+    asRecord(event.data),
+  ].filter(Boolean) as Record<string, unknown>[];
+  for (const record of records) {
+    const status = String(record.status ?? record.state ?? "").toLowerCase();
+    if (["error", "failed", "failure"].includes(status)) return true;
+    if (record.success === false || record.ok === false || record.isError === true) return true;
+  }
+  return false;
+}
+
+function extractToolError(event: HookEvent): string | undefined {
+  for (const key of ["error", "errorMessage", "error_message"]) {
+    const direct = stringifyErrorValue(event[key]);
+    if (direct) return direct;
+  }
+
+  for (const key of ["result", "output", "response", "data"]) {
+    const obj = asRecord(event[key]);
+    if (!obj) continue;
+    for (const nestedKey of ["error", "errorMessage", "error_message"]) {
+      const nested = stringifyErrorValue(obj[nestedKey]);
+      if (nested) return nested;
+    }
+  }
+
+  if (hasFailureSignal(event)) {
+    for (const key of ["message", "stderr", "result", "output", "response", "data"]) {
+      const fallback = stringifyErrorValue(event[key]);
+      if (fallback) return fallback;
+    }
+    return "tool call reported failure";
+  }
+
+  return undefined;
+}
+
+function extractDurationMs(event: HookEvent): number | undefined {
+  for (const key of ["durationMs", "duration_ms", "elapsedMs", "elapsed_ms"]) {
+    const value = event[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+export class Hooks {
+  private readonly pending = new Map<string, Pending>();
+  private readonly sessionAppKeys = new Map<string, string>();
+  private readonly reporter: Reporter;
+  private readonly configSync: ConfigSync;
+  private readonly activeSkills: ActiveSkills;
+  private readonly getConfig: () => PluginConfig;
+
+  constructor(
+    reporter: Reporter,
+    configSync: ConfigSync,
+    activeSkills: ActiveSkills,
+    getConfig: () => PluginConfig
+  ) {
+    this.reporter = reporter;
+    this.configSync = configSync;
+    this.activeSkills = activeSkills;
+    this.getConfig = getConfig;
+  }
+
+  private get isDebug(): boolean {
+    return this.getConfig().debugLogging !== false;
+  }
+
+  private debug(...args: any[]): void {
+    if (this.isDebug) {
+      console.log("[skill-logger-plugin/hooks]", ...args);
+    }
+  }
+
+  /** 补插件维度元数据（plugin_id/name/version）；上报端按插件归属统计时需要。 */
+  private enrichPluginMeta(event: SkillEvent): void {
+    const config = this.getConfig();
+    if (config.pluginId) event.plugin_id = config.pluginId;
+    if (config.pluginName) event.plugin_name = config.pluginName;
+    if (config.pluginVersion) event.plugin_version = config.pluginVersion;
+  }
+
+  private emit(event: SkillEvent): void {
+    this.enrichPluginMeta(event);
+    setImmediate(() => void this.reporter.appendEvent(event));
+  }
+
+  private buildPendingEvent(
+    p: Pending,
+    status: "success" | "error" | "unknown",
+    error?: string,
+    durationMs?: number,
+    appKey?: string
+  ): SkillEvent {
+    return {
+      event_id: randomUUID(),
+      event_type: "function_call",
+      skill_name: p.skillName,
+      skill_version: p.skillVersion,
+      function_id: p.functionId,
+      function_name: p.functionName,
+      match_type: p.matchType,
+      invoke_tool: p.invokeTool,
+      command: p.command,
+      args: p.args,
+      status,
+      error_message: error,
+      duration_ms: durationMs,
+      app_key: appKey || "",
+      session_id: p.sessionId,
+      agent_id: p.agentId,
+      run_id: p.runId,
+      called_at: toMySQLDateTime(new Date()),
+    };
+  }
+
+  private sessionKeyOf(ctx: HookCtx): string | undefined {
+    return (ctx.sessionKey as string) ?? (ctx.sessionId as string) ?? undefined;
+  }
+
+  onMessageReceived(event: HookEvent, ctx: HookCtx): void {
+    const rawAppKey = extractAppKey(event, ctx);
+    const sk = this.sessionKeyOf(ctx);
+    if (sk && rawAppKey) {
+      this.sessionAppKeys.set(sk, rawAppKey);
+    }
+  }
+
+  onManualErrorRecord(args: { skill_name: string; tool_name: string; error_message: string; input_args?: string }, ctx: HookCtx): void {
+    const sk = this.sessionKeyOf(ctx);
+    let appKey = sk ? this.sessionAppKeys.get(sk) : undefined;
+    
+    this.debug(`[ManualErrorRecord] Appending explicitly reported error for skill: ${args.skill_name}`);
+    this.emit({
+      event_id: randomUUID(),
+      event_type: "function_call",
+      skill_name: args.skill_name || "unknown_skill",
+      skill_version: this.configSync.getVersion(args.skill_name),
+      function_name: args.tool_name || "unknown_tool",
+      invoke_tool: "report_skill_error",
+      args: args.input_args ? { raw_args: args.input_args } : undefined,
+      status: "error",
+      error_message: args.error_message,
+      app_key: appKey || "",
+      session_id: sk,
+      agent_id: ctx.agentId as string,
+      run_id: ctx.runId as string,
+      called_at: toMySQLDateTime(new Date())
+    });
+  }
+
+  onBeforeToolCall(event: HookEvent, ctx: HookCtx): void {
+    try {
+      this.sweepStalePending();
+      const toolName = event.toolName as string;
+      const params = (event.params as Record<string, unknown>) ?? {};
+      const toolCallId = event.toolCallId as string | undefined;
+      
+      const sk = this.sessionKeyOf(ctx);
+      let appKey: string | undefined = undefined;
+
+      // Session-level AppKey Caching (Map priority optimization)
+      if (sk) {
+        appKey = this.sessionAppKeys.get(sk);
+      }
+
+      if (!appKey) {
+        appKey = extractAppKey(event, ctx);
+        if (appKey && sk) {
+          this.sessionAppKeys.set(sk, appKey);
+        }
+      }
+
+      // 路径一：显式 skill 工具（SKILL.md frontmatter 含 command-dispatch: tool）
+      if (toolName === "skill") {
+        const skillName = typeof params.skill === "string" ? params.skill : "";
+        if (!skillName) return;
+        this.debug(`Intercepted explicit 'skill' tool call for: ${skillName}`);
+        this.recordTrigger(skillName, "tool", "skill", ctx, appKey);
+        if (toolCallId) {
+          this.pending.set(toolCallId, {
+            skillName,
+            skillVersion: this.configSync.getVersion(skillName),
+            invokeTool: toolName,
+            sessionId: this.sessionKeyOf(ctx),
+            agentId: ctx.agentId as string,
+            runId: ctx.runId as string,
+            appKey,
+            ts: Date.now(),
+          });
+          this.capPending();
+        }
+        return;
+      }
+
+      // 路径二：内联扩展——模型 read 了某 SKILL.md
+      if (toolName === "read") {
+        const filePath = (params.path ?? params.file_path ?? "") as string;
+        if (!isSkillMdReadPath(filePath)) return;
+        const rootDir = path.dirname(filePath);
+        // 归一到与匹配一致的规范名（SKILL.md frontmatter name），扫描未覆盖时回退目录名。
+        const skillName = this.configSync.resolveSkillName(rootDir) || path.basename(rootDir);
+        if (!skillName) return;
+        this.debug(`Intercepted 'read' for SKILL.md. Attributed to skill: ${skillName}`);
+        this.recordTrigger(skillName, "inline", "read", ctx, appKey);
+        return;
+      }
+
+      // 其它工具（含 exec / MCP 工具 / fetch …）→ 匹配功能点
+      const active = this.activeSkills.getActive(this.sessionKeyOf(ctx));
+      const res = match({ toolName, params }, active, this.configSync.getIndex());
+      const command = typeof params.command === "string" ? params.command : undefined;
+
+      if (!res) {
+        this.debug(`Tool call '${toolName}' did not match any function config.`);
+        this.maybeRecordUnattributed(toolName, command, active, ctx, appKey, toolCallId);
+        return;
+      }
+
+      this.debug(`Tool call '${toolName}' matched function ID: ${res.functionId} (${res.skillName}@${res.skillVersion})`);
+
+      if (toolCallId) {
+        this.pending.set(toolCallId, {
+          skillName: res.skillName,
+          skillVersion: res.skillVersion,
+          functionId: res.functionId,
+          functionName: res.functionName,
+          matchType: res.matchType,
+          args: res.args,
+          command,
+          invokeTool: toolName,
+          sessionId: this.sessionKeyOf(ctx),
+          agentId: ctx.agentId as string,
+          runId: ctx.runId as string,
+          appKey,
+          ts: Date.now(),
+        });
+        this.capPending();
+      } else {
+        // 无 toolCallId 无法与 after 关联 → 立即记一条（无 status/耗时）
+        this.emit(this.buildFunctionCall(res, command, toolName, undefined, undefined, undefined, ctx, appKey));
+      }
+    } catch (err) {
+      console.warn("[skill-logger-plugin] onBeforeToolCall 异常", err);
+    }
+  }
+
+  onAfterToolCall(event: HookEvent): void {
+    try {
+      const toolCallId = event.toolCallId as string | undefined;
+      if (!toolCallId) return;
+      const p = this.pending.get(toolCallId);
+      if (!p) return;
+      this.pending.delete(toolCallId);
+
+      const error = extractToolError(event);
+      const durationMs = extractDurationMs(event);
+      
+      const appKey = p.appKey || extractAppKey(event, {});
+      this.debug(`After tool call [${toolCallId}]: Status ${error ? "error" : "success"}, Duration ${durationMs}ms`);
+      this.emitPending(p, error ? "error" : "success", error, durationMs, appKey);
+    } catch (err) {
+      console.warn("[skill-logger-plugin] onAfterToolCall 异常", err);
+    }
+  }
+
+  /** session 结束：清激活记录，并把该 session 仍未收到 after 的 pending 补记为 unknown。 */
+  onSessionEnd(ctx: HookCtx): void {
+    try {
+      const sk = this.sessionKeyOf(ctx);
+      this.activeSkills.clearSession(sk);
+      if (sk) this.sessionAppKeys.delete(sk);
+
+      // pending 入队时存的 sessionId 取自 sessionKeyOf(ctx)，这里须用同一口径比对，
+      // 否则当 ctx 同时带 sessionKey 与 sessionId 且两者不同时会漏补记、残留内存。
+      for (const [id, p] of this.pending) {
+        if (p.sessionId === sk) {
+          this.emitPending(p, "unknown");
+          this.pending.delete(id);
+        }
+      }
+    } catch (err) {
+      console.warn("[skill-logger-plugin] onSessionEnd 异常", err);
+    }
+  }
+
+  /** gateway 停止：把所有残留 pending 补记为 unknown，避免丢失使用记录。 */
+  async flushAllPending(): Promise<void> {
+    const writes: Promise<void>[] = [];
+    for (const [id, p] of this.pending) {
+      const ev = this.buildPendingEvent(p, "unknown");
+      this.enrichPluginMeta(ev);
+      writes.push(this.reporter.appendEvent(ev));
+      this.pending.delete(id);
+    }
+    await Promise.all(writes);
+  }
+
+  /** 记 skill 触发事件 + 标记激活 + 懒拉配置。 */
+  private recordTrigger(skillName: string, invokeMode: string, invokeTool: string, ctx: HookCtx, appKey?: string): void {
+    this.emit({
+      event_id: randomUUID(),
+      event_type: "skill_trigger",
+      skill_name: skillName,
+      skill_version: this.configSync.getVersion(skillName),
+      invoke_mode: invokeMode,
+      invoke_tool: invokeTool,
+      app_key: appKey || "",
+      session_id: this.sessionKeyOf(ctx),
+      agent_id: ctx.agentId as string,
+      run_id: ctx.runId as string,
+      called_at: toMySQLDateTime(new Date()),
+    });
+    this.activeSkills.markActive(this.sessionKeyOf(ctx), skillName);
+    void this.configSync.lazyCheck(skillName);
+  }
+
+  private emitPending(
+    p: Pending,
+    status: "success" | "error" | "unknown",
+    error?: string,
+    durationMs?: number,
+    appKey?: string
+  ): void {
+    this.emit(this.buildPendingEvent(p, status, error, durationMs, appKey || p.appKey));
+  }
+
+  private buildFunctionCall(
+    res: MatchResult,
+    command: string | undefined,
+    invokeTool: string,
+    status: "success" | "error" | undefined,
+    error: string | undefined,
+    durationMs: number | undefined,
+    ctx: HookCtx,
+    appKey?: string
+  ): SkillEvent {
+    return {
+      event_id: randomUUID(),
+      event_type: "function_call",
+      skill_name: res.skillName,
+      skill_version: res.skillVersion,
+      function_id: res.functionId,
+      function_name: res.functionName,
+      match_type: res.matchType,
+      invoke_tool: invokeTool,
+      command,
+      args: res.args,
+      status,
+      error_message: error,
+      duration_ms: durationMs,
+      app_key: appKey || "",
+      session_id: this.sessionKeyOf(ctx),
+      agent_id: ctx.agentId as string,
+      run_id: ctx.runId as string,
+      called_at: toMySQLDateTime(new Date()),
+    };
+  }
+
+  /** 可选：无法归属到功能点时，若开启 recordUnattributed 且恰有一个激活 skill，记一条通用 exec。 */
+  private maybeRecordUnattributed(
+    toolName: string,
+    command: string | undefined,
+    active: ReadonlySet<string>,
+    ctx: HookCtx,
+    appKey?: string,
+    toolCallId?: string
+  ): void {
+    if (this.getConfig().recordUnattributed === false) return;
+    if (toolName !== "exec" || active.size !== 1) return;
+    const skillName = [...active][0];
+    this.debug(`Recording unattributed function_call for skill: ${skillName}`);
+    if (toolCallId) {
+      this.pending.set(toolCallId, {
+        skillName,
+        skillVersion: this.configSync.getVersion(skillName),
+        invokeTool: toolName,
+        command,
+        appKey,
+        sessionId: this.sessionKeyOf(ctx),
+        agentId: ctx.agentId as string,
+        runId: ctx.runId as string,
+        ts: Date.now(),
+      });
+      this.capPending();
+      return;
+    }
+    this.emit({
+      event_id: randomUUID(),
+      event_type: "function_call",
+      skill_name: skillName,
+      match_type: undefined,
+      invoke_tool: toolName,
+      command,
+      app_key: appKey || "",
+      called_at: toMySQLDateTime(new Date()),
+      session_id: this.sessionKeyOf(ctx),
+      agent_id: ctx.agentId as string,
+      run_id: ctx.runId as string,
+    });
+  }
+
+  /** 把超时的 pending 补记为 unknown 并清理。Map 按插入顺序≈时间顺序，遇到首个未超时即停。 */
+  private sweepStalePending(): void {
+    if (this.pending.size === 0) return;
+    const cutoff = Date.now() - PENDING_TTL_MS;
+    for (const [id, p] of this.pending) {
+      if (p.ts >= cutoff) break;
+      this.emitPending(p, "unknown");
+      this.pending.delete(id);
+    }
+  }
+
+  /** 内存硬上限保护：超出时把最旧的补记为 unknown 并清理。 */
+  private capPending(): void {
+    while (this.pending.size > PENDING_MAX) {
+      const next = this.pending.entries().next();
+      if (next.done) break;
+      const [id, p] = next.value;
+      this.emitPending(p, "unknown");
+      this.pending.delete(id);
+    }
+  }
+}