@miphamai/cli 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/skills/mipham/self-audit.mipham-skill.md

@@ -24,58 +24,58 @@ Mipham Code 审计 Mipham Code — 这是 CRSI 递归自我改进的第一个闭
 
 ### 1. 代码质量
 
-| 检查项 | 方法 |
-|--------|------|
-| Dead code | Grep 搜索未被引用的 export、未使用的 import |
-| 不一致模式 | 对比同一目录下多个文件的代码风格/模式差异 |
-| 类型安全 | 搜索 `as any`、`@ts-ignore`、`unknown` 未收窄 |
-| 错误处理 | 搜索裸 `catch`、无 `try/catch` 的 async 调用 |
-| Deep nesting | 搜索嵌套超过 4 层的 if/for/switch |
+| 检查项       | 方法                                          |
+| ------------ | --------------------------------------------- |
+| Dead code    | Grep 搜索未被引用的 export、未使用的 import   |
+| 不一致模式   | 对比同一目录下多个文件的代码风格/模式差异     |
+| 类型安全     | 搜索 `as any`、`@ts-ignore`、`unknown` 未收窄 |
+| 错误处理     | 搜索裸 `catch`、无 `try/catch` 的 async 调用  |
+| Deep nesting | 搜索嵌套超过 4 层的 if/for/switch             |
 
 ### 2. 架构完整性
 
-| 检查项 | 方法 |
-|--------|------|
-| 循环依赖 | 分析 import 图，检测 A→B→A |
-| 接口契约 | 对比 `shared/types.ts` 中的类型定义与实际使用 |
-| 模块边界 | 检查是否有跨层级直接访问（ui/ 直接 import core/ 内部实现） |
-| God objects | 搜索超过 500 行的单个类/函数 |
+| 检查项      | 方法                                                       |
+| ----------- | ---------------------------------------------------------- |
+| 循环依赖    | 分析 import 图，检测 A→B→A                                 |
+| 接口契约    | 对比 `shared/types.ts` 中的类型定义与实际使用              |
+| 模块边界    | 检查是否有跨层级直接访问（ui/ 直接 import core/ 内部实现） |
+| God objects | 搜索超过 500 行的单个类/函数                               |
 
 ### 3. 性能
 
-| 检查项 | 方法 |
-|--------|------|
-| 同步阻塞 | 搜索 `readFileSync`、`execSync` 在主线程中 |
+| 检查项       | 方法                                            |
+| ------------ | ----------------------------------------------- |
+| 同步阻塞     | 搜索 `readFileSync`、`execSync` 在主线程中      |
 | 内存泄漏风险 | 搜索未清理的 setInterval、EventEmitter listener |
-| 渲染性能 | 检查 React memo/callback 使用是否完整 |
-| N+1 模式 | 搜索在循环内的 I/O 操作 |
+| 渲染性能     | 检查 React memo/callback 使用是否完整           |
+| N+1 模式     | 搜索在循环内的 I/O 操作                         |
 
 ### 4. 安全
 
-| 检查项 | 方法 |
-|--------|------|
-| 硬编码凭据 | 搜索 API key、token、password 字符串 |
-| 路径遍历 | 搜索使用用户输入的 `join`/`resolve` 路径 |
-| 命令注入 | 搜索字符串拼接的 shell 命令 |
-| 许可合规 | 检查 package.json 中的 copyleft 依赖 |
+| 检查项     | 方法                                     |
+| ---------- | ---------------------------------------- |
+| 硬编码凭据 | 搜索 API key、token、password 字符串     |
+| 路径遍历   | 搜索使用用户输入的 `join`/`resolve` 路径 |
+| 命令注入   | 搜索字符串拼接的 shell 命令              |
+| 许可合规   | 检查 package.json 中的 copyleft 依赖     |
 
 ### 5. 测试覆盖
 
-| 检查项 | 方法 |
-|--------|------|
-| 未测试模块 | Glob 所有 `src/**/*.ts`，对比 `test/` 目录 |
-| 关键路径覆盖 | 识别 engine、permission、tools 层，检查测试 |
+| 检查项          | 方法                                              |
+| --------------- | ------------------------------------------------- |
+| 未测试模块      | Glob 所有 `src/**/*.ts`，对比 `test/` 目录        |
+| 关键路径覆盖    | 识别 engine、permission、tools 层，检查测试       |
 | Flaky test 风险 | 搜索 `setTimeout`、`Math.random`、Date 依赖的测试 |
-| 边界测试缺失 | 检查主要函数的 null/undefined/empty 参数测试 |
+| 边界测试缺失    | 检查主要函数的 null/undefined/empty 参数测试      |
 
 ### 6. CRSI 集成健康
 
