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

> 性质: 系统现状盘点 / 能力边界（查实的事实，非构想）
> 关联: [任务推进设计](../构想审查/任务推进构想-2026-06-14.md)（AI 执行层依据本文档能力边界）
> 关联: [三层模型-流程模板与人设体系](../专项设计/三层模型-流程模板与人设体系-2026-06-28.md)（人设层是本架构的下一阶段演进方向）
> 关联: [AI-Native方向与路线图](../构想审查/AI-Native方向与路线图-2026-06-29.md)（AI Native 优先级矩阵与推进路线图）
> 用途: 作为「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](任务推进构想-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） |