@gehennawu/dsh-service 2.0.5 → 2.0.7

package/index.js

@@ -238,6 +238,11 @@ const QUOTA_MIN_INTERVAL_MS = 15000
 const QUOTA_MANUAL_COOLDOWN_MS = 5000
 const QUOTA_BACKOFF_BASE_MS = 30000
 const QUOTA_BACKOFF_MAX_MS = 15 * 60 * 1000
+// 确定性失败矩阵：自动重试不会改变结果，只会白打上游（CPA 还会累计 fail2ban 失败次数、把 IP 打进 30 分钟封禁）。
+// 命中即把该 provider 转入「手动模式」——此后只认手动重试这一条路，直到一次成功落定或用户改配置/凭据。
+// 表外（network / network-transient / timeout / 5xx / upstream-error / cancelled）是可能自愈的瞬时失败，
+// 保留指数退避自动重试。与 QUOTA_UNUSABLE_ERROR_RE 无关：这里只决定「还要不要自动打上游」。
+const QUOTA_MANUAL_ONLY_ERROR_RE = /^(credential-missing|credential-rejected|credentials-unavailable|no-base-url|no-subscription|host-not-pinned|mgmt-disabled|mgmt-banned|transport-unavailable|bad-payload|http-status:4\d\d|upstream-status:4\d\d)/i
 const QUOTA_CONFIG_STAT_TTL_MS = 5000
 const QUOTA_MAX_CONCURRENCY = 4
 const MAX_QUOTA_RESPONSE_BYTES = 1024 * 1024
