zen-gitsync 2.18.1 → 2.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-gitsync",
-  "version": "2.18.1",
+  "version": "2.18.2",
   "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",
@@ -79,6 +79,7 @@
     "verify:wb-open-scroll-bottom": "node scripts/verify-workbench-open-scroll-bottom.cjs",
     "verify:chat-rail": "node scripts/verify-chat-message-rail.cjs",
     "verify:agent-session-copy": "node scripts/verify-agent-session-copy.cjs",
+    "verify:agent-retry": "node scripts/verify-agent-llm-retry.cjs",
     "verify:editor-preview-scroll": "node scripts/verify-editor-preview-scroll.cjs",
     "verify:editor-sidebar-width": "node scripts/verify-editor-sidebar-width.cjs",
     "verify:editor-disk-sync": "node scripts/verify-editor-disk-sync.cjs",

package/src/cli/ai/agent.js

@@ -71,6 +71,8 @@ const STRINGS = {
     unknownModel: (q) => `未找到匹配的模型: ${q},使用默认模型`,
     waiting: '思考中…',
     llmError: (msg) => `LLM 请求失败: ${msg}`,
+    // 传输层自动重试时的一行提示（失败原因原样带上，用户自己判断要不要 Ctrl+C 停掉）
+    llmRetrying: (attempt, max, reason) => `LLM 请求中断,正在重试(第 ${attempt}/${max} 次): ${reason}`,
     toolIterLimit: (n) => `已达单轮最大工具调用次数(${n}),本轮结束。如需继续请再发一条消息。`,
     toolRunning: (name) => `执行 ${name}…`,
     busy: '任务执行中，请稍候，或按 Ctrl+C 停止当前任务。',
@@ -130,6 +132,7 @@ const STRINGS = {
     unknownModel: (q) => `No model matching "${q}", falling back to default`,
     waiting: 'Thinking…',
     llmError: (msg) => `LLM request failed: ${msg}`,
+    llmRetrying: (attempt, max, reason) => `LLM request interrupted, retrying (${attempt}/${max}): ${reason}`,
     toolIterLimit: (n) => `Hit max tool iterations (${n}) for this turn. Send another message to continue.`,
     toolRunning: (name) => `Running ${name}…`,
     busy: 'Agent is working. Wait or press Ctrl+C to stop the task.',

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

@@ -59,8 +59,11 @@ test('unsupported stream_options retries once without requesting usage', async (
   assert.equal(result.usage, null)
 })
 
+// 这两条关心的都是"失败时怎么收场"，不是"重试几次" —— 一律 maxRetries: 0，
+// 否则要真等退避（最多 10 次、单次封顶 30s），一个用例就跑到分钟级。
+// 重试本身的行为在文件末尾那组用例里单独验（那里注入 sleepFn，不真等）。
 test('truncated streams do not yield executable tool calls', async () => {
-  await assert.rejects(streamChatOnce({ model, messages: [], fetchFn: async () => response([
+  await assert.rejects(streamChatOnce({ model, messages: [], maxRetries: 0, fetchFn: async () => response([
     event({ choices: [{ delta: { tool_calls: [{ index: 0, id: 'x', function: { name: 'write_file', arguments: '{}' } }] } }] }),
   ]) }), /中断/)
 })
@@ -71,12 +74,98 @@ test('timeout and explicit cancellation have different outcomes', async () => {
     if (signal.aborted) abort()
     else signal.addEventListener('abort', abort, { once: true })
   })
-  await assert.rejects(streamChatOnce({ model, messages: [], fetchFn: hanging, timeoutMs: 10 }), /超时/)
+  await assert.rejects(streamChatOnce({ model, messages: [], fetchFn: hanging, idleTimeoutMs: 10, maxRetries: 0 }), /超时/)
   const result = await streamChatOnce({ model, messages: [], fetchFn: hanging, signal: AbortSignal.abort() })
   assert.equal(result.aborted, true)
   assert.deepEqual(result.toolCalls, [])
 })
 
+// ── 空闲超时 + 自动重试（2026-10-09）─────────────────────────────────
+//
+// 这一组钉的是两件事：
+//   1. 超时的判据是**空闲**（多久没数据）而不是整条流的时长 —— 慢回答不该被掐
+//   2. 失败会自己重试，而"重试也没用"的错误（4xx / 非法 index）不会白试十次
+
+test('空闲超时只在"真的没有数据"时触发，慢回答活得下来', async () => {
+  // 整条流故意拖过 idleTimeoutMs，但每 10ms 吐一段 —— 旧口径（总时长上限）在这里必红
+  const slowButAlive = async (_url, init) => new Response(new ReadableStream({
+    async start(controller) {
+      const bytes = new TextEncoder()
+      for (let i = 0; i < 6; i++) {
+        await new Promise(r => setTimeout(r, 12))
+        controller.enqueue(bytes.encode(event({ choices: [{ delta: { content: `c${i}` } }] })))
+      }
+      controller.enqueue(bytes.encode(event({ choices: [{ delta: {}, finish_reason: 'stop' }] })))
+      controller.enqueue(bytes.encode('data: [DONE]\n\n'))
+      controller.close()
+    },
+  }))
+  const result = await streamChatOnce({ model, messages: [], fetchFn: slowButAlive, idleTimeoutMs: 40, maxRetries: 0 })
+  assert.equal(result.content, 'c0c1c2c3c4c5')
+})
+
+test('可重试的失败会自己重试到成功，并把半截产物交给 onRetry', async () => {
+  let calls = 0
+  const retries = []
+  const flaky = async () => {
+    calls++
+    // 第一次：吐一段正文后流断掉（没有 finish_reason）—— 正是"重试能救"的那类
+    if (calls === 1) return response([event({ choices: [{ delta: { content: '半截' } }] })])
+    return response([event({ choices: [{ delta: { content: '好了' }, finish_reason: 'stop' }] }), 'data: [DONE]\n\n'])
+  }
+  const result = await streamChatOnce({
+    model, messages: [], fetchFn: flaky,
+    sleepFn: async () => {},          // 不真等退避
+    onRetry: info => retries.push(info),
+  })
+  assert.equal(calls, 2)
+  assert.equal(result.content, '好了')
+  assert.equal(retries.length, 1)
+  assert.equal(retries[0].attempt, 1)
+  assert.equal(retries[0].maxRetries, 10, '默认重试上限与 Claude Code 对齐（10）')
+  // 半截内容必须交出来 —— 调用方要靠它把界面上那半句丢掉，否则会看到两段拼在一起
+  assert.equal(retries[0].partial.content, '半截')
+})
+
+test('重试次数用尽后抛出最后一次的错误', async () => {
+  let calls = 0
+  await assert.rejects(streamChatOnce({
+    model, messages: [], maxRetries: 3, sleepFn: async () => {},
+    fetchFn: async () => { calls++; return response([event({ choices: [{ delta: { content: 'x' } }] })]) },
+  }), /中断/)
+  assert.equal(calls, 4, '首次 + 3 次重试')
+})
+
+test('4xx（重试也没用）不重试，网关原话照传', async () => {
+  let calls = 0
+  await assert.rejects(streamChatOnce({
+    model, messages: [], sleepFn: async () => {},
+    fetchFn: async () => { calls++; return new Response('{"error":{"message":"invalid api key"}}', { status: 401 }) },
+  }), /HTTP 401/)
+  assert.equal(calls, 1, '401 重试十次还是 401，不该白烧十次请求')
+})
+
+test('用户点了停止就不再重试', async () => {
+  const controller = new AbortController()
+  let attempts = 0
+  const hanging = async (_url, { signal }) => {
+    attempts++
+    return new Promise((_, reject) => {
+      const abort = () => reject(new DOMException('Aborted', 'AbortError'))
+      if (signal.aborted) abort()
+      else signal.addEventListener('abort', abort, { once: true })
+    })
+  }
+  // 超时→正要重试的那一刻用户按了停止（onRetry 里 abort，最贴近真实时序）
+  const result = await streamChatOnce({
+    model, messages: [], fetchFn: hanging, signal: controller.signal,
+    idleTimeoutMs: 10, sleepFn: async () => { controller.abort() },
+    onRetry: () => { controller.abort() },
+  })
+  assert.equal(result.aborted, true)
+  assert.equal(attempts, 1, '中止后不该再发第二次请求')
+})
+
 const call = n => ({ id: `call${n}`, type: 'function', function: { name: 'read_file', arguments: '{}' } })
 const askCall = (id = 'ask1') => ({ id, type: 'function', function: {
   name: 'ask_user',

package/src/cli/ai/telemetry.js

@@ -28,7 +28,9 @@ export function createTurnStats() {
   return {
     startedAt: new Date().toISOString(), completedAt: null, status: 'running',
     totalMs: 0, llmMs: 0, toolsMs: 0, firstTokenMs: null, firstAnswerMs: null,
-    requests: 0, toolCalls: 0, usageRequests: 0, usage: null,
+    // retries：本轮里被传输层自动重试掉的次数（已在 requests 里计过一次的额外请求）。
+    // 单独留一个数是为了让"请求数忽然变多"有解释，而不是看着像 bug（见 /stats）。
+    requests: 0, retries: 0, toolCalls: 0, usageRequests: 0, usage: null,
   }
 }
 

package/src/cli/ai/termui.js

@@ -657,9 +657,13 @@ export function renderTurnSummary(stats, { locale = 'zh-CN', session, width = Ma
   const timing = [status + (time ? ` ${time}` : ''), `${zh ? '总耗时' : 'total'} ${formatDuration(stats.totalMs)}`]
   if (stats.firstTokenMs != null) timing.push(`${zh ? '首响应' : 'first token'} ${formatDuration(stats.firstTokenMs)}`)
   if (stats.firstAnswerMs != null) timing.push(`${zh ? '正文等待' : 'first answer'} ${formatDuration(stats.firstAnswerMs)}`)
+  // 「重试 N」只在真的重试过时才出现：正常的一轮多一个恒为 0 的字段纯属噪音，
+  // 而真重试过的那一轮，用户需要一个解释（请求数为什么比平时多）。
+  const requestLine = `${zh ? '模型' : 'model'} ${formatDuration(stats.llmMs)} · ${zh ? '工具' : 'tools'} ${formatDuration(stats.toolsMs)} (${stats.toolCalls}) · ${zh ? '请求' : 'requests'} ${stats.requests}`
+    + (stats.retries > 0 ? ` · ${zh ? '重试' : 'retries'} ${stats.retries}` : '')
   const lines = [
     timing.join(' · '),
-    `${zh ? '模型' : 'model'} ${formatDuration(stats.llmMs)} · ${zh ? '工具' : 'tools'} ${formatDuration(stats.toolsMs)} (${stats.toolCalls}) · ${zh ? '请求' : 'requests'} ${stats.requests}`,
+    requestLine,
     usageLine(stats.usage, stats.usageRequests, stats.requests),
   ]
   if (session) lines.push(`${zh ? '会话累计' : 'Session'} (${session.turns}) · ${usageLine(session.usage, session.usageRequests, session.requests)}`)

package/src/cli/ai/transport.js

@@ -5,19 +5,110 @@ import { normalizeUsage } from './telemetry.js'
 // Some compatible gateways reject stream_options. Remember that for this process.
 const withoutStreamUsage = new Set()
 
+// ── 超时与自动重试口径（2026-10-09 改） ────────────────────────────────
+//
+// **超时是"空闲"超时，不再是"整条流"上限。**
+// 原先是一个从请求发出就开始跑的 300s 总时限：一次正常但比较慢的回答
+// （长思考 / 长正文 / 大上下文的首字延迟）跑满 5 分钟就被判"模型响应超时"掐断，
+// 而对面其实还在正常吐字 —— 用户看到的是"跑得好好的突然失败"。
+// 现在只在**连续 idleTimeoutMs 毫秒收不到任何字节**时才判定连接已死：
+// 每收到一段数据就重置计时（见 attemptOnce 里的 touch()）。慢但活着的回答可以一直跑，
+// 真挂死的连接照样会被发现。窗口里那句"模型响应超时"因此换了说法（见 stallError）。
+//
+// 判死的连接不再直接失败：交给下面这条自动重试接手，最多 MAX_LLM_RETRIES 次
+// （口径对齐 Claude Code 的 MAX_RETRIES=10）。
+//
+// 外层的两个调用点（CLI 的 turn.js / Web 的 agentChat.js）通过 onRetry 拿到
+// "这次尝试吐了哪些字"的快照，据此把界面上那半截丢掉再重来。
+export const DEFAULT_IDLE_TIMEOUT_MS = 300_000
+export const MAX_LLM_RETRIES = 10
+const RETRY_BASE_DELAY_MS = 500
+const RETRY_MAX_DELAY_MS = 30_000
+
+// 值得再试一次的 HTTP 状态：限流 / 请求超时 / 服务端 5xx —— 都是"再试一次可能就好了"。
+// 其余 4xx（400 参数错、401/403 鉴权、404 模型名不对、422 校验失败）再试十次也一样，
+// 直接失败，并把网关的原话交给用户。
+const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504, 520, 522, 524])
+
 // 把"网关返回了什么"翻成"用户该做什么"。400 且正文提到 tool/function 时,十有八九是
 // 模型本身不支持 function calling —— 直接说清楚,比把网关 JSON 原样甩出来有用。
 // 这条口径原先只在 Web 智能体面板里写了一份,现在收敛到此处,CLI 与 Web 共用。
-function httpFailure(status, detail, statusText) {
+//
+// status 同时决定这件事**要不要重试**（retryable），所以错误对象上必须带住它 ——
+// 重试判定发生在 catch 里，那时响应对象已经不在手上了。
+function httpFailure(status, detail, statusText, { retryAfterMs = null } = {}) {
   const suffix = detail || statusText || ''
-  if (status === 400 && /tool|function/i.test(String(detail || ''))) {
-    return new Error(`HTTP 400: 当前模型可能不支持 function calling(${suffix})。请在设置中换用支持工具调用的模型。`)
-  }
-  return new Error(`HTTP ${status}: ${suffix}`)
+  const error = status === 400 && /tool|function/i.test(String(detail || ''))
+    ? new Error(`HTTP 400: 当前模型可能不支持 function calling(${suffix})。请在设置中换用支持工具调用的模型。`)
+    : new Error(`HTTP ${status}: ${suffix}`)
+  error.status = status
+  error.retryable = RETRYABLE_STATUS.has(status)
+  if (Number.isFinite(retryAfterMs)) error.retryAfterMs = retryAfterMs
+  return error
+}
+
+/** 网关给的 Retry-After（秒数或 HTTP 日期）。拿不到返回 null，别让解析失败影响重试。 */
+function readRetryAfter(resp) {
+  let raw = null
+  try { raw = resp?.headers?.get?.('retry-after') } catch { return null }
+  if (!raw) return null
+  const secs = Number(raw)
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000)
+  const at = Date.parse(raw)
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null
+}
+
+/**
+ * 这个错误值不值得再试一次。
+ *
+ * 默认**值得**：传输层抛出来的绝大多数是网络/流层面的瞬时故障（连接被掐、网关 5xx、
+ * 流没跑完就断、长时间没数据），重试是唯一能自愈的手段。
+ * "重试也没用"的那几类在建错误时就打了 retryable=false：HTTP 4xx（除限流/超时那三个）、
+ * 模型给了非法的 tool call index（同样的请求发过去还是同一个非法值）。
+ */
+function isRetryable(err) {
+  if (!err) return false
+  if (typeof err.retryable === 'boolean') return err.retryable
+  return true
+}
+
+/** 指数退避 + 抖动；网关给了 Retry-After 就听它的（封顶，免得被一个 3600 挂住半小时）。 */
+function retryDelayMs(attempt, err) {
+  const exp = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** attempt)
+  const jittered = exp / 2 + Math.random() * (exp / 2)
+  const hinted = Number.isFinite(err?.retryAfterMs) ? err.retryAfterMs : 0
+  return Math.max(jittered, Math.min(hinted, RETRY_MAX_DELAY_MS * 2))
 }
 
-export async function streamChatOnce({ model, messages, signal, onToken = () => {}, sessionId, extraTools,
-  fetchFn = fetch, timeoutMs = 300000 }) {
+/** 可被 abort 打断的 sleep —— 用户点了停止就别在这儿干等下一次重试。 */
+function defaultSleep(ms, signal) {
+  return new Promise(resolve => {
+    if (!(ms > 0) || signal?.aborted) return resolve()
+    const done = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', done)
+      resolve()
+    }
+    const timer = setTimeout(done, ms)
+    signal?.addEventListener('abort', done, { once: true })
+  })
+}
+
+/**
+ * 跑一次 LLM 流式请求（失败按上面的口径自动重试）。
+ *
+ * @param {object}   o
+ * @param {number}   [o.idleTimeoutMs] 连续多久收不到数据算连接已死（0 = 不判超时）
+ * @param {number}   [o.maxRetries]    自动重试次数上限（不含首次尝试）
+ * @param {Function} [o.onRetry]       每次重试**之前**调用：
+ *                                     `({ attempt, maxRetries, delayMs, error, partial })`，
+ *                                     attempt 从 1 开始。调用方拿它把界面上那半截丢掉
+ *                                     （partial = 这次尝试已经吐出去的正文/思考/工具调用）。
+ * @param {Function} [o.sleepFn]       退避等待（测试注入用，签名 (ms, signal) => Promise）
+ */
+export async function streamChatOnce({ model, messages, signal, onToken = () => {}, onRetry = null,
+  sessionId, extraTools, fetchFn = fetch, idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+  maxRetries = MAX_LLM_RETRIES, sleepFn = defaultSleep }) {
   const { url, headers } = buildAiChatRequest({ ...model, sessionId })
   const providerKey = `${url}\n${model.model}`
   // 内置 7 个工具是底座;extraTools 是 MCP 等外部能力的叠加(见 extensions.js)。
@@ -25,79 +116,127 @@ export async function streamChatOnce({ model, messages, signal, onToken = () =>
   const tools = Array.isArray(extraTools) && extraTools.length ? [...TOOL_DEFINITIONS, ...extraTools] : TOOL_DEFINITIONS
   const body = { model: model.model, messages, tools, temperature: 0.3, stream: true }
   if (!withoutStreamUsage.has(providerKey)) body.stream_options = { include_usage: true }
-  const controller = new AbortController()
-  let timedOut = false
-  const timer = setTimeout(() => { timedOut = true; controller.abort() }, timeoutMs)
-  const onAbort = () => controller.abort()
-  if (signal?.aborted) controller.abort()
-  else signal?.addEventListener('abort', onAbort)
-  let content = '', reasoning = '', usage = null, finished = false
-  const toolCalls = []
+  const abortedByUser = () => Boolean(signal?.aborted)
+  const emptyResult = () => ({ content: '', reasoning: '', toolCalls: [], usage: null, aborted: true })
+  const stallError = () => new Error(
+    `模型响应超时：连续 ${Math.round(idleTimeoutMs / 1000)} 秒没有收到任何数据，请重试或切换模型。`)
 
-  const consumeLine = line => {
-    const trimmed = line.trim()
-    if (!trimmed.startsWith('data:')) return
-    const payload = trimmed.slice(5).trim()
-    if (payload === '[DONE]') { finished = true; return }
-    if (!payload) return
-    let evt
-    try { evt = JSON.parse(payload) } catch { throw new Error('Invalid JSON in model stream') }
-    if (evt.error) throw new Error(evt.error.message || 'Model stream failed')
-    // Usage may arrive after finish_reason, in a final event with choices: [].
-    // Events report snapshots, so replace fields instead of summing snapshots.
-    const nextUsage = normalizeUsage(evt.usage)
-    if (nextUsage) usage = Object.fromEntries(Object.entries(nextUsage).map(([key, value]) => [key, value ?? usage?.[key] ?? null]))
-    if (evt.choices?.[0]?.finish_reason) finished = true
-    const delta = evt.choices?.[0]?.delta || {}
-    const thinking = delta.reasoning_content || delta.reasoning || delta.reasoning_text || ''
-    if (thinking) { reasoning += thinking; onToken({ thinking }) }
-    if (delta.content) { content += delta.content; onToken({ content: delta.content }) }
-    for (const tc of delta.tool_calls || []) {
-      const i = tc.index ?? 0
-      if (!Number.isInteger(i) || i < 0 || i > 1024) throw new Error('Invalid tool call index')
-      if (!toolCalls[i]) toolCalls[i] = { id: '', type: 'function', function: { name: '', arguments: '' } }
-      if (tc.id) toolCalls[i].id += tc.id
-      if (tc.function?.name) toolCalls[i].function.name += tc.function.name
-      if (tc.function?.arguments) toolCalls[i].function.arguments += tc.function.arguments
-    }
-    if (delta.tool_calls?.length) onToken({ toolCalls: true })
-  }
-  try {
-    const request = () => fetchFn(url, { method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal })
-    let resp = await request()
-    if (!resp.ok) {
-      const detail = describeAiHttpError(await resp.text().catch(() => ''), resp.status)
-      if ([400, 422].includes(resp.status) && body.stream_options && /stream_options|include_usage/i.test(detail)) {
-        delete body.stream_options
-        withoutStreamUsage.add(providerKey)
-        resp = await request()
-      } else throw httpFailure(resp.status, detail, resp.statusText)
+  // 一次尝试：建连接 → 收流 → 返回结果。失败时把"已经吐出去的半截"挂在错误上抛给调用方。
+  const attemptOnce = async () => {
+    const controller = new AbortController()
+    let timedOut = false
+    let timer = null
+    // 每收到一段数据就重置空闲计时（这就是"整条流上限"变"空闲上限"的全部实现）
+    const touch = () => {
+      if (!(idleTimeoutMs > 0)) return
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => { timedOut = true; controller.abort() }, idleTimeoutMs)
     }
-    if (!resp.ok || !resp.body) {
-      throw httpFailure(resp.status, describeAiHttpError(await resp.text().catch(() => ''), resp.status), resp.statusText)
+    const onAbort = () => controller.abort()
+    if (signal?.aborted) controller.abort()
+    else signal?.addEventListener('abort', onAbort)
+    let content = '', reasoning = '', usage = null, finished = false
+    const toolCalls = []
+
+    const consumeLine = line => {
+      const trimmed = line.trim()
+      if (!trimmed.startsWith('data:')) return
+      const payload = trimmed.slice(5).trim()
+      if (payload === '[DONE]') { finished = true; return }
+      if (!payload) return
+      let evt
+      try { evt = JSON.parse(payload) } catch { throw new Error('Invalid JSON in model stream') }
+      if (evt.error) throw new Error(evt.error.message || 'Model stream failed')
+      // Usage may arrive after finish_reason, in a final event with choices: [].
+      // Events report snapshots, so replace fields instead of summing snapshots.
+      const nextUsage = normalizeUsage(evt.usage)
+      if (nextUsage) usage = Object.fromEntries(Object.entries(nextUsage).map(([key, value]) => [key, value ?? usage?.[key] ?? null]))
+      if (evt.choices?.[0]?.finish_reason) finished = true
+      const delta = evt.choices?.[0]?.delta || {}
+      const thinking = delta.reasoning_content || delta.reasoning || delta.reasoning_text || ''
+      if (thinking) { reasoning += thinking; onToken({ thinking }) }
+      if (delta.content) { content += delta.content; onToken({ content: delta.content }) }
+      for (const tc of delta.tool_calls || []) {
+        const i = tc.index ?? 0
+        // 非法 index 是模型/网关给的脏数据，同样的请求重发还是同一个脏值 —— 明确不可重试
+        if (!Number.isInteger(i) || i < 0 || i > 1024) {
+          const err = new Error('Invalid tool call index')
+          err.retryable = false
+          throw err
+        }
+        if (!toolCalls[i]) toolCalls[i] = { id: '', type: 'function', function: { name: '', arguments: '' } }
+        if (tc.id) toolCalls[i].id += tc.id
+        if (tc.function?.name) toolCalls[i].function.name += tc.function.name
+        if (tc.function?.arguments) toolCalls[i].function.arguments += tc.function.arguments
+      }
+      if (delta.tool_calls?.length) onToken({ toolCalls: true })
     }
-    const decoder = new TextDecoder()
-    let buf = ''
-    for await (const chunk of resp.body) {
-      buf += decoder.decode(chunk, { stream: true })
-      const lines = buf.split('\n')
-      buf = lines.pop() ?? ''
-      for (const line of lines) consumeLine(line)
+
+    try {
+      // 首次计时在请求发出**之前**开始：连响应头都还没回来的那段时间同样算"没有数据"
+      touch()
+      const request = () => fetchFn(url, { method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal })
+      let resp = await request()
+      if (!resp.ok) {
+        const detail = describeAiHttpError(await resp.text().catch(() => ''), resp.status)
+        if ([400, 422].includes(resp.status) && body.stream_options && /stream_options|include_usage/i.test(detail)) {
+          // 网关不认 stream_options：去掉它再来一次。这不是"重试"（请求本身没错），
+          // 所以不占重试次数，也不通知 onRetry。
+          delete body.stream_options
+          withoutStreamUsage.add(providerKey)
+          touch()
+          resp = await request()
+        } else throw httpFailure(resp.status, detail, resp.statusText, { retryAfterMs: readRetryAfter(resp) })
+      }
+      if (!resp.ok || !resp.body) {
+        throw httpFailure(resp.status, describeAiHttpError(await resp.text().catch(() => ''), resp.status), resp.statusText,
+          { retryAfterMs: readRetryAfter(resp) })
+      }
+      const decoder = new TextDecoder()
+      let buf = ''
+      for await (const chunk of resp.body) {
+        touch()
+        buf += decoder.decode(chunk, { stream: true })
+        const lines = buf.split('\n')
+        buf = lines.pop() ?? ''
+        for (const line of lines) consumeLine(line)
+      }
+      buf += decoder.decode()
+      if (buf.trim()) consumeLine(buf)
+      if (controller.signal.aborted) throw new DOMException('Aborted', 'AbortError')
+      if (!finished) throw new Error('模型响应意外中断，请重试；未执行不完整的工具调用。')
+      return { content, reasoning, toolCalls: toolCalls.filter(Boolean), usage, aborted: false }
+    } catch (err) {
+      if (controller.signal.aborted && !timedOut) {
+        return { content, reasoning, toolCalls: [], usage, aborted: true }
+      }
+      const error = timedOut ? stallError() : err
+      error.usage = usage
+      // 这次尝试已经吐给 onToken 的东西。调用方在重试前必须把它丢掉，
+      // 否则界面上会出现"半截 + 重来一遍"拼在一起的两段话。
+      error.partial = { content, reasoning, toolCalls: toolCalls.filter(Boolean) }
+      throw error
+    } finally {
+      if (timer) clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
     }
-    buf += decoder.decode()
-    if (buf.trim()) consumeLine(buf)
-    if (controller.signal.aborted) throw new DOMException('Aborted', 'AbortError')
-    if (!finished) throw new Error('模型响应意外中断，请重试；未执行不完整的工具调用。')
-    return { content, reasoning, toolCalls: toolCalls.filter(Boolean), usage, aborted: false }
-  } catch (err) {
-    if (controller.signal.aborted && !timedOut) {
-      return { content, reasoning, toolCalls: [], usage, aborted: true }
+  }
+
+  for (let attempt = 0; ; attempt++) {
+    if (abortedByUser()) return emptyResult()
+    try {
+      return await attemptOnce()
+    } catch (err) {
+      // 用户点的停止不是故障，绝不重试
+      if (abortedByUser()) throw err
+      if (!isRetryable(err) || attempt >= maxRetries) throw err
+      const delayMs = retryDelayMs(attempt, err)
+      try {
+        onRetry?.({ attempt: attempt + 1, maxRetries, delayMs, error: err, partial: err.partial })
+      } catch { /* onRetry 是调用方的界面钩子，它自己抛错不该吃掉这次重试 */ }
+      await sleepFn(delayMs, signal)
+      // 退避期间用户点了停止：当"已中止"收场，别再抛一个超时错误吓他
+      if (abortedByUser()) return emptyResult()
     }
-    const error = timedOut ? new Error('模型响应超时，请重试或切换模型。') : err
-    error.usage = usage
-    throw error
-  } finally {
-    clearTimeout(timer)
-    signal?.removeEventListener('abort', onAbort)
   }
 }

package/src/cli/ai/turn.js

@@ -65,14 +65,18 @@ export async function runAgentTurn(state, userText, t, images = [], dependencies
     for (let iter = 0; iter < maxIterations; iter++) {
       if (cancelled()) { stats.status = 'cancelled'; return stats }
       const spinner = ui.startSpinner(t.waiting)
-      const writer = ui.createAssistantWriter({
+      // 一次请求可能被传输层自动重试多次（长静默 / 网关 5xx / 流中断）。
+      // 每次尝试都换一套 writer + filter：终端没法把已经打出去的字擦掉，
+      // 与其让两次尝试的输出拼在一起，不如把上一截收尾、重开一块新的（中间一行重试提示）。
+      const makeWriter = () => ui.createAssistantWriter({
         showThinking: state.showThinking !== false,
         thinkingHeader: t.thinkingLabel,
         answerHeader: t.answerLabel,
         thinkingLimit: state.thinkingMode === 'compact' ? terminal.THINKING_PREVIEW_LINES : Infinity,
         thinkingHint: t.thinkingHint,
       })
-      const filter = createThinkFilter()
+      let writer = makeWriter()
+      let filter = createThinkFilter()
       const render = seg => {
         if (seg.content) {
           if (seg.content.trim() && stats.firstAnswerMs === null) stats.firstAnswerMs = performance.now() - started
@@ -90,6 +94,16 @@ export async function runAgentTurn(state, userText, t, images = [], dependencies
         const messages = prepareRequestMessages(state.messages, { locale: state.locale, ...(state.requestBudget || {}) })
         result = await chat({ model: state.model, messages, signal: state.abortController?.signal,
           sessionId: state.sessionId, extraTools: extensions?.tools,
+          onRetry: info => {
+            filter.flush().forEach(render)
+            writer.finish()
+            ui.printWarn(t.llmRetrying(info.attempt, info.maxRetries, info.error?.message || ''))
+            writer = makeWriter()
+            filter = createThinkFilter()
+            // 重试是一次**真的**请求，计入本轮请求数（/stats 里那个"请求数"要能对得上网关账单）
+            stats.requests++
+            stats.retries++
+          },
           onToken: token => {
             if (stats.firstTokenMs === null) stats.firstTokenMs = performance.now() - started
             if (token.content || (token.thinking && state.showThinking !== false)) spinner.stop()

package/src/config.js

@@ -126,6 +126,56 @@ export function normalizeNotifySwitch(value) {
   return typeof value === 'boolean' ? value : null;
 }
 
+// 「预设提示词」（智能体视图欢迎页的快捷卡片）的上限。
+// 只防"手改配置把 UI/请求写爆"，不是产品硬约束：卡片区是自适应网格，
+// 12 条在常见窗口里已经铺满；label 上限覆盖"一句话标题"，prompt 上限
+// 覆盖"一段能把要求说全的指令"。
+const AGENT_PRESET_PROMPTS_MAX = 12;
+const AGENT_PRESET_LABEL_MAX = 60;
+const AGENT_PRESET_PROMPT_MAX = 4000;
+
+/**
+ * 规范化「预设提示词」数组（全局配置，跨项目共享）。
+ *
+ * 语义约定（2026-10-09 新增）：
+ *   · undefined / null  → null（没配过，调用方回落 defaultConfig，即内置 5 条）
+ *   · []                → []（**合法值**：显式"恢复内置默认"就是这个表达）
+ *   · 非数组 / 任一条目结构坏 → null（整体拒绝：宁可整组回落内置，也不生成
+ *     "点了没反应"的半截卡片。UI 保存前会防呆，这条主要兜手改 config.json）
+ *   · 正常数组 → 清洗后的副本：trim、去重/补 id、超长截断、超条数截断
+ *     （超量与超长属于"手笔太大"，夹取比整组丢掉更贴近用户意图，
+ *     与 normalizeAiMaxToolIterations 的越界夹取同一套语义）
+ */
+export function normalizeAgentPresetPrompts(value) {
+  if (value === undefined || value === null) return null;
+  if (!Array.isArray(value)) return null;
+  const out = [];
+  const seen = new Set();
+  for (const item of value) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+    const label = typeof item.label === 'string' ? item.label.trim() : '';
+    const prompt = typeof item.prompt === 'string' ? item.prompt.trim() : '';
+    if (!label || !prompt) return null;
+    let id = typeof item.id === 'string' ? item.id.trim() : '';
+    // id 缺失或重复都无伤大雅（前端只拿它当 v-for key），补一个稳定且唯一的即可；
+    // 真正需要拒绝的是 label/prompt 缺失 —— 那会让卡片点了没反应。
+    if (!id || seen.has(id)) {
+      let n = out.length + 1;
+      id = `preset-${n}`;
+      while (seen.has(id)) id = `preset-${++n}-${Math.random().toString(36).slice(2, 5)}`;
+    }
+    seen.add(id);
+    out.push({
+      id,
+      label: label.slice(0, AGENT_PRESET_LABEL_MAX),
+      prompt: prompt.slice(0, AGENT_PRESET_PROMPT_MAX),
+    });
+    // 超出上限的部分直接放弃检查（反正要截断），避免为"手滑粘贴 500 条"做无谓校验
+    if (out.length >= AGENT_PRESET_PROMPTS_MAX) break;
+  }
+  return out;
+}
+
 /**
  * 三个提示通道（页面提示 / 浏览器通知 / 提示音）的最终取值。
  *
@@ -213,6 +263,10 @@ const defaultConfig = {
   // 越界值夹取到 [20,000, 1,000,000]。解析公式见 cli/ai/context.js 的 resolveRequestBudget。
   // 旧字段 aiMaxRequestChars（字符口径）由 resolveRequestTokens 迁移读取。
   aiMaxRequestTokens: REQUEST_DEFAULT_MAX_TOKENS,
+  // 智能体视图欢迎页的「预设提示词」快捷卡片（全局配置，CLI 不消费、只有 Web 端用）。
+  // 空数组 = 使用前端内置的 5 条默认（zh/en 文案随界面语言走，见 utils/agentPresets.ts）；
+  // 非空 = 用户自定义全量（每条 {id, label, prompt}）。归一化见 normalizeAgentPresetPrompts。
+  agentPresetPrompts: [],
   // 工作台任务执行器（claude | opencode | codex）。全局配置，跨项目共享。
   // 决定「执行任务 / 执行子任务 / 从此处开始 / 简单任务续聊」这条链路
   // 默认 spawn 哪个本地 CLI；执行入口可以按次覆盖（见 workbench 执行路由）。
@@ -559,6 +613,8 @@ async function loadConfig() {
         ?? defaultConfig.aiMaxToolIterations,
       aiMaxRequestTokens: resolveRequestTokens(raw),
       taskExecutor: normalizeTaskExecutor(raw.taskExecutor) ?? defaultConfig.taskExecutor,
+      agentPresetPrompts: normalizeAgentPresetPrompts(raw.agentPresetPrompts)
+        ?? defaultConfig.agentPresetPrompts,
       ...resolveNotifySwitches(raw)
     };
   }
@@ -580,6 +636,8 @@ async function loadConfig() {
     aiMaxRequestTokens: resolveRequestTokens(raw),
     taskExecutor: normalizeTaskExecutor(raw?.taskExecutor) ?? defaultConfig.taskExecutor,
     // 同 taskExecutor：全局配置，始终取顶层，防止被项目配置里的旧值覆盖
+    agentPresetPrompts: normalizeAgentPresetPrompts(raw?.agentPresetPrompts)
+      ?? defaultConfig.agentPresetPrompts,
     ...resolveNotifySwitches(raw)
   };
 }
@@ -633,6 +691,7 @@ async function saveConfig(config) {
   // 项目级是这一族键最容易踩的坑。解构出来本身不写回顶层（它已不再被任何地方读取）。
   const {
     theme, locale, models, ui, aiMaxToolIterations, aiMaxRequestTokens, taskExecutor,
+    agentPresetPrompts,
     notifyOnTaskDone: legacyNotifyOnTaskDone,
     notifyPageOnTaskDone, notifyBrowserOnTaskDone, notifySoundOnTaskDone,
     ...projectConfig
@@ -680,6 +739,12 @@ async function saveConfig(config) {
       raw[key] = normalized;
     }
   }
+  // 预设提示词同属全局设置：空数组是**合法值**（= 恢复内置默认），照写；
+  // 非法值（结构坏）不落盘，保留磁盘旧值 —— 与上面各键同一套语义。
+  const normalizedPresets = normalizeAgentPresetPrompts(agentPresetPrompts);
+  if (normalizedPresets !== null) {
+    raw.agentPresetPrompts = normalizedPresets;
+  }
 
   // 写入当前项目配置（在 defaultConfig 基础上合并，但不清空顶层其它键）
   const existingProjectConfig = (raw.projects[key] && typeof raw.projects[key] === 'object') ? raw.projects[key] : {};
@@ -886,6 +951,8 @@ export default {
   // 只在 `export function` 里命名导出是不够的：漏加会变成 undefined 调用 → 路由 500，
   // 而且因为有 try/catch 兜底，前端只会看到"保存失败"，不知道是哪个函数缺了。
   normalizeNotifySwitch,
+  // 智能体视图「预设提示词」的规范化(GUI 保存前也要用,见 /api/config/save-ai-settings)
+  normalizeAgentPresetPrompts,
 };
 
 // 命名导出 — 用于测试与外部复用