重构: aichat agent 能力系统化(L1元能力+L2/L3后端+list去重)

L1 agent 元能力层(治痛①死循环零交付):
- env_profile 环境姿势注入 + shell 默认 PowerShell(防引号地狱)
- 断路器:同类工具失败≥3熔断 + guard.reset
- detect_environment 主动探测工具(python/node/shell)
- 求助协议 AiHelpRequired 事件 + 前端求助卡

L2 统一状态机后端(治痛②,前端批2):
- ConvState enum 5态 + 合法转换守卫(conv_state.rs)
- GeneratingGuard 接入视图层(guard.rs)

L3 事件总线后端骨架(治痛③④⑤,接入批2):
- EventBus pub-sub + AiBusEvent 8变体(event_bus.rs)

list 工具调用重复治理第一步:
- build_system_prompt_with_excluded 去重被@实体 + 清单注明语

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

@@ -0,0 +1,468 @@
+//! L2 统一状态机 — `ConvState` enum(单一真相源)+ 合法转换守卫。
+//!
+//! 来源:`generating状态机加固-2026-06-15.md` §3(轻量状态机决策)+ `aichat体验与
+//! agent能力系统化重构-2026-06-21.md` §3(L2 统一状态机)。
+//!
+//! # 背景(为什么单独建这个 enum)
+//!
+//! 旧实现会话状态由三个标志组合隐式表达(`generating: bool` + `stop_flag: AtomicBool`
+//! + `pending_approvals` HashMap),判别逻辑散落 `try_continue_agent_loop` /
+//! `ai_chat_stop` / `ai_conversation_create` 三处(写侧散布 + 读侧散布双根因,见
+//! generating状态机加固-2026-06-15.md §2.3)。本模块提供**显式的、单一真相的**状态枚举:
+//!
+//! - **写侧收敛**:`ConvState` 仅经 [`ConvState::transition_to`] 守卫方法迁移,非法转换
+//!   直接拒绝(`Err(InvalidTransition)`),调用方无法绕过守卫写入非法组合。
+//! - **读侧收敛**:停止按钮三态(可停 / 停中 / 停失败可重试)、MaxRoundsCard 是否弹等
+//!   判别逻辑由 `ConvState` 变体直接表达,不再靠多变量组合反推。
+//!
+//! # 渐进第一步(本批范围)
+//!
+//! 本模块是**纯逻辑、无 IO**的 enum + 转换守卫,不替代 `PerConvState.generating` 等
+//! 字段(渐进不一次全换)。guard 接入点(`GeneratingGuard` set/reset 时同步 `ConvState`
+//! 转换)作为视图层;开关 [`CONV_STATE_ENABLED`](constant.CONV_STATE_ENABLED.html)
+//! 默认 on,off 降级纯旧 bool 行为(可回退)。
+//!
+//! 后续(批2+):把散落判别点(`try_continue` / `ai_chat_stop` / MaxRoundsCard)逐个迁到
+//! 读 `ConvState`,并视情况把 `generating` bool 退役(状态字段由 enum 单一持有)。
+
+use serde::{Deserialize, Serialize};
+
+// ============================================================
+// 开关
+// ============================================================
+
+/// L2 状态机总开关(默认 on)。
+///
+/// - **on(默认)**:`GeneratingGuard` set/reset 时同步迁移 [`ConvState`](enum.ConvState.html)
+///   作视图层,前后端可读统一状态;guard 失败兜底仍走旧 bool 复位(`generating=false`),
+///   不影响语义(状态机层失败不阻断核心复位)。
+/// - **off(降级)**:guard 不写 `ConvState`,纯旧 `generating` bool 行为(排障 / 对比 / 临时
+///   回退用)。设为 false 即可观察无状态机接入的效果,语义等价改动前。
+///
+/// 机制优先 prompt 说教:每改进配开关 + 兜底,分阶段可回退(对齐 AI 改进方案三原则)。
+pub const CONV_STATE_ENABLED: bool = true;
+
+// ============================================================
+// ConvState enum
+// ============================================================
+
+/// 对话生命周期状态(单一真相源,5 态)。
+///
+/// 设计取舍(对齐 generating状态机加固-2026-06-15.md §3.2 「轻量状态机,不引入框架」):
+///
+/// - **不引入状态机框架**(codegen / FSM 库):5 态 7 边转换简单,枚举 + 显式 `transition_to`
+///   守卫即可表达,过度封装得不偿失。
+/// - **派生关系明确**:`Compressed` 是 `Generating`/`Idle` 期间的瞬时派生态(压缩跑完
+///   回到原态),非终端态;`Error` 可经用户「重试」回到 `Idle` 再 `Generating`。
+/// - **与读视图 [`SessionState`](../enum.SessionState.html) 区分**:`SessionState`
+///   (Streaming/AwaitingApproval/Idle)是面向「是否有审批挂起」的只读视图(读侧收敛①),
+///   `ConvState` 是面向「生成生命周期」的写侧真相(写收敛)。两者正交:如 `Generating` 态
+///   同时有审批挂起时,`ConvState=Generating` 而 `SessionState=AwaitingApproval`。
+///
+/// 序列化(`Serialize`/`Deserialize`):批3 前端经事件总线读 enum 视图时使用(本批未接,
+/// 预留,避免后续改动序列化兼容性)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ConvState {
+    /// 空闲:无 agentic loop 活跃,可接新请求。
+    ///
+    /// 终态目标:所有正常退出路径(完成 / 停止完成 / 错误恢复)的归处。
+    Idle,
+    /// 生成中:agentic loop 流式生成 + 工具执行活跃中(`generating=true`)。
+    ///
+    /// 审批挂起期间 `ConvState` 仍为 `Generating`(审批是 loop 内的暂停点,非独立状态)。
+    Generating,
+    /// 停止中:用户点了停止(`stop_flag` 已置位),loop 检测中或正在收尾退出。
+    ///
+    /// 瞬态:loop 检测到 `stop_flag` 后迁移到 `Idle`(完成收尾),或停止过程出错到 `Error`。
+    Stopping,
+    /// 错误态:生成过程出错(provider 失败 / Fatal / 断路器熔断等),loop 已退出。
+    ///
+    /// 非终态:用户可「重试」从 `Error` → `Idle` → `Generating` 重新发起,或继续空闲。
+    Error,
+    /// 压缩派生态:loop 期间触发上下文压缩(LLM 摘要),生成流程的瞬时派生。
+    ///
+    /// 派生而非独立态:压缩完成(成功 / 失败兜底)后回到原 `Generating`(loop 内压缩)或
+    /// `Idle`(手动压缩 IPC 触发)。前端可据此展示「压缩中」spinner(本批未接)。
+    Compressed,
+}
+
+impl Default for ConvState {
+    /// 新会话默认 `Idle`(无 loop 活跃)。
+    fn default() -> Self {
+        ConvState::Idle
+    }
+}
+
+impl ConvState {
+    /// 尝试迁移到目标态。合法返回 `Ok(新态)`,非法拒绝返回 `Err(InvalidTransition)`。
+    ///
+    /// 调用方持锁后经本方法迁移状态(写收敛):不允许直接写字段绕过守卫。
+    /// 非法转换(如 `Idle → Stopping`,无活跃 loop 不可能停止)直接拒绝——调用方应视为
+    /// 逻辑 bug 并记录 warn 日志,不静默忽略(状态机完整性优先)。
+    ///
+    /// # 合法转换表(7 边)
+    ///
+    /// | from | to | 触发场景 |
+    /// |------|----|---------|
+    /// | Idle | Generating | `run_agentic_loop` 入口,guard set |
+    /// | Generating | Stopping | 用户点停止,置 `stop_flag` |
+    /// | Generating | Idle | loop 正常收敛退出,guard reset |
+    /// | Generating | Error | provider Fatal / 断路器熔断等 |
+    /// | Generating | Compressed | loop 内自动压缩派生 |
+    /// | Stopping | Idle | stop 收尾完成,guard reset |
+    /// | Stopping | Error | 停止过程出错 |
+    /// | Error | Idle | 用户重试前置位(准备再 `Generating`) |
+    /// | Error | Generating | 直接从错误态重新生成(重试) |
+    /// | Compressed | Generating | 压缩完成,loop 内继续 |
+    /// | Compressed | Idle | 手动压缩 IPC 完成(无 loop 活跃) |
+    ///
+    /// 自环(同态 → 同态)允许(幂等写,如 guard 多次 set 同态),返回 `Ok(self)`。
+    pub fn transition_to(self, target: ConvState) -> Result<ConvState, InvalidTransition> {
+        // 自环幂等:同态迁移直接通过(防调用方重复 set 报错)。
+        if self == target {
+            return Ok(target);
+        }
+        // 合法转换白名单(显式列举,非 `match _ => Ok` 兜底——新加态必须显式补边,
+        // 编译器不会漏)。
+        let valid = matches!(
+            (self, target),
+            // Idle 起步
+            (ConvState::Idle, ConvState::Generating)
+            // Generating 分流:停 / 完成 / 错误 / 压缩派生
+            | (ConvState::Generating, ConvState::Stopping)
+            | (ConvState::Generating, ConvState::Idle)
+            | (ConvState::Generating, ConvState::Error)
+            | (ConvState::Generating, ConvState::Compressed)
+            // Stopping 收尾:完成 / 出错
+            | (ConvState::Stopping, ConvState::Idle)
+            | (ConvState::Stopping, ConvState::Error)
+            // Error 恢复:重试前置位 / 直接重新生成
+            | (ConvState::Error, ConvState::Idle)
+            | (ConvState::Error, ConvState::Generating)
+            // Compressed 派生回退:loop 继续 / 手动压缩完成
+            | (ConvState::Compressed, ConvState::Generating)
+            | (ConvState::Compressed, ConvState::Idle)
+        );
+        if valid {
+            Ok(target)
+        } else {
+            Err(InvalidTransition { from: self, to: target })
+        }
+    }
+
+    /// 是否处于活跃生成态(`Generating` / 压缩派生 `Compressed`)。
+    ///
+    /// 读侧便利方法:压缩派生期间 loop 仍活跃(只是临时跑压缩 LLM),归「活跃」。
+    /// 审批挂起(读视图 `SessionState::AwaitingApproval`)期间 `ConvState` 仍是 `Generating`,
+    /// 故本方法返回 true——审批挂起不算「停止生成」。
+    ///
+    /// 预留:批2+ 读侧迁移(try_continue / ai_chat_stop / 前端停止三态)消费。本批仅建状态机 +
+    /// 入口校验,无消费方,标 `allow(dead_code)` 保留(对齐零调用方区分真死 vs 预留原则)。
+    #[allow(dead_code)]
+    pub fn is_active(self) -> bool {
+        matches!(self, ConvState::Generating | ConvState::Compressed)
+    }
+
+    /// 是否可接受新请求(非活跃、非停止中、非压缩派生)。
+    ///
+    /// 读侧便利方法:用于 `ai_conversation_create` / `ai_chat_send` 等入口判断
+    /// 「能否接新请求」。`Error` 态视为可接(用户重试即从 Error 起步)。
+    ///
+    /// 预留:批2+ 读侧迁移(入口能否接新请求判断)消费。本批无消费方,标 `allow(dead_code)` 保留。
+    #[allow(dead_code)]
+    pub fn can_accept_request(self) -> bool {
+        matches!(self, ConvState::Idle | ConvState::Error)
+    }
+}
+
+// ============================================================
+// InvalidTransition(非法转换错误)
+// ============================================================
+
+/// 状态机非法转换错误。
+///
+/// 携带 `from` / `to` 供调用方记录诊断日志(不 panic:状态机完整性违反应记 warn +
+/// 兜底走旧 bool 行为,不阻断核心生成流程——对齐「机制优先,失败兜底」原则)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct InvalidTransition {
+    pub from: ConvState,
+    pub to: ConvState,
+}
+
+impl std::fmt::Display for InvalidTransition {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "ConvState 非法转换:{:?} → {:?}", self.from, self.to)
+    }
+}
+
+impl std::error::Error for InvalidTransition {}
+
+// ============================================================
+// 单元测试(纯逻辑无 IO)
+// ============================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ---- 合法转换通过 ----
+
+    #[test]
+    fn test_idle_to_generating() {
+        assert_eq!(
+            ConvState::Idle.transition_to(ConvState::Generating),
+            Ok(ConvState::Generating)
+        );
+    }
+
+    #[test]
+    fn test_generating_to_stopping() {
+        assert_eq!(
+            ConvState::Generating.transition_to(ConvState::Stopping),
+            Ok(ConvState::Stopping)
+        );
+    }
+
+    #[test]
+    fn test_generating_to_idle_normal_complete() {
+        // loop 正常收敛退出
+        assert_eq!(
+            ConvState::Generating.transition_to(ConvState::Idle),
+            Ok(ConvState::Idle)
+        );
+    }
+
+    #[test]
+    fn test_generating_to_error_provider_fatal() {
+        // provider Fatal / 断路器熔断
+        assert_eq!(
+            ConvState::Generating.transition_to(ConvState::Error),
+            Ok(ConvState::Error)
+        );
+    }
+
+    #[test]
+    fn test_generating_to_compressed_loop_auto_compress() {
+        // loop 内自动压缩派生
+        assert_eq!(
+            ConvState::Generating.transition_to(ConvState::Compressed),
+            Ok(ConvState::Compressed)
+        );
+    }
+
+    #[test]
+    fn test_stopping_to_idle_complete() {
+        // stop 收尾完成
+        assert_eq!(
+            ConvState::Stopping.transition_to(ConvState::Idle),
+            Ok(ConvState::Idle)
+        );
+    }
+
+    #[test]
+    fn test_stopping_to_error() {
+        assert_eq!(
+            ConvState::Stopping.transition_to(ConvState::Error),
+            Ok(ConvState::Error)
+        );
+    }
+
+    #[test]
+    fn test_error_to_idle_retry_prep() {
+        // 用户重试前置位
+        assert_eq!(
+            ConvState::Error.transition_to(ConvState::Idle),
+            Ok(ConvState::Idle)
+        );
+    }
+
+    #[test]
+    fn test_error_to_generating_retry() {
+        // 直接从错误态重新生成
+        assert_eq!(
+            ConvState::Error.transition_to(ConvState::Generating),
+            Ok(ConvState::Generating)
+        );
+    }
+
+    #[test]
+    fn test_compressed_to_generating_loop_continue() {
+        // 压缩完成 loop 内继续
+        assert_eq!(
+            ConvState::Compressed.transition_to(ConvState::Generating),
+            Ok(ConvState::Generating)
+        );
+    }
+
+    #[test]
+    fn test_compressed_to_idle_manual_compress_done() {
+        // 手动压缩 IPC 完成(无 loop 活跃)
+        assert_eq!(
+            ConvState::Compressed.transition_to(ConvState::Idle),
+            Ok(ConvState::Idle)
+        );
+    }
+
+    // ---- 自环幂等 ----
+
+    #[test]
+    fn test_self_transition_idempotent() {
+        // 同态迁移直接通过(防调用方重复 set 报错)
+        for s in [
+            ConvState::Idle,
+            ConvState::Generating,
+            ConvState::Stopping,
+            ConvState::Error,
+            ConvState::Compressed,
+        ] {
+            assert_eq!(s.transition_to(s), Ok(s), "{:?} 自环应通过", s);
+        }
+    }
+
+    // ---- 非法转换拒绝 ----
+
+    #[test]
+    fn test_idle_to_stopping_rejected() {
+        // 无活跃 loop 不可能停止
+        let err = ConvState::Idle
+            .transition_to(ConvState::Stopping)
+            .unwrap_err();
+        assert_eq!(err.from, ConvState::Idle);
+        assert_eq!(err.to, ConvState::Stopping);
+    }
+
+    #[test]
+    fn test_idle_to_error_rejected() {
+        // Idle 直接到 Error 无意义(错误必经活跃态产生)
+        assert!(ConvState::Idle.transition_to(ConvState::Error).is_err());
+    }
+
+    #[test]
+    fn test_idle_to_compressed_rejected() {
+        // 无 loop 活跃不会触发压缩派生(手动压缩 IPC 不经状态机派生)
+        assert!(ConvState::Idle.transition_to(ConvState::Compressed).is_err());
+    }
+
+    #[test]
+    fn test_stopping_to_generating_rejected() {
+        // 停止中不能直接回生成(须先回 Idle 再起)
+        assert!(ConvState::Stopping
+            .transition_to(ConvState::Generating)
+            .is_err());
+    }
+
+    #[test]
+    fn test_stopping_to_compressed_rejected() {
+        assert!(ConvState::Stopping
+            .transition_to(ConvState::Compressed)
+            .is_err());
+    }
+
+    #[test]
+    fn test_error_to_stopping_rejected() {
+        // 错误态已停止,不能再停
+        assert!(ConvState::Error.transition_to(ConvState::Stopping).is_err());
+    }
+
+    #[test]
+    fn test_error_to_compressed_rejected() {
+        assert!(ConvState::Error.transition_to(ConvState::Compressed).is_err());
+    }
+
+    #[test]
+    fn test_compressed_to_stopping_rejected() {
+        // 压缩派生期间不直接到停止(压缩完成后由原态分流)
+        assert!(ConvState::Compressed
+            .transition_to(ConvState::Stopping)
+            .is_err());
+    }
+
+    #[test]
+    fn test_compressed_to_error_rejected() {
+        assert!(ConvState::Compressed
+            .transition_to(ConvState::Error)
+            .is_err());
+    }
+
+    // ---- 便利方法 ----
+
+    #[test]
+    fn test_is_active() {
+        assert!(!ConvState::Idle.is_active());
+        assert!(ConvState::Generating.is_active());
+        assert!(!ConvState::Stopping.is_active());
+        assert!(!ConvState::Error.is_active());
+        // 压缩派生期间 loop 仍活跃(临时跑压缩 LLM)
+        assert!(ConvState::Compressed.is_active());
+    }
+
+    #[test]
+    fn test_can_accept_request() {
+        assert!(ConvState::Idle.can_accept_request());
+        assert!(!ConvState::Generating.can_accept_request());
+        assert!(!ConvState::Stopping.can_accept_request());
+        // Error 态可接(用户重试即从 Error 起步)
+        assert!(ConvState::Error.can_accept_request());
+        assert!(!ConvState::Compressed.can_accept_request());
+    }
+
+    #[test]
+    fn test_default_is_idle() {
+        assert_eq!(ConvState::default(), ConvState::Idle);
+    }
+
+    // ---- 完整生命周期链 ----
+
+    #[test]
+    fn test_full_lifecycle_normal_complete() {
+        // 正常生命周期:Idle → Generating → Idle
+        let s = ConvState::Idle;
+        let s = s.transition_to(ConvState::Generating).unwrap();
+        let s = s.transition_to(ConvState::Idle).unwrap();
+        assert_eq!(s, ConvState::Idle);
+    }
+
+    #[test]
+    fn test_full_lifecycle_with_stop() {
+        // 停止生命周期:Idle → Generating → Stopping → Idle
+        let s = ConvState::Idle;
+        let s = s.transition_to(ConvState::Generating).unwrap();
+        let s = s.transition_to(ConvState::Stopping).unwrap();
+        let s = s.transition_to(ConvState::Idle).unwrap();
+        assert_eq!(s, ConvState::Idle);
+    }
+
+    #[test]
+    fn test_full_lifecycle_with_compress() {
+        // 压缩派生:Idle → Generating → Compressed → Generating → Idle
+        let s = ConvState::Idle;
+        let s = s.transition_to(ConvState::Generating).unwrap();
+        let s = s.transition_to(ConvState::Compressed).unwrap();
+        let s = s.transition_to(ConvState::Generating).unwrap();
+        let s = s.transition_to(ConvState::Idle).unwrap();
+        assert_eq!(s, ConvState::Idle);
+    }
+
+    #[test]
+    fn test_full_lifecycle_error_retry() {
+        // 错误恢复:Idle → Generating → Error → Generating → Idle
+        let s = ConvState::Idle;
+        let s = s.transition_to(ConvState::Generating).unwrap();
+        let s = s.transition_to(ConvState::Error).unwrap();
+        let s = s.transition_to(ConvState::Generating).unwrap();
+        let s = s.transition_to(ConvState::Idle).unwrap();
+        assert_eq!(s, ConvState::Idle);
+    }
+
+    #[test]
+    fn test_invalid_transition_error_display() {
+        // Display 包含 from / to,供日志诊断
+        let err = ConvState::Idle
+            .transition_to(ConvState::Stopping)
+            .unwrap_err();
+        let msg = format!("{}", err);
+        assert!(msg.contains("Idle"), "Display 应含 from: {}", msg);
+        assert!(msg.contains("Stopping"), "Display 应含 to: {}", msg);
+    }
+}

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

