code-abyss 2.0.7 → 2.0.8

package/bin/install.js

@@ -15,18 +15,36 @@ if (parseInt(process.versions.node) < parseInt(MIN_NODE)) {
   process.exit(1);
 }
 const PKG_ROOT = fs.realpathSync(path.join(__dirname, '..'));
-const { shouldSkip, copyRecursive, rmSafe, deepMergeNew, printMergeLog } =
+const { shouldSkip, copyRecursive, rmSafe, deepMergeNew, printMergeLog, formatActionableError } =
   require(path.join(__dirname, 'lib', 'utils.js'));
 const {
   collectInvocableSkills,
 } = require(path.join(__dirname, 'lib', 'skill-registry.js'));
+const {
+  resolveProjectPacks,
+  selectProjectPacksForInstall,
+  readProjectPackLock,
+} = require(path.join(__dirname, 'lib', 'pack-registry.js'));
+const { syncProjectBootstrapArtifacts } = require(path.join(__dirname, 'lib', 'pack-bootstrap.js'));
+const { writeReportArtifact } = require(path.join(__dirname, 'lib', 'pack-reports.js'));
+const {
+  listInstallTargets,
+  listTargetNames,
+  isSupportedTarget,
+  getManagedRootRelativeDir,
+  formatTargetList,
+} = require(path.join(__dirname, 'lib', 'target-registry.js'));
 const {
   listStyles,
   getDefaultStyle,
   resolveStyle,
-  renderCodexAgents,
+  renderGeminiContext,
 } = require(path.join(__dirname, 'lib', 'style-registry.js'));
 const { detectCclineBin, installCcline: _installCcline } = require(path.join(__dirname, 'lib', 'ccline.js'));
