> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具系统

> Zeus 工具系统

## Built-in Tools

Zeus 的工具体系分为四个层级，每层服务于不同的能力域：

```mermaid theme={null}
graph TD
    subgraph L1["Layer 1 · DeepAgents Middleware"]
        todo["TodoListMiddleware<br/>write_todos · read_todos"]
        fs["FilesystemMiddleware<br/>ls · read_file · write_file<br/>edit_file · glob · grep"]
        subagent["SubAgentMiddleware<br/>task (子 Agent 委托)"]
    end

    subgraph L2["Layer 2 · Built-in Tools"]
        memory_tools["Memory Tools<br/>memory_add · memory_search"]
        rag_tools["RAG Tools<br/>knowledge_search<br/>knowledge_read_chunks"]
        sandbox_tools["Sandbox Tools<br/>write · read · edit · bash"]
        lsp_tools["LSP Tools<br/>lsp (diagnostics · definition<br/>references · hover · symbols)"]
        coding_tools["Coding Sandbox Tools<br/>coding_write_file · coding_read_file<br/>coding_grep · coding_exec_sh<br/>coding_list_files"]
        web_tools["Web Search Tools<br/>tavily_search · duckduckgo_search"]
        skill_tools["Skill Tools<br/>skill_discover · skill_activate<br/>skill_execute"]
    end

    subgraph L3["Layer 3 · External Tools"]
        mcp_tools["MCP Tools<br/>用户配置的 MCP 服务器"]
        oauth_tools["OAuth Tools<br/>GitHub · Gmail · Google Drive"]
    end

    subgraph L4["Layer 4 · Connector Tools"]
        browser["Browser Operator<br/>浏览器自动化"]
        desktop["Desktop Operator<br/>桌面应用操控"]
        feishu["Feishu Tools<br/>飞书日程/会议"]
    end

    L1 --> L2 --> L3 --> L4
```

### 工具注入与模式过滤

工具在 `_init_context()` 期间按序加载，不同模式下工具集有所不同：

| 工具类别               | Agent 模式 | Ask 模式           | Plan 模式 | Coding 模式 |
| ------------------ | -------- | ---------------- | ------- | --------- |
| Filesystem（读写）     | 全部       | 只读               | 只读      | 禁用        |
| TodoList           | 全部       | 全部               | 全部      | 全部        |
| Memory             | 读写       | 禁用               | 只读      | 读写        |
| RAG                | 全部       | 只读 (search/list) | 全部      | 全部        |
| Sandbox（Python）    | 全部       | 禁用               | 禁用      | 禁用        |
| **LSP（代码智能）**      | 全部       | 禁用               | 禁用      | 禁用        |
| **Coding Sandbox** | 禁用       | 禁用               | 禁用      | **全部**    |
| Web Search         | 全部       | 全部               | 全部      | 全部        |
| MCP/OAuth          | 全部       | 只读               | 只读      | 全部        |
| Browser/Desktop    | 全部       | 禁用               | 禁用      | 禁用        |

<Note>
  编程模式使用专用的沙盒工具集（`coding_*`），操作 E2B 容器中的 Next.js 项目。详见[编程模式](/zh/documentation/core-capabilities/coding)页面。
</Note>

Ask 模式下，写操作工具被替换为占位符 — Agent 知道工具存在但无法调用，会引导用户切换到 Agent 模式（渐进式披露）。

MCP 工具通过 `MultiServerMCPClient` 加载，每个服务器超时 1800s (30min)。

***

## TODO State Flow

### 概述

TodoList 是 DeepAgents 框架的内置中间件工具，通过 `write_todos` 和 `read_todos` 管理任务状态。

### 问题背景

在实时聊天和历史回放中，`todo.md` 的状态需要正确更新。之前存在一个 bug：`sandbox` 工具调用会覆盖 `todo.md` 的内容。

### 数据流

```mermaid theme={null}
flowchart TD
    A["AI Backend - SSE Events"] --> B["stream-processor.ts"]
    B --> C["解析事件"]
    C --> D["trajectoryStore.ts"]
    D --> E["更新状态"]
    E --> F["UI Components - TrajectoryArea"]
```

### 关键修复

`sandbox` 调用返回的文件列表会覆盖之前 `write_todos` 设置的 `todo.md` 内容。解决方案是在状态更新时检查是否应该保留现有的 `todo.md` 内容。如果新返回的文件列表中不包含 `todo.md` 的更新版本，则保留之前由 `write_todos` 设置的内容，避免被覆盖。

***

## MCP Prompts

### 概述

Zeus 支持 MCP (Model Context Protocol) 的 **Prompts** 功能。除了 `@mcp.tools` 之外，可以通过 `@mcp.prompts` 获取 MCP 服务器提供的提示词模板。

### 什么是 MCP Prompts

MCP Prompts 是 MCP 服务器提供的**可重用提示词模板**，类似于预设的对话场景或工作流程。

**Tools vs Prompts**：

| 特性   | Tools      | Prompts |
| ---- | ---------- | ------- |
| 作用   | 执行具体操作     | 提供预设提示词 |
| 示例   | 搜索、文件读取    | 代码审查模板  |
| 调用方式 | Agent 自动调用 | 用户选择使用  |

### 架构实现

系统通过 BaseService 初始化 MCP Prompts，遍历所有配置的 MCP 服务器，获取每个服务器提供的 prompts 列表（包括名称、描述和参数信息）。

API 验证接口 `/validate` 同时返回工具和提示词信息。数据库中的 MCP 服务器记录包含 `tools` 和 `prompts` 两个 JSON 字段。

### 使用方式

#### 方式 1：作为提示词模板资源

用户可以在界面上选择 prompt 并填写参数，系统将根据选择的 prompt 和参数获取对应的提示词内容。

#### 方式 2：动态调用

AI 可以识别需要使用某个 prompt 模板，通过指定服务器名称、prompt 名称和参数来动态获取提示词内容。

***

## Official Tools

### 概述

Zeus AI 提供了一套预配置的官方工具，可以直接在 MCP 标签页中启用和使用。

### 可用工具

#### Tavily Search

**AI 驱动的网络搜索引擎**

* **功能**: 使用 AI 技术搜索互联网
* **使用场景**: 查找实时信息、新闻、研究资料
* **需要 API Key**: 是
* **获取 API Key**: [https://tavily.com](https://tavily.com)
* **默认启用**: 是

#### GitHub

**GitHub 仓库和代码搜索**

* **功能**: 搜索 GitHub 仓库、查看代码、获取用户信息
* **使用场景**: 查找开源项目、研究代码实现
* **需要 API Key**: 是（推荐）
* **获取 API Key**: GitHub Personal Access Token
* **默认启用**: 否

### 使用指南

#### 启用官方工具

1. 打开工具配置面板
2. 选择 "MCP" 标签页
3. 在"官方工具"区域找到您需要的工具
4. 点击工具卡片上的开关启用

#### 配置 API Key

1. 点击工具卡片上的"配置 API Key"按钮
2. 输入 API Key
3. API Key 将安全加密存储
4. 工具将自动启用

### API 端点

* `GET /api/skills/official` - 获取所有可用的官方工具列表
* `GET /api/skills/official/[name]` - 获取单个官方工具详情
* `POST /api/tools/mcp/validate` - 验证 MCP 服务器连接