# 工具-智能代理 (Tools-Agents-MCP)

> **菜单入口**：主界面工具栏的「AI 助手」按钮
>
> **更新日期**：2026 年 8 月 30 日
>
> 配套 AI 配置文档：[AI集成](/AI%E9%9B%86%E6%88%90.md)

## 功能用途

GSDJDesktop v4.3 的 **Deep Agent 智能代理执行面板**。它不只是聊天界面，而是一个完整的 Agent 执行引擎：

- 配置和管理 AI 模型、MCP 服务器、Skills、Workflow 连接
- 可视化观测工具调用过程（流式输出）
- 人工介入（Human-in-the-Loop）关键决策
- 与 Deep Agent Harness 协同执行复杂评估任务

## 面板结构

### 1. 配置区

- **AI 模型配置**：Base URL、API Key、模型名称（兼容 OpenAI / Anthropic / Qwen / Ollama 等）
- **MCP 服务器连接**：远程 MCP 工具、本地文件系统工具
- **Skills 启用**：服务端下发的 remote skills 白名单管理
- **Workflow 配置**：服务端 Workers `planner` 路由

### 2. 对话区

- 流式输出（Socket.io）
- 工具调用状态实时展示
- 上下文记忆（MemorySaver checkpointer）

### 3. 观测区

- 工具调用日志
- 错误诊断
- 计划（plan）反馈

## Deep Agent Harness 架构要点

GSDJDesktop 的智能代理不是**裸模型调用**，而是一个带约束的 Agent 执行系统：

### System Prompt 拼装

由 5 部分动态拼装：

1. 基础提示词
2. Workflow 提示词
3. Skills 提示词
4. UI Capability 上下文
5. 项目记忆

### 工具集（Tools）

由以下来源共同组成，并受 **Skills 白名单** 过滤：

- 远程 MCP 工具（如 RAGFlow 检索）
- 本地 workspace 工具（`read_file` / `write_file` / `search_files` 等）
- Document 工具
- UI capability 工具
- 联网搜索工具
- 内置工具：`ask_human`、`report_issue`、`analyze_excel_formula`

> `analyze_excel_formula` 这类工具可以由服务侧 workflow 声明和授权，但**执行实现仍由 Desktop 本地运行时提供**。

### 运行时部件

- `createDeepAgent`：创建带约束的 Agent
- `MemorySaver` checkpointer：多轮对话记忆
- 模型响应兼容 middleware
- PythonRuntimeBackend：Python 运行时（如需）
- **Human-in-the-Loop**：关键步骤暂停等待人工确认

## 服务端协同

执行流程：

```mermaid
sequenceDiagram
    participant UI as Tools-Agents-MCP 面板
    participant Agent as 本地 Deep Agent
    participant Planner as Workers planner (服务端)
    participant MCP as MCP Server (主进程桥接)
    participant Model as AI 模型

    UI->>Agent: 发送任务
    Agent->>Planner: 请求 workflow 路由
    Planner-->>Agent: 返回结构化计划 + 缺失输入判断
    Agent->>Model: 按计划调用模型（流式）
    Model->>MCP: 请求工具调用
    MCP-->>Model: 返回工具结果
    Model-->>Agent: 生成最终答案
    Agent-->>UI: 流式输出
```

### Skills 治理

> 工作流/服务模式下，运行时**只使用服务端下发的远程 Skills**；本地内置与自定义 Skills 不参与工作流执行，便于统一升级与授权治理。

## MCP 连接说明

- 所有 MCP 工具调用统一经主进程桥接，便于集中鉴权、网络治理与审计

## 可用工具集

可通过 MCP 调用的工具详见：

- **文件系统**：`read_file`、`write_file`、`list_directory`、`create_directory`、`delete_item`、`copy_item`、`move_item`、`search_files`、`get_file_info`
- **知识库**：`ragflow_list_datasets`、`ragflow_retrieval`、`ragflow_health_check`、`configure_ragflow`
- **系统**：`get_server_info`、配置管理、连接状态监控

## 后续优化方向

继续沿 **harness engineering** 方向推进，优先考虑：

- 自校验
- 循环检测
- trace 驱动调优
- 计划反馈闭环

**避免**把能力退化成"单条 prompt + 任意工具调用"。

## 相关文档

- [AI 集成（Key 配置详解）](/AI%E9%9B%86%E6%88%90.md)
- [软件开发细节 - Deep Agent Harness](/%E5%BC%80%E5%8F%91/%E8%BD%AF%E4%BB%B6%E5%BC%80%E5%8F%91%E7%BB%86%E8%8A%82.md)