+const { installGstackClaudePack } = require(path.join(__dirname, 'lib', 'gstack-claude.js'));
+const { installGstackGeminiPack } = require(path.join(__dirname, 'lib', 'gstack-gemini.js'));
+
+const { installGstackCodexPack } = require(path.join(__dirname, 'lib', 'gstack-codex.js'));
 const {
   detectCodexAuth: detectCodexAuthImpl,
   getCodexCoreFiles,
@@ -38,6 +56,12 @@ const {
   detectClaudeAuth: detectClaudeAuthImpl,
   postClaude: postClaudeFlow,
 } = require(path.join(__dirname, 'adapters', 'claude.js'));
+const {
+  GEMINI_SETTINGS_TEMPLATE,
+  getGeminiCoreFiles,
+  detectGeminiAuth: detectGeminiAuthImpl,
+  postGemini: postGeminiFlow,
+} = require(path.join(__dirname, 'adapters', 'gemini.js'));
 
 // ── ANSI ──
 
@@ -93,7 +117,41 @@ function detectCodexAuth() {
   return detectCodexAuthImpl({ HOME, warn });
 }
 
-// ── 模板 ──
+function detectGeminiAuth(settings) {
+  return detectGeminiAuthImpl({ settings, HOME, warn });
+}
+
+function resolveManagedRootDir(tgt, rootName = tgt) {
+  return path.join(HOME, getManagedRootRelativeDir(rootName));
+}
+
+function normalizeManifestEntry(entry, defaultRoot) {
+  if (typeof entry === 'string') return { root: defaultRoot, path: entry };
+  if (entry && typeof entry === 'object' && typeof entry.path === 'string') {
+    return { root: entry.root || defaultRoot, path: entry.path };
+  }
+  throw new Error('manifest 条目格式无效');
+}
+
+function pushManifestEntry(list, rootName, relPath) {
+  list.push({ root: rootName, path: relPath });
+}
+
+function pushPackReport(manifest, report) {
+  if (!manifest.pack_reports) manifest.pack_reports = [];
+  manifest.pack_reports.push(report);
+}
+
+function resolveEffectivePackSource(sourceMode, installResult) {
+  return (installResult && installResult.sourceMode) || sourceMode || 'pinned';
+}
+
+function manifestLabel(entry, defaultRoot) {
+  const normalized = normalizeManifestEntry(entry, defaultRoot);
+  return normalized.root === defaultRoot
+    ? normalized.path
+    : `${normalized.root}/${normalized.path}`;
+}
 
 // ── CLI 参数 ──
 
@@ -115,8 +173,8 @@ for (let i = 0; i < args.length; i++) {
     console.log(`${c.b('用法:')}  npx code-abyss [选项]
 
 ${c.b('选项:')}
-  --target ${c.cyn('<claude|codex>')}      安装目标
-  --uninstall ${c.cyn('<claude|codex>')}   卸载目标
+  --target ${c.cyn(`<${formatTargetList('|')}>`)}      安装目标
+  --uninstall ${c.cyn(`<${formatTargetList('|')}>`)}   卸载目标
   --style ${c.cyn('<slug>')}               指定输出风格
   --list-styles               列出可用输出风格
   --yes, -y                    全自动模式
@@ -137,27 +195,51 @@ ${c.b('示例:')}
 // ── 卸载 ──
 
 function runUninstall(tgt) {
-  if (!['claude', 'codex'].includes(tgt)) { fail('--uninstall 必须是 claude 或 codex'); process.exit(1); }
-  const targetDir = path.join(HOME, `.${tgt}`);
+  if (!isSupportedTarget(tgt)) {
+    fail(formatActionableError(`--uninstall 必须是 ${listTargetNames().join('、')}`, 'Try: npx code-abyss --uninstall claude'));
+    process.exit(1);
+  }
+  const targetDir = resolveManagedRootDir(tgt);
   const backupDir = path.join(targetDir, '.sage-backup');
   const manifestPath = path.join(backupDir, 'manifest.json');
   if (!fs.existsSync(manifestPath)) { fail(`未找到安装记录: ${manifestPath}`); process.exit(1); }
 
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  if (manifest.manifest_version && manifest.manifest_version > 1) {
+  if (manifest.manifest_version && manifest.manifest_version > 2) {
     fail(`manifest 版本 ${manifest.manifest_version} 不兼容，请升级 code-abyss 后再卸载`);
     process.exit(1);
   }
   divider(`卸载 Code Abyss v${manifest.version}`);
+  if (Array.isArray(manifest.pack_reports) && manifest.pack_reports.length > 0) {
+    console.log(`  ${c.b('Packs:')}`);
+    manifest.pack_reports.forEach((report) => {
+      const source = report.source ? ` source=${report.source}` : '';
+      const reason = report.reason ? ` reason=${report.reason}` : '';
+      console.log(`    ${report.pack}@${report.host} ${report.status || 'installed'}${source}${reason}`);
+    });
+  }
 
-  (manifest.installed || []).forEach(f => {
-    const p = path.join(targetDir, f);
-    if (fs.existsSync(p)) { rmSafe(p); console.log(`  ${c.red('✘')} ${f}`); }
+  (manifest.installed || []).forEach((entry) => {
+    const normalized = normalizeManifestEntry(entry, tgt);
+    const installRoot = resolveManagedRootDir(tgt, normalized.root);
+    const targetPath = path.join(installRoot, normalized.path);
+    if (fs.existsSync(targetPath)) {
+      rmSafe(targetPath);
+      console.log(`  ${c.red('✘')} ${manifestLabel(entry, tgt)}`);
+    }
   });
-  (manifest.backups || []).forEach(f => {
-    const bp = path.join(backupDir, f);
-    const tp = path.join(targetDir, f);
-    if (fs.existsSync(bp)) { fs.renameSync(bp, tp); ok(`恢复: ${f}`); }
+  (manifest.backups || []).forEach((entry) => {
+    const normalized = normalizeManifestEntry(entry, tgt);
+    const backupPath = path.join(backupDir, normalized.root, normalized.path);
+    const legacyBackupPath = path.join(backupDir, normalized.path);
+    const sourcePath = fs.existsSync(backupPath) ? backupPath : legacyBackupPath;
+    const restoreRoot = resolveManagedRootDir(tgt, normalized.root);
+    const restorePath = path.join(restoreRoot, normalized.path);
+    if (fs.existsSync(sourcePath)) {
+      fs.mkdirSync(path.dirname(restorePath), { recursive: true });
+      fs.renameSync(sourcePath, restorePath);
+      ok(`恢复: ${manifestLabel(entry, tgt)}`);
+    }
   });
 
   rmSafe(backupDir);
@@ -173,24 +255,17 @@ function scanInvocableSkills(skillsDir) {
   return collectInvocableSkills(skillsDir);
 }
 
-const INVOCABLE_TARGETS = {
-  claude: {
-    dir: 'commands',
-    label: '斜杠命令',
-    skillRoot: '~/.claude/skills',
-  },
-  codex: {
-    dir: 'prompts',
-    label: 'custom prompts',
-    skillRoot: '~/.codex/skills',
-  },
+const CLAUDE_COMMAND_TARGET = {
+  dir: 'commands',
+  label: '斜杠命令',
+  skillRoot: '~/.claude/skills',
 };
 
-function getInvocableTarget(targetName) {
-  const targetCfg = INVOCABLE_TARGETS[targetName];
-  if (!targetCfg) throw new Error(`不支持的 invocable target: ${targetName}`);
-  return targetCfg;
-}
+const GEMINI_COMMAND_TARGET = {
+  dir: 'commands',
+  label: 'Gemini commands',
+  skillRoot: '~/.gemini/skills',
+};
 
 function getSkillPath(skillRoot, skillRelPath) {
   return skillRelPath
@@ -212,23 +287,20 @@ function buildCommandFrontmatter(skill) {
   return lines;
 }
 
-function buildSkillArtifactSpec(skill, targetName) {
-  const targetCfg = getInvocableTarget(targetName);
+function buildClaudeCommandSpec(skill) {
   const runtimeType = skill.runtimeType || 'knowledge';
   const allowedTools = Array.isArray(skill.allowedTools)
     ? skill.allowedTools.join(', ')
     : (skill.allowedTools || 'Read');
   return {
-    targetName,
-    targetCfg,
     name: skill.name,
     description: skill.description,
     argumentHint: skill.argumentHint || '',
     allowedTools,
     relPath: skill.relPath,
     runtimeType,
-    scriptRunner: `node ${targetCfg.skillRoot}/run_skill.js ${skill.name} $ARGUMENTS`,
-    skillPath: getSkillPath(targetCfg.skillRoot, skill.relPath),
+    scriptRunner: `node ${CLAUDE_COMMAND_TARGET.skillRoot}/run_skill.js ${skill.name} $ARGUMENTS`,
+    skillPath: getSkillPath(CLAUDE_COMMAND_TARGET.skillRoot, skill.relPath),
   };
 }
 
@@ -248,31 +320,6 @@ function buildClaudeBody(spec) {
   return lines;
 }
 
-function buildCodexPromptBody(spec) {
-  const lines = [];
-  if (spec.argumentHint) lines.push(`Arguments: ${spec.argumentHint}`, '');
-  lines.push(`Read \`${spec.skillPath}\` before acting.`, '');
-  if (spec.runtimeType === 'scripted') {
-    lines.push(`Then run \`${spec.scriptRunner}\`.`);
-    lines.push('Do not stop between steps unless blocked by permissions or missing required inputs.');
-    lines.push('Use the skill guidance plus script output to complete the task end-to-end.');
-    return lines;
-  }
-
-  lines.push('Use that skill as the authoritative playbook for the task.');
-  lines.push('Respond with concrete actions instead of generic advice.');
-  return lines;
-}
-
-function generateInvocableContent(skill, targetName) {
-  const spec = buildSkillArtifactSpec(skill, targetName);
-  const lines = targetName === 'claude' ? buildCommandFrontmatter(spec) : [];
-  const body = targetName === 'claude'
-    ? buildClaudeBody(spec)
-    : buildCodexPromptBody(spec);
-  return [...lines, ...body, ''].join('\n');
-}
-
 function normalizeGeneratedSkill(meta, skillRelPath, runtimeType) {
   return {
     ...meta,
@@ -285,19 +332,67 @@ function normalizeGeneratedSkill(meta, skillRelPath, runtimeType) {
 }
 
 function generateCommandContent(meta, skillRelPath, runtimeType = 'knowledge') {
-  return generateInvocableContent(normalizeGeneratedSkill(meta, skillRelPath, runtimeType), 'claude');
+  const skill = normalizeGeneratedSkill(meta, skillRelPath, runtimeType);
+  const spec = buildClaudeCommandSpec(skill);
+  return [...buildCommandFrontmatter(spec), ...buildClaudeBody(spec), ''].join('\n');
 }
 
-function generatePromptContent(meta, skillRelPath, runtimeType = 'knowledge') {
-  return generateInvocableContent(normalizeGeneratedSkill(meta, skillRelPath, runtimeType), 'codex');
+function buildGeminiCommandSpec(skill) {
+  const runtimeType = skill.runtimeType || 'knowledge';
+  return {
+    name: skill.name,
+    description: skill.description || '',
+    relPath: skill.relPath,
+    runtimeType,
+    scriptRunner: `node ${GEMINI_COMMAND_TARGET.skillRoot}/run_skill.js ${skill.name}`,
+    skillPath: getSkillPath(GEMINI_COMMAND_TARGET.skillRoot, skill.relPath),
+  };
+}
+
+function escapeTomlMultiline(value) {
+  return String(value || '').replace(/"""/g, '\"\"\"').trim();
 }
 
-function installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest, targetName) {
+function buildGeminiPromptBody(spec) {
+  const lines = [
+    `Read \`${spec.skillPath}\` before acting.`,
+    '',
+    'If Gemini CLI appended the raw command invocation after these instructions, parse any extra arguments from that appended invocation before acting.',
+    '',
+  ];
+
+  if (spec.runtimeType === 'scripted') {
+    lines.push(`Then run \`${spec.scriptRunner} <parsed-arguments>\` and complete the task end-to-end.`);
+    lines.push('Do not stop between steps unless blocked by permissions or missing required input.');
+  } else {
+    lines.push('Use that skill as the authoritative playbook for the task.');
+    lines.push('Respond with concrete actions instead of generic advice.');
+  }
+
+  return lines.join('\n').trim();
+}
+
+function generateGeminiCommandContent(meta, skillRelPath, runtimeType = 'knowledge') {
+  const skill = normalizeGeneratedSkill(meta, skillRelPath, runtimeType);
+  const spec = buildGeminiCommandSpec(skill);
+  const description = escapeTomlMultiline(spec.description).replace(/"/g, '\\"');
+  const prompt = escapeTomlMultiline(buildGeminiPromptBody(spec));
+  return [
+    `description = "${description}"`,
+    'prompt = """',
+    prompt,
+    '"""',
+    '',
+  ].join('\n');
+}
+
+
+function installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest) {
   const skills = collectInvocableSkills(skillsSrcDir);
   if (skills.length === 0) return 0;
+  const rootName = manifest.target || 'claude';
 
-  const targetCfg = getInvocableTarget(targetName);
-  const installDir = path.join(targetDir, targetCfg.dir);
+  const installDir = path.join(targetDir, CLAUDE_COMMAND_TARGET.dir);
   fs.mkdirSync(installDir, { recursive: true });
 
   let totalFiles = 0;
@@ -309,53 +404,95 @@ function installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest,
     names.forEach((cmdName) => {
       const fileName = `${cmdName}.md`;
       const destFile = path.join(installDir, fileName);
-      const relFile = path.posix.join(targetCfg.dir, fileName);
+      const relFile = path.posix.join(CLAUDE_COMMAND_TARGET.dir, fileName);
 
       if (fs.existsSync(destFile)) {
-        const backupSubdir = path.join(backupDir, targetCfg.dir);
+        const backupSubdir = path.join(backupDir, rootName, CLAUDE_COMMAND_TARGET.dir);
         fs.mkdirSync(backupSubdir, { recursive: true });
         fs.copyFileSync(destFile, path.join(backupSubdir, fileName));
-        manifest.backups.push(relFile);
+        pushManifestEntry(manifest.backups, rootName, relFile);
         info(`备份: ${c.d(relFile)}`);
       }
 
-      const content = generateInvocableContent(skill, targetName);
+      const content = generateCommandContent(skill, skill.relPath, skill.runtimeType);
       fs.writeFileSync(destFile, content);
-      manifest.installed.push(relFile);
+      pushManifestEntry(manifest.installed, rootName, relFile);
       totalFiles++;
     });
   });
 
-  ok(`${targetCfg.dir}/ ${c.d(`(自动生成 ${totalFiles} 个 ${targetCfg.label})`)}`);
+  ok(`${CLAUDE_COMMAND_TARGET.dir}/ ${c.d(`(自动生成 ${totalFiles} 个 ${CLAUDE_COMMAND_TARGET.label})`)}`);
   return skills.length;
 }
 
 function installGeneratedCommands(skillsSrcDir, targetDir, backupDir, manifest) {
-  return installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest, 'claude');
+  return installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest);
 }
 
