helixlife-v5-cli 1.2.8 → 1.2.9

package/lib/cli.js

@@ -1,22 +1,201 @@
 'use strict';
 
+const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const PACKAGE_JSON = require(path.join(__dirname, '..', 'package.json'));
+
+/** Skill 根目录（含 helix-cli.js / package.json 的目录） */
+const SKILL_ROOT = path.join(__dirname, '..');
+
+/** 运行时所需的最低 Node 主版本 */
+const MIN_NODE_MAJOR = 18;
+
+/** 运行时核心依赖（缺失时触发自动安装） */
+const RUNTIME_DEP = '@playwright/cli';
+const RUNTIME_DEP_ENTRY = '@playwright/cli/playwright-cli.js';
 const {
   parseVisualFlags,
   injectVisualConfig,
   shouldWrapWithVisual,
   runWithVisualFeedback,
+  resolveCommandName,
   DEFAULT_VISUAL_ENABLED,
 } = require('./visual');
+const {
+  applyRunCodeAutomationGuard,
+  runUploadCommandWithGuard,
+} = require('./automation-file-chooser-guard');
+const { hideNestedSkillsOnce } = require('./hide-nested-skills');
+const { applyAll: applyNativeModePatches } = require('./native-mode-patch');
+const {
+  isHelixSiteOpen,
+  repairHelixStylesAfterOpen,
+} = require('./helix-styles-guard');
+const {
+  extractProfileDirFromOpenArgs,
+  runOpenWithProfileRecovery,
+} = require('./profile-lock-guard');
+const {
+  resolveTokenFile,
+  resolveHelixConfigDir,
+  readTokenFromBrowser,
+  writeTokenFile,
+  maybePersistLoginToken,
+  shouldTryPersistTokenAfterCommand,
+  DEFAULT_TOKEN_FILE_NAME,
+} = require('./token-file');
 