@@ -601,9 +606,42 @@ function backupMetadataPayload(version, createdAt) {
     dshVersion: typeof version === 'string' ? version : '',
     pluginVersion: typeof pluginVersion === 'string' ? pluginVersion : '',
     createdAt: createdAt instanceof Date ? createdAt.toISOString() : new Date().toISOString(),
+    // 来源平台/架构（v0.47）：跨设备恢复时用来提示「这份快照出自哪个系统」。
+    // 与其它字段一样全部来自宿主常量，浏览器不参与；旧版插件读新归档时忽略这两个键。
+    platform: process.platform,
+    arch: process.arch,
   }, null, 2)}\n`, 'utf8')
 }
 
+// 目标平台的事实来源：执行恢复的那台机器的进程平台。声明式覆盖只服务测试与验证
+// （与 DSH_SERVICE_RUNTIME_ENV 同规），它只能影响只读提示与错误措辞，**不放宽**任何
+// 归档校验——否则「声明成 Linux」就成了把 Windows 非法文件名塞进写入路径的后门。
+function readBackupPlatform() {
+  const declared = process.env.DSH_SERVICE_BACKUP_PLATFORM
+  return typeof declared === 'string' && /^[a-z][a-z0-9_-]{0,15}$/.test(declared) ? declared : process.platform
+}
+
+// 目标机可用于承载恢复内容的 profile 名清单（宿主侧 readdir 事实，浏览器只在该清单内
+// 选名字）。名字口径与备份侧白名单同规：单一路径段、长度封顶。
+async function listLocalProfiles(dshHome) {
+  const root = join(dshHome, 'profiles')
+  let entries
+  try { entries = await readdir(root, { withFileTypes: true }) } catch (error) {
+    if (error?.code === 'ENOENT') return []
+    throw error
+  }
+  const profiles = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^[A-Za-z0-9._-]{1,64}$/.test(entry.name) || entry.name === '.' || entry.name === '..') continue
+    profiles.push({
+      name: entry.name,
+      hasManifest: await pathExists(join(root, entry.name, 'package.json')),
+      hasPatch: await pathExists(join(root, entry.name, 'cordis.patch.yml')),
+    })
+  }
+  return profiles.sort((a, b) => a.name.localeCompare(b.name))
+}
+
 // 从归档名解析版本段（列表展示用，零 I/O）。只有 Host 自己签发的名字会走到这里，
 // 但正则本身也保证不会把任意文本当版本号回给浏览器。
 function backupVersionFromName(name) {
@@ -1258,7 +1296,11 @@ async function exportBackup(dshHome, downloadTokens, id) {
 // 版本事实以归档内的 meta/backup.json 为准，不改名、不重写。
 async function importBackup(dshHome, name, encoded, validatePath) {
   if (typeof name !== 'string' || !BACKUP_NAME.test(name) || typeof encoded !== 'string' || encoded.length === 0) return undefined
-  if (encoded.length > Math.ceil(MAX_BACKUP_TRANSFER_BYTES / 3) * 4 + 8 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) return undefined
+  // 只线性扫描字符；对大文件使用重复分组正则会耗尽 V8 正则调用栈。
+  // 长度、填充位置和解码后重新编码的逐字节一致性仍共同约束规范 Base64。
+  if (encoded.length > Math.ceil(MAX_BACKUP_TRANSFER_BYTES / 3) * 4 + 8 || encoded.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(encoded)) return undefined
+  const padding = encoded.indexOf('=')
+  if (padding !== -1 && (padding < encoded.length - 2 || !/^[A-Za-z0-9+/]{2,3}={1,2}$/.test(encoded.slice(-4)))) return undefined
   const data = Buffer.from(encoded, 'base64')
   if (data.length === 0 || data.length > MAX_BACKUP_TRANSFER_BYTES || data.toString('base64') !== encoded) return undefined
   const backupDir = join(dshHome, 'backups')
@@ -2237,8 +2279,9 @@ async function requestQuotaJson(endpoint, options = {}) {
 }
 
 // 每 provider 节流状态机（内存态，重启清零）。一切来源共用同一判定，优先序：
-// 单飞去重 > 失败指数退避（30s×2 封顶 15min）> 成功 TTL 60s > 最小上游间隔 15s（与 attempt()
-// 判定序一致）；now 由调用方注入，测试可推进假时钟。
+// 单飞去重 > 确定性失败后的手动模式 > 失败指数退避（30s×2 封顶 15min）> 成功 TTL 60s >
+// 最小上游间隔 15s（与 attempt() 判定序一致）；手动模式只由「一次成功落定」或用户写操作
+// （resetGates）解除，中途不会因时间流逝自动恢复。now 由调用方注入，测试可推进假时钟。
 function createQuotaThrottle(options = {}) {
   const successTtlMs = options.successTtlMs ?? QUOTA_SUCCESS_TTL_MS
   const minIntervalMs = options.minIntervalMs ?? QUOTA_MIN_INTERVAL_MS
@@ -2249,7 +2292,7 @@ function createQuotaThrottle(options = {}) {
   const entryOf = (provider) => {
     let entry = entries.get(provider)
     if (entry === undefined) {
-      entry = { lastSuccessAt: 0, lastUpstreamAt: 0, lastManualAt: 0, backoffUntil: 0, failures: 0, inflight: false, windows: undefined, fetchedAt: 0, lastError: undefined, lastErrorDetail: undefined, lastErrorEndpoint: undefined, lastErrorAccount: undefined }
+      entry = { lastSuccessAt: 0, lastUpstreamAt: 0, lastManualAt: 0, backoffUntil: 0, failures: 0, inflight: false, manualOnly: false, windows: undefined, fetchedAt: 0, lastError: undefined, lastErrorDetail: undefined, lastErrorEndpoint: undefined, lastErrorAccount: undefined }
       entries.set(provider, entry)
     }
     return entry
@@ -2269,7 +2312,7 @@ function createQuotaThrottle(options = {}) {
         lastErrorAccount: entry.lastErrorAccount,
       }
     },
-    /** 只读快照：缓存窗口、是否刷新中、下次允许发起上游的时间（null=进行中未知）。 */
+    /** 只读快照：缓存窗口、是否刷新中、是否已转手动、下次允许自动发起上游的时间（null=进行中/手动模式）。 */
     view(provider, now = Date.now()) {
       const entry = entryOf(provider)
       return {
@@ -2280,21 +2323,28 @@ function createQuotaThrottle(options = {}) {
         lastErrorDetail: entry.lastErrorDetail,
         lastErrorEndpoint: entry.lastErrorEndpoint,
         lastErrorAccount: entry.lastErrorAccount,
-        nextAllowedAt: entry.inflight
+        // 手动模式：自动路径一律拒发，故没有「下次自动重试时刻」可报（客户端据此换文案）。
+        manualOnly: entry.manualOnly === true,
+        nextAllowedAt: entry.inflight || entry.manualOnly
           ? null
           : Math.max(entry.backoffUntil, entry.lastUpstreamAt + minIntervalMs, entry.lastSuccessAt + successTtlMs),
       }
     },
-    /** 申请一次上游调用。允许则置单飞并返回 ok；拒绝时给出稳定原因与 nextAllowedAt（优先序：单飞 > 退避 > 成功 TTL > 最小间隔）。 */
-    attempt(provider, now = Date.now()) {
+    /** 申请一次上游调用。允许则置单飞并返回 ok；拒绝时给出稳定原因与 nextAllowedAt
+     * （优先序：单飞 > 手动模式 > 退避 > 成功 TTL > 最小间隔）。
+     * options.manual=true 是「用户手动连接」：跳过手动模式与三道时间闸，只受 force() 的冷却约束。 */
+    attempt(provider, now = Date.now(), options = {}) {
       const entry = entryOf(provider)
       if (entry.inflight) return { ok: false, reason: 'inflight', nextAllowedAt: null }
-      if (now < entry.backoffUntil) return { ok: false, reason: 'backoff', nextAllowedAt: entry.backoffUntil }
-      if (now - entry.lastSuccessAt < successTtlMs) {
-        return { ok: false, reason: 'fresh', nextAllowedAt: entry.lastSuccessAt + successTtlMs }
-      }
-      if (entry.lastUpstreamAt > 0 && now - entry.lastUpstreamAt < minIntervalMs) {
-        return { ok: false, reason: 'interval', nextAllowedAt: entry.lastUpstreamAt + minIntervalMs }
+      if (options.manual !== true) {
+        if (entry.manualOnly) return { ok: false, reason: 'manual-only', nextAllowedAt: null }
+        if (now < entry.backoffUntil) return { ok: false, reason: 'backoff', nextAllowedAt: entry.backoffUntil }
+        if (now - entry.lastSuccessAt < successTtlMs) {
+          return { ok: false, reason: 'fresh', nextAllowedAt: entry.lastSuccessAt + successTtlMs }
+        }
+        if (entry.lastUpstreamAt > 0 && now - entry.lastUpstreamAt < minIntervalMs) {
+          return { ok: false, reason: 'interval', nextAllowedAt: entry.lastUpstreamAt + minIntervalMs }
+        }
       }
       entry.inflight = true
       entry.lastUpstreamAt = now
@@ -2308,6 +2358,8 @@ function createQuotaThrottle(options = {}) {
         entry.lastSuccessAt = now
         entry.failures = 0
         entry.backoffUntil = 0
+        // 唯一解锁点（除 resetGates 的用户写操作外）：一次成功落定即回归自动模式。
+        entry.manualOnly = false
         entry.windows = outcome.windows ?? []
         entry.fetchedAt = now
         entry.lastError = undefined
@@ -2320,27 +2372,29 @@ function createQuotaThrottle(options = {}) {
       const delay = Math.min(backoffBaseMs * 2 ** (entry.failures - 1), backoffMaxMs)
       entry.backoffUntil = now + delay
       entry.lastError = typeof outcome.code === 'string' ? outcome.code : 'unknown'
+      // 确定性失败（换凭据/改配置才可能恢复）→ 转手动模式：自动快照不再重打上游。
+      // 瞬时失败保持自动退避，等下一轮快照接续。
+      if (QUOTA_MANUAL_ONLY_ERROR_RE.test(entry.lastError)) entry.manualOnly = true
       entry.lastErrorDetail = typeof outcome.detail === 'string' && outcome.detail !== '' ? outcome.detail : undefined
       // 渠道特有事实（多候选链的失败端点 / CPA 的失败账号）：只作附注，与错误码、上游原话分开存。
       entry.lastErrorEndpoint = sanitizeQuotaErrorDetail(outcome.endpoint)
       entry.lastErrorAccount = sanitizeQuotaErrorDetail(outcome.account)
     },
-    /** 手动刷新：允许绕过成功 TTL，但保留失败退避，并有不可绕过的硬冷却；单飞仍优先。 */
+    /** 手动重试的准入判定：只受单飞与不可绕过的硬冷却约束——手动模式与失败退避都由调用方的
+     * attempt({ manual: true }) 跳过（用户明确要求「仅可手动连接报错的渠道」，手动不该比自动更受限）。 */
     force(provider, now = Date.now()) {
       const entry = entryOf(provider)
       if (entry.inflight) return { ok: false, reason: 'inflight', nextAllowedAt: null }
-      if (now < entry.backoffUntil) return { ok: false, reason: 'backoff', nextAllowedAt: entry.backoffUntil }
       if (entry.lastManualAt > 0 && now - entry.lastManualAt < manualCooldownMs) {
         return { ok: false, reason: 'cooldown', nextAllowedAt: entry.lastManualAt + manualCooldownMs }
       }
       entry.lastManualAt = now
-      entry.lastSuccessAt = 0
-      entry.lastUpstreamAt = 0
       return { ok: true }
     },
     // 凭据/适配变更后的闸门重置（保存 key/Cookie、改适配类型时调用）：旧失败是旧配置造成的，
     // 填完就该立刻重试，不傻等最长 15min 的指数退避（GUI 反馈点名）；单飞在途不抢占。
-    // 与 force() 的区别：本方法只由宿主写入口触发，可以连硬冷却一并清掉。
+    // 这也是手动模式唯一的「非成功解锁」路径——保存凭据/改适配本身就是用户的手动动作，
+    // 且凭据类错误的「手动连接」正是保存后立刻重试。与 force() 的区别：连硬冷却一并清掉。
     resetGates(provider) {
       const entry = entryOf(provider)
       if (entry.inflight) return { ok: false, reason: 'inflight', nextAllowedAt: null }
@@ -2349,6 +2403,7 @@ function createQuotaThrottle(options = {}) {
       entry.lastManualAt = 0
       entry.lastUpstreamAt = 0
       entry.lastSuccessAt = 0
+      entry.manualOnly = false
       return { ok: true }
     },
     prune(activeProviders) {
@@ -5266,6 +5321,11 @@ function apply(ctx, featureConfig) {
     runtimeEnv,
     previousInstanceId: instanceId,
     scheduleRestart: () => scheduleRestart(ctx, runtimeEnv),
+    // 目标平台与目标 profile 清单都由宿主侧事实提供：恢复发生在哪台机器上，
+    // 就以哪台机器的进程平台与 profiles 目录为准，浏览器不参与判定。
+    platform: readBackupPlatform(),
+    // 工厂只要名字清单（映射校验用）；端点另取带 hasManifest/hasPatch 的完整形态。
+    listProfiles: async () => (await listLocalProfiles(dshHome)).map((profile) => profile.name),
   })
   // 会话管理（v0.35）：删除两段式计划（planId → {id, path, bytes}），TTL 过期自动驱逐。
   const sessionDeletePlans = new Map()
@@ -5365,12 +5425,13 @@ function apply(ctx, featureConfig) {
   const subagentSeamRef = { current: false }
   // 子代理派发记录环（v1.2）：apply 级持有，RPC 端点与 seam 共同读写（seam 写入、端点只读）。
   const dispatchRing = { order: [], byChild: new Map() }
-  // 只包装宿主 subagents 注册表的两个入口（start / startContinuable，spawn/fork/acp 全走这
-  // 两个口）：未显式指定模型的派生按配置注入 agentOptions，其余原样透传。Fiber 销毁还原
-  // 原方法——包装挂在服务实例上，disposer 期间新派生恢复原生行为。
+  // 按宿主能力包装子代理启动入口：新版 startActivation，旧版 start/startContinuable。
+  // 未显式指定模型的派生按配置注入 agentOptions，其余原样透传；Fiber 销毁时还原原方法。
   ctx.inject(['subagents'], (scope) => {
     const subagents = scope.subagents
-    if (subagents === undefined || typeof subagents.start !== 'function' || typeof subagents.startContinuable !== 'function') return
+    const hasActivation = typeof subagents?.startActivation === 'function'
+    const hasLegacyStarts = typeof subagents?.start === 'function' && typeof subagents?.startContinuable === 'function'
+    if (!hasActivation && !hasLegacyStarts) return
     const isRoutable = (provider) => {
       const llm = ctx.get('llm')
       if (llm === undefined || typeof llm.listProviders !== 'function') return false
@@ -5460,15 +5521,24 @@ function apply(ctx, featureConfig) {
       if (dispatch === undefined) return work()
       return pendingDispatchStorage.run(dispatch, work)
     }
+    const originalStartActivation = subagents.startActivation
     const originalStart = subagents.start
     const originalStartContinuable = subagents.startContinuable
-    subagents.start = (name, request) => {
-      const { request: decorated, dispatch } = applyInjection(request)
-      return runWithDispatch(dispatch, () => originalStart.call(subagents, name, decorated))
-    }
-    subagents.startContinuable = (spec) => {
-      const { request: decorated, dispatch } = applyInjection(spec.request)
-      return runWithDispatch(dispatch, () => originalStartContinuable.call(subagents, { ...spec, request: decorated }))
+    if (hasActivation) {
+      subagents.startActivation = (spec) => {
+        const { request: decorated, dispatch } = applyInjection(spec.request)
+        if (dispatch === undefined) return originalStartActivation.call(subagents, spec)
+        return runWithDispatch(dispatch, () => originalStartActivation.call(subagents, { ...spec, request: decorated }))
+      }
+    } else {
+      subagents.start = (name, request) => {
+        const { request: decorated, dispatch } = applyInjection(request)
+        return runWithDispatch(dispatch, () => originalStart.call(subagents, name, decorated))
+      }
+      subagents.startContinuable = (spec) => {
+        const { request: decorated, dispatch } = applyInjection(spec.request)
+        return runWithDispatch(dispatch, () => originalStartContinuable.call(subagents, { ...spec, request: decorated }))
+      }
     }
     // agent/created（0.1.6 起由 announce await ctx.serial 异步串行派发；0.1.5 及之前同步派发在创建栈内）：
     // 记录派发路由 + 绑定等级（仅当确有非空等级）。监听器内部全 try/catch 严格保证绝不抛错，
@@ -5548,8 +5618,11 @@ function apply(ctx, featureConfig) {
     }, { prepend: true }) : null
     subagentSeamRef.current = true
     scope.effect(() => () => {
-      subagents.start = originalStart
-      subagents.startContinuable = originalStartContinuable
+      if (hasActivation) subagents.startActivation = originalStartActivation
+      else {
+        subagents.start = originalStart
+        subagents.startContinuable = originalStartContinuable
+      }
       if (typeof disposeCreated === 'function') disposeCreated()
       if (typeof disposeRequest === 'function') disposeRequest()
       if (typeof disposeRequestError === 'function') disposeRequestError()
@@ -5661,8 +5734,10 @@ function apply(ctx, featureConfig) {
   }
   // 远端额度：后台补拉一次。index.js 只提供节流/生命周期/受控传输 context；所有方言、
   // 端点、凭据策略与编排都通过同一 Adapter interface 执行，不再区分 parser/fetcher 形状。
-  const kickQuotaRefresh = (profile, adapter, config) => {
-    const decision = quotaThrottle.attempt(profile.name)
+  // options.manual=true 只由 quota-refresh（手动重试/连接）传入：跳过手动模式与三道时间闸，
+  // 是「确定性失败转手动」之后唯一还能打上游的路径。
+  const kickQuotaRefresh = (profile, adapter, config, options = {}) => {
+    const decision = quotaThrottle.attempt(profile.name, Date.now(), { manual: options.manual === true })
     if (!decision.ok) return
     const queued = enqueueQuotaWork(async () => {
       const controller = new AbortController()
@@ -6127,7 +6202,7 @@ function apply(ctx, featureConfig) {
     createSessionsRoutes({ ctx, dshHome, sessionBytesCache, sessionDeletePlans, sessionTitleCache, sessionTitlesReady, sessionViewCache, SESSIONS_BYTES_MAX_IDS, SESSIONS_DELETE_PLAN_TTL_MS, SESSIONS_VIEW_PAGE_SIZE, listSessionsForManage, loadDeletedSessions, name, resolveSessionBytesForIds, resolveSessionForDelete, rpcFailure, rpcTechnicalFailure, saveDeletedSessions, searchSessionsContent, sessionExists, sessionIsLive, viewSessionPage }),
     createQuotaRoutes({ ctx, kickQuotaRefresh, quotaThrottle, refreshQuotaConfigCache, serializeQuotaConfigWrite, MAX_QUOTA_PROVIDER_NAME, MAX_QUOTA_RESET_CARDS, MAX_QUOTA_RESET_CARDS_PER_PROVIDER, MAX_QUOTA_RESET_CARD_ACCOUNT, canonicalResetCardExpiresAt, QUOTA_ADAPTER_BY_KIND, name, quotaCredentialConfigured, quotaCredentialEndpoint, quotaCredentialHintNames, readQuotaProfiles, resolveQuotaKind, rpcTechnicalFailure }),
     createSubagentRoutes({ ctx, dispatchRing, serializeSubagentRouteWrite, subagentRouteRef, subagentRouteLoadPromise, subagentSeamRef, MAX_SUBAGENT_ROUTE_FIELD, SUBAGENT_ROUTE_FALLBACK_MAX, SUBAGENT_ROUTE_MODES, listSubagentDispatches, listSubagentModels, rpcTechnicalFailure }),
-    createBackupRoutes({ ctx, backupIntegrity, backupProgress, clearBackupProgress, downloadTokens, dshHome, dshVersion, setBackupProgress, withBackupLock, backupNameVersionSuffix, createBackup, deleteBackup, exportBackup, formatBackupTimestamp, importBackup, listBackups, name, rpcFailure }),
+    createBackupRoutes({ ctx, backupIntegrity, backupProgress, clearBackupProgress, downloadTokens, dshHome, dshVersion, setBackupProgress, withBackupLock, backupNameVersionSuffix, createBackup, deleteBackup, exportBackup, formatBackupTimestamp, importBackup, listBackups, listLocalProfiles, name, rpcFailure }),
   ])
 
   const dispatchEndpoint = createRpcDispatcher({ endpoints: rpcEndpoints, featureEnabled, logger: ctx.logger })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gehennawu/dsh-service",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "DSH Web 运维面板：安全重启、健康监控、备份和 Linux 权限维护。",
   "type": "module",
   "scripts": {
@@ -52,7 +52,7 @@
   "homepage": "https://github.com/gehennawu/dsh-service#readme",
   "engines": {
     "node": ">=22",
-    "dsh": ">=0.1.1-rc.2 <0.2.1-alpha.2"
+    "dsh": ">=0.1.1-rc.2 <0.2.1-alpha.3"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.3"

package/quota-adapters.js

@@ -1110,6 +1110,37 @@ function parseCliproxyUpstream(provider, payload) {
   return normalizeGeminiBuckets(payload?.buckets)
 }
 
+// 管理面 403 的三种语义（上游 `internal/api/handlers/management/handler.go` 原文）：
+//   · `IP banned due to too many failed attempts. Try again in 29m10s` —— fail2ban 封禁（实测 2026-10-10）
+//   · `remote management disabled` / `remote management key not set` —— 管理面没开或没配密钥
+// 三者与「密钥填错」（401 `invalid management key`）完全不同，必须分开归类，否则用户对着一句
+// 状态码猜：填错要给重填入口，封禁/未开启给重填入口是误导。
+const CLIPROXY_BANNED_DETAIL_RE = /IP banned due to too many failed attempts/i
+const CLIPROXY_MGMT_OFF_DETAIL_RE = /remote management (?:disabled|key not set)/i
+
+/** CPA 管理面失败归类：401/403 = 管理密钥被拒（与其余 11 个 kind 同款，行回 unconfigured 就地重填）；
+ *  封禁 → mgmt-banned（专属码，给等待/换出口 IP 的指引）；远程管理未开启 → mgmt-disabled。 */
+function cliproxyManagementFailure(error) {
+  const detail = sanitizeQuotaErrorDetail(error?.detail)
+  if (detail !== undefined && CLIPROXY_BANNED_DETAIL_RE.test(detail)) {
+    const banned = new Error('mgmt-banned')
+    banned.detail = detail
+    return banned
+  }
+  if (detail !== undefined && CLIPROXY_MGMT_OFF_DETAIL_RE.test(detail)) {
+    const disabled = new Error('mgmt-disabled')
+    disabled.detail = detail
+    return disabled
+  }
+  const message = typeof error?.message === 'string' ? error.message : ''
+  if (message === 'http-status:401' || message === 'http-status:403') {
+    const rejected = new Error('credential-rejected')
+    if (detail !== undefined) rejected.detail = detail
+    return rejected
+  }
+  return error
+}
+
 async function fetchCliproxyUsage({ profile, config, credential, signal, requestJson }) {
   if (typeof requestJson !== 'function') throw new Error('transport-unavailable')
   const pinned = Array.isArray(config?.allowedHosts?.[profile.name]) ? config.allowedHosts[profile.name] : []
@@ -1119,8 +1150,9 @@ async function fetchCliproxyUsage({ profile, config, credential, signal, request
   try {
     filesPayload = await requestJson(`${origin}/v0/management/auth-files`, { authorization: credential, signal })
   } catch (error) {
+    // secret-key 为空时管理路由整体不注册 → 404（既有口径，先于其余归类）。
     if (error?.message === 'http-status:404') throw new Error('mgmt-disabled')
-    throw error
+    throw cliproxyManagementFailure(error)
   }
   const files = Array.isArray(filesPayload?.files) ? filesPayload.files : []
   const accounts = []
@@ -1162,8 +1194,12 @@ async function fetchCliproxyUsage({ profile, config, credential, signal, request
           body: JSON.stringify({ auth_index: account.authIndex, method: call.method, url: call.url, header: call.header, data: call.data }),
         })
       } catch (error) {
-        const detail = sanitizeQuotaErrorDetail(error?.detail)
-        pushFailure(accountIndex, quotaErrorCode(error), detail !== undefined ? { detail } : {})
+        // 管理面自身失败（密钥被拒 / 封禁 / 管理面未开）：与账号级上游失败（HTTP 200 信封里的
+        // status_code）严格分开。密钥在 api-call 途中失效或撞上封禁时，整行必须给出可行动指引，
+        // 而不是一个 upstream-status 家族码。
+        const failure = cliproxyManagementFailure(error)
+        const detail = sanitizeQuotaErrorDetail(failure?.detail)
+        pushFailure(accountIndex, quotaErrorCode(failure), detail !== undefined ? { detail } : {})
         const fallback = cliproxFallbackWindows(account)
         if (fallback.length > 0) {
           accountResults.set(accountIndex, fallback)

package/quota-routes.js

@@ -66,10 +66,12 @@ export function createQuotaRoutes({
           // 漏掉它会把卡片锁死在错误态，用户找不到任何入口（GUI 反馈「失效后无法再次填入」）。
           const credentialClass = view.lastError === 'credential-missing' || view.lastError === 'no-base-url' || view.lastError === 'credentials-unavailable' || view.lastError === 'credential-rejected'
           const providerResetCards = resetCardsByProvider.get(profile.name) ?? []
-          // 凭据填写窗口的数据源：仅对「缺凭据」的未配置行附带候选线索名的配置状态（describe 只回
-          // 配置与否/来源/可写，绝不带值）；凭据服务缺席时省略字段——客户端隐藏窗口退回文案指引。
+          // 凭据窗口的数据源：**已适配行一律附带**候选线索名的配置状态，不再以「未配置」为门槛——
+          // 已保存的凭据（密钥轮换、换账号、填错想改）此前没有任何 GUI 修改入口（用户点名）。
+          // describe 只回配置与否/来源/可写，绝不带值，且是内存查询；凭据服务缺席时省略字段，
+          // 客户端随之隐藏入口、退回文案指引。
           let credentialHints
-          if (credentialClass && !view.refreshing && view.lastError !== 'no-base-url') {
+          {
             const credentials = ctx.get('credentials')
             if (credentials !== undefined && typeof credentials.describe === 'function') {
               const described = []
@@ -103,6 +105,8 @@ export function createQuotaRoutes({
             ...(view.lastErrorEndpoint !== undefined ? { errorEndpoint: view.lastErrorEndpoint } : {}),
             ...(view.lastErrorAccount !== undefined ? { errorAccount: view.lastErrorAccount } : {}),
             nextAllowedAt: view.nextAllowedAt,
+            // 确定性失败后的手动模式：客户端据此把「{time} 后可重试」换成「自动重试已暂停」。
+            ...(view.manualOnly === true ? { manualOnly: true } : {}),
             ...(providerResetCards.length > 0 ? { resetCards: providerResetCards } : {}),
             ...(credentialHints !== undefined ? { credentialHints } : {}),
             // 凭据入口语义由 Adapter policy 下发稳定键，客户端只负责本地化，不再对 kind 重复分支。
@@ -119,8 +123,10 @@ export function createQuotaRoutes({
     } },
     'quota-refresh': { feature: 'quotaLookup', audit: true, handle: async (payload, rpcEndpoint) => {
       try {
-        // 手动刷新入口：provider 过白名单且 kind 已适配；清掉节流闸后立即 kick。
-        // 单飞仍生效（在途时本次点击为 no-op）；上游结果经后续 quota 快照带出，不在此等待。
+        // 手动重试/连接入口：provider 过白名单且 kind 已适配；这是「确定性失败转手动模式」之后
+        // 唯一还能打上游的路径（kick 带 manual 标记，跳过手动模式与退避/TTL/间隔三道闸）。
+        // 单飞仍生效（在途时本次点击为 no-op）；只受不可绕过的手动冷却约束；上游结果经后续
+        // quota 快照带出，不在此等待。
         const providerName = typeof payload?.provider === 'string' ? payload.provider : ''
         const profile = readQuotaProfiles(ctx.get('settings'), ctx.get('llm')).find((candidate) => candidate.name === providerName)
         if (profile === undefined) return { ok: false, error: 'unknown-provider' }
@@ -130,9 +136,9 @@ export function createQuotaRoutes({
         const forced = quotaThrottle.force(providerName)
         if (!forced.ok) {
           if (forced.reason === 'inflight') return { ok: true }
-          return { ok: false, error: forced.reason === 'cooldown' ? 'refresh-cooldown' : 'refresh-backoff', nextAllowedAt: forced.nextAllowedAt }
+          return { ok: false, error: 'refresh-cooldown', nextAllowedAt: forced.nextAllowedAt }
         }
-        kickQuotaRefresh(profile, adapter, config)
+        kickQuotaRefresh(profile, adapter, config, { manual: true })
         return { ok: true }
       } catch (error) {
         return rpcTechnicalFailure(error)