---
title: "插件"
description: "用三件套清单扩展智能体的能力边界。"
---

插件让 Bi 通过外部程序获得新的工具能力。每个插件是一个独立目录，装进 `.bi/plugins/<名字>/`，重启或下一轮对话即被扫描装载。

## 三件套

一个插件目录包含三个文件：

| 文件 | 作用 |
| --- | --- |
| `plugin.json` | 清单：名字、版本、描述、命令模板、schema |
| 可执行程序 | 清单里 `entry` 指向的程序，插件实际执行它 |
| `SKILL.md` | 给智能体看的用法说明（注入到系统提示里的一句话 + 用 `read` 工具自取全文） |

## plugin.json 的字段

```json
{
  "name": "websearch",
  "version": "1.0.0",
  "description": "调用外部搜索接口，返回网页结果",
  "when_to_use": "需要实时信息或搜索网页时",
  "entry": "websearch.exe",
  "command": "{entry} search bing \"{query}\" --limit 5 --format markdown",
  "defaults": { "limit": "5" },
  "toggle": "search",
  "enabled": true,
  "schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "搜索关键词" }
    },
    "required": ["query"]
  }
}
```

- **`name`** — 工具名，会被注册为模型可调用的工具。只能是小写字母开头的 `[a-z][a-z0-9_]{1,30}`，且不能与内建工具名（`read`、`write`、`exec`、`search`、`list`、`spawn_agent`）冲突。
- **`entry`** — 插件目录内的可执行程序文件名。必须是普通文件名，不允许 `../` 或绝对路径。
- **`command`** — 命令模板。`{entry}` 替换为可执行程序的绝对路径（自动加引号），`{dir}` 替换为插件目录，`{key}` 按「参数值 → defaults 缺省值 → 空串」的顺序填充。
- **`schema`** — 工具参数 schema，必须为 `object` 类型。模型按它构造参数。
- **`toggle`** — 受哪个前端开关管辖。`"search"` 表示受输入框的智能搜索开关控制：开关关闭时插件**连工具都不挂载**（模型根本发现不了它）。空字符串 = 常驻。
- **`enabled`** — 缺省（null）= 启用；显式 `false` = 禁用（不装载、不进工具集、不注入提示词）。
- **`retry`** — 执行失败的重试策略：`on_error` / `on_empty` 决定触发条件，`max_attempts` 限制总尝试次数，`param_fallbacks` 提供参数备选值逐项重试。

## 执行与授权

插件通过 `exec` 工具的进程管线执行（复用超时、进程树终止、GBK 编码处理），因此：

- **授权走现有权限系统**：插件工具调用同样会触发权限确认，默认需要你批准。
- **命令不做事先 shell 转义**：信任级别与 `exec` 工具一致（模型本来就能执行任意命令），引号由模板作者负责。

## 健康与故障

插件坏了只跳过并记日志，**绝不影响对话主链路**。装载失败的常见原因：

- 缺 `plugin.json`（目录被忽略，不是插件）
- 清单不合法（`name`/`command`/`schema` 不满足上述约束）
- `entry` 不是普通文件名，或可执行程序不存在

每次启动会重新扫描插件目录，改清单后重启生效。

## 注意

- **plan 模式不挂载插件**。规划阶段只做只读分析，不执行外部程序。
- 插件执行的是你机器上的任意程序，等同手动运行。装第三方插件前请确认其来源与行为。
- `toggle: "search"` 的插件在智能搜索关闭时完全不可见，这是「开关即存在性」，不是「禁用但不卸载」。