lxy/DevFlow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
583058acd68889761ad0cec635a41f03a814b111
DevFlow/docs/02-架构设计/专项设计/aichat体验与agent能力系统化重构-2026-06-21.md
绝尘 d2cada97cd 重构: 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 去重被@实体 + 清单注明语
2026-06-22 00:04:14 +08:00

9.2 KiB
Raw Blame History

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 是根,先立见效。

Reference in New Issue View Git Blame Copy Permalink