@miphamai/cli 0.30.1 → 0.31.1

package/bin/mipham.ts

@@ -208,8 +208,10 @@ async function runUpdate(): Promise<boolean> {
   console.log(`  Checking npm registry for latest version...`)
   console.log()
 
-  // Check latest version from npm with retry + mirror fallback
+  // Check latest version from npm with retry + mirror fallback.
+  // Track which registry responded so we can use it for the install step too.
   let latestVersion = ''
+  let workingRegistry = 'https://registry.npmjs.org/' // default
   try {
     const { execSync } = await import('node:child_process')
 
@@ -233,7 +235,10 @@ async function runUpdate(): Promise<boolean> {
           { encoding: 'utf-8', timeout: attempt.timeout, stdio: ['pipe', 'pipe', 'pipe'] },
         ).trim()
         latestVersion = result.replace(/"/g, '')
-        if (latestVersion) break
+        if (latestVersion) {
+          workingRegistry = attempt.registry
+          break
+        }
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err))
         // Continue to next attempt
@@ -278,7 +283,7 @@ async function runUpdate(): Promise<boolean> {
   console.log()
   console.log(`Updating ${PACKAGE} to v${latestVersion}...`)
 
-  const ok = performUpdate(latestVersion)
+  const ok = performUpdate(latestVersion, workingRegistry)
   if (!ok) {
     console.log()
     console.log(`✗ Update failed.`)

package/package.json

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

package/src/config/loader.ts

@@ -6,10 +6,11 @@ import {
   readdirSync,
   unlinkSync,
   chmodSync,
+  writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
-import { parse as parseYaml } from 'yaml'
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import type {
   MiphamConfig,
   ProviderConfig,
@@ -409,3 +410,56 @@ export function loadCrossSessionConfig(cwd: string = process.cwd()): CrossSessio
 
   return merged
 }
+
+/**
+ * Persist an API key for a single provider to the user-level config.yml.
+ * Reads the existing YAML, updates/replaces the provider's apiKey field,
+ * and writes it back. Creates the config if it doesn't exist.
+ *
+ * Returns true on success, false on failure.
+ */
+export function saveProviderApiKey(
+  providerId: string,
+  apiKey: string,
+  cwd: string = process.cwd(),
+): boolean {
+  const userConfigPath = join(MIPHAM_HOME, 'config.yml')
+  const projectConfigPath = join(cwd, '.mipham', 'config.yml')
+
+  // Prefer user-level config; fall back to project-level if no user config exists.
+  const configPath = existsSync(userConfigPath) ? userConfigPath : projectConfigPath
+
+  try {
+    mkdirSync(MIPHAM_HOME, { recursive: true, mode: 0o700 })
+
+    // Read existing config (or start fresh)
+    let doc: Record<string, unknown> = {}
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, 'utf-8')
+      doc = (parseYaml(raw) as Record<string, unknown>) || {}
+    } else if (configPath === projectConfigPath) {
+      mkdirSync(join(cwd, '.mipham'), { recursive: true })
+    }
+
+    // Find and update the provider in the providers array
+    const providers = (doc.providers as Array<Record<string, unknown>>) || []
+    const idx = providers.findIndex((p) => p.id === providerId)
+
+    if (idx >= 0) {
+      providers[idx] = { ...providers[idx], apiKey }
+    } else {
+      // Provider not in config — append it
+      providers.push({ id: providerId, apiKey })
+    }
+
+    doc.providers = providers
+
+    // Write back
+    writeFileSync(configPath, stringifyYaml(doc), { encoding: 'utf-8', mode: 0o600 })
+    return true
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`⚠ Mipham Code: failed to save API key for ${providerId}: ${msg}\n`)
+    return false
+  }
+}

package/src/i18n-core/locales/en-US.json

@@ -190,7 +190,9 @@
     },
     "switch": {
       "usage": "Usage: /switch <provider> <model>\nExample: /switch deepseek deepseek-v4-pro",
-      "confirmed": "✓ Switched to {provider}/{model}"
+      "confirmed": "✓ Switched to {provider}/{model}",
+      "needs_api_key": "{provider} requires an API Key. Enter it below, or use Ctrl+P to select a model and input.",
+      "unknown_provider": "Unknown provider: {provider}"
     },
     "goal": {
       "set": "✓ Goal set: \"{goal}\"",
@@ -240,6 +242,11 @@
       "header": "Provider      Model                          Context     Vision",
       "hint": "Use /switch <provider> <model> to change.\nSee /providers for upcoming models."
     },
