@2api-store/activate 0.2.0 → 0.3.0

package/activate.mjs

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 /**
- * @2api-store/activate — TokenShop CLI 一键激活
+ * @2api-store/activate — TokenShop CLI 一键激活（v0.3.0）
  *
- * 主流程（spec §5.2）：
- *   1. 检测环境（OS / node / 已装 CLI）
- *   2. 输入凭据（sk- 前缀 → API Key；否则兑换码）
- *   3. 兑换码模式 → 补输入 email
- *   4. POST /api/v1/cli/activate → 拿配置包
- *   5. 按 os_type 过滤配置，展示可用 CLI 让用户多选
- *   6. 展示可用模型让用户选 defaultModel
- *   7. 备份 → 渲染（注入 apiKey/baseUrl/defaultModel）→ 写入（两阶段权限）
- *   8. 验证：GET /v1/models（Bearer api_key）确认 200
- *   9. 报告：激活清单 / 备份位置 / （新用户）查收邮件
+ * 主流程（薄编排，逻辑在各 lib 模块）：
+ *   1. banner + 检测环境 + 列已装/未装 CLI
+ *   2. 输入凭据（sk- → API Key；否则兑换码 + email）
+ *   3. POST /api/v1/cli/activate → 配置包
+ *   4. 多选 CLI（主 CLI 默认选；opencode 默认不选；未装的标 ✗）
+ *   5. 未装 CLI → ensureInstalled（询问确认 → npm i -g）
+ *   6. 选默认模型
+ *   7. 备份 → 渲染 → 写入（每个文件彩色 ok/fail）
+ *   8. 验证 API Key（GET /v1/models）
+ *   9. 报告 + 打印启动/使用指南（每个激活 CLI 的 startCmd + usage）
  */
 
 import { detectAll } from './lib/detect.mjs'
@@ -27,18 +27,16 @@ import {
   confirm,
   closePrompt,
 } from './lib/prompt.mjs'
+import { banner, ok, fail, warn, info, step, guide, plain } from './lib/ui.mjs'
+import { getCliMeta, isDefaultSelected } from './lib/platforms.mjs'
+import { ensureInstalled } from './lib/install.mjs'
 
-const VERSION = '0.1.0'
+const VERSION = '0.3.0'
 const DEFAULT_API_BASE = 'https://2api.store'
 