-| 检查项 | 方法 |
-|--------|------|
-| Rule 引擎状态 | 检查活跃规则数、禁用规则数、builtin vs auto-generated |
-| 效果追踪 | 从 EffectivenessTracker 读取规则成功率 |
-| 模式分析器 | 检查累积的 Agent 失败模式 |
-| AutoMemory 状态 | 检查复盘文件数量、CRSI 洞察统计 |
+| 检查项          | 方法                                                  |
+| --------------- | ----------------------------------------------------- |
+| Rule 引擎状态   | 检查活跃规则数、禁用规则数、builtin vs auto-generated |
+| 效果追踪        | 从 EffectivenessTracker 读取规则成功率                |
+| 模式分析器      | 检查累积的 Agent 失败模式                             |
+| AutoMemory 状态 | 检查复盘文件数量、CRSI 洞察统计                       |
 
 ## 执行流程
 
@@ -125,14 +125,14 @@ Mipham Code 审计 Mipham Code — 这是 CRSI 递归自我改进的第一个闭
 
 ## 摘要
 
-| 维度 | 评分 | 发现数 | 严重 |
-|------|------|--------|------|
-| 代码质量 | 7/10 | 12 | 2 |
-| 架构完整性 | 8/10 | 3 | 0 |
-| 性能 | 7/10 | 5 | 1 |
-| 安全 | 8/10 | 2 | 0 |
-| 测试覆盖 | 7/10 | 8 | 1 |
-| CRSI 健康 | 9/10 | 0 | 0 |
+| 维度       | 评分 | 发现数 | 严重 |
+| ---------- | ---- | ------ | ---- |
+| 代码质量   | 7/10 | 12     | 2    |
+| 架构完整性 | 8/10 | 3      | 0    |
+| 性能       | 7/10 | 5      | 1    |
+| 安全       | 8/10 | 2      | 0    |
+| 测试覆盖   | 7/10 | 8      | 1    |
+| CRSI 健康  | 9/10 | 0      | 0    |
 
 ## 🔴 严重 (需要立即处理)
 
@@ -148,9 +148,9 @@ Mipham Code 审计 Mipham Code — 这是 CRSI 递归自我改进的第一个闭
 
 ## CRSI 规则更新
 