-function installGeneratedPrompts(skillsSrcDir, targetDir, backupDir, manifest) {
-  return installGeneratedArtifacts(skillsSrcDir, targetDir, backupDir, manifest, 'codex');
+function installGeneratedGeminiCommands(skillsSrcDir, targetDir, backupDir, manifest) {
+  const skills = collectInvocableSkills(skillsSrcDir);
+  if (skills.length === 0) return 0;
+
+  const installDir = path.join(targetDir, GEMINI_COMMAND_TARGET.dir);
+  fs.mkdirSync(installDir, { recursive: true });
+  let totalFiles = 0;
+
+  skills.forEach((skill) => {
+    const names = [skill.name, ...(skill.aliases || [])];
+    names.forEach((cmdName) => {
+      const fileName = `${cmdName}.toml`;
+      const destFile = path.join(installDir, fileName);
+      const relFile = path.posix.join(GEMINI_COMMAND_TARGET.dir, fileName);
+
+      if (fs.existsSync(destFile)) {
+        const backupSubdir = path.join(backupDir, 'gemini', GEMINI_COMMAND_TARGET.dir);
+        fs.mkdirSync(backupSubdir, { recursive: true });
+        fs.copyFileSync(destFile, path.join(backupSubdir, fileName));
+        pushManifestEntry(manifest.backups, 'gemini', relFile);
+        info(`备份: ${c.d(relFile)}`);
+      }
+
+      const content = generateGeminiCommandContent(skill, skill.relPath, skill.runtimeType);
+      fs.writeFileSync(destFile, content);
+      pushManifestEntry(manifest.installed, 'gemini', relFile);
+      totalFiles++;
+    });
+  });
+
+  ok(`${GEMINI_COMMAND_TARGET.dir}/ ${c.d(`(自动生成 ${totalFiles} 个 ${GEMINI_COMMAND_TARGET.label})`)}`);
+  return totalFiles;
+}
+
+function installGeminiContext(targetDir, backupDir, manifest, selectedStyle) {
+  const relPath = 'GEMINI.md';
+  backupManagedPathIfExists('gemini', 'gemini', backupDir, relPath, manifest);
+  const destPath = path.join(targetDir, relPath);
+  const content = renderGeminiContext(PKG_ROOT, selectedStyle.slug);
+  fs.writeFileSync(destPath, content);
+  pushManifestEntry(manifest.installed, 'gemini', relPath);
+  ok(`${relPath} ${c.d(`(动态生成: ${selectedStyle.slug})`)}`);
 }
 
-function backupPathIfExists(targetDir, backupDir, relPath, manifest) {
-  const targetPath = path.join(targetDir, relPath);
+
+function backupManagedPathIfExists(tgt, rootName, backupDir, relPath, manifest) {
+  const targetRoot = resolveManagedRootDir(tgt, rootName);
+  const targetPath = path.join(targetRoot, relPath);
   if (!fs.existsSync(targetPath)) return false;
 
-  const backupPath = path.join(backupDir, relPath);
+  const backupPath = path.join(backupDir, rootName, relPath);
   rmSafe(backupPath);
   copyRecursive(targetPath, backupPath);
-  manifest.backups.push(relPath);
-  info(`备份: ${c.d(relPath)}`);
+  pushManifestEntry(manifest.backups, rootName, relPath);
+  info(`备份: ${c.d(rootName === tgt ? relPath : `${rootName}/${relPath}`)}`);
   return true;
 }
 
-function pruneLegacyCodexSettings(targetDir, backupDir, manifest) {
+function pruneLegacyCodexSettings(tgt, backupDir, manifest) {
   const relPath = 'settings.json';
-  const settingsPath = path.join(targetDir, relPath);
+  const settingsPath = path.join(resolveManagedRootDir(tgt, 'codex'), relPath);
   if (!fs.existsSync(settingsPath)) return null;
 
-  backupPathIfExists(targetDir, backupDir, relPath, manifest);
+  backupManagedPathIfExists(tgt, 'codex', backupDir, relPath, manifest);
   rmSafe(settingsPath);
   warn('移除 legacy settings.json（Codex 已改用 config.toml）');
   return settingsPath;
@@ -374,7 +511,56 @@ function printStyleCatalog() {
   console.log('');
 }
 
+async function resolveProjectPackPlan(targetName) {
+  const projectPacks = resolveProjectPacks(process.cwd(), targetName);
+  if (!projectPacks.path) {
+    return {
+      ...projectPacks,
+      selected: [],
+      optionalSelected: [],
+      sources: {},
+    };
+  }
+
+  let confirmOptional = null;
+  if (projectPacks.optionalPolicy === 'prompt' && projectPacks.optional.length > 0 && !autoYes) {
+    const { confirm } = await import('@inquirer/prompts');
+    confirmOptional = async (optionalPacks) => confirm({
+      message: `当前仓库声明了 optional packs: ${optionalPacks.join(', ')}，是否一并安装?`,
+      default: true,
+    });
+  }
+
+  const selection = await selectProjectPacksForInstall(projectPacks, {
+    autoYes,
+    confirm: confirmOptional,
+  });
+
+  return {
+    ...projectPacks,
+    ...selection,
+  };
+}
+
 async function resolveInstallStyle(targetName) {
+  if (targetName === 'codex') {
+    if (requestedStyleSlug) {
+      warn('Codex 已改为 skills-only，忽略 --style（不再生成 ~/.codex/AGENTS.md）');
+    }
+    return getDefaultStyle(PKG_ROOT, 'claude');
+  }
+
+  if (targetName === 'gemini') {
+    if (requestedStyleSlug) {
+      const requested = resolveStyle(PKG_ROOT, requestedStyleSlug, 'gemini') || resolveStyle(PKG_ROOT, requestedStyleSlug, 'claude');
+      if (!requested) {
+        throw new Error(`未知输出风格: ${requestedStyleSlug}`);
+      }
+      return requested;
+    }
+    return getDefaultStyle(PKG_ROOT, 'claude');
+  }
+
   if (requestedStyleSlug) {
     const style = resolveStyle(PKG_ROOT, requestedStyleSlug, targetName);
     if (!style) {
@@ -401,36 +587,36 @@ async function resolveInstallStyle(targetName) {
   return resolveStyle(PKG_ROOT, slug, targetName);
 }
 
-function installCodexAgents(targetDir, backupDir, manifest, selectedStyle) {
-  const relPath = 'AGENTS.md';
-  backupPathIfExists(targetDir, backupDir, relPath, manifest);
-  const destPath = path.join(targetDir, relPath);
-  const content = renderCodexAgents(PKG_ROOT, selectedStyle.slug);
-  fs.writeFileSync(destPath, content);
-  manifest.installed.push(relPath);
-  ok(`${relPath} ${c.d(`(动态生成: ${selectedStyle.slug})`)}`);
-}
-
-function installCore(tgt, selectedStyle) {
-  const targetDir = path.join(HOME, `.${tgt}`);
+function installCore(tgt, selectedStyle, packPlan) {
+  const targetDir = resolveManagedRootDir(tgt);
   const backupDir = path.join(targetDir, '.sage-backup');
   const manifestPath = path.join(backupDir, 'manifest.json');
 
-  step(1, 3, `安装核心文件 → ${c.cyn(targetDir)}`);
+  const installSummary = tgt === 'codex'
+    ? `${c.cyn(resolveManagedRootDir(tgt, 'codex'))} + ${c.cyn(resolveManagedRootDir(tgt, 'agents'))}`
+    : c.cyn(targetDir);
+  step(1, 3, `安装核心文件 → ${installSummary}`);
   fs.mkdirSync(backupDir, { recursive: true });
 
   const filesToInstall = tgt === 'codex'
     ? getCodexCoreFiles()
-    : getClaudeCoreFiles();
+    : tgt === 'gemini'
+      ? getGeminiCoreFiles()
+      : getClaudeCoreFiles();
 
   const manifest = {
-    manifest_version: 1, version: VERSION, target: tgt,
-    timestamp: new Date().toISOString(), style: selectedStyle.slug, installed: [], backups: []
+    manifest_version: 2, version: VERSION, target: tgt,
+    timestamp: new Date().toISOString(), style: selectedStyle.slug, installed: [], backups: [],
+    project_packs: packPlan.selected,
+    optional_policy: packPlan.optionalPolicy || 'auto',
+    pack_reports: [],
   };
 
-  filesToInstall.forEach(({ src, dest }) => {
+  filesToInstall.forEach(({ src, dest, root }) => {
+    const rootName = root || tgt;
     const srcPath = path.join(PKG_ROOT, src);
-    const destPath = path.join(targetDir, dest);
+    const destRoot = resolveManagedRootDir(tgt, rootName);
+    const destPath = path.join(destRoot, dest);
     if (!fs.existsSync(srcPath)) {
       if (src === 'skills') {
         fail(`核心文件缺失: ${srcPath}\n    请尝试: npm cache clean --force && npx code-abyss`);
@@ -440,22 +626,125 @@ function installCore(tgt, selectedStyle) {
     }
 
     if (fs.existsSync(destPath)) {
-      const bp = path.join(backupDir, dest);
-      rmSafe(bp); copyRecursive(destPath, bp); manifest.backups.push(dest);
-      info(`备份: ${c.d(dest)}`);
+      const backupPath = path.join(backupDir, rootName, dest);
+      rmSafe(backupPath);
+      copyRecursive(destPath, backupPath);
+      pushManifestEntry(manifest.backups, rootName, dest);
+      info(`备份: ${c.d(rootName === tgt ? dest : `${rootName}/${dest}`)}`);
     }
-    ok(dest);
-    rmSafe(destPath); copyRecursive(srcPath, destPath); manifest.installed.push(dest);
+    ok(rootName === tgt ? dest : `${rootName}/${dest}`);
+    rmSafe(destPath);
+    copyRecursive(srcPath, destPath);
+    pushManifestEntry(manifest.installed, rootName, dest);
+  });
+
+  pushPackReport(manifest, {
+    pack: 'abyss',
+    host: tgt,
+    status: 'installed',
+    source: 'bundled',
   });
 
   // 为目标 CLI 自动生成 user-invocable artifacts
   if (tgt === 'claude') {
     const skillsSrc = path.join(PKG_ROOT, 'skills');
     installGeneratedCommands(skillsSrc, targetDir, backupDir, manifest);
+    if (packPlan.selected.includes('gstack')) {
+      const sourceMode = (packPlan.sources && packPlan.sources.gstack) || 'pinned';
+      const result = installGstackClaudePack({
+        HOME,
+        backupDir,
+        manifest,
+        info,
+        ok,
+        warn,
+        sourceMode,
+        projectRoot: packPlan.root,
+        fallback: true,
+      });
+      pushPackReport(manifest, {
+        pack: 'gstack',
+        host: 'claude',
+        status: result.installed ? 'installed' : 'skipped',
+        source: resolveEffectivePackSource(sourceMode, result),
+        reason: result.reason || null,
+      });
+    } else if (packPlan.required.includes('gstack') || packPlan.optional.includes('gstack')) {
+      const sourceMode = (packPlan.sources && packPlan.sources.gstack) || 'pinned';
+      pushPackReport(manifest, {
+        pack: 'gstack',
+        host: 'claude',
+        status: sourceMode === 'disabled' ? 'disabled' : 'skipped',
+        source: sourceMode,
+        reason: sourceMode === 'disabled' ? 'source-disabled' : `optional-policy-${packPlan.optionalPolicy || 'auto'}`,
+      });
+    }
   } else if (tgt === 'codex') {
-    // Codex 0.117.0+ 已移除 custom prompts，skills 通过 agents/openai.yaml 注册
-    // 不再生成 prompts/ 目录
-    installCodexAgents(targetDir, backupDir, manifest, selectedStyle);
+    // Codex 走 skills-only：不再生成 ~/.codex/AGENTS.md，项目声明的 pack 自动装入 ~/.agents/skills/
+    if (packPlan.selected.includes('gstack')) {
+      const sourceMode = (packPlan.sources && packPlan.sources.gstack) || 'pinned';
+      const result = installGstackCodexPack({
+        HOME,
+        backupDir,
+        manifest,
+        info,
+        ok,
+        warn,
+        sourceMode,
+        projectRoot: packPlan.root,
+        fallback: true,
+      });
+      pushPackReport(manifest, {
+        pack: 'gstack',
+        host: 'codex',
+        status: result.installed ? 'installed' : 'skipped',
+        source: resolveEffectivePackSource(sourceMode, result),
+        reason: result.reason || null,
+      });
+    } else if (packPlan.required.includes('gstack') || packPlan.optional.includes('gstack')) {
+      const sourceMode = (packPlan.sources && packPlan.sources.gstack) || 'pinned';
+      pushPackReport(manifest, {
+        pack: 'gstack',
+        host: 'codex',
+        status: sourceMode === 'disabled' ? 'disabled' : 'skipped',
+        source: sourceMode,
+        reason: sourceMode === 'disabled' ? 'source-disabled' : `optional-policy-${packPlan.optionalPolicy || 'auto'}`,
+      });
+    }
+  } else if (tgt === 'gemini') {
+    const skillsSrc = path.join(PKG_ROOT, 'skills');
+    installGeneratedGeminiCommands(skillsSrc, targetDir, backupDir, manifest);
+    installGeminiContext(targetDir, backupDir, manifest, selectedStyle);
+    if (packPlan.selected.includes('gstack')) {
+      const sourceMode = (packPlan.sources && packPlan.sources.gstack) || 'pinned';
+      const result = installGstackGeminiPack({
+        HOME,
+        backupDir,
+        manifest,
+        info,
+        ok,
+        warn,
+        sourceMode,
+        projectRoot: packPlan.root,
+        fallback: true,
+      });
+      pushPackReport(manifest, {
+        pack: 'gstack',
+        host: 'gemini',
+        status: result.installed ? 'installed' : 'skipped',
+        source: resolveEffectivePackSource(sourceMode, result),
+        reason: result.reason || null,
+      });
+    } else if (packPlan.required.includes('gstack') || packPlan.optional.includes('gstack')) {
+      const sourceMode = (packPlan.sources && packPlan.sources.gstack) || 'pinned';
+      pushPackReport(manifest, {
+        pack: 'gstack',
+        host: 'gemini',
+        status: sourceMode === 'disabled' ? 'disabled' : 'skipped',
+        source: sourceMode,
+        reason: sourceMode === 'disabled' ? 'source-disabled' : `optional-policy-${packPlan.optionalPolicy || 'auto'}`,
+      });
+    }
   }
 
   let settingsPath = null;
@@ -469,15 +758,31 @@ function installCore(tgt, selectedStyle) {
         warn('settings.json 解析失败，将使用空配置');
         settings = {};
       }
-      fs.copyFileSync(settingsPath, path.join(backupDir, 'settings.json'));
-      manifest.backups.push('settings.json');
+      fs.mkdirSync(path.join(backupDir, 'claude'), { recursive: true });
+      fs.copyFileSync(settingsPath, path.join(backupDir, 'claude', 'settings.json'));
+      pushManifestEntry(manifest.backups, 'claude', 'settings.json');
     }
     settings.outputStyle = selectedStyle.slug;
     ok(`outputStyle = ${c.mag(selectedStyle.slug)}`);
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    manifest.installed.push('settings.json');
+    pushManifestEntry(manifest.installed, 'claude', 'settings.json');
+  } else if (tgt === 'gemini') {
+    settingsPath = path.join(targetDir, 'settings.json');
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      } catch (e) {
+        warn('Gemini settings.json 解析失败，将使用空配置');
+        settings = {};
+      }
+      fs.mkdirSync(path.join(backupDir, 'gemini'), { recursive: true });
+      fs.copyFileSync(settingsPath, path.join(backupDir, 'gemini', 'settings.json'));
+      pushManifestEntry(manifest.backups, 'gemini', 'settings.json');
+    }
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    pushManifestEntry(manifest.installed, 'gemini', 'settings.json');
   } else {
-    pruneLegacyCodexSettings(targetDir, backupDir, manifest);
+    pruneLegacyCodexSettings(tgt, backupDir, manifest);
   }
 
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
@@ -486,7 +791,7 @@ function installCore(tgt, selectedStyle) {
   const uDest = path.join(targetDir, '.sage-uninstall.js');
   if (fs.existsSync(uSrc)) { fs.copyFileSync(uSrc, uDest); fs.chmodSync(uDest, '755'); }
 
-  return { targetDir, settingsPath, settings, manifest, manifestPath };
+  return { targetDir, settingsPath, settings, manifest, manifestPath, packPlan };
 }
 
 // ── Claude 后续 ──
@@ -523,6 +828,21 @@ async function postCodex() {
   });
 }
 
+async function postGemini(ctx) {
+  await postGeminiFlow({
+    settingsPath: ctx.settingsPath,
+    settings: ctx.settings,
+    autoYes,
+    HOME,
+    PKG_ROOT,
+    step,
+    ok,
+    warn,
+    info,
+    c,
+  });
+}
+
 // ── 主流程 ──
 
 async function main() {
@@ -536,12 +856,20 @@ async function main() {
   banner();
 
   if (target) {
-    if (!['claude', 'codex'].includes(target)) { fail('--target 必须是 claude 或 codex'); process.exit(1); }
+    if (!isSupportedTarget(target)) {
+      fail(formatActionableError(`--target 必须是 ${listTargetNames().join('、')}`, 'Try: node bin/install.js --target claude'));
+      process.exit(1);
+    }
     const style = await resolveInstallStyle(target);
+    const packPlan = await resolveProjectPackPlan(target);
     info(`输出风格: ${c.mag(style.slug)} (${style.label})`);
-    const ctx = installCore(target, style);
+    if (packPlan.path) {
+      info(`项目 packs: required=[${packPlan.required.join(', ')}] optional=[${packPlan.optional.join(', ')}] policy=${packPlan.optionalPolicy}`);
+    }
+    const ctx = installCore(target, style, packPlan);
     if (target === 'claude') await postClaude(ctx);
-    else await postCodex();
+    else if (target === 'codex') await postCodex();
+    else await postGemini(ctx);
     finish(ctx);
     return;
   }
@@ -549,43 +877,106 @@ async function main() {
   const { select } = await import('@inquirer/prompts');
   const action = await select({
     message: '请选择操作',
-    choices: [
-      { name: `安装到 Claude Code ${c.d('(~/.claude/')}${c.d(')')}`, value: 'install-claude' },
-      { name: `安装到 Codex CLI   ${c.d('(~/.codex/')}${c.d(')')}`, value: 'install-codex' },
-      { name: `${c.red('卸载')} Claude Code`, value: 'uninstall-claude' },
-      { name: `${c.red('卸载')} Codex CLI`, value: 'uninstall-codex' },
-    ],
+    choices: listInstallTargets().flatMap((targetMeta) => {
+      const targetDir = resolveManagedRootDir(targetMeta.name);
+      return [
+        { name: `安装到 ${targetMeta.actionLabel} ${c.d(`(${targetDir})`)}`, value: `install-${targetMeta.name}` },
+        { name: `${c.red('卸载')} ${targetMeta.actionLabel}`, value: `uninstall-${targetMeta.name}` },
+      ];
+    }),
   });
 
   switch (action) {
     case 'install-claude': {
       const style = await resolveInstallStyle('claude');
+      const packPlan = await resolveProjectPackPlan('claude');
       info(`输出风格: ${c.mag(style.slug)} (${style.label})`);
-      const ctx = installCore('claude', style);
+      if (packPlan.path) {
+        info(`项目 packs: required=[${packPlan.required.join(', ')}] optional=[${packPlan.optional.join(', ')}] policy=${packPlan.optionalPolicy}`);
+      }
+      const ctx = installCore('claude', style, packPlan);
       await postClaude(ctx);
       finish(ctx); break;
     }
     case 'install-codex': {
       const style = await resolveInstallStyle('codex');
+      const packPlan = await resolveProjectPackPlan('codex');
       info(`输出风格: ${c.mag(style.slug)} (${style.label})`);
-      const ctx = installCore('codex', style);
+      if (packPlan.path) {
+        info(`项目 packs: required=[${packPlan.required.join(', ')}] optional=[${packPlan.optional.join(', ')}] policy=${packPlan.optionalPolicy}`);
+      }
+      const ctx = installCore('codex', style, packPlan);
       await postCodex();
       finish(ctx); break;
     }
+    case 'install-gemini': {
+      const style = await resolveInstallStyle('gemini');
+      const packPlan = await resolveProjectPackPlan('gemini');
+      info(`输出风格: ${c.mag(style.slug)} (${style.label})`);
+      const ctx = installCore('gemini', style, packPlan);
+      await postGemini(ctx);
+      finish(ctx); break;
+    }
     case 'uninstall-claude': runUninstall('claude'); break;
     case 'uninstall-codex': runUninstall('codex'); break;
+    case 'uninstall-gemini': runUninstall('gemini'); break;
   }
 }
 
 function finish(ctx) {
   const tgt = ctx.manifest.target;
+  let reportPath = null;
+  if (ctx.packPlan && ctx.packPlan.root) {
+    reportPath = writeReportArtifact(ctx.packPlan.root, `install-${tgt}`, {
+      version: VERSION,
+      target: tgt,
+      timestamp: new Date().toISOString(),
+      cwd: process.cwd(),
+      pack_plan: {
+        required: ctx.packPlan.required,
+        optional: ctx.packPlan.optional,
+        selected: ctx.packPlan.selected,
+        optional_policy: ctx.packPlan.optionalPolicy,
+        sources: ctx.packPlan.sources,
+      },
+      pack_reports: ctx.manifest.pack_reports || [],
+      installed: ctx.manifest.installed || [],
+      backups: ctx.manifest.backups || [],
+    });
+  }
   divider('安装完成');
   console.log('');
   console.log(`  ${c.b('目标:')}     ${c.cyn(ctx.targetDir)}`);
   console.log(`  ${c.b('版本:')}     v${VERSION}`);
-  if (ctx.manifest.style) {
+  if (ctx.manifest.style && tgt !== 'codex') {
     console.log(`  ${c.b('风格:')}     ${c.mag(ctx.manifest.style)}`);
   }
+  if (Array.isArray(ctx.manifest.project_packs) && ctx.manifest.project_packs.length > 0) {
+    console.log(`  ${c.b('Packs:')}    ${ctx.manifest.project_packs.join(', ')}`);
+  }
+  if (ctx.manifest.optional_policy) {
+    console.log(`  ${c.b('Pack策略:')} ${ctx.manifest.optional_policy}`);
+  }
+  if (Array.isArray(ctx.manifest.pack_reports) && ctx.manifest.pack_reports.length > 0) {
+    ctx.manifest.pack_reports.forEach((report) => {
+      const source = report.source ? ` source=${report.source}` : '';
+      const reason = report.reason ? ` reason=${report.reason}` : '';
+      console.log(`  ${c.b('Pack报告:')} ${report.pack}@${report.host} ${report.status}${source}${reason}`);
+    });
+  }
+  if (ctx.packPlan && ctx.packPlan.root) {
+    const projectLock = readProjectPackLock(ctx.packPlan.root);
+    if (projectLock) {
+      const bootstrap = syncProjectBootstrapArtifacts(ctx.packPlan.root, projectLock.lock);
+      const updatedDocs = bootstrap.docs.filter((entry) => entry.action !== 'skipped');
+      if (updatedDocs.length > 0) {
+        updatedDocs.forEach((entry) => console.log(`  ${c.b('文档同步:')} ${entry.action} ${entry.filePath}`));
+      }
+    }
+  }
+  if (reportPath) {
+    console.log(`  ${c.b('Report:')}   ${reportPath}`);
+  }
   console.log(`  ${c.b('文件:')}     ${ctx.manifest.installed.length} 个安装, ${ctx.manifest.backups.length} 个备份`);
   console.log(`  ${c.b('卸载:')}     ${c.d(`npx code-abyss --uninstall ${tgt}`)}`);
   console.log('');
@@ -601,7 +992,7 @@ module.exports = {
   detectCclineBin, copyRecursive, shouldSkip, SETTINGS_TEMPLATE,
   scanInvocableSkills,
   generateCommandContent,
-  generatePromptContent,
+  generateGeminiCommandContent,
   installGeneratedCommands,
-  installGeneratedPrompts,
+  installGeneratedGeminiCommands,
 };