+    "ollama_refresh": {
+      "not_configured": "Ollama provider not configured",
+      "done": "Ollama models refreshed: {total} total ({added})",
+      "error": "Refresh failed: {error}"
+    },
     "provider": {
       "current": "Current provider: {provider}\nModel: {model}"
     },
@@ -683,7 +690,9 @@
       "coming_soon": "[coming]",
       "no_active_models": "(no active models)",
       "select_provider_hint": "Select a provider → Enter to see models",
-      "select_model_hint": "Select a model → Enter to switch"
+      "select_model_hint": "Select a model → Enter to switch",
+      "needs_api_key": "{provider} requires an API Key",
+      "api_key_placeholder": "Paste API Key and press Enter..."
     },
     "command_picker": {
       "title": "Commands",

package/src/i18n-core/locales/zh-CN.json

@@ -190,7 +190,9 @@
     },
     "switch": {
       "usage": "用法: /switch <provider> <model>\n示例: /switch deepseek deepseek-v4-pro",
-      "confirmed": "✓ 已切换到 {provider}/{model}"
+      "confirmed": "✓ 已切换到 {provider}/{model}",
+      "needs_api_key": "{provider} 需要 API Key。请在下方输入，或使用 Ctrl+P 选择模型后输入。",
+      "unknown_provider": "未知 provider: {provider}"
     },
     "goal": {
       "set": "✓ 目标已设置：\"{goal}\"",
@@ -240,6 +242,11 @@
       "header": "提供商        模型                          上下文      视觉",
       "hint": "使用 /switch <provider> <model> 切换。\n查看 /providers 了解即将上线的模型。"
     },
+    "ollama_refresh": {
+      "not_configured": "Ollama provider 未配置",
+      "done": "Ollama 模型列表已刷新：共 {total} 个模型（{added}）",
+      "error": "刷新失败：{error}"
+    },
     "provider": {
       "current": "当前提供商: {provider}\n模型: {model}"
     },
@@ -683,7 +690,9 @@
       "coming_soon": "[即将推出]",
       "no_active_models": "（无可用模型）",
       "select_provider_hint": "选择提供商 → Enter 查看模型",
