@spzhongwin/skill-logger-plugin 1.0.10 → 1.0.12

package/dist/active-skills.js

@@ -0,0 +1,67 @@
+/**
+ * 按 session 记录「已触发（激活）的 skill」，供 matcher 在通用命令（curl、共享 CLI）
+ * 出现多候选时消歧——优先归属到本 session 已激活的 skill。
+ *
+ * 内存态，带 TTL + 容量上限，防止长跑 gateway 进程里无限增长。
+ */
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 分钟
+const DEFAULT_MAX_SESSIONS = 500;
+export class ActiveSkills {
+    ttlMs;
+    maxSessions;
+    now;
+    /** sessionKey -> (skillName -> entry)。用 Map 保留插入顺序以便 LRU 淘汰。 */
+    bySession = new Map();
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** 标记某 session 触发了某 skill。 */
+    markActive(sessionKey, skillName) {
+        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) {
+        const key = sessionKey || "__nosession__";
+        const skills = this.bySession.get(key);
+        const out = new Set();
+        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) {
+        this.bySession.delete(sessionKey || "__nosession__");
+    }
+    /** 超出 session 上限时，按 LRU 淘汰最旧的 session。 */
+    evictIfNeeded() {
+        while (this.bySession.size > this.maxSessions) {
+            const oldest = this.bySession.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.bySession.delete(oldest);
+        }
+    }
+}

package/dist/active-skills.test.js

@@ -0,0 +1,29 @@
+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/dist/config-sync.js