@@ -9,6 +9,8 @@ use tokio::sync::Mutex;
 
 use crate::commands::ai::AiSession;
 
+use super::conv_state::{self, ConvState};
+
 /// generating 复位 RAII guard,取代散布的手动 `session.generating = false`。
 ///
 /// 两路复位:
@@ -22,32 +24,87 @@ use crate::commands::ai::AiSession;
 /// F-260616-09 B 批4:guard 持 `conv_id`,复位改写 `session.conv(&conv_id).generating = false`
 /// (per-conv 唯一真相源)。顶层 `session.generating` 字段已在批4 删除,reset/Drop 仅写 per_conv;
 /// IPC(ai_is_generating/ai_chat_send 等)亦改读 per_conv,无需双写桥接。
+///
+/// L2 统一状态机(渐进第一步,2026-06-21):guard 内嵌 `ConvState` 作**写收敛视图层**。
+///
+/// - `new` 时按 `conv_state::CONV_STATE_ENABLED` 门控,把内部 `state` 从 `Idle` 经守卫迁移到
+///   `Generating`(非法转换记 warn 不阻断,对齐「机制优先,失败兜底」原则)。
+/// - `reset` / `drop` 收尾时同步迁移 `Generating → Idle`(状态机视图与 `generating` bool 双轨,
+///   bool 仍是核心真相源,enum 仅视图)。off 降级:guard 不持/不迁 enum,纯旧 bool 行为(可回退)。
+///
+/// **渐进取舍(为什么 enum 放 guard 而非 PerConvState 字段)**:guard 是 loop 生命周期的天然
+/// 边界(set/reset/Drop 成对),把 enum 绑 guard 即覆盖全部生成态进入/退出点,无需改 PerConvState
+/// 字段(改字段会牵动所有读写点,属批2+ 范围)。本批 enum 仅作 guard 内部视图,不对外持久化;
+/// 批2+ 把 enum 提升到 PerConvState.conv_state 字段后,guard 仍可保留作写收敛入口(枚举源切换)。
 pub(super) struct GeneratingGuard {
     session: Arc<Mutex<AiSession>>,
     /// guard 所属会话(loop 启动时快照的 conv_id,来自 run_agentic_loop 入参)。
     conv_id: String,
     done: bool,
+    /// L2 状态机视图(CONV_STATE_ENABLED 门控)。None = 开关 off 降级,guard 不持视图。
+    /// 仅 guard 生命周期内的本地视图,不持久化(批2+ 提升至 PerConvState 字段)。
+    state: Option<ConvState>,
 }
 
 impl GeneratingGuard {
     pub(super) fn new(session: Arc<Mutex<AiSession>>, conv_id: String) -> Self {
-        Self { session, conv_id, done: false }
+        // CONV_STATE_ENABLED 门控:off → state=None,guard 不持/不迁 enum(纯旧 bool 行为)。
+        // on → state 从 Idle 起,入口即经守卫迁移到 Generating(写收敛:状态机入口校验)。
+        let mut state = if conv_state::CONV_STATE_ENABLED {
+            Some(ConvState::Idle)
+        } else {
+            None
+        };
+        if let Some(s) = state.as_mut() {
+            // Idle → Generating 守卫迁移。正常路径(self-loop 幂等 / 首次进入)合法;理论非法不发生
+            // (新 guard 必 Idle),失败记 warn 不阻断(对齐失败兜底原则)。
+            match s.transition_to(ConvState::Generating) {
+                Ok(new_state) => *s = new_state,
+                Err(e) => {
+                    tracing::warn!(
+                        conv_id = %conv_id,
+                        error = %e,
+                        "[ai] guard.new ConvState Idle→Generating 非法(状态机视图层,不阻断核心生成)"
+                    );
+                    // 状态机层失败:enum 保留 Idle(不写非法态),核心 generating 仍由调用方 set true。
+                    // 即 enum 视图与 bool 暂时不同步,但 enum 仅视图不影响核心复位语义。
+                }
+            }
+        }
+        Self { session, conv_id, done: false, state }
     }
 
     /// 显式复位 generating=false。emit 前调用保证顺序。幂等。
     ///
     /// 仅写 per_conv.conv_id.generating(唯一真相源)。
+    /// L2:同步迁移 `ConvState → Idle`(状态机视图,CONV_STATE_ENABLED 门控)。
     pub(super) async fn reset(&mut self) {
         if !self.done {
             let mut session = self.session.lock().await;
             session.conv(&self.conv_id).generating = false;
             self.done = true;
         }
+        // 状态机视图同步:Generating → Idle(正常收敛退出)。仅记日志验证迁移合法(批2+ 接入
+        // PerConvState.conv_state 字段后此处写字段持久化)。done=true 后再次 reset 幂等,enum 已 Idle
+        // 自环通过。开关 off → state=None 跳过(纯旧 bool 行为)。
+        if let Some(s) = self.state.as_mut() {
+            match s.transition_to(ConvState::Idle) {
+                Ok(new_state) => *s = new_state,
+                Err(e) => tracing::warn!(
+                    conv_id = %self.conv_id,
+                    error = %e,
+                    "[ai] guard.reset ConvState →Idle 非法(状态机视图层,不阻断核心复位)"
+                ),
+            }
+        }
     }
 
     /// 解除 Drop 兜底复位但不复位 generating。审批等待 return 路径调用:
     /// 保持 generating=true 留 try_continue 续生成,同时 Drop 因 done=true 跳过复位 spawn。
     /// (B-260615-26: 修复审批执行后对话不续生成回归)
+    ///
+    /// L2:disarm 不迁移 ConvState(审批等待是 Generating 内的暂停点,ConvState 仍 Generating,
+    /// 与「generating 保持 true」语义一致)。续跑时新 guard.new 重新迁移(Generating 自环幂等)。
     pub(super) fn disarm(&mut self) {
         self.done = true;
     }
@@ -55,7 +112,19 @@ impl GeneratingGuard {
 
 impl Drop for GeneratingGuard {
     fn drop(&mut self) {
+        // 状态机视图同步(panic/异常退出路径):未 done 即异常退出,enum 应从 Generating→Idle 收敛。
+        // 仅记日志(无 await 上下文,不写持久化——批2+ 接入字段后此处可写)。
+        // 开关 off / done=true(正常 reset/disarm 已走) → 跳过。
         if !self.done {
+            if let Some(s) = self.state.as_mut() {
+                if let Err(e) = s.transition_to(ConvState::Idle) {
+                    tracing::warn!(
+                        conv_id = %self.conv_id,
+                        error = %e,
+                        "[ai] guard.drop ConvState →Idle 非法(异常退出兜底,核心 generating 仍 spawn 复位)"
+                    );
+                }
+            }
             let session = self.session.clone();
             let conv_id = self.conv_id.clone();
             tauri::async_runtime::spawn(async move {
@@ -65,3 +134,52 @@ impl Drop for GeneratingGuard {
         }
     }
 }
+
+// ============================================================
+// 单元测试(guard 内嵌 ConvState 视图层)
+// ============================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// guard.new 默认迁移 Idle→Generating,内部视图应为 Generating(CONV_STATE_ENABLED on)。
+    ///
+    /// 注:不构造真实 AiSession(lock/Mutex 建会话状态成本高),仅校验 state 字段的迁移语义——
+    /// new 内部 transition_to 是纯函数,直接断言逻辑路径。此处用相同的纯函数路径验证 guard 语义。
+    #[test]
+    fn test_guard_new_migrates_to_generating() {
+        // 模拟 guard.new 内部状态机迁移路径(纯逻辑,无 session):
+        // CONV_STATE_ENABLED on → Idle → Generating。
+        assert!(conv_state::CONV_STATE_ENABLED, "开关默认 on,测试假设");
+        let mut s = ConvState::Idle;
+        s = s.transition_to(ConvState::Generating).unwrap();
+        assert_eq!(s, ConvState::Generating);
+    }
+
+    /// reset 迁移 Generating→Idle(正常收敛),验证迁移合法。
+    #[test]
+    fn test_guard_reset_migrates_to_idle() {
+        let mut s = ConvState::Generating;
+        s = s.transition_to(ConvState::Idle).unwrap();
+        assert_eq!(s, ConvState::Idle);
+    }
+
+    /// 异常 Drop 路径同样 Generating→Idle(兜底),验证迁移合法。
+    #[test]
+    fn test_guard_drop_path_migrates_to_idle() {
+        // guard.drop 异常路径(!done)迁移 Generating→Idle。
+        let mut s = ConvState::Generating;
+        s = s.transition_to(ConvState::Idle).unwrap();
+        assert_eq!(s, ConvState::Idle);
+    }
+
+    /// disarm 不迁移状态(审批等待保持 Generating)。
+    /// 验证:disarm 后 enum 仍 Generating(下次 new 时 Generating 自环幂等通过)。
+    #[test]
+    fn test_guard_disarm_keeps_generating_then_self_loop_on_new() {
+        let s = ConvState::Generating;
+        // disarm 不动 enum;续跑新 guard.new 时 Generating→Generating 自环通过。
+        assert_eq!(s.transition_to(ConvState::Generating), Ok(ConvState::Generating));
+    }
+}

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

@@ -21,7 +21,7 @@ use df_ai::context_helpers::{
 // 收敛的扁平子集之上叠加 plan_hint 编排(并行组同批聚拢/顺序依赖源在前),供 LLM 看到
 // 一份按编排意图排序的工具列表。feature flag PLANNING_ENABLED(false 默认关)门控接入。
 use df_ai::intent::{filter_tool_defs, filter_tool_defs_planned, IntentRecognizer};
-use df_ai::provider::{ChatMessage, CompletionRequest, LlmProvider};
+use df_ai::provider::{ChatMessage, CompletionRequest, LlmProvider, MessageRole};
 // CR-30-1: 复用 retry::backoff_delay(jitter 1s→2s→4s) + is_status_retryable(Fatal 分类)
 // 实现流前失败重试退避对齐(决策 F-260616-07 a1),避免重写退避逻辑。
 use df_ai::retry;
@@ -106,6 +106,30 @@ pub const TOOL_RESULT_COMPRESS_ENABLED: bool = true;
 /// 保守:双高置信才标(任一 topic None 不标),不强制 LLM(软提示非硬约束)。
 pub const TOPIC_MARKER_ENABLED: bool = true;
 
+/// L1 断路器:连续同类工具失败熔断阈值(治 kms 会话 53 轮 0 产出死循环)。
+///
+/// 背景:agent 无止损,某工具反复同类失败(权限拒绝/路径错误等)仍每轮重试,
+/// 耗尽 max_iterations 前 0 产出。机制(非 prompt 教 AI):每轮 process_tool_calls
+/// 后取末尾连续 Tool 消息,失败内容前 40 字符归一为 key 计数,同一 key 累计达此阈值 →
+/// guard.reset + emit AiError + return 强制熔断,逼用户换思路或人工介入。
+///
+/// 阈值 3:同类失败 3 次足以判死循环(去重后仍累加,不同错误各自计数互不干扰)。
+pub const CIRCUIT_BREAKER_THRESHOLD: u32 = 3;
+
+/// L1 断路器总开关(默认 true)。false → 跳过断路器检查,降级为纯 max_iterations
+/// 旧行为(排障/对比/临时关闭用)。机制优先 prompt 说教,每改配开关 + 兜底(关降级旧行为)。
+pub const CIRCUIT_BREAKER_ENABLED: bool = true;
+
+/// L1 断路器熔断时是否发结构化求助(aichat 体验与 agent 能力系统化重构 §2.3,2026-06-21)。
+///
+/// true(默认):熔断 emit AiHelpRequired(结构化求助卡:reason + context + options),
+///   引导用户换思路/授权路径/人工接管(机制优先 prompt 说教,非教 AI 自己止损)。
+/// false(兜底回退):熔断仍 emit AiError(旧行为,前端错误气泡),用于求助卡未就绪/
+///   排障/对比。两路保留 guard.reset + return 强制熔断语义不变,仅换前端呈现形态。
+/// 配合 CIRCUIT_BREAKER_ENABLED:CIRCUIT_BREAKER_ENABLED=false 时断路器整段跳过,
+///   本开关无意义;CIRCUIT_BREAKER_ENABLED=true 时本开关决定呈现形态。
+pub const CIRCUIT_BREAKER_HELP_EVENT: bool = true;
+
 // 阶段2(path_auth 审批链重构):占位配对完整性开关(解 400 orphan)。
 //
 // 单一真相源:`df_ai::context_helpers::PLACEHOLDER_INTEGRITY_ENABLED`(本模块顶部已 use)。
@@ -131,6 +155,22 @@ pub const TOPIC_MARKER_ENABLED: bool = true;
 mod guard;
 use guard::GeneratingGuard;
 
+// ============================================================
+// L2 统一状态机(渐进第一步,2026-06-21):ConvState enum + 转换守卫。
+// 设计:generating状态机加固-2026-06-15.md §3 + aichat体验与agent能力系统化重构-2026-06-21.md §3。
+//
+// 本批范围(渐进):
+//   - 新建 conv_state.rs(纯逻辑 enum + 守卫 + 单测)。
+//   - run_agentic_loop 入口桥接:guard 置 generating=true 时同步迁移 ConvState
+//     (Idle→Generating / Error→Generating),作视图层。CONV_STATE_ENABLED 开关门控。
+//   - guard.reset 同步 ConvState→Idle(正常退出路径)。
+//   - **不替换** PerConvState.generating bool(渐进不一次全换,批2+ 逐步迁读侧)。
+//
+// 开关 CONV_STATE_ENABLED(默认 on):off 降级纯旧 bool 行为(可回退)。
+// 兜底:状态机层迁移失败(非法转换)记 warn 不 panic,核心 generating 复位仍走旧 bool。
+// ============================================================
+pub mod conv_state;
+
 // ============================================================
 // F-260614-04 / F-260614-04b: 单 Provider 流式结果 + fallback 辅助
 // ============================================================
@@ -374,6 +414,11 @@ pub(crate) async fn run_agentic_loop(
     //
     // 单 loop 安全性:批2 阶段是单 active_conversation_id(决策 e 真并发批3+ 落地),无并发 loop 抢
     // per_conv 覆盖。批3+ 多 loop 并发时,每 conv 各自 per_conv 条目,互不干扰(本桥接无需改)。
+    //
+    // L2 状态机视图层:ConvState 的写收敛已收敛到 `guard`(GeneratingGuard::new 已在上方 L399 创建,
+    // new 内部 Idle→Generating 迁移 + reset/drop Generating→Idle 迁移,CONV_STATE_ENABLED 门控)。
+    // 此处不再重复迁移 enum,仅写核心 generating bool(唯一真相源,enum 是其视图)。批2+ 把 enum
+    // 提升到 PerConvState.conv_state 字段后,此 bool 写入与 enum 迁移由 guard 统一收敛。
     {
         let mut session = session_arc.lock().await;
         let conv = session.conv(&conv_id);
@@ -601,6 +646,10 @@ pub(crate) async fn run_agentic_loop(
     // 区分"正常收敛退出"与"达 MAX 被截断退出"——后者末轮 tool_calls 仍非空(tool_result 不再回传 LLM),属异常
     let mut converged = false;
 
+    // L1 断路器:连续同类工具失败计数器(key=失败内容前 40 字符,value=累计次数)。
+    // loop 生命周期内累加,每轮 process_tool_calls 后检查。达 CIRCUIT_BREAKER_THRESHOLD → 熔断退出。
+    let mut fail_counts: std::collections::HashMap<String, u32> = std::collections::HashMap::new();
+
     // BUG-260617-12: DeepSeek thinking 模式推理内容跨轮透传
     let mut last_reasoning_content: Option<String> = None;
 
@@ -1240,6 +1289,95 @@ pub(crate) async fn run_agentic_loop(
             "[AI-DIRAUTH-DIAG] agentic loop 收到 pending"
         );
 
+        // L1 断路器:连续同类工具失败熔断(治 agent 无止损死循环,机制非 prompt 说教)。
+        // CIRCUIT_BREAKER_ENABLED=false → 整段跳过降级 max_iterations 旧行为(开关 + 兜底)。
+        // 仅检查自动执行(Low)的工具结果——pending_count>0(待审批)交给下方审批分支,
+        // 此处只看已回填的 Tool 消息。取末尾连续 Tool 消息(倒序 take_while role==Tool),
+        // 失败内容前 40 字符归一 key 计数,同 key 累计达阈值 → guard.reset + AiError + return。
+        if CIRCUIT_BREAKER_ENABLED {
+            let (max_count, sample_key) = {
+                let session = session_arc.lock().await;
+                // conv 可能已被删除(stop/新对话),get 不到 → 无消息可判,跳过本轮断路器检查。
+                let messages = match session.conv_read(&conv_id) {
+                    Some(conv) => conv.messages.all_messages_clone(),
+                    None => Vec::new(),
+                };
+                // 倒序取末尾连续 role==Tool 消息(本轮工具回填结果;非 Tool 即停)。
+                // MessageRole 未派生 PartialEq,用 matches! 宏判变体(不改共享类型 df-ai-core)。
+                let recent_tool_results: Vec<&ChatMessage> = messages
+                    .iter()
+                    .rev()
+                    .take_while(|m| matches!(m.role, MessageRole::Tool))
+                    .collect();
+                for m in recent_tool_results {
+                    let content = m.content.as_str();
+                    // 失败判定:禁止/跳过重试/失败/Error 关键词(覆盖权限拒绝/路径错误/异常等)。
+                    let is_failure = content.starts_with("禁止")
+                        || content.starts_with("已跳过重试")
+                        || content.contains("失败")
+                        || content.contains("Error")
+                        || content.contains("error");
+                    if is_failure {
+                        // 前 40 字符归一 key:同类失败(同前缀)累加,不同错误各自计数互不干扰。
+                        let key: String = content.chars().take(40).collect();
+                        *fail_counts.entry(key).or_insert(0) += 1;
+                    }
+                }
+                // 取当前最大计数及其 key(无失败 → max_count=0,不触发)。
+                fail_counts
+                    .iter()
+                    .max_by_key(|(_, &v)| v)
+                    .map(|(k, &v)| (v, k.clone()))
+                    .unwrap_or((0u32, String::new()))
+            };
+            // 锁已随作用域 drop,可安全 await/emit(避免持锁 await 死锁)。
+            if max_count >= CIRCUIT_BREAKER_THRESHOLD {
+                tracing::warn!(
+                    conv_id = %conv_id,
+                    max_count,
+                    sample_key = %sample_key,
+                    "[ai] L1 断路器熔断:连续同类失败 {} 次,疑似死循环停止", max_count
+                );
+                guard.reset().await;
+                // L1 求助协议(§2.3,2026-06-21):熔断改发结构化 AiHelpRequired(机制优先 prompt 说教)。
+                // 开关 CIRCUIT_BREAKER_HELP_EVENT=true(默认)→ AiHelpRequired(求助卡,显 reason/options
+                //   供用户选);false(兜底回退)→ AiError(旧错误气泡)。两路均 guard.reset + return 强制熔断,
+                //   仅前端呈现形态不同,语义不变(均终止 loop,逼用户介入)。
+                if CIRCUIT_BREAKER_HELP_EVENT {
+                    let _ = app_handle.emit(
+                        "ai-chat-event",
+                        AiChatEvent::AiHelpRequired {
+                            reason: format!(
+                                "连续同类失败 {} 次,疑似死循环已停止",
+                                max_count
+                            ),
+                            context: format!("最近错误: {}", sample_key),
+                            options: vec![
+                                "换思路".into(),
+                                "授权路径".into(),
+                                "人工接管".into(),
+                            ],
+                            conversation_id: Some(conv_id.clone()),
+                        },
+                    );
+                } else {
+                    // 兜底回退:求助卡未就绪/排障/对比时,沿用旧 AiError 错误气泡呈现。
+                    let _ = app_handle.emit(
+                        "ai-chat-event",
+                        AiChatEvent::AiError {
+                            error: format!(
+                                "连续同类失败 {} 次,疑似死循环已停止。请换思路或人工介入。最近错误: {}",
+                                max_count, sample_key
+                            ),
+                            error_type: Some(ErrorType::Unknown),
+                            conversation_id: Some(conv_id.clone()),
+                        },
+                    );
+                }
+                return;
+            }
+        }
+
         // 有待审批 → 暂停循环，等待用户审批后通过 ai_approve → try_continue_agent_loop 恢复
         if pending_count > 0 {
             let usage = df_ai::provider::TokenUsage {

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

@@ -30,7 +30,7 @@ use super::super::augmentation::build_augmentation_segment;
 use super::super::augmentation::sanitize;
 use super::super::conversation::save_conversation;
 use super::super::knowledge_inject::inject_knowledge_into_prompt;
-use super::super::prompt::build_system_prompt;
+use super::super::prompt::{build_system_prompt, build_system_prompt_with_excluded};
 
 use super::super::{AiChatEvent, ApprovalKind, SessionState};
 
@@ -137,6 +137,29 @@ fn span_to_mention_ref(span: &MentionSpanDto) -> Option<MentionRef> {
     }
 }
 
+/// 从 mention_spans 提取 (被@的项目 id 列表, 被@的任务 id 列表)。
+///
+/// 用于 [`build_system_prompt_with_excluded`] 的去重入参:被@的 project/task 已有 augmentation
+/// 精准投影,需从全局清单中排除以免同一实体两次入 prompt(skill/idea 不在清单内,无需排除)。
+///
+/// - `None` / 空 spans → 两个空 vec(行为退化为无去重的全貌清单,等同旧 build_system_prompt)。
+/// - 仅收集 kind == "project" / "task" 的 `ref_id`(idea/skill 不进项目/任务清单)。
+/// - 不去重(同实体被@多次理论上不会出现,即便出现 excluded 列表多次命中也只是 continue,无副作用)。
+fn excluded_ids_from_mentions(spans: &Option<Vec<MentionSpanDto>>) -> (Vec<String>, Vec<String>) {
+    let mut proj = Vec::new();
+    let mut task = Vec::new();
+    if let Some(spans) = spans.as_ref() {
+        for span in spans {
+            match span.kind.as_str() {
+                "project" => proj.push(span.ref_id.clone()),
+                "task" => task.push(span.ref_id.clone()),
+                _ => {}
+            }
+        }
+    }
+    (proj, task)
+}
+
 // ============================================================
 // 发送 / 审批 / 控制
 // ============================================================
@@ -363,7 +386,11 @@ pub async fn ai_chat_send(
     // 获取工具定义(预取仅用于触发注册表初始化,实际 tool_defs 在 agentic loop 内部按需获取)
     let _tool_defs = state.ai_tools.tool_definitions();
     let lang = language.unwrap_or_else(|| "zh-CN".to_string());
-    let mut system_prompt = build_system_prompt(&state, &lang).await;
+    // 去重:从 mention_spans 提取被@的 project/task id,传给 prompt 构建器从全局清单中排除
+    // (被@实体已有 augmentation 精准投影,清单再现致同一实体两次入 prompt)。
+    // mention_spans 为 None/空时返回两个空 vec(行为退化为无去重的全貌清单)。
+    let (excl_proj, excl_task) = excluded_ids_from_mentions(&mention_spans);
+    let mut system_prompt = build_system_prompt_with_excluded(&state, &lang, &excl_proj, &excl_task).await;
     // Augmentation 注入:/ 技能 + @ mention 经统一 Resolver 投影后拼到 system prompt 前。
     // 隔离标注(build_augmentation_segment 头尾包裹,FR-S4 风格)防 prompt injection 与用户指令/行为准则混淆。
     let aug_seg = resolve_and_inject(&state, &provider_config, &skill, &mention_spans, &lang).await;
@@ -1353,7 +1380,9 @@ pub async fn ai_chat_force_send(
     // system prompt 构建(照 ai_chat_send):augmentation 注入 + 知识注入顺序一致。
     let _tool_defs = state.ai_tools.tool_definitions();
     let lang = language.unwrap_or_else(|| "zh-CN".to_string());
-    let mut system_prompt = build_system_prompt(&state, &lang).await;
+    // 去重:同 ai_chat_send,从 mention_spans 提取被@的 project/task id 从清单排除。
+    let (excl_proj, excl_task) = excluded_ids_from_mentions(&mention_spans);
+    let mut system_prompt = build_system_prompt_with_excluded(&state, &lang, &excl_proj, &excl_task).await;
     // Augmentation 注入:/ 技能 + @ mention 经统一 Resolver 投影(语义同 ai_chat_send)。
     let aug_seg = resolve_and_inject(&state, &provider_config, &skill, &mention_spans, &lang).await;
     if !aug_seg.is_empty() {

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

@@ -0,0 +1,375 @@
+//! 全局事件数据总线 — pub-sub 骨架(L3 阶段1,渐进第一步)
+//!
+//! 关联设计:docs/02-架构设计/专项设计/全局事件数据总线-2026-06-21.md
+//!
+//! 本模块是 **统一事件数据总线(Unified Event Bus)** 的后端骨架,聚焦 **pub-sub**(发布订阅)
+//! 语义。背景:当前 AI 事件经 `app_handle.emit("ai-chat-event", ...)` 散布在各处,无统一总线,
+//! 跨模块直接耦合,阻碍 ai-working 可插拔 + 跨端透传。
+//!
+//! ## 本批范围(L3 骨架,纯新增无行为变化)
+//! - `EventBus` 结构(基于 tokio::sync::broadcast,容量 256)
+//! - `AiBusEvent` 强类型 enum(覆盖关键事件:Stream/Tool/Round/Help/Heartbeat/Completed/Error,
+//!   对齐现有 `AiChatEvent` 子集)
+//! - `subscribe()` / `publish()` 基础接口
+//! - `EVENT_BUS_ENABLED` 开关(预留,默认 on —— 总线骨架自带,但接入实际事件源时此开关控制是否经总线)
+//! - pub/sub 基础单元测试
+//!
+//! ## 不做(留后续批次)
+//! - 不接入 `agentic/mod.rs` 各 emit 点(B 域,留批2接入)
+//! - 不入 `AppState`(接入留批2)
+//! - 不碰前端订阅渲染(留批2 Tauri bridge)
+//! - 不实现 request-reply / 流式 reply(设计阶段2/5,本批仅 pub-sub)
+//! - 不做跨端透传(df-tunnel adapter,阶段6)
+//!
+//! ## 开关与兜底(渐进可回退)
+//! - `EVENT_BUS_ENABLED: bool`(默认 true):接入事件源后,关闭则 publish 静默丢弃(不影响原 emit 路径)。
+//!   骨架阶段未接入,无实际效果,预留作接入期的快速回退开关。
+//! - publish 返回 `usize`(接收者数量),调用方可忽略;无接收者时不报错(broadcast 语义)。
+//! - 慢消费者(broadcast 满):`send` 返 `Err(SendError)`,本骨架 `publish` 静默丢弃并返回 0,
+//!   不 panic(对齐设计待决策6「背压/限流」的保守默认,正式背压策略留后续)。
+//!
+//! ## 与 df-workflow EventBus 关系
+//! df-workflow 的 `EventBus`(`crates/df-workflow/src/eventbus.rs`)是工作流节点间专用总线
+//! (仅 `WorkflowEvent`),本总线是面向 AI 域的通用 pub-sub(对齐 `AiChatEvent` 子集)。
+//! 设计阶段1 计划「df-workflow EventBus 包装为通用 DomainEvent」,本骨架先建 AI 域总线,
+//! 通用 DomainEvent 泛化留后续(待决策1 bus crate 位置 + 待决策2 事件 schema)。
+
+use tokio::sync::broadcast;
+
+// ============================================================
+// 开关(EVENT_BUS_ENABLED,预留,默认 on)
+//
+// 机制:接入事件源后,关闭则 EventBus::publish 静默丢弃事件(原 app.emit 路径不受影响,
+// 双写桥接由接入批负责,关闭总线仅丢总线副本)。骨架阶段未接入,开关预留作接入期快速回退。
+//
+// 兜底:即便开关误关,总线静默丢事件不影响原 emit 路径(AiChatEvent 经 app.emit 仍正常推送前端)。
+// ============================================================
+
+/// 事件总线开关(预留,默认 on)。
+///
+/// 接入实际事件源后,`EventBus::publish` 在 `false` 时静默丢弃(返回 0),原 `app.emit`
+/// 路径不受影响。骨架阶段未接入,无实际效果。
+///
+/// dead_code 说明:本批为骨架,EVENT_BUS_ENABLED 暂无消费方(未接入 emit 点);
+/// 标 allow 保留作批2接入期的快速回退开关(零调用方≠垃圾,预留保留)。
+#[allow(dead_code)]
+pub const EVENT_BUS_ENABLED: bool = true;
+
+/// 默认事件通道容量(对齐 df-workflow EventBus 默认 256)。
+///
+/// 容量权衡:太小 → 慢消费者丢事件(订阅者消费不及时);太大 → 内存占用。
+/// 256 是 broadcast 常见默认值,覆盖典型 AI 流场景(文本片段 + 工具调用 + 心跳混合)。
+///
+/// dead_code 说明:骨架阶段 EventBus::new() 内联用字面量路径常量,但常量本身供
+/// 外部自定义容量场景引用,标 allow 保留(预留)。
+#[allow(dead_code)]
+pub const DEFAULT_BUS_CAPACITY: usize = 256;
+
+// ============================================================
+// AiBusEvent — 总线事件类型(对齐 AiChatEvent 子集)
+//
+// 设计取舍(对齐设计文档待决策2「事件 schema」倾向:强类型 + 开放式):
+// - 强类型 enum:编译期安全,新增事件类型需改 enum(扩展成本可控,AI 域事件类型有限且稳定)
+// - 覆盖关键事件:Stream(流式文本)/Tool(工具调用)/Round(agent 新轮)/Help(求助)/
+//   Heartbeat(心跳)/Completed(完成)/Error(错误) —— 对齐现有 AiChatEvent 高频子集
+//
+// 与 AiChatEvent 区别:
+// - AiChatEvent 是「后端→前端单向推送载荷」(经 app.emit,Tauri 序列化,前端消费)
+// - AiBusEvent 是「总线内部事件」(经 broadcast channel,后端模块间消费,设计上可桥接到前端)
+// 本骨架 AiBusEvent 复用 AiChatEvent 字段语义,但作为独立类型(总线事件 ≠ 前端载荷,未来
+// 可能分叉:如总线事件携带 reply_to / correlation_id 等 request-reply 元数据)。
+//
+// 序列化:derive Serialize/Deserialize 备跨端透传(serde JSON,待决策4);Clone 备 broadcast
+// 多订阅者复制;Debug 备日志诊断。
+// ============================================================
+
+/// AI 事件总线事件(pub-sub 域,对齐 AiChatEvent 子集)。
+///
+/// 总线订阅者经 `EventBus::subscribe()` 拿 Receiver 后 recv 本类型事件。
+/// 事件类型覆盖关键 AI 生命周期:流式文本 / 工具调用 / agent 新轮 / 求助 / 心跳 / 完成 / 错误。
+///
+/// dead_code 说明:骨架阶段 enum 本身未在 emit 点构造(批2接入),标 allow 保留
+/// (零调用方≠垃圾,本枚举为总线核心契约,批2接入立即消费)。
+#[allow(dead_code)]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum AiBusEvent {
+    /// 流式文本片段(对齐 AiChatEvent::AiTextDelta)
+    Stream {
+        delta: String,
+        conversation_id: Option<String>,
+    },
+    /// 工具调用开始(对齐 AiChatEvent::AiToolCallStarted)
+    ToolStarted {
+        id: String,
+        name: String,
+        args: serde_json::Value,
+        conversation_id: Option<String>,
+    },
+    /// 工具调用完成(对齐 AiChatEvent::AiToolCallCompleted)
+    ToolCompleted {
+        id: String,
+        result: serde_json::Value,
+        conversation_id: Option<String>,
+    },
+    /// Agent 循环新一轮(对齐 AiChatEvent::AiAgentRound)
+    Round {
+        round: u32,
+        conversation_id: Option<String>,
+    },
+    /// 求助(对齐 AiChatEvent::AiHelpRequired,L1 求助协议)
+    Help {
+        reason: String,
+        context: String,
+        options: Vec<String>,
+        conversation_id: Option<String>,
+    },
+    /// 流式心跳(对齐 AiChatEvent::AiHeartbeat,静默期报活)
+    Heartbeat {
+        conversation_id: Option<String>,
+    },
+    /// AI 响应完成(对齐 AiChatEvent::AiCompleted)
+    Completed {
+        total_tokens: u32,
+        prompt_tokens: u32,
+        completion_tokens: u32,
+        conversation_id: Option<String>,
+    },
+    /// 错误(对齐 AiChatEvent::AiError)
+    Error {
+        error: String,
+        conversation_id: Option<String>,
+    },
+}
+
+// ============================================================
+// EventBus — 基于 tokio::sync::broadcast 的 pub-sub 总线
+//
+// 选 broadcast 而非 mpsc:
+// - pub-sub 多订阅者(mpsc 单消费者不满足「多模块订阅同一事件」场景)
+// - broadcast 容量固定,慢消费者丢老事件而非阻塞发布者(对齐流式场景:宁可丢老 chunk 不阻塞 LLM 流)
+//
+// Clone 语义:broadcast::Sender 内部 Arc,clone 共享同一通道(多持有者 publish 到同一总线)。
+// 对齐设计 §架构「模块订阅 + 发布,无相互 import」—— 各模块持 clone 的 EventBus 即可 pub/sub。
+// ============================================================
+
+/// AI 事件总线(pub-sub 域,L3 阶段1 骨架)。
+///
+/// 基于 `tokio::sync::broadcast`,多订阅者多发布者共享同一通道。
+/// - `subscribe()`:订阅,返回 [`broadcast::Receiver`] recv [`AiBusEvent`]
+/// - `publish(event)`:发布,所有活跃订阅者收到(broadcast 语义)
+///
+/// 容量默认 256(`DEFAULT_BUS_CAPACITY`),可经 [`EventBus::with_capacity`] 自定义。
+///
+/// 兜底:
+/// - 无订阅者时 publish 不报错(broadcast 语义,事件丢弃)
+/// - 慢消费者(容量满)publish 返 0(静默丢老事件,不 panic)
+/// - `EVENT_BUS_ENABLED=false` 时 publish 静默丢弃(预留开关,接入期回退用)
+///
+/// dead_code 说明:骨架阶段未入 AppState、未在 emit 点构造(批2接入),标 allow 保留
+/// (总线核心结构,批2接入 AppState 即消费)。
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct EventBus {
+    sender: broadcast::Sender<AiBusEvent>,
+}
+
+/// 事件订阅者(broadcast::Receiver,AiBusEvent 接收端)。
+///
+/// dead_code 说明:骨架阶段无外部消费方(批2接入订阅),标 allow 保留。
+#[allow(dead_code)]
+pub type EventSubscriber = broadcast::Receiver<AiBusEvent>;
+
+// dead_code 说明(impl 块):骨架阶段 EventBus 未入 AppState、无外部调用方
+// (批2接入 AppState + emit 点后立即消费)。标 allow 覆盖 new/with_capacity/
+// subscribe/publish/subscriber_count 全部关联项的 never-used 警告。
+// 对齐零调用方原则:预留保留不盲删(批2接入即消除)。
+#[allow(dead_code)]
+impl EventBus {
+    /// 创建默认容量(256)的事件总线。
+    pub fn new() -> Self {
+        Self::with_capacity(DEFAULT_BUS_CAPACITY)
+    }
+
+    /// 创建指定容量的事件总线。
+    ///
+    /// capacity 为 0 会 panic(broadcast::channel 要求 capacity ≥ 1)。
+    pub fn with_capacity(capacity: usize) -> Self {
+        let (sender, _) = broadcast::channel(capacity);
+        Self { sender }
+    }
+
+    /// 订阅事件总线,返回 Receiver。
+    ///
+    /// 订阅后仅收到订阅时刻之后的 publish(历史事件不补发)。可多次 subscribe 获多个独立 Receiver,
+    /// 每个 Receiver 各自维护消费进度(broadcast 多消费者语义)。
+    pub fn subscribe(&self) -> EventSubscriber {
+        self.sender.subscribe()
+    }
+
+    /// 发布事件到总线。
+    ///
+    /// 返回值:成功送达的活跃订阅者数量(0 = 无订阅者或容量满丢老事件)。
+    /// `EVENT_BUS_ENABLED=false` 时静默丢弃返回 0(预留开关,骨架阶段未接入)。
+    ///
+    /// 注:broadcast::send 是同步方法(非 async),与 df-workflow EventBus::send 的 async 签名
+    /// 不同 —— 本骨架 publish 同步返回更直接(broadcast::send 内部无 await 点),df-workflow 的
+    /// async 签名是为对齐 trait 抽象,本总线无此约束故同步。
+    pub fn publish(&self, event: AiBusEvent) -> usize {
+        if !EVENT_BUS_ENABLED {
+            return 0;
+        }
+        // broadcast::send 返 Result<usize, SendError>:
+        //   Ok(n) = 送达 n 个活跃订阅者
+        //   Err(SendError(_)) = 无订阅者(事件丢弃)
+        // 两种情况都不 panic,Err 视为 0(对齐「无订阅者静默丢弃」兜底)。
+        self.sender.send(event).unwrap_or(0)
+    }
+
+    /// 当前活跃订阅者数量(broadcast::receiver_count)。
+    ///
+    /// 诊断/监控用:接入期可观测订阅者是否到位。骨架阶段无实际调用,预留作可观测性扩展。
+    pub fn subscriber_count(&self) -> usize {
+        self.sender.receiver_count()
+    }
+}
+
+impl Default for EventBus {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ============================================================
+// 单元测试 — pub/sub 基础语义
+//
+// 覆盖:
+//   1. subscribe 后 publish,receiver 收到事件(基础 pub-sub)
+//   2. 多订阅者都收到(broadcast 多消费者)
+//   3. 无订阅者时 publish 不 panic(兜底)
+//   4. publish 返回值 = 活跃订阅者数量
+//
+// 不覆盖(留后续批次接入时):
+//   - 慢消费者容量满丢老事件(需灌满容量场景,接入期补)
+//   - 跨模块解耦实际效果(需接入真实 emit 点,批2)
+// ============================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 基础 pub-sub:subscribe 后 publish,receiver 收到事件。
+    #[tokio::test]
+    async fn test_basic_pub_sub() {
+        let bus = EventBus::new();
+        let mut rx = bus.subscribe();
+
+        let event = AiBusEvent::Stream {
+            delta: "hello".to_string(),
+            conversation_id: Some("conv-1".to_string()),
+        };
+
+        let delivered = bus.publish(event.clone());
+        assert_eq!(delivered, 1, "publish 应送达 1 个订阅者");
+
+        let received = rx.recv().await.expect("receiver 应收到事件");
+        match received {
+            AiBusEvent::Stream { delta, conversation_id } => {
+                assert_eq!(delta, "hello");
+                assert_eq!(conversation_id.as_deref(), Some("conv-1"));
+            }
+            other => panic!("期望 Stream 事件,收到 {:?}", other),
+        }
+    }
+
+    /// 多订阅者都收到(broadcast 多消费者语义)。
+    #[tokio::test]
+    async fn test_multiple_subscribers() {
+        let bus = EventBus::new();
+        let mut rx1 = bus.subscribe();
+        let mut rx2 = bus.subscribe();
+
+        let event = AiBusEvent::Heartbeat {
+            conversation_id: None,
+        };
+        let delivered = bus.publish(event.clone());
+        assert_eq!(delivered, 2, "publish 应送达 2 个订阅者");
+
+        // 两个 receiver 各自收到(独立消费进度)
+        let r1 = rx1.recv().await.expect("rx1 应收到");
+        let r2 = rx2.recv().await.expect("rx2 应收到");
+        assert!(matches!(r1, AiBusEvent::Heartbeat { .. }));
+        assert!(matches!(r2, AiBusEvent::Heartbeat { .. }));
+    }
+
+    /// 无订阅者时 publish 不 panic,返回 0(兜底)。
+    #[test]
+    fn test_publish_no_subscribers() {
+        let bus = EventBus::new();
+        // 无 subscribe 直接 publish
+        let delivered = bus.publish(AiBusEvent::Error {
+            error: "no one listening".to_string(),
+            conversation_id: None,
+        });
+        assert_eq!(delivered, 0, "无订阅者 publish 应返回 0");
+    }
+
+    /// publish 返回值 = 活跃订阅者数量(subscriber_count 对齐)。
+    #[test]
+    fn test_delivered_count_matches_subscribers() {
+        let bus = EventBus::new();
+        assert_eq!(bus.subscriber_count(), 0);
+
+        let _rx1 = bus.subscribe();
+        assert_eq!(bus.subscriber_count(), 1);
+
+        let _rx2 = bus.subscribe();
+        assert_eq!(bus.subscriber_count(), 2);
+
+        // delivered 应等于 subscriber_count
+        let delivered = bus.publish(AiBusEvent::Round {
+            round: 1,
+            conversation_id: None,
+        });
+        assert_eq!(delivered, bus.subscriber_count());
+    }
+
+    /// EventBus Clone 后共享同一通道(同一总线多持有者)。
+    #[tokio::test]
+    async fn test_clone_shares_channel() {
+        let bus = EventBus::new();
+        let mut rx = bus.subscribe();
+        let bus_clone = bus.clone();
+
+        // 经 clone 的实例 publish,原实例订阅的 receiver 也应收到(共享通道)
+        bus_clone.publish(AiBusEvent::Completed {
+            total_tokens: 100,
+            prompt_tokens: 50,
+            completion_tokens: 50,
+            conversation_id: None,
+        });
+
+        let received = rx.recv().await.expect("clone 共享通道,receiver 应收到");
+        assert!(matches!(received, AiBusEvent::Completed { .. }));
+    }
+
+    /// 全事件类型枚举可构造 + 可序列化(serde 备跨端透传)。
+    #[test]
+    fn test_event_variants_serde() {
+        let events = vec![
+            AiBusEvent::Stream { delta: "x".into(), conversation_id: None },
+            AiBusEvent::ToolStarted { id: "t1".into(), name: "write_file".into(), args: serde_json::json!({}), conversation_id: None },
+            AiBusEvent::ToolCompleted { id: "t1".into(), result: serde_json::json!({"ok": true}), conversation_id: None },
+            AiBusEvent::Round { round: 2, conversation_id: None },
+            AiBusEvent::Help { reason: "r".into(), context: "c".into(), options: vec!["a".into()], conversation_id: None },
+            AiBusEvent::Heartbeat { conversation_id: None },
+            AiBusEvent::Completed { total_tokens: 1, prompt_tokens: 1, completion_tokens: 1, conversation_id: None },
+            AiBusEvent::Error { error: "e".into(), conversation_id: None },
+        ];
+        // 每个变体都能序列化(serde tag = "type" 生效,备跨端透传)
+        for event in &events {
+            let json = serde_json::to_string(event).expect("事件应可序列化");
+            assert!(json.contains("\"type\""), "序列化后应含 type tag: {}", json);
+        }
+    }
+}

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

@@ -13,6 +13,7 @@
 //! - [`prompt`] — 系统提示词构建
 //! - [`provider_pool`] — F-260614-04 多 Provider 负载均衡池选择(纯逻辑)
 //! - [`compress`] — F-15 上下文压缩 LLM 摘要(compress_via_llm 公共函数)
+//! - [`event_bus`] — L3 全局事件数据总线 pub-sub 骨架(broadcast,渐进第一步,未接入 emit)
 //! - [`tool_registry`] — AI 工具注册表构建 + 文件路径校验
 //! - [`knowledge_inject`] — 知识库注入 + 提炼
 //! - [`augmentation`] — 上下文增强
@@ -31,6 +32,7 @@ pub mod audit;
 pub mod commands;
 pub mod compress;
 pub mod conversation;
+pub mod event_bus;
 pub mod http;
 pub mod knowledge_inject;
 pub mod prompt;
@@ -175,6 +177,26 @@ pub enum AiChatEvent {
     AiCompressing { conversation_id: Option<String> },
     /// F-15 阶段2 手动 LLM 压缩完成:摘要已插入消息首位,前端可展示摘要 + 移除压缩中态。
     AiCompressed { conversation_id: Option<String>, summary: String },
+    /// L1 求助协议(aichat 体验与 agent 能力系统化重构 §2.3,2026-06-21):
+    ///
+    /// agent 断路器(§2.2)熔断 / 自省(识别"我反复失败")时发,区别于 prompt 教 AI
+    /// 「失败就问用户」——LLM 不可靠,故用结构化事件 + 前端求助卡(机制优先 prompt 说教)。
+    ///
+    /// 字段语义:
+    /// - `reason`:求助原因(死循环/环境未知/权限不足等可读摘要,前端直接展示)
+    /// - `context`:已试情况(失败次数/最近错误 sample/卡在哪),供用户判断如何介入
+    /// - `options`:建议选项(如 [换思路/授权路径/人工接管]),前端渲染为按钮供用户选
+    /// - `conversation_id`:多对话路由(与其他事件一致)
+    ///
+    /// 与 AiApprovalRequired 区分:审批=工具执行前确认;求助=AI 主动「我搞不定」。
+    /// 与 AiMaxRoundsReached 区分:达 max 是被动截断;求助是主动识别卡点。
+    /// 兜底:开关 CIRCUIT_BREAKER_ENABLED=false 或求助消费方未接 → 后端保留 AiError 终态分支兜底。
+    AiHelpRequired {
+        reason: String,
+        context: String,
+        options: Vec<String>,
+        conversation_id: Option<String>,
+    },
 }
 
 // ============================================================

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

@@ -31,24 +31,31 @@ pub(crate) async fn get_active_provider(state: &AppState) -> Result<AiProviderRe
     }
 }
 
-/// 当前运行环境信息（注入 system prompt，供 LLM 写日期/命令时参考）
+/// 当前运行环境画像(注入 system prompt):日期 + OS + shell 执行姿势 + 可用解释器。
+/// L1 环境感知(治 kms seq26-52 引号地狱):教 AI 避命令行 -c 内联,复杂脚本写文件执行。
 ///
-/// - 日期：LLM 无法自行获取当前日期，不注入则写文件日期全靠猜（常从项目已有文件名模式推断出错）
-/// - 操作系统：LLM 写 shell 命令需知道平台（dir vs ls、路径分隔符等）
+/// - 日期:LLM 无法自行获取,不注入则写文件日期全靠猜
+/// - OS + shell:平台对应 shell(Windows=PowerShell / Linux·macOS=bash),AI 写命令需对齐
+/// - 执行姿势:复杂脚本(多行/含引号/$变量)写 .ps1/.py 文件用 `powershell -File`/`python` 执行,
+///   避免命令行 -c 内联(cmd/PowerShell 引号转义易出错,kms 实证 20+ 次失败)
+/// - 可用解释器:Windows=python(无 python3);Linux·macOS=python3;node 均有
 ///
-/// 两项合计约 25 token，消除一整类系统性错误。
-fn env_info_line() -> String {
+/// 跨设备:cfg! 分支,平台各自正确姿势。补充探测见 detect_environment 工具(失败自愈)。
+fn env_profile_line() -> String {
     let today = chrono::Local::now().format("%Y-%m-%d");
-    let os = if cfg!(target_os = "windows") {
-        "Windows"
+    let (os, shell, interp) = if cfg!(target_os = "windows") {
+        ("Windows", "PowerShell", "python(无 python3)、node")
     } else if cfg!(target_os = "macos") {
-        "macOS"
+        ("macOS", "bash/zsh", "python3、node")
     } else if cfg!(target_os = "linux") {
-        "Linux"
+        ("Linux", "bash", "python3、node")
     } else {
-        "Unknown"
+        ("Unknown", "sh", "python3、node")
     };
-    format!("当前日期: {today} | 运行环境: {os}\n\n")
+    format!(
+        "当前日期: {today} | 运行环境: {os} | shell: {shell}\n\
+         执行姿势: 复杂脚本(多行/含引号/$变量)写成 .ps1 或 .py 文件,用 `powershell -File x.ps1` 或 `python x.py` 执行,避免命令行 -c 内联(引号转义易出错)。可用解释器: {interp}。\n\n"
+    )
 }
 
 /// 按语言返回系统提示词的 (固定前缀, 项目上下文标题, 任务上下文标题)
@@ -113,9 +120,34 @@ fn system_prompt_parts(lang: &str) -> (&'static str, &'static str, &'static str)
 /// 非 build_system_prompt 职责 —— 两套并行:全局清单(全貌)+ augmentation(用户本次引用)。
 ///
 /// 注入克制:仅各取最近 20 条,防 context 膨胀。
+///
+/// 保留旧签名供 agentic/mod.rs(无 mention 场景)等零改动调用,内部委托给
+/// [`build_system_prompt_with_excluded`] 传两个空排除列表(无去重)。
 pub(crate) async fn build_system_prompt(state: &AppState, lang: &str) -> String {
+    build_system_prompt_with_excluded(state, lang, &[], &[]).await
+}
+
+/// 构建系统提示词(可去重版本)——主路径 chat.rs send / force_send 调用。
+///
+/// 与 [`build_system_prompt`] 的差异(机制而非说教):
+/// 1. **去重**:被 @ 的 project/task 已由 augmentation 层精准投影(含 path/正文),清单中
+///    再现会造成同一实体两次入 prompt(实测 build f64dee94 会话 list_projects 8 次 /
+///    list_tasks 20 次)。此处把 `excluded_project_ids`/`excluded_task_ids` 命中的条目
+///    从全局清单循环中跳过,被@实体只保留 augmentation 一次。
+/// 2. **注明语**:清单末尾按语言追加一行,告知 LLM 「项目已全部列出无需再调 list_projects」/
+///    「任务仅最近 20 条,全量查询请用 list_tasks」,从机制层降低工具与清单重复调用
+///    (而非在行为准则里反复说教)。
+///
+/// - 空排除列表(无 mention 的调用)与 [`build_system_prompt`] 行为完全等价(仅多一行注明语)。
+/// - 注入克制策略不变:仍各 take(20)。
+pub(crate) async fn build_system_prompt_with_excluded(
+    state: &AppState,
+    lang: &str,
+    excluded_project_ids: &[String],
+    excluded_task_ids: &[String],
+) -> String {
     let (prefix, proj_label, task_label) = system_prompt_parts(lang);
-    let mut prompt = env_info_line();
+    let mut prompt = env_profile_line();
     prompt.push_str(prefix);
 
     // 附加当前数据上下文
@@ -123,9 +155,15 @@ pub(crate) async fn build_system_prompt(state: &AppState, lang: &str) -> String
         if !projects.is_empty() {
             prompt.push_str(proj_label);
             // system prompt 前缀克制：仅最近 20 个项目，防 context 膨胀
+            // 去重:被 @ 的项目跳过(已有 augmentation 精准投影,清单再现致同一实体两次入 prompt)
             for p in projects.iter().take(20) {
+                if excluded_project_ids.iter().any(|id| id == &p.id) {
+                    continue;
+                }
                 prompt.push_str(&format!("- {} ({}): {}\n", p.name, p.status, p.description));
             }
+            // 机制层注明语(中/英):项目已全部列出,降 list_projects 重复调用
+            prompt.push_str(&projects_listed_note(lang, 20));
         }
     }
     // 任务全貌清单(供 LLM 知道存在哪些任务;被@任务的精准投影走 augmentation 层)
@@ -133,15 +171,48 @@ pub(crate) async fn build_system_prompt(state: &AppState, lang: &str) -> String
     if let Ok(tasks) = state.tasks.list_active().await {
         if !tasks.is_empty() {
             prompt.push_str(task_label);
+            // 去重:被 @ 的任务跳过(同项目去重机理)
             for tk in tasks.iter().take(20) {
+                if excluded_task_ids.iter().any(|id| id == &tk.id) {
+                    continue;
+                }
                 prompt.push_str(&format!("- {} ({}): {}\n", tk.title, tk.status, tk.description));
             }
+            // 机制层注明语(中/英):仅最近 20 条,全量/按项目查询走 list_tasks
+            prompt.push_str(&tasks_listed_note(lang));
         }
     }
 
     prompt
 }
 
+/// 项目清单尾部注明语(中/英)。
+///
+/// 机制层降重复:直接告知「已全部列出」,LLM 知道再调 list_projects 是冗余。
+/// `shown` 取实际注入条数上限 20(避免传运态 list_active 长度,只描述清单本身)。
+fn projects_listed_note(lang: &str, shown: usize) -> String {
+    match lang {
+        "en" => format!(
+            "(Listed {} active projects above; the active set is shown, no need to call list_projects again.)\n",
+            shown
+        ),
+        _ => format!(
+            "(以上为活跃项目清单,无需重复调用 list_projects)\n"
+        ),
+    }
+}
+
+/// 任务清单尾部注明语(中/英)。
+///
+/// 机制层降重复:明确「仅最近 20 条 + 全量查询走 list_tasks」,避免 LLM 误以为清单即全量
+/// 而反复调 list_tasks 校验(实测单会话 20 次)。
+fn tasks_listed_note(lang: &str) -> String {
+    match lang {
+        "en" => "(Only the 20 most recent tasks are shown. For the full list or filtered by project, use the list_tasks tool.)\n".to_string(),
+        _ => "(仅显示最近 20 条任务,全量或按项目查询请用 list_tasks 工具)\n".to_string(),
+    }
+}
+
 /// 上下文压缩 system prompt 模板（F-15 §4.2，纯函数无 IO）。
 ///
 /// 引导 LLM 把对话压缩为四段式结构化摘要（意图/决策/文件/约束），最大化保留
@@ -284,4 +355,20 @@ mod tests {
         assert!(en.contains("topic words"));
         assert!(en.contains("breaks the context"));
     }
+
+    // 项目/任务清单注明语(中/英)存在
+    #[test]
+    fn listed_notes_present_zh_en() {
+        let zh_proj = projects_listed_note("zh-CN", 20);
+        assert!(zh_proj.contains("无需重复调用 list_projects"));
+        let en_proj = projects_listed_note("en", 20);
+        assert!(en_proj.contains("no need to call list_projects"));
+
+        let zh_task = tasks_listed_note("zh-CN");
+        assert!(zh_task.contains("仅显示最近 20 条任务"));
+        assert!(zh_task.contains("list_tasks"));
+        let en_task = tasks_listed_note("en");
+        assert!(en_task.contains("20 most recent tasks"));
+        assert!(en_task.contains("list_tasks"));
+    }
 }

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

@@ -1835,6 +1835,140 @@ fn register_file_tools(
             }))
         })),
     );
+
+    // ── 环境感知 (Low risk, L1 agent 元能力层) ──
+    // detect_environment:AI 主动探测运行环境的「眼睛」(设计 §2.1 补救式感知)。
+    // 返回 JSON:{ os, default_shell, python_path, node_path }。
+    //
+    // 为什么需要:prompt.rs env_profile_line 只注入静态 OS+shell+解释器提示(编译期 cfg!),
+    // AI 不知 python 真实路径/版本/node 是否安装/GBK 还是 UTF-8,撞墙后才补救。
+    // 本工具让 AI 在「要做某环境相关操作前」(如跑 python 脚本/装依赖)主动探测,
+    // 而非靠 prompt 教(机制优先 prompt 说教,见设计核心原则)。
+    //
+    // 接入断路器(设计 §2.2):后续断路器触发(run_command 连撞 N 次引号/路径错)后,
+    // 系统提示会引导 AI 调本工具刷新环境认知(本工具不主动调断路器,仅提供能力)。
+    //
+    // 安全:Low risk 纯只读探测。which/where 只读 PATH 不写不删,无副作用。
+    // 不走白名单(探测系统 PATH,非 workspace 文件),不审批(只读)。
+    //
+    // 开关(env_probe_enabled,设计 §2.1 §8):DEVFLOW_ENV_PROBE_ENABLED=off 关闭探测,
+    // 返回静态 profile(编译期 OS + 默认 shell,与 env_profile_line 一致),兜底降级旧行为。
+    // 默认 on(空值/未设/on/1/true 均视为开)。开关 off 不致工具调用失败,只退化能力。
+    //
+    // 兜底(设计 §2.1):探测失败(超时/python 未装/which 不可用)→ 该字段 null + errors 收集原因,
+    // 不阻断工具返回。LLM 据此知「该能力不可用」,回退静态 profile 语义。
+    registry.register(
+        "detect_environment",
+        "探测当前运行环境,返回 { os, default_shell, python_path, node_path, errors }。os=Windows/macOS/Linux;default_shell=Windows 默认 PowerShell / Unix 默认 bash(对齐 df-execute ShellType::default);python_path/node_path 为运行时探测到的可执行路径(which/where),探测失败或未安装为 null。只读无副作用。建议在执行 python/node 命令或环境相关操作前主动调用,避免引用不存在的解释器或用错 shell。LLM 可主动调用;命令执行断路器触发后系统提示会引导调用(失败自愈补救式感知)",
+        df_ai::ai_tools::object_schema(vec![]),
+        RiskLevel::Low,
+        Box::new(|_args: serde_json::Value| Box::pin(async move {
+            // 静态 OS:cfg! 编译期分支,跨设备各自正确(Win/macOS/Linux/Unknown)
+            let os = if cfg!(target_os = "windows") {
+                "Windows"
+            } else if cfg!(target_os = "macos") {
+                "macOS"
+            } else if cfg!(target_os = "linux") {
+                "Linux"
+            } else {
+                "Unknown"
+            };
+            // 默认 shell:对齐 df_execute::shell::ShellType::default(Windows=PowerShell, Unix=Sh=bash)。
+            // 不直接 import ShellType(避免 dep 漂移),用同样的 cfg! 逻辑保持单一语义源。
+            // 注:Unix 上 ShellType::Sh 实际执行 sh,AI 视角写 bash 兼容脚本即可(POSIX 子集)。
+            let default_shell = if cfg!(target_os = "windows") {
+                "PowerShell"
+            } else {
+                "bash"
+            };
+
+            // 开关 env_probe_enabled(设计 §8):off 则只返静态 profile(无 python_path/node_path 探测),
+            // 兜底降级旧行为(等于 env_profile_line 静态注入的运行时版本)。默认 on。
+            let probe_enabled = match std::env::var("DEVFLOW_ENV_PROBE_ENABLED") {
+                Ok(v) => !matches!(v.trim().to_lowercase().as_str(), "off" | "0" | "false" | "no"),
+                Err(_) => true, // 未设 = 默认开
+            };
+
+            let mut errors: Vec<String> = Vec::new();
+            let (python_path, node_path) = if probe_enabled {
+                // Windows 用 where,Unix 用 which。探测命令在 PATH 中不可用或解释器未装时返 null + 记错。
+                // probe_executable 内置 8s 超时兜底(防 which 卡死拖垮会话),失败记 error 不阻断。
+                // Unix python:python3 优先(对齐 env_profile_line 语义),无则试 python(记错降级,不噪音)。
+                let py = if cfg!(target_os = "windows") {
+                    probe_executable("python", "where python", &mut errors).await
+                } else {
+                    let p3 = probe_executable("python3", "which python3", &mut errors).await;
+                    if p3.is_some() {
+                        p3
+                    } else {
+                        // python3 探测失败的 errors 已记入主 errors;python 再探,失败记错(两解释器都无才全 null)。
+                        probe_executable("python", "which python", &mut errors).await
+                    }
+                };
+                let node = if cfg!(target_os = "windows") {
+                    probe_executable("node", "where node", &mut errors).await
+                } else {
+                    probe_executable("node", "which node", &mut errors).await
+                };
+                (py, node)
+            } else {
+                // 开关关:探测降级,两字段 null(等于不探测)。errors 不记(非失败,是开关显式关闭)。
+                (None, None)
+            };
+
+            Ok(serde_json::json!({
+                "os": os,
+                "default_shell": default_shell,
+                "python_path": python_path,
+                "node_path": node_path,
+                "probe_enabled": probe_enabled,
+                "errors": errors,
+            }))
+        })),
+    );
+}
+
+/// 探测可执行文件路径(which/where 风格),8s 超时兜底。
+///
+/// 执行 `cmd`(如 "which python3" / "where node")取 stdout 首行(trim 后)作为路径。
+/// 失败(命令不存在/解释器未装/超时/退出码非 0)记 `error` 到 `errors` 并返回 None。
+///
+/// 超时兜底(对齐 workflow-cargo-timeout-wrap 记忆):防 which/where 偶发卡死拖垮会话。
+/// 用 df_execute::shell::execute(对齐 run_command 同源,Windows 无控制台窗口 + kill_on_drop),
+/// shell_type 用 default(Windows=PowerShell / Unix=sh)。
+async fn probe_executable(label: &str, cmd: &str, errors: &mut Vec<String>) -> Option<String> {
+    let request = ShellRequest {
+        command: cmd.to_string(),
+        working_dir: None,
+        env: HashMap::new(),
+        // 8s 超时:which/where 通常 <1s,8s 足够且不拖垮会话。超时视为不可用(记错返 None)。
+        timeout_secs: Some(8),
+        shell_type: Default::default(),
+    };
+    match execute(request).await {
+        Ok(result) => {
+            // 退出码非 0:which/where 未找到目标(如 python 未装)→ 正常情况,记错返 None
+            if !matches!(result.exit_code, Some(0)) {
+                errors.push(format!(
+                    "{}: 探测命令退出码 {:?}({})",
+                    label, result.exit_code, cmd
+                ));
+                return None;
+            }
+            let first_line = result.stdout.lines().next().map(|s| s.trim().to_string());
+            match first_line {
+                Some(p) if !p.is_empty() => Some(p),
+                _ => {
+                    errors.push(format!("{}: 探测输出为空({})", label, cmd));
+                    None
+                }
+            }
+        }
+        Err(e) => {
+            errors.push(format!("{}: 探测失败({}): {}", label, cmd, e));
+            None
+        }
+    }
 }
 
 /// 递归列出目录内容(最多 max_depth 层,最多 max_entries 条)
@@ -2262,7 +2396,7 @@ mod tests {
     // 任一层漏移 register 调用,此测试立即红。工具名集合也断言,防 rename 致 LLM tool 突变。
     // ============================================================
 
-    /// build_ai_tool_registry 应注册恰好 30 个工具(18 data + 11 file + 1 http),且工具名集合稳定。
+    /// build_ai_tool_registry 应注册恰好 31 个工具(18 data + 12 file + 1 http),且工具名集合稳定。
     ///
     /// 用 in-memory SQLite(Database::open_in_memory 自跑迁移),构造零外部依赖的 db,
     //  不实际执行任何 handler——仅断言注册阶段的定义完整性,故无需真实数据。
@@ -2275,17 +2409,18 @@ mod tests {
         let allowed_dirs = Arc::new(RwLock::new(AllowedDirs::default_with_root()));
         let registry = build_ai_tool_registry(&db, &allowed_dirs);
 
-        // 总量基线:30(18 data + 11 file + 1 http)。拆分前后必须一致。
+        // 总量基线:31(18 data + 12 file + 1 http)。拆分前后必须一致。
         // F-260621: file 层 10→11(新增 grep 跨文件内容搜索工具)。
+        // L1 环境感知(设计 §2.1): file 层 11→12(新增 detect_environment 环境探测工具)。
         assert_eq!(
             registry.len(),
-            30,
-            "工具总数应为 30(18 data + 11 file + 1 http),实际 {}", registry.len()
+            31,
+            "工具总数应为 31(18 data + 12 file + 1 http),实际 {}", registry.len()
         );
 
         // 工具名集合基线:防 rename / 漏注册 / 误删除。
         // data 层 18 个(持 db):CRUD/状态机/工作流
-        // file 层 11 个(不持 db):命令/读/列/写/改/元/追加/删/移/搜/grep
+        // file 层 12 个(不持 db):命令/读/列/写/改/元/追加/删/移/搜/grep/环境探测
         // http 层 1 个(不持 db):http_request
         let mut expected: Vec<&str> = vec![
             // ── data 层 (18) ──
@@ -2295,12 +2430,13 @@ mod tests {
             "run_workflow", "delete_task", "create_idea",
             "delete_project", "restore_project", "purge_project",
             "list_trash", "get_project_count", "get_task_count",
-            // ── file 层 (11) ──（run_command 注册顺序已移至末位降低 LLM 偏好,
-            //   集合断言经 sort 后与顺序无关,仅守护工具名不漂移。grep 新增 F-260621）
+            // ── file 层 (12) ──（run_command 注册顺序已移至末位降低 LLM 偏好,
+            //   集合断言经 sort 后与顺序无关,仅守护工具名不漂移。grep 新增 F-260621;
+            //   detect_environment 新增 L1 环境感知 设计 §2.1）
             "read_file", "list_directory", "write_file",
             "patch_file", "file_info", "append_file",
             "delete_file", "rename_file", "search_files", "run_command",
-            "grep",
+            "grep", "detect_environment",
             // ── http 层 (1) ──
             "http_request",
         ];