From 3465d23db344bc39d0b65dbe6488e766c4d01020 Mon Sep 17 00:00:00 2001
From: AAEE86 <ppk0227@hotmail.com>
Date: Thu, 24 Sep 2026 11:29:46 +0800
Subject: [PATCH] feat(frontend): improve Codex fingerprint setting guidance

---
 frontend/src/components/common/HelpHint.vue   |  2 +-
 .../components/ProviderFormDialog.vue         | 23 ++++++++++++-------
 frontend/src/i18n/legacy-ui-messages.ts       |  2 +-
 frontend/src/i18n/messages.ts                 |  2 ++
 4 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/frontend/src/components/common/HelpHint.vue b/frontend/src/components/common/HelpHint.vue
index e02a33041..48c7050d1 100644
--- a/frontend/src/components/common/HelpHint.vue
+++ b/frontend/src/components/common/HelpHint.vue
@@ -24,7 +24,7 @@ const open = ref(false)
     </button>
     <span
       role="tooltip"
-      class="pointer-events-none invisible absolute left-1/2 top-full z-[230] mt-2 w-max max-w-xs -translate-x-1/2 rounded-md border bg-popover px-3 py-2 text-xs leading-5 text-popover-foreground opacity-0 shadow-md transition-opacity group-hover:visible group-hover:opacity-100 group-focus-within:visible group-focus-within:opacity-100"
+      class="pointer-events-none invisible absolute left-1/2 top-full z-[230] mt-2 w-max max-w-xs -translate-x-1/2 whitespace-pre-line rounded-md border bg-popover px-3 py-2 text-xs leading-5 text-popover-foreground opacity-0 shadow-md transition-opacity group-hover:visible group-hover:opacity-100 group-focus-within:visible group-focus-within:opacity-100"
       :class="open ? 'visible opacity-100' : ''"
     >
       {{ props.text }}
diff --git a/frontend/src/features/providers/components/ProviderFormDialog.vue b/frontend/src/features/providers/components/ProviderFormDialog.vue
index c8720e027..67728867c 100644
--- a/frontend/src/features/providers/components/ProviderFormDialog.vue
+++ b/frontend/src/features/providers/components/ProviderFormDialog.vue
@@ -250,12 +250,18 @@
           data-testid="codex-fingerprint-convergence-setting"
         >
           <div class="space-y-0.5">
-            <Label
-              for="codex-fingerprint-convergence"
-              class="text-sm font-medium"
-            >
-              {{ legacyT('Codex 指纹收敛') }}
-            </Label>
+            <div class="flex items-center gap-1">
+              <Label
+                for="codex-fingerprint-convergence"
+                class="text-sm font-medium"
+              >
+                {{ legacyT('Codex 指纹收敛（推荐开启）') }}
+              </Label>
+              <HelpHint
+                :label="legacyT('Codex 指纹收敛（推荐开启）')"
+                :text="legacyT('开启后，Aether 会根据当前账号身份为出站请求统一生成并写入以下标识，使同一 Codex 账号在上游看来始终是同一设备与会话：\n\n• 请求头：installation_id、session_id、thread_id、window_id、turn_id 等\n• 请求体（Responses 格式）：client_metadata 与 prompt_cache_key 中的对应字段\n\n关闭时保持客户端原始透传，不做任何改写。建议开启以提升上游指纹稳定性与会话连续性。')"
+              />
+            </div>
             <p class="text-xs text-muted-foreground leading-relaxed">
               {{ legacyT('统一同一 Codex 身份的设备与会话标识；关闭时保持现有透传行为。') }}
             </p>
@@ -263,7 +269,7 @@
           <Switch
             id="codex-fingerprint-convergence"
             :model-value="form.codex_fingerprint_convergence_enabled"
-            :aria-label="legacyT('Codex 指纹收敛')"
+            :aria-label="legacyT('Codex 指纹收敛（推荐开启）')"
             @update:model-value="(v: boolean) => form.codex_fingerprint_convergence_enabled = v"
           />
         </div>
