@zooique/memora 2.0.3 → 3.0.0

package/dist/skill/skillScriptRunner.js

@@ -0,0 +1,271 @@
+/**
+ * 技能脚本执行器 — L3 脚本运行时。
+ * 三级渐进披露 L3：脚本在宿主环境（隔离子进程）执行，源代码不入 LLM 上下文，
+ * 只有执行结果（stdout/stderr）作为工具返回值注入。
+ * 安全模型：继承宿主用户环境变量（用户会话环境——脚本可读项目所需配置与用户 shell 环境；
+ *   密钥默认经 SecretStorage→配置对象注入、不经 env（宿主默认路径）；env 回退配置模式
+ *   （MEMORA_API_KEY 等，security_rules 支持）下 key 在进程 env、对脚本可见——owner 信任
+ *   模型（默认自动批准）+ 脚本来源审阅（判据 B）为边界，视同用户本地 shell 语义）+ 超时
+ *   限制（默认 60s，最大 600s——适配脚本内 API 调用/批处理长耗时）+ 白名单 runtime（node/python/shell）+ Windows 隐藏窗口
+ *   （windowsHide:true，不弹 conhost）。
+ * 注：当前为简单子进程执行，非完整沙箱（文件系统/网络隔离由宿主在生产环境实现）。
+ */
+import * as childProcess from 'node:child_process';
+import { logger } from '../logging/logger.js';
+/** 默认执行超时（毫秒）：脚本常用交互/构建任务在 1 分钟内完成；超长任务由 LLM 传 timeoutMs */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** 最大执行超时（毫秒）：适配脚本内 API 调用/批处理等长耗时任务 */
+const MAX_TIMEOUT_MS = 600_000;
+/**
+ * 超时钳制真理源（SSOT）：实际超时 = clamp(timeoutMs, 1s, MAX_TIMEOUT_MS)
+ *
+ * 执行侧（spawn 的 timeout 选项）与文案侧（formatScriptResult 的「超过 Ns」）必须同源，
+ * 否则两处漂移会重现「实际 60s 超时却告知超过 600s」的谎报。
+ *
+ * @param timeoutMs 调用方传入的超时（毫秒；toolExecutor 由 LLM 的 timeout_ms 秒值 ×1000 得到）
+ * @returns 钳制后的实际超时（毫秒，落在 [1_000, MAX_TIMEOUT_MS] 区间内）
+ */
+function normalizeTimeoutMs(timeoutMs) {
+    return Math.min(Math.max(timeoutMs, 1_000), MAX_TIMEOUT_MS);
+}
+/**
+ * Windows 平台 shell 档脚本守卫
+ *
+ * 缺陷事实链：`.sh` → runtime `shell`（scanner.SCRIPT_RUNTIME_MAP）→ win32 派发
+ * `cmd /c <path>`（resolveCommand shell 分支）——而 `.sh` 不是 cmd 原生可执行类型
+ * （只有 `.bat`/`.cmd` 是），命令退到「Windows 关联程序」路径：status=0 但
+ * stdout/stderr 全空（静默空跑）。`formatExecutionResult` 见 status=0 向模型报
+ * 「成功」→ 模型认定脚本已跑完 → 静默失败。
+ * `.ps1` 同理：`cmd /c` 不起 PowerShell，同样静默空跑（不新增 powershell runtime 档——
+ * 那是新能力，留待宿主 shell 选型一并设计）。
+ *
+ * 本守卫改的是「喂给判据的事实」（Win 下喂进 spawn 的 `cmd /c foo.sh` 只会制造假
+ * status=0），非判据本身——属止血。POSIX 不受影响（`sh <path>` 合法）。
+ *
+ * @param scriptPath 脚本路径
+ * @param runtime 运行时（node/python/shell）
+ * @param platform 当前平台（win32 才拦截；参数化便于测试）
+ * @returns 命中拦截返回显式错误文案（含替代方案），否则 null
+ */
+export function guardWindowsShellScript(scriptPath, runtime, platform) {
+    if (platform !== 'win32' || runtime !== 'shell')
+        return null;
+    const ext = scriptPath.slice(scriptPath.lastIndexOf('.')).toLowerCase();
+    // cmd 原生可执行类型：批处理文件（与 scanner SCRIPT_RUNTIME_MAP 注释同源，
+    // win32 派发 `cmd /c` 实测 status=0 + 输出正确）
+    if (ext === '.bat' || ext === '.cmd')
+        return null;
+    return (`Windows 平台 shell 档仅支持 .bat/.cmd（cmd 原生可执行类型）。当前脚本扩展名 "${ext}" ` +
+        (ext === '.ps1'
+            ? '(.ps1 静默空跑：cmd /c 不起 PowerShell，且内核未接入 PowerShell runtime档)。'
+            : '(shell 档在 Windows 依赖 sh/bash 解释器——本机无 Git Bash 时会静默空跑：退出码 0 但 stdout/stderr 全空，不是执行成功)。') +
+        '请改用跨平台脚本 .mjs/.js/.py；确需 Windows 批处理用 .bat/.cmd。');
+}
+/**
+ * 执行技能脚本：在隔离子进程中运行，收集 stdout/stderr/exitCode/timedOut
+ *
+ * @param scriptPath 脚本绝对路径
+ * @param runtime 运行时（node/python/shell 白名单三档）
+ * @param args 传给脚本的参数数组
+ * @param timeoutMs 超时（毫秒，限制在 [1s, MAX_TIMEOUT_MS] 内）
+ * @param cwd 子进程工作目录（可选；run_project_script 以项目根为 cwd，
+ *        使项目脚本可加载项目本地依赖/相对数据文件）
+ * @param nodePath node 可执行文件路径（可选，缺省 'node' 走 PATH）——供宿主注入真实
+ *        node 路径用。
+ *        ⚠️ 宿主尚未接入——`hosts/memora-vscode` 零注入点，故实际恒走缺省 `'node'`。
+ *        且真解不止「传个路径」：Electron 宿主（VS Code）的
+ *        `process.execPath` 指向应用二进制，需配 `ELECTRON_RUN_AS_NODE` 一类环境变量才能以
+ *        node 语义执行 `.mjs` **文件**，而内核只收路径、不收环境（边界铁律：内核不持有平台知识）。
+ *        ⇒ 真解 = 接口扩展（宿主上报运行时环境，内核零解释转发），留待与宿主 shell 选型同批。
+ *        此处保留该可选参数：接入点已就绪，扩展时无须再动调用链。
+ */
+export async function runSkillScript(scriptPath, runtime, args = [], timeoutMs = DEFAULT_TIMEOUT_MS, cwd, nodePath) {
+    // win32 + shell + 非 .bat/.cmd → 在 spawn 前显式拒绝，
+    // 不让假 status=0 进入 formatExecutionResult（喂给判据的事实必须为真）
+    const guardError = guardWindowsShellScript(scriptPath, runtime, process.platform);
+    if (guardError) {
+        return { stdout: '', stderr: guardError, exitCode: -1, timedOut: false };
+    }
+    // 超时限制在 [1s, MAX_TIMEOUT_MS] 内（与超时文案同源，见 normalizeTimeoutMs）
+    const effectiveTimeout = normalizeTimeoutMs(timeoutMs);
+    const { command, args: cmdArgs } = resolveCommand(runtime, scriptPath, args, nodePath);
+    /**
+     * 单次子进程执行（spawn + 输出收集）。
+     *
+     * @returns 执行结果 + enoent 标记（命令不存在 → 供调用方判定 L2 fallback 重试）
+     */
+    const runOnce = (cmd, runArgs) => new Promise((resolve) => {
+        /** ENOENT 标记：spawn 命令不存在（如 Windows 缺 python 命令，仅 python runtime 场景用） */
+        let enoent = false;
+        let child;
+        try {
+            child = childProcess.spawn(cmd, runArgs, {
+                timeout: effectiveTimeout,
+                // 继承宿主用户环境变量（不走 PATH/HOME 最小白名单——
+                // 项目脚本读用户环境（API KEY/PATH/工作区变量）是合理需求；密钥默认经
+                // SecretStorage→config 不经 env，env 回退模式下 key 在 env 属 owner 信任
+                // 语义（见文件头安全模型）。对齐宿主 codeExecutor 持久会话环境语义）
+                // 禁子进程彩色输出：FORCE_COLOR:0/NO_COLOR:1 源头禁色（对齐宿主 codeExecutor
+                // 同构）；回流净化由 toolExecutor sanitizeExternalText 兜底剥残留 ANSI——
+                // 源头禁根因 + 通用防御两层不冲突
+                env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+                stdio: ['ignore', 'pipe', 'pipe'],
+                // 隐藏子进程窗口（Windows）：不传则每次执行弹 conhost 黑框（对齐宿主
+                // codeExecutor 既有 windowsHide 语义 + 大厂仅隐藏子进程回流输出共识）
+                windowsHide: true,
+                // cwd 缺省时由 node 决定（当前进程目录）；仅显式传入时指定
+                ...(cwd ? { cwd } : {}),
+            });
+        }
+        catch (err) {
+            logger.error({ scriptPath, runtime, err }, '启动脚本进程失败');
+            resolve({
+                stdout: '',
+                stderr: `启动失败: ${err.message}`,
+                exitCode: -1,
+                timedOut: false,
+                enoent: false,
+            });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString('utf-8');
+        });
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString('utf-8');
+        });
+        child.on('error', (err) => {
+            // ENOENT = 命令不存在（Windows python 9009 场景：现代 Python 只装 py 启动器）
+            // 记标记供 L2 fallback，其余错误原样返回
+            enoent = err.code === 'ENOENT';
+            logger.error({ scriptPath, err }, '脚本进程执行错误');
+            resolve({ stdout, stderr: stderr || String(err), exitCode: -1, timedOut: false, enoent });
+        });
+        child.on('close', (code, signal) => {
+            if (signal === 'SIGTERM' || signal === 'SIGKILL') {
+                timedOut = true;
+                logger.warn({ scriptPath, effectiveTimeout }, '脚本执行超时，已被终止');
+            }
+            resolve({
+                stdout,
+                stderr,
+                exitCode: code ?? 0,
+                timedOut,
+                enoent,
+            });
+        });
+    });
+    const result = await runOnce(command, cmdArgs);
+    // Windows python 不可用兜底链。python 命令在本机
+    // 不可用有两种形态：① spawn ENOENT（现代 Python 只装 py 启动器、无 python 命令）；
+    // ② 退出码 9009（spawn 命中 Windows Store 空壳启动器 python.exe，它启动即退出 9009；
+    // 非 ENOENT，故不能只看 enoent 标记）。命中即在两个候选解释器间逐级替换重试：
+    //   ① `py -3`（py 启动器）② `cmd /c python`（shell 派发——cmd 按 PATHEXT 解析 .bat shim，
+    //   pyenv/conda 的 python.bat 由此生效；原生 spawn 不解析 .bat 的跨层缺环在此补上）。
+    if (shouldFallbackPythonToPy(runtime, process.platform) &&
+        isPythonUnavailable(result, process.platform)) {
+        // ① py 启动器重试：任一成功（上已判定不可用、此命令=解释器本体）即返回
+        const pyResult = await runOnce('py', ['-3', scriptPath, ...args]);
+        if (!isPythonUnavailable(pyResult, process.platform)) {
+            return pyResult;
+        }
+        // ② shell 派发兜底：cmd /c python —— 经 cmd 的 PATHEXT 解析让 pyenv/conda shim 生效
+        return await runOnce('cmd', ['/c', 'python', scriptPath, ...args]);
+    }
+    return result;
+}
+/**
+ * 兜底判定：python runtime 在 Windows 下进入兜底链（纯函数，平台参数化可测）
+ *
+ * @param runtime  脚本运行时
+ * @param platform 当前平台（process.platform；参数化便于测试）
+ * @returns 是否应进入「py -3 → cmd /c python」兜底链
+ */
+export function shouldFallbackPythonToPy(runtime, platform) {
+    return runtime === 'python' && platform === 'win32';
+}
+/**
+ * python 是否不可用（判定「要不要继续走兜底链」）
+ *
+ * 两种失败形态任一命中即不可用：
+ *   ① enoent —— spawn 未找到 python 命令（PATH 缺 python / 只装 py 启动器）
+ *   ② exitCode 9009 —— spawn 命中 Windows Store 空壳启动器 python.exe，它非文件缺失、
+ *     而是启动后立即以 9009（Windows「命令未找到」）退出。此形态 spawn 不报 ENOENT、
+ *     `enoent` 标记为 false，必须靠退出码识别，否则 python 被误判「执行失败」而非「不可用」。
+ *
+ * @param result  单次执行结果（含 enoent/exitCode 标记）
+ * @param platform 当前平台（win32 之外的平台不判 9009——非 Windows「命令未找到」语义）
+ */
+export function isPythonUnavailable(result, platform) {
+    if (platform !== 'win32')
+        return result.enoent;
+    return result.enoent || result.exitCode === 9009;
+}
+/**
+ * 根据 runtime 解析执行命令：node/python 直接执行，shell 依平台用 cmd /c（Windows）或 sh -c
+ *
+ * @param nodePath node 可执行文件路径（可选）：缺省 'node'（走 PATH 查找）。
+ *        供给方（宿主）可注入真实 node 路径（如 VS Code 内置 node / 用户配置的 node），
+ *        避免「系统无独立 node → .js/.mjs 技能脚本 ENOENT」。
+ */
+function resolveCommand(runtime, scriptPath, args, nodePath) {
+    switch (runtime) {
+        case 'node':
+            return { command: nodePath ?? 'node', args: [scriptPath, ...args] };
+        case 'python':
+            return { command: 'python', args: [scriptPath, ...args] };
+        case 'shell':
+            // Windows 用 cmd /c，其余平台用 sh 直接解释脚本文件
+            // 注意：用 sh <scriptPath> 而非 sh -c（-c 把路径当命令执行，依赖文件可执行位，POSIX 下无 chmod 会报 126）
+            if (process.platform === 'win32') {
+                return { command: 'cmd', args: ['/c', scriptPath, ...args] };
+            }
+            return { command: 'sh', args: [scriptPath, ...args] };
+        default:
+            return { command: scriptPath, args };
+    }
+}
+/**
+ * 执行结果三态格式化（run_skill_script 与 run_code 共用的格式化真理源）
+ *
+ * 超时 / 非零退出码 / 成功三态；前缀与文案由 labels 定制，成功分支统一
+ * 「无输出兜底 + stderr 附加」。stdout/stderr 须由调用方先行净化。
+ *
+ * @param result 执行结果
+ * @param labels 三态前缀标签与详情文案
+ * @returns 格式化后的可读字符串（供工具返回值注入 LLM 上下文）
+ */
+export function formatExecutionResult(result, labels) {
+    if (result.timedOut) {
+        return `[${labels.kind}_TIMEOUT] ${labels.timeoutDetail}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`;
+    }
+    if (result.exitCode !== 0) {
+        return `[${labels.kind}_ERROR] ${labels.errorDetail}（退出码: ${result.exitCode}）\nstdout: ${result.stdout}\nstderr: ${result.stderr}`;
+    }
+    // 成功：优先 stdout，stderr 附加
+    const output = result.stdout || '(无输出)';
+    if (result.stderr) {
+        return `${output}\n[stderr] ${result.stderr}`;
+    }
+    return output;
+}
+/**
+ * 格式化脚本执行结果为可读字符串（供 tool 返回值）：formatExecutionResult 的 SCRIPT 变体
+ *
+ * 超时文案的「超过 Ns」取本次**实际**超时（经 normalizeTimeoutMs 钳制），不再恒写上限 600s：
+ * 默认 60s 超时却报「超过 600s」是对 LLM 的谎报，会诱导它盲目调大 timeout_ms 重试。
+ *
+ * @param result 执行结果
+ * @param timeoutMs 本次实际超时（毫秒）；省略则用 DEFAULT_TIMEOUT_MS（与执行侧默认同源）
+ */
+export function formatScriptResult(result, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return formatExecutionResult(result, {
+        kind: 'SCRIPT',
+        timeoutDetail: `脚本执行超时（超过 ${Math.round(normalizeTimeoutMs(timeoutMs) / 1000)}s）`,
+        errorDetail: '脚本执行失败',
+    });
+}
+//# sourceMappingURL=skillScriptRunner.js.map

