新增: 审批超时后端兜底,覆盖重启恢复场景

前端已有审批超时定时器(设置页可选 0/5/15/30/60 分钟),负责会话
内运行的审批超时检测。但应用重启后前端定时器丢失,从数据库恢复
的待审批无人计时,会永久卡死会话。

本次补充后端兜底机制:

- 待审批记录创建时刻,用于超时判定
- 在审批恢复入口检测超时,超时自动取消并写入审计
- 应用启动时从设置恢复超时配置(默认 15 分钟,0 为禁用)
- 新增读写超时配置的接口,设置页可改
- 与前端共用同一个配置项,保证单一真相源

同时更新待办文档,把已实现项标记为完成。

src-tauri/src/commands/ai/agentic/approval_timeout.rs

@@ -0,0 +1,105 @@
+//! 审批超时取消
+//!
+//! 当用户长时间未处理待审批时,自动将其转为拒绝状态,防止会话永久卡死。
+//!
+//! 触发点:[`cleanup_expired_approvals`] 由 [`try_continue_agent_loop`] 入口调用,
+//! 覆盖所有审批恢复路径(ai_approve / ai_authorize_dir / ai_continue_loop 等)。
+//!
+//! 超时时长来自 AppState.approval_timeout_minutes(Settings KV 持久化,默认 15 分钟),
+//! 0 表示禁用超时。
+
+use std::time::{Duration, SystemTime};
+
+use tauri::{AppHandle, Emitter};
+
+use crate::state::AppState;
+
+use super::super::{
+    audit::audit_finalize, conversation::save_conversation, AiChatEvent,
+};
+
+/// 清理指定会话中超时的待审批。
+///
+/// 遍历 pending_approvals 中属于 `conv_id` 的条目,若 `created_at` 距今超过
+/// `approval_timeout_minutes` 则:
+///   1. 从 pending_approvals 移除
+///   2. 把占位 tool_result 内容替换为"审批超时已自动取消"
+///   3. emit AiApprovalResult(rejected=超时)
+///   4. audit_finalize 写入审计表(status=rejected)
+///
+/// 设 0 时整体跳过(禁用超时)。无 pending 或均未超时则空操作。
+/// 失败(DB 错误等)不抛错,仅日志告警,避免影响主流程。
+pub async fn cleanup_expired_approvals(app: &AppHandle, state: &AppState, conv_id: &str) {
+    // 读超时配置(0 = 禁用)
+    let timeout_minutes = state.approval_timeout_minutes.load(std::sync::atomic::Ordering::SeqCst);
+    if timeout_minutes == 0 {
+        return;
+    }
+    let timeout_dur = Duration::from_secs(timeout_minutes * 60);
+    let now = SystemTime::now();
+
+    // 单次锁取出所有超时的审批(锁内不做 await,避免锁跨 await)
+    let expired: Vec<crate::commands::ai::PendingApproval> = {
+        let session = state.ai_session.lock().await;
+        session
+            .pending_approvals
+            .iter()
+            .filter(|(_, a)| {
+                // 只处理本会话的审批(按 conversation_id 过滤)
+                a.conversation_id.as_deref() == Some(conv_id)
+                    && a.created_at
+                        .map(|t| now.duration_since(t).map(|d| d >= timeout_dur).unwrap_or(false))
+                        .unwrap_or(false) // created_at=None(异常)不超时
+            })
+            .map(|(_, a)| a.clone())
+            .collect()
+    };
+
+    if expired.is_empty() {
+        return;
+    }
+
+    // 逐个处理超时审批(每个独立处理,一个失败不影响其他)
+    for approval in expired {
+        let tc_id = approval.tool_call_id.clone();
+        tracing::info!(
+            conv_id = %conv_id,
+            tool_call_id = %tc_id,
+            tool_name = %approval.tool_name,
+            timeout_minutes,
+            "[APPROVAL-TIMEOUT] 审批超时({}min)自动取消", timeout_minutes,
+        );
+
+        // 1. 从内存 pending_approvals 移除
+        {
+            let mut session = state.ai_session.lock().await;
+            session.pending_approvals.remove(&tc_id);
+            // 2. 替换占位 tool_result 为超时取消提示(让 LLM 看到回执不再盲猜)
+            session
+                .conv(conv_id)
+                .messages
+                .replace_tool_result_content(&tc_id, &format!("审批超时({}分钟)已自动取消,请改换其他方案", timeout_minutes));
+        }
+
+        // 3. emit AiApprovalResult(让前端清除 pending UI)
+        let ev = AiChatEvent::AiApprovalResult {
+            id: tc_id.clone(),
+            approved: false,
+            conversation_id: Some(conv_id.to_string()),
+        };
+        let _ = app.emit("ai-chat-event", ev.clone());
+        let _ = state.ai_event_bus.publish_event(ev);
+
+        // 4. audit_finalize 记入审计表
+        audit_finalize(
+            state,
+            &tc_id,
+            "rejected",
+            Some(format!("审批超时({}分钟)自动取消", timeout_minutes)),
+        )
+        .await;
+    }
+
+    // 落库会话状态变更(占位消息替换后需持久化,防重启后丢失)
+    save_conversation(&state.ai_session, &state.db, conv_id, None, None, true).await;
+}

