DevFlow/docs/02-架构设计/专项设计/aichat体验与agent能力系统化重构-2026-06-21.md

# aichat 体验与 agent 能力系统化重构

> 2026-06-21 | 不破不立 · 长久治本 · 机制优先说教

## 0. 背景:为什么是系统化重构

7-agent UX 诊断 + kms 会话(8f607aa4,53 轮 0 产出)实证:**用户难受不是几个 bug,是失控感 + 黑箱感叠加**。诊断出 5 个高痛,但均匀修 5 痛 = 补丁堆砌([[no-patch-groundwork]] 元原则禁止)。

反思收敛:**DevFlow 给了 AI 一双手(工具),没给一双眼(环境感知)和一个刹车(止损求助)**。根是 **agent 元能力(感知+决策+求助)整体缺失**,表是 UX(降噪/控制/反馈/密度)。

**系统性解法**:立三层架构,L2/L3 已有设计待整合落地,L1 新立。5 痛作每层第一个消费场景驱动实现。每个 fix 是架构一块砖(可累积/可演进/可观测),非独立补丁。

## 1. 三层架构

| 层 | 职责 | 机制(代码强制,非 prompt 说教) | 现状 |
|---|---|---|---|
| **L1 agent 元能力层** | AI 看得见路、刹得住车、会求助 | 环境探测工具 + 断路器 + 求助协议 | **新立**(四空壳之一,[[aichat-arch-extensibility]]) |
| **L2 统一状态机** | 状态收敛,前后端同一真相 | generating/stopping/error enum 视图 + guard 写收敛 | 已设计([[devflow-generating-statemachine]] `generating状态机加固-2026-06-15.md`),待落地 |
| **L3 事件总线可观测性** | 进度/卡点/失败/求助统一可见 | pub-sub + request-reply + 流式统一总线 | 已设计([[global-event-bus-design]] `全局事件数据总线-2026-06-21.md`),推进 C |

**核心原则**([[ai-improvement-principles]]):**机制优先 prompt 说教**。断路器不靠"教 AI 别重试"(LLM 不听),靠代码强制熔断;环境感知不靠"prompt 写死 Windows 规则"(过时),靠动态探测工具。

## 2. L1 agent 元能力层(新立 · 核心)

L1 是根。三个组件:

### 2.1 环境感知(给 AI 一双眼)

**问题**:`prompt.rs:44 env_info_line()` 只注入"日期+OS"(25 token),AI 不知道 cmd 吃 `$`、PowerShell 才靠谱、python 路径在哪、编码 GBK/UTF-8。kms seq26-52 引号地狱根因。

**机制**(预防式 + 补救式 + 自省式三层):

