evolcore 0.0.28 → 0.0.29

package/dist/core/session/{session-turns.js → session-transcript.js}

@@ -1,9 +1,18 @@
 import { createHash } from 'node:crypto';
+export function aunMessageTranscriptUuid(messageId) {
+    const bytes = createHash('sha256')
+        .update(`evolcore:aun-input:v1\0${messageId}`)
+        .digest();
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
 // These prompts are steered into the active base-agent turn by EvolCore. The
 // Codex history adapter exposes steered input as a regular `user` item, so it
 // must not split the user's actual turn when reconstructing fork anchors.
 const TASK_RECOVERY_PROMPT = '继续当前会话尚未完成的任务。先核对最新用户指令、已有结果和任务状态；若已完成、用户已停止或正在等待必要输入/审批，则不要重复执行。对可能已产生副作用的步骤先核实结果，再继续未完成的工作。';
-function isInternalInjectedUserMessage(message) {
+export function isInternalInjectedUserMessage(message) {
     const text = extractUserText(message);
     if (!text)
         return false;
@@ -17,6 +26,14 @@ function isInternalInjectedUserMessage(message) {
         return true;
     return false;
 }
+function toolResultCallIds(message) {
+    const content = message?.content;
+    if (!Array.isArray(content))
+        return [];
+    return content.filter((block) => block?.type === 'tool_result')
+        .map((block) => block.tool_use_id)
+        .filter((id) => typeof id === 'string' && id.length > 0);
+}
 function extractText(message) {
     const value = message;
     let text = '';
@@ -59,13 +76,13 @@ export function extractSessionUserContent(message) {
 function textHash(text) {
     return createHash('sha256').update(text.replace(/\s+/g, ' ').trim()).digest('hex');
 }
-function isToolResultMessage(message) {
+export function isToolResultMessage(message) {
     const content = message?.content;
     return Array.isArray(content)
         && content.length > 0
         && content.every((block) => block?.type === 'tool_result');
 }
-export function buildSessionTurnList(messages) {
+export function buildTranscriptTurns(messages) {
     const turns = [];
     let pending;
     const finishPending = () => {
@@ -79,12 +96,19 @@ export function buildSessionTurnList(messages) {
             assistantUuids: [...(pending.assistantUuids ?? [])],
             userTextHash: pending.userTextHash,
             assistantTextHashes: [...pending.assistantTextHashes],
+            assistantTextAnchors: [...pending.assistantTextAnchors],
+            toolResultAnchors: [...pending.toolResultAnchors],
         });
     };
     for (const message of messages) {
         if (message.type === 'user') {
-            if (isToolResultMessage(message.message))
+            if (isToolResultMessage(message.message)) {
+                if (pending)
+                    for (const callId of toolResultCallIds(message.message)) {
+                        pending.toolResultAnchors.push({ callId, messageId: message.uuid });
+                    }
                 continue;
+            }
             if (isInternalInjectedUserMessage(message.message))
                 continue;
             finishPending();
@@ -92,6 +116,8 @@ export function buildSessionTurnList(messages) {
             pending = userContent ? {
                 userContent, userUuid: message.uuid, assistantUuids: [],
                 userTextHash: textHash(extractUserText(message.message)), assistantTextHashes: [],
+                assistantTextAnchors: [],
+                toolResultAnchors: [],
             } : undefined;
             continue;
         }
@@ -99,8 +125,11 @@ export function buildSessionTurnList(messages) {
             pending.assistantUuid = message.uuid;
             pending.assistantUuids.push(message.uuid);
             const text = extractText(message.message);
-            if (text)
-                pending.assistantTextHashes.push(textHash(text));
+            if (text) {
+                const hash = textHash(text);
+                pending.assistantTextHashes.push(hash);
+                pending.assistantTextAnchors.push({ messageId: message.uuid, textHash: hash });
+            }
         }
     }
     finishPending();

package/dist/core/skill/global-watcher.js

@@ -0,0 +1,282 @@
+import chokidar from 'chokidar';
+import fs from 'fs';
+import path from 'path';
+import { getPackageRoot, resolveRoot, resolvePaths, agentDir } from '../../paths.js';
+import { generateSkillIndexes } from './index-generator.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * 全局技能监控器（单例）
+ *
+ * 职责：
+ * 1. 递归监控三级技能目录（内置/本机/每个Agent）
+ * 2. 标记哪些作用域有变化（dirty 标记）
+ * 3. 2秒防抖：连续变更时重置计时器，静默2秒后触发回调
+ *
+ * Agent 监控采用注册机制：
+ * - Agent 启动时调用 `watchAgent(aid)` 注册监控
+ * - Agent 停止时调用 `unwatchAgent(aid)` 注销监控
+ */
+class GlobalSkillWatcher {
+    // 内置和本机的 watcher（固定）
+    builtinWatcher = null;
+    localWatcher = null;
+    // Agent 级 watcher（动态注册/注销）
+    agentWatchers = new Map();
+    /** 路径覆盖（测试注入；生产为 undefined） */
+    pathsOverride;
+    /** 防抖时长（毫秒）。测试可缩短。 */
+    debounceMs = 2000;
+    dirtyScopes = new Set();
+    dirtyAgents = new Set();
+    /** 首次检查标志：记录哪些 agent 已完成首次检查 */
+    checkedAgents = new Set();
+    // 防抖计时器：key = "builtin" | "local" | "agent:<aid>"
+    timers = new Map();
+    // 回调函数：在防抖完成后被调用
+    callbacks = new Map();
+    started = false;
+    /**
+     * 启动全局监控器（仅监控内置和本机目录）
+     * @param override 路径与防抖覆盖（仅测试用）
+     */
+    start(override) {
+        if (this.started)
+            return;
+        this.started = true;
+        this.pathsOverride = override;
+        if (override?.debounceMs !== undefined)
+            this.debounceMs = override.debounceMs;
+        const builtinDir = override?.builtin ?? path.join(getPackageRoot(), 'kits', 'skills');
+        const localDir = override?.local ?? path.join(resolveRoot(), 'skills');
+        // 1. 内置技能目录（递归监控）
+        this.builtinWatcher = chokidar.watch(builtinDir, {
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+        });
+        this.builtinWatcher.on('all', () => {
+            this.markDirty('builtin');
+        });
+        // 2. 本机技能目录（递归监控）
+        this.localWatcher = chokidar.watch(localDir, {
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+        });
+        this.localWatcher.on('all', () => {
+            this.markDirty('local');
+        });
+    }
+    /**
+     * 注册某个 Agent 的技能目录监控（Agent 启动时调用）
+     */
+    watchAgent(aid) {
+        if (this.agentWatchers.has(aid))
+            return; // 已经监控，跳过
+        const resolveAgentDir = this.pathsOverride?.agentDir ?? agentDir;
+        const agentSkillsDir = path.join(resolveAgentDir(aid), 'skills');
+        const watcher = chokidar.watch(agentSkillsDir, {
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+        });
+        watcher.on('all', () => {
+            this.markDirtyAgent(aid);
+        });
+        this.agentWatchers.set(aid, watcher);
+    }
+    /**
+     * 注销某个 Agent 的技能目录监控（Agent 停止时调用）
+     */
+    async unwatchAgent(aid) {
+        const watcher = this.agentWatchers.get(aid);
+        if (!watcher)
+            return; // 没有监控记录，跳过
+        await watcher.close();
+        this.agentWatchers.delete(aid);
+        // 清除该 Agent 的 dirty 标记和计时器
+        this.dirtyAgents.delete(aid);
+        const timerKey = `agent:${aid}`;
+        if (this.timers.has(timerKey)) {
+            clearTimeout(this.timers.get(timerKey));
+            this.timers.delete(timerKey);
+        }
+        this.callbacks.delete(timerKey);
+    }
+    /**
+     * 停止全局监控器（关闭内置和本机 watcher，Agent watcher 已由注销时关闭）
+     */
+    async stop() {
+        if (!this.started)
+            return;
+        // 关闭内置和本机 watcher
+        if (this.builtinWatcher) {
+            await this.builtinWatcher.close();
+            this.builtinWatcher = null;
+        }
+        if (this.localWatcher) {
+            await this.localWatcher.close();
+            this.localWatcher = null;
+        }
+        // 关闭所有 Agent watcher（兜底，正常应该已在注销时关闭）
+        for (const watcher of this.agentWatchers.values()) {
+            await watcher.close();
+        }
+        this.agentWatchers.clear();
+        // 清除所有防抖计时器
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.callbacks.clear();
+        this.dirtyScopes.clear();
+        this.dirtyAgents.clear();
+        this.checkedAgents.clear();
+        this.pathsOverride = undefined;
+        this.debounceMs = 2000;
+        this.started = false;
+    }
+    /**
+     * 标记某个作用域有变化（触发防抖）
+     */
+    markDirty(scope) {
+        this.dirtyScopes.add(scope);
+        this.debounce(scope);
+    }
+    /**
+     * 标记某个 Agent 有变化（触发防抖）
+     */
+    markDirtyAgent(aid) {
+        this.dirtyAgents.add(aid);
+        this.debounce(`agent:${aid}`);
+    }
+    /**
+     * 防抖机制：2秒内有新变化就重置计时器，静默2秒后触发回调
+     */
+    debounce(key) {
+        // 清除旧计时器
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+        }
+        // 设置新计时器
+        const timer = setTimeout(() => {
+            this.timers.delete(key);
+            // 触发回调（如果注册了）
+            const callback = this.callbacks.get(key);
+            if (callback) {
+                callback();
+            }
+        }, this.debounceMs); // 默认 2 秒防抖
+        this.timers.set(key, timer);
+    }
+    /**
+     * 检查某个作用域是否 dirty
+     */
+    isDirty(scope) {
+        return this.dirtyScopes.has(scope);
+    }
+    /**
+     * 检查某个 Agent 是否 dirty
+     */
+    isAgentDirty(aid) {
+        return this.dirtyAgents.has(aid);
+    }
+    /**
+     * 清除某个作用域的 dirty 标记
+     */
+    markClean(scope) {
+        this.dirtyScopes.delete(scope);
+    }
+    /**
+     * 清除某个 Agent 的 dirty 标记
+     */
+    markAgentClean(aid) {
+        this.dirtyAgents.delete(aid);
+    }
+    /**
+     * 重置所有内存状态（仅测试用）。
+     * 不关闭 watcher，只清标志位，确保跨测试状态隔离。
+     */
+    _resetForTest() {
+        this.dirtyScopes.clear();
+        this.dirtyAgents.clear();
+        this.checkedAgents.clear();
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        this.callbacks.clear();
+    }
+    /**
+     * 注册回调：防抖完成后执行
+     * @param scope 作用域或 Agent 标识（格式："builtin" | "local" | "agent:<aid>"）
+     * @param callback 回调函数
+     */
+    onDebouncedChange(scope, callback) {
+        this.callbacks.set(scope, callback);
+    }
+    /**
+     * 判断某个 agent 是否需要生成索引（懒加载逻辑）。
+     *
+     * 返回 true 的情况：
+     * 1. 该 agent 未进行过首次检查
+     * 2. 已检查但被标记为"脏"
+     */
+    needsIndexGeneration(aid) {
+        // 未进行过首次检查
+        if (!this.checkedAgents.has(aid)) {
+            return true;
+        }
+        // 已检查但标记为脏
+        if (this.dirtyAgents.has(aid)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 标记某个 agent 已完成首次检查
+     */
+    markAgentChecked(aid) {
+        this.checkedAgents.add(aid);
+    }
+    /**
+     * 标记所有 agent 为脏（内置或本机技能变化时调用）
+     */
+    markAllAgentsDirty() {
+        // 不实际遍历所有 agent，而是在 needsIndexGeneration 时判断
+        // 这里设置一个全局标志
+        this.dirtyScopes.add('builtin');
+        this.dirtyScopes.add('local');
+        // 清除所有 agent 的首次检查标志，强制下次检查时重新生成
+        this.checkedAgents.clear();
+    }
+}
+// 导出单例
+export const globalSkillWatcher = new GlobalSkillWatcher();
+/** Generate indexes for existing agents and start the shared watcher. */
+export function generateSkillIndexesForAllAgents() {
+    const agentsDir = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsDir))
+        return;
+    for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            generateSkillIndexes(path.join(agentsDir, entry.name));
+        }
+        catch (error) {
+            logger.warn(`[skill] 生成索引失败 (${entry.name}): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    globalSkillWatcher.start();
+    globalSkillWatcher.onDebouncedChange('builtin', () => {
+        logger.info('[skill] 内置技能有变化，重新生成所有 agent 索引');
+        generateSkillIndexesForAllAgents();
+    });
+    globalSkillWatcher.onDebouncedChange('local', () => {
+        logger.info('[skill] 本机技能有变化，重新生成所有 agent 索引');
+        generateSkillIndexesForAllAgents();
+    });
+}
+export async function stopGlobalSkillWatcher() {
+    await globalSkillWatcher.stop();
+}

package/dist/core/skill/index-generator.js

@@ -0,0 +1,84 @@
+import fs from 'fs';
+import path from 'path';
+import { parseDocument } from 'yaml';
+import { resolveSkills } from './switch-resolver.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * 生成索引文件（汇总 → 分组 → 落两文件）。
+ *
+ * 按 injection §3 流程：
+ * 1. 汇总解析（调用 switch-resolver）
+ * 2. 按来源分组（builtin / local）
+ * 3. 分别生成 .index-builtin.md / .index-local.md
+ * 4. 空集时删除已存在的旧文件
+ */
+export function generateSkillIndexes(agentDir, override) {
+    const skills = resolveSkills(agentDir, override);
+    // ② 分组
+    const builtinSkills = skills.filter(s => s.source === 'builtin');
+    const localSkills = skills.filter(s => s.source === 'local');
+    const indexDir = path.join(agentDir, 'skills');
+    fs.mkdirSync(indexDir, { recursive: true });
+    // ③ 分别生成（或清理）
+    generateOneIndex(indexDir, '.index-builtin.md', builtinSkills, 'builtin');
+    generateOneIndex(indexDir, '.index-local.md', localSkills, 'local');
+}
+function generateOneIndex(indexDir, filename, skills, label) {
+    const filePath = path.join(indexDir, filename);
+    // 空集：删除旧文件
+    if (skills.length === 0) {
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+            logger.debug(`[skill-index] ${filename} 已删除（无启用技能）`);
+        }
+        return;
+    }
+    // 根目录从任一条目反推（同组内同源，父目录一致）
+    const rootDir = path.dirname(skills[0].skillDir);
+    // 示例用第一个技能的真实路径——模型照抄真路径比按规则推导可靠
+    const exampleName = skills[0].name;
+    const examplePath = path.join(skills[0].skillDir, 'SKILL.md');
+    // 路径规则块（用 path.sep，示例路径用真实技能名）
+    const sep = path.sep;
+    const header = `[skills-${label}] 本 Agent 已启用 ${skills.length} 个${label === 'builtin' ? '内置' : '本机'}技能。
+
+路径规则:
+  根目录: ${rootDir}
+  技能目录 = 根目录 + "${sep}" + 技能名
+  SKILL.md = 技能目录 + "${sep}SKILL.md"
+  例: 技能名为 ${exampleName}，其 SKILL.md 完整路径为
+      ${examplePath}
+  执行脚本时必须写完整绝对路径。
+`;
+    // 技能条目（name + description）
+    const items = [];
+    for (const skill of skills) {
+        const desc = readSkillDescription(skill.skillDir);
+        items.push(`- ${skill.name}\n  ${desc || '（无描述）'}`);
+    }
+    const content = header + '\n' + items.join('\n\n') + '\n';
+    fs.writeFileSync(filePath, content, 'utf-8');
+    logger.debug(`[skill-index] ${filename} 已生成（${skills.length} 个技能）`);
+}
+/**
+ * 读取指定技能目录下 SKILL.md 的 description。
+ *
+ * 直接按目录读，不走 discoverSkillDirectories——后者按父目录扫描再按 name 匹配，
+ * 同名技能（本机覆盖内置）会读到另一份的 description。
+ */
+function readSkillDescription(skillDir) {
+    try {
+        const text = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8');
+        const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        if (!match)
+            return '';
+        const doc = parseDocument(match[1]);
+        if (doc.errors.length > 0)
+            return '';
+        const meta = doc.toJS();
+        return typeof meta?.description === 'string' ? meta.description.trim() : '';
+    }
+    catch {
+        return '';
+    }
+}

package/dist/core/skill/startup.js

@@ -0,0 +1,73 @@
+import { generateSkillIndexes } from './index-generator.js';
+import { globalSkillWatcher } from './global-watcher.js';
+import { logger } from '../../utils/logger.js';
+import { invalidateKitCache } from '../../eck/kit-renderer.js';
+/**
+ * daemon 启动时，启动全局监控器。
+ *
+ * 采用懒加载机制：
+ * - 启动时不生成索引
+ * - 监控器检测到变化时标记所有 agent 为"脏"
+ * - agent 收到消息需要组装系统上下文时，检查并按需生成索引
+ */
+export function startSkillWatcher() {
+    // 启动全局监控器（监控内置和本机技能目录）
+    globalSkillWatcher.start();
+    // 注册防抖回调：内置和本机技能变化时标记所有 agent 为脏并失效缓存
+    globalSkillWatcher.onDebouncedChange('builtin', () => {
+        logger.info('[skill] 内置技能有变化，标记所有 agent 为脏状态');
+        globalSkillWatcher.markAllAgentsDirty();
+        invalidateKitCache();
+    });
+    globalSkillWatcher.onDebouncedChange('local', () => {
+        logger.info('[skill] 本机技能有变化，标记所有 agent 为脏状态');
+        globalSkillWatcher.markAllAgentsDirty();
+        invalidateKitCache();
+    });
+}
+/**
+ * 为单个 agent 注册技能目录监控及防抖回调。
+ *
+ * 在以下两处调用：
+ * 1. daemon 启动后 loadAll() 加载已有 agent（补注册）
+ * 2. startAgent 动态启动新 agent
+ *
+ * 注意：回调内不得再调 markDirtyAgent——脏标记已由文件事件触发时设置，
+ * 重复调用会 re-arm debounce timer 造成 2 秒自激循环。
+ */
+export function watchAgentSkills(aid) {
+    globalSkillWatcher.watchAgent(aid);
+    globalSkillWatcher.onDebouncedChange(`agent:${aid}`, () => {
+        logger.info(`[skill] Agent ${aid} 技能目录有变化，标记为脏状态并失效缓存`);
+        // 脏标记已在 watcher 的 'all' 事件里由 markDirtyAgent 设置，此处只失效缓存
+        invalidateKitCache();
+    });
+}
+/**
+ * 确保指定 agent 的技能索引是最新的（懒加载入口）。
+ *
+ * 在需要组装系统上下文时调用：
+ * 1. 如果该 agent 未进行过首次检查 → 生成索引并标记已检查
+ * 2. 如果已检查但标记为脏 → 重新生成索引并清除脏标记
+ * 3. 如果已检查且干净 → 直接返回
+ */
+export function ensureSkillIndexUpToDate(agentDir, aid) {
+    const needsGenerate = globalSkillWatcher.needsIndexGeneration(aid);
+    if (needsGenerate) {
+        try {
+            logger.debug(`[skill] 为 agent ${aid} 生成技能索引`);
+            generateSkillIndexes(agentDir);
+            globalSkillWatcher.markAgentChecked(aid);
+            globalSkillWatcher.markAgentClean(aid);
+        }
+        catch (e) {
+            logger.warn(`[skill] 生成索引失败 (${aid}): ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+}
+/**
+ * 停止全局监控器（daemon 关闭时调用）
+ */
+export async function stopGlobalSkillWatcher() {
+    await globalSkillWatcher.stop();
+}

package/dist/core/skill/switch-resolver.js

@@ -0,0 +1,115 @@
+import fs from 'fs';
+import path from 'path';
+import { getPackageRoot } from '../../paths.js';
+import { resolveRoot } from '../../paths.js';
+function getSkillPaths(agentDir, override) {
+    return {
+        builtin: override?.builtin ?? path.join(getPackageRoot(), 'kits', 'skills'),
+        local: override?.local ?? path.join(resolveRoot(), 'skills'),
+        agent: path.join(agentDir, 'skills'),
+    };
+}
+/** 读取汇总开关文件（.switches.json），返回技能名 → 开关的字典 */
+function readSwitchesFile(file) {
+    try {
+        if (!fs.existsSync(file))
+            return {};
+        const raw = fs.readFileSync(file, 'utf-8');
+        const data = JSON.parse(raw);
+        if (typeof data !== 'object' || data === null)
+            return {};
+        const result = {};
+        for (const [name, value] of Object.entries(data)) {
+            if (typeof value !== 'object' || value === null)
+                continue;
+            const sw = value;
+            result[name] = {
+                enabled: sw.enabled !== undefined ? Boolean(sw.enabled) : false,
+                locked: sw.locked !== undefined ? Boolean(sw.locked) : false,
+            };
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/** 从字典中获取某个技能的开关（缺失时返回默认 enabled:false） */
+function getSwitch(switches, name) {
+    return switches[name] || { enabled: false, locked: false };
+}
+/** 扫描一级目录下所有技能名（有 SKILL.md 才算） */
+function scanSkillNames(root) {
+    const names = new Set();
+    try {
+        if (!fs.existsSync(root))
+            return names;
+        const entries = fs.readdirSync(root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            const skillFile = path.join(root, entry.name, 'SKILL.md');
+            if (fs.existsSync(skillFile))
+                names.add(entry.name);
+        }
+    }
+    catch { }
+    return names;
+}
+/**
+ * 三级开关解析 + 覆盖链求值。
+ *
+ * 按 design §4.1 算法：
+ * 1. 扫描三级目录，收集所有技能名
+ * 2. 对每个技能按覆盖链求值：内置 locked → Agent → 本机 → 内置
+ * 3. 返回最终启用的技能集合（带来源标记）
+ */
+export function resolveSkills(agentDir, override) {
+    const paths = getSkillPaths(agentDir, override);
+    // ① 收集所有技能名（合并三级）
+    const builtinNames = scanSkillNames(paths.builtin);
+    const localNames = scanSkillNames(paths.local);
+    const allNames = new Set([...builtinNames, ...localNames]);
+    // ② 读取三级汇总开关文件
+    const builtinSwitches = readSwitchesFile(path.join(paths.builtin, '.switches.json'));
+    const localSwitches = readSwitchesFile(path.join(paths.local, '.switches.json'));
+    const agentSwitches = readSwitchesFile(path.join(paths.agent, '.switches.json'));
+    const results = [];
+    for (const name of allNames) {
+        // ③ 判断来源：本机有 SKILL.md → local，否则 builtin
+        const source = localNames.has(name) ? 'local' : 'builtin';
+        const skillRoot = source === 'local' ? paths.local : paths.builtin;
+        const skillDir = path.join(skillRoot, name);
+        // ④ 覆盖链求值（design §4.1）
+        const builtinSwitch = getSwitch(builtinSwitches, name);
+        // 内置 locked 时，直接由内置 enabled 决定
+        if (builtinSwitch.locked) {
+            if (builtinSwitch.enabled) {
+                results.push({ name, source, enabled: true, skillDir });
+            }
+            continue;
+        }
+        // 否则从 Agent 级往下找第一个存在的开关
+        const agentSwitch = getSwitch(agentSwitches, name);
+        if (name in agentSwitches) {
+            if (agentSwitch.enabled) {
+                results.push({ name, source, enabled: true, skillDir });
+            }
+            continue;
+        }
+        const localSwitch = getSwitch(localSwitches, name);
+        if (name in localSwitches) {
+            if (localSwitch.enabled) {
+                results.push({ name, source, enabled: true, skillDir });
+            }
+            continue;
+        }
+        // 三级都没有显式开关 → 用缺省（enabled:false，装完必须显式启用）
+        if (builtinSwitch.enabled) {
+            results.push({ name, source, enabled: true, skillDir });
+        }
+    }
+    return results;
+}