DevFlow/docs/03-模块文档/AI对话引擎-2026-06-14.md

AI 对话引擎（Agentic Loop）

创建：2026-06-14 | 来源：基于 src-tauri/src/commands/ai/ 实际代码核对编写 关联模块文档：df-ai-AI集成模块（crate 层：Provider / ContextManager / 工具基础设施） 关联架构文档：Agent架构说明-2026-06-14.md（能力边界盘点）

---

一、概述

DevFlow 的 AI 对话不是简单的"发消息→收回复"，而是一个 ReAct 循环（Reason + Act）：LLM 流式回复 → 调用工具 → 执行工具 → 结果回传 LLM → 循环，直到 LLM 不再需要工具（返回纯文本）或达到最大轮次。

核心代码位于 src-tauri/src/commands/ai/，11 个子模块协作：

commands/ai/
├── mod.rs              — 模块入口 + glob 重导出 + AiSession 定义
├── commands.rs         — 17 个 IPC 命令（send/approve/reject/clear/switch…）
├── agentic.rs          — ReAct 循环主体（run_agentic_loop / try_continue_agent_loop）
├── stream_recv.rs      — 流式接收（idle timeout / 断连检测 / 停止信号）
├── conversation.rs     — 持久化 + Token 累加器 + 截断函数
├── audit.rs            — 工具执行审计（process_tool_calls / audit_finalize / build_approval_reason）
├── tool_registry.rs    — 12 个 AI 工具注册 + 路径校验
├── prompt.rs           — system prompt 构建 + provider 获取
├── skills.rs           — 技能联想（SKILL.md frontmatter 解析）
├── title.rs            — 对话标题自动生成
└── knowledge_inject.rs — 知识注入 + 知识提炼

---

二、ReAct 循环详解

核心流程

用户发消息
    │
    ▼
┌─ for iteration in 0..MAX_AGENT_ITERATIONS(10) ──────────────┐
│                                                              │
│  1. 用户停止? → 收尾退出                                      │
│                                                              │
│  2. 构建请求消息                                              │
│     ├─ system prompt（技能 + 知识注入）                        │
│     ├─ 历史消息（超预算时裁剪，保护工具三元组 + 最近 6 条）      │
│     └─ 工具定义（12 个内置工具）                               │
│                                                              │
│  3. LLM 并发限流（全局 3 / 单对话 2 双层 Semaphore）           │
│                                                              │
│  4. stream_llm（流式接收）                                    │
│     ├─ 逐 chunk 推送 AiTextDelta 到前端                       │
│     ├─ 累积 tool_calls（按 index 排序）                       │
│     ├─ idle 120s timeout → 判定断连                          │
│     └─ 流尽未收 finished → 丢弃残缺                          │
│                                                              │
│  5. 有 tool_calls?                                           │
│     ├─ 无 → 最终文本，break（正常结束）                       │
│     └─ 有 → process_tool_calls                               │
│           ├─ Low 风险 → 自动执行                             │
│           └─ Medium/High → 进 pending_approvals，暂停循环     │
│                                                              │
│  6. 全自动完成 → 继续下一轮                                   │
│  有 pending → return（generating 保持 true，等审批恢复）      │
│                                                              │
└─ 达 10 轮 → 正常结束 ────────────────────────────────────────┘
    │
    ▼
收尾（后台 spawn，不阻塞 Completed 事件）
├─ save_conversation（消息 + token 累加落库）
├─ maybe_spawn_extraction（知识提炼）
└─ ensure_conversation_title（标题生成）

退出条件

条件	处理
LLM 只返回文本（无 tool_calls）	正常结束，emit AiCompleted
有工具待审批	暂停循环，generating 保持 true，等 ai_approve → try_continue_agent_loop 恢复
达 MAX_AGENT_ITERATIONS(10)	正常结束
用户请求停止	已生成文本入库后退出，emit AiCompleted
流式错误（idle timeout / 断连）	emit AiError，generating = false，退出

审批恢复

当用户审批通过最后一个 pending 工具后，try_continue_agent_loop 检测到 generating && pending_approvals.is_empty()，spawn 新的 run_agentic_loop 恢复循环。恢复前 emit AiAgentRound 通知前端新建 assistant 消息（审批结果不应追加到发起工具调用的旧消息）。

---

三、三重可靠性保险