-/** 默认快照/下载等工作区目录名（相对 cwd），替代引擎默认的 .playwright-cli */
-const DEFAULT_OUTPUT_DIR_NAME = 'helixlife-v5-cli';
+/** 默认快照/下载/日志等工作区目录名（相对 cwd），替代引擎默认的 .playwright-cli */
+const DEFAULT_OUTPUT_DIR_NAME = '.helix-output';
+
+/** 默认持久化 profile 目录名（相对用户主目录） */
+const DEFAULT_PROFILE_DIR_NAME = '.helixlife-profile';
+
+/**
+ * 解析持久化 profile 目录为绝对路径。
+ * 相对路径基于用户主目录（非 cwd），避免 WorkBuddy 等环境每次会话 cwd 不同导致登录态丢失。
+ * @param {string | undefined} [dir]
+ * @returns {string}
+ */
+function resolveProfileDir(dir) {
+  const raw = (dir ?? process.env.HELIX_PROFILE_DIR ?? DEFAULT_PROFILE_DIR_NAME).trim();
+  if (path.isAbsolute(raw)) {
+    return path.normalize(raw);
+  }
+  return path.join(os.homedir(), raw);
+}
+
+/**
+ * 将透传参数中的 --profile 规范化为绝对路径。
+ * @param {string[]} tokens
+ * @returns {string[]}
+ */
+function normalizeProfileArgs(tokens) {
+  const out = [...tokens];
+  for (let i = 0; i < out.length; i += 1) {
+    const t = out[i];
+    if (t === '--profile') {
+      const next = out[i + 1];
+      if (next !== undefined) {
+        out[i + 1] = resolveProfileDir(next);
+      }
+    } else if (t.startsWith('--profile=')) {
+      out[i] = `--profile=${resolveProfileDir(t.slice('--profile='.length))}`;
+    }
+  }
+  return out;
+}
 
 function playwrightCliEntry() {
-  return require.resolve('@playwright/cli/playwright-cli.js');
+  return require.resolve(RUNTIME_DEP_ENTRY);
+}
+
+/** 当前 Node 主版本号（解析失败返回 NaN） */
+function currentNodeMajor() {
+  return parseInt(String(process.versions.node).split('.')[0], 10);
+}
+
+/**
+ * 运行时依赖 @playwright/cli 是否已可解析。
+ * 仅吞 MODULE_NOT_FOUND；其他错误（如依赖损坏）原样抛出，避免误判为"未安装"。
+ * @returns {boolean}
+ */
+function runtimeDepInstalled() {
+  try {
+    playwrightCliEntry();
+    return true;
+  } catch (e) {
+    if (e && e.code === 'MODULE_NOT_FOUND') {
+      return false;
+    }
+    throw e;
+  }
+}
+
+/** 是否允许缺失依赖时自动 npm install（默认开启，HELIX_AUTO_INSTALL=0/false/no 关闭） */
+function autoInstallEnabled() {
+  const v = String(process.env.HELIX_AUTO_INSTALL ?? '').trim().toLowerCase();
+  return v !== '0' && v !== 'false' && v !== 'no';
+}
+
+/**
+ * 在 SKILL_ROOT 执行一次 `npm install`，安装进度直出到终端。
+ * @returns {boolean} 安装命令是否成功（exit 0）
+ */
+function runNpmInstall() {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  console.error(
+    `[${PACKAGE_JSON.name}] 缺少运行时依赖 ${RUNTIME_DEP}，正在 ${SKILL_ROOT} 自动执行 \`npm install\` …`
+  );
+  const result = spawnSync(npmCmd, ['install'], {
+    cwd: SKILL_ROOT,
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+  if (result.error) {
+    console.error(
+      `[${PACKAGE_JSON.name}] 无法启动 npm（${result.error.message}）。请确认已安装 npm，并手动在 ${SKILL_ROOT} 执行 \`npm install\`。`
+    );
+    return false;
+  }
+  return result.status === 0;
+}
+
+/**
+ * 运行前置校验：Node 版本 + 运行时依赖（缺失则自动安装）。
+ * 失败时打印友好提示并返回 false（由 main 转换为非零退出码）。
+ * @returns {boolean}
+ */
+function ensureRuntimeReady() {
+  const major = currentNodeMajor();
+  if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
+    console.error(
+      `[${PACKAGE_JSON.name}] 需要 Node.js >= ${MIN_NODE_MAJOR}，当前为 ${process.versions.node}。请升级 Node 后重试。`
+    );
+    return false;
+  }
+
+  if (runtimeDepInstalled()) {
+    // 兜底：覆盖「旧版本已装好 node_modules、postinstall 未运行过」的存量场景。
+    // 由哨兵保证仅扫描一次，稳态快路径开销可忽略（一次 existsSync）。
+    hideNestedSkillsOnce(SKILL_ROOT, {
+      log: (msg) => console.error(`[${PACKAGE_JSON.name}] ${msg}`),
+    });
+    applyNativeModePatches(SKILL_ROOT, {
+      log: (msg) => console.error(`[${PACKAGE_JSON.name}][native-mode-patch] ${msg}`),
+    });
+    return true;
+  }
+
+  if (!autoInstallEnabled()) {
+    console.error(`[${PACKAGE_JSON.name}] 缺少运行时依赖 ${RUNTIME_DEP}（已通过 HELIX_AUTO_INSTALL=0 关闭自动安装）。`);
+    console.error(`[${PACKAGE_JSON.name}] 请手动执行: cd "${SKILL_ROOT}" && npm install`);
+    return false;
+  }
+
+  if (!runNpmInstall()) {
+    console.error(`[${PACKAGE_JSON.name}] 自动安装失败。请手动在 ${SKILL_ROOT} 执行 \`npm install\` 后重试。`);
+    return false;
+  }
+
+  if (!runtimeDepInstalled()) {
+    console.error(
+      `[${PACKAGE_JSON.name}] 安装已完成但仍无法解析 ${RUNTIME_DEP}，请检查 ${path.join(SKILL_ROOT, 'node_modules')}。`
+    );
+    return false;
+  }
+
+  // postinstall 钩子通常已隐藏嵌套 Skill；此处兜底覆盖钩子未触发（如 --ignore-scripts）的情况。
+  hideNestedSkillsOnce(SKILL_ROOT, {
+    log: (msg) => console.error(`[${PACKAGE_JSON.name}] ${msg}`),
+  });
+  applyNativeModePatches(SKILL_ROOT, {
+    log: (msg) => console.error(`[${PACKAGE_JSON.name}][native-mode-patch] ${msg}`),
+  });
+  console.error(`[${PACKAGE_JSON.name}] 依赖就绪，继续执行。`);
+  return true;
 }
 
 /**
@@ -29,12 +208,20 @@ function resolveOutputDir() {
   return path.isAbsolute(dir) ? dir : path.resolve(process.cwd(), dir);
 }
 
-/** 传给底层引擎子进程的环境变量（含输出目录覆盖） */
+/** 透传给底层引擎子进程的环境变量（含输出目录与原生交互模式默认开关）。 */
 function buildChildEnv() {
   const env = { ...process.env };
   if (!env.PLAYWRIGHT_MCP_OUTPUT_DIR) {
     env.PLAYWRIGHT_MCP_OUTPUT_DIR = resolveOutputDir();
   }
+  // 原生交互模式默认开启：与 CDP 直连基线对齐（手动可弹原生上传 / 下载用真实文件名 + 原生图标）。
+  // 用户已显式设置 0 时尊重用户选择，便于回退或定向调试 browser_file_upload 工具。
+  if (env.HELIX_NATIVE_FILE_CHOOSER === undefined) {
+    env.HELIX_NATIVE_FILE_CHOOSER = '1';
+  }
+  if (env.HELIX_NATIVE_DOWNLOADS === undefined) {
+    env.HELIX_NATIVE_DOWNLOADS = '1';
+  }
   return env;
 }
 
@@ -79,8 +266,7 @@ function parseHelixFlags(tokens, startIndex) {
   const options = {
     headless: false,
     cdpUrl: process.env.HELIX_CDP_URL || 'http://127.0.0.1:9222',
-    profile:
-      process.env.HELIX_PROFILE_DIR || path.join(process.cwd(), '.helixlife-profile'),
+    profile: resolveProfileDir(),
     visual: { enabled: DEFAULT_VISUAL_ENABLED, durationMs: null },
   };
   for (let i = startIndex; i < tokens.length; i += 1) {
@@ -102,10 +288,10 @@ function parseHelixFlags(tokens, startIndex) {
         console.error(`[${PACKAGE_JSON.name}] --profile requires a value`);
         return null;
       }
-      options.profile = next;
+      options.profile = resolveProfileDir(next);
       i += 1;
     } else if (t.startsWith('--profile=')) {
-      options.profile = t.slice('--profile='.length);
+      options.profile = resolveProfileDir(t.slice('--profile='.length));
     } else if (t === '--cdp-url') {
       const next = tokens[i + 1];
       if (next === undefined) {
@@ -146,22 +332,34 @@ function printHelp() {
   console.log(
     `  ${n} helix doctor [--cdp-url <url>] [--profile <dir>]   先 list，再执行 helix home`
   );
+  console.log(
+    `  ${n} helix token save                              从当前浏览器会话读取 token 并保存到用户目录`
+  );
+  console.log(
+    `  ${n} helix token path                              输出 token 文件绝对路径（供后台 CLI 读取）`
+  );
   console.log('');
-  console.log('页面内视觉反馈（默认开启，作用于 click/fill/hover 等元素命令）：');
+  console.log('页面内视觉反馈（默认开启，作用于 click/fill/hover/run-code 等命令）：');
   console.log(`  ${n} click e5                         操作前黄框 + 标签，成功后绿框`);
+  console.log(`  ${n} run-code --filename=script.js    脚本内 click/hover/fill 自动逐步高亮 + HUD`);
   console.log(`  ${n} click e5 --no-visual              静默执行，无页面高亮`);
   console.log(`  ${n} fill e3 "文本" --visual-ms 700     自定义高亮时长（毫秒）`);
+  console.log(`  ${n} click e5 --visual-persist         HUD 与高亮不自动消失（改样式用）`);
   console.log('');
   console.log('本地开发可使用：');
   console.log('  node helix-cli.js <同上参数>');
   console.log('');
   console.log(
-    '环境变量：HELIX_BASE_URL、HELIX_CDP_URL、HELIX_PROFILE_DIR（默认 profile 目录）、'
+    `环境变量：HELIX_BASE_URL、HELIX_CDP_URL、HELIX_PROFILE_DIR（默认 ${DEFAULT_PROFILE_DIR_NAME} 于用户主目录）、`
+  );
+  console.log(
+    `  HELIX_CONFIG_DIR / HELIX_TOKEN_FILE（默认 ~/.config/helix/${DEFAULT_TOKEN_FILE_NAME}，全平台一致）、`
   );
   console.log(
     `  HELIX_OUTPUT_DIR / PLAYWRIGHT_MCP_OUTPUT_DIR（默认输出目录 <cwd>/${DEFAULT_OUTPUT_DIR_NAME}）、`
   );
   console.log('  HELIX_VISUAL=0（全局关闭视觉反馈，可用 --visual 单次开启）');
+  console.log('  HELIX_VISUAL_PERSIST=1（全局常驻反馈层，可用 --no-visual-persist 单次关闭）');
 }
 
 function getBaseUrl() {
@@ -177,12 +375,47 @@ function helixHome(options) {
   if (!options.headless) {
     openArgs.push('--headed');
   }
-  const code = runPlaywrightCliPassthrough(openArgs);
+  const code = runOpenWithProfileRecovery(openArgs, runPlaywrightCliPassthrough, {
+    resolveProfileDir,
+    log: (msg) => console.error(`[${PACKAGE_JSON.name}] ${msg}`),
+  });
   if (code !== 0) {
     return code;
   }
+  repairHelixStylesAfterOpen(runPlaywrightCliPassthrough);
   console.error(`[${PACKAGE_JSON.name}] opened: ${baseUrl}`);
-  return runPlaywrightCliPassthrough(['eval', 'document.title']);
+  return maybePersistLoginToken(runPlaywrightCliPassthrough, {
+    log: (msg) => console.error(`[${PACKAGE_JSON.name}] ${msg}`),
+  }).then((saved) => {
+    if (!saved) {
+      console.error(
+        `[${PACKAGE_JSON.name}] 未检测到登录 token；登录后可执行 helix token save`
+      );
+    }
+    return runPlaywrightCliPassthrough(['eval', 'document.title']);
+  });
+}
+
+function helixTokenSave() {
+  const read = readTokenFromBrowser(runPlaywrightCliPassthrough);
+  if (!read.ok) {
+    if (read.reason === 'not_logged_in') {
+      console.error(`[${PACKAGE_JSON.name}] 未检测到登录 token，请先登录 ${getBaseUrl()}`);
+    } else {
+      console.error(
+        `[${PACKAGE_JSON.name}] 读取 token 失败：${read.detail || read.reason}`
+      );
+    }
+    return 1;
+  }
+  const filePath = writeTokenFile(read.token);
+  console.log(filePath);
+  return 0;
+}
+
+function helixTokenPath() {
+  console.log(resolveTokenFile());
+  return 0;
 }
 
 function helixDoctor(options) {
@@ -200,22 +433,56 @@ function helixDoctor(options) {
 }
 
 async function runPassthroughWithVisual(tokens) {
+  const normalized = normalizeProfileArgs(tokens);
   let visual;
   let stripped;
   try {
-    ({ tokens: stripped, visual } = parseVisualFlags(tokens));
+    ({ tokens: stripped, visual } = parseVisualFlags(normalized));
   } catch (e) {
     console.error(`[${PACKAGE_JSON.name}] ${e.message}`);
     return 3;
   }
   const withConfig = injectVisualConfig(stripped, visual);
+  const passthrough = (args, opts) => runPlaywrightCliPassthrough(args, opts);
+  const nativeFileChooser =
+    process.env.HELIX_NATIVE_FILE_CHOOSER === undefined ||
+    process.env.HELIX_NATIVE_FILE_CHOOSER === '1';
+  const cmd = resolveCommandName(stripped);
+
   if (shouldWrapWithVisual(stripped, visual)) {
     return runWithVisualFeedback(stripped, visual, (args, opts) => {
       const result = runPlaywrightCliPassthrough(args, opts);
       return opts && opts.capture ? result.code : result;
     });
   }
-  return runPlaywrightCliPassthrough(withConfig);
+
+  let code;
+  if (nativeFileChooser && (cmd === 'upload' || cmd === 'drop')) {
+    code = runUploadCommandWithGuard(withConfig, passthrough);
+  } else if (nativeFileChooser && cmd === 'run-code') {
+    const guarded = injectVisualConfig(applyRunCodeAutomationGuard(stripped), visual);
+    code = passthrough(guarded);
+  } else {
+    const isOpenWithProfile = Boolean(extractProfileDirFromOpenArgs(withConfig, resolveProfileDir));
+    code = isOpenWithProfile
+      ? runOpenWithProfileRecovery(withConfig, passthrough, {
+          resolveProfileDir,
+          log: (msg) => console.error(`[${PACKAGE_JSON.name}] ${msg}`),
+        })
+      : passthrough(withConfig);
+  }
+
+  if (code === 0) {
+    if (isHelixSiteOpen(stripped)) {
+      repairHelixStylesAfterOpen(runPlaywrightCliPassthrough);
+    }
+    if (shouldTryPersistTokenAfterCommand(stripped)) {
+      await maybePersistLoginToken(runPlaywrightCliPassthrough, {
+        log: (msg) => console.error(`[${PACKAGE_JSON.name}] ${msg}`),
+      });
+    }
+  }
+  return code;
 }
 
 /**
@@ -241,8 +508,31 @@ async function main(argv = process.argv) {
     return 1;
   }
 
+  if (tokens[0] === 'helix' && tokens[1] === 'token' && tokens[2] === 'path') {
+    return helixTokenPath();
+  }
+
+  if (!ensureRuntimeReady()) {
+    return 1;
+  }
+
   if (tokens[0] === 'helix') {
     const sub = tokens[1];
+    if (sub === 'token') {
+      const tokenSub = tokens[2];
+      if (tokenSub === 'save') {
+        return helixTokenSave();
+      }
+      if (tokenSub === 'help' || tokenSub === '--help' || tokenSub === '-h') {
+        console.log('helix token save   从当前浏览器会话读取 token 并保存');
+        console.log('helix token path   输出 token 文件绝对路径');
+        return 0;
+      }
+      console.error(
+        `[${PACKAGE_JSON.name}] unknown helix token subcommand: ${tokenSub ?? '(missing)'}. Try: helix token save | helix token path`
+      );
+      return 2;
+    }
     const rest = parseHelixFlags(tokens, 2);
     if (rest === null) {
       return 2;
@@ -273,7 +563,19 @@ main.playwrightCliEntry = playwrightCliEntry;
 module.exports = {
   main,
   resolveOutputDir,
+  resolveProfileDir,
+  resolveTokenFile,
+  resolveHelixConfigDir,
+  normalizeProfileArgs,
   buildChildEnv,
+  ensureRuntimeReady,
+  runtimeDepInstalled,
+  autoInstallEnabled,
+  currentNodeMajor,
   DEFAULT_OUTPUT_DIR_NAME,
+  DEFAULT_PROFILE_DIR_NAME,
+  DEFAULT_TOKEN_FILE_NAME,
+  SKILL_ROOT,
+  MIN_NODE_MAJOR,
   runPassthroughWithVisual,
 };

package/lib/helix-reload-bypass-cache.run-code.js

@@ -0,0 +1,7 @@
+/**
+ * Helix 样式修复：绕过磁盘缓存硬刷新（profile 缓存旧 index.html 导致 CSS 404→HTML 时触发）。
+ */
+async (page) => {
+  await page.reload({ waitUntil: 'networkidle', bypassCache: true });
+  return { ok: true };
+};

package/lib/helix-styles-guard.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const path = require('node:path');
+
+const HELIX_HOST_RE = /helixlife\.(cn|net|org)/i;
+const RELOAD_SCRIPT = path.join(__dirname, 'helix-reload-bypass-cache.run-code.js');
+
+/** 页面内检测 Helix 主样式表是否加载失败（缓存 HTML 指向已下线 CSS 时 link.sheet 为 null） */
+const BROKEN_STYLES_EVAL = [
+  'eval',
+  '--raw',
+  `[...document.querySelectorAll('link[rel="stylesheet"]')].filter(l=>l.href.includes('/static/css/')).some(l=>{try{return!l.sheet}catch{return true}})`,
+];
+
+function resolveCommandName(tokens) {
+  let i = 0;
+  if (tokens[i] === '--raw') i += 1;
+  if (tokens[i] === '--json') i += 1;
+  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
+  return tokens[i] || '';
+}
+
+function extractOpenUrl(tokens) {
+  let i = 0;
+  if (tokens[i] === '--raw') i += 1;
+  if (tokens[i] === '--json') i += 1;
+  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
+  if (tokens[i] !== 'open') return null;
+  i += 1;
+  for (; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t.startsWith('--')) {
+      if (!t.includes('=')) {
+        const next = tokens[i + 1];
+        if (next !== undefined && !next.startsWith('-')) i += 1;
+      }
+      continue;
+    }
+    if (t.startsWith('http://') || t.startsWith('https://')) return t;
+  }
+  return null;
+}
+
+function isHelixSiteOpen(tokens) {
+  if (resolveCommandName(tokens) !== 'open') return false;
+  const url = extractOpenUrl(tokens);
+  return Boolean(url && HELIX_HOST_RE.test(url));
+}
+
+/**
+ * open 完成后检测样式表；若主 CSS 未生效则 bypassCache 硬刷新一次。
+ * @param {(args: string[], opts?: object) => number | { code: number, stdout: string, stderr: string }} runPassthrough
+ * @returns {number} 附加步骤退出码（0 表示成功或未触发修复）
+ */
+function repairHelixStylesAfterOpen(runPassthrough) {
+  const check = runPassthrough(BROKEN_STYLES_EVAL, { capture: true });
+  const code = typeof check === 'object' ? check.code : check;
+  if (code !== 0) return code;
+
+  const broken = String(check.stdout || '').trim() === 'true';
+  if (!broken) return 0;
+
+  const reload = runPassthrough(
+    ['run-code', `--filename=${RELOAD_SCRIPT.replace(/\\/g, '/')}`],
+    { capture: true },
+  );
+  return typeof reload === 'object' ? reload.code : reload;
+}
+
+module.exports = {
+  HELIX_HOST_RE,
+  BROKEN_STYLES_EVAL,
+  RELOAD_SCRIPT,
+  resolveCommandName,
+  isHelixSiteOpen,
+  repairHelixStylesAfterOpen,
+};

package/lib/hide-nested-skills.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * 隐藏依赖包内的嵌套 Skill（如 @playwright/cli、playwright-core 自带的
+ * `SKILL.md`），避免被 WorkBuddy / Cursor 等按 `**\/SKILL.md` 扫描后注册为
+ * playwright-cli、playwright-trace 等额外工具项。
+ *
+ * 处理方式：把 `node_modules/**\/SKILL.md` 重命名为 `SKILL.md.disabled`。
+ * - 仅改文件名（basename 不再等于 `SKILL.md`），技能扫描器不再发现；
+ * - 这些文件只是给 Agent 看的说明文档，底层运行时不读取，重命名不影响功能；
+ * - 可逆：需要时把 `.disabled` 改回即可；重新 `npm install` 也会还原后由
+ *   postinstall 再次处理。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SKILL_FILENAME = 'SKILL.md';
+const DISABLED_SUFFIX = '.disabled';
+
+/** 写入 node_modules 根的哨兵文件，标记已处理，供 CLI 快路径跳过重复扫描。 */
+const SENTINEL_NAME = '.helix-nested-skills-hidden';
+
+/** 遍历目录时跳过的子目录（避免无意义的深扫）。 */
+const SKIP_DIRS = new Set(['.bin', '.cache']);
+
+/**
+ * 递归收集 dir 下所有 basename 为 `SKILL.md` 的文件绝对路径。
+ * @param {string} dir
+ * @param {string[]} acc
+ */
+function collectSkillFiles(dir, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      collectSkillFiles(full, acc);
+    } else if (entry.isFile() && entry.name === SKILL_FILENAME) {
+      acc.push(full);
+    }
+  }
+}
+
+/**
+ * 隐藏 <skillRoot>/node_modules 内的全部嵌套 SKILL.md。
+ * 幂等：已重命名过的文件不会被再次发现。
+ * @param {string} skillRoot 含本仓库 package.json 的目录
+ * @param {{ log?: (msg: string) => void }} [options]
+ * @returns {{ hidden: number, files: string[] }}
+ */
+function hideNestedSkills(skillRoot, options = {}) {
+  const log = options.log;
+  const nodeModules = path.join(skillRoot, 'node_modules');
+  if (!fs.existsSync(nodeModules)) {
+    return { hidden: 0, files: [] };
+  }
+
+  const found = [];
+  collectSkillFiles(nodeModules, found);
+
+  const hiddenFiles = [];
+  for (const file of found) {
+    const target = file + DISABLED_SUFFIX;
+    try {
+      // 覆盖式重命名：若上次的 .disabled 残留（如 reinstall 重新生成了 SKILL.md），先清理。
+      if (fs.existsSync(target)) {
+        fs.rmSync(target, { force: true });
+      }
+      fs.renameSync(file, target);
+      hiddenFiles.push(file);
+    } catch (e) {
+      if (log) {
+        log(`无法隐藏嵌套 Skill ${file}: ${e && e.message ? e.message : e}`);
+      }
+    }
+  }
+
+  // 始终刷新哨兵，标记已处理（即便本次没有可隐藏文件，也避免后续重复扫描）。
+  try {
+    fs.writeFileSync(path.join(nodeModules, SENTINEL_NAME), new Date().toISOString());
+  } catch {
+    // 哨兵写入失败不影响主流程。
+  }
+
+  if (log && hiddenFiles.length > 0) {
+    log(`已隐藏 ${hiddenFiles.length} 个依赖内嵌套 Skill（不对外注册）。`);
+  }
+  return { hidden: hiddenFiles.length, files: hiddenFiles };
+}
+
+/**
+ * 哨兵不存在时执行一次隐藏（供 CLI 快路径低成本调用）。
+ * @param {string} skillRoot
+ * @param {{ log?: (msg: string) => void }} [options]
+ * @returns {boolean} 本次是否执行了扫描
+ */
+function hideNestedSkillsOnce(skillRoot, options = {}) {
+  const sentinel = path.join(skillRoot, 'node_modules', SENTINEL_NAME);
+  if (fs.existsSync(sentinel)) {
+    return false;
+  }
+  hideNestedSkills(skillRoot, options);
+  return true;
+}
+
+module.exports = {
+  hideNestedSkills,
+  hideNestedSkillsOnce,
+  SENTINEL_NAME,
+  SKILL_FILENAME,
+  DISABLED_SUFFIX,
+};