Merge pull request #833 from AAEE86/feat/usage-skipped-candidates

feat(usage): 展示调度跳过候选及原因并补齐手机端提示

frontend/src/api/usageRecords.ts

@@ -65,5 +65,13 @@ export interface UsageRecord {
   response_time_updated_at?: string | null
   has_fallback?: boolean
   has_retry?: boolean
+  /**
+   * 是否存在被调度跳过的候选（候选在调度阶段即被判定不可用，从未向上游发起请求）。
+   * 与 has_fallback 的区别：has_fallback 代表"更靠前的候选真的失败了"，
+   * 本字段代表"更靠前的候选压根没被发出去"，用于解释"无报错却换了提供商"。
+   */
+  has_skipped_candidate?: boolean
+  /** 被跳过候选的原因列表（后端已按候选顺序去重） */
+  skipped_candidate_reasons?: string[]
   image_progress?: ImageProgress | null
 }

frontend/src/features/usage/components/HorizontalRequestTimeline.vue

@@ -36,6 +36,21 @@
               <Badge :variant="getFinalStatusBadgeVariant(computedFinalStatus)">
                 {{ getFinalStatusLabel(computedFinalStatus) }}
               </Badge>
+              <!-- 被跳过的候选可以收起，避免长时间线上排查时干扰视线 -->
+              <button
+                v-if="skippedTraceCandidates.length > 0"
+                type="button"
+                class="skipped-toggle"
+                :class="{ active: showSkippedCandidates }"
+                :aria-pressed="showSkippedCandidates"
+                :title="showSkippedCandidates
+                  ? '隐藏被跳过的候选'
+                  : '被跳过的候选在调度阶段就被判定本次不可用，从未向上游发起请求'"
+                data-timeline-skipped-toggle
+                @click="showSkippedCandidates = !showSkippedCandidates"
+              >
+                {{ showSkippedCandidates ? '隐藏' : '显示' }}被跳过候选（{{ skippedTraceCandidates.length }}）
+              </button>
             </div>
             <div class="text-sm text-muted-foreground">
               {{ formatLatency(totalTraceLatency) }}
@@ -449,7 +464,7 @@
                   v-if="currentAttemptSkipReasonDisplay"
                   class="skip-reason"
                 >
-                  <span class="reason-label">跳过原因</span>
+                  <span class="reason-label">{{ currentAttemptSkipReasonLabel }}</span>
                   <span class="reason-content">
                     <span class="reason-value">{{ currentAttemptSkipReasonDisplay }}</span>
                     <span
@@ -586,6 +601,7 @@ import { resolveTimelineFinalStatus } from '../utils/status'
 import { useClipboard } from '@/composables/useClipboard'
 import { buildFailureDiagnosticBundle, diagnosticPathFromMessage, visibleFailureRecords } from '../utils/failureDiagnostic'
 import { prepareDiagnosticExport, sanitizeDiagnostic } from '../utils/diagnosticExport'
+import { formatCandidateSkipReason } from '../utils/skipReason'
 import {
   buildPoolGroupVisibleAttempts,
   buildPoolParticipatedCandidates,
@@ -841,13 +857,30 @@ const compareBySchedulingOrder = (a: CandidateRecord, b: CandidateRecord): numbe
 }
 
 // 候选时间线（按调度顺序排序；lazy 加载的跳过候选通常没有 started_at）