-| 规则 ID | 类型 | 状态 | 上次评估 |
-|---------|------|------|---------|
-| ... | ... | active/degraded/disabled | ... |
+| 规则 ID | 类型 | 状态                     | 上次评估 |
+| ------- | ---- | ------------------------ | -------- |
+| ...     | ...  | active/degraded/disabled | ...      |
 ```
 
 ## 安全约束

package/src/core/auto-memory.ts

@@ -419,10 +419,7 @@ export class AutoMemoryEngine {
     return decisions.slice(0, 5)
   }
 
-  private extractActionItems(
-    assistantContent: string,
-    toolCalls: ToolCallRecord[],
-  ): string[] {
+  private extractActionItems(assistantContent: string, toolCalls: ToolCallRecord[]): string[] {
     const items: string[] = []
 
     // Check for TODO markers in assistant content
@@ -594,7 +591,13 @@ export class AutoMemoryEngine {
       `| 成功率 | ${totalSuccesses + totalFailures > 0 ? Math.round((totalSuccesses / (totalSuccesses + totalFailures)) * 100) : 100}% |`,
       '',
       ...(criticalInsights.length > 0
-        ? ['## ⚠️ 关键洞察', '', ...criticalInsights.map((i) => `- **${i.category}**: ${i.description}\n  → ${i.suggestion}`)]
+        ? [
+            '## ⚠️ 关键洞察',
+            '',
+            ...criticalInsights.map(
+              (i) => `- **${i.category}**: ${i.description}\n  → ${i.suggestion}`,
+            ),
+          ]
         : []),
       '',
       '---',

package/src/core/crsi-sandbox.ts

@@ -52,7 +52,8 @@ export interface CrsiModificationResult {
   /** Error message if something failed */
   error?: string
   /** Current phase of the sandbox pipeline */
-  phase: 'pending' | 'applied' | 'testing' | 'passed' | 'failed' | 'approved' | 'merged' | 'rolled-back'
+  phase:
+    'pending' | 'applied' | 'testing' | 'passed' | 'failed' | 'approved' | 'merged' | 'rolled-back'
 }
 
 export interface CrsiTestResult {
@@ -154,7 +155,12 @@ export class CrsiSandbox {
    */
   applyModification(mod: CrsiModification): CrsiModificationResult {
     if (!this.worktreePath) {
-      return { modification: mod, applied: false, phase: 'pending', error: 'No worktree created. Call createWorktree() first.' }
+      return {
+        modification: mod,
+        applied: false,
+        phase: 'pending',
+        error: 'No worktree created. Call createWorktree() first.',
+      }
     }
 
     this.sessionReport.summary.total++
@@ -180,7 +186,8 @@ export class CrsiSandbox {
     try {
       const currentContent = readFileSync(targetPath, 'utf-8')
       if (currentContent !== mod.originalContent && mod.originalContent) {
-        result.error = 'Original content mismatch — file may have been modified since the audit. Aborting.'
+        result.error =
+          'Original content mismatch — file may have been modified since the audit. Aborting.'
         result.phase = 'failed'
         this.sessionReport.modifications.push(result)
         return result
@@ -313,9 +320,7 @@ export class CrsiSandbox {
     }
 
     // Check that all modifications passed tests
-    const failedCount = this.sessionReport.modifications.filter(
-      (m) => m.phase === 'failed',
-    ).length
+    const failedCount = this.sessionReport.modifications.filter((m) => m.phase === 'failed').length
     if (failedCount > 0) {
       return {
         success: false,

package/src/index.tsx

@@ -24,7 +24,7 @@ import { ContextManager } from './core/context'
 import { QueryEngine } from './core/engine'
 import { ExperienceRuleEngine } from './core/rule-engine.js'
 import { SessionStore } from './core/session-store'
-import type { PermissionLevel } from './shared/types'
+import type { PermissionLevel, MiphamConfig } from './shared/types'
 import { SkillsLoader } from './skills/loader'
 import { PluginManager } from './plugin/plugin-manager'
 import { loadPlugins } from './plugin/plugin-loader'
@@ -42,6 +42,7 @@ import { AgentViewDashboard } from './agent-view/dashboard'
 import { createT } from './i18n-core/t'
 import { detectLocale } from './i18n-core/detect'
 import { I18nProvider } from './i18n-context'
+import { ConfigWizard } from './ui/config-wizard'
 import enUS from './i18n-core/locales/en-US.json' with { type: 'json' }
 import zhCN from './i18n-core/locales/zh-CN.json' with { type: 'json' }
 import type { TranslationMap } from './i18n-core/types'
@@ -111,6 +112,70 @@ async function checkWorkspaceTrust(): Promise<void> {
   }
 }
 
+// ── SetupGate: first-run wizard → App bridge ──
+
+interface SetupGateProps {
+  needsSetup: boolean
+  engine: QueryEngine
+  config: MiphamConfig
+  defaultProvider: string
+  defaultModel: string
+  lang?: string
+  skillsLoader?: SkillsLoader
+  pluginManager?: PluginManager
+  version?: string
+  sessionId: string
+  agentViewManager?: AgentViewManager
+  locale: string
+  t: (key: string) => string
+}
+
+function SetupGate(props: SetupGateProps) {
+  const [showWizard, setShowWizard] = React.useState(props.needsSetup)
+  const [wizardProvider, setWizardProvider] = React.useState<string | null>(null)
+  const [wizardModel, setWizardModel] = React.useState<string | null>(null)
+
+  // When wizard completes: write config, switch provider, proceed to App
+  const handleWizardComplete = React.useCallback(
+    (wizardConfig: { providerId: string; modelId: string; apiKey: string }) => {
+      // Switch the engine to the newly configured provider
+      try {
+        props.engine.switchProvider(wizardConfig.providerId, wizardConfig.modelId)
+      } catch {
+        // If switch fails (e.g. provider not yet in registry), just use as-is
+      }
+      setWizardProvider(wizardConfig.providerId)
+      setWizardModel(wizardConfig.modelId)
+      setShowWizard(false)
+    },
+    [props.engine],
+  )
+
+  const handleWizardSkip = React.useCallback(() => {
+    setShowWizard(false)
+  }, [])
+
+  if (showWizard) {
+    return React.createElement(ConfigWizard, {
+      onComplete: handleWizardComplete,
+      onSkip: handleWizardSkip,
+    })
+  }
+
+  return React.createElement(App, {
+    engine: props.engine,
+    config: props.config,
+    initialProvider: wizardProvider || props.defaultProvider,
+    initialModel: wizardModel || props.defaultModel,
+    lang: props.lang,
+    skillsLoader: props.skillsLoader,
+    pluginManager: props.pluginManager,
+    version: props.version,
+    sessionId: props.sessionId,
+    agentViewManager: props.agentViewManager,
+  })
+}
+
 export async function runApp(options: RunOptions): Promise<void> {
   // Metrics: count CLI invocation
   getMetrics().cliInvocations.inc()
@@ -481,21 +546,29 @@ export async function runApp(options: RunOptions): Promise<void> {
     }
   })
 
+  // ── First-run detection: show interactive ConfigWizard if no config exists ──
+  const hasUserConfig = existsSync(join(homedir(), '.mipham', 'config.yml'))
+  const hasProjectConfig = existsSync(join(process.cwd(), '.mipham', 'config.yml'))
+  const needsSetup = !hasUserConfig && !hasProjectConfig
+
   const { waitUntilExit } = render(
     React.createElement(I18nProvider, {
       locale,
       t,
-      children: React.createElement(App, {
+      children: React.createElement(SetupGate, {
+        needsSetup,
         engine,
         config,
-        initialProvider: defaultProvider,
-        initialModel: defaultModel,
+        defaultProvider,
+        defaultModel,
         lang: options.lang,
         skillsLoader,
         pluginManager,
         version: options.version,
         sessionId: sessionName,
         agentViewManager,
+        locale,
+        t,
       }),
     }),
   )

package/src/shared/constants.ts

@@ -35,6 +35,33 @@ export const DEFAULT_PROVIDERS: ProviderConfig[] = [
         vision: true,
         status: 'active',
       },
+      {
+        id: 'claude-fable-5',
+        name: 'Claude Fable 5',
+        providerId: 'anthropic',
+        contextWindow: 1_000_000,
+        maxOutput: 128_000,
+        vision: true,
+        status: 'active',
+      },
+      {
+        id: 'claude-sonnet-5',
+        name: 'Claude Sonnet 5',
+        providerId: 'anthropic',
+        contextWindow: 1_000_000,
+        maxOutput: 128_000,
+        vision: true,
+        status: 'active',
+      },
+      {
+        id: 'claude-opus-5',
+        name: 'Claude Opus 5',
+        providerId: 'anthropic',
+        contextWindow: 1_000_000,
+        maxOutput: 128_000,
+        vision: true,
+        status: 'active',
+      },
     ],
   },
   {

package/src/ui/app.tsx

@@ -44,6 +44,8 @@ export interface ToolMeta {
   input: string
   output?: string
   collapsed: boolean
+  /** Original tool name before Claude Code display renaming (e.g. Write→Update). */
+  originalName?: string
 }
 
 export interface ChatMessage {
@@ -87,7 +89,8 @@ const PERMISSION_COLORS: Record<PermissionMode, string> = {
   bypassPermissions: 'red',
 }
 
-/** Format a tool's input parameters into a compact one-line detail string. */
+/** Format a tool's input parameters into a compact one-line detail string.
+ *  Tool display names follow Claude Code convention: Write/Edit → Update. */
 function formatToolDetail(name: string, input: Record<string, unknown>): string {
   switch (name) {
     case 'Bash':
@@ -95,9 +98,9 @@ function formatToolDetail(name: string, input: Record<string, unknown>): string
     case 'Read':
       return (input.file_path as string) || ''
     case 'Write':
-      return (input.file_path as string) || ''
+      return (input.file_path as string) || '' // displayed as "Update" in chat
     case 'Edit':
-      return (input.file_path as string) || ''
+      return `${(input.file_path as string) || ''}: ${((input.old_string as string) || '').slice(0, 60)}` // displayed as "Update" in chat
     case 'Grep':
       return (input.pattern as string) || ''
     case 'Glob':
@@ -115,6 +118,12 @@ function formatToolDetail(name: string, input: Record<string, unknown>): string
   }
 }
 
+/** Claude Code display name: maps Write/Edit → Update for parity. */
+function toolDisplayName(name: string): string {
+  if (name === 'Write' || name === 'Edit') return 'Update'
+  return name
+}
+
 export function App({
   engine,
   config,
@@ -462,7 +471,12 @@ export function App({
               {
                 role: 'system' as const,
                 content: detail,
-                toolMeta: { name: toolName, input: detail, collapsed: true },
+                toolMeta: {
+                  name: toolDisplayName(toolName),
+                  input: detail,
+                  collapsed: true,
+                  originalName: toolName,
+                },
               },
             ])
             // Flush stream buffer before showing tool card
@@ -475,18 +489,35 @@ export function App({
             setAgentProgress(null)
             // Sync background agents (e.g. Agent tool may have spawned them)
             syncBgAgents()
-            // Only show tool results with meaningful content.
-            // Skip empty results, "(no matches)", and other noise.
             const output = chunk.content ? String(chunk.content).trim() : ''
             if (output && output !== '(no matches)' && output.length > 20) {
-              const firstLine = output.split('\n')[0]!.slice(0, 200)
-              const preview = firstLine.length < output.length ? `${firstLine}...` : firstLine
+              // Generate diff-style summary for file operations (Claude Code parity)
+              let preview: string
+              const isFileOp = chunk.toolUse?.name === 'Write' || chunk.toolUse?.name === 'Edit'
+              if (isFileOp && chunk.toolUse?.input?.file_path) {
+                const filePath = String(chunk.toolUse.input.file_path)
+                const newContent = String(
+                  chunk.toolUse.input.content || chunk.toolUse.input.new_string || '',
+                )
+                // Count lines added/removed for Write operations
+                const lineCount = newContent.split('\n').length
+                preview = `Updated ${filePath} · ${lineCount} lines`
+              } else {
+                const firstLine = output.split('\n')[0]!.slice(0, 200)
+                preview = firstLine.length < output.length ? `${firstLine}...` : firstLine
+              }
               setMessages((prev) => [
                 ...prev,
                 {
                   role: 'system' as const,
-                  content: `  ⎿  ${preview}`,
-                  toolMeta: { name: '', input: '', output: preview, collapsed: true },
+                  content: preview,
+                  toolMeta: {
+                    name: '',
+                    input: '',
+                    output: preview,
+                    collapsed: true,
+                    originalName: chunk.toolUse?.name,
+                  },
                 },
               ])
             }

package/src/ui/chat.tsx

@@ -28,6 +28,7 @@ function toolColor(name: string): string {
       return 'white'
     case 'Write':
     case 'Edit':
+    case 'Update':
       return 'red'
     case 'Agent':
     case 'Task':
@@ -59,12 +60,19 @@ const MessageRow = React.memo(
       >
         {msg.toolMeta ? (
           <Box flexDirection="column">
-            <Text color={toolColor(msg.toolMeta.name)}>
-              {msg.toolMeta.collapsed ? '⏺' : '⏺ ▼'} {msg.toolMeta.name}
-              {msg.toolMeta.input ? `(${msg.toolMeta.input.slice(0, 120)})` : ''}
-            </Text>
+            {/* Tool call line: ⏺ ToolName(detail) — Claude Code parity */}
+            {msg.toolMeta.name ? (
+              <Text color={toolColor(msg.toolMeta.name)}>
+                {msg.toolMeta.collapsed ? '⏺' : '⏺ ▼'} {msg.toolMeta.name}
+                {msg.toolMeta.input ? ` (${msg.toolMeta.input.slice(0, 120)})` : ''}
+              </Text>
+            ) : null}
+            {/* Tool result line: ⎿  summary text */}
             {msg.toolMeta.output ? (
-              <Text dimColor> ⎿ {msg.toolMeta.output.slice(0, 300)}</Text>
+              <Text dimColor>
+                {'  ⎿  '}
+                {msg.toolMeta.output.slice(0, 300)}
+              </Text>
             ) : msg.content && !msg.toolMeta.collapsed ? (
               <Text dimColor>{msg.content}</Text>
             ) : null}

package/src/ui/config-wizard.tsx

@@ -0,0 +1,519 @@
+/**
+ * Interactive first-run Config Wizard
+ *
+ * Replaces manual config.yml editing for non-technical users.
+ * Flow: Welcome → Local/Cloud → Provider → Model → API Key → Done
+ *
+ * Local path: Ollama setup (endpoint + model pull)
+ * Cloud path: pick provider → pick model → paste API key → auto-configure
+ */
+
+import React, { useState, useCallback } from 'react'
+import { Box, Text, useInput } from 'ink'
+import TextInput from 'ink-text-input'
+import { DEFAULT_PROVIDERS } from '../shared/constants'
+import type { ProviderConfig, ModelInfo } from '../shared/types'
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { execSync } from 'node:child_process'
+
+// ── Types ──
+
+interface WizardState {
+  step:
+    | 'welcome'
+    | 'mode'
+    | 'cloud-provider'
+    | 'cloud-model'
+    | 'cloud-key'
+    | 'local-ollama'
+    | 'confirm'
+    | 'done'
+  mode: 'local' | 'cloud' | null
+  providerId: string | null
+  modelId: string | null
+  apiKey: string
+  ollamaEndpoint: string
+  ollamaModel: string
+  error: string | null
+}
+
+interface Props {
+  onComplete: (config: { providerId: string; modelId: string; apiKey: string }) => void
+  onSkip: () => void
+}
+
+// ── Helpers ──
+
+/** Filter to cloud-only providers (exclude ollama/mipham local-only). */
+const CLOUD_PROVIDERS = DEFAULT_PROVIDERS.filter((p) => p.id !== 'ollama' && p.id !== 'mipham')
+
+/** Get active models for a provider. */
+function getModels(providerId: string): ModelInfo[] {
+  const provider = DEFAULT_PROVIDERS.find((p) => p.id === providerId)
+  return provider?.models.filter((m) => m.status === 'active') || []
+}
+
+/** Write config.yml to ~/.mipham/ */
+function writeConfig(providerId: string, modelId: string, apiKey: string): void {
+  const configDir = join(homedir(), '.mipham')
+  mkdirSync(configDir, { recursive: true })
+
+  const provider = DEFAULT_PROVIDERS.find((p) => p.id === providerId)
+  const configLines = [
+    `# Mipham Code Configuration`,
+    `# Generated by Config Wizard`,
+    `# ${new Date().toISOString()}`,
+    ``,
+    `version: 1`,
+    `defaultProvider: ${providerId}`,
+    `defaultModel: ${modelId}`,
+    `permission: default`,
+    ``,
+    `providers:`,
+    `  - id: ${providerId}`,
+    `    name: ${provider?.name || providerId}`,
+    `    protocol: ${provider?.protocol || 'openai-compatible'}`,
+    ...(provider?.baseUrl ? [`    baseUrl: ${provider.baseUrl}`] : []),
+    `    apiKey: ${apiKey}`,
+    `    models:`,
+  ]
+
+  const models = getModels(providerId)
+  for (const m of models) {
+    configLines.push(`      - id: ${m.id}`)
+  }
+
+  writeFileSync(join(configDir, 'config.yml'), configLines.join('\n'), 'utf-8')
+}
+
+/** Check if Ollama is installed and running. */
+function checkOllama(): { installed: boolean; running: boolean; models: string[] } {
+  try {
+    execSync('ollama --version', { timeout: 5000, stdio: 'ignore' })
+    const models = execSync('ollama list', { timeout: 5000, encoding: 'utf-8' })
+      .split('\n')
+      .slice(1)
+      .filter(Boolean)
+      .map((l) => l.split(/\s+/)[0]!)
+    return { installed: true, running: true, models }
+  } catch {
+    try {
+      execSync('ollama --version', { timeout: 5000, stdio: 'ignore' })
+      return { installed: true, running: false, models: [] }
+    } catch {
+      return { installed: false, running: false, models: [] }
+    }
+  }
+}
+
+// ── Component ──
+
+export function ConfigWizard({ onComplete, onSkip }: Props) {
+  const [state, setState] = useState<WizardState>({
+    step: 'welcome',
+    mode: null,
+    providerId: null,
+    modelId: null,
+    apiKey: '',
+    ollamaEndpoint: 'http://localhost:11434',
+    ollamaModel: '',
+    error: null,
+  })
+
+  const [selectedIdx, setSelectedIdx] = useState(0)
+  const [inputValue, setInputValue] = useState('')
+  const [ollamaStatus, setOllamaStatus] = useState<ReturnType<typeof checkOllama> | null>(null)
+
+  // ── Navigation helpers ──
+
+  const goTo = useCallback((step: WizardState['step']) => {
+    setSelectedIdx(0)
+    setInputValue('')
+    setState((s) => ({ ...s, step, error: null }))
+  }, [])
+
+  const setMode = useCallback(
+    (mode: 'local' | 'cloud') => {
+      setState((s) => ({ ...s, mode }))
+      if (mode === 'cloud') {
+        goTo('cloud-provider')
+      } else {
+        const status = checkOllama()
+        setOllamaStatus(status)
+        goTo('local-ollama')
+      }
+    },
+    [goTo],
+  )
+
+  const selectProvider = useCallback(
+    (providerId: string) => {
+      setState((s) => ({ ...s, providerId }))
+      goTo('cloud-model')
+    },
+    [goTo],
+  )
+
+  const selectModel = useCallback(
+    (modelId: string) => {
+      setState((s) => ({ ...s, modelId }))
+      goTo('cloud-key')
+    },
+    [goTo],
+  )
+
+  const confirmApiKey = useCallback(() => {
+    const key = inputValue.trim()
+    if (!key) {
+      setState((s) => ({ ...s, error: '请输入 API Key' }))
+      return
+    }
+    setState((s) => ({ ...s, apiKey: key, error: null }))
+    goTo('confirm')
+  }, [inputValue, goTo])
+
+  const finishLocal = useCallback(() => {
+    const endpoint = inputValue.trim() || 'http://localhost:11434'
+    const model = state.ollamaModel || 'llama3.2'
+    try {
+      writeConfig('ollama', model, 'ollama-local')
+      onComplete({ providerId: 'ollama', modelId: model, apiKey: 'ollama-local' })
+    } catch (err) {
+      setState((s) => ({ ...s, error: `配置写入失败: ${String(err)}` }))
+    }
+  }, [inputValue, state.ollamaModel, onComplete])
+
+  const finishCloud = useCallback(() => {
+    if (!state.providerId || !state.modelId || !state.apiKey) return
+    try {
+      writeConfig(state.providerId, state.modelId, state.apiKey)
+      onComplete({ providerId: state.providerId, modelId: state.modelId, apiKey: state.apiKey })
+    } catch (err) {
+      setState((s) => ({ ...s, error: `配置写入失败: ${String(err)}` }))
+    }
+  }, [state, onComplete])
+
+  // ── Keyboard ──
+
+  useInput((_input, key) => {
+    if (key.escape) {
+      onSkip()
+      return
+    }
+
+    if (state.step === 'welcome') {
+      if (key.return) goTo('mode')
+      return
+    }
+
+    if (state.step === 'mode') {
+      if (key.upArrow || key.downArrow) {
+        setSelectedIdx((i) => (i === 0 ? 1 : 0))
+      }
+      if (key.return) {
+        setMode(selectedIdx === 0 ? 'cloud' : 'local')
+      }
+      return
+    }
+
+    // Cloud provider / model selection (list navigation)
+    if (state.step === 'cloud-provider' || state.step === 'cloud-model') {
+      const items =
+        state.step === 'cloud-provider'
+          ? CLOUD_PROVIDERS
+          : state.providerId
+            ? getModels(state.providerId)
+            : []
+
+      if (items.length === 0) return
+
+      if (key.upArrow) {
+        setSelectedIdx((i) => (i > 0 ? i - 1 : items.length - 1))
+      }
+      if (key.downArrow) {
+        setSelectedIdx((i) => (i < items.length - 1 ? i + 1 : 0))
+      }
+      if (key.return) {
+        const item = items[selectedIdx]
+        if (item) {
+          if (state.step === 'cloud-provider') {
+            selectProvider((item as ProviderConfig).id)
+          } else {
+            selectModel((item as ModelInfo).id)
+          }
+        }
+      }
+      return
+    }
+
+    // API key input: Enter submits
+    if (state.step === 'cloud-key') {
+      if (key.return) {
+        confirmApiKey()
+      }
+      return
+    }
+
+    // Local Ollama input
+    if (state.step === 'local-ollama') {
+      if (key.return) {
+        finishLocal()
+      }
+      return
+    }
+
+    // Confirm
+    if (state.step === 'confirm') {
+      if (key.return) {
+        finishCloud()
+      }
+      if (key.backspace) {
+        goTo('cloud-key')
+      }
+      return
+    }
+  })
+
+  // ── Render ──
+
+  const selectedColor = 'cyan'
+  const dimColor = 'gray'
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      {/* Header */}
+      <Box marginBottom={1}>
+        <Text color="#FFD700" bold>
+          Mipham Code
+        </Text>
+        <Text dimColor> — 配置向导</Text>
+      </Box>
+
+      <Box marginBottom={1}>
+        <Text dimColor>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</Text>
+      </Box>
+
+      {/* ── Welcome ── */}
+      {state.step === 'welcome' && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold color="cyan">
+              欢迎使用 Mipham Code！
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>在开始之前，需要先配置 AI 模型连接。</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>此向导只需 1-2 分钟，需要您准备好 API Key。</Text>
+          </Box>
+          <Box marginTop={1}>
+            <Text color="yellow">按 Enter 开始配置 →</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Mode Selection ── */}
+      {state.step === 'mode' && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold>选择模型连接方式：</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text color={selectedIdx === 0 ? selectedColor : dimColor}>
+              {selectedIdx === 0 ? '▶' : ' '} 🌐 云端 AI 模型（推荐）
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text dimColor> Claude · DeepSeek · Gemini · 豆包 · Qwen · 混元 · OpenAI</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text color={selectedIdx === 1 ? selectedColor : dimColor}>
+              {selectedIdx === 1 ? '▶' : ' '} 🖥️ 本地模型（Ollama）
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text dimColor> 需要提前安装 Ollama 并下载模型</Text>
+          </Box>
+          <Box marginTop={1}>
+            <Text dimColor>↑↓ 选择 · Enter 确认 · Esc 跳过</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Cloud: Provider Selection ── */}
+      {state.step === 'cloud-provider' && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold>选择 AI 模型提供商：</Text>
+          </Box>
+          {CLOUD_PROVIDERS.map((p, i) => (
+            <Box key={p.id} marginBottom={1}>
+              <Text color={i === selectedIdx ? selectedColor : undefined}>
+                {i === selectedIdx ? '▶' : ' '} {p.name}
+              </Text>
+              <Text dimColor> ({p.models.filter((m) => m.status === 'active').length} 个模型)</Text>
+            </Box>
+          ))}
+          <Box marginTop={1}>
+            <Text dimColor>↑↓ 选择 · Enter 确认 · Esc 返回</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Cloud: Model Selection ── */}
+      {state.step === 'cloud-model' && state.providerId && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold>
+              选择模型（{DEFAULT_PROVIDERS.find((p) => p.id === state.providerId)?.name}）：
+            </Text>
+          </Box>
+          {getModels(state.providerId).map((m, i) => (
+            <Box key={m.id} marginBottom={1}>
+              <Text color={i === selectedIdx ? selectedColor : undefined}>
+                {i === selectedIdx ? '▶' : ' '} {m.name}
+              </Text>
+              <Text dimColor> ({m.id})</Text>
+            </Box>
+          ))}
+          <Box marginTop={1}>
+            <Text dimColor>↑↓ 选择 · Enter 确认 · Esc 返回</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Cloud: API Key ── */}
+      {state.step === 'cloud-key' && state.providerId && state.modelId && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold>粘贴 API Key：</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text dimColor>
+              提供商：{DEFAULT_PROVIDERS.find((p) => p.id === state.providerId)?.name}
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text dimColor>
+              模型：{getModels(state.providerId).find((m) => m.id === state.modelId)?.name}
+            </Text>
+          </Box>
+          {state.error && (
+            <Box marginBottom={1}>
+              <Text color="red">⚠ {state.error}</Text>
+            </Box>
+          )}
+          <Box>
+            <Text color="yellow">🔑 </Text>
+            <TextInput
+              value={inputValue}
+              onChange={setInputValue}
+              onSubmit={confirmApiKey}
+              placeholder="粘贴 API Key 后按 Enter..."
+            />
+          </Box>
+          <Box marginTop={1}>
+            <Text dimColor>Enter 确认 · Esc 返回</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Local: Ollama ── */}
+      {state.step === 'local-ollama' && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold>Ollama 本地模型配置：</Text>
+          </Box>
+          {ollamaStatus ? (
+            <Box flexDirection="column" marginBottom={1}>
+              <Text>
+                状态：{ollamaStatus.installed ? '✅ 已安装' : '❌ 未安装'}
+                {ollamaStatus.running ? ' · 运行中' : ''}
+              </Text>
+              {ollamaStatus.models.length > 0 && (
+                <Box marginTop={1}>
+                  <Text dimColor>已下载模型：{ollamaStatus.models.join(', ')}</Text>
+                </Box>
+              )}
+            </Box>
+          ) : (
+            <Box marginBottom={1}>
+              <Text dimColor>正在检测 Ollama...</Text>
+            </Box>
+          )}
+          <Box marginBottom={1}>
+            <Text dimColor>请输入 Ollama 模型名称（如 llama3.2, qwen2.5, deepseek-r1）：</Text>
+          </Box>
+          <Box>
+            <Text color="yellow">🖥️ </Text>
+            <TextInput
+              value={inputValue}
+              onChange={setInputValue}
+              onSubmit={finishLocal}
+              placeholder="ollama 模型名，默认 llama3.2"
+            />
+          </Box>
+          <Box marginTop={1}>
+            <Text dimColor>Enter 确认 · Esc 返回</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Confirm ── */}
+      {state.step === 'confirm' && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text bold color="cyan">
+              配置确认：
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>连接方式：{state.mode === 'cloud' ? '🌐 云端' : '🖥️ 本地'}</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>提供商：{DEFAULT_PROVIDERS.find((p) => p.id === state.providerId)?.name}</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>模型：{state.modelId}</Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>
+              API Key：{state.apiKey.slice(0, 8)}...{state.apiKey.slice(-4)}
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text dimColor>配置文件将保存到 ~/.mipham/config.yml</Text>
+          </Box>
+          {state.error && (
+            <Box marginBottom={1}>
+              <Text color="red">⚠ {state.error}</Text>
+            </Box>
+          )}
+          <Box marginTop={1}>
+            <Text color="yellow">按 Enter 保存并开始 →</Text>
+          </Box>
+          <Box marginTop={1}>
+            <Text dimColor>Backspace 返回修改 · Esc 跳过配置</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Done ── */}
+      {state.step === 'done' && (
+        <Box flexDirection="column">
+          <Box marginBottom={1}>
+            <Text color="green" bold>
+              ✅ 配置完成！
+            </Text>
+          </Box>
+          <Box marginBottom={1}>
+            <Text>Mipham Code 正在启动...</Text>
+          </Box>
+        </Box>
+      )}
+    </Box>
+  )
+}