@mzzsfy/dsh-keep-working 0.0.0-stage → 0.2.0

package/src/closure.mjs

@@ -0,0 +1,174 @@
+/**
+ * 结案判定:纯函数层,不依赖宿主服务。
+ *
+ * 判定对象是一个 turn 的事件切片。结案凭据有两种:
+ * - present:本回合成功交付文件,且交付之后没有再改文件
+ * - marker:末行独占 TASK_DONE 或 TASK_BLOCKED: ...
+ *
+ * 有文件写入的回合只认 present,否则模型会退化成写一行标记就交差。
+ */
+
+export const DONE_MARKER = 'TASK_DONE'
+export const BLOCKED_PREFIX = 'TASK_BLOCKED'
+
+const BLOCKED_LINE = new RegExp(`^${BLOCKED_PREFIX}:\\s*\\S.*$`)
+
+/** 宿主写文件的工具名;新增写入面时在此登记。 */
+export const FILE_WRITE_TOOLS = new Set(['write', 'edit', 'apply_patch', 'str_replace_editor'])
+
+/** 取 assistant 消息里的可见文本,工具块不计入。 */
+export function assistantText(message) {
+  const content = message?.content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('')
+}
+
+/** 本回合事件切片:从该 turn 的 turn/start 起,到同号 turn/end 止。 */
+export function turnSlice(events, turn) {
+  if (!Array.isArray(events)) return []
+  let start = -1
+  let end = events.length
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index]
+    if (event?.type === 'turn/start' && event.data?.turn === turn) start = index
+    if (event?.type === 'turn/end' && event.data?.turn === turn) {
+      end = index
+      break
+    }
+  }
+  return events.slice(Math.max(start, 0), end)
+}
+
+/** 末行标记;严格匹配裸标记,括号、下划线、连字符等装饰都不算。 */
+export function matchMarker(text) {
+  if (typeof text !== 'string' || text === '') return null
+  const last = (text.trimEnd().split('\n').at(-1) ?? '').trim()
+  if (last === DONE_MARKER) return 'done'
+  if (BLOCKED_LINE.test(last)) return 'blocked'
+  return null
+}
+
+/** 本回合最后一条带可见文本的 assistant 消息文本;纯工具调用步骤跳过。 */
+export function lastAssistantText(events, turn) {
+  const slice = turnSlice(events, turn)
+  for (let index = slice.length - 1; index >= 0; index -= 1) {
+    const event = slice[index]
+    if (event?.type !== 'assistant/message') continue
+    const text = assistantText(event.data?.message)
+    if (text.trim() !== '') return text
+  }
+  return ''
+}
+
+/** 本回合是否产生过可见输出。 */
+export function hasVisibleOutput(events) {
+  return events.some(
+    (event) => event?.type === 'assistant/message' && assistantText(event.data?.message).trim() !== '',
+  )
+}
+
+/** 真人消息:来源是 user,且不是本插件补发的。 */
+const isHumanMessage = (event, excludeIds) =>
+  event?.type === 'user/message' &&
+  event.data?.source?.kind === 'user' &&
+  excludeIds?.has?.(event.data?.id) !== true
+
+/**
+ * 回合前导段里的真人发起消息。
+ *
+ * 宿主把各类上下文(指令文件、工作目录、任务事件、定时唤醒等)作为
+ * user/message 注入在真人消息之前,kind 由各生产者自定且持续增加,不能靠白名单。
+ * 这里只看 turn/start 之后的第一段:跳过非 user 来源,遇到本插件自投递或
+ * 模型、工具事件即结束。返回 undefined 表示本回合不是真人发起的。
+ */
+function leadingHumanMessage(events, turn, excludeIds) {
+  for (const event of turnSlice(events, turn)) {
+    if (event?.type === 'user/message') {
+      if (event.data?.source?.kind !== 'user') continue
+      // 本插件补发的消息是回合发起者,但不是真人
+      if (excludeIds?.has?.(event.data?.id) === true) return undefined
+      return event
+    }
+    if (event?.type === 'assistant/message' || event?.type === 'tool/call' || event?.type === 'tool/result') {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/** 回合发起来源;跳过注入上下文后取第一条 user 来源消息(含本插件补发)。 */
+export function turnInitiator(events, turn) {
+  for (const event of turnSlice(events, turn)) {
+    if (event?.type === 'user/message') {
+      if (event.data?.source?.kind !== 'user') continue
+      return 'user'
+    }
+    if (event?.type === 'assistant/message' || event?.type === 'tool/call' || event?.type === 'tool/result') {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/** 回合由真人发起:第一条非注入消息是真人且不是本插件自投递。 */
+export function humanInitiatedTurn(events, turn, excludeIds) {
+  return leadingHumanMessage(events, turn, excludeIds) !== undefined
+}
+
+/** 用户在本回合中途插话:结案提醒让路,避免与人的意图抢方向。 */
+export function userTookOver(events, turn, excludeIds) {
+  const humans = turnSlice(events, turn).filter((event) => isHumanMessage(event, excludeIds))
+  if (humans.length === 0) return false
+  // 发起者不是真人(插件补发的回合)时,第一条真人消息就是插话
+  return leadingHumanMessage(events, turn, excludeIds) === undefined || humans.length > 1
+}
+
+const isFileWrite = (event) => event?.type === 'tool/call' && FILE_WRITE_TOOLS.has(event.data?.name)
+
+/** 只读子命令:编辑器工具的 view 不改文件,不该逼出交付。 */
+function isReadOnlyCall(call) {
+  if (call?.data?.name !== 'str_replace_editor') return false
+  try {
+    return JSON.parse(call.data?.arguments ?? '{}')?.command === 'view'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 本回合真正改动过文件的调用。
+ *
+ * 失败的写(沙箱拒绝、审批驳回、参数错误)没有产生改动,按结果消息自带的 callId
+ * 精确剔除;没有 callId 的旧日志退化为不剔除,宁可多要求一次 present。
+ */
+function effectiveWrites(slice) {
+  const failed = new Set()
+  for (const event of slice) {
+    if (event?.type !== 'tool/result' || event.data?.message?.isError !== true) continue
+    const callId = event.data?.message?.toolCallId ?? event.data?.message?.source?.callId
+    if (callId !== undefined) failed.add(callId)
+  }
+  return slice
+    .filter(isFileWrite)
+    .filter((call) => !failed.has(call.data?.callId) && !isReadOnlyCall(call))
+}
+
+/** 结案判定;reason 供日志与提醒文案选择。 */
+export function closureVerdict(events, turn) {
+  const slice = turnSlice(events, turn)
+  const writes = effectiveWrites(slice)
+  const presents = slice.filter(
+    (event) => event?.type === 'deliverables/presented' && event.data?.turn === turn,
+  )
+  const lastPresent = presents.at(-1)
+  const presentInvalidated =
+    lastPresent !== undefined && writes.some((event) => event.seq > lastPresent.seq)
+
+  if (lastPresent !== undefined && !presentInvalidated) return { closed: true, reason: 'present' }
+  if (writes.length > 0) return { closed: false, reason: 'file-write-requires-present' }
+  if (matchMarker(lastAssistantText(slice, turn)) !== null) return { closed: true, reason: 'marker' }
+  return { closed: false, reason: 'no-signal' }
+}

package/src/config.mjs

@@ -0,0 +1,103 @@
+/**
+ * 配置解析:静态默认值 + 用户覆盖。
+ *
+ * 所有字段都有内置默认值,缺省即安全;数值一律 clamp 到可用区间,
+ * 避免误配把恢复节奏压成高频循环。
+ */
+
+export const DEFAULTS = Object.freeze({
+  graceMs: 3_000,
+  cooldownMs: 20_000,
+  maxConsecutive: 3,
+  backoffFactor: 2,
+  backoffMaxMs: 5 * 60_000,
+  scanOnBoot: true,
+  scanLimit: 8,
+  freshMs: 30 * 60_000,
+  resumeGoals: true,
+  resumePausedGoals: false,
+  resumeSilentTurns: true,
+  pauseWhenOffline: true,
+  offlineCheckMs: 15_000,
+  classify: true,
+  retryableErrorPatterns: '',
+  paused: false,
+  continueText: '继续。上一步结果未知,确认后继续。',
+  continueTextMaxTokens: '继续。上一轮被输出上限截断,分段接着输出。',
+  continueTextSilent: '继续。上一轮没有可见输出,直接说明结果或继续执行。',
+  continueTextInterrupted: '继续。上一步结果未知,确认后继续。',
+  closureText:
+    '[keepWork] 结束必须显式提交:没改文件末行单独写 TASK_DONE;任务阻塞末行单独写 TASK_BLOCKED: 原因;改过文件必须最后只使用 present;禁止同时 present 和 TASK_DONE',
+})
+
+const numberOr = (value, fallback) =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
+
+const booleanOr = (value, fallback) => (typeof value === 'boolean' ? value : fallback)
+
+const textOr = (value, fallback) =>
+  typeof value === 'string' && value.trim() !== '' ? value : fallback
+
+/** 行 config 的 volatile 字段是 boxed ref,逐字段解箱后再解析。 */
+function unwrap(entry) {
+  if (entry === null || typeof entry !== 'object') return {}
+  const out = {}
+  for (const [key, field] of Object.entries(entry)) {
+    const raw = typeof field?.get === 'function' ? field.get() : field
+    out[key] = raw !== null && typeof raw === 'object' ? structuredClone(raw) : raw
+  }
+  return out
+}
+
+/** 时长上界:超出即视为误填,按上界截断而不是让恢复实际停摆。 */
+const MAX_GRACE_MS = 5 * 60 * 1000
+const MAX_COOLDOWN_MS = 60 * 60 * 1000
+const MAX_BACKOFF_MS = 24 * 60 * 60 * 1000
+const MAX_FRESH_MS = 7 * 24 * 60 * 60 * 1000
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value))
+
+/** 覆盖解析;未知字段忽略,非法值回落默认。 */
+export function resolveConfig(input = {}, overrides = undefined) {
+  const panel = unwrap(overrides ?? {})
+  const value = { ...unwrap(input), ...Object.fromEntries(Object.entries(panel).filter(([, v]) => v !== undefined)) }
+  return {
+    graceMs: clamp(numberOr(value.graceMs, DEFAULTS.graceMs), 0, MAX_GRACE_MS),
+    cooldownMs: clamp(numberOr(value.cooldownMs, DEFAULTS.cooldownMs), 0, MAX_COOLDOWN_MS),
+    maxConsecutive: Math.max(1, numberOr(value.maxConsecutive, DEFAULTS.maxConsecutive)),
+    backoffFactor: Math.max(1, numberOr(value.backoffFactor, DEFAULTS.backoffFactor)),
+    backoffMaxMs: clamp(numberOr(value.backoffMaxMs, DEFAULTS.backoffMaxMs), 0, MAX_BACKOFF_MS),
+    scanOnBoot: booleanOr(value.scanOnBoot, DEFAULTS.scanOnBoot),
+    scanLimit: Math.max(1, numberOr(value.scanLimit, DEFAULTS.scanLimit)),
+    freshMs: clamp(numberOr(value.freshMs, DEFAULTS.freshMs), 0, MAX_FRESH_MS),
+    resumeGoals: booleanOr(value.resumeGoals, DEFAULTS.resumeGoals),
+    resumePausedGoals: booleanOr(value.resumePausedGoals, DEFAULTS.resumePausedGoals),
+    resumeSilentTurns: booleanOr(value.resumeSilentTurns, DEFAULTS.resumeSilentTurns),
+    pauseWhenOffline: booleanOr(value.pauseWhenOffline, DEFAULTS.pauseWhenOffline),
+    offlineCheckMs: Math.max(1_000, numberOr(value.offlineCheckMs, DEFAULTS.offlineCheckMs)),
+    classify: booleanOr(value.classify, DEFAULTS.classify),
+    retryableErrorPatterns:
+      typeof value.retryableErrorPatterns === 'string'
+        ? value.retryableErrorPatterns.trim()
+        : DEFAULTS.retryableErrorPatterns,
+    paused: booleanOr(value.paused, DEFAULTS.paused),
+    continueText: textOr(value.continueText, DEFAULTS.continueText),
+    continueTextMaxTokens: textOr(value.continueTextMaxTokens, DEFAULTS.continueTextMaxTokens),
+    continueTextSilent: textOr(value.continueTextSilent, DEFAULTS.continueTextSilent),
+    continueTextInterrupted: textOr(value.continueTextInterrupted, DEFAULTS.continueTextInterrupted),
+    closureText: textOr(value.closureText, DEFAULTS.closureText),
+  }
+}
+
+/** 模板占位符替换;缺失值替换为空串。 */
+export function fillTemplate(template, context = {}) {
+  return String(template).replace(/\{(\w+)\}/g, (_, key) =>
+    context[key] === undefined || context[key] === null ? '' : String(context[key]),
+  )
+}
+
+/** 连续失败后的冷却:基础冷却 × 退避因子^n,封顶。 */
+export function cooldownFor(config, consecutive) {
+  const factor = config.backoffFactor ** Math.max(0, consecutive - 1)
+  return Math.min(config.cooldownMs * factor, config.backoffMaxMs)
+}

package/src/engine.mjs

@@ -0,0 +1,240 @@
+/**
+ * 恢复引擎:消费会话事件,在需要续跑时按宿主节奏补一条用户消息。
+ *
+ * 判定与发送分离:decide 只读事件给出结论,schedule 管节奏,fire 才落地。
+ * 状态按会话驻留内存,进程重启清零(重启恢复由 scan.mjs 另行负责)。
+ */
+
+import {
+  closureVerdict,
+  hasVisibleOutput,
+  humanInitiatedTurn,
+  turnInitiator,
+  turnSlice,
+  userTookOver,
+} from './closure.mjs'
+import { cooldownFor, fillTemplate } from './config.mjs'
+import { isTransientFailure, parseFailureFacts } from './failure.mjs'
+import { isDerivedSessionHeader } from './session-kind.mjs'
+
+/** 宿主重启产生的取消原因;只有这些值得在重启后补一次。 */
+const RESTART_CANCEL_CAUSES = new Set(['disposed', 'legacy'])
+
+/** 自己发出的消息 id 只保留近期,避免长期驻留。 */
+const SENT_ID_MEMORY = 50
+
+const isSubagent = (session) => isDerivedSessionHeader(session?.header)
+
+function snapshotEvents(session) {
+  const read = session?.snapshotEvents
+  if (typeof read === 'function') return read.call(session)
+  return Array.isArray(session?.events) ? session.events : []
+}
+
+export function createEngine({
+  ctx,
+  config,
+  createUserMessage,
+  timers = globalThis,
+  now = Date.now,
+  probe,
+}) {
+  const states = new Map()
+  let disposed = false
+  let unregister
+
+  const stateOf = (sessionId) => {
+    let state = states.get(sessionId)
+    if (state === undefined) {
+      state = {
+        consecutive: 0,
+        lastAttemptAt: 0,
+        pendingTimer: undefined,
+        pending: undefined,
+        sentIds: new Set(),
+          }
+      states.set(sessionId, state)
+    }
+    return state
+  }
+
+  const log = (message) => ctx.logger?.info?.(`[keep-working] ${message}`)
+
+  function cancelPending(state, why) {
+    if (state.pendingTimer === undefined) return
+    timers.clearTimeout(state.pendingTimer)
+    state.pendingTimer = undefined
+    state.pending = undefined
+    log(`取消待发送(${why})`)
+  }
+
+  function rememberSent(state, messageId) {
+    state.sentIds.add(messageId)
+    if (state.sentIds.size <= SENT_ID_MEMORY) return
+    const oldest = state.sentIds.values().next().value
+    state.sentIds.delete(oldest)
+  }
+
+  /** 按 turn/end 的原因给出动作;undefined 表示不恢复,{ closed } 表示正常结案。 */
+  function decide(session, event, state) {
+    const turn = event.data?.turn
+    const reason = event.data?.reason ?? {}
+    const events = snapshotEvents(session)
+
+    switch (reason.kind) {
+      case 'completed': {
+        const verdict = closureVerdict(events, turn)
+        if (verdict.closed) return { closed: true }
+        // 人已插话就让路,静的回合也不抢方向
+        if (userTookOver(events, turn, state.sentIds)) return undefined
+        // 有有效文件写入时结案规则优先:没 present 就必须提醒,不能被空回合开关跳过
+        const silent = !hasVisibleOutput(turnSlice(events, turn))
+        if (silent && verdict.reason !== 'file-write-requires-present') {
+          return config.resumeSilentTurns ? { reason: 'silent', text: config.continueTextSilent } : undefined
+        }
+        if (turnInitiator(events, turn) !== 'user') return undefined
+        return { reason: 'closure', text: config.closureText }
+      }
+      case 'error': {
+        const failure = parseFailureFacts(reason.error)
+        if (failure === undefined) return undefined
+        if (config.classify && !isTransientFailure(failure, config.retryableErrorPatterns)) {
+          log(`跳过永久错误 ${failure.code}: ${failure.message}`)
+          return undefined
+        }
+        return {
+          reason: 'error',
+          text: fillTemplate(config.continueText, {
+            code: failure.code,
+            message: failure.message,
+            status: failure.status,
+          }),
+        }
+      }
+      case 'max-tokens':
+        return { reason: 'max-tokens', text: config.continueTextMaxTokens }
+      case 'interrupted':
+        return { reason: 'interrupted', text: config.continueTextInterrupted }
+      case 'aborted': {
+        if (!RESTART_CANCEL_CAUSES.has(reason.reason?.kind)) return undefined
+        return { reason: 'interrupted', text: config.continueTextInterrupted }
+      }
+      default:
+        return undefined
+    }
+  }
+
+  function fire(session, state, decision) {
+    if (disposed || config.paused) return
+    const agent = ctx.agents.get(session.id)
+    if (agent === undefined) {
+      log(`${session.id}: 无 live agent,放弃本次恢复`)
+      return
+    }
+    const message = createUserMessage({
+      content: [{ type: 'text', text: decision.text }],
+      source: { kind: 'user' },
+    })
+    try {
+      agent.followup(message)
+    } catch (error) {
+      log(`${session.id}: 投递失败 ${error instanceof Error ? error.message : String(error)}`)
+      return
+    }
+    rememberSent(state, message.id)
+    state.lastAttemptAt = now()
+    state.consecutive += 1
+    log(`${session.id}: 已发送恢复消息(${decision.reason},连续 ${state.consecutive})`)
+  }
+
+  /** 离线时挂起,联网后自会重试;探测失败按在线处理,避免永久卡住。 */
+  function settle(session, state, decision) {
+    if (!config.pauseWhenOffline || probe === undefined) {
+      fire(session, state, decision)
+      return
+    }
+    probe().then(
+      (online) => {
+        if (disposed || config.paused) return
+        if (online) {
+          fire(session, state, decision)
+          return
+        }
+        state.pendingTimer = timers.setTimeout(() => {
+          state.pendingTimer = undefined
+          settle(session, state, decision)
+        }, config.offlineCheckMs)
+      },
+      () => fire(session, state, decision),
+    )
+  }
+
+  function schedule(session, state, decision) {
+    if (disposed || config.paused) return
+    if (isSubagent(session)) return
+    if (state.pendingTimer !== undefined) return
+    if (state.consecutive >= config.maxConsecutive) {
+      log(`${session.id}: 已达连续上限 ${config.maxConsecutive},等待用户介入`)
+      return
+    }
+    const cooldown = cooldownFor(config, state.consecutive)
+    const delay = Math.max(config.graceMs, cooldown - (now() - state.lastAttemptAt))
+    state.pending = decision
+    state.pendingTimer = timers.setTimeout(() => {
+      state.pendingTimer = undefined
+      state.pending = undefined
+      settle(session, state, decision)
+    }, delay)
+  }
+
+  function onSessionEvent(session, event) {
+    if (disposed) return
+    const state = stateOf(session.id)
+    switch (event.type) {
+      case 'turn/start':
+        cancelPending(state, '新回合开始')
+        return
+      case 'turn/end':
+        return handleTurnEnd(session, state, event)
+      default:
+        return
+    }
+  }
+
+  function handleTurnEnd(session, state, event) {
+    const turn = event.data?.turn
+    cancelPending(state, '回合结束')
+    // 真人发起的回合说明人已介入:恢复额度,封顶不再永久沉默。
+    // 判定按消息 id 排除本插件自投递的消息,不依赖"下一个 turn/start 是我们的"这一猜测。
+    if (humanInitiatedTurn(snapshotEvents(session), turn, state.sentIds)) {
+      if (state.consecutive > 0) log(`${session.id}: 用户回合,连续计数清零`)
+      state.consecutive = 0
+      state.lastAttemptAt = 0
+    }
+    const decision = decide(session, event, state)
+    // 正常结案代表恢复目的已达成:清零连续计数,后续回合重新获得额度
+    if (decision?.closed === true) {
+      state.consecutive = 0
+      state.lastAttemptAt = 0
+      log(`${session.id}: 已结案,连续计数清零`)
+      return
+    }
+    if (decision !== undefined) schedule(session, state, decision)
+  }
+
+  function attach() {
+    if (unregister !== undefined) return unregister
+    unregister = ctx.on('session/event', onSessionEvent)
+    return unregister
+  }
+
+  function dispose() {
+    disposed = true
+    for (const state of states.values()) cancelPending(state, '插件卸载')
+    states.clear()
+    unregister?.()
+    unregister = undefined
+  }
+
+  return { attach, dispose, onSessionEvent }
+}

package/src/failure.mjs

@@ -0,0 +1,84 @@
+/**
+ * 失败分类:决定一次 turn/end error 是否值得自动恢复。
+ *
+ * 永久性失败(鉴权、余额、模型不存在、上下文超限、非法请求)重试必然再失败,
+ * 只会消耗额度;其余(网络、超时、5xx、429)按临时处理。
+ */
+
+/**
+ * 宿主规范错误码里的永久集合。
+ *
+ * 宿主明确要求按 code 路由而非解析文案,这些码的 message 常常是中性描述
+ * (例如 "the request failed"),只看文本会把额度耗尽、缺少适配器当成
+ * 临时错误反复重试,每次都在真实计费面上再失败一次。
+ */
+const PERMANENT_CODES = new Set([
+  'QUOTA',
+  'ACCOUNT_QUOTA',
+  'AUTH',
+  'INVALID_CREDENTIAL',
+  'MISSING_CREDENTIAL',
+  'CONTEXT_WINDOW_EXCEEDED',
+  'NO_ADAPTER',
+  'INVALID_ARGS',
+])
+
+/** 永久失败的文本特征;命中即不重试。 */
+const PERMANENT_PATTERNS = [
+  /unauthor|forbidden|api[\s_-]?key|\bauth\b|authentication|credential|permission denied|invalid token/i,
+  /insufficient.*(balance|quota|funds)|billing|payment required|quota exceeded/i,
+  // 各家额度耗尽的原文彼此不通用,补两条最常见的无码形态
+  /credit balance is too low|resource has been exhausted/i,
+  /model.*not\s*found|unknown model|does not support model/i,
+  /context.*(length|limit|overflow|exceeded)|token limit|max.*context/i,
+  /invalid[_-]?request|bad[_-]?request/i,
+  /prompt variable .* has no value/i,
+]
+
+/** 宿主会把 HTTP 状态并进 message 而非独立字段,文本里的 401/403 同样是永久信号。 */
+const PERMANENT_STATUS = /(?:^|[^\d])(401|403)(?:[^\d]|$)/
+
+const textOf = (failure) => `${failure?.code ?? ''} ${failure?.status ?? ''} ${failure?.message ?? ''}`
+
+/** 解析 turn/end 的 error 载荷;无法解释时返回 undefined。 */
+export function parseFailureFacts(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const code = typeof value.code === 'string' && value.code.trim() !== '' ? value.code : undefined
+  const message =
+    typeof value.message === 'string' && value.message.trim() !== '' ? value.message : undefined
+  const status =
+    typeof value.status === 'number' && Number.isFinite(value.status) ? value.status : undefined
+  if (code === undefined && message === undefined && status === undefined) return undefined
+  return {
+    code: code ?? 'UNKNOWN',
+    message: message ?? code ?? `HTTP ${status}`,
+    ...(status === undefined ? {} : { status }),
+  }
+}
+
+/** 自定义片段按行填写,命中即视为可重试。 */
+function matchesCustomPattern(text, patterns) {
+  if (typeof patterns !== 'string' || patterns === '') return false
+  return patterns
+    .split(/\r?\n/)
+    .map((pattern) => pattern.trim().toLowerCase())
+    .filter((pattern) => pattern !== '')
+    .some((pattern) => text.includes(pattern))
+}
+
+/**
+ * 失败是否值得自动继续。
+ * 401/403 与 MALFORMED_RESPONSE 是历史踩坑点:前者恒永久,后者的消息可能
+ * 回显工具参数里的 "api_key" 之类字样,不能按文本判永久。
+ */
+export function isTransientFailure(failure, retryableErrorPatterns = '') {
+  const text = textOf(failure).toLowerCase()
+  if (matchesCustomPattern(text, retryableErrorPatterns)) return true
+  // 规范码优先于文本:中性描述的额度与适配器错误只有 code 认得出来
+  if (typeof failure?.code === 'string' && PERMANENT_CODES.has(failure.code)) return false
+  if (failure?.status === 401 || failure?.status === 403) return false
+  if (PERMANENT_STATUS.test(text)) return false
+  if (failure?.code === 'MALFORMED_RESPONSE') return true
+  return !PERMANENT_PATTERNS.some((pattern) => pattern.test(text))
+}
+