DevFlow/docs/02-架构设计/专项设计/Agent架构说明-2026-06-14.md

Agent 架构与能力边界（系统现状记录） — 2026-06-14

性质: 系统现状盘点 / 能力边界（查实的事实，非构想） 关联: 任务推进设计（AI 执行层依据本文档能力边界） 关联: 三层模型-流程模板与人设体系（人设层是本架构的下一阶段演进方向） 用途: 作为「AI 执行层」「AI 自审」等设计的真实能力依据，避免在超出系统现状的能力上做设计

---

1. Agent 引擎：单链 ReAct

核心：run_agentic_loop（src-tauri/src/commands/ai/agentic.rs）

完整的 ReAct（Reason+Act）循环：LLM 流式接收 → 工具调用 → 执行工具 → 结果回传 LLM → 循环。

┌─ for iteration in 0..MAX_AGENT_ITERATIONS(10) ─────────────┐
│  1. 用户停止? → 收尾退出                                     │
│  2. 构建请求消息（超预算裁剪旧消息，保护工具三元组+最近6条）    │
│  3. stream_llm（流式，含 idle timeout/断连检测/停止信号）     │
│  4. 有 tool_calls?                                           │
│     ├ 无 → 最终文本，break（正常结束）                       │
│     └ 有 → process_tool_calls（Low 自动 / Medium+High 待审批）│
│           ├ 有 pending 审批 → 暂停循环（generating 保持 true）│
│           └ 全自动完成 → 继续下一轮                          │
└─ 达 10 轮 → 正常结束 ────────────────────────────────────────┘

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

配套设施：

• TokenEstimator：超预算裁剪历史（保护工具调用三元组 + 最近 6 条）
• LlmConcurrency：全局 + 单对话双层并发限流（仅覆盖 stream_llm，工具执行本地操作不限流）
• AiAgentRound 事件：每轮通知前端新建 assistant 消息
• 知识提炼（maybe_spawn_extraction）、标题生成（ensure_conversation_title）后台化

服务场景

当前服务于交互式 AI 对话（侧边栏 aichat 式），不是任务执行。会话级状态在 AiSession（generating/messages/pending_approvals/stop_flag）。

协调器：空壳

crates/df-ai/src/coordinator.rs 的 AgentCoordinator 是 B 路线占位空壳，注释明示：

⚠ B 路线占位：当前单链 ReAct 够用，多 Agent 协作待 B 路线立项。有意保留空壳，勿删。

run() 返回 "TODO: Agent 协作结果"。多 Agent 协作、Agent 间消息传递、任务分配——全部未实现。当前是单链 ReAct。

---

2. 工具系统

注册：编译期硬编码

build_ai_tool_registry（src-tauri/src/commands/ai/tool_registry.rs:77）启动时构建注册表。所有工具 Rust 写死，无运行时动态注册。

工具三要素同源

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

风险分级 + 审批

RiskLevel	执行	机制
Low	自动执行	process_tool_calls 直接跑
Medium / High	待人工审批	进 ai_pending_tool_calls（持久化到 ai_tool_executions 表 status='pending'），启动可恢复；ai_approve/ai_reject 决定

审批机制现成——这是「人工核对」可直接复用的基础设施。

路径安全

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

审计

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

---

3. 内置工具清单（固定工具集）

风险	工具	说明
Low	list_projects / list_tasks / list_ideas	列表查询（truncate 50 防 context 膨胀，排软删）
Low	read_file / list_directory	文件读取（offset/limit 分页）
Medium	create_project / create_task	创建（create_project 可选 path/stack 一步绑定）
Medium	update_project	改字段（复用 CRUD 白名单校验）
Medium	write_file	写文件（自动建父目录）
Medium	bind_directory	项目绑定代码目录 + 探测技术栈
—	knowledge 相关（search 等）	对齐 MCP 语义

完整清单见 tool_registry.rs（约 12+ 个 register）。

---

4. 能力边界（查实的四个「无」）