@@ -0,0 +1,439 @@
+/**
+ * 智能动态拉取 skill 标准配置。
+ *
+ * - 扫描本地已装 skill（extensions 下的 SKILL.md），算签名（版本或文件 mtime/size）。
+ * - 与本地缓存的同步状态比对，找出「新增 / 签名变化」的 skill，按需拉取标准配置。
+ * - 拉取来源：配了 platformBaseUrl → POST 平台接口；否则用本地静态桩（第一步交付）。
+ * - 维护 matcher 索引：任何配置变化后重建。
+ *
+ * 触发时机：① skill_trigger 懒触发(lazyCheck) ② 3 分钟周期 reconcile ③ before_install 后 reconcile。
+ * 全部异常吞掉，绝不阻塞 hook。
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveAgentSkillDirs, openclawHome } from "./paths.ts";
+import { buildIndex, emptyIndex } from "./matcher.ts";
+import { defaultFetch } from "./http.ts";
+import { parseSkillVersion } from "./skill-version.ts";
+// 保持对外导出位置不变（历史测试从 config-sync 导入）。
+export { parseSkillVersion };
+const MAX_SCAN_DEPTH = 6;
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".cache"]);
+/** lazyCheck 扫描缓存有效期：足够吸收同一会话内的连续 skill_trigger，又不至于明显滞后真实安装变化。 */
+const SCAN_CACHE_TTL_MS = 5000;
+export class ConfigSync {
+    paths;
+    getConfig;
+    fetchImpl;
+    sampleConfigs;
+    resolveSkillDirs;
+    updater;
+    signatures = new Map();
+    configs = new Map();
+    configPool = new Map();
+    index = emptyIndex();
+    /** skill 根目录 → 规范名（SKILL.md frontmatter name）。用于把触发事件归一到与匹配一致的身份。 */
+    skillNameByDir = new Map();
+    /** 同一时刻只跑一次 reconcile，避免周期/懒触发并发。 */
+    reconciling = false;
+    /** 同一时刻只跑一次版本检查，避免周期/启动并发。 */
+    checkingVersions = false;
+    /** skill 名 → 平台最新版本（由 30 分钟版本检查刷新；缺省回退用已装配置的 version）。 */
+    latestVersions = new Map();
+    /** scanInstalledSkills 的短 TTL 缓存，仅服务 lazyCheck 的高频触发；reconcile 始终全新扫描并刷新它。 */
+    scanCache;
+    /** skill 名 → 所有安装副本（多 agent workspace 各一份）。每次扫描刷新。 */
+    installations = new Map();
+    constructor(opts) {
+        this.paths = opts.paths;
+        this.getConfig = opts.getConfig;
+        this.fetchImpl = opts.fetchImpl ?? defaultFetch();
+        this.sampleConfigs = opts.sampleConfigs;
+        // 默认：每次扫描重读 openclaw.json，动态发现新增 agent workspace（无需重启网关）。
+        this.resolveSkillDirs =
+            opts.resolveSkillDirs ?? (() => resolveAgentSkillDirs(openclawHome(), this.paths.openclawConfigPath));
+        this.updater = opts.updater;
+    }
+    get isDebug() {
+        return this.getConfig().debugLogging !== false;
+    }
+    debug(...args) {
+        if (this.isDebug) {
+            console.log("[skill-logger-plugin/config-sync]", ...args);
+        }
+    }
+    getIndex() {
+        return this.index;
+    }
+    getVersion(skillName) {
+        const cfg = this.configs.get(skillName);
+        if (cfg?.version)
+            return cfg.version;
+        const sig = this.signatures.get(skillName);
+        if (sig) {
+            const v = sig.split("|")[0];
+            return v ? v : undefined;
+        }
+        return undefined;
+    }
+    /** 把 SKILL.md 所在目录解析为规范 skill 名；未扫描到时返回 undefined（调用方回退目录名）。 */
+    resolveSkillName(rootDir) {
+        return this.skillNameByDir.get(rootDir);
+    }
+    /** 从磁盘加载已缓存的同步状态并重建索引（gateway 启动时调一次）。 */
+    async load() {
+        try {
+            const raw = await fs.readFile(this.paths.syncStatePath, "utf-8");
+            const state = JSON.parse(raw);
+            // 兼容旧版本格式
+            if (state.skills) {
+                for (const [name, entry] of Object.entries(state.skills)) {
+                    this.signatures.set(name, entry.signature);
+                    if (entry.config) {
+                        this.configs.set(name, entry.config);
+                        const cacheKey = `${name}@${entry.version || "unknown"}`;
+                        this.configPool.set(cacheKey, entry.config);
+                    }
+                }
+            }
+            // 新版本格式
+            if (state.configPool) {
+                for (const [key, cfg] of Object.entries(state.configPool)) {
+                    this.configPool.set(key, cfg);
+                }
+            }
+            if (state.active) {
+                for (const [name, entry] of Object.entries(state.active)) {
+                    this.signatures.set(name, entry.signature);
+                    const v = entry.signature.split("|")[0];
+                    const cacheKey = `${name}@${v || "unknown"}`;
+                    const cfg = this.configPool.get(cacheKey);
+                    if (cfg)
+                        this.configs.set(name, cfg);
+                }
+            }
+            this.rebuildIndex();
+        }
+        catch {
+            // 无状态文件，留空
+        }
+    }
+    /**
+     * 递归扫描 extensions 及各 agent workspace 下所有 SKILL.md，解析名称/版本/签名。
+     * 同名 skill 可能分布在多个 workspace（如 coder/coder2 各持一份副本）。缓存以 skill 名为全局 key，
+     * 故这里按名去重并取确定性的一份（按 rootDir 排序后取首个），避免 reconcile 每轮在不同副本的
+     * 签名间反复横跳、触发无意义的重复拉取与持久化抖动。skillNameByDir 仍保留全部副本目录的映射。
+     */
+    async scanInstalledSkills() {
+        const out = [];
+        const walk = async (dir, depth) => {
+            if (depth > MAX_SCAN_DEPTH)
+                return;
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                if (e.isDirectory()) {
+                    if (SKIP_DIRS.has(e.name))
+                        continue;
+                    await walk(path.join(dir, e.name), depth + 1);
+                }
+                else if (e.name === "SKILL.md") {
+                    const skillMd = path.join(dir, e.name);
+                    const skill = await this.readSkill(dir, skillMd);
+                    if (skill) {
+                        out.push(skill);
+                        this.skillNameByDir.set(skill.rootDir, skill.name);
+                    }
+                }
+            }
+        };
+        await walk(this.paths.extensionsDir, 0);
+        // 动态解析所有 agent workspace 的 skills 目录（含顶层全局 skills）：每次扫描重读 openclaw.json，
+        // 运行期新增 agent 无需重启即可被发现。不存在的目录在 walk 内已被吞掉。
+        for (const skillsDir of this.resolveSkillDirs()) {
+            await walk(skillsDir, 0);
+        }
+        out.sort((a, b) => a.rootDir.localeCompare(b.rootDir));
+        // 记录 skill → 所有安装副本（含各 workspace 下的 rootDir 与本地版本），供版本更新定位覆盖目标。
+        const installs = new Map();
+        for (const s of out) {
+            const arr = installs.get(s.name);
+            if (arr)
+                arr.push(s);
+            else
+                installs.set(s.name, [s]);
+        }
+        this.installations = installs;
+        // 按 skill 名去重，取确定性的一份（rootDir 字典序最小）。
+        const deduped = new Map();
+        for (const s of out) {
+            if (!deduped.has(s.name))
+                deduped.set(s.name, s);
+        }
+        return [...deduped.values()];
+    }
+    /** skill → 所有安装副本（多 agent workspace 各一份）。供版本更新定位需要覆盖的目录。 */
+    getInstallations() {
+        return this.installations;
+    }
+    /** lazyCheck 专用：命中短 TTL 缓存则跳过整树遍历；reconcile 不走此路径，始终全新扫描。 */
+    async scanInstalledSkillsCached() {
+        const now = Date.now();
+        if (this.scanCache && now - this.scanCache.ts < SCAN_CACHE_TTL_MS) {
+            return this.scanCache.skills;
+        }
+        const skills = await this.scanInstalledSkills();
+        this.scanCache = { ts: now, skills };
+        return skills;
+    }
+    async readSkill(rootDir, skillMdPath) {
+        try {
+            const content = await fs.readFile(skillMdPath, "utf-8");
+            const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)?.[1] ?? "";
+            const name = /(^|\n)name:\s*(.+)/.exec(fm)?.[2]?.trim() || path.basename(rootDir);
+            const version = parseSkillVersion(content);
+            const signature = await this.computeSignature(rootDir, skillMdPath, version);
+            return { name, version, rootDir, signature };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** 签名 = 版本（若有）+ SKILL.md 与 scripts/ 的 mtime/size 摘要。 */
+    async computeSignature(rootDir, skillMdPath, version) {
+        const parts = [version ?? ""];
+        try {
+            const st = await fs.stat(skillMdPath);
+            parts.push(`md:${st.mtimeMs}:${st.size}`);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            const scriptsDir = path.join(rootDir, "scripts");
+            const entries = await fs.readdir(scriptsDir, { withFileTypes: true });
+            for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (!e.isFile())
+                    continue;
+                const st = await fs.stat(path.join(scriptsDir, e.name));
+                parts.push(`s:${e.name}:${st.mtimeMs}:${st.size}`);
+            }
+        }
+        catch {
+            /* 无 scripts 目录 */
+        }
+        return parts.join("|");
+    }
+    /** 找出需要拉取（新增或签名变化）与已移除的 skill。优先命中本地 configPool。 */
+    diffAgainstState(installed) {
+        const toFetch = [];
+        const cached = [];
+        const removed = [];
+        const seen = new Set();
+        for (const s of installed) {
+            seen.add(s.name);
+            if (this.signatures.get(s.name) !== s.signature) {
+                const cacheKey = `${s.name}@${s.version || "unknown"}`;
+                if (this.configPool.has(cacheKey)) {
+                    cached.push(s);
+                }
+                else {
+                    toFetch.push(s);
+                }
+            }
+        }
+        for (const name of this.signatures.keys()) {
+            if (!seen.has(name))
+                removed.push(name);
+        }
+        return { toFetch, removed, cached };
+    }
+    /** 全量对账：扫描 → diff → 拉取 → 更新缓存 → 重建索引 → 持久化。 */
+    async reconcile() {
+        if (this.reconciling)
+            return;
+        this.reconciling = true;
+        try {
+            const installed = await this.scanInstalledSkills();
+            this.scanCache = { ts: Date.now(), skills: installed }; // 刷新 lazyCheck 缓存，保证安装后对账的新鲜度
+            this.debug(`reconcile: Found ${installed.length} installed skills.`);
+            const { toFetch, removed, cached } = this.diffAgainstState(installed);
+            if (toFetch.length === 0 && removed.length === 0 && cached.length === 0)
+                return;
+            // 命中本地池的，直接置为活跃
+            for (const s of cached) {
+                this.signatures.set(s.name, s.signature);
+                this.configs.set(s.name, this.configPool.get(`${s.name}@${s.version || "unknown"}`));
+                this.debug(`reconcile: Skill ${s.name}@${s.version} instantly loaded from local configPool.`);
+            }
+            if (toFetch.length > 0) {
+                this.debug(`reconcile: Fetching configs for ${toFetch.length} skills...`);
+                const { ok, configs } = await this.pullConfigs(toFetch.map((s) => ({ name: s.name, version: s.version })));
+                // 仅在拿到确定性结果时推进签名；拉取失败则不推进，下轮重试。
+                if (ok) {
+                    const byName = new Map(configs.map((c) => [c.skillName, c]));
+                    this.debug(`reconcile: Fetched ${configs.length} configs successfully.`);
+                    for (const s of toFetch) {
+                        const cfg = byName.get(s.name);
+                        // If the platform says this config is still being processed or reviewed,
+                        // we skip updating the signature so it will be retried in the next reconcile.
+                        if (cfg && (cfg.status === 'REVIEW_NEEDED' || cfg.status === 'EXTRACTING')) {
+                            this.debug(`reconcile: Skill ${s.name} is ${cfg.status}, skipping signature update.`);
+                            continue;
+                        }
+                        this.signatures.set(s.name, s.signature);
+                        if (cfg) {
+                            this.configs.set(s.name, cfg);
+                            this.configPool.set(`${s.name}@${s.version || "unknown"}`, cfg);
+                        }
+                        else {
+                            this.configs.delete(s.name); // 平台明确无此配置
+                        }
+                    }
+                }
+            }
+            for (const name of removed) {
+                this.signatures.delete(name);
+                this.configs.delete(name);
+            }
+            this.rebuildIndex();
+            await this.persist();
+        }
+        catch (err) {
+            console.warn("[skill-logger-plugin] reconcile 异常", err);
+        }
+        finally {
+            this.reconciling = false;
+        }
+    }
+    /** 懒触发：仅检查某个被触发的 skill，缺配置/签名变才拉。`ident` 可为规范名或目录名。 */
+    async lazyCheck(ident) {
+        try {
+            const find = (list) => list.find((x) => x.name === ident || path.basename(x.rootDir) === ident);
+            let s = find(await this.scanInstalledSkillsCached());
+            // 缓存里没有该 skill：可能是刚安装的新 skill，强制全新扫描兜底，行为与未加缓存前一致。
+            if (!s) {
+                const fresh = await this.scanInstalledSkills();
+                this.scanCache = { ts: Date.now(), skills: fresh };
+                s = find(fresh);
+            }
+            if (!s)
+                return;
+            if (this.signatures.get(s.name) === s.signature && this.configs.has(s.name))
+                return;
+            const cacheKey = `${s.name}@${s.version || "unknown"}`;
+            if (this.configPool.has(cacheKey)) {
+                this.debug(`lazyCheck: Skill ${s.name}@${s.version} loaded instantly from local configPool.`);
+                this.signatures.set(s.name, s.signature);
+                this.configs.set(s.name, this.configPool.get(cacheKey));
+                this.rebuildIndex();
+                await this.persist();
+                return;
+            }
+            this.debug(`lazyCheck: Fetching config for ${s.name}@${s.version}...`);
+            const { ok, configs } = await this.pullConfigs([{ name: s.name, version: s.version }]);
+            if (!ok)
+                return; // 拉取失败，保留旧状态，下轮重试
+            this.debug(`lazyCheck: Fetched ${configs.length} configs successfully.`);
+            const cfg = configs.find((c) => c.skillName === s.name);
+            if (cfg && (cfg.status === 'REVIEW_NEEDED' || cfg.status === 'EXTRACTING')) {
+                this.debug(`lazyCheck: Skill ${s.name} is ${cfg.status}, skipping signature update.`);
+                return;
+            }
+            this.signatures.set(s.name, s.signature);
+            if (cfg) {
+                this.configs.set(s.name, cfg);
+                this.configPool.set(cacheKey, cfg);
+            }
+            else {
+                this.configs.delete(s.name);
+            }
+            this.rebuildIndex();
+            await this.persist();
+        }
+        catch (err) {
+            console.warn("[skill-logger-plugin] lazyCheck 异常", err);
+        }
+    }
+    /**
+     * 拉取标准配置。配了 platformBaseUrl → POST 平台；否则用本地静态桩。
+     *
+     * 返回 `ok` 区分「确定性结果」与「拉取失败」：
+     *  - ok=true  ：拿到了平台的明确答复（configs 可能为空，表示平台对这些 skill 暂无配置）。
+     *  - ok=false ：网络/服务异常，调用方**不应**推进签名，下轮重试。
+     */
+    async pullConfigs(skillRefs) {
+        const config = this.getConfig();
+        if (config.platformBaseUrl) {
+            try {
+                const url = config.platformBaseUrl.replace(/\/$/, "") + "/skill_config/pull";
+                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({ skills: skillRefs }),
+                });
+                if (!res.ok) {
+                    console.warn("[skill-logger-plugin] 拉取标准配置失败，HTTP", res.status);
+                    return { ok: false, configs: [] };
+                }
+                const data = (await res.json());
+                return { ok: true, configs: data.configs ?? [] };
+            }
+            catch (err) {
+                console.warn("[skill-logger-plugin] 拉取标准配置异常", err);
+                return { ok: false, configs: [] };
+            }
+        }
+        // 本地静态桩：仅返回请求到的 skill（视为确定性结果）
+        const want = new Set(skillRefs.map((r) => r.name));
+        return { ok: true, configs: (await this.loadSampleConfigs()).filter((c) => want.has(c.skillName)) };
+    }
+    async loadSampleConfigs() {
+        if (this.sampleConfigs)
+            return this.sampleConfigs;
+        try {
+            const here = path.dirname(fileURLToPath(import.meta.url));
+            const raw = await fs.readFile(path.join(here, "sample-config.json"), "utf-8");
+            this.sampleConfigs = JSON.parse(raw).configs;
+        }
+        catch {
+            this.sampleConfigs = [];
+        }
+        return this.sampleConfigs;
+    }
+    rebuildIndex() {
+        this.index = buildIndex([...this.configs.values()]);
+    }
+    async persist() {
+        try {
+            const state = { active: {}, configPool: {}, installations: {} };
+            for (const [name, signature] of this.signatures) {
+                state.active[name] = { signature };
+            }
+            for (const [key, cfg] of this.configPool) {
+                state.configPool[key] = cfg;
+            }
+            // agent↔skill 安装映射：本地留存每个 skill 在各 workspace 的副本与版本。
+            for (const [name, copies] of this.installations) {
+                state.installations[name] = copies.map((c) => ({ rootDir: c.rootDir, version: c.version }));
+            }
+            await fs.mkdir(path.dirname(this.paths.syncStatePath), { recursive: true });
+            // 原子写：写临时文件再 rename，避免 reconcile 与版本检查并发持久化时相互写坏。
+            const tmp = `${this.paths.syncStatePath}.tmp-${process.pid}-${Date.now()}`;
+            await fs.writeFile(tmp, JSON.stringify(state));
+            await fs.rename(tmp, this.paths.syncStatePath);
+        }
+        catch (err) {
+            console.warn("[skill-logger-plugin] 持久化同步状态失败", err);
+        }
+    }
+}

