@yixinkj/inquiry-opening-coach-cli 0.3.1

package/launcher-core.js

@@ -0,0 +1,1457 @@
+/**
+ * 译心独立 Skill 系列 npm 启动器的共享内核。
+ *
+ * 为什么要有这个文件：
+ * priority-buyer-alert / public-customer-reactivation / review-customer-insight 三份
+ * index.js 里有 700 行以上逐字相同的启动逻辑，一直靠手工复制保持同步。手工同步已经
+ * 出过事故——给三份都加「清理旧运行时」的日志时，日志前缀写成了模块级常量 SKILL_ID，
+ * 而只有 priority-buyer-alert 定义了它，另外两个发布后一启动就 ReferenceError，整个
+ * 启动中止。启动器是用户机器上跑的第一段代码，它崩了没有任何兜底。
+ *
+ * 因此本文件有一条不可让步的规矩：
+ *   **这里的每个函数都不读取任何模块级配置常量。**
+ * SKILL_ID、SKILL_VERSION、RUNTIME_VERSION、版本目录、日志前缀……全部由调用方显式传入。
+ * 少传就在调用点抛出一句中文错误（见 requireOption），而不是等到某条冷路径才炸成
+ * ReferenceError。本文件里唯一的模块级常量是一个与具体 Skill 无关的数值默认值。
+ *
+ * 另外两条边界：
+ * - 不引入任何第三方依赖，只用 node: 内置模块。启动器要在 npx 冷启动、网络不确定的
+ *   环境下跑，多一个依赖就多一个装不上的理由。
+ * - 不做运行时远程下载来获取自身代码。业务运行时的下载是本文件的职责之一，但那条链路
+ *   有清单 + SHA256 双重校验；启动器自己的代码必须随 npm 包一起落地。
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 同机保留的运行时版本数（含当前正在用的这一版）。
+ *
+ * 每升一版就多留一份二进制，从来没人删。真机上 public-customer-reactivation 攒了 16 份
+ * 共 94M，三个 Skill 合计 164M，而任何时刻真正被执行的只有一份。
+ * 不设成 1 是因为同一台机器会交替跑不同 dist-tag（例如 latest 与 beta），
+ * 只留当前版会让每次切换都重新下载一遍。
+ *
+ * 这是本文件里唯一的模块级常量：它是一个跨 Skill 通用的策略数值，不含任何 Skill 身份，
+ * 复制到第四个仓也不会变。所有带 Skill 身份的值一律走参数。
+ */
+const RUNTIME_VERSIONS_TO_KEEP = 2;
+
+/**
+ * 把「调用方漏传配置」变成一句能读懂的中文错误，而不是运行到一半的 ReferenceError。
+ *
+ * 这就是那次事故的正解：日志前缀漏传时，应该在函数入口立刻说「缺少 logPrefix」，
+ * 而不是等到真的删掉了旧版本、走到打印那一行时才崩掉整个启动。
+ * @param {*} value 调用方传入的值。
+ * @param {string} name 参数名，直接出现在报错里。
+ * @returns {*} 原值。
+ */
+function requireOption(value, name) {
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`launcher-core 缺少必填参数 ${name}：共享内核不读取任何模块级常量，请由调用方显式传入。`);
+  }
+  return value;
+}
+
+/* ------------------------------------------------------------------ *
+ * 一、命令行参数
+ * ------------------------------------------------------------------ */
+
+/**
+ * 摘出 `--skill-path`，其余参数原样转交原生运行时。
+ *
+ * 之所以由 npm 启动器自己解析而不是透传：这个参数决定的是「本次要同步哪一份 SKILL.md」，
+ * 属于启动器的职责，原生运行时既不认识也不该认识它。
+ * @param {string[]} args 原始命令行参数。
+ * @returns {{skillPath: string | null, forwardedArgs: string[]}} 解析出的路径与待转交参数。
+ */
+function extractSkillPath(args) {
+  let skillPath = null;
+  const forwardedArgs = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--skill-path') {
+      if (!args[index + 1]) throw new Error('--skill-path 缺少 SKILL.md 路径');
+      skillPath = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--skill-path=')) {
+      skillPath = arg.slice('--skill-path='.length);
+      continue;
+    }
+    forwardedArgs.push(arg);
+  }
+  return { skillPath, forwardedArgs };
+}
+
+/**
+ * 判断参数中是否已经显式提供某个长选项。
+ *
+ * 必须同时认 `--x value` 和 `--x=value` 两种写法：只认一种时，模型换个写法就绕过了
+ * 「不允许模板文件旁路」这类硬门禁。
+ * @param {string[]} args 参数数组。
+ * @param {string} option 以 `--` 开头的选项名。
+ * @returns {boolean} 是否存在。
+ */
+function hasOption(args, option) {
+  return args.some((arg) => arg === option || arg.startsWith(`${option}=`));
+}
+
+/**
+ * 判断是否为纯帮助请求。帮助必须在 Skill OTA 和 Runtime 初始化前返回，
+ * 避免一个只读命令改写本地状态、甚至触发一次几十兆的下载。
+ *
+ * `emptyArgsMeansHelp` 必须由调用方显式声明，因为三个仓在这里本来就不一致：
+ * priority-buyer-alert 把「不带任何参数」当帮助（它没有可用的默认动作），
+ * public-customer-reactivation 不这么认为。把它做成默认值会悄悄改掉某一边的行为，
+ * 所以宁可让每个调用点自己写清楚。
+ * @param {string[]} args 原始命令行参数。
+ * @param {{emptyArgsMeansHelp: boolean}} options 空参数是否视为帮助。
+ * @returns {boolean} 是否请求帮助。
+ */
+function isHelpRequest(args, { emptyArgsMeansHelp } = {}) {
+  if (typeof emptyArgsMeansHelp !== 'boolean') {
+    throw new Error('launcher-core 缺少必填参数 emptyArgsMeansHelp：三个仓对「空参数是否算帮助」的判断本就不同，必须显式声明。');
+  }
+  if (emptyArgsMeansHelp && args.length === 0) return true;
+  return args.some((arg) => arg === '--help' || arg === '-h');
+}
+
+/* ------------------------------------------------------------------ *
+ * 二、Skill 元数据与版本
+ * ------------------------------------------------------------------ */
+
+/**
+ * 只读取 SKILL.md 顶部 frontmatter 里的简单键值。
+ *
+ * 这里故意不接 YAML 库：启动器不能有第三方依赖，而 frontmatter 里真正被使用的只有
+ * name / description / version 三个单行字段。引号是可选的，两种引号都要脱掉，
+ * 否则 `name: "重点买家预警"` 会连引号一起参与身份比对，把自己挡在门外。
+ * @param {string} content SKILL.md 全文。
+ * @returns {Record<string, string>} frontmatter 键值；没有 frontmatter 时返回空对象。
+ */
+function parseSkillMetadata(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return {};
+  const metadata = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!field) continue;
+    let value = field[2].trim();
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+    metadata[field[1]] = value;
+  }
+  return metadata;
+}
+
+/**
+ * 解析三段式版本号；任何不合规的写法都返回空值。
+ * @param {string} version 版本字符串。
+ * @returns {number[] | null} [major, minor, patch]。
+ */
+function parseSemver(version) {
+  const match = String(version || '').trim().match(/^(\d+)\.(\d+)\.(\d+)$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+/**
+ * 比较两个版本号。
+ *
+ * 解析不出来的版本一律视为「更旧」，这样缺失或畸形的本地版本会被正常升级覆盖，
+ * 而不是因为比不出大小就卡住升级链路。两边都解析不出来时视为相等，避免反复重写。
+ * @param {string | null} left 左值。
+ * @param {string | null} right 右值。
+ * @returns {number} -1 / 0 / 1。
+ */
+function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a && !b) return 0;
+  if (!a) return -1;
+  if (!b) return 1;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * 生成 Skill 版本标记文件的内容。
+ *
+ * 写入和比对必须用同一个函数生成同一串字节（含结尾换行）：曾经写入时带换行、比对时
+ * 不带，导致每次启动都判定为「有变化」，于是每次都触发一次 OTA 并要求用户重跑。
+ * @param {string} version 目标版本。
+ * @returns {string} 标记文件内容。
+ */
+function versionMarkerContent(version) {
+  return `${JSON.stringify({ version: requireOption(version, 'version') }, null, 2)}\n`;
+}
+
+/**
+ * 读取本地已安装的 Skill 版本，优先信任版本标记文件。
+ *
+ * 为什么不直接读 SKILL.md 的 frontmatter：展示名和版本字段会随产品调整改写，
+ * 而标记文件是启动器自己写的、格式由自己控制。标记读不到时才退回 registry 里的版本，
+ * 让没有标记文件的历史安装也能被正确升级。
+ * @param {string} skillDir SKILL.md 所在目录。
+ * @param {{markerFileName: string, registryVersion?: string | null}} options 标记文件名与回退版本。
+ * @returns {string | null} 本地版本。
+ */
+function readInstalledSkillVersion(skillDir, { markerFileName, registryVersion = null } = {}) {
+  requireOption(markerFileName, 'markerFileName');
+  const markerPath = path.join(skillDir, markerFileName);
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    return marker.version || registryVersion || null;
+  } catch {
+    return registryVersion || null;
+  }
+}
+
+/**
+ * 校验 `--skill-path` 指向的确实是一份存在的 SKILL.md，并返回绝对路径。
+ *
+ * basename 校验不能省：这个参数后面会被当成覆盖写入的目标，指错了就是直接改写用户
+ * 工作区里的其它文件。大小写不敏感是因为 macOS / Windows 上 `skill.md` 同样能打开。
+ * @param {string} skillPath 调用方给出的路径。
+ * @returns {string} 解析后的绝对路径。
+ */
+function resolveSkillMdPath(skillPath) {
+  const resolvedSkillPath = path.resolve(requireOption(skillPath, 'skillPath'));
+  if (path.basename(resolvedSkillPath).toLowerCase() !== 'skill.md') {
+    throw new Error('--skill-path 必须指向 SKILL.md');
+  }
+  if (!fs.existsSync(resolvedSkillPath)) {
+    throw new Error(`SKILL.md 不存在：${resolvedSkillPath}`);
+  }
+  return resolvedSkillPath;
+}
+
+/**
+ * 读取并初检 npm 包内置的 SKILL.md。
+ *
+ * 只做「包自身是否完整」这层检查（文件在不在、name/description 有没有），
+ * 至于内置 name 是否等于本 Skill 的展示名，交给各仓自己判断：三个仓的身份判定规则
+ * 本来就不一样（有的比展示名、有的比内部 ID、有的还要兼容历史名），
+ * 把它塞进共享内核只会变成一堆互相矛盾的开关。
+ * @param {string} bundledSkillPath 内置 SKILL.md 路径。
+ * @returns {{content: string, metadata: Record<string, string>}} 内置内容与元数据。
+ */
+function loadBundledSkill(bundledSkillPath) {
+  requireOption(bundledSkillPath, 'bundledSkillPath');
+  if (!fs.existsSync(bundledSkillPath)) {
+    throw new Error('npm 包缺少内置 SKILL.md，请重新安装当前版本');
+  }
+  const content = fs.readFileSync(bundledSkillPath, 'utf8');
+  const metadata = parseSkillMetadata(content);
+  if (!metadata.name || !metadata.description) {
+    throw new Error('内置 SKILL.md 缺少 name 或 description');
+  }
+  return { content, metadata };
+}
+
+/* ------------------------------------------------------------------ *
+ * 三、skills.jsonc 注册表
+ * ------------------------------------------------------------------ */
+
+/**
+ * 去掉 JSONC 里的注释和尾逗号，再交给 JSON.parse。
+ *
+ * 智能体侧的 skills.jsonc 是人手维护的，带注释和尾逗号是常态。这里必须是一个真正的
+ * 状态机而不是正则：注释符号完全可能出现在字符串值里（比如 URL 或 Windows 路径），
+ * 用正则一刀切会把合法内容剪掉，从而把整份注册表改坏。
+ * @param {string} content JSONC 文本。
+ * @returns {string} 可被 JSON.parse 的文本。
+ */
+function stripJsonComments(content) {
+  let output = '';
+  let inString = false;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = 0; index < content.length; index += 1) {
+    const char = content[index];
+    const next = content[index + 1];
+    if (lineComment) {
+      if (char === '\n') {
+        lineComment = false;
+        output += char;
+      }
+      continue;
+    }
+    if (blockComment) {
+      if (char === '*' && next === '/') {
+        blockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (inString) {
+      output += char;
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      output += char;
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      lineComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      blockComment = true;
+      index += 1;
+      continue;
+    }
+    output += char;
+  }
+  return output.replace(/,\s*([}\]])/g, '$1');
+}
+
+/**
+ * 读取一份 skills.jsonc。
+ * @param {string} registryPath 注册表路径。
+ * @returns {object} 解析结果。
+ */
+function readSkillsRegistry(registryPath) {
+  return JSON.parse(stripJsonComments(fs.readFileSync(registryPath, 'utf8')));
+}
+
+/**
+ * 归一化路径以便比较。
+ *
+ * Windows 上同一个目录会以不同大小写出现在 registry 和实际调用里，直接字符串比较
+ * 会找不到条目，于是启动器误判「registry 里没有这个 Skill」并抛错终止。
+ * 只在 win32 上小写化：Linux 下路径大小写敏感，强行小写会把两个不同目录判成同一个。
+ * @param {string} filePath 任意路径。
+ * @param {{platform?: string}} options 平台名，测试可覆盖。
+ * @returns {string} 归一化后的绝对路径。
+ */
+function normalizePath(filePath, { platform = process.platform } = {}) {
+  const resolved = path.resolve(filePath);
+  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+/**
+ * 在注册表里按安装目录找到本 Skill 的条目。
+ * @param {object} data 已解析的 skills.jsonc。
+ * @param {string} skillDir SKILL.md 所在目录。
+ * @param {{platform?: string}} options 平台名，测试可覆盖。
+ * @returns {object | undefined} 命中的条目。
+ */
+function findRegistryEntry(data, skillDir, { platform = process.platform } = {}) {
+  const target = normalizePath(skillDir, { platform });
+  return data.skills?.find(
+    (entry) => entry.installPath && normalizePath(entry.installPath, { platform }) === target
+  );
+}
+
+/**
+ * 预演一次 skills.jsonc 更新，但不落盘。
+ *
+ * 拆成「预演 + 提交」两步是为了让 registry 里找不到条目这类错误在**写任何文件之前**
+ * 就抛出来。否则 SKILL.md 已经被覆盖、registry 却写不动，用户手上就剩下半个新版 Skill。
+ *
+ * `targetVersion` 必须显式传入：三个仓里有的写 npm 包版本、有的写内置 frontmatter 里的
+ * 版本，取值来源不同，共享内核不替谁做决定。
+ * @param {string} skillPath SKILL.md 绝对路径。
+ * @param {{name: string, description: string}} metadata 内置 Skill 元数据。
+ * @param {{targetVersion: string, platform?: string}} options 目标版本。
+ * @returns {{registryPath: string | null, currentVersion: string | null, changed: boolean, content: string | null}} 预演结果。
+ */
+function registryUpdatePreview(skillPath, metadata, { targetVersion, platform = process.platform } = {}) {
+  requireOption(targetVersion, 'targetVersion');
+  const skillDir = path.dirname(skillPath);
+  const registryPath = path.join(skillDir, '..', 'skills.jsonc');
+  if (!fs.existsSync(registryPath)) {
+    return { registryPath: null, currentVersion: null, changed: false, content: null };
+  }
+  const data = readSkillsRegistry(registryPath);
+  const entry = findRegistryEntry(data, skillDir, { platform });
+  if (!entry) {
+    throw new Error(`skills.jsonc 未找到 installPath 对应项：${skillDir}`);
+  }
+  const before = JSON.stringify(entry);
+  const currentVersion = entry.version || null;
+  entry.name = metadata.name;
+  entry.description = metadata.description;
+  entry.version = targetVersion;
+  return {
+    registryPath,
+    currentVersion,
+    changed: before !== JSON.stringify(entry),
+    content: `${JSON.stringify(data, null, 2)}\n`
+  };
+}
+
+/**
+ * 写入之后再把 registry 读回来核对一遍。
+ *
+ * 写入成功不等于内容正确：注册表可能被别的进程同时改写，也可能因为 JSONC 里的注释
+ * 被 stripJsonComments 处理后丢失了某个字段。核对失败要让调用方走回滚，而不是让一份
+ * 版本号对不上的 registry 留在用户机器上——那会让下一次启动每次都判定需要升级。
+ * @param {{registryPath: string, skillDir: string, version: string, name: string, description: string, platform?: string}} options 期望值。
+ * @returns {void}
+ */
+function assertRegistryEntryWritten({ registryPath, skillDir, version, name, description, platform = process.platform }) {
+  const writtenEntry = findRegistryEntry(readSkillsRegistry(registryPath), skillDir, { platform });
+  if (
+    !writtenEntry ||
+    writtenEntry.version !== version ||
+    writtenEntry.name !== name ||
+    writtenEntry.description !== description
+  ) {
+    throw new Error('写入后的 skills.jsonc 校验失败');
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * 四、可回滚的写入事务
+ * ------------------------------------------------------------------ */
+
+/**
+ * 记录单个文件的当前状态（含「原本不存在」这一状态）。
+ * @param {string} filePath 文件路径。
+ * @returns {{exists: boolean, content: Buffer | null}} 快照。
+ */
+function snapshotFile(filePath) {
+  return fs.existsSync(filePath)
+    ? { exists: true, content: fs.readFileSync(filePath) }
+    : { exists: false, content: null };
+}
+
+/**
+ * 按快照还原单个文件。
+ *
+ * 这里的 mkdir 不能省：回滚时目标目录可能是本次刚创建的（例如首次写入 agents/openai.yaml），
+ * 直接 writeFileSync 会因为父目录不存在而在回滚过程中再抛一次错，把原始错误盖掉。
+ * 三份 index.js 里 review-customer-insight 那份恰好漏了这行，这里统一按有 mkdir 的写法。
+ * @param {string} filePath 文件路径。
+ * @param {{exists: boolean, content: Buffer | null}} snapshot 快照。
+ * @returns {void}
+ */
+function restoreFile(filePath, snapshot) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  if (snapshot.exists) fs.writeFileSync(filePath, snapshot.content);
+  else fs.rmSync(filePath, { force: true });
+}
+
+/**
+ * 记录整棵目录树的内容。
+ *
+ * 资源目录（模板、策略、图片）是整体替换的，回滚也必须整体还原：只还原被改动的文件会
+ * 把新版新增的文件留在原地，得到一份「一半新一半旧」的资源目录，比彻底失败更难排查。
+ * @param {string} root 目录根。
+ * @returns {{exists: boolean, files: Map<string, Buffer>}} 快照。
+ */
+function snapshotTree(root) {
+  if (!fs.existsSync(root)) return { exists: false, files: new Map() };
+  const files = new Map();
+  const visit = (current, relative = '') => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const childRelative = path.join(relative, entry.name);
+      const childPath = path.join(current, entry.name);
+      if (entry.isDirectory()) visit(childPath, childRelative);
+      else if (entry.isFile()) files.set(childRelative, fs.readFileSync(childPath));
+    }
+  };
+  visit(root);
+  return { exists: true, files };
+}
+
+/**
+ * 按快照还原整棵目录树；原本不存在就整棵删掉。
+ * @param {string} root 目录根。
+ * @param {{exists: boolean, files: Map<string, Buffer>}} snapshot 快照。
+ * @returns {void}
+ */
+function restoreTree(root, snapshot) {
+  fs.rmSync(root, { recursive: true, force: true });
+  if (!snapshot.exists) return;
+  for (const [relative, content] of snapshot.files) {
+    const target = path.join(root, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+}
+
+/**
+ * 计算目录树的内容摘要，用来判断「要不要重写」和「写完对不对」。
+ *
+ * 路径分隔符要归一化成 `/` 再进摘要，否则同一份资源在 Windows 和 macOS 上算出不同摘要，
+ * 于是 Windows 用户每次启动都被判定为「资源有变化」，每次都要重新同步并重跑一次。
+ * 每段之间插 `\0` 是为了避免「文件名尾巴 + 内容开头」拼出与另一组相同的字节序列。
+ * @param {string} root 目录根。
+ * @returns {string | null} sha256；目录不存在时为空值。
+ */
+function treeDigest(root) {
+  if (!fs.existsSync(root)) return null;
+  const hash = crypto.createHash('sha256');
+  const snapshot = snapshotTree(root);
+  for (const [relative, content] of [...snapshot.files.entries()].sort()) {
+    hash.update(relative.replaceAll(path.sep, '/'));
+    hash.update('\0');
+    hash.update(content);
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * 把一组文件/目录的写入包成一次「全成功或全还原」的事务。
+ *
+ * 三个仓的 syncSkillInstallation 各自内联了一遍这个骨架，而它恰恰是整个启动器里
+ * 最不能出错的一段：写到一半失败会让用户手上留下半个新版 Skill——SKILL.md 是新的、
+ * 渲染脚本还是旧的，下一次启动既不报错也跑不对。
+ *
+ * verify 一定要在事务内执行：写完之后的自检（名称对不对、版本标记对不对、registry 对不对）
+ * 失败时同样必须回滚，否则「校验」只是打印了一句话而已。
+ * @param {{files?: string[], trees?: string[], apply: () => *, verify?: () => void}} options 事务描述。
+ * @returns {*} apply 的返回值。
+ */
+function runWithRollback({ files = [], trees = [], apply, verify } = {}) {
+  if (typeof apply !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 apply：事务必须显式给出写入动作。');
+  }
+  const fileSnapshots = files.map((filePath) => [filePath, snapshotFile(filePath)]);
+  const treeSnapshots = trees.map((root) => [root, snapshotTree(root)]);
+  try {
+    const result = apply();
+    if (verify) verify();
+    return result;
+  } catch (error) {
+    for (const [filePath, snapshot] of fileSnapshots) restoreFile(filePath, snapshot);
+    for (const [root, snapshot] of treeSnapshots) restoreTree(root, snapshot);
+    throw error;
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * 五、Skill 安装位置发现与门禁
+ * ------------------------------------------------------------------ */
+
+/**
+ * 扫描本机智能体目录，找出可能是本 Skill 的安装位置。
+ *
+ * 这是给「调用方忘了传 --skill-path」准备的兜底：不是为了替它做决定，而是为了能在
+ * 报错里点名具体路径。判定函数由调用方注入，因为三个仓的识别特征各不相同（有的靠
+ * npm 包名出现在正文里，有的靠 frontmatter 的 name 前缀），写死在共享内核里的话，
+ * 第四个 Skill 接进来时就得改这个文件。
+ *
+ * 任何一层读失败都只跳过、不抛错：用户机器上完全可能存在权限不足或损坏的 skills.jsonc，
+ * 那不该让一次正常启动失败。
+ * @param {{homeDir?: string, matches: (content: string, skillPath: string) => boolean, platform?: string}} options 扫描选项。
+ * @returns {string[]} 去重后的候选 SKILL.md 绝对路径。
+ */
+function discoverLegacySkillPaths({ homeDir = os.homedir(), matches, platform = process.platform } = {}) {
+  if (typeof matches !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 matches：各 Skill 的识别特征不同，必须由调用方注入判定函数。');
+  }
+  const accountsRoot = path.join(homeDir, '.accio', 'accounts');
+  if (!fs.existsSync(accountsRoot)) return [];
+  const candidates = [];
+  for (const account of fs.readdirSync(accountsRoot, { withFileTypes: true })) {
+    if (!account.isDirectory()) continue;
+    const agentsRoot = path.join(accountsRoot, account.name, 'agents');
+    if (!fs.existsSync(agentsRoot)) continue;
+    for (const agent of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+      if (!agent.isDirectory()) continue;
+      const registryPath = path.join(agentsRoot, agent.name, 'agent-core', 'skills', 'skills.jsonc');
+      if (!fs.existsSync(registryPath)) continue;
+      let data;
+      try {
+        data = readSkillsRegistry(registryPath);
+      } catch {
+        continue;
+      }
+      for (const entry of data.skills || []) {
+        if (!entry.installPath) continue;
+        const skillPath = path.join(entry.installPath, 'SKILL.md');
+        if (!fs.existsSync(skillPath)) continue;
+        let content;
+        try {
+          content = fs.readFileSync(skillPath, 'utf8');
+        } catch {
+          continue;
+        }
+        if (matches(content, skillPath)) candidates.push(path.resolve(skillPath));
+      }
+    }
+  }
+  return [...new Set(candidates.map((candidate) => normalizePath(candidate, { platform })))];
+}
+
+/**
+ * Skill OTA 门禁：决定这一次调用是「可以干活」还是「先同步再重来」。
+ *
+ * 只有「本地副本与 npm 包完全一致」才放行。一旦发生了同步，本次就必须停：智能体是
+ * 按它**已经读进上下文的那份 SKILL.md** 在调用参数的，磁盘上换成新版之后再执行，
+ * 参数含义可能已经不同了。
+ *
+ * `discoveredPathPolicy` 显式区分两种历史行为，不设默认值偏向，因为它会改变退出协议：
+ * - 'require_argument'：没传 --skill-path 时**永远不放行**，并在结论里点名参数和路径。
+ *   缺的是参数，不是同步；含糊的「请重新试一次」正好会诱导调用方原样重试——重试一万次
+ *   也不会成功。priority-buyer-alert 已经改成这个语义。
+ * - 'restart_required'：public-customer-reactivation 与 review-customer-insight 的现状，
+ *   把扫描出来的路径当作已同步，返回 restart_required 让调用方重跑。迁移时先保持原样，
+ *   确认上层文案配套后再切换到 'require_argument'。
+ * @param {string | null} skillPath 调用方传入的路径。
+ * @param {{syncSkill: (path: string) => object, discoverSkillPaths: () => string[], discoveredPathPolicy: 'require_argument' | 'restart_required'}} options 注入项。
+ * @returns {{allowRun: boolean, sync: object}} 门禁结论。
+ */
+function resolveSkillGate(skillPath, { syncSkill, discoverSkillPaths, discoveredPathPolicy } = {}) {
+  if (typeof syncSkill !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 syncSkill：同步哪些产物是各仓自己的事，必须注入。');
+  }
+  if (typeof discoverSkillPaths !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 discoverSkillPaths：识别特征各仓不同，必须注入。');
+  }
+  if (!['require_argument', 'restart_required'].includes(discoveredPathPolicy)) {
+    throw new Error("launcher-core 缺少必填参数 discoveredPathPolicy：只接受 'require_argument' 或 'restart_required'，该选择会改变退出协议，不设默认值。");
+  }
+  if (skillPath) {
+    const sync = syncSkill(skillPath);
+    return { allowRun: sync.action === 'current', sync };
+  }
+  const candidates = discoverSkillPaths();
+  if (candidates.length !== 1) {
+    return { allowRun: false, sync: { action: 'skill_path_required', candidates } };
+  }
+  const sync = syncSkill(candidates[0]);
+  if (sync.action === 'local_newer') {
+    // 本地版本更高是一个独立结论：它不是「缺参数」，也不该被重跑修复。
+    return { allowRun: false, sync };
+  }
+  if (discoveredPathPolicy === 'require_argument') {
+    return {
+      allowRun: false,
+      sync: { ...sync, action: 'skill_path_required', candidates, synced: sync.action !== 'current' }
+    };
+  }
+  return { allowRun: false, sync: { ...sync, action: 'restart_required' } };
+}
+
+/* ------------------------------------------------------------------ *
+ * 六、平台识别与下载源
+ * ------------------------------------------------------------------ */
+
+/**
+ * 把当前进程的平台/架构映射为发布产物条目。
+ *
+ * 不支持的平台要在报错里列出**已支持**的清单：只说「暂不支持」的话，用户唯一能做的
+ * 就是换台机器试，而列出清单能立刻说明是缺 Windows 还是缺 x64。
+ * @param {{platforms: Record<string, object>, binName: string, platform?: string, arch?: string}} options 平台表与二进制前缀。
+ * @returns {object} 平台条目，附带 binaries 数组。
+ */
+function detectTarget({ platforms, binName, platform = process.platform, arch = process.arch } = {}) {
+  requireOption(platforms, 'platforms');
+  requireOption(binName, 'binName');
+  const entry = platforms[`${platform}-${arch}`];
+  if (!entry) {
+    const supported = Object.values(platforms).map((item) => item.id).join('、');
+    throw new Error(`暂不支持当前平台：${platform}/${arch}。已支持：${supported}。`);
+  }
+  return { ...entry, binaries: [`${binName}-${entry.id}${entry.exe || ''}`] };
+}
+
+/**
+ * 生成业务运行时下载源，固定保持主源优先、备用源在后。
+ *
+ * 显式覆盖主源时不擅自追加默认备用源：私有部署或联调时把主源指到内网，却偷偷保留一个
+ * 公网备用源，会让「内网下载失败」被公网悄悄兜住，从而掩盖配置错误，也越过了部署边界。
+ * 去重和去尾斜杠是因为拼接时统一按 `${base}/${file}`，尾斜杠会拼出 `//` 这种在某些
+ * 对象存储上直接 404 的路径。
+ * @param {{defaultPrimary: string, defaultFallbacks?: string[], overridePrimary?: string | null, overrideFallbacks?: string | string[] | null}} options 下载源。
+ * @returns {string[]} 已清理、去重并保持优先级的下载根地址。
+ */
+function resolveReleaseBaseUrls({
+  defaultPrimary,
+  defaultFallbacks = [],
+  overridePrimary = null,
+  overrideFallbacks = null
+} = {}) {
+  requireOption(defaultPrimary, 'defaultPrimary');
+  const primary = overridePrimary || defaultPrimary;
+  const rawFallbacks = overrideFallbacks
+    ? (Array.isArray(overrideFallbacks) ? overrideFallbacks : String(overrideFallbacks).split(','))
+    : overridePrimary
+      ? []
+      : defaultFallbacks;
+  return [
+    ...new Set(
+      [primary, ...rawFallbacks]
+        .filter(Boolean)
+        .map((value) => String(value).trim().replace(/\/$/, ''))
+    )
+  ];
+}
+
+/**
+ * 按下载源优先级生成当前平台归档地址。
+ * @param {string[]} baseUrls 下载根地址。
+ * @param {object} target 平台条目。
+ * @returns {string[]} 归档地址。
+ */
+function releaseUrls(baseUrls, target) {
+  return baseUrls.map((baseUrl) => `${baseUrl}/${target.archive}`);
+}
+
+/**
+ * 根据运行时下载源生成一一对应的外部清单地址。
+ * @param {string[]} baseUrls 下载根地址。
+ * @returns {string[]} 清单地址。
+ */
+function runtimeManifestUrls(baseUrls) {
+  return baseUrls.map((baseUrl) => `${baseUrl}/runtime-manifest.json`);
+}
+
+/* ------------------------------------------------------------------ *
+ * 七、下载与校验
+ * ------------------------------------------------------------------ */
+
+/**
+ * 计算文件的 sha256。
+ * @param {string} filePath 文件路径。
+ * @returns {string} 十六进制摘要。
+ */
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+/**
+ * 下载单个文件。
+ *
+ * 手写而不是用 fetch/第三方库的原因：启动器要兼容 Node 18，且不能有依赖。
+ * 几个细节都对应过真实故障：
+ * - 必须跟随重定向（对象存储的自定义域名会 302），但要有次数上限，否则循环重定向会挂死。
+ * - 必须显式处理 'aborted'：连接被中断时 finish 事件不会触发，Promise 会永远悬着，
+ *   表现为启动器卡住不动、也不报错。
+ * - 必须有超时：默认无超时的情况下，一个不响应的源能让启动器无限期等待。
+ * @param {string} url 下载地址。
+ * @param {string} outputPath 落盘路径。
+ * @param {{userAgent: string, redirects?: number, timeoutMs?: number}} options 下载选项。
+ * @returns {Promise<void>} 下载完成。
+ */
+function download(url, outputPath, { userAgent, redirects = 5, timeoutMs = 60000 } = {}) {
+  requireOption(userAgent, 'userAgent');
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('http:') ? http : https;
+    const request = client.get(url, { headers: { 'User-Agent': userAgent } }, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        response.resume();
+        if (!response.headers.location || redirects === 0) {
+          reject(new Error(`下载重定向过多：${url}`));
+          return;
+        }
+        download(new URL(response.headers.location, url).toString(), outputPath, {
+          userAgent,
+          redirects: redirects - 1,
+          timeoutMs
+        }).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`下载失败：HTTP ${response.statusCode} ${url}`));
+        return;
+      }
+      const file = fs.createWriteStream(outputPath);
+      response.pipe(file);
+      response.on('aborted', () => {
+        file.destroy();
+        reject(new Error(`下载连接意外中断：${url}`));
+      });
+      response.on('error', (error) => file.destroy(error));
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    });
+    request.setTimeout(timeoutMs, () => request.destroy(new Error(`下载超时：${url}`)));
+    request.on('error', reject);
+  });
+}
+
+/**
+ * 校验运行时清单与归档是否匹配当前启动器。
+ *
+ * schema 字段是各 Skill 自己的字符串，必须由调用方传入：两个 Skill 的产物可能被放到
+ * 同一个对象存储桶里，只比版本号会让「下错 Skill 的包」这种事一路通过校验。
+ * 大小和 sha256 都要比：只比 sha256 时，一个被截断的空文件如果恰好命中缓存里的旧摘要
+ * 就会被放行；先比大小能让绝大多数损坏在算摘要之前就被拦下。
+ * @param {object} manifest 运行时清单。
+ * @param {object} target 平台条目。
+ * @param {string} archivePath 归档路径。
+ * @param {{manifestSchema: string, runtimeVersion: string}} options 期望的 schema 与版本。
+ * @returns {void}
+ */
+function verifyReleaseArchive(manifest, target, archivePath, { manifestSchema, runtimeVersion } = {}) {
+  requireOption(manifestSchema, 'manifestSchema');
+  requireOption(runtimeVersion, 'runtimeVersion');
+  if (manifest?.schema !== manifestSchema || manifest.runtime_version !== runtimeVersion) {
+    throw new Error('公共运行时清单版本与当前启动器不一致');
+  }
+  const expected = manifest.platforms?.[target.id];
+  if (!expected || expected.archive !== target.archive) {
+    throw new Error(`公共运行时清单缺少平台 ${target.id}`);
+  }
+  const stat = fs.statSync(archivePath);
+  if (stat.size !== expected.size || sha256File(archivePath) !== expected.sha256) {
+    throw new Error(`公共运行时压缩包校验失败：${target.archive}`);
+  }
+}
+
+/**
+ * 从同一个来源成对下载清单和压缩包，并在切换来源前完成版本、平台和 SHA256 校验。
+ *
+ * 清单与文件必须同源处理，避免主源清单与备用源文件版本漂移时被错误组合：主源清单说
+ * sha 是 A、备用源上的归档其实是上一版，两边各自都是「好的」，组合起来却是一个永远
+ * 校验不过、或者更糟——恰好校验通过但版本对不上的运行时。
+ *
+ * 每次换源前先删掉上一轮的残留文件，否则上一次下载了一半的归档会被当成本次结果。
+ * @param {object} target 当前平台的归档名称和标识。
+ * @param {string} releaseManifestPath 临时清单文件路径。
+ * @param {string} archivePath 临时运行时归档路径。
+ * @param {{baseUrls: string[], downloadFile: (url: string, outputPath: string) => Promise<void>, verifyArchive: (manifest: object, target: object, archivePath: string) => void}} options 注入项。
+ * @returns {Promise<object>} 与归档同源且已通过校验的运行时清单。
+ */
+async function downloadVerifiedRelease(target, releaseManifestPath, archivePath, {
+  baseUrls,
+  downloadFile,
+  verifyArchive
+} = {}) {
+  requireOption(baseUrls, 'baseUrls');
+  if (typeof downloadFile !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 downloadFile：User-Agent 属于各仓身份，必须由调用方绑定后注入。');
+  }
+  if (typeof verifyArchive !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 verifyArchive：清单 schema 与运行时版本属于各仓身份，必须由调用方绑定后注入。');
+  }
+  const failures = [];
+  for (const baseUrl of baseUrls) {
+    const root = String(baseUrl).trim().replace(/\/$/, '');
+    try {
+      fs.rmSync(releaseManifestPath, { force: true });
+      fs.rmSync(archivePath, { force: true });
+      await downloadFile(`${root}/runtime-manifest.json`, releaseManifestPath);
+      const manifest = JSON.parse(fs.readFileSync(releaseManifestPath, 'utf8'));
+      await downloadFile(`${root}/${target.archive}`, archivePath);
+      verifyArchive(manifest, target, archivePath);
+      return manifest;
+    } catch (error) {
+      fs.rmSync(releaseManifestPath, { force: true });
+      fs.rmSync(archivePath, { force: true });
+      failures.push(`${root}: ${error.message}`);
+    }
+  }
+  throw new Error(`所有下载源均未通过运行时校验：\n${failures.join('\n')}`);
+}
+
+/**
+ * 解压后再按包内 checksums.json 逐个核对二进制。
+ *
+ * 外层已经校验过归档的 sha256，这里再核一遍解压结果，是因为两者防的不是同一件事：
+ * 外层防「下载链路把包换了/传坏了」，这里防「包本身内容与它自称的版本不符」，
+ * 也防解压工具在个别平台上静默截断。
+ * @param {string} extractedDir 解压目录。
+ * @param {object} target 平台条目。
+ * @param {{runtimeVersion: string}} options 期望的运行时版本。
+ * @returns {Record<string, {size: number, sha256: string}>} 校验通过的文件清单。
+ */
+function verifyExtractedRuntime(extractedDir, target, { runtimeVersion } = {}) {
+  requireOption(runtimeVersion, 'runtimeVersion');
+  const manifest = JSON.parse(fs.readFileSync(path.join(extractedDir, 'checksums.json'), 'utf8'));
+  if (manifest.version !== runtimeVersion || manifest.platform !== target.id) {
+    throw new Error('下载包版本或平台与当前启动器不一致');
+  }
+  for (const name of target.binaries) {
+    const expected = manifest.files?.[name];
+    const filePath = path.join(extractedDir, name);
+    if (
+      !expected ||
+      !fs.existsSync(filePath) ||
+      fs.statSync(filePath).size !== expected.size ||
+      sha256File(filePath) !== expected.sha256
+    ) {
+      throw new Error(`下载包校验失败：${name}`);
+    }
+  }
+  return manifest.files;
+}
+
+/* ------------------------------------------------------------------ *
+ * 八、本地运行时安装
+ * ------------------------------------------------------------------ */
+
+/**
+ * 执行外部命令并把失败转成可读错误。
+ *
+ * stdout/stderr 都捕获再拼进错误信息：tar 和 unzip 的失败原因有时只写在 stdout 上，
+ * 只取 stderr 会得到一句「退出码为 1」，完全无法定位。
+ * windowsHide 是为了不让用户看到一闪而过的黑窗口。
+ * @param {string} command 命令。
+ * @param {string[]} args 参数。
+ * @returns {void}
+ */
+function runCommand(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+    throw new Error(detail || `${command} 退出码为 ${result.status}`);
+  }
+}
+
+/**
+ * 解压运行时归档。
+ *
+ * 用系统自带工具而不是 Node 侧解压库，仍然是「不能有第三方依赖」的延伸。
+ * Windows 上没有 unzip，只能走 PowerShell 的 Expand-Archive，且路径必须用
+ * JSON.stringify 包起来——用户目录里带空格或中文时，不加引号会被拆成多个参数。
+ * @param {string} archivePath 归档路径。
+ * @param {string} destination 解压目标目录。
+ * @param {{platform?: string}} options 平台名，测试可覆盖。
+ * @returns {void}
+ */
+function extractArchive(archivePath, destination, { platform = process.platform } = {}) {
+  fs.mkdirSync(destination, { recursive: true });
+  if (archivePath.endsWith('.tar.gz')) {
+    runCommand('tar', ['-xzf', archivePath, '-C', destination]);
+    return;
+  }
+  if (archivePath.endsWith('.zip')) {
+    if (platform === 'win32') {
+      runCommand('powershell.exe', [
+        '-NoProfile',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        `Expand-Archive -LiteralPath ${JSON.stringify(archivePath)} -DestinationPath ${JSON.stringify(destination)} -Force`
+      ]);
+      return;
+    }
+    runCommand('unzip', ['-q', archivePath, '-d', destination]);
+    return;
+  }
+  throw new Error(`暂不支持的压缩包类型：${archivePath}`);
+}
+
+/**
+ * 判断本地是否已有一份可用的同版本运行时。
+ *
+ * 不能只看 installed.json 存不存在：磁盘清理工具、杀软隔离、同步盘都可能把二进制删掉
+ * 而留下标记文件。因此每次都真的比对大小和 sha256——这一步的开销远小于「以为装好了、
+ * 结果 spawn 一个不存在的文件」带来的排查成本。
+ * 整个函数用 try/catch 包住并返回 false：读不到、解析不了都等价于「没装」，
+ * 让调用方走重装流程，而不是让启动直接失败。
+ * @param {{target: object, binDir: string, installMarkerPath: string, runtimeVersion: string}} options 校验依据。
+ * @returns {boolean} 是否已安装。
+ */
+function isRuntimeInstalled({ target, binDir, installMarkerPath, runtimeVersion } = {}) {
+  requireOption(binDir, 'binDir');
+  requireOption(installMarkerPath, 'installMarkerPath');
+  requireOption(runtimeVersion, 'runtimeVersion');
+  try {
+    const marker = JSON.parse(fs.readFileSync(installMarkerPath, 'utf8'));
+    return (
+      marker.version === runtimeVersion &&
+      marker.platform === target.id &&
+      target.binaries.every((name) => {
+        const expected = marker.files?.[name];
+        const filePath = path.join(binDir, name);
+        return (
+          expected &&
+          fs.existsSync(filePath) &&
+          fs.statSync(filePath).size === expected.size &&
+          sha256File(filePath) === expected.sha256
+        );
+      })
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * macOS 上去掉隔离属性并补上可执行位。
+ *
+ * 从网络下载的二进制带 com.apple.quarantine，直接执行会被 Gatekeeper 弹窗拦下；
+ * xattr 失败不抛错（有些文件系统不支持扩展属性），但 chmod 失败必须抛——没有可执行位
+ * 就是真的跑不起来。每次启动都执行一遍，因为备份还原、同步盘都可能把属性带回来。
+ * @param {{target: object, binDir: string, platform?: string}} options 目标与目录。
+ * @returns {void}
+ */
+function prepareMacBinaries({ target, binDir, platform = process.platform } = {}) {
+  if (platform !== 'darwin') return;
+  requireOption(binDir, 'binDir');
+  for (const name of target.binaries) {
+    const filePath = path.join(binDir, name);
+    spawnSync('xattr', ['-dr', 'com.apple.quarantine', filePath], { stdio: 'ignore' });
+    runCommand('chmod', ['+x', filePath]);
+  }
+}
+
+/**
+ * 清理旧版本运行时目录，按最近使用时间保留最新的若干份。
+ *
+ * 尽力而为：删不掉就算了，绝不因为清理失败影响本次运行。
+ * @param {{versionsRoot: string, active: string, keepCount?: number}} options 版本目录根、当前版本目录名、保留份数。
+ * @returns {string[]} 实际删掉的版本目录名。
+ */
+function pruneOldRuntimeVersions({ versionsRoot, active, keepCount = RUNTIME_VERSIONS_TO_KEEP } = {}) {
+  requireOption(versionsRoot, 'versionsRoot');
+  requireOption(active, 'active');
+  let entries;
+  try {
+    entries = fs.readdirSync(versionsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  // 先把当前版本的时间戳刷新成现在：保留依据是「最近用过」而不是「最近装的」，
+  // 否则交替使用两个版本时，先装的那个会被误判成最旧的。
+  try {
+    const now = new Date();
+    fs.utimesSync(path.join(versionsRoot, active), now, now);
+  } catch {
+    // 目录还没建好（首次安装前）就跳过，不影响后面的判断。
+  }
+  const ranked = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    // 排除 v<版本>.staging-<pid>：那可能是另一个进程正在写的半成品。
+    .filter((name) => /^v\d/.test(name) && !name.includes('.staging-'))
+    .map((name) => {
+      let usedAt = 0;
+      try {
+        usedAt = fs.statSync(path.join(versionsRoot, name)).mtimeMs;
+      } catch {
+        usedAt = 0;
+      }
+      return { name, usedAt };
+    })
+    .sort((a, b) => b.usedAt - a.usedAt);
+
+  const keep = new Set(ranked.slice(0, keepCount).map((item) => item.name));
+  keep.add(active);
+
+  const removed = [];
+  for (const { name } of ranked) {
+    if (keep.has(name)) continue;
+    try {
+      fs.rmSync(path.join(versionsRoot, name), { recursive: true, force: true });
+      removed.push(name);
+    } catch {
+      // 正被占用或权限不足都不是本次运行该处理的问题，留到下次。
+    }
+  }
+  return removed;
+}
+
+/**
+ * 每次启动都清理一次旧版本，并把删掉的版本写到 stderr。
+ *
+ * 放在「已安装」的快路径上也要跑：只在新装时清理的话，一台停止升级的机器会把
+ * 历史版本永远留着。
+ *
+ * **logPrefix 必须显式传入，这一行就是那次事故的现场。** 当初这句日志的前缀写成了
+ * 模块级常量 SKILL_ID，而三份启动器里只有一份定义了它，另外两份发布后一旦真的删掉了
+ * 旧版本就抛 ReferenceError，整个启动中止。更阴的是这条路径只在「确实删了东西」时才
+ * 走到，测试和联调机上都是空目录，压根碰不到。所以这里宁可在入口硬性要求参数。
+ * @param {{versionsRoot: string, active: string, keepCount?: number, logPrefix: string, log?: (line: string) => void}} options 清理与日志选项。
+ * @returns {string[]} 实际删掉的版本目录名。
+ */
+function reportPrunedRuntimeVersions({ versionsRoot, active, keepCount, logPrefix, log = console.error } = {}) {
+  requireOption(logPrefix, 'logPrefix');
+  const removed = pruneOldRuntimeVersions({ versionsRoot, active, keepCount });
+  if (removed.length > 0) {
+    log(`[${logPrefix}] 已清理旧版本运行时：${removed.join('、')}`);
+  }
+  return removed;
+}
+
+/**
+ * 把校验完毕的 staging 目录提交为当前版本运行时。
+ *
+ * 同一 Skill 的两个实例可能同时首次安装同一版本，各自下载到自己的 staging。
+ * 版本目录按版本号钉死，内容又逐个核对过大小与 sha256，谁装出来的字节都一样，
+ * 因此没有必要抢：对方已经装好就直接用他那份。
+ *
+ * 抢的代价是真的。原来的写法是无条件 `rmSync` 再 `renameSync`，会删掉对方刚
+ * 装好、正准备执行的目录：POSIX 上对方若已 spawn 还能活下来，但两步之间那一瞬
+ * 版本目录是不存在的；Windows 上更直接——删正在运行的 exe 会抛错，把这次启动
+ * 整个带崩。
+ *
+ * @param {string} stagingRoot 已校验完毕、等待就位的临时目录。
+ * @param {string} versionRoot 版本目录。
+ * @param {() => boolean} isVersionReady 版本目录里是否已经是一份可用的同版本运行时。
+ * @returns {'installed' | 'kept_existing'} 就位的是本进程这份还是别人那份。
+ */
+function commitRuntimeInstall(stagingRoot, versionRoot, isVersionReady) {
+  if (isVersionReady()) return 'kept_existing';
+  fs.rmSync(versionRoot, { recursive: true, force: true });
+  try {
+    fs.renameSync(stagingRoot, versionRoot);
+  } catch (error) {
+    // 对方恰好在这两步之间把同版本装好了。抢输不该让本次启动失败。
+    if (!isVersionReady()) throw error;
+    return 'kept_existing';
+  }
+  return 'installed';
+}
+
+/**
+ * 确保本地有一份可执行的当前版本运行时，没有就下载安装。
+ *
+ * 全程走「临时目录 → staging → rename 就位」，绝不直接往版本目录里写：版本目录随时
+ * 可能正被另一个进程执行，半成品出现在那里等于让别人跑一个残缺的二进制。
+ * staging 目录名带 pid，是为了让并发安装的两个进程互不覆盖。
+ * finally 里无条件清掉 staging 和临时目录——失败时留下的半成品会在下次被 prune 跳过
+ * （名字里有 .staging-），从此永远占着磁盘。
+ * @param {object} options 安装参数，见下方各字段说明。
+ * @returns {Promise<'already_installed' | 'installed' | 'kept_existing'>} 本次的处理结果。
+ */
+async function ensureRuntimeInstalled({
+  target,
+  runtimeVersion,
+  versionRoot,
+  binDir,
+  tempDirPrefix,
+  logPrefix,
+  downloadRelease,
+  keepCount,
+  platform = process.platform,
+  log = console.error,
+  pid = process.pid,
+  tempDirRoot = os.tmpdir(),
+  installMarkerPath = versionRoot ? path.join(versionRoot, 'installed.json') : null,
+  extract = extractArchive,
+  verifyExtracted = null,
+  isInstalled = null
+} = {}) {
+  requireOption(target, 'target');
+  requireOption(runtimeVersion, 'runtimeVersion');
+  requireOption(versionRoot, 'versionRoot');
+  requireOption(binDir, 'binDir');
+  requireOption(tempDirPrefix, 'tempDirPrefix');
+  requireOption(logPrefix, 'logPrefix');
+  if (typeof downloadRelease !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 downloadRelease：下载源与清单 schema 属于各仓身份，必须由调用方绑定后注入。');
+  }
+  const checkInstalled = isInstalled
+    || (() => isRuntimeInstalled({ target, binDir, installMarkerPath, runtimeVersion }));
+  const checkExtracted = verifyExtracted
+    || ((extractedDir) => verifyExtractedRuntime(extractedDir, target, { runtimeVersion }));
+  const prune = () => reportPrunedRuntimeVersions({
+    versionsRoot: path.dirname(versionRoot),
+    active: path.basename(versionRoot),
+    keepCount,
+    logPrefix,
+    log
+  });
+
+  if (checkInstalled()) {
+    prepareMacBinaries({ target, binDir, platform });
+    prune();
+    return 'already_installed';
+  }
+
+  const tempRoot = fs.mkdtempSync(path.join(tempDirRoot, tempDirPrefix));
+  const archivePath = path.join(tempRoot, target.archive);
+  const releaseManifestPath = path.join(tempRoot, 'runtime-manifest.json');
+  const extractedDir = path.join(tempRoot, 'extracted');
+  const stagingRoot = `${versionRoot}.staging-${pid}`;
+  try {
+    await downloadRelease(target, releaseManifestPath, archivePath);
+    extract(archivePath, extractedDir, { platform });
+    const files = checkExtracted(extractedDir, target);
+
+    fs.mkdirSync(path.dirname(versionRoot), { recursive: true });
+    fs.rmSync(stagingRoot, { recursive: true, force: true });
+    fs.mkdirSync(path.join(stagingRoot, 'bin'), { recursive: true });
+    for (const name of target.binaries) {
+      fs.copyFileSync(path.join(extractedDir, name), path.join(stagingRoot, 'bin', name));
+    }
+    fs.writeFileSync(
+      path.join(stagingRoot, 'installed.json'),
+      `${JSON.stringify({ version: runtimeVersion, platform: target.id, files }, null, 2)}\n`
+    );
+
+    const outcome = commitRuntimeInstall(stagingRoot, versionRoot, checkInstalled);
+    prepareMacBinaries({ target, binDir, platform });
+    prune();
+    return outcome;
+  } finally {
+    fs.rmSync(stagingRoot, { recursive: true, force: true });
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * 九、共享译心桥
+ * ------------------------------------------------------------------ */
+
+/**
+ * 校验当前共享桥是否具备本 Skill 的硬依赖能力。
+ *
+ * 只校验自己声明的能力，避免无关运行时能力成为全局硬依赖：从别的仓照抄一份能力清单
+ * （比如用不到的 frame_url_v1），会在插件升级改名或合并能力时变成假硬依赖，
+ * 把本来能跑的 Skill 直接挡在门外。空清单必须真的放行，而不是被当成「未配置」而报错。
+ * @param {object} result 共享桥管理器返回的运行时信息。
+ * @param {string[]} requiredCapabilities 本 Skill 声明的能力白名单。
+ * @returns {object} 校验通过后的原始运行时信息。
+ */
+function validateBridgeCapabilities(result, requiredCapabilities = []) {
+  const missing = requiredCapabilities.filter(
+    (capability) => !result.capabilities?.includes(capability)
+  );
+  if (missing.length > 0) {
+    throw new Error(`共享译心桥缺少必要能力：${missing.join(', ')}`);
+  }
+  return result;
+}
+
+/**
+ * 确保共享译心桥已安装，并返回它的运行路径。
+ *
+ * 桥的 import 由调用方注入，这样共享内核里不会出现任何第三方包名的静态依赖——
+ * 它可以被复制到任何一个仓、任何一个测试里而不需要先 npm install。
+ * 「返回了路径」和「路径真的存在」是两件事，必须都查：管理器在部分失败时仍可能返回
+ * 一个指向已被清理目录的路径，那样后面 spawn 会得到一句难以理解的 ENOENT。
+ * @param {{importBridge: () => Promise<object>, minVersion: string, requiredCapabilities?: string[], packageName?: string}} options 注入项。
+ * @returns {Promise<object>} 共享桥运行时信息。
+ */
+async function ensureSharedBridge({
+  importBridge,
+  minVersion,
+  requiredCapabilities = [],
+  packageName = '@yixinkj/yixin-bridge-cli'
+} = {}) {
+  if (typeof importBridge !== 'function') {
+    throw new Error('launcher-core 缺少必填参数 importBridge：共享内核不静态依赖任何第三方包，桥的加载方式必须注入。');
+  }
+  requireOption(minVersion, 'minVersion');
+  let manager;
+  try {
+    manager = await importBridge();
+  } catch (error) {
+    throw new Error(`缺少共享译心桥管理器 ${packageName}：${error.message}`);
+  }
+  const result = await manager.ensureBridgeRuntime({ minVersion });
+  if (!result?.bridge_path || !fs.existsSync(result.bridge_path)) {
+    throw new Error('共享译心桥安装完成后未返回有效运行路径');
+  }
+  validateBridgeCapabilities(result, requiredCapabilities);
+  return result;
+}
+
+/**
+ * 把共享管理器的底层插件状态转换为用户可理解的有限提示。
+ *
+ * 无更新时返回空值，避免每次分析都输出无行动价值的运行时细节——每次都刷一行
+ * 「插件版本 x.y.z」只会让真正需要动手的那一次被淹没。
+ *
+ * `manualReloadMessage` 可覆盖：priority-buyer-alert 把这句改成了「先删除旧插件、
+ * 再按下方路径导入新版」的完整步骤，因为只说「请手动重新加载」时，用户在扩展管理页
+ * 点了刷新却仍然是旧版（旧目录还在），反复来回。默认用这版更完整的说法。
+ * @param {object | null} sharedBridge 共享桥管理器返回的安装和插件状态。
+ * @param {{manualReloadMessage?: (version: string) => string}} options 文案覆盖。
+ * @returns {object | null} 需要展示的提示结构；无需提示时返回空值。
+ */
+function browserExtensionNotice(sharedBridge, { manualReloadMessage = null } = {}) {
+  if (!sharedBridge) return null;
+  const reloadStatus = sharedBridge.extension_reload?.status || 'not_requested';
+  const details = {
+    extension_version: sharedBridge.extension_version || null,
+    extension_path: sharedBridge.extension_path || null,
+    reload_status: reloadStatus
+  };
+  const version = details.extension_version || '最新版';
+  if (sharedBridge.extension_updated) {
+    if (reloadStatus === 'reloaded') {
+      return {
+        ...details,
+        status: 'updated_reloaded',
+        message: `浏览器插件已更新至 ${version}，并已自动重新加载。`
+      };
+    }
+    return {
+      ...details,
+      status: 'manual_reload_required',
+      message: manualReloadMessage
+        ? manualReloadMessage(version)
+        : `浏览器插件已更新至 ${version}，但未能自动加载。请先删除 Chrome 扩展管理页中的旧译心插件，再按下方“浏览器插件本地路径”导入新版并重新加载。`
+    };
+  }
+  if (reloadStatus === 'active_tasks_present') {
+    return {
+      ...details,
+      status: 'update_deferred',
+      message: '检测到浏览器插件更新，但当前仍有采集任务，已暂缓更新。任务结束后请重新运行。'
+    };
+  }
+  if (reloadStatus === 'daemon_status_unavailable') {
+    return {
+      ...details,
+      status: 'update_deferred',
+      message: '检测到浏览器插件更新，但暂时无法确认浏览器任务状态，未自动替换。请稍后重新运行。'
+    };
+  }
+  return null;
+}
+
+/**
+ * 仅把需要用户知晓的插件动作写入 stderr。
+ *
+ * 原生 CLI 的 stdout 是机器解析的 JSON，因此提示只能写 stderr——混进 stdout 会让
+ * 调用方的 JSON.parse 直接失败，表现成「Skill 坏了」而不是「插件需要重载」。
+ * logPrefix 同样必须显式传入，理由与 reportPrunedRuntimeVersions 完全一致。
+ * @param {object | null} sharedBridge 共享桥管理器返回的安装和插件状态。
+ * @param {{logPrefix: string, log?: (line: string) => void, noticeOptions?: object}} options 日志选项。
+ * @returns {object | null} 实际输出的提示结构。
+ */
+function emitBrowserExtensionNotice(sharedBridge, { logPrefix, log = console.error, noticeOptions = {} } = {}) {
+  requireOption(logPrefix, 'logPrefix');
+  const notice = browserExtensionNotice(sharedBridge, noticeOptions);
+  if (!notice) return null;
+  log(`[${logPrefix}] ${notice.message}`);
+  if (notice.extension_path) {
+    log(`[${logPrefix}] 浏览器插件本地路径：${notice.extension_path}`);
+  }
+  return notice;
+}
+
+/* ------------------------------------------------------------------ *
+ * 十、输出与进程边界
+ * ------------------------------------------------------------------ */
+
+/**
+ * 造一个绑定了当前 Skill 版本的状态输出函数。
+ *
+ * 做成工厂而不是普通函数，是因为 skill_version 必须出现在**每一条**状态里：
+ * 调用方拿到一条状态时要能立刻判断「这是哪一版说的话」，靠每个调用点自己记得传是不现实的。
+ * details 放在最后展开，允许个别状态覆盖同名字段。
+ * @param {{skillVersion: string, write?: (line: string) => void}} options 版本与输出通道。
+ * @returns {(status: string, message: string, details?: object) => void} 状态输出函数。
+ */
+function createStatusEmitter({ skillVersion, write = (line) => console.log(line) } = {}) {
+  requireOption(skillVersion, 'skillVersion');
+  return function emitStatus(status, message, details = {}) {
+    write(JSON.stringify({ status, message, skill_version: skillVersion, ...details }, null, 2));
+  };
+}
+
+/**
+ * 造一个统一的致命错误处理函数。
+ *
+ * 前缀由调用方传入（同一类事故的第三处现场）。错误一律写 stderr 并以非零码退出：
+ * 启动器失败时 stdout 必须保持干净，否则调用方会把半截错误文本当成结果去解析。
+ * @param {{logPrefix: string, log?: (line: string) => void, exit?: (code: number) => void}} options 日志与退出通道。
+ * @returns {(message: string) => void} 失败处理函数。
+ */
+function createFailHandler({ logPrefix, log = console.error, exit = (code) => process.exit(code) } = {}) {
+  requireOption(logPrefix, 'logPrefix');
+  return function fail(message) {
+    log(`[${logPrefix}] ${message}`);
+    exit(1);
+  };
+}
+
+/**
+ * 判断当前模块是不是被直接执行（而不是被测试 import）。
+ *
+ * **moduleUrl 必须由调用方传入自己的 import.meta.url。** 共享内核如果用自己的
+ * import.meta.url 来比，结果永远是 false，三个启动器会全部变成「导入即返回、什么都不做」——
+ * 这正是「隐式依赖模块级常量」这类事故的同族，而且它不会报错，只会静默失效。
+ *
+ * 先走 realpath 再比较，是因为 npm 会把 bin 装成 node_modules/.bin 下的符号链接，
+ * argv[1] 是链接路径而模块路径是真实路径，不解析就永远判不相等。
+ * @param {string} moduleUrl 调用方的 import.meta.url。
+ * @param {{argv?: string[], platform?: string}} options 进程信息，测试可覆盖。
+ * @returns {boolean} 是否为直接执行。
+ */
+function isDirectExecution(moduleUrl, { argv = process.argv, platform = process.platform } = {}) {
+  requireOption(moduleUrl, 'moduleUrl');
+  if (!argv[1]) return false;
+  let invoked = path.resolve(argv[1]);
+  let current = moduleUrl.startsWith('file:') ? fileURLToPath(moduleUrl) : path.resolve(moduleUrl);
+  try {
+    invoked = fs.realpathSync(invoked);
+    current = fs.realpathSync(current);
+  } catch {
+    // 某些文件系统无法解析符号链接时使用绝对路径比较。
+  }
+  return platform === 'win32'
+    ? invoked.toLowerCase() === current.toLowerCase()
+    : invoked === current;
+}
+
+export {
+  RUNTIME_VERSIONS_TO_KEEP,
+  assertRegistryEntryWritten,
+  browserExtensionNotice,
+  commitRuntimeInstall,
+  compareVersions,
+  createFailHandler,
+  createStatusEmitter,
+  detectTarget,
+  discoverLegacySkillPaths,
+  download,
+  downloadVerifiedRelease,
+  emitBrowserExtensionNotice,
+  ensureRuntimeInstalled,
+  ensureSharedBridge,
+  extractArchive,
+  extractSkillPath,
+  findRegistryEntry,
+  hasOption,
+  isDirectExecution,
+  isHelpRequest,
+  isRuntimeInstalled,
+  loadBundledSkill,
+  normalizePath,
+  parseSkillMetadata,
+  prepareMacBinaries,
+  pruneOldRuntimeVersions,
+  readInstalledSkillVersion,
+  readSkillsRegistry,
+  registryUpdatePreview,
+  releaseUrls,
+  reportPrunedRuntimeVersions,
+  resolveReleaseBaseUrls,
+  resolveSkillGate,
+  resolveSkillMdPath,
+  restoreFile,
+  restoreTree,
+  runCommand,
+  runWithRollback,
+  runtimeManifestUrls,
+  sha256File,
+  snapshotFile,
+  snapshotTree,
+  stripJsonComments,
+  treeDigest,
+  validateBridgeCapabilities,
+  verifyExtractedRuntime,
+  verifyReleaseArchive,
+  versionMarkerContent
+};