---
title: "工具系统"
description: "理解 Peri 的 direct 与 deferred 工具、条件装配和执行边界"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具系统

Peri 的工具清单不是固定库存。会话入口、配置、已启用插件、MCP 连接状态和中间件装配都会影响当前可用工具，因此这页介绍稳定机制，而不维护一个容易过期的总数。

## 常见能力类别

- **文件与搜索** — 当前核心实现包含 Read、Write、Edit、Glob、Grep 和目录操作。具体 schema、输出截断和权限行为以当前会话暴露的工具定义为准。
- **Shell** — Bash 用于运行构建、测试和其他命令，也可在宿主提供任务管理器时启动后台进程。Shell 命令继承启动 Peri 的用户权限。
- **交互与任务** — 会话可以按条件装配提问、Todo、Goal、Cron、工作流与子代理等能力；并非每个入口都会提供同一集合。
- **网络与扩展** — Web、MCP、插件和其他扩展工具取决于配置及连接状态。远程内容应按不可信输入处理。
- **Skills** — Skills 中间件可提供 skill 搜索与全文加载能力。可见 skill 来自用户、项目、配置目录、插件和内置来源。
- **子代理** — Agent 工具把有边界的子任务交给独立 agent。可选 agent、后台能力和并发边界由当前装配决定。

## Direct 与 deferred

每个工具通过 `BaseTool::is_direct()` 声明可见性：

- **Direct**：schema 直接进入本轮模型的工具列表，模型可以按名称调用。
- **Deferred**：保留在工具注册表中，不直接占用常驻工具列表；Agent 先发现，再通过包装工具执行。

deferred 工具的标准路径是：

```text
SearchExtraTools → 返回匹配工具及 schema → ExecuteExtraTool → 实际目标工具
```

MCP、Cron、Goal 或插件贡献的能力可能走 deferred 路径。包装层会把调用解析到实际目标工具，再按目标工具名称进行权限判断，不能借包装器绕过审批。

> **Note**
>
> 用户通常不需要手写 `SearchExtraTools`。直接描述任务和目标系统，Agent 会在核心工具不足时搜索扩展能力。

## 条件装配

工具可见性至少受以下条件影响：

- TUI、print、ACP stdio 等入口采用的宿主配置；
- `--bare` 是否跳过插件、hooks 等初始化；
- MCP server 是否配置并连接成功；
- 插件是否安装且启用；
- 项目是否提供 skills、agents 或相关配置；
- 运行路径是否提供后台任务、审批 broker 等依赖。

因此，文档示例中的工具名不等于你的会话一定拥有该工具。需要确认时，让 Agent 搜索对应能力，或查看 MCP、Plugin、Tasks 等状态面板。

## 名称、别名与参数

工具可以声明别名，调用解析大小写也会被规范化；例如当前 Bash 声明 `Shell`，Read 声明 `reading`。别名属于实现细节，自动生成工具调用时会由解析器处理。用户提示词应描述意图，不必记忆别名。

参数以当前会话提供的 JSON schema 为准。不要从旧文章复制超时、结果上限或参数默认值：这些值可能由工具内部、外层 dispatcher 或宿主分别控制。

## 权限和安全

- 工具审批依据解析后的实际目标工具，而不是包装器显示名称。
- Bypass 会跳过审批，但不会创建 OS 沙箱。
- 文件和 Shell 工具使用 Peri 进程拥有的权限。
- MCP、Web 和插件结果可能携带恶意指令，不应自动信任外部内容。
- 后台工具返回“已启动”不等于任务已经成功完成；需要继续检查任务状态和最终结果。

详见[权限系统](/peri-cool/docs/features/permissions/)、[MCP](/peri-cool/docs/features/mcp/)和[Skills](/peri-cool/docs/features/skills/)。

Source: https://konghayao.github.io/peri-cool/docs/features/tools/index.mdx