zen-gitsync 2.16.9 → 2.16.11

package/README.md

@@ -437,6 +437,11 @@ $ g ai "fix the failing test"   # one-shot task, then exit
 $ g ai --model=2                # pick the 2nd configured model (index or name)
 ```
 
+The first-run setup wizard and `/addmodel` provider/model lists support **↑↓ keys to switch
+selection + Enter to confirm** (typing a number also jumps directly; `0` selects the trailing
+"custom / manual input" entry). Non-TTY environments (CI, piped input) automatically fall back
+to numeric input. `Esc` or `Ctrl+C` cancels the wizard cleanly.
+
 In-session commands: `/help`, `/model`, `/addmodel`, `/cd <path>`, `/image [path]`, `/think`, `/clear`, `/exit`.
 
 Images: press `Alt+V` in the REPL to paste a clipboard image (screenshot), or attach a
@@ -966,6 +971,10 @@ $ g ai "修复失败的测试"           # 单发模式：执行一轮后退出
 $ g ai --model=2                # 使用第 2 个已配置的模型（序号或名称）
 ```
 
+启动配置向导与 `/addmodel` 的"服务商 / 模型"列表支持 **↑↓ 键切换 + Enter 确认**（也可
+直接输入数字跳转，`0` = 列表底部的"自定义 / 手动输入"）；非 TTY 环境下自动回退为数字输入。
+`Esc` 或 `Ctrl+C` 一键取消整个向导。
+
 会话内命令：`/help`、`/model`、`/addmodel`、`/cd <路径>`、`/image [路径]`、`/think`、`/clear`、`/exit`。
 
 图片：在 REPL 中按 `Alt+V` 粘贴剪贴板图片（截图），或用 `/image <路径>` 附加本地图片；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-gitsync",
-  "version": "2.16.9",
+  "version": "2.16.11",
   "description": "Auto commit, scheduled sync, and visual GUI for Git. Run `g` in any repo for one-key commit & push, AI commit messages, scheduled background sync, and a drag-and-drop workflow builder.",
   "main": "index.js",
   "type": "module",

package/src/cli/ai/agent.js

@@ -49,9 +49,10 @@ import { TOOL_DEFINITIONS, executeTool } from './tools.js'
 import { createThinkFilter } from './streamFilter.js'
 import {
   printBanner, printHelpPanel,
-  filterSlashCommands, renderSlashHintBody,
+  filterSlashCommands, renderSlashHintBody, parseKeyForSlashHint,
   startSpinner, createAssistantWriter,
   summarizeToolArgs, printToolHeader, printToolResult,
+  formatDuration,
   printOk, printWarn, printError, printDim,
 } from './termui.js'
 import { readClipboardImage, checkImageFile, imageToDataUrl, formatBytes } from './images.js'