package/dist/skill/skillScriptRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillScriptRunner.js","sourceRoot":"","sources":["../../src/skill/skillScriptRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAM7C,4DAA4D;AAC5D,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,wCAAwC;AACxC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAkB,EAClB,OAAsB,EACtB,QAAyB;IAEzB,IAAI,QAAQ,KAAK,OAAO,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxE,uDAAuD;IACvD,wCAAwC;IACxC,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,CACL,yDAAyD,GAAG,IAAI;QAChE,CAAC,GAAG,KAAK,MAAM;YACb,CAAC,CAAC,8DAA8D;YAChE,CAAC,CAAC,yFAAyF,CAAC;QAC9F,kDAAkD,CACnD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAkB,EAClB,OAAsB,EACtB,OAAiB,EAAE,EACnB,YAAoB,kBAAkB,EACtC,GAAY,EACZ,QAAiB;IAEjB,+CAA+C;IAC/C,qDAAqD;IACrD,MAAM,UAAU,GAAG,uBAAuB,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClF,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC3E,CAAC;IAED,6DAA6D;IAC7D,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAEvD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAEvF;;;;OAIG;IACH,MAAM,OAAO,GAAG,CACd,GAAW,EACX,OAAiB,EACqC,EAAE,CACxD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACtB,wEAAwE;QACxE,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,KAAgC,CAAC;QACrC,IAAI,CAAC;YACH,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;gBACvC,OAAO,EAAE,gBAAgB;gBACzB,kCAAkC;gBAClC,2CAA2C;gBAC3C,6DAA6D;gBAC7D,2CAA2C;gBAC3C,2DAA2D;gBAC3D,2DAA2D;gBAC3D,oBAAoB;gBACpB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE;gBACxD,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;gBACjC,4CAA4C;gBAC5C,mDAAmD;gBACnD,WAAW,EAAE,IAAI;gBACjB,oCAAoC;gBACpC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;YACvD,OAAO,CAAC;gBACN,MAAM,EAAE,EAAE;gBACV,MAAM,EAAE,SAAU,GAAa,CAAC,OAAO,EAAE;gBACzC,QAAQ,EAAE,CAAC,CAAC;gBACZ,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,KAAK;aACd,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YACxC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YACxC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,6DAA6D;YAC7D,4BAA4B;YAC5B,MAAM,GAAI,GAA6B,CAAC,IAAI,KAAK,QAAQ,CAAC;YAC1D,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;YAC9C,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5F,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACjC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACjD,QAAQ,GAAG,IAAI,CAAC;gBAChB,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,aAAa,CAAC,CAAC;YAC/D,CAAC;YACD,OAAO,CAAC;gBACN,MAAM;gBACN,MAAM;gBACN,QAAQ,EAAE,IAAI,IAAI,CAAC;gBACnB,QAAQ;gBACR,MAAM;aACP,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAE/C,qCAAqC;IACrC,4DAA4D;IAC5D,kEAAkE;IAClE,gDAAgD;IAChD,6EAA6E;IAC7E,gEAAgE;IAChE,IACE,wBAAwB,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;QACnD,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC7C,CAAC;QACD,wCAAwC;QACxC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,wEAAwE;QACxE,OAAO,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAsB,EACtB,QAAyB;IAEzB,OAAO,OAAO,KAAK,QAAQ,IAAI,QAAQ,KAAK,OAAO,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAmD,EACnD,QAAyB;IAEzB,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IAC/C,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CACrB,OAAsB,EACtB,UAAkB,EAClB,IAAc,EACd,QAAiB;IAEjB,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACtE,KAAK,QAAQ;YACX,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAC5D,KAAK,OAAO;YACV,qCAAqC;YACrC,4EAA4E;YAC5E,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;gBACjC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YAC/D,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACxD;YACE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;AACH,CAAC;AAYD;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA2B,EAC3B,MAAmC;IAEnC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO,IAAI,MAAM,CAAC,IAAI,aAAa,MAAM,CAAC,aAAa,aAAa,MAAM,CAAC,MAAM,aAAa,MAAM,CAAC,MAAM,EAAE,CAAC;IAChH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,MAAM,CAAC,IAAI,WAAW,MAAM,CAAC,WAAW,SAAS,MAAM,CAAC,QAAQ,cAAc,MAAM,CAAC,MAAM,aAAa,MAAM,CAAC,MAAM,EAAE,CAAC;IACrI,CAAC;IACD,yBAAyB;IACzB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC;IACxC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,GAAG,MAAM,cAAc,MAAM,CAAC,MAAM,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA6B,EAC7B,YAAoB,kBAAkB;IAEtC,OAAO,qBAAqB,CAAC,MAAM,EAAE;QACnC,IAAI,EAAE,QAAQ;QACd,aAAa,EAAE,aAAa,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,IAAI;QAChF,WAAW,EAAE,QAAQ;KACtB,CAAC,CAAC;AACL,CAAC"}