- **预防式 — 启动详细环境注入**:扩 `env_info_line` 为 `env_profile`,启动注入:OS + 默认 shell 类型(Win→PowerShell / Linux·Mac→bash)+ python/node 路径 + 终端编码 + **平台陷阱提示**(Win: cmd 吃 `$/引号,复杂脚本写文件用 `powershell -File` / `python file`;Linux·Mac: bash 引号规则)。约 +120 token,消除引号地狱类系统性错误。
- **补救式 — `detect_environment` 工具**:AI 可主动调,返回详细环境(shell/编码/可用命令/Python 版本)。失败 N 次后**自动触发**(见 2.2 断路器),把结果注入 context。
- **自省式 — 环境画像缓存**:探测结果缓存(会话级 `env_profile`),避免重复探测;关键环境变化(如 shell 切换)刷新。

**跨设备**:env_profile 动态 `cfg!` 分支 + 运行时探测,平台无关。Win/Linux/Mac 各自正确姿势。

**兜底**:探测失败回退静态 env_profile(编译期 OS + 默认 shell),不阻断。

**开关**:`env_probe_enabled`(默认 on),off 则只静态注入。

### 2.2 断路器(给 AI 一个刹车)

**问题**:agentic loop 仅 `max_iterations=10` 硬截断,无智能止损。kms write_file 连撞 8 次、run_command 引号失败 20+ 次才到上限。路径防护错误 AI 视作普通错误反复换法。

**机制**(代码强制熔断,非说教):

- **同 tool_call 连续失败 ≥2 次**:熔断,强制停该工具,发求助。
- **同路径连撞 ≥2 次**:熔断(路径错误不可绕过,AI 换工具也撞)。
- **同错误类型连续 ≥3 次**:熔断(如引号错误反复)。
- **熔断动作**:停 loop → 发 `AiHelpRequired` 事件(2.3)→ 前端求助卡(而非 max_iterations 默默截断)。
- **错误分类**:路径防护错误标 `fatal_unbypassable`(AI 可操作提示:"路径 X 不在授权区,此错误不可换工具绕过,请改路径或 bind_directory")。

**开关**:`circuit_breaker_enabled`(默认 on)+ 阈值可调(`max_consecutive_fail=2`)。

**兜底**:断路器误判 → 用户在求助卡选"继续重试"可覆盖熔断(人工 > 机制)。

### 2.3 求助协议(让 AI 会求助)

**问题**:AI 卡死只靠 max_iterations 截断或用户手动打断,无主动求助。prompt 教"失败就问用户"是说教,不可靠。

**机制**(结构化求助通道):

- **`AiHelpRequired` 事件**:agent 断路器触发 / 自省(识别"我反复失败")时发,结构化字段:`reason`(死循环/环境未知/权限不足)+ `context`(已试 N 次/卡在哪)+ `options`([换策略/授权路径/人工接管])。
- **前端求助卡**:显式 UI(非隐藏),用户选 option → 注入 context → loop 续跑或停。
- **与审批区分**:审批=工具执行前确认;求助=AI 主动"我搞不定"。两套机制不混。

**开关**:`help_required_enabled`(默认 on)。

## 3. L2 统一状态机(整合现有设计)

落地 `generating状态机加固-2026-06-15.md`:guard 写收敛 + enum 视图读收敛。

- **单一真相**:`ConvState` enum(`Idle/Generating/Stopping/Error/Compressed`),消 streaming/generating/isStopping 多源割裂。
- **前端读 enum 视图**:停止按钮三态(可停/停中/停失败可重试)是 `Stopping` 状态自然产物,非加变量。
- **MaxRoundsCard 判断改 enum**:达轮次时 `Generating` 态可靠弹"继续/停止"卡(诊断痛②:看门狗误清 streaming 致卡片不弹的根解)。

## 4. L3 事件总线可观测性(整合现有设计)

落地 `全局事件数据总线-2026-06-21.md`:进度/卡点/失败/求助/心跳统一事件,前端订阅渲染。

- **心跳 UI 化**:复用 `AiHeartbeat`,每 10-15s 显"AI 已思考 Xs"(诊断痛③:130s 盲等)。
- **轮次可视化**:`AiAgentRound` → "轮次 X/Y"(Y=max_iterations 或 ∞)。
- **工具分级**:30s 前 10s 预警(橙),30s 后红 + toast。
- **审批倒计时**:剩余 X 分钟,临 1 分钟红。
- **求助消费**:`AiHelpRequired`(L1)→ 求助卡(L3 渲染)。

## 5. 5 痛 → 架构组件映射(消费场景驱动)

| 诊断痛 | 眼前补丁(弃) | 长久架构组件 | 阶段 |
|---|---|---|---|
| ① AI 死循环零交付 | prompt 教止损 + 折叠 | **L1 断路器 + 环境探测 + 求助协议** | 1 |
| ② 停止割裂/卡片不弹 | 加 isStopping | **L2 状态机**(三态是其产物) | 2 |
| ③ 无进度反馈 | 加心跳动画 | **L3 事件总线**(心跳是事件之一) | 3 |
| ④ 审批疲劳 | 分组按钮 | **L1 会话信任目录机制** + L3 批量事件 | 1/3 |
| ⑤ 基础硌人 | 各自修 | L2 状态驱动渲染(统一,非散修) | 3 |

## 6. 实施顺序(分阶段,每阶段独立可回退)

**阶段1 · 立 L1 根**(治痛①,最痛):
- 环境感知:`env_profile` 注入 + `detect_environment` 工具 + 缓存
- 断路器:agentic loop 熔断(同 tool_call/路径/错误类型)
- 求助协议:`AiHelpRequired` 事件 + 前端求助卡
- 会话信任目录(L1):首次授权后同会话自动放行(治痛④一部分)

**阶段2 · 立 L2 状态机**(治痛②):
- 落地 `ConvState` enum + guard 收敛
- 停止三态 + MaxRoundsCard 改 enum 判断

**阶段3 · 立 L3 事件总线 + 前端消费**(治痛③④⑤):
- 事件总线统一输出(进度/卡点/失败/求助/心跳)
- 前端订阅渲染:心跳/轮次/工具分级/审批倒计时/求助卡
- 降噪:失败折叠 + 同类聚类(x3 点击展开)
- 基础:滚动锁存 / 代码围栏占位 / Shift+Enter hint

每阶段:**独立可回退 + 开关 + 兜底**。阶段1 不依赖 2/3 可先落地见效。

## 7. 跨设备约束(硬约束)

| 组件 | 跨设备要求 |
|---|---|
| L1 env_profile | 动态 `cfg!` + 运行时探测,Win→PowerShell / Linux·Mac→bash,平台陷阱各自注入 |
| L1 断路器/求助 | 纯逻辑,平台无关 |
| L2 状态机 | 纯逻辑,平台无关 |
| L3 事件总线 | 纯逻辑 + 前端,平台无关 |
| 路径处理 | 已 `std::path` + workspace_root 归一化 |

本机跨平台(Win/Linux/Mac)先保证;跨设备同步(手机/多端)是 `df-relay/df-miniapp` 云后端路线([[cross-end-rust-backend]]),另立。

## 8. 兜底 / 开关 / 可回退([[ai-improvement-principles]])

每机制配:
- **开关**:`env_probe_enabled` / `circuit_breaker_enabled`(+阈值)/ `help_required_enabled`,默认 on,可关。
- **兜底**:探测失败→静态 profile;断路器误判→人工覆盖;求助不发→回退 max_iterations。
- **可回退**:每阶段独立 git 可 revert;开关 off 即降级旧行为。

## 9. 关联现有设计(整合不重复)

- L2 → `generating状态机加固-2026-06-15.md`(直接落地)
- L3 → `全局事件数据总线-2026-06-21.md`(直接落地)
- L1 决策 → `条件表达式引擎-2026-06-15.md` + `Agent架构说明-2026-06-14.md`(四空壳 coordinator/planner,元能力是其具体化)
- 痛①实证 → `aichat-技术债审查-2026-06-21.md` + kms 会话 8f607aa4

## 10. 验收

- kms 类场景(白名单外整理):AI 撞 ≤2 次即求助(非 53 轮 0 产出)
- 引号地狱:env_profile 注入后 AI 用对 shell / 写文件执行,不反复 -c 内联
- 停止按钮:三态可靠,打断后状态干净
- 进度:任意时刻用户知 AI 在哪/卡哪/还要多久
- 审批:会话信任目录后同路径不重复弹
- 跨设备:Win/Linux/Mac env_profile 各自正确

---

**下一步**:本设计过目 → 阶段1(L1 根)开整改 workflow 实施。L1 是根,先立见效。