@@ -280,7 +286,7 @@
               {{ legacyT('Responses WebSocket 模式') }}
             </Label>
             <p class="text-xs text-muted-foreground leading-relaxed">
-              {{ legacyT('允许此提供商处理标准 Responses API WebSocket 请求。仅在已验证兼容性后启用。') }}
+              {{ legacyT('允许此提供商处理标准 Responses API WebSocket 请求。') }}
             </p>
           </div>
           <Switch
@@ -336,6 +342,7 @@ import {
   Switch,
 } from '@/components/ui'
 import { Server, SquarePen } from 'lucide-vue-next'
+import HelpHint from '@/components/common/HelpHint.vue'
 import { useToast } from '@/composables/useToast'
 import { useFormDialog } from '@/composables/useFormDialog'
 import { useI18n } from '@/i18n'
diff --git a/frontend/src/i18n/legacy-ui-messages.ts b/frontend/src/i18n/legacy-ui-messages.ts
index 44d4e02a9..cb5fb6d6b 100644
--- a/frontend/src/i18n/legacy-ui-messages.ts
+++ b/frontend/src/i18n/legacy-ui-messages.ts
@@ -711,7 +711,7 @@ export const legacyUiEnglishMessages: Record<string, string> = {
   '测试请求头必须是 JSON 对象': 'Test request headers must be a JSON object',
   '号池调度模式': 'Pool scheduling mode',
   'Responses WebSocket 模式': 'Responses WebSocket mode',
-  '允许此提供商处理标准 Responses API WebSocket 请求。仅在已验证兼容性后启用。': 'Allow this provider to handle standard Responses API WebSocket requests. Enable only after verifying compatibility.',
+  '允许此提供商处理标准 Responses API WebSocket 请求。': 'Allow this provider to handle standard Responses API WebSocket requests.',
   '发放成功后，冲突的旧套餐及其组合权益会整包失效。确定继续发放吗？': 'Granting this plan will replace conflicting plans and all their bundled benefits. Continue?',
   '确认替换旧套餐': 'Confirm plan replacement',
   '继续发放': 'Grant plan',
diff --git a/frontend/src/i18n/messages.ts b/frontend/src/i18n/messages.ts
index 9aa571175..f4c087ed0 100644
--- a/frontend/src/i18n/messages.ts
+++ b/frontend/src/i18n/messages.ts
@@ -1795,6 +1795,8 @@ const legacyExactEnglishMessages: Record<string, string> = {
   '模拟缓存模式': 'Simulated cache mode',
   '启用后仅对 Kiro 请求模拟 prompt cache 读写计量。': 'When enabled, only Kiro requests simulate prompt cache read/write accounting.',
   'Codex 指纹收敛': 'Codex fingerprint convergence',
+  'Codex 指纹收敛（推荐开启）': 'Codex fingerprint convergence (recommended)',
+  '开启后，Aether 会根据当前账号身份为出站请求统一生成并写入以下标识，使同一 Codex 账号在上游看来始终是同一设备与会话：\n\n• 请求头：installation_id、session_id、thread_id、window_id、turn_id 等\n• 请求体（Responses 格式）：client_metadata 与 prompt_cache_key 中的对应字段\n\n关闭时保持客户端原始透传，不做任何改写。建议开启以提升上游指纹稳定性与会话连续性。': 'When enabled, Aether generates and writes consistent identifiers for outbound requests based on the current account identity, so the same Codex account always appears as the same device and session upstream:\n\n• Request headers: installation_id, session_id, thread_id, window_id, turn_id, etc.\n• Request body (Responses format): corresponding fields in client_metadata and prompt_cache_key\n\nWhen disabled, the original client values are passed through unchanged. Enabling is recommended for better upstream fingerprint stability and session continuity.',
   '统一同一 Codex 身份的设备与会话标识；关闭时保持现有透传行为。': 'Use consistent device and session identifiers for the same Codex identity. When disabled, preserve the existing pass-through behavior.',
   '请前往模块管理-敏感信息保护中配置详细规则。': 'Configure detailed rules in Modules - Sensitive information protection.',
   '验证失败': 'Validation failed',