@spzhongwin/skill-logger-plugin 1.0.2

package/dist/ws-client.js

@@ -0,0 +1,484 @@
+import WebSocket from "ws";
+import path from "path";
+import fs from "fs/promises";
+import { openclawHome } from "./paths.ts";
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_ACK_TIMEOUT_MS = 75_000;
+const AGENT_SCAN_INTERVAL_MS = 3 * 60 * 1000;
+export class GatewayWsClient {
+    ws = null;
+    options;
+    reconnectTimer = null;
+    agentScanTimer = null;
+    pingTimer = null;
+    connectTimeoutTimer = null;
+    lastServerAckAt = 0;
+    reconnectAttempts = 0;
+    isDestroyed = false;
+    // 本地缓存的 agent ID 列表
+    currentAgentIds = new Set();
+    appendLogToFile(level, category, message, payload) {
+        if (!this.options.enableFileLog)
+            return;
+        try {
+            const ts = new Date().toISOString();
+            let logLine = `[${ts}] [${level}] [${category}] ${message}`;
+            if (payload !== undefined && payload !== null) {
+                // 如果是 Error 对象，主动提取 stack
+                if (payload instanceof Error) {
+                    logLine += `\n  Stack: ${payload.stack || payload.message}`;
+                }
+                else {
+                    logLine += ` | Data: ${typeof payload === 'object' ? JSON.stringify(payload) : payload}`;
+                }
+            }
+            logLine += '\n';
+            const logsDir = path.join(openclawHome(), "logs");
+            fs.mkdir(logsDir, { recursive: true }).then(() => {
+                const logPath = path.join(logsDir, "skill-logger.err");
+                fs.appendFile(logPath, logLine).catch(() => { });
+            }).catch(() => { });
+        }
+        catch (e) {
+            // ignore
+        }
+    }
+    constructor(options) {
+        this.options = options;
+    }
+    connect() {
+        if (this.isDestroyed)
+            return;
+        if (this.ws && (this.ws.readyState === WebSocket.OPEN ||
+            this.ws.readyState === WebSocket.CONNECTING)) {
+            this.appendLogToFile("INFO", "Connection", "Connect skipped: websocket already active", { readyState: this.ws.readyState });
+            return;
+        }
+        this.clearConnectTimeout();
+        const msgConnect = `Connecting to Central Service: ${this.options.serverUrl}`;
+        console.log(`[skill-logger-plugin][WS] ${msgConnect}`);
+        this.appendLogToFile("INFO", "Connection", msgConnect);
+        const headers = {
+            "X-Gateway-Id": this.options.gatewayId,
+        };
+        if (this.options.authToken) {
+            headers["Authorization"] = this.options.authToken;
+        }
+        try {
+            const ws = new WebSocket(this.options.serverUrl, { headers });
+            this.ws = ws;
+            this.connectTimeoutTimer = setTimeout(() => {
+                if (this.ws === ws && ws.readyState === WebSocket.CONNECTING) {
+                    this.appendLogToFile("WARN", "Connection", "Connection timed out before open; terminating socket.");
+                    ws.terminate();
+                }
+            }, 15000);
+        }
+        catch (err) {
+            console.error(`[skill-logger-plugin][WS] Sync init error:`, err);
+            this.appendLogToFile("ERROR", "Connection", "Sync initialization error", err);
+            this.scheduleReconnect();
+            return;
+        }
+        const ws = this.ws;
+        ws.on("open", async () => {
+            if (this.ws !== ws)
+                return;
+            console.log(`[skill-logger-plugin][WS] Connected successfully!`);
+            this.appendLogToFile("INFO", "Connection", "Connected successfully!");
+            this.clearConnectTimeout();
+            this.reconnectAttempts = 0;
+            this.lastServerAckAt = Date.now();
+            this.clearReconnectTimer();
+            // 首次连接，全量扫描并上报，同时进行应用层握手，确保服务端能把 DB 在线态刷新成真实状态。
+            await this.scanAndReportAgents(true);
+            this.sendGatewayHello();
+            this.startHeartbeat();
+            // 开启 3 分钟定期的自动扫码增量同步
+            if (!this.agentScanTimer) {
+                this.agentScanTimer = setInterval(() => {
+                    this.scanAndReportAgents(true);
+                }, AGENT_SCAN_INTERVAL_MS);
+            }
+        });
+        ws.on("pong", () => {
+            this.lastServerAckAt = Date.now();
+        });
+        ws.on("message", async (data) => {
+            if (this.ws !== ws)
+                return;
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg?.type === "GATEWAY_HELLO_ACK" || msg?.type === "HEARTBEAT_ACK") {
+                    this.lastServerAckAt = Date.now();
+                    this.appendLogToFile("INFO", "Heartbeat", "Server heartbeat acknowledged", { type: msg.type, connectionId: msg.connectionId });
+                    return;
+                }
+                await this.handleMessage(msg);
+            }
+            catch (err) {
+                console.error(`[skill-logger-plugin][WS] Failed to parse/handle message:`, err);
+            }
+        });
+        ws.on("close", () => {
+            console.warn(`[skill-logger-plugin][WS] Connection closed.`);
+            this.appendLogToFile("WARN", "Connection", "Connection closed. Starting reconnect timer.");
+            if (this.ws === ws) {
+                this.ws = null;
+                this.clearConnectTimeout();
+                this.clearAgentScanTimer();
+                this.clearHeartbeat();
+                this.scheduleReconnect();
+            }
+        });
+        ws.on("error", (err) => {
+            console.error(`[skill-logger-plugin][WS] Connection error:`, err);
+            this.appendLogToFile("ERROR", "Connection", "Connection error", err);
+            if (this.ws === ws) {
+                ws.close(); // 触发 close 事件进行重连
+            }
+        });
+    }
+    /**
+     * 扫描 OpenClaw 根目录下的 workspace-assistant-{userId} 目录
+     */
+    async scanAndReportAgents(isInitialReport) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            const rootPath = openclawHome();
+            let entries = [];
+            try {
+                entries = await fs.readdir(rootPath);
+            }
+            catch (e) {
+                this.currentAgentIds = new Set();
+                this.appendLogToFile("WARN", "AgentScan", "OpenClaw home is not readable; reporting empty agent list", e);
+                this.sendAgentListReport("AGENT_LIST_REPORT");
+                return;
+            }
+            const newAgentIds = new Set();
+            for (const entry of entries) {
+                if (entry.startsWith("workspace-assistant-")) {
+                    const suffix = entry.replace("workspace-assistant-", "").trim();
+                    if (suffix && suffix === path.basename(suffix) && !suffix.startsWith(".")) {
+                        newAgentIds.add(`assistant-${suffix}`);
+                    }
+                }
+            }
+            let changed = false;
+            if (newAgentIds.size !== this.currentAgentIds.size) {
+                changed = true;
+            }
+            else {
+                for (const id of newAgentIds) {
+                    if (!this.currentAgentIds.has(id)) {
+                        changed = true;
+                        break;
+                    }
+                }
+            }
+            this.currentAgentIds = newAgentIds;
+            if (isInitialReport) {
+                this.appendLogToFile("INFO", "AgentScan", `Reporting full agent list`, { count: this.currentAgentIds.size, agents: Array.from(this.currentAgentIds) });
+                this.sendAgentListReport("AGENT_LIST_REPORT");
+            }
+            else if (changed) {
+                this.appendLogToFile("INFO", "AgentScan", `Syncing changed agent list`, { count: this.currentAgentIds.size, agents: Array.from(this.currentAgentIds) });
+                this.sendAgentListReport("AGENT_LIST_SYNC");
+            }
+        }
+        catch (err) {
+            console.error(`[skill-logger-plugin][WS] Failed to scan agents:`, err);
+            this.appendLogToFile("ERROR", "AgentScan", `Failed to scan agents`, err);
+        }
+    }
+    startHeartbeat() {
+        this.clearHeartbeat();
+        this.pingTimer = setInterval(() => {
+            const ws = this.ws;
+            if (!ws || ws.readyState !== WebSocket.OPEN)
+                return;
+            const ackAge = Date.now() - this.lastServerAckAt;
+            if (ackAge > HEARTBEAT_ACK_TIMEOUT_MS) {
+                this.appendLogToFile("WARN", "Heartbeat", "Server heartbeat ACK timed out; terminating socket for reconnect", { ackAge });
+                ws.terminate();
+                return;
+            }
+            ws.ping();
+            this.sendClientHeartbeat();
+        }, HEARTBEAT_INTERVAL_MS);
+        this.sendClientHeartbeat();
+    }
+    clearHeartbeat() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.isDestroyed || this.reconnectTimer)
+            return;
+        // 闭环完善：引入随机 Jitter 抖动，打散服务端重启时可能引发的瞬间重连风暴
+        const jitter = Math.floor(Math.random() * 5000);
+        const baseDelay = Math.min(30000, 2000 * Math.max(1, 2 ** this.reconnectAttempts));
+        const delay = baseDelay + jitter;
+        this.reconnectAttempts += 1;
+        console.log(`[skill-logger-plugin][WS] Reconnecting in ${delay}ms...`);
+        this.appendLogToFile("INFO", "Connection", "Reconnect scheduled", { delay, attempt: this.reconnectAttempts });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    clearConnectTimeout() {
+        if (this.connectTimeoutTimer) {
+            clearTimeout(this.connectTimeoutTimer);
+            this.connectTimeoutTimer = null;
+        }
+    }
+    terminateCurrentSocket(reason, payload) {
+        const ws = this.ws;
+        if (!ws)
+            return;
+        this.appendLogToFile("WARN", "Connection", `Terminating websocket: ${reason}`, payload);
+        try {
+            ws.terminate();
+        }
+        catch (err) {
+            this.appendLogToFile("WARN", "Connection", "Terminate websocket failed", err);
+        }
+    }
+    sendJson(payload, category) {
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return false;
+        try {
+            ws.send(JSON.stringify(payload), (err) => {
+                if (!err)
+                    return;
+                this.appendLogToFile("WARN", category, "WebSocket send failed", err);
+                if (this.ws === ws) {
+                    this.terminateCurrentSocket("send_failed", { category, message: err.message });
+                }
+            });
+            return true;
+        }
+        catch (err) {
+            this.appendLogToFile("WARN", category, "WebSocket send threw", err);
+            if (this.ws === ws) {
+                this.terminateCurrentSocket("send_threw", err);
+            }
+            return false;
+        }
+    }
+    sendGatewayHello() {
+        this.sendJson({
+            type: "GATEWAY_HELLO",
+            gatewayId: this.options.gatewayId,
+            agentIds: Array.from(this.currentAgentIds),
+            clientTime: Date.now(),
+        }, "Heartbeat");
+    }
+    sendClientHeartbeat() {
+        this.sendJson({
+            type: "CLIENT_HEARTBEAT",
+            gatewayId: this.options.gatewayId,
+            agentIds: Array.from(this.currentAgentIds),
+            clientTime: Date.now(),
+        }, "Heartbeat");
+    }
+    sendAgentListReport(type) {
+        this.sendJson({
+            type,
+            gatewayId: this.options.gatewayId,
+            agentIds: Array.from(this.currentAgentIds),
+            clientTime: Date.now(),
+        }, "AgentScan");
+    }
+    clearAgentScanTimer() {
+        if (this.agentScanTimer) {
+            clearInterval(this.agentScanTimer);
+            this.agentScanTimer = null;
+        }
+    }
+    /**
+     * 核心指令分发中心：完全跳过沙盒，基于 userId 直接进行底层物理文件操作
+     */
+    async handleMessage(msg) {
+        const { action, userId, code, url, force, version, replyId } = msg;
+        this.appendLogToFile("INFO", "Command", `Received WS message`, { action, userId, code, version, replyId });
+        if (!action || !userId) {
+            this.appendLogToFile("WARN", "Command", `Message dropped: missing action or userId`, msg);
+            return;
+        }
+        // 闭环完善：强制清理 userId 和 code 字符串，防止恶意指令通过 '../' 引发宿主机目录穿越攻击
+        const safeUserId = path.basename(userId);
+        const safeCode = code ? path.basename(code) : undefined;
+        // 100% 确定性安全寻址 (去掉 userId 中可能带有的 assistant- 前缀，统一用 workspace-assistant- 拼接)
+        const pureId = safeUserId.replace(/^assistant-/, "");
+        const targetDir = path.join(openclawHome(), `workspace-assistant-${pureId}`, "skills");
+        try {
+            if (action === "INSTALL_SKILL") {
+                if (!safeCode)
+                    throw new Error("Missing code parameter");
+                console.log(`[skill-logger-plugin][WS] Executing INSTALL for user ${userId}, code: ${safeCode}`);
+                this.appendLogToFile("INFO", "Command", `INSTALL_SKILL received`, { userId, code: safeCode, version });
+                const result = await this.options.updater.manualInstall({
+                    code: safeCode, url, version, force: force !== false, targetDir
+                });
+                this.reply(replyId, { success: result.success, message: result.message, action });
+            }
+            else if (action === "UNINSTALL_SKILL") {
+                if (!safeCode)
+                    throw new Error("Missing code parameter");
+                console.log(`[skill-logger-plugin][WS] Executing UNINSTALL for user ${userId}, code: ${safeCode}`);
+                this.appendLogToFile("INFO", "Command", `UNINSTALL_SKILL received`, { userId, code: safeCode });
+                const skillPath = path.join(targetDir, safeCode);
+                await fs.rm(skillPath, { recursive: true, force: true });
+                this.reply(replyId, { success: true, message: `Skill ${safeCode} removed`, action });
+            }
+            else if (action === "LIST_SKILLS") {
+                let list = [];
+                let targetDirExists = false;
+                try {
+                    const targetStat = await fs.stat(targetDir);
+                    targetDirExists = targetStat.isDirectory();
+                }
+                catch (err) {
+                    if (err?.code !== "ENOENT")
+                        throw err;
+                }
+                if (!targetDirExists) {
+                    throw new Error(`Target skills directory does not exist: ${targetDir}`);
+                }
+                const entries = await fs.readdir(targetDir, { withFileTypes: true });
+                const dirs = entries.filter(e => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith("."));
+                for (const e of dirs) {
+                    const skillDir = path.join(targetDir, e.name);
+                    const skillMdPath = path.join(skillDir, 'SKILL.md');
+                    try {
+                        const stat = await fs.stat(skillMdPath);
+                        if (!stat.isFile())
+                            continue;
+                    }
+                    catch (err) {
+                        continue;
+                    }
+                    const metaPath = path.join(skillDir, '.meta.json');
+                    let isPlatform = false;
+                    let isBuiltIn = e.isSymbolicLink();
+                    let metaData = null;
+                    let name = e.name;
+                    let description = "";
+                    let skillVersion = "";
+                    try {
+                        const mdContent = await fs.readFile(skillMdPath, 'utf8');
+                        const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(mdContent)?.[1] ?? "";
+                        const parsedName = /(^|\n)name:\s*(.+)/.exec(fm)?.[2]?.trim();
+                        if (parsedName)
+                            name = parsedName;
+                        const parsedVersion = /(^|\n)version:\s*(.+)/i.exec(fm)?.[2]?.trim();
+                        if (parsedVersion)
+                            skillVersion = parsedVersion.replace(/^['"]|['"]$/g, '').replace(/\s+#.*$/, '');
+                        const descMatch = /(^|\n)description:\s*(?:>\s*\n\s*)?(.*?)(?=\n[a-z]+:|\n---|$)/is.exec(fm);
+                        if (descMatch && descMatch[2]) {
+                            description = descMatch[2].replace(/\n\s+/g, ' ').trim();
+                        }
+                    }
+                    catch (err) { }
+                    try {
+                        const metaContent = await fs.readFile(metaPath, 'utf8');
+                        const parsed = JSON.parse(metaContent);
+                        if (parsed) {
+                            if (parsed.ownerId === 'CMS' || parsed.ownerId === 'CMS_COMPAT')
+                                isPlatform = true;
+                            if (parsed.isBuiltIn === true || parsed.ownerId === 'built-in')
+                                isBuiltIn = true;
+                            metaData = parsed;
+                        }
+                    }
+                    catch (err) { }
+                    if (isPlatform) {
+                        list.push({
+                            code: e.name,
+                            isPlatform: true,
+                            isBuiltIn: isBuiltIn,
+                            version: metaData?.version || skillVersion,
+                            name,
+                            description,
+                            publishedAt: metaData?.publishedAt
+                        });
+                    }
+                    else {
+                        list.push({
+                            code: e.name,
+                            isPlatform: false,
+                            isBuiltIn: isBuiltIn,
+                            version: skillVersion,
+                            name: name,
+                            description: description
+                        });
+                    }
+                }
+                this.reply(replyId, { success: true, data: list, action });
+            }
+            else if (action === "UPDATE_SKILL") {
+                if (!safeCode)
+                    throw new Error("Missing code parameter");
+                // 更新可能是大批量广播，增加防阻塞的随机延时 (0~5秒)
+                const delayMs = Math.random() * 5000;
+                console.log(`[skill-logger-plugin][WS] Scheduled UPDATE for user ${userId}, code: ${safeCode} in ${Math.round(delayMs)}ms`);
+                this.appendLogToFile("INFO", "Command", `Scheduled UPDATE_SKILL`, { userId, code: safeCode, version, delayMs: Math.round(delayMs) });
+                setTimeout(async () => {
+                    try {
+                        await this.options.updater.manualInstall({
+                            code: safeCode, url, version, force: true, targetDir
+                        });
+                        // 广播更新一般无需强阻塞等待 replyId，若有需要也可以回传
+                        if (replyId) {
+                            this.reply(replyId, { success: true, message: `Skill ${safeCode} updated successfully`, action });
+                        }
+                    }
+                    catch (e) {
+                        if (replyId)
+                            this.reply(replyId, { success: false, message: e.message, action });
+                    }
+                }, delayMs);
+            }
+            else {
+                console.warn(`[skill-logger-plugin][WS] Unknown action: ${action}`);
+                this.appendLogToFile("WARN", "Command", `Unknown action: ${action}`);
+            }
+        }
+        catch (err) {
+            this.appendLogToFile("ERROR", "Command", `Error executing action ${action}`, err);
+            this.reply(replyId, { success: false, message: err.message, action });
+        }
+    }
+    reply(replyId, payload) {
+        this.appendLogToFile("INFO", "Command", `Replying to command`, { replyId, payload });
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !replyId) {
+            this.appendLogToFile("WARN", "Command", `Cannot reply: WS closed or missing replyId`, { replyId });
+            return;
+        }
+        this.ws.send(JSON.stringify({ type: "REPLY", replyId, ...payload }));
+    }
+    destroy() {
+        this.isDestroyed = true;
+        this.clearReconnectTimer();
+        this.clearAgentScanTimer();
+        this.clearHeartbeat();
+        this.clearConnectTimeout();
+        if (this.ws) {
+            this.ws.terminate(); // 强行销毁，斩断半开连接残留
+            this.ws = null;
+        }
+    }
+}