-      "select_model_hint": "选择模型 → Enter 切换"
+      "select_model_hint": "选择模型 → Enter 切换",
+      "needs_api_key": "{provider} 需要 API Key",
+      "api_key_placeholder": "粘贴 API Key 后按 Enter..."
     },
     "command_picker": {
       "title": "命令",

package/src/providers/openai-compat.ts

@@ -1,6 +1,8 @@
+import { execSync } from 'node:child_process'
 import type { ProviderConfig, ModelInfo, Message, StreamChunk } from '../shared/index.ts'
 import type { ProviderInstance, ChatRequest } from './registry'
 import { fetchWithRetry } from './fetch-utils'
+import { OLLAMA_PRESET_MODELS } from '../shared/constants'
 
 export class OpenAICompatProvider implements ProviderInstance {
   constructor(public config: ProviderConfig) {}
@@ -167,9 +169,58 @@ export class OpenAICompatProvider implements ProviderInstance {
   }
 
   async listModels(): Promise<ModelInfo[]> {
+    if (this.config.id === 'ollama') {
+      return this.listOllamaModels()
+    }
     return this.config.models.filter((m) => m.status === 'active')
   }
 
+  private listOllamaModels(): ModelInfo[] {
+    const seen = new Set<string>()
+    const result: ModelInfo[] = []
+
+    // 1. ollama list locally downloaded models
+    try {
+      const out = execSync('ollama list', { timeout: 5000, encoding: 'utf-8' })
+      const lines = out.split('\n').slice(1).filter(Boolean)
+      for (const line of lines) {
+        const name = line.split(/\s+/)[0]!
+        if (!seen.has(name)) {
+          seen.add(name)
+          result.push({
+            id: name,
+            name,
+            providerId: 'ollama',
+            contextWindow: 128_000,
+            maxOutput: 32_000,
+            vision: false,
+            status: 'active',
+          })
+        }
+      }
+    } catch {
+      // ollama list failed (not installed / not running) → continue with presets
+    }
+
+    // 2. Preset models (deduplicated)
+    for (const preset of OLLAMA_PRESET_MODELS) {
+      if (!seen.has(preset.id)) {
+        seen.add(preset.id)
+        result.push({
+          id: preset.id,
+          name: `${preset.id} [${preset.source}]`,
+          providerId: 'ollama',
+          contextWindow: 128_000,
+          maxOutput: 32_000,
+          vision: false,
+          status: 'active',
+        })
+      }
+    }
+
+    return result
+  }
+
   async healthCheck(): Promise<boolean> {
     try {
       const rawBase = (this.config as any).baseUrl || (this.config as any).baseURL

package/src/shared/constants.ts

@@ -362,6 +362,14 @@ export const DEFAULT_PROVIDERS: ProviderConfig[] = [
     ],
     status: 'upcoming',
   },
+  {
+    id: 'ollama',
+    name: 'Ollama (本地)',
+    protocol: 'openai-compatible' as const,
+    baseUrl: 'http://localhost:11434/v1',
+    apiKey: 'ollama-local',
+    models: [], // 动态发现，初值为空
+  },
   {
     id: 'openai',
     name: 'OpenAI',
@@ -443,6 +451,19 @@ export const PROTOCOL_LABELS: Record<string, string> = {
 }
 
 export const TOOL_CATEGORIES = ['file', 'exec', 'agent', 'network', 'system', 'artifact'] as const
+
+/** 预置 Ollama 模型 — 与 ollama list 结果合并去重后展示 */
+export const OLLAMA_PRESET_MODELS = [
+  { id: 'om-V5-Flash', source: 'MiphamAI' },
+  { id: 'om-V5-Pro', source: 'MiphamAI' },
+  { id: 'om-V5-Visual', source: 'MiphamAI' },
+  { id: 'om-V5-Apex', source: 'MiphamAI' },
+  { id: 'deepseek-r1:70b', source: '热门' },
+  { id: 'deepseek-v3', source: '热门' },
+  { id: 'qwen2.5:72b', source: '热门' },
+  { id: 'qwen3', source: '热门' },
+] as const
+
 export const CONFIG_FILE_NAME = 'config.yml'
 export const MIPHAM_DIR = '.mipham'
 export const USER_CONFIG_DIR = '.mipham'

package/src/shared/update.ts

@@ -139,19 +139,30 @@ function isValidSemver(v: string): boolean {
 /**
  * Perform the actual update via npm install -g.
  * Validates the version string before shell execution (prevents command injection).
+ *
+ * @param version  Target semver version (must pass isValidSemver).
+ * @param registry Optional npm registry URL — when provided the install uses it
+ *                 directly (useful when the primary registry is slow, e.g. China).
+ *                 Falls back to the npm default if omitted.
  * Returns true on success.
  */
-export function performUpdate(version: string): boolean {
+export function performUpdate(version: string, registry?: string): boolean {
   if (!isValidSemver(version)) {
     process.stderr.write(`⚠ Refusing to install invalid version: "${version}"\n`)
     return false
   }
 
+  // Sanitize registry — only allow known URLs to prevent command injection
+  const allowedRegistries = REGISTRIES.map((r) => r.url)
+  const safeRegistry = registry && allowedRegistries.includes(registry) ? registry : undefined
+
+  const registryFlag = safeRegistry ? ` --registry=${safeRegistry}` : ''
+
   try {
-    execSync(`npm install -g ${PACKAGE}@${version}`, {
+    execSync(`npm install -g ${PACKAGE}@${version}${registryFlag}`, {
       encoding: 'utf-8',
       stdio: 'inherit',
-      timeout: 120_000,
+      timeout: 600_000, // 10 min — slow networks (e.g. China → npmjs) may need 7+ min
     })
     return true
   } catch {

package/src/ui/app.tsx

@@ -1,11 +1,13 @@
 import React, { useState, useCallback, useEffect, useRef, useMemo } from 'react'
 import { Box, Text, useInput } from 'ink'
+import TextInput from 'ink-text-input'
 import { readFileSync } from 'node:fs'
 import type { QueryEngine } from '../core/engine'
 import type { MiphamConfig } from '../shared/index.ts'
 import type { SkillsLoader } from '../skills/loader'
 import type { PluginManager } from '../plugin/plugin-manager'
 import { setPreference } from '../config/preferences'
+import { saveProviderApiKey } from '../config/loader'
 import { AgentRegistry } from '../agent/agent-registry'
 import { getBackgroundAgentRegistry } from '../agent/background-registry'
 import { ChatPanel } from './chat'
@@ -154,6 +156,12 @@ export function App({
   const [modelId, setModelId] = useState(initialModel || config.defaultModel)
   const [pickerOpen, setPickerOpen] = useState(false)
   const [agentViewOpen, setAgentViewOpen] = useState(false)
+  const [apiKeyPrompt, setApiKeyPrompt] = useState<{
+    providerId: string
+    modelId: string
+    providerName: string
+  } | null>(null)
+  const [apiKeyInput, setApiKeyInput] = useState('')
   const [_sessionTitle, setSessionTitle] = useState('')
   const [_fastMode, setFastMode] = useState(false)
   const [_effort, setEffort] = useState('high')
@@ -279,6 +287,40 @@ export function App({
     [engine, config, providerId, modelId, skillsLoader, pluginManager, sessionId, t],
   )
 
+  const handleApiKeySubmit = useCallback(
+    (submittedKey: string) => {
+      if (!apiKeyPrompt || !submittedKey.trim()) return
+
+      const trimmed = submittedKey.trim()
+      const saved = saveProviderApiKey(apiKeyPrompt.providerId, trimmed)
+
+      // Update the in-memory provider's apiKey so subsequent checks pass
+      const provider = config.providers.find((p) => p.id === apiKeyPrompt.providerId)
+      if (provider) {
+        provider.apiKey = trimmed
+      }
+
+      // Execute the switch now that we have the key
+      engine.switchProvider(apiKeyPrompt.providerId, apiKeyPrompt.modelId)
+      setProviderId(apiKeyPrompt.providerId)
+      setModelId(apiKeyPrompt.modelId)
+
+      setMessages((prev) => [
+        ...prev,
+        {
+          role: 'system',
+          content: saved
+            ? `✓ API Key saved for ${apiKeyPrompt.providerName}. Switched to ${apiKeyPrompt.providerId}/${apiKeyPrompt.modelId}.`
+            : `⚠ Could not persist API Key to config, but switched to ${apiKeyPrompt.providerId}/${apiKeyPrompt.modelId} for this session.`,
+        },
+      ])
+
+      setApiKeyPrompt(null)
+      setApiKeyInput('')
+    },
+    [apiKeyPrompt, config, engine],
+  )
+
   const handleSubmit = useCallback(
     async (input: string) => {
       if (!input.trim()) return
@@ -290,13 +332,23 @@ export function App({
         // /switch takes args, handled separately
         if (command === '/switch') {
           const result = await handleSwitch(mkCtx(), args)
-          setMessages((prev) => [
-            ...prev,
-            { role: 'user', content: input },
-            { role: 'system', content: result.content },
-          ])
-          if (result.nextProvider) setProviderId(result.nextProvider)
-          if (result.nextModel) setModelId(result.nextModel)
+          if (result.needsApiKey) {
+            setApiKeyPrompt(result.needsApiKey)
+            setApiKeyInput('')
+            setMessages((prev) => [
+              ...prev,
+              { role: 'user', content: input },
+              { role: 'system', content: result.content },
+            ])
+          } else {
+            setMessages((prev) => [
+              ...prev,
+              { role: 'user', content: input },
+              { role: 'system', content: result.content },
+            ])
+            if (result.nextProvider) setProviderId(result.nextProvider)
+            if (result.nextModel) setModelId(result.nextModel)
+          }
           if (result.exit) process.exit(0)
           return
         }
@@ -335,11 +387,21 @@ export function App({
         if (handler) {
           const result = await handler(mkCtx(), args)
           forwardToAI = result.forwardToAI
+          // Handle API key prompt from command result
+          if (result.needsApiKey) {
+            setApiKeyPrompt(result.needsApiKey)
+            setApiKeyInput('')
+          }
           setMessages((prev) => [
             ...prev,
             { role: 'user', content: input },
             { role: 'system', content: result.content },
           ])
+          if (result.needsApiKey) {
+            // Don't process nextProvider/model when waiting for API key
+            if (result.exit) process.exit(0)
+            return
+          }
           if (result.clearMessages) setMessages([])
           if (result.nextProvider) setProviderId(result.nextProvider)
           if (result.nextModel) setModelId(result.nextModel)
@@ -584,9 +646,14 @@ export function App({
   )
 
   useInput((_input, key) => {
-    // Escape: close picker → abort loading (does NOT exit app)
+    // Escape: close apiKeyPrompt → close picker → abort loading (does NOT exit app)
     // Vim mode toggle is handled by InputBar
     if (key.escape) {
+      if (apiKeyPrompt) {
+        setApiKeyPrompt(null)
+        setApiKeyInput('')
+        return
+      }
       if (pickerOpen) {
         setPickerOpen(false)
         return
@@ -603,6 +670,55 @@ export function App({
     // are handled in InputBar to avoid ink-text-input conflicts
   })
 
+  // ── API Key prompt modal ──
+  if (apiKeyPrompt) {
+    return (
+      <Box flexDirection="column" padding={1} height="100%">
+        {/* Header */}
+        <Box flexDirection="column" marginBottom={1}>
+          <Text color="#FFD700" bold>
+            Mipham Code
+          </Text>
+          <Text dimColor>v{version || '0.0.0'}</Text>
+        </Box>
+
+        {/* Chat panel — show existing messages */}
+        <ChatPanel messages={messages} focusMode={false} />
+
+        {/* API Key input prompt */}
+        <Box flexDirection="column" marginTop={1}>
+          <Text dimColor>──────────────────────────────</Text>
+          <Box
+            flexDirection="column"
+            marginY={1}
+            borderStyle="round"
+            borderColor="yellow"
+            padding={1}
+          >
+            <Text bold color="yellow">
+              {t('ui.picker.needs_api_key', { provider: apiKeyPrompt.providerName })}
+            </Text>
+            <Text dimColor>
+              {apiKeyPrompt.providerId}/{apiKeyPrompt.modelId}
+            </Text>
+            <Box marginTop={1}>
+              <TextInput
+                value={apiKeyInput}
+                onChange={setApiKeyInput}
+                onSubmit={handleApiKeySubmit}
+                placeholder={t('ui.picker.api_key_placeholder')}
+              />
+            </Box>
+            <Box marginTop={1}>
+              <Text dimColor>Esc {t('ui.status.esc_to_interrupt')}</Text>
+            </Box>
+          </Box>
+          <Text dimColor>──────────────────────────────</Text>
+        </Box>
+      </Box>
+    )
+  }
+
   return (
     <Box flexDirection="column" padding={1} height="100%">
       {/* Header — left-aligned */}
@@ -645,6 +761,18 @@ export function App({
                   { role: 'system', content: `✓ Switched to ${newProvider}/${newModel}` },
                 ])
               }}
+              onNeedsApiKey={(providerId, modelId, providerName) => {
+                setApiKeyPrompt({ providerId, modelId, providerName })
+                setApiKeyInput('')
+                setPickerOpen(false)
+                setMessages((prev) => [
+                  ...prev,
+                  {
+                    role: 'system',
+                    content: t('ui.picker.needs_api_key', { provider: providerName }),
+                  },
+                ])
+              }}
               onClose={() => setPickerOpen(false)}
             />
           ) : (

package/src/ui/commands.ts

@@ -41,6 +41,8 @@ import { themeCmd, releaseNotesCmd, ideCmd, terminalSetupCmd } from '../commands
 import { commitCmd, pushCmd, prCmd, issueCmd } from '../commands/git.js'
 import { keysCmd } from '../commands/keys'
 import { workflowViewCmd, workflowWatchCmd } from '../commands/workflow-view.js'
+import { execSync } from 'node:child_process'
+import { OLLAMA_PRESET_MODELS } from '../shared/constants'
 
 export interface CommandContext {
   engine: QueryEngine
@@ -81,6 +83,12 @@ export interface CommandResult {
   forwardToAI?: string
   /** If set, restored messages to load into the session (used by /resume last). */
   forwardedMessages?: Message[]
+  /** API Key 补录请求：切换前需用户输入 Key */
+  needsApiKey?: {
+    providerId: string
+    modelId: string
+    providerName: string
+  }
 }
 
 export type CommandHandler = (
@@ -142,6 +150,7 @@ const helpCmd: CommandHandler = (ctx) => {
       /fast [on|off] Toggle fast mode
       /effort <lvl>  Set reasoning effort (low|medium|high|xhigh|max)
       /theme [dark|light|auto] Set terminal theme
+      /ollama-refresh Refresh Ollama model list at runtime
 
       ── Tools & Skills ──────────────────
       /tools         List available tools (${toolsCount} total)
@@ -351,6 +360,66 @@ const modelsCmd: CommandHandler = (ctx) => {
   }
 }
 
+const ollamaRefreshCmd: CommandHandler = (ctx) => {
+  const t = resolveT(ctx)
+  const ollamaProvider = ctx.config.providers.find((p) => p.id === 'ollama')
+  if (!ollamaProvider) {
+    return { content: t('commands.ollama_refresh.not_configured') }
+  }
+
+  const before = ollamaProvider.models.length
+  try {
+    const seen = new Set<string>()
+    const refreshed: Array<{ id: string }> = []
+
+    // 1. Scan locally downloaded models via `ollama list`
+    try {
+      const out = execSync('ollama list', { timeout: 5000, encoding: 'utf-8' })
+      const lines = out.split('\n').slice(1).filter(Boolean)
+      for (const line of lines) {
+        const name = line.split(/\s+/)[0]!
+        if (!seen.has(name)) {
+          seen.add(name)
+          refreshed.push({ id: name })
+        }
+      }
+    } catch {
+      // ollama list failed (not installed / not running) — continue with presets
+    }
+
+    // 2. Merge preset models (deduplicated)
+    for (const preset of OLLAMA_PRESET_MODELS) {
+      if (!seen.has(preset.id)) {
+        seen.add(preset.id)
+        refreshed.push({ id: preset.id })
+      }
+    }
+
+    // 3. Update the in-memory provider model list
+    ollamaProvider.models = refreshed.map((m) => ({
+      id: m.id,
+      name: m.id,
+      providerId: 'ollama',
+      contextWindow: 128_000,
+      maxOutput: 32_000,
+      vision: false,
+      status: 'active' as const,
+    }))
+
+    const after = refreshed.length
+    const added = after - before
+    return {
+      content: t('commands.ollama_refresh.done', {
+        total: String(after),
+        added: added > 0 ? `+${added}` : String(added),
+      }),
+    }
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return { content: t('commands.ollama_refresh.error', { error: msg }) }
+  }
+}
+
 const providerCmd: CommandHandler = (ctx) => {
   const t = resolveT(ctx)
   return {
@@ -369,12 +438,34 @@ const providersCmd: CommandHandler = (ctx) => {
   }
 }
 
+/** Detect whether an API key is missing (empty, placeholder, or env-var reference that resolves to empty). */
+function isApiKeyMissing(apiKey: string): boolean {
+  if (!apiKey || apiKey.trim() === '') return true
+  if (apiKey === 'ollama-local') return false // Ollama local — no key needed
+  if (/^\$\{[A-Z_]+\}$/.test(apiKey.trim())) return true // ${VAR} placeholder
+  return false
+}
+
 const switchCmd: CommandHandler = (ctx, args) => {
   const t = resolveT(ctx)
   const [newProvider, newModel] = args
   if (!newProvider || !newModel) {
     return { content: t('commands.switch.usage') }
   }
+
+  const provider = ctx.config.providers.find((p) => p.id === newProvider)
+  if (!provider) {
+    return { content: t('commands.switch.unknown_provider', { provider: newProvider }) }
+  }
+
+  // Check API Key before switching
+  if (isApiKeyMissing(provider.apiKey)) {
+    return {
+      content: t('commands.switch.needs_api_key', { provider: provider.name }),
+      needsApiKey: { providerId: newProvider, modelId: newModel, providerName: provider.name },
+    }
+  }
+
   ctx.engine.switchProvider(newProvider, newModel)
   return {
     content: t('commands.switch.confirmed', { provider: newProvider, model: newModel }),
@@ -3169,6 +3260,7 @@ const commandsListCmd: CommandHandler = () => {
     '/pick': 'Model & Provider',
     '/model': 'Model & Provider',
     '/models': 'Model & Provider',
+    '/ollama-refresh': 'Model & Provider',
     '/provider': 'Model & Provider',
     '/providers': 'Model & Provider',
     '/switch': 'Model & Provider',
@@ -3313,6 +3405,7 @@ registry.set('/ultracode', ultracodeCmd)
 // Model & Provider
 registry.set('/model', modelCmd)
 registry.set('/models', modelsCmd)
+registry.set('/ollama-refresh', ollamaRefreshCmd)
 registry.set('/provider', providerCmd)
 registry.set('/providers', providersCmd)
 registry.set('/config', configCmd)

package/src/ui/config-wizard.tsx

@@ -11,7 +11,7 @@
 import React, { useState, useEffect } from 'react'
 import { Box, Text, useInput } from 'ink'
 import TextInput from 'ink-text-input'
-import { DEFAULT_PROVIDERS } from '../shared/constants'
+import { DEFAULT_PROVIDERS, OLLAMA_PRESET_MODELS } from '../shared/constants'
 import type { ProviderConfig, ModelInfo } from '../shared/types'
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -45,7 +45,53 @@ function writeConfigFile(providerId: string, modelId: string, apiKey: string): v
   mkdirSync(configDir, { recursive: true })
 
   const provider = DEFAULT_PROVIDERS.find((p) => p.id === providerId)
-  const models = getActiveModels(providerId)
+  const models =
+    providerId === 'ollama' ? getOllamaModelListForConfig() : getActiveModels(providerId)
+
+  function getOllamaModelListForConfig(): ModelInfo[] {
+    // 与 getOllamaModelList 逻辑一致，但用于配置写入
+    const seen = new Set<string>()
+    const result: ModelInfo[] = []
+
+    // ollama list
+    try {
+      const out = execSync('ollama list', { timeout: 5000, encoding: 'utf-8' })
+      const lines = out.split('\n').slice(1).filter(Boolean)
+      for (const line of lines) {
+        const name = line.split(/\s+/)[0]!
+        if (!seen.has(name)) {
+          seen.add(name)
+          result.push({
+            id: name,
+            name,
+            providerId: 'ollama',
+            contextWindow: 128_000,
+            maxOutput: 32_000,
+            vision: false,
+            status: 'active',
+          })
+        }
+      }
+    } catch {
+      /* ollama not available */
+    }
+
+    for (const p of OLLAMA_PRESET_MODELS) {
+      if (!seen.has(p.id)) {
+        seen.add(p.id)
+        result.push({
+          id: p.id,
+          name: p.id,
+          providerId: 'ollama',
+          contextWindow: 128_000,
+          maxOutput: 32_000,
+          vision: false,
+          status: 'active',
+        })
+      }
+    }
+    return result
+  }
   const lines = [
     '# Mipham Code Configuration',
     `# Generated by Config Wizard — ${new Date().toISOString()}`,
@@ -88,6 +134,36 @@ function checkOllama(): { installed: boolean; running: boolean; models: string[]
   }
 }
 
+// ── Ollama model list helpers ──
+
+interface OllamaModelItem {
+  id: string
+  source: 'local' | 'MiphamAI' | '热门'
+}
+
+function getOllamaModelList(installedModels: string[]): OllamaModelItem[] {
+  const seen = new Set<string>()
+  const result: OllamaModelItem[] = []
+
+  // ollama list 返回的本地模型
+  for (const name of installedModels) {
+    if (!seen.has(name)) {
+      seen.add(name)
+      result.push({ id: name, source: 'local' })
+    }
+  }
+
+  // 预置模型（去重）
+  for (const preset of OLLAMA_PRESET_MODELS) {
+    if (!seen.has(preset.id)) {
+      seen.add(preset.id)
+      result.push({ id: preset.id, source: preset.source as 'MiphamAI' | '热门' })
+    }
+  }
+
+  return result
+}
+
 // ── Component ──
 
 export function ConfigWizard({ onComplete, onSkip }: Props) {
@@ -104,8 +180,10 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
   const [cursor, setCursor] = useState(0)
 
   // Ollama
-  const [ollamaModel, setOllamaModel] = useState('')
+  const [ollamaModel, _setOllamaModel] = useState('')
   const [ollamaStatus, setOllamaStatus] = useState<ReturnType<typeof checkOllama> | null>(null)
+  const [ollamaCursor, setOllamaCursor] = useState(0)
+  const ollamaModelList = ollamaStatus ? getOllamaModelList(ollamaStatus.models) : []
 
   // ── Derived data ──
 
@@ -115,6 +193,7 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
   // Reset cursor when step changes
   const goStep = (s: Step) => {
     setCursor(0)
+    setOllamaCursor(0)
     setError(null)
     setStep(s)
   }
@@ -135,7 +214,8 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
   }
 
   const finishLocal = () => {
-    const model = ollamaModel.trim() || 'llama3.2'
+    const selectedModel = ollamaModelList[ollamaCursor]
+    const model = selectedModel?.id || ollamaModel.trim() || 'llama3.2'
     try {
       writeConfigFile('ollama', model, 'ollama-local')
       onComplete({ providerId: 'ollama', modelId: model, apiKey: 'ollama-local' })
@@ -249,6 +329,24 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
       return
     }
 
+    // ── Ollama model selection ──
+    if (step === 'ollama') {
+      if (ollamaModelList.length === 0) return
+      if (key.upArrow) {
+        setOllamaCursor((c) => (c > 0 ? c - 1 : ollamaModelList.length - 1))
+        return
+      }
+      if (key.downArrow) {
+        setOllamaCursor((c) => (c < ollamaModelList.length - 1 ? c + 1 : 0))
+        return
+      }
+      if (key.return) {
+        goStep('confirm')
+        return
+      }
+      return
+    }
+
     // ── Confirm ──
     if (step === 'confirm') {
       if (key.return) {
@@ -261,8 +359,6 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
 
   // ── Render ──
 
-  const dim = 'gray'
-
   return (
     <Box flexDirection="column" padding={1}>
       {/* Header */}
@@ -404,29 +500,43 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
             <Box flexDirection="column" marginBottom={1}>
               <Text>
                 状态：{ollamaStatus.installed ? '✅ 已安装' : '❌ 未安装'}
-                {ollamaStatus.running ? ' · 运行中' : ''}
+                {ollamaStatus.running
+                  ? ' · 运行中'
+                  : ollamaStatus.installed
+                    ? ' · 未运行（请执行 ollama serve）'
+                    : ''}
               </Text>
-              {ollamaStatus.models.length > 0 && (
-                <Text dimColor>已下载模型：{ollamaStatus.models.join(', ')}</Text>
-              )}
             </Box>
           ) : (
             <Text dimColor>正在检测 Ollama...</Text>
           )}
+          {ollamaModelList.length > 0 && (
+            <Box flexDirection="column" marginBottom={1}>
+              <Box marginBottom={1}>
+                <Text dimColor>已下载模型（↑↓ 选择 · Enter 确认）：</Text>
+              </Box>
+              {ollamaModelList.map((m, i) => (
+                <Box key={m.id}>
+                  <Text color={i === ollamaCursor ? 'cyan' : undefined}>
+                    {i === ollamaCursor ? '▶' : '  '} {m.id}
+                  </Text>
+                  {m.source !== 'local' && (
+                    <Text dimColor> [{m.source === 'MiphamAI' ? 'MiphamAI' : '热门'}]</Text>
+                  )}
+                </Box>
+              ))}
+            </Box>
+          )}
+          {ollamaStatus && ollamaModelList.length === 0 && (
+            <Box marginBottom={1}>
+              <Text dimColor>
+                未检测到已下载模型。请先运行 ollama pull &lt;model&gt; 下载模型。
+              </Text>
+              <Text dimColor>以下为预置模型列表，选择后可在对话中通过 /models 切换。</Text>
+            </Box>
+          )}
           <Box marginTop={1}>
-            <Text dimColor>输入 Ollama 模型名称（如 llama3.2, qwen2.5, deepseek-r1）：</Text>
-          </Box>
-          <Box marginTop={1}>
-            <Text color="yellow">🖥️ </Text>
-            <TextInput
-              value={ollamaModel}
-              onChange={setOllamaModel}
-              onSubmit={() => goStep('confirm')}
-              placeholder="模型名，默认 llama3.2"
-            />
-          </Box>
-          <Box marginTop={1}>
-            <Text dimColor>Enter 继续 · Esc 返回</Text>
+            <Text dimColor>↑↓ 选择 · Enter 确认 · Esc 返回</Text>
           </Box>
         </Box>
       )}
@@ -449,7 +559,11 @@ export function ConfigWizard({ onComplete, onSkip }: Props) {
               </Text>
             </>
           )}
-          {mode === 'local' && <Text>Ollama 模型：{ollamaModel.trim() || 'llama3.2'}</Text>}
+          {mode === 'local' && (
+            <Text>
+              Ollama 模型：{ollamaModelList[ollamaCursor]?.id || ollamaModel.trim() || 'llama3.2'}
+            </Text>
+          )}
           <Box marginTop={1}>
             <Text dimColor>配置文件将保存到 ~/.mipham/config.yml</Text>
           </Box>

package/src/ui/picker.tsx

@@ -8,6 +8,7 @@ interface PickerProps {
   currentProvider: string
   currentModel: string
   onSelect: (providerId: string, modelId: string) => void
+  onNeedsApiKey?: (providerId: string, modelId: string, providerName: string) => void
   onClose: () => void
 }
 
@@ -18,6 +19,7 @@ export function ModelPicker({
   currentProvider,
   currentModel,
   onSelect,
+  onNeedsApiKey,
   onClose,
 }: PickerProps) {
   const { t } = useI18n()
@@ -60,9 +62,17 @@ export function ModelPicker({
     if (!selectedProvider) return
     const model = models[modelIdx]
     if (model) {
+      // Check API key before confirming switch
+      const apiKey = selectedProvider.apiKey
+      if (!apiKey || apiKey.trim() === '' || /^\$\{[A-Z_]+\}$/.test(apiKey.trim())) {
+        if (selectedProvider.id !== 'ollama' && onNeedsApiKey) {
+          onNeedsApiKey(selectedProvider.id, model.id, selectedProvider.name)
+          return
+        }
+      }
       onSelect(selectedProvider.id, model.id)
     }
-  }, [selectedProvider, models, modelIdx, onSelect])
+  }, [selectedProvider, models, modelIdx, onSelect, onNeedsApiKey])
 
   useInput((input, key) => {
     // Global keys