保险层	机制	防什么	代码位置
连接层	connect_timeout(30s)，不设总 timeout	连不上无限 hang；总 timeout 会误砍流式长任务（流式可持续数分钟）	openai_compat.rs / anthropic_compat.rs
流式层	每个 chunk 间 idle timeout 120s	连上后中途静默无限 hang	stream_recv.rs
前端层	60s streaming watchdog	后端任何路径漏发收尾事件 → 前端永久 streaming=true 卡死	stores/ai.ts（useAiEvents composable）

审批等待时 watchdog 暂停（不计超时），避免用户思考时间被误判。

断连丢弃残缺

维护 finished_received 标志；流尽未收到 finished 信号 → emit AiError 并丢弃残缺响应，不当完整入库。防脏历史污染对话记录。

停止生成保留文本

AiSession.stop_flag: Arc<AtomicBool> + 多检查点响应（循环顶 / stream 内 / 工具执行前）。停止后保留已生成文本——用户主动停止 ≠ 丢弃成果。

---

四、12 个 AI 工具

工具清单

工具定义在 tool_registry.rs::build_ai_tool_registry，编译期硬编码（无运行时动态注册）。

风险	工具	说明
Low（自动执行）	list_projects	列出项目（排软删，截断 50 条）
Low	list_tasks	列出任务（可按 project_id 筛选）
Low	list_ideas	列出灵感
Low	read_file	读文件（offset/limit 分页，1MB 上限）
Low	list_directory	列目录（噪音剪枝 + 1000 条上限）
Medium（需审批）	create_project	创建项目（可选 path/stack 一步绑定）
Medium	update_project	改字段（复用 CRUD 白名单校验）
Medium	create_task	创建任务
Medium	create_idea	创建灵感
Medium	write_file	写文件（自动建父目录，1MB 上限）
Medium	bind_directory	项目绑定代码目录 + 探测技术栈
High（需审批）	delete_project	删项目（软删进回收站）
High	run_workflow	运行工作流（当前返回提示，未实装）

工具三要素同源

每个工具一次 registry.register 同时定义：name + description + schema + RiskLevel + handler 闭包。handler 即唯一执行路径，schema+risk+实现同源，消除双轨。

路径安全

• validate_path：禁 .. 路径遍历、禁 .ssh/.aws/.gnupg/AppData/ProgramData/Windows/System32 等敏感目录
• resolve_workspace_path：双层校验（词法 starts_with + canonicalize 解析 symlink），锚定 workspace_root

审计

每次工具调用写 ai_tool_executions 表（V9 建），audit_finalize 落盘 executed/rejected + 结果。

已知限制

• 截断 50 条无翻页：三个 list 工具 truncate(50) 硬截断，无 offset/limit，AI 不知道有数据被漏掉（待改进）
• "能写不能跑"：AI 有 write_file 但无 run_command，无法形成"写→跑→改"闭环（待改进）
• 工具集封闭：编译期硬编码，无 MCP 客户端，AI 运行时不能新增/修改工具

---

五、审批门控机制

流程

AI 要执行 create_project（Medium 风险）
    │
    ▼
process_tool_calls → 不自动执行，写入 ai_tool_executions（status=pending）
    │
    ▼
emit AiApprovalRequired → 前端 ToolCard 显示审批按钮
    │
    ├─ 用户点「同意」→ ai_approve → 执行工具 → try_continue_agent_loop 恢复
    └─ 用户点「拒绝」→ ai_reject  → 跳过执行 → 恢复循环

持久化

pending 审批写入 DB（ai_tool_executions 表 status='pending'），重启后 restore_pending_approvals 从 DB 恢复。ai_conversation_switch 用 retain 保其他对话的 pending（不清空全局 HashMap）。

审批卡片信息

build_approval_reason（audit.rs）为 9 种工具拼接 reason 含项目名（resolve_project_label 查项目名，查不到 fallback「(项目已不存在, id=xxx)」）。前端 ToolCard.vue 对 id/project_id 字段特化回显项目名。

与工作流审批的区别

	AI 工具审批	工作流审批
触发	AI 对话中调 Medium/High 工具	DAG 执行到 HumanNode
事件	AiApprovalRequired	HumanApprovalRequest / HumanApprovalResponse
恢复	ai_approve → try_continue_agent_loop	approve_human_approval IPC → EventBus broadcast
通道	独立链路	独立链路（EventBus broadcast）

两条审批链路完全独立，不共享事件类型或通道。

---

六、上下文窗口管理（ContextManager）

实现在 crates/df-ai/src/context.rs，解决长对话 token 暴涨导致 context_length_exceeded 死锁。

分组滑动窗口

消息历史：[旧] U₁ A₁(tool) T(result) A₁' U₂ A₂(tool) T(result) A₂' U₃ A₃ [新]
                    ↑                                        ↑
              可淘汰区                                  保护区（最后6条）

