zen-gitsync 2.16.8 → 2.16.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-gitsync",
-  "version": "2.16.8",
+  "version": "2.16.10",
   "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",
@@ -12,10 +12,10 @@
     "npm:publish": "npm publish --registry https://registry.npmjs.org/",
     "npm:whoami": "npm whoami --registry https://registry.npmjs.org/",
     "pull": "git pull",
-    "dev:server": "cross-env PORT=5545 nodemon server.js --no-open",
-    "dev:vue": "npm run install:vue && cd ./src/ui/client && npm run dev",
+    "dev:server": "cross-env ZEN_PERF=1 PORT=5545 nodemon server.js --no-open",
+    "dev:vue": "node scripts/ensure-client-deps.cjs && cd ./src/ui/client && cross-env ZEN_PERF=1 npm run dev",
     "install:vue": "cd ./src/ui/client && npm install",
-    "dev": "concurrently -n backend,vite -c blue,green \"npm:dev:server\" \"npm:dev:vue\"",
+    "dev": "concurrently -n backend,vite -c blue,green --prefix \"[{time}][{name}]\" --timestamp-format \"HH:mm:ss.SSS\" \"npm:dev:server\" \"npm:dev:vue\"",
     "dev:ping": "node scripts/dev-ping.cjs",
     "start:server:no-open": "node server.js --no-open",
     "start:vue": "cd ./src/ui/client && npm run dev",

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. 保存到配置文件并返回模型对象
@@ -137,6 +137,8 @@ const STRINGS = {
     endpointInvalid: '接口地址格式不正确(需为 http/https URL)',
     modelLabel: '模型名称',
     builtinModels: '常用模型:',
+    fetchingModels: '正在获取模型列表…',
+    fetchModelsFailed: '获取模型列表失败,使用内置列表',
     manualInput: '手动输入',
     modelPrompt: '请输入模型名称: ',
     modelRequired: '模型名称不能为空',
@@ -170,6 +172,8 @@ const STRINGS = {
     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 +263,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)。
  *
@@ -463,11 +509,25 @@ 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 }))
+    if (modelList.length > 0) {
+      const modelItems = modelList.map(m => ({ label: m, value: m }))
       const modelChoice = await selectFromList(asker, t.builtinModels, modelItems, t, t.manualInput)
       if (modelChoice) {
         model = modelChoice.value
@@ -480,7 +540,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 +548,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 +648,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 }

package/src/cli/ai/modelSetup.test.js

@@ -409,8 +409,8 @@ function silenceConsole() {
 test('collectModelInput: 预设服务商 + 内置模型 + 测试成功 → 返回收集的字段', async () => {
   const restore = silenceConsole()
   try {
-    // 答案:选 OpenAI(1) → 确认 baseURL(空=默认) → 选第一个模型(1) → apiKey → displayName(空=默认)
-    const rl = createMockRl(['1', '', '1', 'sk-test', ''])
+    // 答案:选 OpenAI(1) → 确认 baseURL(空=默认) → apiKey → 选第一个模型(1) → displayName(空=默认)
+    const rl = createMockRl(['1', '', 'sk-test', '1', ''])
     const result = await collectModelInput({
       locale: 'zh-CN',
       rl,
@@ -429,8 +429,8 @@ test('collectModelInput: 预设服务商 + 内置模型 + 测试成功 → 返
 test('collectModelInput: 自定义服务商 + 手动输入模型名 → 返回收集的字段', async () => {
   const restore = silenceConsole()
   try {
-    // 选自定义(0) → 输入 baseURL → 确认(空=默认) → 手动输入模型名 → apiKey(空) → displayName(空=默认)
-    const rl = createMockRl(['0', 'https://my.custom.api/v1', '', 'my-model', '', ''])
+    // 选自定义(0) → 输入 baseURL → 确认(空=默认) → apiKey(空) → 手动输入模型名 → displayName(空=默认)
+    const rl = createMockRl(['0', 'https://my.custom.api/v1', '', '', 'my-model', ''])
     const result = await collectModelInput({
       locale: 'zh-CN',
       rl,
@@ -449,8 +449,8 @@ test('collectModelInput: 自定义服务商 + 手动输入模型名 → 返回
 test('collectModelInput: 测试失败 + 用户选择不保存 → 返回 null', async () => {
   const restore = silenceConsole()
   try {
-    // 选 DeepSeek(3) → 确认 → 选第一个模型(1) → apiKey → displayName → 测试401失败 → 不保存(n)
-    const rl = createMockRl(['3', '', '1', 'sk-bad', '', 'n'])
+    // 选 DeepSeek(3) → 确认 → apiKey → 选第一个模型(1) → displayName → 测试401失败 → 不保存(n)
+    const rl = createMockRl(['3', '', 'sk-bad', '1', '', 'n'])
     const result = await collectModelInput({
       locale: 'zh-CN',
       rl,
@@ -465,7 +465,7 @@ test('collectModelInput: 测试失败 + 用户选择不保存 → 返回 null',
 test('collectModelInput: 测试失败 + 用户选择继续 → 返回收集的字段', async () => {
   const restore = silenceConsole()
   try {
-    const rl = createMockRl(['3', '', '1', 'sk-bad', '', 'y'])
+    const rl = createMockRl(['3', '', 'sk-bad', '1', '', 'y'])
     const result = await collectModelInput({
       locale: 'zh-CN',
       rl,
@@ -494,3 +494,32 @@ test('collectModelInput: 用户取消(触发 close)→ 返回 null', async () =>
     restore()
   }
 })
+
+test('collectModelInput: API 返回模型列表时优先使用 → 返回收集的字段', async () => {
+  const restore = silenceConsole()
+  try {
+    // mock fetch: /models 返回模型列表, /chat/completions 返回 200
+    const smartFetch = async (url, opts) => {
+      if (url.endsWith('/models')) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ data: [{ id: 'api-model-1' }, { id: 'api-model-2' }] }),
+        }
+      }
+      return { ok: true, status: 200, json: async () => ({}) }
+    }
+    // 选 OpenAI(1) → 确认 baseURL → apiKey → 选第一个 API 返回的模型(1) → displayName
+    const rl = createMockRl(['1', '', 'sk-test', '1', ''])
+    const result = await collectModelInput({
+      locale: 'zh-CN',
+      rl,
+      fetchFn: smartFetch,
+    })
+    assert.ok(result)
+    assert.equal(result.model, 'api-model-1', '应使用 API 返回的模型而非内置列表')
+    assert.equal(result.apiKey, 'sk-test')
+  } finally {
+    restore()
+  }
+})

package/src/cli/ai/termui.js

@@ -140,16 +140,59 @@ export function filterSlashCommands(input, locale) {
 
 /**
  * 生成即时提示面板的 ANSI 字符串(不含定位,由调用方负责保存/恢复光标)。
- * 每行:两空格缩进 + 青色命令名(左对齐补齐)+ 灰色说明。
- * 空数组返回空串。
+ * 每行:两空格缩进 + 蓝色命令名(左对齐补齐 12 字符宽)+ 灰色说明。
+ * 所有行的"视觉起点"一致(均为 2 空格缩进);选中行用整行反白区分(从缩进处
+ * 开始),不另加 ❯ 之类的偏移标记 —— 避免反白块起点与其他行不齐。
+ *   - 越界 selectedIndex(<0 / >=matches.length) 自动回退为 -1(即不高亮)
+ *   - 空数组返回空串
  */
-export function renderSlashHintBody(matches) {
+export function renderSlashHintBody(matches, selectedIndex = -1) {
   if (!Array.isArray(matches) || matches.length === 0) return ''
+  const sel = (Number.isInteger(selectedIndex) && selectedIndex >= 0 && selectedIndex < matches.length)
+    ? selectedIndex
+    : -1
+  // 行宽固定 = 2 空格缩进 + 12 字符命令 + 说明;选中行反白整行(含缩进),
+  // 反白起点与未选中行严格对齐,视觉上选中行不会"偏左"。
+  const rowWidth = (m) => 2 + Math.max(12, String(m.cmd).length) + 1 + String(m.desc).length
   return matches
-    .map((m) => '  ' + chalk.cyan(String(m.cmd).padEnd(12)) + chalk.dim(m.desc))
+    .map((m, i) => {
+      // 用 padEnd 凑满 rowWidth,这样反白背景能延伸到行尾,左右不留缝
+      const raw = '  ' + String(m.cmd).padEnd(12) + ' ' + m.desc
+      // 所有行命令名统一用青色(不带额外前缀),选中行靠反白区分
+      const line = chalk.cyan(String(m.cmd).padEnd(12)) + ' ' + chalk.dim(m.desc)
+      if (i !== sel) return '  ' + line
+      // 选中行:把命令名+说明之外的两空格缩进也纳入反白,这样视觉起点严格对齐
+      return chalk.inverse(raw.padEnd(rowWidth(m)))
+    })
     .join('\n')
 }
 
+/**
+ * 解析 readline keypress 事件,识别"斜杠命令提示"专用快捷键。
+ * 返回动作字符串(消费方据此改 selectedIndex 或补全输入);
+ * 不识别的键返回 null(由 readline 正常处理)。
+ *
+ *   - ↑ / Shift+Tab → 'prev'
+ *   - ↓             → 'next'
+ *   - Tab           → 'complete'(补全选中命令到输入行)
+ *   - Enter         → 'submit'(由 readline 默认提交,本函数仅标记是补全时机)
+ *   - Esc           → 'cancel'
+ *
+ * 注意:readline 默认会把方向键当历史浏览。消费方需要在我们这个 handler
+ * 里"事后回滚":把 rl.line 恢复成 hint 显示时的基线,再 _refreshLine()。
+ * (详见 agent.js 的 keypress 监听与说明)
+ */
+export function parseKeyForSlashHint(key) {
+  if (!key) return null
+  const name = key.name
+  if (name === 'tab') return key.shift ? 'prev' : 'complete'
+  if (name === 'up') return 'prev'
+  if (name === 'down') return 'next'
+  if (name === 'return' || name === 'enter') return 'submit'
+  if (name === 'escape') return 'cancel'
+  return null
+}
+
 /** 盒式帮助面板 */
 export function printHelpPanel(title, lines) {
   const body = [chalk.bold(title), ...lines].join('\n')
@@ -376,6 +419,28 @@ export function createAssistantWriter({
   }
 }
 
+// ──────────────────────────────────────────────────────
+// 耗时格式化
+// ──────────────────────────────────────────────────────
+
+/**
+ * 格式化耗时(毫秒 → 人类可读)。
+ *   < 1s  → "123ms"
+ *   < 60s → "1.2s"
+ *   ≥ 60s → "2m30s"
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return ''
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  const s = ms / 1000
+  if (s < 60) return `${s.toFixed(1)}s`
+  const m = Math.floor(s / 60)
+  const rem = Math.round(s % 60)
+  return `${m}m${rem}s`
+}
+
 // ──────────────────────────────────────────────
 // 工具调用块(Claude Code 风格)
 // ──────────────────────────────────────────────
@@ -426,8 +491,12 @@ export function printToolHeader(name, summary, write = (s) => process.stdout.wri
  * run_command 的结果里首行是 `$ <command>` 回显——这条信息已经出现在上方的
  * `▶ run_command $ <summary>` 工具头里,这里再印一次就是重复。所以这里把首
  * 行 `$ ...` 剥掉,同时复用它来识别退出码(退出码仍驱动错误着色)。
+ *
+ * @param {string} result - 工具输出文本
+ * @param {(s: string) => void} [write] - 输出函数,默认写 stdout
+ * @param {number} [durationMs] - 执行耗时(毫秒),有值时在结果末尾追加 ⏱ 计时行
  */
-export function printToolResult(result, write = (s) => process.stdout.write(s)) {
+export function printToolResult(result, write = (s) => process.stdout.write(s), durationMs) {
   const text = truncateDisplay(result)
   // 先把 "$ <command>\n" 这一行回显从展示里剥掉(退出码仍在第二行里识别)
   const visible = text.replace(/^\$[^\n]*\n/, '')
@@ -440,7 +509,11 @@ export function printToolResult(result, write = (s) => process.stdout.write(s))
   const colorize = isError ? chalk.hex('#f0a020') : chalk.hex('#94a3b8')
   const lines = visible.split('\n')
   const rendered = lines.map((l) => chalk.dim('  │  ') + colorize(l)).join('\n')
-  write(rendered + '\n')
+  // 有耗时时在结果末尾追加 ⏱ 计时行(与结果块同缩进)
+  const timingLine = (durationMs != null && Number.isFinite(durationMs))
+    ? '\n' + chalk.dim('  │  ⏱ ') + chalk.hex('#7a87a0')(formatDuration(durationMs))
+    : ''
+  write(rendered + timingLine + '\n')
 }
 
 // ──────────────────────────────────────────────
@@ -456,11 +529,13 @@ export default {
   termWidth,
   stripAnsi,
   truncateDisplay,
+  formatDuration,
   printBanner,
   printHelpPanel,
   SLASH_COMMANDS,
   filterSlashCommands,
   renderSlashHintBody,
+  parseKeyForSlashHint,
   drawInputTop,
   drawInputBottom,
   inputBottomBorder,