能力	现状	证据
配置/调用外部工具	❌ 无	无 MCP 客户端（knowledge.rs 注释提「MCP 语义」只是概念对齐，非实现）；无 HTTP 工具；无动态注册；工具全编译期硬编码
自造/迭代工具	❌ 无	工具定义（schema+risk+handler）是 Rust 代码，AI 运行时不能新增/修改；AI 能 write_file 写代码但不会变成可调用工具（要重编译）
执行类工具（run shell/script）	❌ 无	grep exec/shell/run_command 零命中；AI 能写代码没有工具运行它；agentic coding「写→跑→改」闭环做不到
agent ↔ workflow 打通	❌ 未打通	run_workflow AI 工具是空壳（返回「请通过工作流页面运行」）；ScriptNode 能跑 shell 但那是工作流节点不是 agent 工具，两套执行能力割裂

---

5. 关键缺口

1. 执行能力：AI 能写不能跑。要做真 agentic coding 必须补执行类工具（run_command/run_script，或把 ScriptNode 能力暴露给 agent）。
2. 外部工具接入：无 MCP 客户端，无法消费外部 MCP server 工具，工具集封闭。
3. 工具自造闭环：AI 不能为特定任务临时造工具、不能迭代改进工具。
4. agent ↔ workflow 割裂：两套执行能力（agent ReAct / workflow DAG）未打通，AI 不能在 agent loop 内触发工作流。
5. 多 Agent 协作：coordinator 空壳，单链 ReAct，无 Agent 间消息/任务分配。

---

6. 对任务推进 AI 执行层的影响

任务推进构想-2026-06-14.md 的 AI 执行层（start 闸门）依赖系统 Agent 能力。本文档查实的边界直接框定其可达范围：

设计点	受能力边界约束的真实情况
AI 执行任务	现状只能用固定工具集（主要 write_file 写代码 + CRUD），不能运行/验证代码。「AI 执行」≠「AI 写码并跑通」，当前只能前者的一半（写）
AI 自审	AiNode 现成（通用 LLM 调用），可配 review prompt 做 code review。但要审得准需 AI 能读 diff（read_file 可）+ 判断（LLM 可），可行
人工核对	ai_pending_tool_calls（Medium+High 审批）现成，可直接复用为 merge 关卡
advance_task 默认 AI 触发	agent loop 现成，AI 执行完成事件可触发推进

结论：AI 执行层要在当前 Agent 能力上落地，真实可达的是「AI 用固定工具干活（写文件/CRUD）+ AI 自审（LLM review）+ 人工审批（现成）」。要做到「AI 写码并运行验证」的真 agentic coding，必须先补执行能力（执行类工具 + agent/workflow 打通），否则 start 闸门的「AI 执行」实质只是「AI 写文件」。

---

7. 演进方向（待定，非承诺）

方向	内容	依赖
执行工具补全	暴露 run_command/run_script 为 agent 工具（沙箱化），或把 run_workflow 空壳做实让 agent 能触发工作流	安全沙箱、风险分级
MCP 外部工具	接 MCP 客户端，消费外部 server 工具，工具集从封闭走向开放	MCP 协议实现、工具配置 UI
工具自造闭环	AI 写脚本 → 注册成工具 → agent 可调用 → 迭代改进	动态工具注册、工具持久化
多 Agent 协作（B 路线）	coordinator 实化，Agent 间消息/任务分配	立项

这些是补齐「真正 AI 执行」的方向，是否纳入、何时纳入，取决于任务推进 AI 执行层的目标定位（保守=AI 写文件为主 / 激进=补执行能力做真 agentic coding）。

---

附：关键文件

文件	职责
src-tauri/src/commands/ai/agentic.rs	ReAct 循环（run_agentic_loop / try_continue_agent_loop）
src-tauri/src/commands/ai/tool_registry.rs	工具注册（build_ai_tool_registry）+ 路径校验
src-tauri/src/commands/ai/audit.rs	工具执行审计（process_tool_calls / audit_finalize）
src-tauri/src/commands/ai/commands.rs	审批 IPC（ai_approve/ai_reject）+ pending 恢复
crates/df-ai/src/coordinator.rs	协调器空壳（B 路线占位）
crates/df-ai/src/context.rs	TokenEstimator（上下文裁剪）
crates/df-ai/src/ai_tools.rs	AiToolRegistry + RiskLevel + schema
crates/df-nodes/src/ai_node.rs	AiNode（工作流用的单次 LLM 调用节点，非 agent loop）