package/openclaw.plugin.json

@@ -0,0 +1,50 @@
+{
+  "id": "skill-logger-plugin",
+  "name": "Skill Logger",
+  "description": "追踪 openclaw skill 内功能点（脚本/命令/工具/HTTP）使用与报错，落本地并批量上报",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "pluginId": {
+        "type": "string",
+        "description": "自定义插件 ID"
+      },
+      "pluginName": {
+        "type": "string",
+        "description": "自定义插件名称"
+      },
+      "platformBaseUrl": {
+        "type": "string",
+        "description": "拉取 skill 标准配置的服务地址；缺省时使用内置静态桩"
+      },
+      "reportBaseUrl": {
+        "type": "string",
+        "description": "批量上报的服务地址；缺省时只落本地、不上报"
+      },
+      "authToken": {
+        "type": "string",
+        "description": "拉取/上报接口的 Authorization 头值（如 'Bearer xxx'）"
+      },
+      "recordUnattributed": {
+        "type": "boolean",
+        "description": "是否记录无法归属到具体功能点的 exec 调用（默认 true）"
+      },
+      "enableFileLog": {
+        "type": "boolean",
+        "description": "是否开启插件专属文件日志（落盘为 skill-logger.err），用于排查 WS 连接和指令运行情况"
+      },
+      "autoUpdateSkills": {
+        "type": "boolean",
+        "description": "是否开启 skill 版本自动更新（检测到本地落后于平台最新版本时下载并覆盖各 workspace 下的副本）；默认开启，仅显式设为 false 才关闭"
+      },
+      "versionCheckIntervalMinutes": {
+        "type": "number",
+        "description": "版本检查+自动更新的周期（分钟）。每隔该周期按本地所有已装 skill 向服务端拉最新版本并按需更新；默认 30。本地扫描发现固定 3 分钟，与此独立"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@spzhongwin/skill-logger-plugin",
+  "version": "1.0.2",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "scripts": {
+    "test": "node --experimental-strip-types --test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "npx esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:ws"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "contracts": {
+      "tools": ["report_skill_error"]
+    },
+    "compat": {
+      "pluginApi": ">=2026.3.28",
+      "minGatewayVersion": "2026.3.28"
+    },
+    "build": {
+      "openclawVersion": "2026.3.28",
+      "pluginSdkVersion": "2026.3.28"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.20",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "ws": "^8.21.0"
+  }
+}

package/src/active-skills.test.ts

@@ -0,0 +1,32 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ActiveSkills } from "./active-skills.ts";
+
+describe("ActiveSkills", () => {
+  it("标记并取回激活 skill", () => {
+    const a = new ActiveSkills();
+    a.markActive("s1", "skA");
+    a.markActive("s1", "skB");
+    assert.deepEqual([...a.getActive("s1")].sort(), ["skA", "skB"]);
+    assert.deepEqual([...a.getActive("s2")], []);
+  });
+
+  it("TTL 过期后不再返回", () => {
+    let t = 1000;
+    const a = new ActiveSkills({ ttlMs: 100, now: () => t });
+    a.markActive("s", "skA");
+    t = 1050;
+    assert.deepEqual([...a.getActive("s")], ["skA"]);
+    t = 2000;
+    assert.deepEqual([...a.getActive("s")], []);
+  });
+
+  it("超出 session 上限按 LRU 淘汰最旧", () => {
+    const a = new ActiveSkills({ maxSessions: 2 });
+    a.markActive("s1", "x");
+    a.markActive("s2", "x");
+    a.markActive("s3", "x"); // 淘汰 s1
+    assert.deepEqual([...a.getActive("s1")], []);
+    assert.deepEqual([...a.getActive("s3")], ["x"]);
+  });
+});