-const BANNER = String.raw`
-  _   _   _   _   ____    _    ____    _   _
- | | | | | | | | / ___|  / \  | __ )  | \ | |
- | |_| | | | | || |  _  / _ \ |  _ \  |  \| |
- |  _  | | |_| || |_| |/ ___ \| |_) | | |\  |
- |_| |_|  \___/ \____/_/   \_\____/  |_| \_|
-        TokenShop CLI 一键激活  v${VERSION}
-`
+// ============================================================
+// 参数解析 / 帮助 / 凭据分流
+// ============================================================
 
 function parseArgs(argv) {
   const args = { dryRun: false, platform: null, _: [] }
@@ -74,7 +72,7 @@ function printHelp() {
   npx @2api-store/activate [options]
 
 选项:
-  --dry-run, -n          不真写配置，只展示将写入什么
+  --dry-run, -n          不真写配置/不真装 CLI，只展示将做什么
   --platform <name>      只激活指定平台（openai/anthropic/gemini/grok/antigravity）
   --api-base <url>       覆盖 API 端点（默认 $ACTIVATE_API_BASE 或 ${DEFAULT_API_BASE}）
   -h, --help             显示帮助
@@ -98,18 +96,34 @@ function printHelp() {
 }
 
 /**
- * 凭据格式分流（spec §5.3）
- *   sk- 前缀 → key
- *   32 字符 [a-zA-Z0-9] → redeem
+ * 凭据格式分流：sk- → key；16-64 字符 [a-zA-Z0-9] → redeem
  */
 function classifyCredential(cred) {
   if (!cred) return 'empty'
   if (cred.startsWith('sk-')) return 'key'
-  // 兑换码：16-64 字符 [a-zA-Z0-9]
   if (/^[a-zA-Z0-9]{16,64}$/.test(cred)) return 'redeem'
   return 'unknown'
 }
 
+/**
+ * 从模型 ID 列表推断平台集合（脚本兜底，与端点 inferPlatforms 对应）
+ */
+function inferModelPlatforms(models) {
+  const set = new Set()
+  for (const m of models || []) {
+    const id = (typeof m === 'string' ? m : m?.id || '').toLowerCase()
+    if (/^(gpt|o1|o3|codex|glm|minimax|deepseek)/.test(id)) set.add('openai')
+    else if (id.startsWith('claude')) set.add('anthropic')
+    else if (id.startsWith('gemini')) set.add('gemini')
+    else if (id.startsWith('grok')) set.add('grok')
+  }
+  return [...set]
+}
+
+// ============================================================
+// 主流程
+// ============================================================
+
 async function main() {
   const args = parseArgs(process.argv.slice(2))
   if (args.help) {
@@ -121,9 +135,8 @@ async function main() {
     return 0
   }
 
-  console.log(BANNER)
-
-  // === 1. 检测环境 ===
+  // === 1. banner + 环境检测 ===
+  banner()
   const env = detectAll()
   const osLabel = env.os.isMac
     ? 'macOS'
@@ -132,70 +145,79 @@ async function main() {
       : env.os.isWindows
         ? 'Windows'
         : env.os.platform
-  console.log(`环境：${osLabel} · node v${env.node.version}`)
+  info(`环境：${osLabel} · node v${env.node.version}`)
   if (!env.node.supported) {
-    console.error(`✗ 需要 node >= 18，当前 ${env.node.version}`)
+    fail(`需要 node >= 18，当前 ${env.node.version}`)
     return 1
   }
+
+  // 列出已装/未装 CLI（彩色）
   const installedNames = Object.keys(env.installed)
+  const installedList = installedNames.map((n) => {
+    const v = env.installed[n]?.version
+    return v ? `${n}@${v}` : n
+  })
   if (installedNames.length > 0) {
-    console.log(`已检测到 CLI：${installedNames.join(', ')}`)
+    ok(`已检测到 CLI：${installedList.join(', ')}`)
   } else {
-    console.log('未检测到 codex/claude/gemini/grok/opencode（不影响激活，仅参考）')
+    info('未检测到 codex/claude/gemini/grok/opencode（可在后续步骤按需自动安装）')
   }
 
   const apiBase = args.apiBase || process.env.ACTIVATE_API_BASE || DEFAULT_API_BASE
-  console.log(`API 端点：${apiBase}`)
-  if (args.dryRun) console.log('【试运行模式 --dry-run】不会真写任何文件')
-  if (args.platform) console.log(`平台过滤：${args.platform}`)
+  info(`API 端点：${apiBase}`)
+  if (args.dryRun) warn('【试运行模式 --dry-run】不会真写文件、不会真装 CLI')
+  if (args.platform) info(`平台过滤：${args.platform}`)
   console.log()
 
   // === 2. 输入凭据 ===
   const credential = (await askSecret('请输入 API Key（sk-...）或兑换码')).trim()
   if (!credential) {
-    console.error('✗ 未输入凭据')
+    fail('未输入凭据')
     return 1
   }
   const kind = classifyCredential(credential)
   if (kind === 'unknown') {
-    console.error('✗ 凭据格式无法识别（应为 sk- 前缀的 API Key 或兑换码）')
+    fail('凭据格式无法识别（应为 sk- 前缀的 API Key 或兑换码）')
     return 1
   }
-  console.log(`识别为：${kind === 'key' ? 'API Key' : '兑换码'}模式`)
+  info(`识别为：${kind === 'key' ? 'API Key' : '兑换码'}模式`)
 
   // === 3. 兑换码 → 邮箱 ===
   let email = ''
   if (kind === 'redeem') {
-    email = (await ask('请输入邮箱（用于兑换码绑定 / 新账号创建')).trim()
+    email = (await ask('请输入邮箱（用于兑换码绑定 / 新账号创建）')).trim()
     if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
-      console.error('✗ 邮箱格式不正确')
+      fail('邮箱格式不正确')
       return 1
     }
   }
 
   // === 4. POST /cli/activate ===
-  console.log()
-  console.log('正在请求激活服务…')
+  step('请求激活服务')
   let bundle
   try {
     bundle = await cliActivate({ credential, email, platform: args.platform, apiBase })
   } catch (err) {
-    console.error(`✗ 激活失败：${err.message}`)
-    if (err.statusCode) console.error(`  HTTP ${err.statusCode}`)
+    fail(`激活失败：${err.message}`)
+    if (err.statusCode) fail(`  HTTP ${err.statusCode}`)
     return 1
   }
 
-  console.log(`✓ 模式：${bundle.mode}${bundle.user?.is_new ? '（新用户已创建）' : ''}`)
+  ok(`模式：${bundle.mode}${bundle.user?.is_new ? '（新用户已创建）' : ''}`)
   if (bundle.user?.is_new && bundle.user?.email) {
-    console.log(`  新账号：${bundle.user.email}`)
-    if (bundle.user.message) console.log(`  ${bundle.user.message}`)
+    info(`新账号：${bundle.user.email}`)
+    if (bundle.user.message) info(bundle.user.message)
   }
   console.log()
 
-  // === 5. 按 os_type 过滤、展示可用 CLI ===
-  let osConfigs = (bundle.configs || []).filter((c) => {
+  // === 5. 过滤配置（os_type + 平台） + 多选 CLI（主 CLI 默认选，opencode 默认不选）===
+  const allowedPlatforms = inferModelPlatforms(bundle.models || [])
+  if (args.platform && !allowedPlatforms.includes(args.platform)) {
+    allowedPlatforms.push(args.platform)
+  }
+  const osConfigs = (bundle.configs || []).filter((c) => {
     if (!c) return false
-    // 客户端 --platform 二次过滤（防御性，后端已过滤）
+    if (allowedPlatforms.length > 0 && !allowedPlatforms.includes(c.platform)) return false
     if (args.platform && c.platform !== args.platform) return false
     if (env.os.isWindows) {
       return c.os_type === 'windows' || c.os_type === 'all'
@@ -204,93 +226,140 @@ async function main() {
   })
 
   if (osConfigs.length === 0) {
-    console.error('✗ 服务端未返回适配当前系统的配置模板')
+    fail('服务端未返回适配当前系统的配置模板')
     return 1
   }
 
-  // dedupe by platform + client_type
+  // dedupe by platform + client_type，构建多选项
   const seen = new Set()
   const cliItems = []
   for (const c of osConfigs) {
     const key = `${c.platform}/${c.client_type}`
     if (seen.has(key)) continue
     seen.add(key)
-    const displayName = c.display_name || c.displayName || `${c.platform} ${c.client_type}`
+    const meta = getCliMeta(c.client_type)
+    const displayName = c.display_name || c.displayName || meta?.name || `${c.platform} ${c.client_type}`
+    const installed = env.installed[c.client_type]?.path || (meta && env.installed[meta.detectBin]?.path)
+    const installMark = installed ? '✓' : '✗'
+    const primaryMark = isDefaultSelected(c.client_type) ? '' : '（独立 CLI）'
     cliItems.push({
-      label: `${displayName} [${c.platform}/${c.client_type}]`,
+      label: `[${installMark}] ${displayName} [${c.platform}/${c.client_type}]${primaryMark}`,
       config: c,
+      clientType: c.client_type,
+      meta,
+      alreadyInstalled: !!installed,
     })
   }
 
-  console.log('可用 CLI：')
-  const selectedIdxes = await multiSelect('选择要激活的 CLI（默认全选）', cliItems, {
-    defaultSelected: cliItems.map((_, i) => i),
-  })
+  // 默认选中：主 CLI（isPrimary=true）。dry-run 也用此默认（不因 dry-run 改默认）
+  const defaultSelected = cliItems
+    .map((item, i) => ({ item, i }))
+    .filter(({ item }) => isDefaultSelected(item.clientType))
+    .map(({ i }) => i)
+
+  step('选择 CLI')
+  const selectedIdxes = await multiSelect(
+    '选择要激活的 CLI（✓=已装 ✗=未装；默认选主 CLI，独立 CLI 默认不选）',
+    cliItems,
+    { defaultSelected },
+  )
   if (selectedIdxes.length === 0) {
-    console.log('未选择任何 CLI，退出。')
+    plain('未选择任何 CLI，退出。')
     return 0
   }
-  const selectedConfigs = selectedIdxes.map((i) => cliItems[i].config)
+  const selectedItems = selectedIdxes.map((i) => cliItems[i])
   console.log()
 
-  // === 6. 选 defaultModel ===
+  // === 6. 未装 CLI → 询问确认 → npm i -g（dry-run 跳过真装）===
+  if (!args.dryRun) {
+    step('检查 CLI 安装状态')
+    for (const item of selectedItems) {
+      if (item.alreadyInstalled) {
+        const ver = env.installed[item.clientType]?.version || env.installed[item.meta?.detectBin]?.version
+        ok(`${item.meta?.name || item.clientType} 已安装${ver ? `（v${ver}）` : ''}`)
+        continue
+      }
+      if (!item.meta || !item.meta.installPackage) {
+        // 未知 CLI（如 grok 无官方 npm 包）→ 只提示不装
+        warn(`${item.clientType} 无可自动安装的 npm 包，请手动安装后重跑（配置仍会写入）`)
+        continue
+      }
+      info(`未检测到 ${item.meta.name}（命令 ${item.meta.detectBin}）`)
+      const r = await ensureInstalled(item.meta, { dryRun: args.dryRun })
+      if (r.installed) {
+        ok(`${item.meta.name} 安装成功${r.version ? `（v${r.version}）` : ''}`)
+      } else if (r.skipped && r.reason === 'user-declined') {
+        warn(`已跳过 ${item.meta.name} 安装（配置仍会写入，但请手动安装后使用）`)
+      } else if (r.skipped) {
+        info(`已跳过 ${item.meta.name} 安装（${r.reason}）`)
+      } else {
+        fail(`${item.meta.name} 安装失败：${r.error || '未知错误'}（配置仍会写入，但请手动安装后使用）`)
+      }
+    }
+    console.log()
+  }
+
+  // === 7. 选默认模型 ===
   const modelItems = listModels(bundle.models || [])
   let defaultModelId = ''
   if (modelItems.length > 0) {
-    console.log('可用模型：')
+    step('选择默认模型')
     const selectItems = modelItems.map((m) => ({ label: `${m.label} (${m.id})` }))
     const idx = await select('选择默认模型', selectItems, { defaultIndex: 0 })
     defaultModelId = modelItems[idx].id
-    console.log(`已选默认模型：${defaultModelId}`)
+    ok(`已选默认模型：${defaultModelId}`)
   } else {
-    console.warn('⚠ 服务端未返回模型列表，{{defaultModel}} 将留空')
+    warn('服务端未返回模型列表，{{defaultModel}} 将留空')
   }
   console.log()
 
-  // 准备渲染值
+  // 渲染值
   const baseUrl = bundle.base_url || ''
   const baseUrlBeta = bundle.base_url_beta || baseUrl
   const renderValues = {
     apiKey: bundle.api_key || '',
     baseUrl,
-    apiBase: baseUrl, // alias
+    apiBase: baseUrl,
     apiBaseBeta: baseUrlBeta,
     antigravityApiBase: `${baseUrl}/antigravity`,
     antigravityApiBaseBeta: `${baseUrlBeta}/antigravity`,
     defaultModel: defaultModelId,
   }
 
-  // === 7. 每个选中 CLI 的每个 file：备份 → 渲染 → 写入 ===
+  // === 8. 每个选中 CLI 的每个 file：备份 → 渲染 → 写入 ===
+  step('备份并写入配置')
   const report = []
   let firstPermissionError = null
 
-  for (const cfg of selectedConfigs) {
+  for (const item of selectedItems) {
     const displayName =
-      cfg.display_name || cfg.displayName || `${cfg.platform} ${cfg.client_type}`
-    console.log(`── ${displayName} ──`)
-    const files = cfg.files || []
+      item.config.display_name || item.config.displayName || item.meta?.name || item.clientType
+    plain(`── ${displayName} ──`)
+    const files = item.config.files || []
     for (const f of files) {
       const rawPath = f.path || ''
       const isShellOnly = rawPath === 'Terminal' || rawPath === 'PowerShell'
-      const targetPath = isShellOnly ? rawPath : expandPath(rawPath, { isWindows: env.os.isWindows })
+      const targetPath = isShellOnly
+        ? rawPath
+        : expandPath(rawPath, { isWindows: env.os.isWindows })
       const rendered = renderContent(f.content || '', renderValues)
 
       if (isShellOnly) {
-        console.log(`  [shell 命令，请手动执行]`)
-        console.log(rendered.split('\n').map((l) => '    ' + l).join('\n'))
+        plain('  [shell 命令，请手动执行]')
+        plain(rendered.split('\n').map((l) => '    ' + l).join('\n'))
         report.push({ cli: displayName, path: rawPath, action: 'shell-only' })
         continue
       }
 
-      console.log(`  目标：${targetPath}`)
+      plain(`  目标：${targetPath}`)
 
       if (args.dryRun) {
-        console.log(`  [试运行] 不真实写入`)
+        warn('  [试运行] 不真实写入')
         const lines = rendered.split('\n')
         const preview = lines.slice(0, 8).join('\n')
-        console.log('  内容预览：')
-        console.log(preview.split('\n').map((l) => '    ' + l).join('\n'))
-        if (lines.length > 8) console.log(`    ...（共 ${lines.length} 行）`)
+        plain('  内容预览：')
+        plain(preview.split('\n').map((l) => '    ' + l).join('\n'))
+        if (lines.length > 8) plain(`    ...（共 ${lines.length} 行）`)
         report.push({ cli: displayName, path: targetPath, action: 'dry-run' })
         console.log()
         continue
@@ -300,30 +369,25 @@ async function main() {
       let backupPath = null
       try {
         backupPath = backupFile(targetPath)
-        if (backupPath) console.log(`  备份：${backupPath}`)
+        if (backupPath) plain(`  备份：${backupPath}`)
       } catch (err) {
-        console.error(`  ✗ 备份失败：${err.message}（跳过此文件避免无备份覆盖）`)
+        fail(`备份失败：${err.message}（跳过此文件避免无备份覆盖）`)
         report.push({ cli: displayName, path: targetPath, action: 'backup-failed', error: err.message })
         continue
       }
 
-      // 写入（两阶段权限）
+      // 写入
       try {
         writeFileWithPermission(targetPath, rendered, { isWindows: env.os.isWindows })
-        console.log(`  ✓ 已写入`)
+        ok('已写入')
         report.push({ cli: displayName, path: targetPath, action: 'written', backup: backupPath })
       } catch (err) {
         if (err instanceof PermissionDeniedError) {
           if (!firstPermissionError) firstPermissionError = err
-          console.error(`  ✗ ${err.message}`)
-          report.push({
-            cli: displayName,
-            path: targetPath,
-            action: 'permission-denied',
-            error: err.message,
-          })
+          fail(err.message)
+          report.push({ cli: displayName, path: targetPath, action: 'permission-denied', error: err.message })
         } else {
-          console.error(`  ✗ 写入失败：${err.message}`)
+          fail(`写入失败：${err.message}`)
           report.push({ cli: displayName, path: targetPath, action: 'failed', error: err.message })
         }
       }
@@ -333,22 +397,21 @@ async function main() {
 
   closePrompt()
 
-  // === 8. 验证 API Key（非 dry-run） ===
+  // === 9. 验证 API Key ===
   if (!args.dryRun && bundle.api_key && bundle.base_url) {
-    console.log('验证 API Key…')
+    step('验证 API Key')
+    info('请求 GET /v1/models…')
     const v = await verifyApiKey({ apiKey: bundle.api_key, baseUrl: bundle.base_url })
     if (v.ok) {
-      console.log(`✓ API Key 验证通过（GET /v1/models → 200）`)
+      ok('API Key 验证通过（GET /v1/models → 200）')
     } else {
-      console.warn(
-        `⚠ 验证未通过：${v.error || `HTTP ${v.statusCode}`}（配置已写入，请手动检查）`,
-      )
+      warn(`验证未通过：${v.error || `HTTP ${v.statusCode}`}（配置已写入，请手动检查）`)
     }
     console.log()
   }
 
-  // === 9. 报告 ===
-  console.log('══════════ 激活报告 ══════════')
+  // === 10. 报告 ===
+  step('激活报告')
   const written = report.filter((r) => r.action === 'written')
   const failed = report.filter(
     (r) => r.action === 'failed' || r.action === 'permission-denied' || r.action === 'backup-failed',
@@ -357,33 +420,46 @@ async function main() {
   const dryRunItems = report.filter((r) => r.action === 'dry-run')
 
   if (args.dryRun) {
-    console.log(`[试运行] 将写入 ${dryRunItems.length} 个文件（未真实写入）`)
+    plain(`[试运行] 将写入 ${dryRunItems.length} 个文件（未真实写入）`)
   } else {
-    console.log(`已写入 ${written.length} 个文件`)
+    ok(`已写入 ${written.length} 个文件`)
   }
   if (shellOnly.length > 0) {
-    console.log(`需手动执行的 shell 命令：${shellOnly.length} 项（见上方输出）`)
+    info(`需手动执行的 shell 命令：${shellOnly.length} 项（见上方输出）`)
   }
   if (failed.length > 0) {
-    console.warn(`失败 ${failed.length} 项：`)
-    failed.forEach((f) => console.warn(`  - ${f.cli} ${f.path}`))
+    warn(`失败 ${failed.length} 项：`)
+    failed.forEach((f) => warn(`  - ${f.cli} ${f.path}`))
   }
 
   const backups = report.filter((r) => r.backup).map((r) => r.backup)
   if (backups.length > 0) {
-    console.log(`备份位置：`)
-    backups.forEach((b) => console.log(`  - ${b}`))
+    info('备份位置：')
+    backups.forEach((b) => plain(`  - ${b}`))
   }
 
   if (bundle.user?.is_new) {
     console.log()
-    console.log(`📧 新账号 ${bundle.user.email || ''} 已创建，请查收邮件获取初始密码，登录后尽快修改。`)
+    info(`📧 新账号 ${bundle.user.email || ''} 已创建，请查收邮件获取初始密码，登录后尽快修改。`)
+  }
+
+  // === 11. 启动/使用指南（每个激活 CLI）===
+  if (!args.dryRun) {
+    const guideItems = selectedItems
+      .map((item) => item.meta)
+      .filter(Boolean)
+      .map((meta) => ({
+        name: meta.name,
+        startCmd: meta.startCmd,
+        usage: meta.usage,
+      }))
+    guide(guideItems)
   }
 
   if (firstPermissionError) {
     console.log()
-    console.error('部分文件权限不足，请按提示用 sudo / 管理员 PowerShell 重跑：')
-    console.error('  sudo npx -y @2api-store/activate')
+    fail('部分文件权限不足，请按提示用 sudo / 管理员 PowerShell 重跑：')
+    fail('  sudo npx -y @2api-store/activate')
     return 2
   }
 
@@ -396,7 +472,8 @@ main()
     process.exit(code || 0)
   })
   .catch((err) => {
-    console.error('✗ 未捕获错误：', err)
+    fail(`未捕获错误：${err?.message || err}`)
+    if (err?.stack) console.error(err.stack)
     closePrompt()
     process.exit(1)
   })

package/lib/detect.mjs

@@ -27,7 +27,8 @@ export function detectNode() {
 }
 
 /**
- * 已知 CLI 列表（按 spec §5.2 step 1）
+ * 已知 CLI 列表（含 codex-ws 共享 codex 二进制）
+ * grok 仅检测（无官方 npm CLI 包，不参与自动安装）
  */
 const KNOWN_CLIS = ['codex', 'claude', 'gemini', 'grok', 'opencode']
 
@@ -53,21 +54,63 @@ function findBinary(name, isWindows) {
 }
 
 /**
- * 检测已安装的 CLI
+ * 查询二进制版本（--version 输出第一行）
+ * @param {string} bin 二进制名
  * @param {boolean} isWindows
- * @returns {Record<string, string>} name → path
+ * @returns {string|null} 版本字符串（如 "1.2.3"），失败返回 null
+ */
+function getVersion(bin, isWindows) {
+  // --version 是通用约定；codex/claude/gemini/opencode/grok 都支持
+  try {
+    const result = spawnSync(bin, ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+      shell: isWindows, // Windows 可能需要 shell 解析 .cmd
+    })
+    if (result.status === 0 && result.stdout) {
+      const firstLine = result.stdout.trim().split(/\r?\n/)[0]
+      // 提取常见版本格式：可能形如 "codex 0.1.2505162003" / "1.2.3" / "claude 2.1.0"
+      const match = firstLine.match(/(\d+\.\d+(?:\.\d+)?(?:[-.\w]*)?)/)
+      return match ? match[1] : firstLine.slice(0, 40)
+    }
+  } catch {
+    // 二进制存在但 --version 不支持 / 超时 → 不阻塞，返回 null
+  }
+  return null
+}
+
+/**
+ * 检测单个二进制是否已安装（含版本）
+ * @param {string} bin 二进制名
+ * @returns {{installed: boolean, path: string|null, version: string|null}}
+ */
+export function detectInstalled(bin) {
+  const os = detectOS()
+  const path = findBinary(bin, os.isWindows)
+  if (!path) return { installed: false, path: null, version: null }
+  const version = getVersion(bin, os.isWindows)
+  return { installed: true, path, version }
+}
+
+/**
+ * 检测已安装的 CLI（批量）
+ * @param {boolean} isWindows
+ * @returns {Record<string, {path: string, version: string|null}>} name → info
  */
 export function detectInstalledCLIs(isWindows) {
   const installed = {}
   for (const name of KNOWN_CLIS) {
     const path = findBinary(name, isWindows)
-    if (path) installed[name] = path
+    if (path) {
+      installed[name] = { path, version: getVersion(name, isWindows) }
+    }
   }
   return installed
 }
 
 /**
- * 一次性检测全部环境
+ * 一次性检测全部环境（含已装 CLI 的版本）
  */
 export function detectAll() {
   const os = detectOS()

package/lib/install.mjs

@@ -0,0 +1,105 @@
+/**
+ * CLI 自动安装模块
+ *
+ *   installCLI(meta)         执行 npm install -g（stdio inherit 展示 npm 进度）
+ *   ensureInstalled(meta)    检测 + 询问确认 + 按需安装
+ *
+ * 设计：
+ *   - 不自动安装（用户必须确认，避免后台改全局环境）
+ *   - 安装用 spawnSync + stdio inherit（npm 进度直接透传，体验与手动 npm i 一致）
+ *   - dry-run 模式不真装，只打印「将运行 npm install -g <pkg>」
+ *   - 未识别包（无 meta / 无 installPackage）→ 返回 skipped，不阻塞主流程
+ */
+
+import { spawnSync } from 'node:child_process'
+import { detectInstalled } from './detect.mjs'
+import { confirm } from './prompt.mjs'
+
+/**
+ * 执行 npm install -g
+ * @param {{installPackage: string}} meta CLI 元数据
+ * @param {{dryRun?: boolean}} opts
+ * @returns {{ok: boolean, skipped?: boolean, reason?: string, error?: string}}
+ *   - ok=true           安装成功（或 dry-run 跳过）
+ *   - ok=false+error    安装失败（npm exit !=0 / spawn 错误）
+ *   - skipped=true      因 dryRun 跳过实际安装
+ */
+export function installCLI(meta, opts = {}) {
+  if (!meta || !meta.installPackage) {
+    return { ok: false, skipped: true, reason: 'no-install-package' }
+  }
+  const pkg = meta.installPackage
+  const cmd = `npm install -g ${pkg}`
+
+  if (opts.dryRun) {
+    console.log(`  [试运行] 将运行：${cmd}（不真实安装）`)
+    return { ok: true, skipped: true, reason: 'dry-run' }
+  }
+
+  console.log(`  正在执行：${cmd}…`)
+  try {
+    const result = spawnSync('npm', ['install', '-g', pkg], {
+      stdio: 'inherit', // npm 进度/输出直接透传到当前终端
+      shell: process.platform === 'win32', // Windows 需要 shell 解析 npm.cmd
+    })
+    if (result.status === 0) {
+      return { ok: true }
+    }
+    const errText = `npm exit ${result.status}`
+    return { ok: false, error: errText }
+  } catch (err) {
+    return { ok: false, error: err.message }
+  }
+}
+
+/**
+ * 确保 CLI 已安装：检测 → 未装则询问确认 → 安装
+ *
+ * @param {{detectBin?: string, installPackage?: string, name?: string, installCmd?: string}} meta CLI 元数据
+ * @param {{dryRun?: boolean, autoInstall?: boolean}} opts
+ *   - dryRun       不真装
+ *   - autoInstall  true=未装时直接装（不问）；false/缺省=询问确认后才装
+ * @returns {{installed: boolean, skipped?: boolean, reason?: string, version?: string|null, error?: string}}
+ *   - installed=true     已装（或本次成功安装）
+ *   - installed=false    未装且用户拒绝安装/安装失败/未知 meta
+ */
+export async function ensureInstalled(meta, opts = {}) {
+  if (!meta || !meta.installPackage) {
+    return { installed: false, skipped: true, reason: 'no-meta' }
+  }
+  const bin = meta.detectBin || meta.installPackage.split('/').pop()
+  const detectResult = detectInstalled(bin)
+  if (detectResult.installed) {
+    return { installed: true, version: detectResult.version }
+  }
+
+  // 未装：决定是否安装
+  const { dryRun, autoInstall } = opts
+
+  // dry-run：直接走 installCLI 的 dry-run 分支（不问，因为不会真装）
+  if (dryRun) {
+    const r = installCLI(meta, { dryRun: true })
+    return { installed: false, skipped: true, reason: r.reason || 'dry-run' }
+  }
+
+  // 非 dry-run：按 autoInstall 决定是否询问
+  let shouldInstall = autoInstall === true
+  if (!shouldInstall) {
+    shouldInstall = await confirm(
+      `未检测到 ${meta.name || bin}（命令 ${bin}），是否现在安装？\n  运行：${meta.installCmd || `npm install -g ${meta.installPackage}`}`,
+      { defaultValue: true },
+    )
+  }
+
+  if (!shouldInstall) {
+    return { installed: false, skipped: true, reason: 'user-declined' }
+  }
+
+  const r = installCLI(meta, { dryRun: false })
+  if (r.ok) {
+    // 安装后复查（确认二进制可解析）
+    const recheck = detectInstalled(bin)
+    return { installed: recheck.installed, version: recheck.version, justInstalled: true }
+  }
+  return { installed: false, error: r.error }
+}

package/lib/platforms.mjs

@@ -0,0 +1,109 @@
+/**
+ * CLI 元数据（按 client_type 索引）
+ *
+ * 用于：detect（识别已装/未装）、install（按需 npm i -g）、guide（启动/使用指南）。
+ *
+ * 字段约定：
+ *   name           展示名（UI 用）
+ *   installPackage npm 包名（npm i -g <pkg>）
+ *   installCmd     完整安装命令字符串（UI 展示用，含 npm i -g）
+ *   startCmd       启动命令（guide 用）
+ *   detectBin      检测二进制名（which/where 用）
+ *   configFiles    典型配置文件路径（仅展示参考，实际写入路径由服务端 configs 驱动）
+ *   usage          使用提示文案（guide 用）
+ *   isPrimary      true=主 CLI（默认选中）；false=独立 CLI（默认不选，如 opencode）
+ *
+ * npm 包名经 WebSearch 查证（2026-08-08）：
+ *   - @openai/codex           官方包（npm view @openai/codex → 0.147.0）
+ *   - @anthropic-ai/claude-code 官方包（避开 imposter 包 claude-ai）→ 2.1.226
+ *   - @google/gemini-cli      官方包 → 0.54.4
+ *   - opencode-ai             SST 官方包（非 @opencode-ai/cli）→ 1.18.15
+ */
+
+export const CLI_META = {
+  codex: {
+    name: 'Codex CLI',
+    installPackage: '@openai/codex',
+    installCmd: 'npm install -g @openai/codex',
+    startCmd: 'codex',
+    detectBin: 'codex',
+    configFiles: ['~/.codex/config.toml', '~/.codex/auth.json'],
+    usage: [
+      '权限模式（默认每步确认）：',
+      '  codex --full-auto                                  全自动（sandbox 内自动批准，推荐）',
+      '  codex --yolo                                       全跳过（无 sandbox 无 approval，仅信任仓库）',
+      '  codex --sandbox read-only --ask-for-approval never 只读（最安全）',
+      '  codex --help                                       查看所有选项',
+      '项目根放 AGENTS.md 让 Codex 了解你的代码库',
+    ].join('\n'),
+    isPrimary: true,
+  },
+  'codex-ws': {
+    // WebSocket 变体：与 codex 同包同二进制，仅服务端配置不同
+    name: 'Codex CLI (WebSocket)',
+    installPackage: '@openai/codex',
+    installCmd: 'npm install -g @openai/codex',
+    startCmd: 'codex',
+    detectBin: 'codex',
+    configFiles: ['~/.codex/config.toml', '~/.codex/auth.json'],
+    usage: [
+      '权限模式（WebSocket 模式由服务端配置激活，默认每步确认）：',
+      '  codex --full-auto                                  全自动（sandbox 内自动批准，推荐）',
+      '  codex --yolo                                       全跳过（无 sandbox 无 approval，仅信任仓库）',
+      '  codex --sandbox read-only --ask-for-approval never 只读（最安全）',
+      '  codex --help                                       查看所有选项',
+    ].join('\n'),
+    isPrimary: true,
+  },
+  claude: {
+    name: 'Claude Code',
+    installPackage: '@anthropic-ai/claude-code',
+    installCmd: 'npm install -g @anthropic-ai/claude-code',
+    startCmd: 'claude',
+    detectBin: 'claude',
+    configFiles: ['~/.claude/', '~/.claude.json'],
+    usage: '运行 `claude` 开始；`claude --help` 查看选项；在项目根放 CLAUDE.md 让 Claude 了解你的代码库',
+    isPrimary: true,
+  },
+  'gemini-cli': {
+    name: 'Gemini CLI',
+    installPackage: '@google/gemini-cli',
+    installCmd: 'npm install -g @google/gemini-cli',
+    startCmd: 'gemini',
+    detectBin: 'gemini',
+    configFiles: ['~/.gemini/settings.json'],
+    usage: '运行 `gemini` 开始；`gemini --help` 查看选项；在项目根放 GEMINI.md 让 Gemini 了解你的代码库',
+    isPrimary: true,
+  },
+  opencode: {
+    // 独立 CLI（非主 CLI），默认不选
+    name: 'OpenCode',
+    installPackage: 'opencode-ai',
+    installCmd: 'npm install -g opencode-ai',
+    startCmd: 'opencode',
+    detectBin: 'opencode',
+    configFiles: ['~/.config/opencode/opencode.json', 'opencode.json'],
+    usage: '运行 `opencode` 开始；`opencode --help` 查看选项；在项目根放 AGENTS.md 让 OpenCode 了解你的代码库',
+    isPrimary: false,
+  },
+}
+
+/**
+ * 按 client_type 查询元数据，未定义返回 null
+ * @param {string} clientType
+ * @returns {object|null}
+ */
+export function getCliMeta(clientType) {
+  return CLI_META[clientType] || null
+}
+
+/**
+ * 判断 client_type 是否默认应选中（主 CLI 默认选，独立 CLI 默认不选）
+ * @param {string} clientType
+ * @returns {boolean}
+ */
+export function isDefaultSelected(clientType) {
+  const meta = CLI_META[clientType]
+  if (!meta) return true // 未知类型保守全选（向后兼容）
+  return meta.isPrimary
+}

package/lib/ui.mjs

@@ -0,0 +1,91 @@
+/**
+ * 彩色 UI 输出（chalk 驱动）
+ *
+ * 颜色规范：
+ *   banner   粗体青色（品牌色）
+ *   ✓ ok     绿色（成功）
+ *   ✗ fail   红色（错误）
+ *   ⚠ warn   黄色（警告）
+ *   ℹ info   蓝色（信息）
+ *   step     粗体青色（步骤标题）
+ *   guide    绿色（启动/使用指南）
+ *
+ * chalk 在非 TTY（CI/管道/重定向）/ Windows cmd 自动降级为无色，无需手动处理。
+ */
+
+import chalk from 'chalk'
+
+const PKG_VERSION = '0.3.0'
+
+const BANNER = String.raw`
+  _   _   _   _   ____    _    ____    _   _
+ | | | | | | | | / ___|  / \  | __ )  | \ | |
+ | |_| | | | | || |  _  / _ \ |  _ \  |  \| |
+ |  _  | | |_| || |_| |/ ___ \| |_) | | |\  |
+ |_| |_|  \___/ \____/_/   \_\____/  |_| \_|
+        TokenShop CLI 一键激活  v${PKG_VERSION}
+`
+
+/** 彩色 banner */
+export function banner() {
+  // 去除模板字面量首尾换行，保留 ASCII art 结构
+  console.log(chalk.bold.cyan(BANNER.replace(/^\n/, '').trimEnd()))
+}
+
+/** 成功（✓ 绿色） */
+export function ok(msg) {
+  console.log(chalk.green(`✓ ${msg}`))
+}
+
+/** 错误（✗ 红色 → stderr） */
+export function fail(msg) {
+  console.error(chalk.red(`✗ ${msg}`))
+}
+
+/** 警告（⚠ 黄色） */
+export function warn(msg) {
+  console.warn(chalk.yellow(`⚠ ${msg}`))
+}
+
+/** 信息（ℹ 蓝色） */
+export function info(msg) {
+  console.log(chalk.blue(`ℹ ${msg}`))
+}
+
+/**
+ * 步骤标题（粗体青色 + 框线分隔）
+ * @param {string} title
+ */
+export function step(title) {
+  console.log()
+  console.log(chalk.bold.cyan(`■ ${title}`))
+}
+
+/**
+ * CLI 启动/使用指南（彩色框）
+ * 渲染每个已激活 CLI 的 startCmd + usage
+ * @param {Array<{name: string, startCmd: string, usage: string}>} items
+ */
+export function guide(items) {
+  if (!items || items.length === 0) return
+  step('启动 / 使用指南')
+  for (const it of items) {
+    const head = chalk.bold.green(`  ▶ ${it.name}`)
+    const start = chalk.green(`    启动：${it.startCmd}`)
+    const usage = chalk.dim(it.usage || '')
+    console.log(head)
+    console.log(start)
+    if (usage) console.log(usage)
+    console.log()
+  }
+}
+
+/**
+ * 普通纯文本输出（无颜色修饰，用于已经内嵌颜色的字符串或纯文本）
+ */
+export function plain(msg) {
+  console.log(msg)
+}
+
+/** 暴露 chalk 给调用方（复杂场景按需用） */
+export { chalk }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@2api-store/activate",
-  "version": "0.2.0",
-  "description": "TokenShop CLI 一键激活：配置本地 codex/claude/gemini/grok/opencode 指向 2api.store 中转",
+  "version": "0.3.0",
+  "description": "TokenShop CLI 一键激活：配置本地 codex/claude/gemini/grok/opencode 指向 2api.store 中转（彩色输出 + 自动安装 CLI）",
   "type": "module",
   "bin": {
     "activate": "./activate.mjs"
@@ -32,7 +32,8 @@
   ],
   "author": "TokenShop",
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0"
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.4.0"
   },
   "license": "MIT",
   "publishConfig": {