package/dist/config-sync.test.js

@@ -0,0 +1,145 @@
+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 { ConfigSync, parseSkillVersion } from "./config-sync.ts";
+let dir;
+let extensionsDir;
+let syncStatePath;
+const sampleConfigs = [
+    { skillName: "foo", version: "1", functions: [{ id: "run", name: "运行", match: { type: "script", script: "scripts/run.py" } }] },
+    { skillName: "bar", version: "1", functions: [{ id: "x", name: "x", match: { type: "tool", toolName: "bar_x" } }] },
+];
+async function writeSkill(name, withScripts = true) {
+    const skillDir = path.join(extensionsDir, "myext", "skills", name);
+    await fs.mkdir(skillDir, { recursive: true });
+    await fs.writeFile(path.join(skillDir, "SKILL.md"), `---\nname: ${name}\n---\n# ${name}\n`);
+    if (withScripts) {
+        await fs.mkdir(path.join(skillDir, "scripts"), { recursive: true });
+        await fs.writeFile(path.join(skillDir, "scripts", "run.py"), "print(1)\n");
+    }
+}
+function makeSync() {
+    return new ConfigSync({
+        paths: { extensionsDir, syncStatePath, openclawConfigPath: path.join(dir, "openclaw.json") },
+        getConfig: () => ({}), // 无 platformBaseUrl → 用静态桩
+        sampleConfigs,
+        // 测试注入固定扫描目录，跳过 openclaw.json 解析；skill 实际写在 extensionsDir 下。
+        resolveSkillDirs: () => [path.join(os.tmpdir(), "openclaw-test-skills")],
+    });
+}
+beforeEach(async () => {
+    dir = path.join(os.tmpdir(), `slp-sync-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    extensionsDir = path.join(dir, "extensions");
+    syncStatePath = path.join(dir, "sync.json");
+    await fs.mkdir(extensionsDir, { recursive: true });
+});
+afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+});
+describe("parseSkillVersion（中英文兼容、纯正则）", () => {
+    const fm = (body) => `---\n${body}\n---\n# skill\n`;
+    it("英文 version", () => assert.equal(parseSkillVersion(fm("name: x\nversion: 1.2.3")), "1.2.3"));
+    it("大写 Version", () => assert.equal(parseSkillVersion(fm("Version: 2.0.0")), "2.0.0"));
+    it("中文 版本号 + 全角冒号", () => assert.equal(parseSkillVersion(fm("版本号：3.1")), "3.1"));
+    it("中文 版本 + 半角冒号", () => assert.equal(parseSkillVersion(fm("版本: v4")), "v4"));
+    it("去除包裹引号", () => assert.equal(parseSkillVersion(fm('version: "1.0.0"')), "1.0.0"));
+    it("去除行尾注释", () => assert.equal(parseSkillVersion(fm("version: 1.0.0  # latest")), "1.0.0"));
+    it("无版本字段返回 undefined", () => assert.equal(parseSkillVersion(fm("name: x")), undefined));
+    it("无 frontmatter 时全文宽松查找", () => assert.equal(parseSkillVersion("版本号: 9.9\n正文"), "9.9"));
+    it("版本写在正文单独一行 → 能取到", () => assert.equal(parseSkillVersion(fm("name: x") + "\n版本号：7.7\n"), "7.7"));
+    it("Markdown 标题 ## Version 不误取（# 前缀）", () => assert.equal(parseSkillVersion(fm("name: x") + "\n## Version: 5.5\n"), undefined));
+    it("frontmatter 与正文都有版本 → frontmatter 优先", () => assert.equal(parseSkillVersion(fm("version: 1.0.0") + "\nversion: 2.0.0\n"), "1.0.0"));
+});
+describe("ConfigSync.scanInstalledSkills", () => {
+    it("扫描出 SKILL.md 并解析 name", async () => {
+        await writeSkill("foo");
+        const skills = await makeSync().scanInstalledSkills();
+        const foo = skills.find((s) => s.name === "foo");
+        assert.ok(foo);
+        assert.ok(foo.signature.length > 0);
+    });
+    it("跳过 node_modules", async () => {
+        const nm = path.join(extensionsDir, "myext", "node_modules", "pkg", "skills", "ghost");
+        await fs.mkdir(nm, { recursive: true });
+        await fs.writeFile(path.join(nm, "SKILL.md"), `---\nname: ghost\n---\n`);
+        const skills = await makeSync().scanInstalledSkills();
+        assert.equal(skills.find((s) => s.name === "ghost"), undefined);
+    });
+});
+describe("ConfigSync.diffAgainstState", () => {
+    it("初次全部需拉取", async () => {
+        await writeSkill("foo");
+        const cs = makeSync();
+        const installed = await cs.scanInstalledSkills();
+        const { toFetch } = cs.diffAgainstState(installed);
+        assert.equal(toFetch.length, 1);
+        assert.equal(toFetch[0].name, "foo");
+    });
+});
+describe("ConfigSync.pullConfigs（静态桩）", () => {
+    it("仅返回请求到的 skill（ok=true）", async () => {
+        const got = await makeSync().pullConfigs([{ name: "foo" }]);
+        assert.equal(got.ok, true);
+        assert.equal(got.configs.length, 1);
+        assert.equal(got.configs[0].skillName, "foo");
+    });
+});
+describe("ConfigSync 多 workspace 映射与过期检测", () => {
+    async function writeSkillIn(wsDir, name, version) {
+        const skillDir = path.join(wsDir, "skills", name);
+        await fs.mkdir(skillDir, { recursive: true });
+        await fs.writeFile(path.join(skillDir, "SKILL.md"), `---\nname: ${name}\nversion: ${version}\n---\n`);
+        return skillDir;
+    }
+    it("同名 skill 在多个 workspace → 映射记录全部副本，去重后只返回一份", async () => {
+        const wsA = path.join(dir, "workspace-a");
+        const wsB = path.join(dir, "workspace-b");
+        await writeSkillIn(wsA, "demo", "1.0.0");
+        await writeSkillIn(wsB, "demo", "1.0.0");
+        const cs = new ConfigSync({
+            paths: { extensionsDir, syncStatePath, openclawConfigPath: path.join(dir, "openclaw.json") },
+            getConfig: () => ({}),
+            sampleConfigs,
+            resolveSkillDirs: () => [path.join(wsA, "skills"), path.join(wsB, "skills")],
+        });
+        const list = await cs.scanInstalledSkills();
+        assert.equal(list.filter((s) => s.name === "demo").length, 1); // 去重
+        assert.equal(cs.getInstallations().get("demo")?.length, 2); // 映射保留两份
+    });
+    it("detectOutdated：本地版本落后于平台最新版本时被标记", async () => {
+        const wsA = path.join(dir, "workspace-a");
+        await writeSkillIn(wsA, "demo", "1.0.0");
+        const cs = new ConfigSync({
+            paths: { extensionsDir, syncStatePath, openclawConfigPath: path.join(dir, "openclaw.json") },
+            getConfig: () => ({}),
+            // 平台最新版本 2.0.0（桩无 latestVersion 字段 → 回退用 version 当最新）
+            sampleConfigs: [{ skillName: "demo", version: "2.0.0", functions: [] }],
+            resolveSkillDirs: () => [path.join(wsA, "skills")],
+        });
+        await cs.checkVersionsAndUpdate(); // 刷新 latestVersions + 检测（无 updater 注入则不覆盖文件）
+        const outdated = cs.detectOutdated();
+        assert.equal(outdated.length, 1);
+        assert.equal(outdated[0].skillName, "demo");
+        assert.equal(outdated[0].localVersion, "1.0.0");
+        assert.equal(outdated[0].latestVersion, "2.0.0");
+        // agent↔skill 映射应本地持久化到 sync.json
+        const state = JSON.parse(await fs.readFile(syncStatePath, "utf-8"));
+        assert.ok(state.installations.demo, "sync.json 应含 installations 映射");
+        assert.equal(state.installations.demo[0].version, "1.0.0");
+    });
+});
+describe("ConfigSync.reconcile 端到端", () => {
+    it("对账后索引含该 skill 功能点，并持久化", async () => {
+        await writeSkill("foo");
+        const cs = makeSync();
+        await cs.reconcile();
+        // foo 的 run.py 应进入 script 索引
+        assert.ok(cs.getIndex().scriptByBasename.has("run.py"));
+        // 持久化文件存在且含 foo
+        const state = JSON.parse(await fs.readFile(syncStatePath, "utf-8"));
+        assert.ok(state.active.foo);
+        assert.ok(state.configPool["foo@unknown"]);
+    });
+});