@@ -488,6 +489,7 @@ async function runAgentTurn(state, userText, t, images = []) {
     // 发送前消毒:确保历史里没有空 content 的消息(部分 provider 报 2013)
     sanitizeMessages(state.messages)
 
+    const llmStart = performance.now()
     let result
     try {
       result = await streamChatOnce({
@@ -512,6 +514,7 @@ async function runAgentTurn(state, userText, t, images = []) {
       if (last?.role === 'user') state.messages.pop()
       return
     }
+    const llmDuration = performance.now() - llmStart
     stopSpinner()
     writer.finish()
 
@@ -532,6 +535,11 @@ async function runAgentTurn(state, userText, t, images = []) {
     // content 为 null 而非空字符串:部分 provider 拒绝空字符串内容(2013 错误)
     state.messages.push({ role: 'assistant', content: content || null, tool_calls: toolCalls })
 
+    // LLM 耗时在进入工具执行前打印(仅本轮有工具调用时显示)
+    if (llmDuration > 0) {
+      printDim(`  ⏱ LLM ${formatDuration(llmDuration)}`)
+    }
+
     for (const tc of toolCalls) {
       const name = tc.function?.name || ''
       const rawArgs = tc.function?.arguments || ''
@@ -550,9 +558,11 @@ async function runAgentTurn(state, userText, t, images = []) {
       printToolHeader(name, summarizeToolArgs(name, args, { chars: t.chars }))
       // 长命令执行期间给个 spinner,让用户知道没有卡死
       const toolSpinner = startSpinner(t.toolRunning(name))
+      const toolStart = performance.now()
       const output = await executeTool(name, args, state.ctx)
+      const toolDuration = performance.now() - toolStart
       toolSpinner.stop()
-      printToolResult(output)
+      printToolResult(output, undefined, toolDuration)
       state.messages.push({ role: 'tool', tool_call_id: tc.id || name, name, content: output })
     }
     // 工具结果全部入历史后继续循环,让模型基于结果决定下一步
@@ -923,10 +933,16 @@ export async function runAiAgent(argv = []) {
     if (!state.busy) safeShowPrompt()
   }
 
-  // ── 斜杠命令即时提示 ──
+  // ── 斜杠命令即时提示(支持 ↑↓ 切换 / Tab 补全 / Enter 提交) ──
   // 在提示符下方浮现匹配到的命令,随输入过滤;不移动光标(用 DECSC/DECRC 保存-恢复)。
   // slashHintRows 记录当前提示占了几行,下次刷新/提交时据此擦除,避免残影。
+  // slashHintBaseLine:本次 hint 显示时"输入行的基线值" — ↑↓ 时 readline 已经把
+  //   rl.line 改成历史上一行,我们用基线回滚 + _refreshLine() 重绘,让用户视觉上看
+  //   不到"按 ↑ 输入行变了",只看到 hint 高亮跳了一格。
   let slashHintRows = 0
+  let slashHintBaseLine = ''
+  let slashHintMatches = []
+  let slashHintIndex = 0
   const eraseSlashHint = () => {
     if (!process.stdout.isTTY || slashHintRows === 0) return
     // 保存光标 → 下移到提示区逐行清空 → 恢复光标
@@ -936,11 +952,8 @@ export async function runAiAgent(argv = []) {
     process.stdout.write(seq)
     slashHintRows = 0
   }
-  const renderSlashHint = () => {
-    if (!process.stdout.isTTY || state.busy || state.inWizard) { return }
-    const matches = filterSlashCommands(rl.line, state.locale)
-    const body = renderSlashHintBody(matches)
-    // 先擦掉旧提示(行数可能变化),再画新的
+  const drawSlashHint = () => {
+    const body = renderSlashHintBody(slashHintMatches, slashHintIndex)
     eraseSlashHint()
     if (!body) return
     const rows = body.split('\n')
@@ -951,6 +964,42 @@ export async function runAiAgent(argv = []) {
     process.stdout.write(seq)
     slashHintRows = rows.length
   }
+  // 重置 hint 上下文:重新计算匹配 + 重画。输入字符变化时调用。
+  const refreshSlashHint = () => {
+    if (!process.stdout.isTTY || state.busy || state.inWizard) {
+      eraseSlashHint()
+      slashHintMatches = []
+      slashHintIndex = 0
+      slashHintBaseLine = ''
+      return
+    }
+    slashHintBaseLine = rl.line
+    slashHintMatches = filterSlashCommands(rl.line, state.locale)
+    // 匹配列表缩短时夹紧 index(增删交替时不会越界)
+    slashHintIndex = slashHintIndex < slashHintMatches.length ? slashHintIndex : 0
+    drawSlashHint()
+  }
+  // ↑↓ / Shift+Tab:readline 已经把 rl.line 改成历史行或没动 → 强制恢复基线并重绘输入行
+  const restoreInputLineToBaseline = () => {
+    if (rl.line === slashHintBaseLine) return
+    rl.line = slashHintBaseLine
+    rl.cursor = slashHintBaseLine.length
+    if (typeof rl._refreshLine === 'function') rl._refreshLine()
+  }
+  // Tab / Enter:把 rl.line 替换为补全文本 + 清掉 hint 状态
+  //   Tab:补全文本末尾加空格,便于用户继续打参数(不回车)
+  //   Enter:不用此函数 — 用 state.slashHintSubmitLine 标志 + line handler 替换
+  //     (readline 自己处理 Enter,我们不能事后改 rl.line 触发提交)
+  const applyHintCompletion = (newLine) => {
+    rl.line = newLine
+    rl.cursor = newLine.length
+    eraseSlashHint()
+    slashHintMatches = []
+    slashHintIndex = 0
+    slashHintRows = 0
+    slashHintBaseLine = newLine
+    if (typeof rl._refreshLine === 'function') rl._refreshLine()
+  }
 
   // Alt+V 粘贴剪贴板图片(node 把 ESC+v 解析为 meta+v;部分终端不发 Alt,可用 /image 兜底)
   const pasteFromClipboard = async () => {
@@ -973,14 +1022,73 @@ export async function runAiAgent(argv = []) {
     }
   }
   rl.input.on('keypress', (ch, key) => {
-    // Enter 提交由 line 处理器负责擦除提示,这里不重画(此刻 readline 已换行,
-    // 光标不在输入行,重画会错位)
-    if (!(key && (key.name === 'return' || key.name === 'enter'))) {
-      // 每次按键后即时刷新斜杠命令提示(readline 已先处理完本次按键,rl.line 为最新值)。
-      // 非 slash / 无匹配时 renderSlashHint 会把上一次的提示擦掉。
-      renderSlashHint()
-    }
     if (!key) return
+
+    // ── 斜杠命令提示专用键盘:↑↓/Tab/Enter/Shift+Tab/Esc ──
+    // 仅在 hint 已显示且有匹配项时拦截,readline 的 default 行为(历史浏览等)
+    // 我们在 handler 里事后回滚 rl.line 来抵消
+    const action = parseKeyForSlashHint(key)
+    const hintActive = action === 'prev' || action === 'next' || action === 'complete' || action === 'submit' || action === 'cancel'
+      ? (slashHintRows > 0 && slashHintMatches.length > 0 && !state.busy && !state.inWizard)
+      : false
+
+    if (hintActive) {
+      if (action === 'prev' || action === 'next') {
+        const n = slashHintMatches.length
+        slashHintIndex = action === 'prev'
+          ? (slashHintIndex - 1 + n) % n
+          : (slashHintIndex + 1) % n
+        restoreInputLineToBaseline()
+        drawSlashHint()
+        return   // 不再走 default update + Alt+V 分支
+      }
+      if (action === 'complete') {
+        // Tab:把输入行替换为选中命令 + 末尾空格(便于继续打参数),
+        // 光标跳到末尾;之后不再触发 hint(已经精确选了某个命令)
+        const sel = slashHintMatches[slashHintIndex]
+        const newLine = sel.cmd + ' '
+        applyHintCompletion(newLine)
+        return
+      }
+      if (action === 'submit') {
+        // Enter:把 rl.line 替换为补全命令,然后手动调用 rl._line() 触发 line 事件。
+        // 这样提交的就是补全后的命令,而不是用户敲到一半的前缀。
+        // 必须 return — 否则 readline 自己也会按 Enter 把当前 rl.line(用户原始输入) 提交一遍。
+        const sel = slashHintMatches[slashHintIndex]
+        const newLine = sel.cmd
+        console.error('[DEBUG-ENTER] sel.cmd=' + JSON.stringify(sel.cmd) + ' rl.line before=' + JSON.stringify(rl.line))
+        rl.line = newLine
+        rl.cursor = newLine.length
+        eraseSlashHint()
+        slashHintMatches = []
+        slashHintIndex = 0
+        slashHintRows = 0
+        slashHintBaseLine = newLine
+        if (typeof rl._refreshLine === 'function') rl._refreshLine()
+        // readline 的 _line() 内部会 this.emit('line', this.line) — 用补全后的 line
+        if (typeof rl._line === 'function') {
+          try { rl._line(); console.error('[DEBUG-ENTER] _line ok, rl.line after=' + JSON.stringify(rl.line)) } catch (e) { console.error('[DEBUG-ENTER] _line err: ' + e.message); rl.emit('line', newLine) }
+        } else {
+          rl.emit('line', newLine)
+        }
+        return
+      }
+      if (action === 'cancel') {
+        // Esc:只清 hint,不动输入行
+        eraseSlashHint()
+        slashHintMatches = []
+        slashHintIndex = 0
+        return
+      }
+    }
+
+    // submit(Enter)走默认 readline 提交,line 事件里统一擦除 hint;
+    // 其他普通按键:重算匹配 + 重画 hint
+    if (!(key.name === 'return' || key.name === 'enter')) {
+      refreshSlashHint()
+    }
+
+    // Alt+V 粘贴剪贴板图片(node 把 ESC+v 解析为 meta+v;部分终端不发 Alt,可用 /image 兜底)
     const isAltV = (key.meta && key.name === 'v')
       || (typeof key.sequence === 'string' && key.sequence.length === 2
           && key.sequence.charCodeAt(0) === 27 && key.sequence[1] === 'v')

package/src/cli/ai/modelSetup.js

@@ -22,8 +22,8 @@
 //   1. 询问是否现在配置
 //   2. 选择服务商(预设列表 / 自定义)
 //   3. 确认接口地址(baseURL)
-//   4. 选择模型名称(常用模型列表 / 手动输入)
-//   5. 输入 API Key(本地模型可留空)
+//   4. 输入 API Key(本地模型可留空)
+//   5. 选择模型名称(先从 API 获取模型列表,失败则用内置列表 / 手动输入)
 //   6. 输入显示名称(可选)
 //   7. 测试连接
 //   8. 保存到配置文件并返回模型对象
@@ -34,7 +34,7 @@
 import readline from 'node:readline'
 import chalk from 'chalk'
 import config from '../../config.js'
-import { startSpinner } from './termui.js'
+import { startSpinner, renderSelectableListBody, parseKeyForSelectableList } from './termui.js'
 
 // ──────────────────────────────────────────────
 // 预设服务商列表
@@ -131,12 +131,15 @@ const STRINGS = {
     selectProvider: '选择 AI 服务商:',
     customOption: '自定义',
     selectPrompt: (min, max) => `请选择 (${min}-${max}): `,
+    navHint: '↑↓ 切换,Enter 确认,数字直跳(0 = 上一行)',
     invalidChoice: (min, max) => `无效选择,请输入 ${min}-${max} 之间的数字`,
     endpointLabel: '接口地址',
     endpointPrompt: (def) => `接口地址 [${def}]: `,
     endpointInvalid: '接口地址格式不正确(需为 http/https URL)',
     modelLabel: '模型名称',
     builtinModels: '常用模型:',
+    fetchingModels: '正在获取模型列表…',
+    fetchModelsFailed: '获取模型列表失败,使用内置列表',
     manualInput: '手动输入',
     modelPrompt: '请输入模型名称: ',
     modelRequired: '模型名称不能为空',
@@ -164,12 +167,15 @@ const STRINGS = {
     selectProvider: 'Select an AI provider:',
     customOption: 'Custom',
     selectPrompt: (min, max) => `Choose (${min}-${max}): `,
+    navHint: '↑↓ to switch, Enter to confirm, number to jump (0 = extra)',
     invalidChoice: (min, max) => `Invalid choice, enter a number between ${min} and ${max}`,
     endpointLabel: 'Endpoint URL',
     endpointPrompt: (def) => `Endpoint [${def}]: `,
     endpointInvalid: 'Invalid endpoint URL (must be http/https)',
     modelLabel: 'Model name',
     builtinModels: 'Popular models:',
+    fetchingModels: 'Fetching model list…',
+    fetchModelsFailed: 'Failed to fetch model list, using built-in list',
     manualInput: 'Manual input',
     modelPrompt: 'Enter model name: ',
     modelRequired: 'Model name cannot be empty',
@@ -259,6 +265,48 @@ export function buildModelConfig({ baseURL, model, apiKey, name, isDefault }) {
   }
 }
 
+/**
+ * 从 API 获取可用模型列表(OpenAI 兼容 /models 接口)。
+ *
+ * @param {object} opts
+ * @param {string} opts.baseURL - API 基础地址
+ * @param {string} [opts.apiKey] - API Key(可选)
+ * @param {number} [opts.timeoutMs=5000] - 超时时间
+ * @param {typeof fetch} [opts.fetchFn] - 可注入 fetch(测试用)
+ * @returns {Promise<string[]>} 模型名数组,失败返回空数组
+ */
+export async function fetchModelsFromApi({ baseURL, apiKey, timeoutMs = 5000, fetchFn } = {}) {
+  const fetch = fetchFn || globalThis.fetch
+  if (!fetch) return []
+
+  const url = `${String(baseURL || '').replace(/\/$/, '')}/models`
+  const headers = {}
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+    })
+
+    if (!res.ok) return []
+
+    const data = await res.json()
+    // OpenAI 兼容接口返回 { data: [{ id: 'model-name', ... }] }
+    const models = data?.data || []
+    return models.map(m => m.id).filter(Boolean)
+  } catch (err) {
+    // 任何错误都静默返回空数组,由调用方决定是否回退
+    return []
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 /**
  * 测试模型连接(OpenAI 兼容 /chat/completions)。
  *
@@ -367,32 +415,201 @@ async function askYesNo(asker, prompt) {
 }
 
 /**
- * 让用户从数字列表中选择一项。
- * @param {object} asker
- * @param {string} title - 列表标题
- * @param {Array<{label: string, value: any}>} items
- * @param {object} t - i18n strings
- * @param {number} [extraOption] - 额外选项的序号(如"手动输入"用 0)
- * @param {string} [extraLabel]
- * @returns {Promise<{index: number, value: any}|null>} 选中的项,null = 用户选了额外选项
+ * 让用户从列表中选择一项。
+ *
+ * 两条路径:
+ *   - TTY(终端)且传入了 rl → 上下键切换 + Enter 提交(类似 Codex CLI 的列表选择)
+ *     - 数字键 1..9 / 0 也可直跳(0 = 额外项)
+ *     - Esc / Ctrl+C 视作取消整个 wizard(调用方按 { cancelled: true } 走 catch 分支)
+ *   - 其他情况 → 回退到原数字输入(由 asker.ask 提示,数字 + 回车确认;非法输入不退出,
+ *     提示 t.invalidChoice 让用户重新输)
+ *
+ * 设计要点:
+ *   - 列表用 renderSelectableListBody 渲染,选中行整行反白(可视化锚点固定,跟斜杠命令
+ *     提示一样的"反白起点严格对齐"思路)
+ *   - 方向键会触发 readline 默认历史浏览,我们用"清空 rl.line + 调 _refreshLine"撤销
+ *     (参考 agent.js 对斜杠命令提示的处理)
+ *   - 按 Enter 时 rl.question 回调自然拿到 line 字符串;空字符串 → 用当前 selectedIndex,
+ *     数字 → 直接选中,非数字 → 视为无效,保持当前列表继续等待输入(不重画列表)
+ *
+ * @param {object} opts
+ * @param {import('node:readline').Interface} [opts.rl] - 用于挂 keypress + rl.question;
+ *   不传或非 TTY 时退回数字输入
+ * @param {{ask:(p:string,d?:string)=>Promise<string>}} opts.asker - 数字输入回退路径的 asker;
+ *   TTY 路径不需要,但参数签名上必须传(避免 collectModelInput 内部拆开两个调用)
+ * @param {string} opts.title
+ * @param {Array<{label: string, value: any}>} opts.items
+ * @param {object} opts.t - i18n strings
+ * @param {string} [opts.extraOptionLabel] - 额外项(编号 0)
+ * @returns {Promise<{index: number, value: any}|null>}
+ *   - { index, value }:选中标准项
+ *   - null:选中额外项
+ *   - 抛出 { cancelled: true }:用户取消整个 wizard(Ctrl+C / Esc / readline close)
  */
-async function selectFromList(asker, title, items, t, extraOptionLabel) {
+async function selectFromList({ rl, asker, title, items, t, extraOptionLabel } = {}) {
+  const safeItems = Array.isArray(items) ? items : []
+  const extraActive = !!extraOptionLabel
+  const totalItems = safeItems.length + (extraActive ? 1 : 0)
+  if (totalItems === 0) return null
+
   console.log()
   console.log(chalk.bold(title))
+
+  // 判断走哪条路
+  const interactive = !!(rl && rl.input && process.stdout.isTTY && process.stdin.isTTY)
+
+  if (!interactive) {
+    // 非 TTY / 没 rl:走数字输入回退(原行为,保留 CI / 管道环境的可脚本化能力)
+    return selectByDigits({ asker, items: safeItems, t, extraOptionLabel })
+  }
+
+  // ── TTY 路径:方向键列表选择 ──
+  let selectedIndex = 0
+  let finished = false
+
+  // 渲染初始列表
+  const initialBody = renderSelectableListBody(safeItems, 0, extraOptionLabel)
+  process.stdout.write(initialBody + '\n')
+  const listRows = initialBody.split('\n').length
+
+  /**
+   * 重画列表:用 ANSI 把光标逐行上移 + 清行,然后重新打印,光标回到列表首行行首,
+   * 不影响 readline 在 listRows+1 行的 prompt 行。
+   * 用 \x1b[2K(清整行)+ \x1b[1A(上移一行)循环 N 次,等价于
+   * "清掉光标以上 N 行"但不污染更下面的内容;最后 \r 回到行首方便后续输出起点对齐。
+   */
+  const redraw = () => {
+    for (let i = 0; i < listRows; i++) {
+      process.stdout.write('\x1b[1A\x1b[2K')
+    }
+    process.stdout.write('\r')
+    process.stdout.write(renderSelectableListBody(safeItems, selectedIndex, extraOptionLabel) + '\n')
+  }
+
+  /**
+   * 撤销 readline 内置行为对 rl.line 的副作用:
+   *   - 方向键:readline 读 history 一条回填到 rl.line + _refreshLine 重画 prompt
+   *     用户本来在 prompt 行没敲任何字符,历史回填会让用户突然看到历史的脏字符。
+   *     所以清空 line buffer 让 prompt 行保持空(类似 agent.js 对斜杠命令提示的做法)。
+   *   - 数字键(jump:N):用户在 prompt 行确实敲了数字,该数字已经在 rl.line 里,
+   *     不能撤销(否则用户按 "8" 看不到 "8")— 但目前的 jump 路径用 rl.line.length === 0 守门,
+   *     等于已经避免和 readline 的字符输入重叠,所以 prev/next 路径才需要清,数字路径不用清。
+   */
+  const clearLineBuffer = () => {
+    if (!rl) return
+    rl.line = ''
+    rl.cursor = 0
+    if (typeof rl._refreshLine === 'function') {
+      try { rl._refreshLine() } catch { /* 兜底 — 某些 readline 版本没有 _refreshLine */ }
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      if (finished) return
+      finished = true
+      if (rl && rl.input) rl.input.removeListener('keypress', keyHandler)
+      if (rl) rl.removeListener('close', onClose)
+    }
+    const onClose = () => {
+      cleanup()
+      reject({ cancelled: true })
+    }
+
+    const keyHandler = (_str, key) => {
+      if (finished || !key) return
+      const action = parseKeyForSelectableList(key)
+      const max = totalItems - 1
+
+      if (action === 'prev' || action === 'next') {
+        if (action === 'prev') {
+          selectedIndex = selectedIndex > 0 ? selectedIndex - 1 : max
+        } else {
+          selectedIndex = selectedIndex < max ? selectedIndex + 1 : 0
+        }
+        clearLineBuffer()   // 撤销 readline 历史回填
+        redraw()
+        return
+      }
+
+      if (typeof action === 'string' && action.startsWith('jump:')) {
+        // 只在用户当前没敲字符时接受 jump,避免和 readline 正常字符输入冲突
+        if (rl.line && rl.line.length > 0) return
+        const n = Number(action.slice(5))
+        let target = -1
+        if (n === 0 && extraActive) target = safeItems.length
+        else if (n >= 1 && n <= safeItems.length) target = n - 1
+        if (target >= 0) {
+          selectedIndex = target
+          redraw()   // 数字已进 rl.line,不清;用户会看到 prompt 行同步显示这个数字
+        }
+        return
+      }
+
+      if (action === 'cancel') {
+        // Esc / Ctrl+C — 让用户取消整个 wizard
+        cleanup()
+        reject({ cancelled: true })
+        return
+      }
+
+      // 'confirm' (Enter) 不处理,让 readline 自然触发 line 事件 → rl.question 回调拿 answer
+      // 其他字符(字母/数字但 line buffer 非空)让 readline 自然处理
+    }
+
+    rl.input.on('keypress', keyHandler)
+    rl.once('close', onClose)
+
+    // 提示词:列出可选范围 + 导航提示
+    const minIdx = extraActive ? 0 : 1
+    const maxIdx = safeItems.length
+    const navHint = t.navHint  // "↑↓ 切换,Enter 确认,数字直跳"
+    const promptStr = `${chalk.cyan(t.selectPrompt(minIdx, maxIdx))}${chalk.dim(navHint ? '  ' + navHint : '')} `
+
+    rl.question(promptStr, (answer) => {
+      cleanup()
+      const trimmed = (answer || '').trim()
+      let idx = Number.parseInt(trimmed, 10)
+      if (Number.isFinite(idx) && idx >= minIdx && idx <= maxIdx) {
+        if (idx === 0) return resolve(null)
+        return resolve({ index: idx - 1, value: safeItems[idx - 1].value })
+      }
+      if (trimmed === '') {
+        // 空回答:用当前 selectedIndex
+        if (selectedIndex >= safeItems.length) return resolve(null)
+        return resolve({ index: selectedIndex, value: safeItems[selectedIndex].value })
+      }
+      // 非法输入:在当前列表下方打印提示,不重画列表(列表还在可见)
+      console.log(chalk.yellow(t.invalidChoice(minIdx, maxIdx)))
+      resolve('__retry__')
+    })
+  }).then(async (r) => {
+    if (r === '__retry__') {
+      // 递归重试(重新调一次)— 列表会再画一遍,实测可接受;保持 wizard 流程的简洁
+      return selectFromList({ rl, asker, title, items, t, extraOptionLabel })
+    }
+    return r
+  })
+}
+
+/**
+ * 数字输入回退路径(原 selectFromList 的实现)。
+ * 保留给非 TTY / 无 readline 的场景(管道、CI、测试)。
+ */
+async function selectByDigits({ asker, items, t, extraOptionLabel }) {
   items.forEach((item, i) => {
     console.log(`  ${chalk.cyan(String(i + 1).padStart(2))}. ${item.label}`)
   })
   if (extraOptionLabel) {
     console.log(`  ${chalk.dim('0')}. ${chalk.dim(extraOptionLabel)}`)
   }
-
   const min = extraOptionLabel ? 0 : 1
   const max = items.length
   while (true) {
     const answer = await asker.ask(t.selectPrompt(min, max))
     const idx = Number.parseInt(answer, 10)
     if (Number.isFinite(idx) && idx >= min && idx <= max) {
-      if (idx === 0) return null // 额外选项
+      if (idx === 0) return null
       return { index: idx - 1, value: items[idx - 1].value }
     }
     console.log(chalk.yellow(t.invalidChoice(min, max)))
@@ -435,7 +652,13 @@ export async function collectModelInput({ locale = 'zh-CN', rl: injectedRl, fetc
       label: `${p.label} ${chalk.dim(p.url)}`,
       value: p,
     }))
-    const providerChoice = await selectFromList(asker, t.selectProvider, providerItems, t, t.customOption)
+    const providerChoice = await selectFromList({
+      rl, asker,
+      title: t.selectProvider,
+      items: providerItems,
+      t,
+      extraOptionLabel: t.customOption,
+    })
 
     let baseURL
     if (providerChoice) {
@@ -463,12 +686,32 @@ export async function collectModelInput({ locale = 'zh-CN', rl: injectedRl, fetc
       baseURL = confirmedBaseURL
     }
 
-    // 3. 选择/输入模型名称
-    const builtin = getBuiltinModels(baseURL)
+    // 3. 输入 API Key(在获取模型列表之前,因为大部分服务商需要 Key 才能调 /models)
+    const apiKey = await asker.ask(t.apiKeyPrompt)
+
+    // 4. 选择/输入模型名称
+    // 先尝试从 API 获取模型列表(有了 apiKey 才能调通)
+    const fetchSpinner = startSpinner(t.fetchingModels)
+    const fetchedModels = await fetchModelsFromApi({ baseURL, apiKey, fetchFn })
+    fetchSpinner.stop()
+
+    // 使用 API 返回的模型列表,如果失败则使用内置列表
+    const modelList = fetchedModels.length > 0 ? fetchedModels : getBuiltinModels(baseURL)
+
+    if (fetchedModels.length === 0 && getBuiltinModels(baseURL).length > 0) {
+      console.log(chalk.dim(`  ${t.fetchModelsFailed}`))
+    }
+
     let model
-    if (builtin.length > 0) {
-      const modelItems = builtin.map(m => ({ label: m, value: m }))
-      const modelChoice = await selectFromList(asker, t.builtinModels, modelItems, t, t.manualInput)
+    if (modelList.length > 0) {
+      const modelItems = modelList.map(m => ({ label: m, value: m }))
+      const modelChoice = await selectFromList({
+        rl, asker,
+        title: t.builtinModels,
+        items: modelItems,
+        t,
+        extraOptionLabel: t.manualInput,
+      })
       if (modelChoice) {
         model = modelChoice.value
       } else {
@@ -480,7 +723,7 @@ export async function collectModelInput({ locale = 'zh-CN', rl: injectedRl, fetc
         }
       }
     } else {
-      // 没有预设模型,直接手动输入
+      // 没有模型列表,直接手动输入
       while (true) {
         model = await asker.ask(t.modelPrompt)
         if (model) break
@@ -488,9 +731,6 @@ export async function collectModelInput({ locale = 'zh-CN', rl: injectedRl, fetc
       }
     }
 
-    // 4. 输入 API Key
-    const apiKey = await asker.ask(t.apiKeyPrompt)
-
     // 5. 输入显示名称(默认用 model 名)
     const displayName = await asker.ask(t.displayNamePrompt(model), model)
 
@@ -591,4 +831,4 @@ export async function runModelSetup({ locale = 'zh-CN', rl: injectedRl, fetchFn
   }
 }
 
-export default { runModelSetup, collectModelInput, testModelConnection, getBuiltinModels, findProviderByUrl, validateEndpoint, buildModelConfig, PROVIDERS, BUILTIN_MODELS }
+export default { runModelSetup, collectModelInput, fetchModelsFromApi, testModelConnection, getBuiltinModels, findProviderByUrl, validateEndpoint, buildModelConfig, PROVIDERS, BUILTIN_MODELS }