插件

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

三件套

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

plugin.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" 的插件在智能搜索关闭时完全不可见，这是「开关即存在性」，不是「禁用但不卸载」。