淘汰单位 = 工具调用三元组（原子性同进同出）：
  Assistant(tool_calls) + Tool(result)* + Assistant(紧随文本)

• 保护区：PROTECT_COUNT = 6（≈ 最近 2 个完整用户轮次），永不裁
• 裁剪只影响发送视图：build_for_request 返回裁剪版给 LLM；all_messages_clone 返回全量给持久化
• Token 估算零依赖：chars × 0.35（保守 ±15%），不引入 tiktoken-rs（5MB BPE 数据文件对 Tauri 打包不友好）
• 预算公式：(max_tokens 128k − output_reserve 8192) × safety_ratio 0.85 ≈ 101K tokens

关键方法

方法	用途
push(message)	追加消息并计 token、更新缓存（push 不裁剪，裁剪统一在 build_for_request）
build_for_request(sys_tokens)	返回裁剪后的消息列表 + 是否发生裁剪
all_messages_clone()	返回全量消息（持久化 / 标题生成）
restore_from_messages(msgs)	切换对话时重建缓存
replace_tool_result_content(tool_call_id, new_content)	审批通过/拒绝时回填工具结果（反向 rposition 命中最近一条）

---

七、Token 累加

两协议语义差异

	OpenAI	Anthropic
usage 时机	末 chunk 一次性给全量	message_start（input）+ message_delta（output）
output_tokens	最终值	累计值（非增量），直接覆盖不累加

跨 loop 实例累加

审批暂停→恢复 spawn 全新 run_agentic_loop 实例，新 loop 局部累加器从 0 起。save_conversation 的 upsert 路径 token 读旧值叠加（非覆盖），保证跨 loop 实例的对话总用量正确。

loop 实例 1：prompt=500, completion=200 → save(旧值 None + 500/200)
    │ 审批暂停
    ▼
loop 实例 2：prompt=800, completion=300 → save(旧值 500/200 + 800/300 = 1300/500)

---

八、LLM 并发控制

LlmConcurrency（state.rs）：双层 Semaphore，运行时可调。

Semaphore	默认 permits	限流对象
global	3	全部 LLM 调用（stream_llm / 标题 / 提炼）
per_conv	2	单对话并发

• permit 仅覆盖 stream_llm 调用本身；工具执行（process_tool_calls）是本地操作无 RPM 成本，permit 在 stream 后立即释放
• Semaphore 重建用「软收敛」策略（替换内层 Arc，旧 permit 不受影响）

---

九、知识库集成

知识注入（对话开始时）

build_knowledge_context(state, query, config) -> String：

• auto_inject == false → 返回空（零开销）
• hybrid_search() top-3（LIKE 或 LIKE+向量混合）
• 每条命中调 increment_reuse_count（fire-and-forget）
• 格式化为 markdown，注入 system prompt 头部

知识提炼（对话结束后）

extract_knowledge_from_conversation(db, conv_id, provider_cfg)：

• 后台 spawn，提炼失败仅 warn 不阻断
• 取最后 6 条 user/assistant 消息 → LLM JSON 输出
• parse 失败整批丢弃；成功逐条写 candidate（待人工审核）

maybe_spawn_extraction(...)：agentic loop 两处正常退出路径（max iterations / 无工具调用 break）统一调用。

---

十、切对话不中断路由

Sprint 8 实现：生成中可切换对话不打断。

• 后端给所有 event 加 conversation_id + spawn 前快照 conv_id
• 前端按 id 路由：后台对话事件不污染当前视图
• switchConversation 加 _latestSwitchId 丢弃过期响应

---

十一、Agent 能力边界（四个"无"）

当前系统的硬边界，做设计时不能假设超出这些能力：

能力	现状	影响
配置/调用外部工具	❌ 无 MCP 客户端，工具全编译期硬编码	工具集封闭
自造/迭代工具	❌ AI 运行时不能新增/修改工具	不能为特定任务临时造工具
执行类工具	❌ 无 run_command/run_script	AI 能写代码但不能运行验证（"能写不能跑"）
agent ↔ workflow 打通	❌ run_workflow 工具是空壳	AI 不能在对话中触发工作流

详见 Agent架构说明-2026-06-14.md。

---

相关文档

• df-ai AI 集成模块 — crate 层（Provider / ContextManager / 工具基础设施）
• Agent架构说明 — 能力边界盘点
• df-workflow 工作流引擎 — DAG 引擎
• DAG 引擎详解 — 基于代码的引擎详解
• 经验记录 — 踩坑/约定/技巧