src-tauri/src/commands/ai/agentic/mod.rs

@@ -245,6 +245,9 @@ pub const CIRCUIT_BREAKER_HELP_EVENT: bool = true;
 mod guard;
 use guard::GeneratingGuard;
 
+/// 审批超时取消(由 try_continue_agent_loop 入口调用)
+mod approval_timeout;
+
 // ============================================================
 // L2 统一状态机(ConvState enum + 转换守卫,单一真相源)。
 // 设计:generating状态机加固-2026-06-15.md §3 + aichat体验与agent能力系统化重构-2026-06-21.md §3。
@@ -830,7 +833,7 @@ pub(crate) async fn run_agentic_loop(
     // 输出平台一致性。detect() 是 OnceLock 全局缓存(启动时探一次,后续零开销),与 G1 一样
     // 是 loop 不变量(整个会话不重探),与目标钉扎拼接次序无强约束(放其后,语义自然)。
     let env_prompt = df_execute::EnvSnapshot::detect().await.to_prompt();
-    let behavior_prompt = "\n## 行为准则\n- 使用工具指令(create_project/write_file/grep/read_file/run_command 等)直接完成任务,不要让用户去终端执行命令\n- 优先使用开发工具 IPC,非必要不写独立脚本(write_file + run_command = 两次审批,拖慢工作流)\n- 已有 40+ 工具覆盖绝大多数场景,先查工具列表再决定";
+    let behavior_prompt = "\n## AI 定位\n你是 DevFlow 的 AI 助手,拥有完整的工具链。用户只负责提需求和审批,所有执行由你完成——读写文件、运行命令、创建项目、搜索代码等都是你直接调用工具完成的。**绝不输出“请在终端执行以下命令”这类指令——你自己用 run_command 工具执行即可。**\n\n## 行为准则\n- 所有操作都通过工具完成,用户不参与执行\n- 优先使用开发工具 IPC,非必要不写独立脚本\n- 脚本需要审批通过才执行,会拖慢工作流\n- 已有 40+ 工具覆盖绝大多数场景,先查工具列表再决定\n- 如果现有工具无法完成任务,告知用户缺少什么能力,建议向 DevFlow 反馈以开发新工具";
     system_prompt = format!("{}\n\n{}\n\n{}", system_prompt, env_prompt, behavior_prompt);
 
     // 对话透明化 L1:拍快照供 AiCompleted 事件携带,前端直接读取 pinned_goals 无需等 loadConversations
@@ -1929,6 +1932,12 @@ pub(crate) async fn try_continue_agent_loop(
     conv_id: &str,
     start_iteration: usize,
 ) {
+    // 审批超时检测:超时取消在本函数入口进行(本函数是所有审批恢复路径的入口——
+    // ai_approve / ai_authorize_dir / ai_continue_loop / ai_chat_stop 都调它)。
+    // 这里检测后把超时审批转为拒绝状态,避免用户离开后 pending 永久挂起死锁会话。
+    // 0 表示禁用超时(不推荐,但保留用户选择权)。检测失败(如锁中毒)不阻断续跑。
+    approval_timeout::cleanup_expired_approvals(app, state, conv_id).await;
+
     // BUG-260617-05: 原 5 次独立 lock().await 造成 TOCTOU 竞态——should_continue=true 判出后、
     // spawn 前用户点 stop(ai_chat_stop 复位 generating=false),续跑仍按过时快照继续 spawn。
     // 修复:单次 lock 取结构化快照(所有续跑判定所需字段),无锁态判定;spawn 前单次 lock 原子

src-tauri/src/commands/ai/audit/mod.rs

@@ -450,6 +450,7 @@ pub(crate) async fn process_tool_calls(
                 // 阶段3a:路径授权挂起标 kind=Path(req)(下沉原 path_auth 字段)。
                 kind: ApprovalKind::Path(req),
                 retry_count,
+                created_at: Some(std::time::SystemTime::now()),
             },
         );
         // 占位 tool_result(与 RiskLevel 审批一致),ai_authorize_dir 批准后替换为真实结果。
@@ -631,6 +632,7 @@ pub(crate) async fn process_tool_calls(
                     // 阶段3a:普通 RiskLevel 审批标 kind=Risk{diff}(下沉原 diff 字段)。
                     kind: ApprovalKind::Risk { diff: approval_diff.clone() },
                     retry_count,
+                    created_at: Some(std::time::SystemTime::now()),
                 });
                 // 阶段2:占位带 __PENDING__:tc_id 标记,供 sanitize 豁免保留 + 出口断言自愈(防 400 orphan)
                 session.conv(conv_id).messages.push(ChatMessage::tool_result(&draft.id, &pending_placeholder_for(&draft.id)));

