zen-gitsync 2.16.10 → 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.10",
+  "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/modelSetup.js

@@ -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,6 +131,7 @@ const STRINGS = {
     selectProvider: '选择 AI 服务商:',
     customOption: '自定义',
     selectPrompt: (min, max) => `请选择 (${min}-${max}): `,
+    navHint: '↑↓ 切换,Enter 确认,数字直跳(0 = 上一行)',
     invalidChoice: (min, max) => `无效选择,请输入 ${min}-${max} 之间的数字`,
     endpointLabel: '接口地址',
     endpointPrompt: (def) => `接口地址 [${def}]: `,
@@ -166,6 +167,7 @@ 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}]: `,
@@ -413,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)))
@@ -481,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) {
@@ -528,7 +705,13 @@ export async function collectModelInput({ locale = 'zh-CN', rl: injectedRl, fetc
     let model
     if (modelList.length > 0) {
       const modelItems = modelList.map(m => ({ label: m, value: m }))
-      const modelChoice = await selectFromList(asker, t.builtinModels, modelItems, t, t.manualInput)
+      const modelChoice = await selectFromList({
+        rl, asker,
+        title: t.builtinModels,
+        items: modelItems,
+        t,
+        extraOptionLabel: t.manualInput,
+      })
       if (modelChoice) {
         model = modelChoice.value
       } else {

package/src/cli/ai/sessionStore.js

@@ -1,97 +1,97 @@
-// Copyright 2026 xz333221
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-// CLI 侧智能体会话持久化。
-//
-// 与 Web 端 (src/ui/server/routes/workbench/agentSessionStore.js) 共享同一数据目录
-// (~/.zen-gitsync/agent-sessions/) 和同一 JSON 格式,这样:
-//   - CLI 对话在 Web UI 的智能体 tab 里可见(带 CLI 标记)
-//   - Web UI 可以读取/继续 CLI 创建的会话
-//
-// 本模块刻意不依赖服务器代码,仅用 node 内置 fs/path/os,保持 CLI 自包含。
-
-import fsp from 'fs/promises';
-import path from 'path';
-import os from 'os';
-
-const SESSIONS_DIR = path.join(os.homedir(), '.zen-gitsync', 'agent-sessions');
-const MAX_SESSIONS = 200;
-const KEEP_SESSIONS = 100;
-
-/**
- * 生成会话 ID: ag-{时间戳base36}-{随机base36}
- */
-export function genSessionId() {
-  return `ag-${Date.now().toString(36).slice(-8)}-${Math.random().toString(36).slice(2, 10)}`;
-}
-
-/**
- * 从第一条 user 消息自动生成标题(取第一行,截断 40 字符)
- */
-export function autoTitle(messages) {
-  for (const m of messages) {
-    if (m.role === 'user') {
-      let text = '';
-      if (typeof m.content === 'string') {
-        text = m.content;
-      } else if (Array.isArray(m.content)) {
-        text = m.content.filter(p => p?.type === 'text').map(p => p.text).join(' ');
-      }
-      text = text.trim();
-      if (text) {
-        const firstLine = text.split('\n')[0].trim();
-        return firstLine.length > 40 ? firstLine.slice(0, 40) + '…' : firstLine;
-      }
-    }
-  }
-  return '(新会话)';
-}
-
-/**
- * 写入会话(原子操作: tmp + rename)
- */
-export async function writeSession(sessionId, data) {
-  await fsp.mkdir(SESSIONS_DIR, { recursive: true });
-  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
-  const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
-  await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf-8');
-  await fsp.rename(tmp, file);
-}
-
-/**
- * 读取会话
- */
-export async function readSession(sessionId) {
-  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
-  return JSON.parse(await fsp.readFile(file, 'utf-8'));
-}
-
-/**
- * 保留策略:超过 MAX_SESSIONS 时删最旧的,保留 KEEP_SESSIONS 个
- */
-export async function enforceRetention() {
-  const files = await fsp.readdir(SESSIONS_DIR).catch(() => []);
-  const jsonFiles = files.filter(f => f.endsWith('.json'));
-  if (jsonFiles.length < MAX_SESSIONS) return;
-  const stats = await Promise.all(jsonFiles.map(async f => {
-    const full = path.join(SESSIONS_DIR, f);
-    const s = await fsp.stat(full);
-    return { file: full, mtime: s.mtimeMs };
-  }));
-  stats.sort((a, b) => b.mtime - a.mtime);
-  const toDelete = stats.slice(KEEP_SESSIONS);
-  await Promise.all(toDelete.map(s => fsp.unlink(s.file).catch(() => {})));
-}
-
-export { SESSIONS_DIR };
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// CLI 侧智能体会话持久化。
+//
+// 与 Web 端 (src/ui/server/routes/workbench/agentSessionStore.js) 共享同一数据目录
+// (~/.zen-gitsync/agent-sessions/) 和同一 JSON 格式,这样:
+//   - CLI 对话在 Web UI 的智能体 tab 里可见(带 CLI 标记)
+//   - Web UI 可以读取/继续 CLI 创建的会话
+//
+// 本模块刻意不依赖服务器代码,仅用 node 内置 fs/path/os,保持 CLI 自包含。
+
+import fsp from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+const SESSIONS_DIR = path.join(os.homedir(), '.zen-gitsync', 'agent-sessions');
+const MAX_SESSIONS = 200;
+const KEEP_SESSIONS = 100;
+
+/**
+ * 生成会话 ID: ag-{时间戳base36}-{随机base36}
+ */
+export function genSessionId() {
+  return `ag-${Date.now().toString(36).slice(-8)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * 从第一条 user 消息自动生成标题(取第一行,截断 40 字符)
+ */
+export function autoTitle(messages) {
+  for (const m of messages) {
+    if (m.role === 'user') {
+      let text = '';
+      if (typeof m.content === 'string') {
+        text = m.content;
+      } else if (Array.isArray(m.content)) {
+        text = m.content.filter(p => p?.type === 'text').map(p => p.text).join(' ');
+      }
+      text = text.trim();
+      if (text) {
+        const firstLine = text.split('\n')[0].trim();
+        return firstLine.length > 40 ? firstLine.slice(0, 40) + '…' : firstLine;
+      }
+    }
+  }
+  return '(新会话)';
+}
+
+/**
+ * 写入会话(原子操作: tmp + rename)
+ */
+export async function writeSession(sessionId, data) {
+  await fsp.mkdir(SESSIONS_DIR, { recursive: true });
+  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
+  const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
+  await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf-8');
+  await fsp.rename(tmp, file);
+}
+
+/**
+ * 读取会话
+ */
+export async function readSession(sessionId) {
+  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
+  return JSON.parse(await fsp.readFile(file, 'utf-8'));
+}
+
+/**
+ * 保留策略:超过 MAX_SESSIONS 时删最旧的,保留 KEEP_SESSIONS 个
+ */
+export async function enforceRetention() {
+  const files = await fsp.readdir(SESSIONS_DIR).catch(() => []);
+  const jsonFiles = files.filter(f => f.endsWith('.json'));
+  if (jsonFiles.length < MAX_SESSIONS) return;
+  const stats = await Promise.all(jsonFiles.map(async f => {
+    const full = path.join(SESSIONS_DIR, f);
+    const s = await fsp.stat(full);
+    return { file: full, mtime: s.mtimeMs };
+  }));
+  stats.sort((a, b) => b.mtime - a.mtime);
+  const toDelete = stats.slice(KEEP_SESSIONS);
+  await Promise.all(toDelete.map(s => fsp.unlink(s.file).catch(() => {})));
+}
+
+export { SESSIONS_DIR };

package/src/cli/ai/termui.js

@@ -193,6 +193,96 @@ export function parseKeyForSlashHint(key) {
   return null
 }
 
+// ──────────────────────────────────────────────────
+// 交互式可选列表(供 modelSetup 等一次性向导使用:上下键切换 + Enter 提交)
+// ──────────────────────────────────────────────────
+//
+// 与 renderSlashHintBody 的差异:
+//   - 必须支持 Enter 提交(parseKeyForSlashHint 把它当 'submit',但那个由 readline 默认接管;
+//     可选列表场景下 wizard 自己消费 Enter,不能丢给 readline)
+//   - 多支持直接按数字 1..9/0 跳到指定项(给经常用键盘的用户省一趟 ↑↓)
+//   - Ctrl+C 在可选列表场景下与 Esc 等价(都视作取消)
+//
+// 渲染/解析都做成纯函数,wizard 内部(modelSetup.selectFromList)负责:
+//   - 调用 renderSelectableListBody 把列表写到屏幕
+//   - 在 rl.input 上挂 keypress 监听,把 readline 默认行为(历史浏览)回滚掉
+//   - 每次 selectedIndex 变化时,重绘列表(用 ANSI 把光标上移、清行、再写)
+
+/**
+ * 渲染可选项列表 body(纯函数,便于单测)。
+ *
+ *   - 标准项:`  [k]. label`(未选中)
+ *   - 选中项:`▶ [k]. label`(整行反白,含前缀空格,跟下方其它行起点对齐)
+ *   - 额外项:编号 0,dim 灰;选中时整行反白(与普通选中项视觉一致)
+ *
+ * @param {Array<{label: string, value: any}>} items
+ * @param {number} [selectedIndex=0] - 选中项下标;范围 [0, items.length+extra)
+ *   越界回退为 0(默认选第一项,避免空数组报错)
+ * @param {string|null} [extraOptionLabel=null] - 额外项(如"自定义" / "手动输入")
+ * @returns {string} body 字符串(不含末尾换行 — 由调用方控制)
+ */
+export function renderSelectableListBody(items, selectedIndex = 0, extraOptionLabel = null) {
+  const safeItems = Array.isArray(items) ? items : []
+  const extraActive = !!extraOptionLabel
+  const totalLen = safeItems.length + (extraActive ? 1 : 0)
+  // selectedIndex 越界时静默回退为 0(首次调用时通常如此)
+  if (!Number.isInteger(selectedIndex) || selectedIndex < 0 || selectedIndex >= totalLen) {
+    selectedIndex = 0
+  }
+  const rows = []
+  for (let i = 0; i < safeItems.length; i++) {
+    const num = String(i + 1).padStart(2)
+    const label = safeItems[i].label
+    if (i === selectedIndex) {
+      // 整行反白(含 '  ' 缩进) — 起点与未选中行严格对齐,不留左侧白边
+      rows.push(chalk.inverse(`  ${num}. ${label}`))
+    } else {
+      rows.push(`  ${chalk.cyan(num)}. ${label}`)
+    }
+  }
+  if (extraActive) {
+    const extraIdx = safeItems.length
+    if (extraIdx === selectedIndex) {
+      // extra 选中时也整行反白,这样高亮跨度统一(虽然 label 是 dim,但反白让它可读)
+      rows.push(chalk.inverse(`  ${chalk.dim('0')}. ${extraOptionLabel}`))
+    } else {
+      rows.push(`  ${chalk.dim('0')}. ${chalk.dim(extraOptionLabel)}`)
+    }
+  }
+  return rows.join('\n')
+}
+
+/**
+ * 解析 readline keypress 事件,识别"可选列表"专用键。
+ * 返回动作字符串(消费方据此改 selectedIndex 或提交);
+ * 不识别的键返回 null(让 readline 正常处理 — 但消费方应恢复 line buffer
+ * 防止方向键的历史浏览把当前输入覆盖)。
+ *
+ *   - ↑ / Shift+Tab  → 'prev'
+ *   - ↓              → 'next'
+ *   - Enter          → 'confirm'
+ *   - Esc / Ctrl+C   → 'cancel'
+ *   - 数字 0..9      → 'jump:N'(1-based;0 = extra option,需消费方映射)
+ *
+ * 与 parseKeyForSlashHint 的差别:
+ *   - 这里 Enter 直接是 'confirm'——wizard 不会让 readline 默认提交(否则进 line 事件
+ *     走 REPL 的命令分发,体验错乱);Esc / Ctrl+C 都是 'cancel';不支持 Tab 补全
+ *     (列表项不是命令片段,不需要补全语义)
+ */
+export function parseKeyForSelectableList(key) {
+  if (!key) return null
+  const name = key.name
+  if (name === 'up') return 'prev'
+  if (name === 'tab') return key.shift ? 'prev' : 'next'
+  if (name === 'down') return 'next'
+  if (name === 'return' || name === 'enter') return 'confirm'
+  if (name === 'escape') return 'cancel'
+  if (key.ctrl && name === 'c') return 'cancel'
+  // 数字键 0..9:readline keypress 事件的 key.name 会是该字符
+  if (typeof name === 'string' && /^[0-9]$/.test(name)) return `jump:${name}`
+  return null
+}
+
 /** 盒式帮助面板 */
 export function printHelpPanel(title, lines) {
   const body = [chalk.bold(title), ...lines].join('\n')
@@ -536,6 +626,8 @@ export default {
   filterSlashCommands,
   renderSlashHintBody,
   parseKeyForSlashHint,
+  renderSelectableListBody,
+  parseKeyForSelectableList,
   drawInputTop,
   drawInputBottom,
   inputBottomBorder,