-const rawTimeline = computed<CandidateRecord[]>(() => {
+const allTraceCandidates = computed<CandidateRecord[]>(() => {
   if (!trace.value) return []
   return [...trace.value.candidates]
     .filter(c => TIMELINE_STATUS.includes(c.status))
     .sort(compareBySchedulingOrder)
 })
 
+/**
+ * 被跳过的候选：调度阶段就判定"这次不能用"，从未真正向上游发起请求。
+ *
+ * 默认展示：它是"为什么这次没用优先级更高的提供商"的直接答案，
+ * 隐藏后容易让人误以为该提供商从未参与调度。开关供长时间排查时收起。
+ */
+const showSkippedCandidates = ref(true)
+
+const skippedTraceCandidates = computed<CandidateRecord[]>(
+  () => allTraceCandidates.value.filter(c => c.status === 'skipped'),
+)
+
+const rawTimeline = computed<CandidateRecord[]>(() => {
+  if (showSkippedCandidates.value) return allTraceCandidates.value
+  return allTraceCandidates.value.filter(c => c.status !== 'skipped')
+})
+
 
 const schedulingAudit = computed<Record<string, unknown> | null>(() => {
   const metadata = props.requestMetadata
@@ -1233,7 +1266,12 @@ const latestTraceAttemptForState = computed<CandidateRecord | null>(() => {
   const candidates = rawTimeline.value
   for (let index = candidates.length - 1; index >= 0; index -= 1) {
     const candidate = candidates[index]
-    if (candidate.status !== 'available' && candidate.status !== 'unused') {
+    // 跳过/未使用候选没有状态码与错误信息，不能代表本次请求的最终结果。
+    if (
+      candidate.status !== 'available' &&
+      candidate.status !== 'unused' &&
+      candidate.status !== 'skipped'
+    ) {
       return candidate
     }
   }
@@ -1418,35 +1456,30 @@ const currentAttemptKeyFormatsDisplay = computed(() => {
     .map(format => formatApiFormat(format))
     .join(' / ')
 })
-const SKIP_REASON_LABELS: Record<string, string> = {
-  auth_api_key_concurrency_limit_reached: '调用方 API Key 并发已达上限',
-  api_key_concurrency_limit_reached: '调用方 API Key 并发已达上限',
-  pool_key_lease_busy: '池内账号正被其他请求占用',
-  provider_concurrency_limit_reached: '上游提供商并发已达上限',
-  provider_key_concurrency_limit_reached: '上游账号并发已达上限',
-  provider_request_body_build_failed: '上游请求体转换失败',
-  provider_request_body_missing: '无法构建上游请求体',
-}
 const currentAttemptSkipReasonDisplay = computed(() => {
   const attempt = currentAttempt.value
   if (!attempt?.skip_reason) return ''
 
-  const skipReasonLabel = SKIP_REASON_LABELS[attempt.skip_reason]
-  if (skipReasonLabel) {
-    return skipReasonLabel
+  // transport_unsupported 这类"泛化原因"优先展示后端采集到的具体细节，便于排查。
+  if (attempt.skip_reason === 'transport_unsupported') {
+    const transportDiagnostics = resolveTransportDiagnostics(attempt)
+    const requestPair = extractObject(transportDiagnostics?.request_pair)
+    const detailedReason = typeof requestPair?.transport_unsupported_reason === 'string'
+      ? requestPair.transport_unsupported_reason.trim()
+      : ''
+    return detailedReason || formatCandidateSkipReason(attempt.skip_reason)
   }
 
-  if (attempt.skip_reason !== 'transport_unsupported') {
-    return attempt.skip_reason
-  }
+  return formatCandidateSkipReason(attempt.skip_reason)
+})
 
-  const transportDiagnostics = resolveTransportDiagnostics(attempt)
-  const requestPair = extractObject(transportDiagnostics?.request_pair)
-  const detailedReason = typeof requestPair?.transport_unsupported_reason === 'string'
-    ? requestPair.transport_unsupported_reason.trim()
-    : ''
-
-  return detailedReason || attempt.skip_reason
+/**
+ * 区分"跳过"与"尝试失败"：被跳过的候选从未发到上游，
+ * 不写清楚容易被误读成"上游返回了错误"。
+ */
+const currentAttemptSkipReasonLabel = computed(() => {
+  const status = currentAttempt.value?.status
+  return status === 'skipped' ? '跳过原因（未向上游发起请求）' : '跳过原因'
 })
 
 const currentAttemptFailureDiagnostic = computed<{
@@ -2212,7 +2245,9 @@ const loadTrace = async (silent = false) => {
     error.value = null
 
     try {
-      internalTrace.value = await requestTraceApi.getRequestTrace(requestId, { attemptedOnly: true })
+      // 始终拉取全部候选：被跳过的候选是"为什么没用某个提供商"的关键证据，
+      // 是否显示由前端开关控制，避免再发一次请求。
+      internalTrace.value = await requestTraceApi.getRequestTrace(requestId, { attemptedOnly: false })
     } catch (err: unknown) {
       if (isAxiosError(err) && err.response?.status === 404) {
         internalTrace.value = null
@@ -2798,6 +2833,30 @@ function getDisplayStatus(attempt: CandidateRecord | null | undefined): string {
   cursor: not-allowed;
 }
 
+/* 「显示/隐藏被跳过候选」开关：低调的描边小按钮，不抢主状态徽标的视觉重心 */
+.skipped-toggle {
+  padding: 0.125rem 0.5rem;
+  border: 1px dashed hsl(var(--border));
+  border-radius: 9999px;
+  background: transparent;
+  color: hsl(var(--muted-foreground));
+  font-size: 0.75rem;
+  line-height: 1.5;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.skipped-toggle:hover {
+  color: hsl(var(--foreground));
+  border-color: hsl(var(--muted-foreground) / 0.5);
+}
+
+.skipped-toggle.active {
+  border-style: solid;
+  border-color: hsl(var(--primary) / 0.5);
+  color: hsl(var(--primary));
+}
+
 .nav-info {
   font-size: 0.8rem;
   font-weight: 500;

frontend/src/features/usage/components/UsageRecordsTable.vue

@@ -149,32 +149,14 @@
             <SelectValue placeholder="状态" />
           </SelectTrigger>
           <SelectContent>
-            <SelectItem value="__all__">
-              全部类型
-            </SelectItem>
-            <SelectItem value="stream">
-              HTTP 流式
-            </SelectItem>
-            <SelectItem value="standard">
-              HTTP 标准
-            </SelectItem>
-            <SelectItem value="websocket">
-              WebSocket (WS)
-            </SelectItem>
-            <SelectItem value="active">
-              活跃
-            </SelectItem>
-            <SelectItem value="failed">
-              失败
-            </SelectItem>
-            <SelectItem value="cancelled">
-              已取消
-            </SelectItem>
-            <SelectItem value="has_retry">
-              发生重试
-            </SelectItem>
-            <SelectItem value="has_fallback">
-              发生转移
+            <!-- 手机与桌面共用状态选项，避免新增筛选时漏掉手机入口。 -->
+            <SelectItem
+              v-for="option in statusFilterOptions"
+              :key="option.value"
+              :value="option.value"
+              :disabled="option.disabled"
+            >
+              {{ option.label }}
             </SelectItem>
           </SelectContent>
         </Select>
@@ -362,6 +344,28 @@
           </span>
           <span class="shrink-0 text-muted-foreground/40">·</span>
           <span class="min-w-0 truncate">{{ formatRecordProviderSegment(record) }}</span>
+          <!-- 手机与桌面保持相同的标记优先级：发生故障转移时优先显示转移标记。 -->
+          <Shuffle
+            v-if="record.has_fallback"
+            data-usage-attempt-marker="fallback"
+            class="w-3.5 h-3.5 text-amber-600 dark:text-amber-400 flex-shrink-0"
+            title="此请求发生了 Provider 故障转移"
+            aria-label="发生 Provider 故障转移"
+          />
+          <Ban
+            v-if="record.has_skipped_candidate && !record.has_fallback"
+            data-usage-attempt-marker="skipped-candidate"
+            class="w-3.5 h-3.5 text-slate-500 dark:text-slate-400 flex-shrink-0"
+            :title="skippedCandidateTooltip(record)"
+            :aria-label="skippedCandidateAriaLabel(record)"
+          />
+          <RefreshCcw
+            v-if="record.has_retry"
+            data-usage-attempt-marker="retry"
+            class="w-3.5 h-3.5 text-blue-600 dark:text-blue-400 flex-shrink-0"
+            title="此请求发生了重试"
+            aria-label="发生重试"
+          />
         </div>
 
         <!-- 第四行：性能指标 -->
@@ -791,6 +795,18 @@
                 title="此请求发生了 Provider 故障转移"
                 aria-label="发生 Provider 故障转移"
               />
+              <!--
+                被跳过的更高优先级候选：与"故障转移"区分开。
+                它表示候选在调度阶段就被排除、请求从未发出，因此不会有任何上游报错，
+                是"无报错却换了提供商"这一现象的直接解释。
+              -->
+              <Ban
+                v-if="record.has_skipped_candidate && !record.has_fallback"
+                data-usage-attempt-marker="skipped-candidate"
+                class="w-3.5 h-3.5 text-slate-500 dark:text-slate-400 flex-shrink-0"
+                :title="skippedCandidateTooltip(record)"
+                :aria-label="skippedCandidateAriaLabel(record)"
+              />
               <RefreshCcw
                 v-if="record.has_retry"
                 data-usage-attempt-marker="retry"
@@ -1093,7 +1109,7 @@ import {
   SortableTableHead,
   TableFilterMenu,
 } from '@/components/ui'
-import { EyeOff, RefreshCcw, Search, Shuffle } from 'lucide-vue-next'
+import { Ban, EyeOff, RefreshCcw, Search, Shuffle } from 'lucide-vue-next'
 import { formatTokens, formatCurrency } from '@/utils/format'
 import { getCacheCreationTokens, getCacheReadTokens, getEffectiveInputTokens } from '../token-normalization'
 import {
@@ -1115,6 +1131,7 @@ import { useDarkMode } from '@/composables/useDarkMode'
 import { API_FORMAT_ORDER, formatApiFormat } from '@/api/endpoints/types/api-format'
 import { formatClientFamily } from '@/features/usage/utils/clientFamily'
 import { formatServiceTierFact } from '../utils/service-tier'
+import { formatCandidateSkipReason } from '../utils/skipReason'
 import { isCyberPolicyError } from '../utils/cyberError'
 import { formatUsageWebSocketTransportTitle as getWebSocketTransportTitle } from '../utils/websocketTransport'
 import type { DateRangeParams, UsageRecord } from '../types'
@@ -1370,6 +1387,8 @@ const statusFilterOptions: FilterOption[] = [
   { value: 'cancelled', label: '已取消' },
   { value: 'has_retry', label: '发生重试' },
   { value: 'has_fallback', label: '发生转移' },
+  // 与"发生转移"区分：候选在调度阶段就被排除，请求从未发出（无上游报错）
+  { value: 'has_skipped_candidate', label: '有候选被调度跳过' },
 ]
 
 const timeRangeModel = computed({
@@ -1602,6 +1621,23 @@ function shouldShowFormatConversion(record: UsageRecord): boolean {
   return record.api_format.trim().toLowerCase() !== record.endpoint_api_format.trim().toLowerCase()
 }
 
+// 被跳过候选的提示文案：把"调度阶段排除"和"上游失败"讲清楚，
+// 避免用户把"无报错换提供商"误判成调度 bug 或提供商静默出错。
+function skippedCandidateTooltip(record: UsageRecord): string {
+  const reasons = (record.skipped_candidate_reasons ?? [])
+    .map(formatCandidateSkipReason)
+    .filter((reason, index, all) => reason && all.indexOf(reason) === index)
+
+  const header = '本次有候选在调度阶段被跳过，请求未发往该候选（因此不会有上游报错）'
+  if (!reasons.length) return header
+  return `${header}\n跳过原因：${reasons.join('；')}`
+}
+
+function skippedCandidateAriaLabel(record: UsageRecord): string {
+  const reasons = (record.skipped_candidate_reasons ?? []).map(formatCandidateSkipReason)
+  return reasons.length ? `有候选被调度跳过：${reasons.join('；')}` : '有候选被调度跳过'
+}
+
 // 获取 API 格式的 tooltip（包含转换信息）
 function getApiFormatTooltip(record: UsageRecord): string {
   if (!record.api_format) {

frontend/src/features/usage/components/__tests__/HorizontalRequestTimeline.spec.ts

@@ -425,6 +425,56 @@ describe('HorizontalRequestTimeline', () => {
     expect(nodeDots[2].classList.contains('status-pending')).toBe(true)
   })
 
+  it('shows a skipped candidate with a Chinese reason and can collapse it', async () => {
+    const trace = buildTrace([
+      buildCandidate({
+        id: 'cand-skipped-rpm',
+        provider_id: 'provider-1',
+        provider_name: 'Provider 1',
+        key_id: 'key-1',
+        key_name: 'Key 1',
+        candidate_index: 0,
+        status: 'skipped',
+        skip_reason: 'key_rpm_exhausted',
+        started_at: undefined,
+        finished_at: undefined,
+      }),
+      buildCandidate({
+        id: 'cand-success-2',
+        provider_id: 'provider-2',
+        provider_name: 'Provider 2',
+        key_id: 'key-2',
+        key_name: 'Key 2',
+        candidate_index: 1,
+        status: 'success',
+      }),
+    ])
+
+    const root = mountTimeline(trace)
+    await nextTick()
+
+    // 被跳过的候选默认可见：它是"为什么没用这个提供商"的答案
+    expect([...root.querySelectorAll<HTMLElement>('.node-label')]
+      .map(label => label.textContent?.trim()))
+      .toEqual(['Provider 1', 'Provider 2'])
+
+    // 点击第一个节点查看详情，应看到中文跳过原因
+    root.querySelector<HTMLElement>('.minimal-node-group')?.click()
+    await nextTick()
+    expect(root.textContent).toContain('密钥本分钟请求数已达上限')
+    // 必须点明"没有向上游发起请求"，否则会被误读成上游报错
+    expect(root.textContent).toContain('未向上游发起请求')
+
+    // 开关可把跳过候选整体收起
+    const toggle = root.querySelector<HTMLButtonElement>('.skipped-toggle')
+    expect(toggle).not.toBeNull()
+    toggle?.click()
+    await nextTick()
+    expect([...root.querySelectorAll<HTMLElement>('.node-label')]
+      .map(label => label.textContent?.trim()))
+      .toEqual(['Provider 2'])
+  })
+
   it('keeps successful runtime pool key visible when only pool_key_index is recorded', async () => {
     const trace = buildTrace([
       buildCandidate({

frontend/src/features/usage/components/__tests__/UsageRecordsTable.spec.ts

@@ -92,6 +92,7 @@ vi.mock('lucide-vue-next', async () => {
     EyeOff: Icon,
     Search: Icon,
     Shuffle: Icon,
+    Ban: Icon,
     ChevronDown: Icon,
     Check: Icon,
   }
@@ -679,4 +680,37 @@ describe('UsageRecordsTable', () => {
     expect(root.querySelector('[data-usage-attempt-marker="fallback"]')).not.toBeNull()
     expect(root.querySelector('[data-usage-attempt-marker="retry"]')).not.toBeNull()
   })
+
+  it('shows the skipped-candidate marker when a candidate was skipped by scheduling', () => {
+    const root = mountUsageRecordsTable([buildRecord({
+      has_skipped_candidate: true,
+      skipped_candidate_reasons: ['key_rpm_exhausted'],
+    })])
+
+    const marker = root.querySelector('[data-usage-attempt-marker="skipped-candidate"]')
+    expect(marker).not.toBeNull()
+    // tooltip 必须说明"请求未发往该候选"，否则用户会以为上游报了错
+    const title = marker?.getAttribute('title') ?? ''
+    expect(title).toContain('调度阶段被跳过')
+    expect(title).toContain('不会有上游报错')
+    expect(title).toContain('密钥本分钟请求数已达上限')
+  })
+
+  it('prefers the fallback marker over the skipped-candidate marker', () => {
+    // 真正发生过故障转移时，琥珀色转移图标信息量更大，不再叠加灰色角标
+    const root = mountUsageRecordsTable([buildRecord({
+      has_fallback: true,
+      has_skipped_candidate: true,
+      skipped_candidate_reasons: ['key_rpm_exhausted'],
+    })])
+
+    expect(root.querySelector('[data-usage-attempt-marker="fallback"]')).not.toBeNull()
+    expect(root.querySelector('[data-usage-attempt-marker="skipped-candidate"]')).toBeNull()
+  })
+
+  it('hides the skipped-candidate marker when no candidate was skipped', () => {
+    const root = mountUsageRecordsTable([buildRecord({ has_skipped_candidate: false })])
+
+    expect(root.querySelector('[data-usage-attempt-marker="skipped-candidate"]')).toBeNull()
+  })
 })

frontend/src/features/usage/composables/useUsageFilters.ts

@@ -3,6 +3,7 @@ import type { UsageRecord, FilterStatusValue } from '../types'
 import {
   hasUsageFallback,
   hasUsageRetry,
+  hasUsageSkippedCandidate,
   isUsageRecordFailed,
   isUsageUpstreamStream,
   isUsageWebSocket,
@@ -97,6 +98,8 @@ export function useUsageFilters(options: UseUsageFiltersOptions) {
         records = records.filter(record => hasUsageFallback(record))
       } else if (filterStatus.value === 'has_retry') {
         records = records.filter(record => hasUsageRetry(record))
+      } else if (filterStatus.value === 'has_skipped_candidate') {
+        records = records.filter(record => hasUsageSkippedCandidate(record))
       }
     }
 

frontend/src/features/usage/types.ts

@@ -100,7 +100,8 @@ export type FilterStatusValue =
   'failed' |
   'cancelled' |
   'has_fallback' |
-  'has_retry'
+  'has_retry' |
+  'has_skipped_candidate'
 
 // 默认统计状态
 export function createDefaultStats(): UsageStatsState {

frontend/src/features/usage/utils/__tests__/skipReason.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  CANDIDATE_SKIP_REASON_LABELS,
+  formatCandidateSkipReason,
+  isNonAttemptedCandidateStatus,
+  isSkippedCandidateStatus,
+} from '../skipReason'
+
+describe('candidate skip reason formatting', () => {
+  it('translates known skip reasons into Chinese labels', () => {
+    expect(formatCandidateSkipReason('key_rpm_exhausted')).toBe('密钥本分钟请求数已达上限')
+    expect(formatCandidateSkipReason('provider_concurrency_limit_reached')).toBe('上游提供商并发已达上限')
+    expect(formatCandidateSkipReason('key_circuit_open')).toBe('密钥熔断中（连续失败后暂停）')
+  })
+
+  it('trims surrounding whitespace before lookup', () => {
+    expect(formatCandidateSkipReason('  key_rpm_exhausted  ')).toBe('密钥本分钟请求数已达上限')
+  })
+
+  it('falls back to the raw reason so new backend reasons stay visible', () => {
+    // 后端新增白名单原因、前端还没补翻译时，不能丢信息。
+    expect(formatCandidateSkipReason('brand_new_reason')).toBe('brand_new_reason')
+  })
+
+  it('returns an empty string for missing or blank reasons', () => {
+    expect(formatCandidateSkipReason(undefined)).toBe('')
+    expect(formatCandidateSkipReason(null)).toBe('')
+    expect(formatCandidateSkipReason('   ')).toBe('')
+  })
+
+  it('labels every backend allowlisted reason', () => {
+    // 与后端 REQUEST_CANDIDATE_SKIP_REASONS 白名单保持同步的关键集合抽查。
+    const criticalReasons = [
+      'account_quota_exhausted',
+      'api_key_concurrency_limit_reached',
+      'auth_api_key_concurrency_limit_reached',
+      'key_circuit_open',
+      'key_health_score_zero',
+      'key_rpm_exhausted',
+      'pool_key_lease_busy',
+      'provider_concurrency_limit_reached',
+      'provider_key_concurrency_limit_reached',
+      'provider_quota_blocked',
+      'transport_unsupported',
+    ]
+    for (const reason of criticalReasons) {
+      expect(CANDIDATE_SKIP_REASON_LABELS[reason], `missing label for ${reason}`).toBeTruthy()
+    }
+  })
+
+  it('distinguishes skipped candidates from attempted ones', () => {
+    expect(isSkippedCandidateStatus('skipped')).toBe(true)
+    expect(isSkippedCandidateStatus('failed')).toBe(false)
+    expect(isSkippedCandidateStatus(undefined)).toBe(false)
+
+    // available/unused 同样是"从未尝试"，用于时间线是否展示的判定。
+    expect(isNonAttemptedCandidateStatus('skipped')).toBe(true)
+    expect(isNonAttemptedCandidateStatus('available')).toBe(true)
+    expect(isNonAttemptedCandidateStatus('unused')).toBe(true)
+    expect(isNonAttemptedCandidateStatus('success')).toBe(false)
+    expect(isNonAttemptedCandidateStatus('failed')).toBe(false)
+  })
+})

frontend/src/features/usage/utils/__tests__/status.spec.ts

@@ -4,6 +4,7 @@ import {
   formatUsageStreamLabel,
   hasUsageFallback,
   hasUsageRetry,
+  hasUsageSkippedCandidate,
   isUsageRecordFailed,
   isUsageRecordSuccessful,
   isUsageWebSocket,
@@ -178,6 +179,19 @@ describe('usage status helpers', () => {
     expect(hasUsageRetry(buildUsageRecord({ has_retry: undefined }))).toBe(false)
   })
 
+  it('uses explicit has_skipped_candidate flag for scheduling-skip filtering', () => {
+    expect(hasUsageSkippedCandidate(buildUsageRecord({ has_skipped_candidate: true }))).toBe(true)
+    expect(hasUsageSkippedCandidate(buildUsageRecord({ has_skipped_candidate: false }))).toBe(false)
+    expect(hasUsageSkippedCandidate(buildUsageRecord({ has_skipped_candidate: undefined }))).toBe(false)
+  })
+
+  it('keeps skipped-candidate signal independent from fallback signal', () => {
+    // 被调度跳过 ≠ 故障转移：前者请求从未发出，因此不应被 hasUsageFallback 认领
+    const skippedOnly = buildUsageRecord({ has_skipped_candidate: true, has_fallback: false })
+    expect(hasUsageSkippedCandidate(skippedOnly)).toBe(true)
+    expect(hasUsageFallback(skippedOnly)).toBe(false)
+  })
+
   it('recognizes persisted WebSocket usage records', () => {
     expect(isUsageWebSocket(buildUsageRecord({ is_websocket: true }))).toBe(true)
     expect(isUsageWebSocket(buildUsageRecord({ is_websocket: false }))).toBe(false)

frontend/src/features/usage/utils/recordFilterPolicy.ts

@@ -1,7 +1,11 @@
 import type { FilterStatusValue } from '../types'
 
 export function isUserLocalOnlyRecordStatus(status: FilterStatusValue): boolean {
-  return status === 'has_retry' || status === 'has_fallback'
+  // 这三个标记都由后端在列表响应里直接给出，但用户侧接口不支持作为服务端筛选条件，
+  // 因此统一走前端本地过滤。
+  return status === 'has_retry'
+    || status === 'has_fallback'
+    || status === 'has_skipped_candidate'
 }
 
 export function shouldUseServerUserRecordFilters(input: {

frontend/src/features/usage/utils/skipReason.ts

@@ -0,0 +1,98 @@
+/**
+ * 候选"被跳过"原因的中文标签。
+ *
+ * 这些字符串来自后端 `StoredRequestCandidate.skip_reason`，取值受
+ * `crates/aether-data/contracts/src/repository/candidates/types.rs` 里的
+ * `REQUEST_CANDIDATE_SKIP_REASONS` 白名单约束（未知原因会被后端统一清洗成
+ * `unclassified_candidate_skip_reason`）。
+ *
+ * 维护约定：后端新增白名单项时，这里补一条中文说明；缺失时前端会原样显示英文，
+ * 不会丢信息，所以可以安全地"先上线原因、后补翻译"。
+ */
+export const CANDIDATE_SKIP_REASON_LABELS: Record<string, string> = {
+  // —— 调度期运行时可选择性（不满足条件，从未真正发起请求）——
+  account_quota_exhausted: '账号额度已耗尽',
+  oauth_invalid: 'OAuth 凭证已失效',
+  provider_quota_blocked: '上游提供商额度已用尽',
+  provider_concurrency_limit_reached: '上游提供商并发已达上限',
+  provider_key_concurrency_limit_reached: '上游账号并发已达上限',
+  provider_inactive: '提供商已停用',
+  key_inactive: '密钥已停用',
+  key_circuit_open: '密钥熔断中（连续失败后暂停）',
+  key_health_score_zero: '密钥健康分为 0',
+  key_rpm_exhausted: '密钥本分钟请求数已达上限',
+  key_model_disabled: '该密钥已停用此模型',
+  key_model_not_allowed: '该密钥不允许使用此模型',
+  key_api_format_disabled: '该密钥已停用此 API 格式',
+  api_key_concurrency_limit_reached: '调用方 API Key 并发已达上限',
+  auth_api_key_concurrency_limit_reached: '调用方 API Key 并发已达上限',
+
+  // —— 传输与路由策略门（在真正发请求前就被拦下）——
+  auth_channel_mismatch: '鉴权通道不匹配',
+  auth_snapshot_missing: '缺少该密钥的鉴权快照',
+  endpoint_api_format_changed: '端点 API 格式已变更',
+  endpoint_inactive: '端点已停用',
+  format_conversion_disabled: '该提供商未开启格式转换',
+  mapped_model_missing: '缺少映射后的上游模型',
+  routing_profile_disallowed_key: '路由策略未允许该密钥',
+  routing_profile_disallowed_provider: '路由策略未允许该提供商',
+  upstream_url_missing: '缺少上游地址',
+  gemini_file_mapping_mismatch: 'Gemini 文件映射不匹配',
+  provider_request_body_build_failed: '上游请求体转换失败',
+  provider_request_body_missing: '无法构建上游请求体',
+
+  // —— transport_* 系列：该提供商/端点不支持当前这种转发方式 ——
+  transport_unsupported: '该传输方式不受支持',
+  transport_api_format_mismatch: 'API 格式与端点不匹配',
+  transport_api_format_unsupported: '不支持该 API 格式',
+  transport_auth_unavailable: '无法获取可用鉴权',
+  transport_body_rules_apply_failed: '请求体改写规则执行失败',
+  transport_body_rules_unsupported: '不支持请求体改写规则',
+  transport_body_rules_unsupported_for_binary_upload: '二进制上传不支持请求体改写规则',
+  transport_custom_path_unsupported: '不支持自定义路径',
+  transport_endpoint_kind_unsupported: '不支持该端点类型',
+  transport_header_rules_apply_failed: '请求头改写规则执行失败',
+  transport_header_rules_unsupported: '不支持请求头改写规则',
+  transport_oauth_resolution_unsupported: '不支持该 OAuth 解析方式',
+  transport_operation_unsupported: '不支持该操作类型',
+  transport_profile_unsupported: '不支持该传输配置',
+  transport_provider_type_unsupported: '不支持该提供商类型',
+  transport_proxy_or_profile_unsupported: '不支持代理或传输配置',
+  transport_proxy_unsupported: '不支持该代理',
+  transport_snapshot_missing: '缺少传输快照',
+
+  // —— 号池（pool）相关 ——
+  pool_group_exhausted: '号池已无可用账号',
+  pool_account_blocked: '号池账号已被封禁',
+  pool_account_exhausted: '号池账号额度已耗尽',
+  pool_active_probe_sealed: '号池探测中，暂不分配',
+  pool_cooldown: '号池账号冷却中',
+  pool_cost_limit_reached: '号池费用已达上限',
+  pool_key_lease_busy: '池内账号正被其他请求占用',
+  pool_score_member_missing: '号池评分成员缺失',
+}
+
+/** 后端无法归类时使用的占位原因。 */
+export const UNCLASSIFIED_CANDIDATE_SKIP_REASON = 'unclassified_candidate_skip_reason'
+
+/**
+ * 把候选跳过原因转成中文展示文案。
+ *
+ * 命中已知标签时返回中文；否则原样返回后端字符串（便于排查新原因），
+ * 空值返回空字符串，调用方据此判断是否展示。
+ */
+export function formatCandidateSkipReason(reason?: string | null): string {
+  const normalized = typeof reason === 'string' ? reason.trim() : ''
+  if (!normalized) return ''
+  return CANDIDATE_SKIP_REASON_LABELS[normalized] ?? normalized
+}
+
+/** 是否为"根本没有向上游发起请求"的跳过状态。 */
+export function isSkippedCandidateStatus(status?: string | null): boolean {
+  return status === 'skipped'
+}
+
+/** 是否为"被枚举出来但从未尝试"的候选状态（含跳过与未使用）。 */
+export function isNonAttemptedCandidateStatus(status?: string | null): boolean {
+  return status === 'skipped' || status === 'available' || status === 'unused'
+}

frontend/src/features/usage/utils/status.ts

@@ -49,6 +49,16 @@ export function hasUsageRetry(
   return record.has_retry === true
 }
 
+/**
+ * 是否有候选在调度阶段被跳过（请求从未发往该候选）。
+ * 与 hasUsageFallback 互补：后者要求"更靠前的候选确实尝试并失败"。
+ */
+export function hasUsageSkippedCandidate(
+  record: Pick<UsageRecord, 'has_skipped_candidate'>
+): boolean {
+  return record.has_skipped_candidate === true
+}
+
 export function isUsageWebSocket(
   record: Pick<UsageRecord, 'is_websocket'>
 ): boolean {

frontend/src/views/shared/Usage.vue

@@ -441,6 +441,8 @@ const filteredRecords = computed(() => {
         records = records.filter(record => hasUsageFallback(record))
       } else if (filterStatus.value === 'has_retry') {
         records = records.filter(record => record.has_retry === true)
+      } else if (filterStatus.value === 'has_skipped_candidate') {
+        records = records.filter(record => record.has_skipped_candidate === true)
       }
     }