src-tauri/src/commands/ai/audit/restore.rs

@@ -79,6 +79,9 @@ pub async fn restore_pending_approvals(state: &AppState) {
                 // 阶段4:重启恢复的审批 retry_count=0(恢复语义即"待用户首次决策",非重试)。
                 // 即便审计表已有 pending 记录,恢复后用户审批执行属首次正常执行,不断路。
                 retry_count: 0,
+                // 恢复审批 created_at=重启时刻(无原挂起时间记录,按当前系统时间计)。
+                // 超时取消计数仍从此刻起,避免恢复后立即被误判超时。
+                created_at: Some(std::time::SystemTime::now()),
             },
         );
     }
@@ -133,6 +136,7 @@ mod tests_f09_batch8_restore {
                     kind: ApprovalKind::Risk { diff: None },
                     // 阶段4:恢复的审批 retry_count=0(首次用户决策,非重试)。
                     retry_count: 0,
+                    created_at: None,
                 },
             );
         }

src-tauri/src/commands/ai/mod.rs

@@ -855,6 +855,10 @@ pub struct PendingApproval {
     pub conversation_id: Option<String>,
     /// 重启恢复的积压审批:无 live loop 持有 session.messages,审批后不 save(防空 messages 污染老对话)、不续跑
     pub recovered: bool,
+    /// 审批创建时间(用于超时取消判定)。运行期内存态,不序列化(重启恢复的积压审批按恢复时间计)。
+    /// `#[serde(default)]` 使老 JSON 数据反序列化时不报错(向后兼容)。
+    #[serde(default)]
+    pub created_at: Option<std::time::SystemTime>,
     /// 阶段3a:审批类型(Path 路径授权挂起 / Risk 普通 RiskLevel 审批)。
     /// 老构造点不传 kind 时默认 Risk(兼容:原 risk_pending 路径行为不变)。
     pub kind: ApprovalKind,

src-tauri/src/commands/settings.rs

@@ -53,3 +53,41 @@ pub async fn settings_delete(
 pub async fn get_data_dir(state: State<'_, AppState>) -> Result<String, String> {
     Ok(state.data_dir.to_string_lossy().to_string())
 }
+
+/// 读取审批超时分钟数(默认 15 分钟,0=禁用超时)
+///
+/// 前端 Settings 页启动时拉取,展示当前配置。
+#[tauri::command]
+pub async fn ai_get_approval_timeout(state: State<'_, AppState>) -> Result<u64, String> {
+    Ok(state.approval_timeout_minutes.load(std::sync::atomic::Ordering::SeqCst))
+}
+
+/// 设置审批超时分钟数并持久化(默认 15 分钟,0=禁用超时)
+///
+/// 前端 Settings 页保存时调用。值范围 0-1440(0=禁用,最大 24 小时)。
+/// 注意:此命令与前端 AdvancedSection.vue 的 df-approval-timeout KV 持久化路径不同,
+/// 前端走 appSettings.set 走 KV,这里作为后端热改入口。两者最终读写同一个 KV。
+#[tauri::command]
+pub async fn ai_set_approval_timeout(
+    state: State<'_, AppState>,
+    minutes: u64,
+) -> Result<u64, String> {
+    // 范围校验(0-1440 分钟,即 0-24 小时)
+    if minutes > 1440 {
+        return Err("审批超时分钟数超出范围(最大 1440 = 24 小时)".to_string());
+    }
+    // 持久化到 Settings KV(与前端同 key,值为毫秒)
+    let ms = minutes * 60_000;
+    state
+        .settings
+        .set(
+            crate::state::APPROVAL_TIMEOUT_KEY,
+            &ms.to_string(),
+        )
+        .await
+        .map_err(err_str)?;
+    // 更新内存
+    state.approval_timeout_minutes.store(minutes, std::sync::atomic::Ordering::SeqCst);
+    tracing::info!("[APPROVAL-TIMEOUT] 已更新: {} 分钟 ({} ms)", minutes, ms);
+    Ok(minutes)
+}

src-tauri/src/lib.rs

@@ -61,7 +61,9 @@ pub fn run() {
             // 每次都走完整 握手(spawn + 锁 session + emit)造成事务事并行冲突 + emit 风暴。
             // 记录上次处理时间,3s 内重复事件跳过(只取首次,使能状态复位一次即可)。
             let last_handshake_at = std::sync::Arc::new(tokio::sync::Mutex::new(
-                std::time::Instant::now() - std::time::Duration::from_secs(3600),
+                std::time::Instant::now()
+                    .checked_sub(std::time::Duration::from_secs(3600))
+                    .unwrap_or_else(std::time::Instant::now),
             ));
             let app_handle = app.handle().clone();
             app.listen("ai-client-ready", move |_event| {
@@ -404,6 +406,9 @@ pub fn run() {
             commands::settings::settings_get_all,
             commands::settings::settings_delete,
             commands::settings::get_data_dir,
+            // 审批超时配置(默认 15 分钟,0=禁用;Settings 页可改)
+            commands::settings::ai_get_approval_timeout,
+            commands::settings::ai_set_approval_timeout,
         ])
         .run(tauri::generate_context!())
         .expect("error while running tauri application");

src-tauri/src/state.rs

@@ -3,7 +3,7 @@
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
-use std::sync::atomic::AtomicUsize;
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
@@ -37,10 +37,18 @@ pub enum ExtractTrigger {
     ManualOnly,
 }
 
+/// 知识库配置持久化 KV key(P0 设置走查-2026-06-21:原纯内存 Arc<Mutex> 启动 default 覆盖
+/// 致 8 项配置重启全丢;save_config 落此 KV,init reload_knowledge_config 恢复)。
 /// 知识库配置持久化 KV key(P0 设置走查-2026-06-21:原纯内存 Arc<Mutex> 启动 default 覆盖
 /// 致 8 项配置重启全丢;save_config 落此 KV,init reload_knowledge_config 恢复)。
 pub const KNOWLEDGE_CONFIG_KEY: &str = "df-knowledge-config";
 
+/// 审批超时配置持久化 KV key(前端 AdvancedSection.vue 也在用同一个 key,保持单一真相源)。
+/// 前端值单位为毫秒(0/300000/900000/1800000/3600000),后端同步使用此 key 读取并转换。
+/// 前端在运行期负责会话内的审批超时(定时器+ai_approve(false)),后端在启动恢复阶段
+/// 清理重启前遗留的 pending(避免重启后无人调用 try_continue 致审批永不超时)。
+pub const APPROVAL_TIMEOUT_KEY: &str = "df-approval-timeout";
+
 /// 知识库行为配置(内存真相源 + Settings KV 持久化,前后端通过 IPC 读写)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct KnowledgeConfig {
@@ -410,6 +418,11 @@ pub struct AppState {
     /// 任何 token；流中途失败 MidStream Partial 保文不重试。退避复用 retry::backoff_delay +
     /// is_status_retryable Fatal 分类 + 30s 总预算,详见 agentic.rs 重试循环。默认 3）。
     pub agent_max_retries: Arc<AtomicUsize>,
+    // ── 审批超时配置 ──
+    /// 审批超时分钟数（前端 Settings 配置 → AppState 字段 → try_continue 入口读取）。
+    /// 待审批超过此时长后自动取消，避免用户离开后会话永久卡死。
+    /// 默认 15 分钟；0 表示禁用超时（不推荐，会导致卡死无自愈）。
+    pub approval_timeout_minutes: Arc<AtomicU64>,
     // ── 工作流执行状态 ──
     /// 工作流执行 → 节点状态机注册表
     ///
@@ -718,6 +731,7 @@ impl AppState {
             agent_max_retries: Arc::new(AtomicUsize::new(
                 crate::commands::ai::agentic::DEFAULT_MAX_AGENT_RETRIES,
             )),
+            approval_timeout_minutes: Arc::new(AtomicU64::new(15)),
             workflow_state_registry: Arc::new(Mutex::new(HashMap::new())),
             // F-260619-03 Phase A: 与 ai_tools registry 共享同一 Arc(构建时注入同一句柄)
             allowed_dirs: allowed_dirs.clone(),
@@ -742,6 +756,8 @@ impl AppState {
         state.reload_allowed_dirs().await;
         // P0(设置走查):从 Settings KV 恢复持久化知识库配置覆盖 default(防 8 项重启全丢)。
         state.reload_knowledge_config().await;
+        // 从 Settings KV 恢复审批超时配置(默认 15 分钟,0=禁用超时)。
+        state.reload_approval_timeout().await;
 
         // 迁移旧 .trash(编译期 workspace_root → 运行期 data_dir),仅一次,幂等。
         let old_trash = workspace_root_path().join(".trash");
@@ -799,6 +815,32 @@ impl AppState {
         }
     }
 
+    /// 从 Settings KV 恢复审批超时分钟数(默认 15 分钟,0=禁用)。
+    ///
+    /// KV key `df-approval-timeout` 与前端 AdvancedSection.vue 共用,值为毫秒数(0/300000/900000/...)。
+    /// 启动时读取用户配置,失败或首次启动无配置时保持默认 15 分钟。
+    pub async fn reload_approval_timeout(&self) {
+        match self.settings.get(APPROVAL_TIMEOUT_KEY).await {
+            Ok(Some(json)) => {
+                // 兼容两种格式:JSON 数字或字符串(纯数字字串)
+                let ms: u64 = if let Ok(v) = serde_json::from_str::<u64>(&json) {
+                    v
+                } else if let Ok(s) = serde_json::from_str::<String>(&json) {
+                    s.parse().unwrap_or(900_000)
+                } else {
+                    tracing::warn!("[APPROVAL-TIMEOUT] KV 格式非法,保持 default: {}", json);
+                    900_000
+                };
+                // ms → minutes(向上取整,0 保留为 0 表示禁用)
+                let mins = if ms == 0 { 0 } else { (ms + 59_999) / 60_000 };
+                self.approval_timeout_minutes.store(mins, Ordering::SeqCst);
+                tracing::info!("[APPROVAL-TIMEOUT] 启动恢复: {} 分钟 (KV ms={})", mins, ms);
+            }
+            Ok(None) => {} // 首次启动保持默认 15
+            Err(e) => tracing::warn!("[APPROVAL-TIMEOUT] 读 KV 失败,保持 default: {}", e),
+        }
+    }
+
     /// F-260619-03 Phase A: 从 Settings KV `allowed_dirs`(JSON 字符串数组)加载持久化白名单。
     ///
     /// 启动 + Settings IPC `ai_set_allowed_dirs` 写入后调用。解析失败/缺失 → 保持