@zooique/memora 2.0.3 → 3.0.0

package/dist/skill/skillManager.js

@@ -1,34 +1,51 @@
 /**
- * 技能管理器 — 继承 ConfigResourceManager，扩展 trigger 正则匹配 + 运行时注册
- *
- * 职责：
- *   - 启动时扫描 configDir/skills/ 目录
- *   - 通过关键词匹配 + trigger 正则选择技能
- *   - 支持运行时 register() 注入技能
- *
- * 设计原则：
- *   - 单层目录：<configDir>/skills/（宿主负责汇总全局+项目级技能到 configDir）
- *   - 与 PersonaManager 共享 ConfigResourceManager 基类（消除重复扫描/匹配/生命周期）
- *
- * 触发词说明：
- *   每个 skill 文件的 frontmatter 声明 keywords（逗号分隔）和 trigger（触发正则，可选）。
- *   skill 文件命名规范：`<技能名>.md`（如"去AI味.md""审视角.md""写代码.md"）。
+ * 技能管理器 — 继承 ConfigResourceManager。
+ * 单层目录 <configDir>/skills/（宿主负责汇总全局+项目级技能到 configDir）。
+ * 三级渐进披露：L1 元数据常驻 / L2 read_skill 按需 / L3 resources+scripts。
  */
 import { logger } from '../logging/logger.js';
 import { configError } from '../utils/errors.js';
 import { ConfigResourceManager } from '../utils/configResourceManager.js';
-import { parseTrigger, parseKeywords } from '../utils/scanner.js';
+import { scanMarkdownDir } from '../utils/scanner.js';
+import { parseFrontmatter } from '../utils/frontmatter.js';
+import { discoverSkillLayer3, projectDiscoveredLayer3, resolveSkillDir, findLayer3Resource, resolveLayer3ResourcePath, resolveLayer3ScriptPath, } from '../skill/skillLayer3.js';
+import { readFileCapped, existsSyncSafe } from '../utils/fileSafe.js';
 /**
- * 技能匹配最低激活阈值
- *
- * score < 此阈值的匹配不激活技能（避免低匹配度噪音）。
- * 与 PersonaManager 的 KEYWORD_HIGH_CONFIDENCE_THRESHOLD (0.3) 一致。
+ * L1 阈值保护：技能数超过此值时压缩 L1 描述为 20 字摘要。
+ * SSOT：全局技能（SkillManager）与角色包内嵌技能（RolePackManager）共用同一渐进披露阈值。
  */
