fix(ai): 任务句柄契约对齐 camelCase + 401/403 区分——修复精修补充永久排队中

AiTaskHandle 经 serde camelCase 序列化为 taskId，前端读 handle.task_id 恒为 undefined：事件通道被忽略、轮询缺参报错，任务实际已失败但前端永久显示排队中（EnrichPanel 另漏 taskIdRef 赋值）。401/403 拆分便于区分密钥无效与模型无权限。

Author: Aparencia

app/src-tauri/src/ai_balance.rs

@@ -103,8 +103,13 @@ impl AiBalanceAdapter {
                         .map_err(|e| format!("读取余额响应失败: {}", e))?;
                     return parse_balance(&body);
                 }
-                Err(ureq::Error::Status(401 | 403, _)) => {
-                    return Err("API 密钥无效或无权限（请检查设置页密钥）".to_string());
+                // 401/403 拆分（2026-08-21 真机 unauthorized 排查）：与
+                // ai_client.rs 同口径——401=密钥无效，403=无权限/模型未开通
+                Err(ureq::Error::Status(401, _)) => {
+                    return Err("API 密钥无效（HTTP 401）——请检查设置页密钥或环境变量 SILICONFLOW_API_KEY".to_string());
+                }
+                Err(ureq::Error::Status(403, _)) => {
+                    return Err("API 密钥无权限（HTTP 403）——账号未开通该模型或额度受限".to_string());
                 }
                 Err(ureq::Error::Status(429, _)) => {
                     last_err = "请求过频（HTTP 429）".to_string();

app/src-tauri/src/ai_client.rs

@@ -126,8 +126,18 @@ impl AiClient {
                         .map_err(|e| AiClientError::Network(format!("读取响应失败: {}", e)))?;
                     return extract_content(&body);
                 }
-                Err(ureq::Error::Status(401 | 403, _)) => {
-                    return Err(AiClientError::Auth("API 密钥无效或无权限（请检查设置页密钥）".to_string()));
+                // 401/403 拆分（2026-08-21 真机 unauthorized 排查）：401=密钥
+                // 无效（换密钥），403=账号无权限/模型未开通（换模型或开权限）——
+                // 合并时用户无法区分该修密钥还是该换模型
+                Err(ureq::Error::Status(401, _)) => {
+                    return Err(AiClientError::Auth(
+                        "API 密钥无效（HTTP 401）——请检查设置页密钥或环境变量 SILICONFLOW_API_KEY".to_string(),
+                    ));
+                }
+                Err(ureq::Error::Status(403, _)) => {
+                    return Err(AiClientError::Auth(
+                        "API 密钥无权限（HTTP 403）——账号未开通该模型或额度受限".to_string(),
+                    ));
                 }
                 Err(ureq::Error::Status(402, _)) => {
                     return Err(AiClientError::Balance("账户余额不足（请充值或切换免费档模型）".to_string()));

app/src/components/AiRefineCard.tsx

@@ -191,7 +191,10 @@ export default function AiRefineCard({ sessionId, onApplied }: { sessionId: numb
       }).catch(() => undefined);
     }
     setPhase("running");
-    const handle = await invoke<{ task_id: number; state: AiTaskState }>("ai_refine_start", {
+    // 契约修复（2026-08-21 真机"排队中"根因）：Rust AiTaskHandle 为 camelCase
+    // 序列化（taskId），此前读 handle.task_id 恒为 undefined → 事件被忽略、
+    // 轮询缺参报错 → 前端永久"排队中"而任务实际早已失败
+    const handle = await invoke<{ taskId: number; state: AiTaskState }>("ai_refine_start", {
       sessionId,
       authorized: true,
     }).catch((e) => {
@@ -200,10 +203,10 @@ export default function AiRefineCard({ sessionId, onApplied }: { sessionId: numb
       return null;
     });
     if (handle) {
-      taskIdRef.current = handle.task_id;
-      setTaskId(handle.task_id);
+      taskIdRef.current = handle.taskId;
+      setTaskId(handle.taskId);
       void handleState(handle.state);
-      poll(handle.task_id);
+      poll(handle.taskId);
     }
   };
 

app/src/components/EnrichPanel.tsx

@@ -197,7 +197,10 @@ export default function EnrichPanel({ noteId, onUpdated }: { noteId: number; onU
   const start = async () => {
     setMsg("");
     setPhase("running");
-    const handle = await invoke<{ task_id: number; state: AiTaskState }>("ai_enrich_start", {
+    // 契约修复（2026-08-21 真机"排队中"根因）：Rust AiTaskHandle 为 camelCase
+    // 序列化（taskId）——此前读 handle.task_id 恒为 undefined；且本组件遗漏
+    // taskIdRef 赋值，事件通道永远失效，一并补上（与 AiRefineCard 同款修复）
+    const handle = await invoke<{ taskId: number; state: AiTaskState }>("ai_enrich_start", {
       noteId,
       selectedKinds: selected,
       authorized: true,
@@ -207,9 +210,10 @@ export default function EnrichPanel({ noteId, onUpdated }: { noteId: number; onU
       return null;
     });
     if (handle) {
-      setTaskId(handle.task_id);
+      taskIdRef.current = handle.taskId;
+      setTaskId(handle.taskId);
       void handleState(handle.state);
-      poll(handle.task_id);
+      poll(handle.taskId);
     }
   };
 

app/src/types.ts

@@ -696,9 +696,9 @@ export type AiTaskState =
   | "Succeeded"
   | { Failed: { reason: AiTaskFailure } };
 
-/** 任务句柄（Rust AiTaskHandle） */
+/** 任务句柄（Rust AiTaskHandle——camelCase 契约：taskId，2026-08-21 修复） */
 export interface AiTaskHandle {
-  task_id: number;
+  taskId: number;
   state: AiTaskState;
 }