skillcaddy 0.27.0

package/scripts/tui.js

@@ -0,0 +1,1058 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { execFile, spawn } from 'node:child_process';
+import { stdin as input, stdout as output } from 'node:process';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  disableAlias,
+  enableCollectionChoice,
+  enableSkillChoice,
+  formatAdvice,
+  listEnabledAliases,
+  listSkillChoices,
+  loadTuiState,
+  saveSkillMetadata,
+  summarizeState,
+  syncClaude
+} from '../lib/tuiActions.js';
+import { buildCollectionEnablePlan } from '../lib/enablePlan.js';
+import { isRemoteSkillFileInput } from '../lib/sourceHttp.js';
+import { isDefiniteGitSourceInput } from '../lib/sourceGitUrl.js';
+import { applyAddSource, planAddSource } from '../lib/sourceManager.js';
+import { checkCliInstall, installCliCommand } from '../lib/tuiInstall.js';
+import {
+  formatCompactSkillChoice,
+  formatSkillTableDivider,
+  formatSkillTableHeader,
+  getSkillIntroduction,
+  getSkillPage,
+  getSkillTableLayout
+} from '../lib/tuiLayout.js';
+import { resolveLibraryRoot } from '../lib/roots.js';
+import { isCliCommand, runCli } from './cli.js';
+import { formatOrigin } from './source.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const codeRootDir = path.resolve(__dirname, '..');
+
+if (isCliCommand(process.argv.slice(2))) {
+  const exitCode = await runCli({
+    argv: process.argv.slice(2),
+    rootDir: process.env.SKILLCADDY_ROOT,
+    runtimeRootDir: codeRootDir
+  });
+  process.exit(exitCode);
+}
+
+const options = parseArgs(process.argv.slice(2));
+// 原件库根与代码根解耦：clone 形态下两者同目录，发行形态（npm/npx）下
+// 原件库落到 ~/.skillcaddy/library，不会跟着包缓存一起消失。
+const libraryRoot = path.resolve(
+  options.root || process.env.SKILLCADDY_ROOT || resolveLibraryRoot({ codeRoot: codeRootDir })
+);
+const roots = { libraryRoot, codeRoot: codeRootDir };
+
+const rl = createInterface({ input, output });
+let state = await loadTuiState(roots, options.projectPath || process.cwd());
+
+try {
+  await mainLoop();
+} finally {
+  rl.close();
+}
+
+async function mainLoop() {
+  while (true) {
+    printSummary();
+    console.log([
+      '1. 查看已启用 skill',
+      '2. 浏览/搜索 skill',
+      '3. 启用 skill',
+      '4. 清理已启用 skill',
+      '5. 同步 Claude Code',
+      '6. 编辑 skill metadata',
+      '7. 查看项目诊断',
+      '8. 刷新项目状态',
+      '9. 更新 GitHub skill 库',
+      '10. 批量生成中文 note',
+      '11. 安装/检查全局 CLI + TUI 命令',
+      '12. 按地址添加远程 Source 到原件库',
+      '13. 管理全局 skill（~/.agents/skills）',
+      '14. 管理 Hermes skill（~/.hermes/skills）',
+      'q. 退出'
+    ].join('\n'));
+
+    const choice = await ask('选择操作');
+    if (choice === 'q') {
+      console.log('\nbyebye 👋');
+      return;
+    }
+
+    try {
+      if (choice === '1') printEnabledSkills();
+      else if (choice === '2') await browseSkills();
+      else if (choice === '3') await enableSkillFlow();
+      else if (choice === '4') await disableAliasFlow();
+      else if (choice === '5') await syncClaudeFlow();
+      else if (choice === '6') await editMetadataFlow();
+      else if (choice === '7') printAdvice();
+      else if (choice === '8') await refreshState();
+      else if (choice === '9') await updateGithubSkillsFlow();
+      else if (choice === '10') await batchTranslateNotesFlow();
+      else if (choice === '11') await installGlobalCommandFlow();
+      else if (choice === '12') await addRemoteSourceFlow();
+      else if (choice === '13') await globalSkillsFlow();
+      else if (choice === '14') await hermesSkillsFlow();
+      else console.log('未知操作');
+    } catch (error) {
+      const category = error?.category ? ` [${error.category}]` : '';
+      console.log(`错误${category}：${error.message}`);
+    }
+
+    await ask('回车继续');
+  }
+}
+
+async function installGlobalCommandFlow() {
+  const current = await checkCliInstall(codeRootDir);
+  console.log(current.message);
+  if (current.ok) return;
+  if (current.status !== 'missing') throw new Error(current.message);
+
+  const installed = await installCliCommand(codeRootDir);
+  console.log(installed.message);
+  console.log(`命令: ${installed.command}`);
+}
+
+async function addRemoteSourceFlow() {
+  const input = await ask('远程 Source 地址（留空或 b 返回）');
+  if (!input || isBack(input)) return;
+
+  if (isRemoteSkillFileInput(input)) {
+    const name = await ask('Remote file name（必填，b 返回）');
+    if (isBack(name)) return;
+    await applyRemoteSourcePlan(
+      await planAddSource({ rootDir: libraryRoot }, { input, name })
+    );
+    return;
+  }
+
+  if (!isSupportedRemoteAddress(input)) {
+    printUnsupportedRemoteSourceInput();
+    return;
+  }
+
+  let plan;
+  let archiveIdentityResolved = false;
+  try {
+    plan = await planAddSource({ rootDir: libraryRoot }, { input });
+  } catch (error) {
+    if (error?.category !== 'source-collision' || isDefiniteGitSourceInput(input)) {
+      throw error;
+    }
+    plan = await customizeRemoteArchivePlan(input);
+    if (!plan) return;
+    archiveIdentityResolved = true;
+  }
+  if (plan.input.type === 'remote-zip' && !archiveIdentityResolved) {
+    plan = await customizeRemoteArchivePlan(input, plan);
+    if (!plan) return;
+  }
+
+  if (!['git', 'remote-zip'].includes(plan.input.type)) {
+    printUnsupportedRemoteSourceInput();
+    return;
+  }
+  await applyRemoteSourcePlan(plan);
+}
+
+async function customizeRemoteArchivePlan(input, plan) {
+  const name = await ask('Archive 名称（留空自动推断，b 返回）');
+  if (isBack(name)) return null;
+  const namespace = await ask('Archive namespace（留空自动推断，b 返回）');
+  if (isBack(namespace)) return null;
+  if (!name && !namespace) {
+    if (plan) return plan;
+    return planAddSource({ rootDir: libraryRoot }, { input });
+  }
+
+  const request = { input };
+  if (name) request.name = name;
+  if (namespace) request.namespace = namespace;
+  return planAddSource({ rootDir: libraryRoot }, request);
+}
+
+function isSupportedRemoteAddress(input) {
+  if (isDefiniteGitSourceInput(input)) return true;
+  try {
+    const url = new URL(input.trim());
+    return ['http:', 'https:'].includes(url.protocol);
+  } catch {
+    return false;
+  }
+}
+
+function printUnsupportedRemoteSourceInput() {
+  console.log(
+    '当前 TUI 仅支持 HTTPS/SSH/SCP Git、公共 HTTP(S) Archive 和直接 /SKILL.md Remote file；Web source acquisition 暂不支持'
+  );
+}
+
+async function applyRemoteSourcePlan(plan) {
+  printRemoteSourcePlan(plan);
+  if (plan.status !== 'ready') {
+    if (plan.status === 'already-installed') {
+      const result = await applyAddSource({ rootDir: libraryRoot }, plan);
+      state = await loadTuiState(roots, state.projectPath);
+      printRemoteSourceResult(result);
+    } else {
+      console.log(`未执行添加：${plan.status}`);
+    }
+    return;
+  }
+
+  const confirm = await ask('确认添加? y/N');
+  if (!['y', 'yes'].includes(confirm.toLowerCase())) {
+    console.log('已取消添加');
+    return;
+  }
+
+  const result = await applyAddSource({ rootDir: libraryRoot }, plan);
+  state = await loadTuiState(roots, state.projectPath);
+  printRemoteSourceResult(result);
+}
+
+function printRemoteSourcePlan(plan) {
+  console.log(`Add plan: ${plan.status}`);
+  console.log(`source: ${plan.sourceId}`);
+  console.log(`install: ${plan.installPath}`);
+  console.log(`input: ${plan.input.type} ${plan.input.remote || plan.input.display}`);
+  console.log(`origin: ${formatOrigin(plan.origin)}`);
+  if (plan.focus) {
+    console.log(`focus: ${plan.focus.ref}${plan.focus.path ? ` ${plan.focus.path}` : ''}`);
+  }
+  if (plan.integrity) {
+    console.log(`integrity: ${plan.integrity.algorithm} ${plan.integrity.value}`);
+  }
+  console.log(`skills (${plan.skills.length}):`);
+  for (const skillPath of plan.skills) console.log(`  - ${skillPath}`);
+  console.log(`warnings (${plan.warnings.length}):`);
+  for (const warning of plan.warnings) {
+    console.log(`  - [${warning.category}] ${warning.skillPath}: ${warning.message}`);
+  }
+}
+
+function printRemoteSourceResult(result) {
+  console.log(`Outcome: ${result.status}`);
+  console.log(`source: ${result.sourceId}`);
+  console.log(`install: ${result.installPath}`);
+}
+
+function printSummary() {
+  const summary = summarizeState(state);
+  console.log('\nSkillcaddy TUI');
+  console.log(`原件库: ${libraryRoot}`);
+  if (codeRootDir !== libraryRoot) console.log(`代码根: ${codeRootDir}`);
+  console.log(`项目: ${summary.projectPath}`);
+  console.log(`Skills: ${summary.totalSkills}  可用: ${summary.availableSkills}  项目 Agents: ${summary.enabledAgents}  全局 Agents: ${state.global.length}  Hermes: ${state.hermes.length}  Claude: ${summary.enabledClaude}  诊断: ${summary.advice}`);
+  console.log('');
+}
+
+async function refreshState() {
+  console.log(`当前原件库: ${libraryRoot}`);
+  const nextProject = await ask(`项目路径 [${state.projectPath}]`);
+  state = await loadTuiState(roots, nextProject || state.projectPath);
+  console.log('已刷新');
+}
+
+async function updateGithubSkillsFlow() {
+  const githubDir = path.join(libraryRoot, 'github');
+  console.log(`将更新 GitHub skill 库: ${githubDir}`);
+  console.log('dirty 的子库会被跳过；不会 stash、reset 或覆盖本地改动。');
+  const confirm = await ask('确认运行更新? y/N');
+  if (!['y', 'yes'].includes(confirm.toLowerCase())) return;
+
+  await runCommand('bash', [
+    path.join(codeRootDir, 'scripts', 'pull-github.sh'),
+    githubDir,
+    state.projectPath
+  ]);
+  state = await loadTuiState(roots, state.projectPath);
+  console.log('已重新扫描本地状态');
+}
+
+function printEnabledSkills() {
+  console.log('\n已启用 skill / Agents');
+  if (state.enabled.length === 0) {
+    console.log('当前项目没有启用 Agents skill');
+  } else {
+    printSkillChoices(state.enabled.map(toEnabledSkillChoice));
+  }
+
+  console.log('\n已启用 skill / Claude Code');
+  const claudeSkills = state.claude?.skills || [];
+  if (claudeSkills.length === 0) {
+    console.log('当前项目没有启用 Claude Code skill');
+  } else {
+    printSkillChoices(claudeSkills.map((skill, index) => {
+      const agentsSkill = state.enabled.find((item) => item.alias === skill.alias);
+      return toEnabledSkillChoice(agentsSkill || skill, index);
+    }));
+  }
+
+  console.log('\n已启用 skill / 全局 Agents');
+  if (state.global.length === 0) {
+    console.log('当前没有全局 Agents skill');
+  } else {
+    printSkillChoices(state.global.map(toEnabledSkillChoice));
+  }
+
+  console.log('\n已启用 skill / Hermes');
+  if (state.hermes.length === 0) {
+    console.log('当前没有 Hermes skill');
+  } else {
+    printSkillChoices(state.hermes.map(toEnabledSkillChoice));
+  }
+}
+
+function toEnabledSkillChoice(enabledSkill, index) {
+  const sourceSkill = findSourceSkillForEnabled(enabledSkill);
+  return {
+    index: index + 1,
+    enabled: true,
+    skill: sourceSkill || {
+      name: enabledSkill.alias,
+      note: enabledSkill.isSymlink ? '' : '非软链接',
+      path: enabledSkill.targetPath || enabledSkill.linkPath,
+      autoEnable: true
+    }
+  };
+}
+
+function findSourceSkillForEnabled(enabledSkill) {
+  if (!enabledSkill) return null;
+  if (enabledSkill.targetPath) {
+    const byTarget = state.skills.find((skill) => skill.path === enabledSkill.targetPath);
+    if (byTarget) return byTarget;
+  }
+  return state.skills.find((skill) => skill.name === enabledSkill.alias) || null;
+}
+
+async function browseSkills() {
+  let query = '';
+  let source = '';
+
+  while (true) {
+    const skills = listSkillChoices(state, { query, source, limit: state.skills.length });
+    const libraries = groupSkillChoices(skills);
+    console.log(`\nSkill 库${query ? ` / 搜索: ${query}` : ''}${source ? ` / 来源: ${source}` : ''}`);
+    if (libraries.length === 0) {
+      console.log(`没有匹配的 skill。当前原件库是 ${libraryRoot}；如果你在 worktree 里开发，请用 --root 指向真实原件库。`);
+    } else {
+      printLibraryChoices(libraries);
+    }
+
+    console.log('输入库序号进入库；/关键词 搜索；s 设置来源；r 重置；b 返回');
+    const selected = await ask('选择');
+    if (isBack(selected)) return;
+    if (selected === 'r') {
+      query = '';
+      source = '';
+      continue;
+    }
+    if (selected === 's') {
+      source = await ask('来源 official/github/personal/archived，可空');
+      continue;
+    }
+    if (selected.startsWith('/')) {
+      query = selected.slice(1).trim();
+      continue;
+    }
+
+    const index = Number(selected);
+    if (!Number.isInteger(index) || index < 1 || index > libraries.length) {
+      console.log('请输入列表序号，或使用 /关键词 搜索');
+      continue;
+    }
+
+    await libraryFlow(libraries[index - 1]);
+  }
+}
+
+async function libraryFlow(library) {
+  let page = 1;
+
+  while (true) {
+    const skills = reindexChoices(listSkillChoices(state, {
+      source: library.source,
+      limit: state.skills.length
+    }).filter((choice) => choice.skill.collection === library.collection));
+    const currentLibrary = groupSkillChoices(skills)[0] || library;
+
+    console.log(`\n库详情: ${library.source}/${library.collection}`);
+    console.log(`路径: ${library.collectionPath}`);
+    console.log(`Skills: ${currentLibrary.total}  可一键添加: ${currentLibrary.bulkable}  已启用: ${currentLibrary.enabled}  跳过一键: ${currentLibrary.skipped}`);
+    printCollectionSetupStatus(library.source, library.collection);
+    const skillPage = getSkillPage(skills, page);
+    page = skillPage.currentPage;
+    printCompactSkillChoices(skillPage);
+    console.log('──────────────────');
+    console.log(`输入 skill 序号进入详情；a 一键添加；${skillPage.totalPages > 1 ? 'n/p 翻页；' : ''}b 返回`);
+
+    const selected = await ask('选择');
+    if (isBack(selected)) return;
+    if (selected === 'n' && page < skillPage.totalPages) {
+      page += 1;
+      continue;
+    }
+    if (selected === 'p' && page > 1) {
+      page -= 1;
+      continue;
+    }
+    if (selected === 'a') {
+      const scopeChoice = await ask('1. 启用到当前项目  2. 启用到全局  3. 启用到 Hermes  b. 取消');
+      if (isBack(scopeChoice)) continue;
+      if (!['1', '2', '3'].includes(scopeChoice)) {
+        console.log('请输入 1、2、3 或 b');
+        continue;
+      }
+      await enableLibraryFlow(currentLibrary, skills, scopeChoice === '2' ? 'global' : scopeChoice === '3' ? 'hermes' : 'project');
+      continue;
+    }
+
+    const index = Number(selected);
+    if (!Number.isInteger(index) || index < 1 || index > skills.length) {
+      console.log('请输入 skill 序号，或 a 一键添加该库');
+      continue;
+    }
+
+    await skillDetailFlow(skills[index - 1].skill.id);
+  }
+}
+
+async function enableLibraryFlow(library, choices, scope = 'project') {
+  const plan = buildCollectionEnablePlan(state, choices.map((choice) => choice.skill.id), { scope });
+  const targetIds = new Set(plan.targetSkillIds);
+  const targets = choices.filter((choice) => targetIds.has(choice.skill.id));
+  const skipped = choices.filter((choice) => plan.skippedSkillIds.includes(choice.skill.id));
+  const pendingSetups = scope === 'project' ? plan.setups : [];
+  if (targets.length === 0) {
+    console.log(skipped.length ? `没有需要启用的 skill，已跳过 ${skipped.length} 个不参与一键加入` : '没有需要启用的 skill');
+    return;
+  }
+
+  console.log(`将启用 ${targets.length} 个 skill；跳过 ${skipped.length} 个不参与一键加入。`);
+  targets.forEach((choice) => console.log(`- ${choice.skill.name}`));
+  let showSetupGuidance = false;
+  if (pendingSetups.length > 0) {
+    printSetupPreflight(pendingSetups);
+    console.log('1. 启用并显示配置指引\n2. 仅启用，稍后配置\nb. 取消');
+    const setupChoice = await ask('选择');
+    if (isBack(setupChoice)) return;
+    if (!['1', '2'].includes(setupChoice)) {
+      console.log('请输入 1、2 或 b');
+      return;
+    }
+    showSetupGuidance = setupChoice === '1';
+  } else {
+    const confirm = await ask(`确认一键添加 ${library.source}/${library.collection}? y/N`);
+    if (!['y', 'yes'].includes(confirm.toLowerCase())) return;
+  }
+
+  const result = await enableCollectionChoice(
+    roots,
+    state,
+    choices.map((choice) => choice.skill.id),
+    { scope }
+  );
+  state = await loadTuiState(roots, state.projectPath);
+  result.outcomes
+    .filter((outcome) => outcome.status === 'failed')
+    .forEach((outcome) => console.log(`失败 ${outcome.alias}: ${outcome.error}`));
+
+  console.log(`已处理 ${library.collection}: 启用 ${result.counts.enabled}，已存在 ${result.counts.unchanged}，跳过 ${result.counts.skipped}，失败 ${result.counts.failed}`);
+  if (!result.refresh.ok) {
+    console.log(`配置提醒刷新失败：${result.refresh.error}`);
+  }
+  const refreshedSetups = result.refresh.ok ? result.setups : pendingSetups;
+  const remainingSetups = refreshedSetups.filter((setup) => setup.status !== 'ready');
+  if (scope === 'project' && remainingSetups.length > 0) {
+    showSetupGuidance ? printSetupGuidance(remainingSetups) : console.log(`库已启用但仍待配置；稍后请运行 ${remainingSetups.map((setup) => setup.setupSkillName).join('、')}。`);
+  }
+}
+
+function printCollectionSetupStatus(source, collection) {
+  const setup = (state.setups || []).find((item) => item.id === `${source}/${collection}`);
+  if (!setup) return;
+  const labels = { missing: setup.affectedEnabledSkillIds.length > 0 ? '待配置' : '启用后需配置', partial: '配置不完整', ready: '已就绪', invalid: '配置定义无效' };
+  console.log(`初始化: ${labels[setup.status] || setup.status}${setup.setupSkillName ? `（${setup.setupSkillName}）` : ''}`);
+}
+
+function printSetupPreflight(setups) {
+  setups.forEach((setup) => {
+    const status = setup.status === 'partial' ? '配置不完整' : '尚未配置';
+    console.log(`初始化提醒: ${setup.id} ${status}，缺少 ${setup.missingArtifacts.join('、')}`);
+    console.log(`初始化 skill: ${setup.setupSkillName}`);
+  });
+}
+
+function printSetupGuidance(setups) {
+  setups.forEach((setup) => console.log(`下一步: ${setup.instruction}`));
+}
+
+async function enableSkillFlow() {
+  const value = await chooseSkill('要启用的 skill 关键词或 id');
+  if (!value) return;
+  const result = await enableSkillChoice(roots, state, value);
+  state = await loadTuiState(roots, state.projectPath);
+  console.log(result.unchanged ? `已存在：${result.alias}` : `已启用：${result.alias}`);
+  if (result.claudeSync?.ok === false) {
+    console.log(`Claude Code 同步失败：${result.claudeSync.error}`);
+  }
+}
+
+async function globalSkillsFlow() {
+  while (true) {
+    console.log('\n全局 Agents skill');
+    const globalAliases = listEnabledAliases(state, 'global');
+    if (globalAliases.length === 0) console.log('当前没有全局 skill');
+    else globalAliases.forEach((item) => console.log(`${item.index}. ${item.label}${item.canDisable ? '' : ' (只读)'}`));
+    console.log('a. 启用 skill 到全局\nd. 清理全局 skill\nb. 返回');
+    const choice = await ask('选择');
+    if (isBack(choice)) return;
+    if (choice === 'a') {
+      const value = await chooseSkill('要全局启用的 skill 关键词或 id', { scope: 'global' });
+      if (!value) continue;
+      const skill = findSkillById(value);
+      if (!skill) {
+        console.log(`找不到 skill：${value}`);
+        continue;
+      }
+      const suggestedAlias = findSuggestedAlias(skill.id) || skill.name;
+      const alias = await ask(`全局 skill 名称 [${suggestedAlias}]`) || suggestedAlias;
+      const result = await enableSkillChoice(roots, state, skill.id, { scope: 'global', alias });
+      state = await loadTuiState(roots, state.projectPath);
+      console.log(result.unchanged ? `全局已存在：${result.alias}` : `全局已启用：${result.alias}`);
+      continue;
+    }
+    if (choice === 'd') {
+      if (globalAliases.length === 0) continue;
+      const selected = await ask('输入序号或 skill 名称');
+      const alias = resolveIndexedValue(globalAliases, selected, 'alias');
+      const item = globalAliases.find((candidate) => candidate.alias === alias);
+      if (!item?.canDisable) {
+        console.log('这个全局链接不属于当前原件库，只能查看，不能由当前库清理');
+        continue;
+      }
+      const confirm = await ask(`清理全局 skill ${alias}? y/N`);
+      if (!['y', 'yes'].includes(confirm.toLowerCase())) continue;
+      const result = await disableAlias(state, alias, { scope: 'global', roots });
+      state = await loadTuiState(roots, state.projectPath);
+      console.log(result.removed ? `已清理全局：${alias}` : `未找到：${alias}`);
+      continue;
+    }
+    console.log('未知操作');
+  }
+}
+
+async function hermesSkillsFlow() {
+  while (true) {
+    console.log('\nHermes skill');
+    const hermesAliases = listEnabledAliases(state, 'hermes');
+    if (hermesAliases.length === 0) console.log('当前没有 Hermes skill');
+    else hermesAliases.forEach((item) => console.log(`${item.index}. ${item.label}${item.canDisable ? '' : ' (只读)'}`));
+    console.log('a. 启用 skill 到 Hermes\nd. 清理 Hermes skill\nb. 返回');
+    const choice = await ask('选择');
+    if (isBack(choice)) return;
+    if (choice === 'a') {
+      const value = await chooseSkill('要启用到 Hermes 的 skill 关键词或 id', { scope: 'hermes' });
+      if (!value) continue;
+      const skill = findSkillById(value);
+      if (!skill) {
+        console.log(`找不到 skill：${value}`);
+        continue;
+      }
+      const suggestedAlias = findSuggestedAlias(skill.id) || skill.name;
+      const alias = await ask(`Hermes skill 名称 [${suggestedAlias}]`) || suggestedAlias;
+      const result = await enableSkillChoice(roots, state, skill.id, { scope: 'hermes', alias });
+      state = await loadTuiState(roots, state.projectPath);
+      console.log(result.unchanged ? `Hermes 已存在：${result.alias}` : `Hermes 已启用：${result.alias}`);
+      continue;
+    }
+    if (choice === 'd') {
+      if (hermesAliases.length === 0) continue;
+      const selected = await ask('输入序号或 skill 名称');
+      const alias = resolveIndexedValue(hermesAliases, selected, 'alias');
+      const item = hermesAliases.find((candidate) => candidate.alias === alias);
+      if (!item?.canDisable) {
+        console.log('这个 Hermes 链接不属于当前原件库，只能查看，不能由当前库清理');
+        continue;
+      }
+      const confirm = await ask(`清理 Hermes skill ${alias}? y/N`);
+      if (!['y', 'yes'].includes(confirm.toLowerCase())) continue;
+      const result = await disableAlias(state, alias, { scope: 'hermes', roots });
+      state = await loadTuiState(roots, state.projectPath);
+      console.log(result.removed ? `已清理 Hermes：${alias}` : `未找到：${alias}`);
+      continue;
+    }
+    console.log('未知操作');
+  }
+}
+
+async function disableAliasFlow() {
+  const aliases = listEnabledAliases(state);
+  if (aliases.length === 0) {
+    console.log('当前项目没有 Agents skill');
+    return;
+  }
+  aliases.forEach((item) => console.log(`${item.index}. ${item.label}${item.canDisable ? '' : ' (不可清理)'}`));
+  const selected = await ask('输入序号或 skill 名称');
+  const alias = resolveIndexedValue(aliases, selected, 'alias');
+  const result = await disableAlias(state, alias);
+  state = await loadTuiState(roots, state.projectPath);
+  console.log(result.removed ? `已清理：${alias}` : `未找到：${alias}`);
+}
+
+async function syncClaudeFlow() {
+  const result = await syncClaude(state);
+  state = await loadTuiState(roots, state.projectPath);
+  console.log(result.unchanged ? 'Claude Code 已是最新' : `已同步 Claude Code：${result.linkPath}`);
+}
+
+async function editMetadataFlow() {
+  const value = await chooseSkill('要编辑 metadata 的 skill 关键词或 id');
+  if (!value) return;
+  await editAllMetadata(value);
+}
+
+async function skillDetailFlow(skillId) {
+  while (true) {
+    const skill = state.skills.find((item) => item.id === skillId);
+    if (!skill) {
+      console.log(`找不到 skill：${skillId}`);
+      return;
+    }
+
+    printSkillDetail(skill);
+    console.log([
+      '1. 启用到当前项目 Agents，并同步 Claude Code',
+      '2. 使用其他名称启用到当前项目',
+      '3. 启用到全局 Agents',
+      '4. 启用到 Hermes',
+      '5. 清理当前项目 skill',
+      '6. 编辑备注',
+      '7. 编辑 tags',
+      `8. ${skill.autoEnable === false ? '开启' : '关闭'}参与一键加入`,
+      '9. 编辑全部 metadata',
+      'b. 返回列表'
+    ].join('\n'));
+
+    const choice = await ask('选择操作');
+    if (isBack(choice)) return;
+
+    if (choice === '1') await enableSkillById(skill.id);
+    else if (choice === '2') await enableSkillWithAlias(skill);
+    else if (choice === '3') await enableGlobalSkillById(skill.id);
+    else if (choice === '4') await enableHermesSkillById(skill.id);
+    else if (choice === '5') await disableSkillAlias(skill);
+    else if (choice === '6') await editNote(skill);
+    else if (choice === '7') await editTags(skill);
+    else if (choice === '8') await toggleAutoEnable(skill);
+    else if (choice === '9') await editAllMetadata(skill.id);
+    else console.log('未知操作');
+  }
+}
+
+function printSkillDetail(skill) {
+  const enabled = findEnabledSkill(skill);
+  const globalEnabled = findGlobalSkill(skill);
+  const hermesEnabled = findHermesSkill(skill);
+  console.log('\nSkill 详情');
+  console.log(`名称: ${skill.name}`);
+  console.log(`ID: ${skill.id}`);
+  console.log(`来源: ${skill.source}/${skill.collection}`);
+  const statuses = [];
+  if (enabled) statuses.push(`项目=${enabled.alias}`);
+  if (globalEnabled) statuses.push(`全局=${globalEnabled.alias}`);
+  if (hermesEnabled) statuses.push(`Hermes=${hermesEnabled.alias}`);
+  console.log(`状态: ${statuses.length > 0 ? statuses.join('，') : '未启用'}`);
+  console.log(`一键加入: ${skill.autoEnable === false ? '否' : '是'}`);
+  console.log(`Tags: ${(skill.tags || []).join(', ') || '-'}`);
+  console.log(`介绍: ${getSkillIntroduction(skill)}`);
+  console.log(`路径: ${skill.path}`);
+  console.log('');
+}
+
+async function enableSkillById(skillId) {
+  const result = await enableSkillChoice(roots, state, skillId);
+  await reportEnableResult(result);
+}
+
+async function enableSkillWithAlias(skill) {
+  const suggestedAlias = findSuggestedAlias(skill.id) || skill.name;
+  const alias = await ask(`项目中的 skill 名称 [${suggestedAlias}]`) || suggestedAlias;
+  const result = await enableSkillChoice(roots, state, skill.id, { alias });
+  await reportEnableResult(result);
+}
+
+async function enableGlobalSkillById(skillId) {
+  const skill = state.skills.find((item) => item.id === skillId);
+  if (!skill) return;
+  const suggestedAlias = findSuggestedAlias(skill.id) || skill.name;
+  const alias = await ask(`全局 skill 名称 [${suggestedAlias}]`) || suggestedAlias;
+  const result = await enableSkillChoice(roots, state, skill.id, { scope: 'global', alias });
+  await reportEnableResult(result);
+}
+
+async function enableHermesSkillById(skillId) {
+  const skill = state.skills.find((item) => item.id === skillId);
+  if (!skill) return;
+  if (!['official', 'github', 'personal'].includes(skill.source)) {
+    console.log('Hermes 只接受 official、github 或 personal 来源的 skill');
+    return;
+  }
+  const suggestedAlias = findSuggestedAlias(skill.id) || skill.name;
+  const alias = await ask(`Hermes skill 名称 [${suggestedAlias}]`) || suggestedAlias;
+  const result = await enableSkillChoice(roots, state, skill.id, { scope: 'hermes', alias });
+  await reportEnableResult(result);
+}
+
+async function reportEnableResult(result) {
+  state = await loadTuiState(roots, state.projectPath);
+  const prefix = result.scope === 'global' ? '全局' : result.scope === 'hermes' ? 'Hermes' : '项目';
+  console.log(result.unchanged ? `${prefix}已存在：${result.alias}` : `${prefix}已启用：${result.alias}`);
+  if (result.claudeSync?.ok === false) {
+    console.log(`Claude Code 同步失败：${result.claudeSync.error}`);
+  }
+}
+
+function findSuggestedAlias(skillId) {
+  for (const advice of state.advice) {
+    const action = (advice.actions || []).find((item) => item.type === 'enable-with-alias' && item.skillId === skillId);
+    if (action) return action.alias;
+  }
+  return '';
+}
+
+function findSkillById(skillId) {
+  return state.skills.find((skill) => skill.id === skillId);
+}
+
+async function disableSkillAlias(skill) {
+  const enabled = findEnabledSkill(skill);
+  if (!enabled) {
+    console.log('当前项目未启用这个 skill');
+    return;
+  }
+  const confirm = await ask(`清理已启用 skill ${enabled.alias}? y/N`);
+  if (!['y', 'yes'].includes(confirm.toLowerCase())) return;
+  const result = await disableAlias(state, enabled.alias);
+  state = await loadTuiState(roots, state.projectPath);
+  console.log(result.removed ? `已清理：${enabled.alias}` : `未找到：${enabled.alias}`);
+}
+
+async function editNote(skill) {
+  const note = await ask(`备注 [${skill.note || ''}]`);
+  if (!note) return;
+  await saveSkillMetadata(roots, state, skill.id, { note });
+  state = await loadTuiState(roots, state.projectPath);
+  console.log('已保存备注');
+}
+
+async function editTags(skill) {
+  const tags = await ask(`Tags 逗号分隔 [${(skill.tags || []).join(', ')}]`);
+  if (!tags) return;
+  await saveSkillMetadata(roots, state, skill.id, {
+    tags: tags.split(',').map((tag) => tag.trim()).filter(Boolean)
+  });
+  state = await loadTuiState(roots, state.projectPath);
+  console.log('已保存 tags');
+}
+
+async function toggleAutoEnable(skill) {
+  await saveSkillMetadata(roots, state, skill.id, {
+    autoEnable: skill.autoEnable === false
+  });
+  state = await loadTuiState(roots, state.projectPath);
+  console.log('已更新一键加入设置');
+}
+
+async function editAllMetadata(skillId) {
+  const skill = state.skills.find((item) => item.id === skillId);
+  const note = await ask(`备注 [${skill?.note || ''}]`);
+  const tags = await ask(`Tags 逗号分隔 [${(skill?.tags || []).join(', ')}]`);
+  const autoEnableInput = await ask(`参与一键加入 true/false [${skill?.autoEnable !== false}]`);
+
+  const metadata = {};
+  if (note) metadata.note = note;
+  if (tags) metadata.tags = tags.split(',').map((tag) => tag.trim()).filter(Boolean);
+  if (autoEnableInput) metadata.autoEnable = parseBoolean(autoEnableInput);
+
+  await saveSkillMetadata(roots, state, skillId, metadata);
+  state = await loadTuiState(roots, state.projectPath);
+  console.log('已保存 metadata');
+}
+
+function printAdvice() {
+  const advice = formatAdvice(state.advice);
+  if (advice.length === 0) {
+    console.log('当前没有 advice');
+    return;
+  }
+  advice.forEach((item) => {
+    console.log(`${item.index}. [${item.severity}] ${item.title}`);
+    console.log(`   ${item.detail}`);
+  });
+}
+
+async function chooseSkill(prompt, options = {}) {
+  const query = await ask(prompt);
+  const choices = listSkillChoices(state, {
+    query,
+    limit: options.scope === 'hermes' ? state.skills.length : 20,
+    scope: options.scope
+  })
+    .filter((choice) => options.scope !== 'hermes' || ['official', 'github', 'personal'].includes(choice.skill.source))
+    .slice(0, 20);
+  if (choices.length === 0) {
+    console.log(`没有匹配的 skill。当前原件库是 ${libraryRoot}；如果你在 worktree 里开发，请用 --root 指向真实原件库。`);
+    return '';
+  }
+  if (choices.length === 1) {
+    console.log(`匹配：${choices[0].label}${choices[0].enabled ? ' (已启用)' : ''}`);
+    const confirm = await ask('直接使用这个 skill? Y/n');
+    if (!confirm || ['y', 'yes'].includes(confirm.toLowerCase())) return choices[0].id;
+  }
+  printSkillChoices(choices);
+  const selected = await ask('输入序号或完整 id');
+  return resolveIndexedValue(choices, selected, 'id');
+}
+
+function printSkillChoices(choices) {
+  printCompactSkillChoices(getSkillPage(choices, 1, Math.max(choices.length, 1)));
+}
+
+function printCompactSkillChoices(skillPage) {
+  const indexWidth = String(skillPage.end).length;
+  const tableLayout = getSkillTableLayout(output.columns);
+  console.log(`\nSkills ${skillPage.start}-${skillPage.end} / ${skillPage.total}`);
+  console.log(formatSkillTableHeader(tableLayout));
+  console.log(formatSkillTableDivider(tableLayout));
+  skillPage.choices.forEach((choice) => console.log(formatCompactSkillChoice(choice, indexWidth, tableLayout)));
+  if (skillPage.totalPages > 1) {
+    console.log(`第 ${skillPage.currentPage}/${skillPage.totalPages} 页`);
+  }
+}
+
+function findEnabledSkill(skill) {
+  return state.enabled.find((enabled) => enabled.targetPath === skill.path);
+}
+
+function findGlobalSkill(skill) {
+  return state.global.find((enabled) => enabled.targetPath === skill.path);
+}
+
+function findHermesSkill(skill) {
+  return state.hermes.find((enabled) => enabled.targetPath === skill.path);
+}
+
+function groupSkillChoices(choices) {
+  const groups = new Map();
+  for (const choice of choices) {
+    const key = `${choice.skill.source}/${choice.skill.collection}`;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        index: groups.size + 1,
+        key,
+        source: choice.skill.source,
+        collection: choice.skill.collection,
+        collectionPath: choice.skill.collectionPath,
+        total: 0,
+        enabled: 0,
+        skipped: 0,
+        bulkable: 0
+      });
+    }
+    const group = groups.get(key);
+    group.total += 1;
+    if (choice.enabled) group.enabled += 1;
+    if (choice.skill.autoEnable === false) group.skipped += 1;
+    if (!choice.enabled && choice.skill.autoEnable !== false) group.bulkable += 1;
+  }
+
+  return [...groups.values()];
+}
+
+function printLibraryChoices(libraries) {
+  libraries.forEach((library) => {
+    const parts = [`${library.total} 个 skill`];
+    if (library.enabled) parts.push(`已启用 ${library.enabled}`);
+    if (library.skipped) parts.push(`一键跳过 ${library.skipped}`);
+    const setup = (state.setups || []).find((item) => item.id === `${library.source}/${library.collection}`);
+    if (setup?.status === 'missing') parts.push(setup.affectedEnabledSkillIds.length > 0 ? '待配置' : '需初始化');
+    else if (setup?.status === 'partial') parts.push('配置不完整');
+    else if (setup?.status === 'ready') parts.push('已就绪');
+    console.log(`${library.index}. ${library.source}/${library.collection} (${parts.join('，')})`);
+  });
+}
+
+function reindexChoices(choices) {
+  return choices.map((choice, index) => ({ ...choice, index: index + 1 }));
+}
+
+function resolveIndexedValue(items, selected, field) {
+  const text = String(selected || '').trim();
+  const index = Number(text);
+  if (Number.isInteger(index) && index >= 1 && index <= items.length) {
+    return items[index - 1][field];
+  }
+  return text;
+}
+
+function parseBoolean(value) {
+  const text = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes', 'y', 'on'].includes(text)) return true;
+  if (['false', '0', 'no', 'n', 'off'].includes(text)) return false;
+  throw new Error('autoEnable 必须是 true 或 false');
+}
+
+async function ask(prompt) {
+  try {
+    return (await rl.question(`${prompt}: `)).trim();
+  } catch (error) {
+    if (error.code === 'ABORT_ERR' || error.code === 'ERR_USE_AFTER_CLOSE' || error.code === 'ERR_INVALID_STATE' || error.name === 'AbortError') {
+      rl.close();
+      console.log('\nbyebye 👋');
+      process.exit(0);
+    }
+    throw error;
+  }
+}
+
+async function runCommand(command, args) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: codeRootDir,
+      stdio: 'inherit'
+    });
+
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      code === 0 ? resolve() : reject(new Error(`${command} exited with code ${code}`));
+    });
+  });
+}
+
+function isBack(value) {
+  return String(value || '').trim().toLowerCase() === 'b';
+}
+
+async function batchTranslateNotesFlow() {
+  // 1. 筛选待翻译的 skills
+  const pending = state.skills.filter((skill) => {
+    if (skill.source === 'archived') return false;
+    const note = String(skill.note || '').trim();
+    const description = String(skill.description || '').trim();
+    return description && !note;
+  });
+
+  if (pending.length === 0) {
+    console.log('所有 skill 都已有中文介绍');
+    return;
+  }
+
+  console.log(`\n待翻译 skill: ${pending.length} 个`);
+
+  // 2. 让用户选择批次大小
+  console.log('处理方式:');
+  console.log('  1. 处理 5 个');
+  console.log('  2. 处理 10 个');
+  console.log('  3. 处理全部');
+  console.log('  b. 返回');
+
+  const batchChoice = await ask('选择');
+  if (isBack(batchChoice)) return;
+
+  let batchSize;
+  if (batchChoice === '1') batchSize = 5;
+  else if (batchChoice === '2') batchSize = 10;
+  else if (batchChoice === '3') batchSize = pending.length;
+  else {
+    console.log('未知选项');
+    return;
+  }
+
+  const toProcess = pending.slice(0, batchSize);
+  console.log(`\n将处理 ${toProcess.length} 个 skill:\n`);
+
+  // 3. 显示待处理列表
+  toProcess.forEach((skill, index) => {
+    console.log(`${index + 1}. ${skill.name} [${skill.source}/${skill.collection}]`);
+  });
+
+  const confirmStart = await ask('\n开始处理? y/N');
+  if (!['y', 'yes'].includes(confirmStart.toLowerCase())) return;
+
+  // 4. 逐个处理
+  const results = [];
+  for (let i = 0; i < toProcess.length; i += 1) {
+    const skill = toProcess[i];
+    console.log(`\n${'─'.repeat(50)}`);
+    console.log(`[${i + 1}/${toProcess.length}] ${skill.name}`);
+    console.log(`来源: ${skill.source}/${skill.collection}`);
+    console.log(`\n英文描述:`);
+    console.log(skill.description);
+    console.log('');
+
+    const note = await ask('输入中文介绍 (留空跳过, q 退出)');
+    if (note.toLowerCase() === 'q') {
+      console.log('已中断');
+      break;
+    }
+    if (!note) {
+      console.log('已跳过');
+      results.push({ skill, status: 'skipped' });
+      continue;
+    }
+
+    try {
+      await saveSkillMetadata(roots, state, skill.id, { note });
+      state = await loadTuiState(roots, state.projectPath);
+      console.log('✓ 已保存');
+      results.push({ skill, status: 'saved', note });
+    } catch (error) {
+      console.log(`✗ 保存失败: ${error.message}`);
+      results.push({ skill, status: 'failed', error: error.message });
+    }
+  }
+
+  // 5. 汇总结果
+  console.log(`\n${'─'.repeat(50)}`);
+  console.log('处理完成');
+  const saved = results.filter((r) => r.status === 'saved').length;
+  const skipped = results.filter((r) => r.status === 'skipped').length;
+  const failed = results.filter((r) => r.status === 'failed').length;
+  console.log(`已保存: ${saved}，已跳过: ${skipped}，失败: ${failed}`);
+}
+
+function parseArgs(args) {
+  const options = { root: '', projectPath: '' };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--root') {
+      options.root = args[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--root=')) {
+      options.root = arg.slice('--root='.length);
+      continue;
+    }
+    if (!options.projectPath) options.projectPath = arg;
+  }
+
+  return options;
+}