package/dist/skill/types.d.ts

@@ -1,33 +1,90 @@
 /**
- * 技能模块类型定义
+ * 技能模块类型定义 — 三级渐进披露
+ *
+ * L1 元数据：name + description（必填，渐进披露唯一激活依据）→ 常驻 system prompt（对齐主流：仅两字段）
+ * L2 正文：content（SKILL.md 全文）→ read_skill 按需加载
+ * L3 资源/脚本：resources + references + scripts → read_resource / run_skill_script 按需调用
  */
-/** 技能条目（从 skills/*.md 解析） */
+import type { ResourceSubdir, ScriptRuntime } from '../utils/scanner.js';
+/** L3 资源条目（resources/ 或 references/ 目录下的参考文件） */
+export interface SkillResource {
+    /** 资源相对路径（相对技能目录根，如 "resources/api-spec.md"） */
+    path: string;
+    /** 资源描述（可选，供 L1 清单提示） */
+    description?: string;
+    /** 文件大小（字节），用于判断是否需要分块读取 */
+    size?: number;
+    /**
+     * 资源来源子目录（resources / references）。
+     * references/ 为 TRAE / Agent Skills 主流辅助文档目录（兼容主流），read_resource 据此选择读取基目录。
+     * 取值 SSOT 在 `utils/scanner`（目录名常量派生），此处只引用类型不重复字面量。
+     */
+    subdir?: ResourceSubdir;
+}
+/** L3 脚本条目（scripts/ 目录下的可执行脚本） */
+export interface SkillScript {
+    /** 脚本相对路径（相对技能目录根，如 "scripts/lint.ts"） */
+    path: string;
+    /** 运行时（由目录扫描按扩展名推断，SSOT 在 utils/scanner.SCRIPT_RUNTIME_MAP） */
+    runtime: ScriptRuntime;
+    /** 脚本描述（可选） */
+    description?: string;
+    /**
+     * 脚本文件大小（字节），由 `utils/scanner.discoverLayer3` 发现时产出
+     * （经 skillLayer3.projectDiscoveredLayer3 投影写入）。
+     *
+     * 内核当前无读取方（`resources.size` 才有：`agent/assembler.ts` 的 list_resources 回调输出）；
+     * 保留该字段是为让「L3 投影」在脚本侧与资源侧同构，不丢已发现的事实。
+     */
+    size?: number;
+}
+/** L3 层数据（资源 + 脚本，可选） */
+export interface SkillLayer3 {
+    /** 资源列表 */
+    resources: SkillResource[];
+    /** 脚本列表 */
+    scripts: SkillScript[];
+}
+/** 技能条目（从 skills/*.md 或 skills/<dir>/SKILL.md 解析） */
 export interface SkillEntry {
-    /** 技能名（文件名去 .md） */
+    /** 技能名（文件名去 .md，或目录名） */
     name: string;
-    /** 触发关键词列表 */
-    keywords: string[];
-    /** 触发正则（可选，优先级高于 keywords） */
-    trigger?: RegExp;
     /** 技能描述（可选） */
     description?: string;
-    /** 技能 prompt 正文 */
+    /** 技能 prompt 正文（L2 内容） */
     content: string;
     /** 来源路径 */
     filePath: string;
     /**
      * 来源层（agent / project）
      *
-     * skillManager 写入（project 层扫描），精灵宿主通过 systemHandlers 读取
-     * 并在 settingsPanelManager 中渲染"全局/项目"标签。
+     * skillManager 写入（project 层扫描）。
+     * ⚠️ 展示语义不由本字段单独决定：宿主以 filePath 前缀为主判据，
+     * 本字段仅在无路径/未命中时兜底（project → 用户源，agent → 内置源）。
      */
     layer: 'agent' | 'project';
+    /**
+     * L3 层数据（资源 + 脚本，可选）
+     *
+     * 当技能目录包含 resources/ 或 scripts/ 时自动填充。
+     * 三级渐进披露：L3 内容不进 system prompt，由 read_resource / run_skill_script 按需调用。
+     */
+    layer3?: SkillLayer3;
+}
+/** 技能校验单条问题（写→验→用闭环） */
+export interface SkillIssue {
+    /** 级别：error=不可生效 / warning=可加载但变弱 */
+    level: 'error' | 'warning';
+    /** 问题归属字段（frontmatter/description/layer/body/file） */
+    field?: string;
+    /** 人类可读问题描述（说明影响，供 UI 错误定位） */
+    message: string;
 }
