工具

工具（Tool）为 Bub 应用执行具体的外部动作，负责实际执行（如读写文件、运行命令、管理会话等）。

内置工具

安装 Bub 应用后自带以下核心工具：

类别	工具	用途
进程管理	bash	执行 Shell 命令；支持工作目录、超时与后台执行
	bash.output、bash.kill	增量读取后台进程输出，或终止正在运行的进程
文件操作	fs.read、fs.write、fs.edit	分页读取、覆盖写入与文本精准替换
网络抓取	web.fetch	发起 GET 请求抓取网页（优先返回 Markdown）
能力发现	skill	列出工作区发现的技能，或读取指定技能正文
	tool.describe	动态加载延迟工具的完整定义
会话管理	tape.info、tape.search	查看 Token 用量、检索历史会话记录
	tape.handoff、tape.reset	移动上下文起点以压缩会话，或归档并重置上下文
	spill.read	分块读取超出上下文上限的大型工具输出
多任务协作	subagent	启动子 Agent 在独立会话中并行处理任务
代码模式	run_code	在 代码模式 开启时通过 Python 组合多个工具

内置工具的详细参数及默认值见 工具参考。

使用工具

在 Bub 应用中，工具可以通过两种方式调用：

1. 模型自主选用：在会话中正常提问，模型会根据任务意图和工具描述自动选择并调用。
2. 命令行直接调用：在终端中使用逗号前缀直接调用工具（不调用模型、不消耗 Token）：

   bub run ",fs.read path=README.md"

若要约束或规范模型如何使用工具：

• 全局约定：在项目根目录的 AGENTS.md 中编写通用约束；
• 任务流程：将多步骤操作封装为 技能，指引模型按顺序调用对应工具。

开启 代码模式

当需要处理复杂逻辑或批量处理数据时，模型多次往返调用工具会消耗大量上下文。启用 代码模式 后，模型会直接编写 Python 代码（通过 run_code 工具执行）一次性组合多个工具：

,code_mode enable=true

注意：

• 该设置在下一轮对话生效，并持久化保存在当前会话记录中。
• 使用 ,code_mode enable=false 可以关闭并恢复默认模式。
• 关于在代码模式下调用工具的 Python 语法，见run_code 参考。

执行环境与安全

内置的 Shell 命令（bash）、文件读写（fs.*）和代码执行（run_code）等均在本地当前用户权限下直接运行，可能会对系统或数据产生不可逆的影响，使用前须知：

• 非安全隔离：默认环境不是隔离沙箱，模型执行的命令会对本地系统产生真实的读写和进程副作用。
• 权限与拦截：如需在执行高危命令前进行人工审批或条件限制，可使用工具拦截 Hooks。
• 容器与隔离环境：如需隔离执行，可通过插件提供独立的执行环境。

集成与扩展工具

如果内置工具无法满足需求，可以通过以下方式扩展：

• 安装社区插件：浏览 社区插件 列表搜索插件或第三方 MCP 服务（见 MCP 集成）；
• 开发自定义插件：编写 Python 函数并注册为 Bub 工具，随插件一起分发，详见插件开发：提供工具。