package/src/active-skills.ts

@@ -0,0 +1,77 @@
+/**
+ * 按 session 记录「已触发（激活）的 skill」，供 matcher 在通用命令（curl、共享 CLI）
+ * 出现多候选时消歧——优先归属到本 session 已激活的 skill。
+ *
+ * 内存态，带 TTL + 容量上限，防止长跑 gateway 进程里无限增长。
+ */
+
+type SkillEntry = { name: string; ts: number };
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 分钟
+const DEFAULT_MAX_SESSIONS = 500;
+
+export type ActiveSkillsOptions = {
+  ttlMs?: number;
+  maxSessions?: number;
+  /** 注入时钟，便于测试。 */
+  now?: () => number;
+};
+
+export class ActiveSkills {
+  private readonly ttlMs: number;
+  private readonly maxSessions: number;
+  private readonly now: () => number;
+  /** sessionKey -> (skillName -> entry)。用 Map 保留插入顺序以便 LRU 淘汰。 */
+  private readonly bySession = new Map<string, Map<string, SkillEntry>>();
+
+  constructor(opts: ActiveSkillsOptions = {}) {
+    this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    this.now = opts.now ?? Date.now;
+  }
+
+  /** 标记某 session 触发了某 skill。 */
+  markActive(sessionKey: string | undefined, skillName: string): void {
+    const key = sessionKey || "__nosession__";
+    let skills = this.bySession.get(key);
+    if (!skills) {
+      skills = new Map();
+      this.bySession.set(key, skills);
+    } else {
+      // 触碰即刷新 LRU 顺序
+      this.bySession.delete(key);
+      this.bySession.set(key, skills);
+    }
+    skills.set(skillName, { name: skillName, ts: this.now() });
+    this.evictIfNeeded();
+  }
+
+  /** 取某 session 当前仍在 TTL 内的已激活 skill 集合。 */
+  getActive(sessionKey: string | undefined): Set<string> {
+    const key = sessionKey || "__nosession__";
+    const skills = this.bySession.get(key);
+    const out = new Set<string>();
+    if (!skills) return out;
+    const cutoff = this.now() - this.ttlMs;
+    for (const [name, entry] of skills) {
+      if (entry.ts >= cutoff) out.add(name);
+      else skills.delete(name);
+    }
+    if (skills.size === 0) this.bySession.delete(key);
+    return out;
+  }
+
+  /** session 结束时清掉其激活记录（释放内存 + 避免跨会话误判）。 */
+  clearSession(sessionKey: string | undefined): void {
+    this.bySession.delete(sessionKey || "__nosession__");
+  }
+
+  /** 超出 session 上限时，按 LRU 淘汰最旧的 session。 */
+  private evictIfNeeded(): void {
+    while (this.bySession.size > this.maxSessions) {
+      const oldest = this.bySession.keys().next().value;
+      if (oldest === undefined) break;
+      this.bySession.delete(oldest);
+    }
+  }
+}