-const SKILL_MATCH_MIN_SCORE = 0.3;
+export const L1_COMPRESSED_THRESHOLD = 30;
+/** L1 阈值保护：技能数超过此值时切换为 list_skills 工具动态查询（SSOT 同一来源） */
+export const L1_LIST_TOOL_THRESHOLD = 50;
+/**
+ * 解析来源层（agent / project）：SSOT 收口——仅接受合法枚举值，
+ * 非法/缺失回退 'project'（与历史默认一致，防御 frontmatter 手误导致契约外值透传宿主）。
+ */
+function resolveLayer(raw) {
+    return raw === 'agent' ? 'agent' : 'project';
+}
 /**
  * 技能管理器
  */
 export class SkillManager extends ConfigResourceManager {
+    /**
+     * 已被用户技能覆盖的内置技能名。
+     *
+     * 与基类 runtimeNames 记账互补：runtimeNames 说明「该项无内核扫描真理源」，
+     * 本集合说明「同名磁盘（内置）项被用户版覆盖」——reload 扫描回同名内置时
+     * 以用户版为准（基类 isUserOverride 钩子）。load()（纯内置重载）时一并清空。
+     */
+    userOverrides = new Set();
+    /**
+     * 禁用的技能名集合：宿主配置形态启停。命中者
+     * get() 返回 null（read_skill/L3 全链路经 get 短路）+ buildSkillList 不枚举。
+     * list 快照保持完整——宿主 UI 依据同名设置标注「已禁用」徽章（对 LLM 静默）。
+     *
+     * **作用域 = 全局技能池（内置/用户）**：角色包内嵌技能由 RolePackManager 持有、
+     * 不经本管理器（其启用判据 = 角色是否激活），对本集**免疫**——角色包技能
+     * 「随角色启停、不可按名禁用」（见宿主 skillAggregation 定案声明）。
+     */
+    disabledNames = new Set();
     /**
      * @param configDir 配置目录（技能文件在 <configDir>/skills/ 下）
      */
@@ -44,59 +61,54 @@ export class SkillManager extends ConfigResourceManager {
     async load() {
         return this.loadItems();
     }
-    /**
-     * 根据用户输入匹配最合适的技能
-     *
-     * 匹配流程：
-     *   1. 先检查所有 trigger 正则，命中直接返回（最高优先级，score=1.0）
-     *   2. 再检查关键词匹配（复用基类 findBestKeywordMatch）
-     *   3. 关键词得分 < SKILL_MATCH_MIN_SCORE 的匹配不激活
-     *
-     * @param userInput 用户输入文本
-     * @returns 匹配结果，无匹配返回 null
-     */
-    match(userInput) {
-        if (this.items.length === 0)
-            return null;
-        // 1. trigger 正则匹配（最高优先级）
-        for (const skill of this.items) {
-            if (skill.trigger?.test(userInput)) {
-                logger.debug({ skill: skill.name, trigger: skill.trigger.source }, '技能触发器匹配');
-                return { skill, score: 1.0 };
-            }
-        }
-        // 2. 关键词匹配（委托基类）
-        const best = this.findBestKeywordMatch(userInput, SKILL_MATCH_MIN_SCORE);
-        if (!best)
-            return null;
-        logger.debug({ matched: best.item.name, score: best.score }, '技能关键词匹配');
-        return { skill: best.item, score: best.score };
-    }
     // ── 公共方法 ──────────────────────────────────────
     /**
      * 根据技能名获取技能
      */
     get(name) {
+        // 禁用技能对 LLM 不可见：get=null → read_skill 报未找到、L3 全链路短路
+        if (this.disabledNames.has(name))
+            return null;
         return this.items.find((s) => s.name === name) ?? null;
     }
     /**
-     * 删除技能（向后兼容别名，委托基类 deleteItem）
+     * 设置禁用技能清单（配置形态启停；装配期一次性注入，可由 reloadConfig 重设）
+     *
+     * @param names 禁用的技能名（命中者 L1/L2/L3 全不可用；对 LLM 语义 = 不存在）
      */
-    deleteSkill(name) {
-        return this.deleteItem(name);
+    setDisabledSkills(names) {
+        this.disabledNames.clear();
+        for (const name of names)
+            this.disabledNames.add(name);
+        logger.info({ count: this.disabledNames.size }, '技能禁用集已设置');
     }
     /**
-     * 注册运行时注入的技能
+     * 当前禁用技能名快照（只读）——宿主 UI 渲染「已禁用」徽章的真源。
+     *
+     * 为何由内核提供而非宿主自读一份配置：**实际生效的禁用集在内核**（`disabledNames` 是
+     * `get()` / `buildSkillList()` 的判据）。宿主若另读 workspace 配置，会出现「UI 标注的」
+     * 与「实际生效的」两源分叉（如 reloadConfig 重设后不同步）。
      *
-     * 供 Agent.addSkill() 调用：宿主程序可在 init() 之后动态注入技能。
-     * 重复注册同名技能会被拒绝。
+     * ⚠️ 对 **LLM** 仍然静默：本 getter 仅供宿主 UI 对照显示，
+     * **不得**出现在工具返回、L1 清单或任何进入上下文的文本里（语义 = 技能不存在）。
+     */
+    get disabledSkillNames() {
+        return [...this.disabledNames];
+    }
+    /**
+     * 注册运行时注入的技能（如 confirmConfigSuggestion 持久化技能）；同名重复注册被拒绝。
+     *
+     * 必须走基类 registerRuntimeItem 登记——直接 push 进 items 会被 reload() 的磁盘扫描结果覆盖
+     * （运行时注入项无磁盘真理源，reload 保留依赖 runtimeNames 记账；设定记忆不写记忆库）。
      */
     register(skill) {
         if (this.items.some((s) => s.name === skill.name)) {
-            throw configError(`技能 "${skill.name}" 已存在，不能重复注册`, undefined, ['请使用不同的技能名称']);
+            throw configError(`技能 "${skill.name}" 已存在，不能重复注册`, undefined, [
+                '请使用不同的技能名称',
+            ]);
         }
-        this.items.push(skill);
-        logger.info({ name: skill.name, keywords: skill.keywords.length }, '技能已注册（运行时注入）');
+        this.registerRuntimeItem(skill);
+        logger.info({ name: skill.name }, '技能已注册（运行时注入）');
     }
     /**
      * 构建 system prompt 中的技能段
@@ -109,16 +121,255 @@ export class SkillManager extends ConfigResourceManager {
             return '';
         return `【当前技能】${skill.name}\n${skill.content}`;
     }
+    /**
+     * 格式化单个技能为 Prompt 字符串
+     *
+     * SSOT：所有技能展示（System Prompt、Tool 回调）必须走此方法保证格式统一。
+     * compress=true 时描述截断至 20 字（技能较多时的 token 节约）。
+     */
+    static formatSkillForPrompt(skill, fallbackName, compress = false) {
+        const label = skill?.name || fallbackName || '';
+        if (!label)
+            return '';
+        let desc = '';
+        if (skill?.description) {
+            const descText = compress && skill.description.length > 20
+                ? skill.description.slice(0, 20) + '…'
+                : skill.description;
+            desc = `：${descText}`;
+        }
+        const hasL3 = skill?.layer3 && (skill.layer3.resources.length > 0 || skill.layer3.scripts.length > 0);
+        const l3Tag = hasL3 ? '（含资源/脚本）' : '';
+        return `- ${label}${desc}${l3Tag}`;
+    }
+    /**
+     * 对 **LLM 可见**的技能条目——渐进披露可用性判据的**唯一真理源**。
+     *
+     * 判据两条（缺一不可）：
+     *   ① 有 `description`（渐进披露的唯一依据：缺则模型不知何时激活）；
+     *   ② 未命中 `disabledNames`（启停：对模型语义 = 不存在）。
+     *
+     * ⚠️ **L1 枚举**（`buildSkillList`）与 **`list_skills` 工具侧**（assembler 注入回调）
+     * 必须共用本方法：两者同为 **LLM 消费**、是同一份清单的两个交付通道，
+     * 判据一旦分叉即「双轨镜像」（同一模型在两条路径看到不同技能集）。
+     * 教训：启停/可用性过滤须两侧同步——单侧漏改会让禁用技能在另一通道仍可见。
+     *
+     * 注：本方法**不**过滤 L3 归属，也不做排序——排序由调用方决定（两通道排序本就不同）。
+     */
+    listAvailable() {
+        return this.items.filter((s) => s.description?.trim() && !this.disabledNames.has(s.name));
+    }
+    /**
+     * 构建全局技能清单块（渐进披露 L1），与角色包技能清单同格式。
+     * 两级技能同构：通用技能全局激活，角色包技能随角色激活；LLM 按需调 read_skill 读正文（L2）。
+     * 含 resources/scripts 的技能附加 "(含资源/脚本)" 标记。
+     *
+     * L1 阈值保护（与角色包 buildSystemPrompt 同构）：
+     *   ≤ 30 技能：完整 L1（name + full description）
+     *   31-50 技能：压缩 L1（name + 20 字摘要）
+     *   > 50 技能：切换 list_skills 工具动态查询，不在 system prompt 枚举
+     */
+    buildSkillList() {
+        // 可用性 + 禁用过滤**收口于 listAvailable**（LLM 可见集唯一真理源，
+        // 与 list_skills 工具侧共用；此处不再自写 filter，防两通道判据分叉）。
+        // 不进清单者由宿主 UI 显式标注而非静默隐藏：「未生效」= 健康徽章 / 禁用 = 「已禁用」徽章。
+        const candidates = this.listAvailable();
+        if (candidates.length === 0)
+            return '';
+        const skillCount = candidates.length;
+        // L1 阈值保护：超上限不枚举，提示用 list_skills 工具动态查询
+        if (skillCount > L1_LIST_TOOL_THRESHOLD) {
+            return `【通用技能（${skillCount} 个，数量较多，使用 list_skills 工具查询具体清单）】`;
+        }
+        const compressed = skillCount > L1_COMPRESSED_THRESHOLD;
+        const listed = candidates
+            .map((skill) => SkillManager.formatSkillForPrompt(skill, undefined, compressed))
+            .filter(Boolean);
+        if (listed.length === 0)
+            return '';
+        const modeNote = compressed
+            ? '（技能较多，描述已压缩至 20 字，可用 read_skill 读取完整正文）'
+            : '（渐进披露 L1，按需调用 read_skill 读取正文）';
+        return `【通用技能${modeNote}】\n${listed.join('\n')}`;
+    }
+    /**
+     * 校验单技能文件（写→验→用闭环，宿主 UI 校验入口）。
+     * 复用 parser frontmatter 解析做单一真理源，不重写解析；只做确定性结构检查，不做语义 schema。
+     * 判级（三点强化）：
+     *   - error：无 frontmatter / description 缺失/空（渐进披露唯一依据，缺则技能不可用）/ 正文空
+     *   - warning：layer 非法（回退 project）
+     */
+    async validateFile(filePath) {
+        const issues = [];
+        // 读取收口于 fileSafe.readFileCapped（统一长度上限保护，与角色包内容读取同级）
+        const raw = await readFileCapped(filePath);
+        if (raw === null) {
+            return {
+                ok: false,
+                issues: [{ level: 'error', field: 'file', message: '无法读取技能文件' }],
+            };
+        }
+        const { frontmatter, body } = parseFrontmatter(raw);
+        // 无 frontmatter 结构（fallback：整体落入 body 且无任何键值）→ 不被识别
+        if (Object.keys(frontmatter).length === 0 && body === raw) {
+            issues.push({
+                level: 'error',
+                field: 'frontmatter',
+                message: '缺少 frontmatter（文件需以 --- 开头声明 name/description）',
+            });
+        }
+        const desc = frontmatter['description'];
+        if (!desc || !desc.trim()) {
+            issues.push({
+                level: 'error',
+                field: 'description',
+                message: '缺少 description：渐进披露不暴露，模型不知何时激活此技能',
+            });
+        }
+        if (!body.trim()) {
+            issues.push({ level: 'error', field: 'body', message: '技能正文为空，无可执行指令' });
+        }
+        const layer = frontmatter['layer'];
+        if (layer && layer !== 'agent' && layer !== 'project') {
+            issues.push({
+                level: 'warning',
+                field: 'layer',
+                message: `layer 值「${layer}」非法，将回退为 project`,
+            });
+        }
+        return { ok: issues.every((i) => i.level !== 'error'), issues };
+    }
+    // ── L3 资源/脚本访问 ──────────────────────────────────
+    /**
+     * 读取技能的 L3 资源文件（渐进披露 L3）；资源须在 layer3 中且路径不逃逸其来源子目录
+     * （resources/ 或 references/，兼容主流 references/ 辅助文档目录）
+     */
+    async readResource(skillName, resourcePath) {
+        const skill = this.get(skillName);
+        if (!skill)
+            return null;
+        // 白名单前置：资源须已由扫描登记在 layer3 中（未登记 → 静默 null）
+        if (!findLayer3Resource(skill.layer3, resourcePath))
+            return null;
+        // 路径解析（按条目来源子目录选基目录 + 路径穿越防护）收口于 skillLayer3（SSOT）
+        const skillDir = resolveSkillDir(skill.filePath);
+        const resourceFullPath = resolveLayer3ResourcePath(skillDir, skill.layer3, resourcePath);
+        if (!resourceFullPath) {
+            logger.warn({ skill: skillName, resourcePath }, 'read_resource 路径穿越被阻止');
+            return null;
+        }
+        // 读取收口于 fileSafe.readFileCapped：长度上限保护与角色包内嵌技能同级（差异点取更全面形态）
+        const content = await readFileCapped(resourceFullPath);
+        if (content === null) {
+            logger.warn({ skill: skillName, resourcePath }, '读取 L3 资源失败');
+            return null;
+        }
+        return content;
+    }
+    /**
+     * 列出技能的 L3 资源
+     */
+    listResources(skillName) {
+        const skill = this.get(skillName);
+        return skill?.layer3?.resources ?? [];
+    }
+    /**
+     * 列出技能的 L3 脚本
+     */
+    listScripts(skillName) {
+        const skill = this.get(skillName);
+        return skill?.layer3?.scripts ?? [];
+    }
+    /**
+     * 获取脚本的完整路径（须在 layer3 中且路径不逃逸 scripts/ 目录）
+     */
+    getScriptPath(skillName, scriptPath) {
+        const skill = this.get(skillName);
+        if (!skill)
+            return null;
+        const skillDir = resolveSkillDir(skill.filePath);
+        const fullPath = resolveLayer3ScriptPath(skillDir, skill.layer3, scriptPath);
+        if (!fullPath)
+            return null;
+        // 存在性校验与角色包内嵌技能对齐（差异点取更全面形态）：防止交出指向缺失脚本的路径
+        return existsSyncSafe(fullPath) ? fullPath : null;
+    }
     // ── 基类抽象方法实现 ──────────────────────────────
-    createEntry(entry) {
+    /**
+     * 加载用户目录的技能（宿主调用，用于扩展内置技能池）
+     *
+     * 与 load() 的区别：
+     * - load() 从 configDir/skills/ 扫描内置技能（有磁盘真理源）
+     * - loadExtraDir() 从额外目录扫描用户技能（运行时注入，reload 时保留）
+     *
+     * 设计哲学：内核保持单一真理源（configDir/skills/），宿主负责扩展用户目录。
+     * 用户技能通过 registerRuntimeItem 注入，reload() 时会保留（同名冲突以磁盘为准）。
+     *
+     * @param dir 用户技能目录（如 ~/.memora/skills/）
+     * @returns 加载的技能数量
+     */
+    async loadExtraDir(dir) {
+        const entries = await scanMarkdownDir(dir);
+        let count = 0;
+        for (const entry of entries) {
+            // 已是用户覆盖项（本会话此前注入过）：幂等跳过，避免同名双存重复注入
+            if (this.userOverrides.has(entry.name))
+                continue;
+            const existingIdx = this.items.findIndex((s) => s.name === entry.name);
+            const skill = await this.createEntry(entry);
+            if (!skill)
+                continue;
+            // 同名覆盖（对齐主流「用户可覆盖内置」）：用户版生效——
+            // 移除内置版（磁盘真理源，reload 可重扫）、
+            // 登记 userOverrides 供 reload 保持用户版胜出（基类 isUserOverride 钩子）；
+            // 不覆盖则用户同名技能会被静默丢弃。
+            if (existingIdx >= 0) {
+                this.items.splice(existingIdx, 1);
+                this.userOverrides.add(entry.name);
+                logger.info({ name: entry.name }, '用户技能覆盖内置技能');
+            }
+            this.registerRuntimeItem(skill);
+            count++;
+        }
+        logger.info({ count, dir }, '用户技能加载完成');
+        return count;
+    }
+    /**
+     * 用户覆盖声明：userOverrides 中记录的同名技能，reload 扫描回内置版时
+     * 用户版胜出、内置版剔除（基类 retainRuntimeItems 消费）。其余同名不声明——
+     * 保持基类默认「磁盘（内置）赢」语义（如 register() 运行时技能撞内置仍内置赢）。
+     */
+    isUserOverride(name) {
+        return this.userOverrides.has(name);
+    }
+    /**
+     * load()（纯内置重载）后 userOverrides 一并清空——与基类 runtimeNames 同寿命：
+     * load() 整体替换 items、运行时注入全丢，账目须同步；否则残留名字会在未来
+     * loadExtraDir 同名时被幂等跳过（见其开头判定），用户技能静默丢失。
+     */
+    onAfterLoad() {
+        this.userOverrides.clear();
+    }
+    async createEntry(entry) {
+        // L3 隔离纪律（对齐 Claude Code 主流）：仅「文件夹形态」（入口为 SKILL.md）才发现
+        // resources/ scripts/。顶层裸 .md 单文件技能目录 = 技能池共享根，同级扫描会把别的技能的
+        // resources/scripts 误归给自己 → 污染。故裸 .md 为纯 L1/L2，需要 L3 资源/脚本必须用文件夹+SKILL.md。
+        //
+        // 该规则与角色包内嵌技能**逐字同构**；发现与投影均已收口于 skillLayer3
+        // （discoverSkillLayer3 + projectDiscoveredLayer3，SSOT）——两侧各写一遍投影，
+        // 改一处即静默漂移。
+        const discovered = await discoverSkillLayer3(entry.filePath);
+        const layer3 = projectDiscoveredLayer3(discovered);
         return {
             name: entry.name,
-            keywords: parseKeywords(entry.frontmatter),
-            trigger: parseTrigger(entry.frontmatter),
             description: entry.frontmatter['description'],
             content: entry.body.trim(),
             filePath: entry.filePath,
-            layer: 'project',
+            // 来源层（agent / project）：解析 frontmatter.layer，非法/缺失回退 project（与现状默认一致）。
+            // ⚠️ 展示语义不由本字段单独决定：宿主以 filePath 前缀为主判据，
+            // 本字段仅在无路径/未命中时兜底（project → 用户源，agent → 内置源）。
+            layer: resolveLayer(entry.frontmatter['layer']),
+            layer3,
         };
     }
 }

package/dist/skill/skillManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"skillManager.js","sourceRoot":"","sources":["../../src/skill/skillManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skillManager.js","sourceRoot":"","sources":["../../src/skill/skillManager.ts"],"names":[],"mappings":"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"}

package/dist/skill/skillScriptRunner.d.ts

@@ -0,0 +1,97 @@
+import type { CodeExecutionResult } from '../code-exec/types.js';
+import type { ScriptRuntime } from '../utils/scanner.js';
+/** 脚本执行结果（= CodeExecutionResult，复用代码执行结果形态，SSOT 不重复定义） */
+export type ScriptExecutionResult = CodeExecutionResult;
+/**
+ * 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 declare function guardWindowsShellScript(scriptPath: string, runtime: ScriptRuntime, platform: NodeJS.Platform): string | null;
+/**
+ * 执行技能脚本：在隔离子进程中运行，收集 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 declare function runSkillScript(scriptPath: string, runtime: ScriptRuntime, args?: string[], timeoutMs?: number, cwd?: string, nodePath?: string): Promise<ScriptExecutionResult>;
+/**
+ * 兜底判定：python runtime 在 Windows 下进入兜底链（纯函数，平台参数化可测）
+ *
+ * @param runtime  脚本运行时
+ * @param platform 当前平台（process.platform；参数化便于测试）
+ * @returns 是否应进入「py -3 → cmd /c python」兜底链
+ */
+export declare function shouldFallbackPythonToPy(runtime: ScriptRuntime, platform: NodeJS.Platform): boolean;
+/**
+ * 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 declare function isPythonUnavailable(result: ScriptExecutionResult & {
+    enoent: boolean;
+}, platform: NodeJS.Platform): boolean;
+/** formatExecutionResult 的三态标签配置：前缀与详情文案（run_skill_script / run_code 各自定制） */
+export interface ExecutionResultFormatLabels {
+    /** 三态前缀标签（'SCRIPT' → [SCRIPT_TIMEOUT]/[SCRIPT_ERROR]；'CODE' → [CODE_TIMEOUT]/[CODE_ERROR]） */
+    kind: 'SCRIPT' | 'CODE';
+    /** 超时详情文案（如「脚本执行超时（超过 120s）」） */
+    timeoutDetail: string;
+    /** 失败详情文案（如「代码执行失败」） */
+    errorDetail: string;
+}
+/**
+ * 执行结果三态格式化（run_skill_script 与 run_code 共用的格式化真理源）
+ *
+ * 超时 / 非零退出码 / 成功三态；前缀与文案由 labels 定制，成功分支统一
+ * 「无输出兜底 + stderr 附加」。stdout/stderr 须由调用方先行净化。
+ *
+ * @param result 执行结果
+ * @param labels 三态前缀标签与详情文案
+ * @returns 格式化后的可读字符串（供工具返回值注入 LLM 上下文）
+ */
+export declare function formatExecutionResult(result: CodeExecutionResult, labels: ExecutionResultFormatLabels): string;
+/**
+ * 格式化脚本执行结果为可读字符串（供 tool 返回值）：formatExecutionResult 的 SCRIPT 变体
+ *
+ * 超时文案的「超过 Ns」取本次**实际**超时（经 normalizeTimeoutMs 钳制），不再恒写上限 600s：
+ * 默认 60s 超时却报「超过 600s」是对 LLM 的谎报，会诱导它盲目调大 timeout_ms 重试。
+ *
+ * @param result 执行结果
+ * @param timeoutMs 本次实际超时（毫秒）；省略则用 DEFAULT_TIMEOUT_MS（与执行侧默认同源）
+ */
+export declare function formatScriptResult(result: ScriptExecutionResult, timeoutMs?: number): string;
+//# sourceMappingURL=skillScriptRunner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skillScriptRunner.d.ts","sourceRoot":"","sources":["../../src/skill/skillScriptRunner.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,0DAA0D;AAC1D,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAoBxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACxB,MAAM,GAAG,IAAI,CAaf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,MAAM,EAAO,EACnB,SAAS,GAAE,MAA2B,EACtC,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAgHhC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACxB,OAAO,CAET;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,qBAAqB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EACnD,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACxB,OAAO,CAGT;AAgCD,8EAA8E;AAC9E,MAAM,WAAW,2BAA2B;IAC1C,8FAA8F;IAC9F,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,2BAA2B,GAClC,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,MAA2B,GACrC,MAAM,CAMR"}