-/** 技能匹配结果 */
-export interface SkillMatch {
-    /** 匹配的技能 */
-    skill: SkillEntry;
-    /** 匹配得分（0-1，用于排序） */
-    score: number;
+/** 技能校验结果（单一入口 validateFile 返回；UI 据此叠加健康徽章 + 错误定位） */
+export interface SkillValidation {
+    /** 是否可用（无 error 即 true；warning 不阻断） */
+    ok: boolean;
+    /** 问题清单（error + warning） */
+    issues: SkillIssue[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/skill/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skill/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;CAC5B;AAED,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,YAAY;IACZ,KAAK,EAAE,UAAU,CAAC;IAClB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skill/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExE,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,kCAAkC;AAClC,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yBAAyB;AACzB,MAAM,WAAW,WAAW;IAC1B,WAAW;IACX,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,WAAW;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,4BAA4B;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB"}

package/dist/skill/types.js

@@ -1,5 +1,9 @@
 /**
- * 技能模块类型定义
+ * 技能模块类型定义 — 三级渐进披露
+ *
+ * L1 元数据：name + description（必填，渐进披露唯一激活依据）→ 常驻 system prompt（对齐主流：仅两字段）
+ * L2 正文：content（SKILL.md 全文）→ read_skill 按需加载
+ * L3 资源/脚本：resources + references + scripts → read_resource / run_skill_script 按需调用
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/skill/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skill/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skill/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils/array.d.ts

@@ -4,21 +4,20 @@
  * 职责：
  * - 提供通用的数组排序、去重、拷贝等纯函数工具
  *
- * 设计原则（ADR-017 枝叶层 2 次提取）：
+ * 设计原则：
  * - 同一模式在 2+ 文件出现时提取到此处
  * - 纯函数，零依赖，可被任何内核模块安全导入
  */
 /**
- * 按 score 字段降序排序的比较函数
+ * 按 accessedAt 字段降序排序（最近使用优先）的比较函数
  *
- * 用于记忆/角色/技能等带 score 字段的排序场景。
- * 9 处 `.sort((a, b) => b.score - a.score)` 的统一提取（ADR-017 枝叶层 2 次提取）。
+ * 使用轨迹唯一事实源为 accessedAt；采集/推荐等需要「采样 top-N」的场景统一按 accessedAt 降序。
  *
  * @param a 前一个元素
  * @param b 后一个元素
  * @returns 负数表示 a 排前，正数表示 b 排前
  */
-export declare function byScoreDesc<T extends {
-    score: number;
+export declare function byAccessedDesc<T extends {
+    accessedAt: string;
 }>(a: T, b: T): number;
 //# sourceMappingURL=array.d.ts.map

package/dist/utils/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/utils/array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,MAAM,CAE3E"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/utils/array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,MAAM,CAGnF"}

package/dist/utils/array.js

@@ -4,21 +4,21 @@
  * 职责：
  * - 提供通用的数组排序、去重、拷贝等纯函数工具
  *
- * 设计原则（ADR-017 枝叶层 2 次提取）：
+ * 设计原则：
  * - 同一模式在 2+ 文件出现时提取到此处
  * - 纯函数，零依赖，可被任何内核模块安全导入
  */
 /**
- * 按 score 字段降序排序的比较函数
+ * 按 accessedAt 字段降序排序（最近使用优先）的比较函数
  *
- * 用于记忆/角色/技能等带 score 字段的排序场景。
- * 9 处 `.sort((a, b) => b.score - a.score)` 的统一提取（ADR-017 枝叶层 2 次提取）。
+ * 使用轨迹唯一事实源为 accessedAt；采集/推荐等需要「采样 top-N」的场景统一按 accessedAt 降序。
  *
  * @param a 前一个元素
  * @param b 后一个元素
  * @returns 负数表示 a 排前，正数表示 b 排前
  */
-export function byScoreDesc(a, b) {
-    return b.score - a.score;
+export function byAccessedDesc(a, b) {
+    // ISO 8601 字符串可直接按字典序比较（时间正序 → 字符串升序）
+    return a.accessedAt < b.accessedAt ? 1 : a.accessedAt > b.accessedAt ? -1 : 0;
 }
 //# sourceMappingURL=array.js.map

package/dist/utils/array.js.map

@@ -1 +1 @@
-{"version":3,"file":"array.js","sourceRoot":"","sources":["../../src/utils/array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAA8B,CAAI,EAAE,CAAI;IACjE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../../src/utils/array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAmC,CAAI,EAAE,CAAI;IACzE,sCAAsC;IACtC,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/dist/utils/atomicWrite.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 原子写入文本文件（UTF-8）
+ *
+ * @param filePath - 目标文件绝对路径（其所在目录须已存在）
+ * @param content - 待写入的文本内容
+ */
+export declare function atomicWriteFile(filePath: string, content: string): Promise<void>;
+//# sourceMappingURL=atomicWrite.d.ts.map

package/dist/utils/atomicWrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicWrite.d.ts","sourceRoot":"","sources":["../../src/utils/atomicWrite.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF"}

package/dist/utils/atomicWrite.js

@@ -0,0 +1,31 @@
+/**
+ * 原子写文件 — 先写同目录临时文件，再 rename 覆盖目标
+ *
+ * 解决的问题：直写目标路径时若进程在写入中途崩溃/断电，目标文件会停留在
+ * 被截断的半成品状态。对「唯一真理源」类文件而言这等于数据永久损坏。
+ * rename 在同一文件系统内是原子操作——目标要么是旧内容，要么是完整新内容。
+ *
+ * 适用：内容为唯一真理源且损坏后不可重建的文件
+ *   - 设定记忆 md（文件即真理源，记忆库只是派生索引）
+ *
+ * 不适用（用了反而制造 Bug）：
+ *   - 锁文件：语义要求排他创建，rename 会静默覆盖他人持有的锁
+ *   - 面向用户的文件写工具：rename 更换 inode，破坏硬链接、符号链接目标、
+ *     以及编辑器/监视器对该 inode 的订阅
+ *
+ * 临时文件与目标同目录，确保 rename 不跨设备（跨设备 rename 会抛 EXDEV）。
+ * 调用方需自行保证目标目录已存在。
+ */
+import { writeFile, rename } from 'node:fs/promises';
+/**
+ * 原子写入文本文件（UTF-8）
+ *
+ * @param filePath - 目标文件绝对路径（其所在目录须已存在）
+ * @param content - 待写入的文本内容
+ */
+export async function atomicWriteFile(filePath, content) {
+    const tmpPath = `${filePath}.tmp`;
+    await writeFile(tmpPath, content, 'utf-8');
+    await rename(tmpPath, filePath);
+}
+//# sourceMappingURL=atomicWrite.js.map

package/dist/utils/atomicWrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicWrite.js","sourceRoot":"","sources":["../../src/utils/atomicWrite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB,EAAE,OAAe;IACrE,MAAM,OAAO,GAAG,GAAG,QAAQ,MAAM,CAAC;IAClC,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/utils/backgroundTask.d.ts

@@ -0,0 +1,38 @@
+/** 后台任务累计统计快照（宿主读后台健康度，纯只读） */
+export interface BackgroundTaskStats {
+    /** 在途任务数（含排队中的） */
+    pending: number;
+    /** 成功完成数（累计） */
+    completed: number;
+    /** 失败数（累计，未被业务侧消化的） */
+    failed: number;
+}
+/**
+ * 启动一个后台任务（不阻塞调用方）。统一计数 + 兜底失败日志 + 并发槽位控制。
+ * 保留「调用即纳入在途计数」的契约——无论立即执行还是排队等待。
+ *
+ * @param label 任务标签（日志/观测区分用途）
+ * @param factory 返回业务 Promise 的工厂；内部不要自行 `catch`，交给本门面统一兜底计数
+ * @param onFailure 失败时的业务侧补救（如宿主事件 emit）；缺省仅记日志
+ */
+export declare function backgroundTask(label: string, factory: () => Promise<unknown>, onFailure?: (err: unknown) => void): void;
+/** 读取后台任务累计统计快照（只读副本，宿主可观测后台健康度） */
+export declare function getBackgroundTaskStats(): BackgroundTaskStats;
+/**
+ * 等待所有在途后台任务完成（带超时保护，防止任务永不返回阻塞 close）。
+ * Agent.close() 必须调用此函数——否则后台命中刷新/摘要生成等任务可能在 storage 关闭后 upsert 失效。
+ *
+ * @param timeoutMs 超时时间（毫秒），默认 5000ms
+ * @returns **等待开始时**的在途任务数（0 = 进入本函数时无在途任务）。
+ *   ⚠️ 该值是「曾经在途」而非「已等到完成」：超时放弃剩余任务时返回值仍为初始在途数，
+ *   不代表实际完成数。调用方据此判断「是否有在途任务」是正确的（如 `Agent.close()` 的
+ *   `awaited > 0`），但**不可当作已完成计数**使用。
+ */
+export declare function awaitBackgroundTasks(timeoutMs?: number): Promise<number>;
+/**
+ * 重置模块级状态（仅测试使用，生产代码禁止调用）。
+ * 清理 activeCount、pendingQueue、stats，确保测试用例间状态隔离。
+ * @internal
+ */
+export declare function _resetBackgroundTaskState(): void;
+//# sourceMappingURL=backgroundTask.d.ts.map

package/dist/utils/backgroundTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundTask.d.ts","sourceRoot":"","sources":["../../src/utils/backgroundTask.ts"],"names":[],"mappings":"AAaA,+BAA+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAmBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC/B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GACjC,IAAI,CAWN;AA4CD,oCAAoC;AACpC,wBAAgB,sBAAsB,IAAI,mBAAmB,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB5E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD"}