内置工具

模型工具使用下划线别名，例如 fs.read 对应 fs_read；文本命令保留原名。插件可以增加或覆盖工具，实际集合以 ,help 和 ,tool.describe 为准。

文本命令支持位置值和 key=value；布尔值使用 true / false，列表使用 JSON 字符串，含空格的值使用引号。

文件、Shell 和 代码模式 操作使用当前会话的 Environment，默认直接在宿主机执行，而非安全沙箱中。

进程

bash

bash(command, cwd=None, timeout_seconds=30, background=False)

参数	类型	说明
command	str	Shell 命令
cwd	str | None	工作目录；相对路径由当前环境解析
timeout_seconds	float	前台等待秒数；超时后转入后台并返回 shell_id
background	bool	是否直接在后台启动；此模式忽略 timeout_seconds

非零退出状态返回工具错误并保留输出；前台无输出时返回 (no output)。

bash.output

bash.output(shell_id, offset=0, limit=None)

参数	类型	说明
shell_id	str	后台 Shell ID
offset	int	字符偏移；限制在 0 到当前输出长度之间
limit	int | None	最多读取的字符数

返回 status、exit_code、output 和 next_offset；进程运行期间 exit_code 为 null。

bash.kill

bash.kill(shell_id)

终止后台进程并返回最终状态和退出码；进程已结束时也可调用。

文件

fs.read

fs.read(path, offset=0, limit=None)

参数	类型	说明
path	str	UTF-8 文本文件路径
offset	int	从 0 开始的行号
limit	int | None	最多返回的行数

省略分页参数时返回整个文件。

fs.write

fs.write(path, content)

写入完整文本并创建缺失的父目录；已有文件会被覆盖，不支持追加或补丁。

fs.edit

fs.edit(path, old, new, start=0)

参数	类型	说明
path	str	文件路径
old	str	待替换文本
new	str	替换后的文本
start	int	从 0 开始的查找行号

替换指定范围内的所有字面匹配；找不到匹配时返回错误，不进行语法解析。

网页

web.fetch

web.fetch(url, headers=None, timeout=10)

参数	类型	说明
url	str	请求 URL
headers	dict | None	HTTP 请求头；可覆盖默认的 Accept: text/markdown
timeout	float	整个请求的总秒数

发送 HTTP GET 请求，返回最终 url、status、content_type 和响应正文；非成功状态返回工具错误。

技能与工具发现

skill

skill(name=None)

省略 name 时列出当前可用技能；传入名称时返回技能位置和正文。找不到时返回 (no such skill)。

tool.describe

tool.describe(names)

names 是运行时名称或模型别名组成的列表。返回工具名称、描述和参数 schema；未知名称列入 unknown，已加载名称列入 already_loaded。

延迟工具从下一个 Step 起可调用，加载记录保存在当前 Tape 中，直到 Tape 重置。

Tape

tape.info

无参数。返回 Tape 名称、条目数、anchor 数、最近 anchor、该 anchor 后的条目数，以及最近的 token 用量和缓存命中率。

tape.search

tape.search(query, limit=20, start=None, end=None, kinds=["message", "tool_result"])

参数	类型	说明
query	str	在 kind、日期、payload 和 meta 的 JSON 文本中进行不区分大小写的包含匹配
limit	int	最多返回的条目数
start / end	str | None	包含边界的 ISO 日期或时间
kinds	list[str]	条目类型列表

返回 matches 和 filtered 数量，并过滤搜索命令自身产生的输出。

内置 FuzzyFileTapeStore 从最新条目向回查找，支持去重和模糊匹配；短于 3 个字符的查询只做包含匹配。其他后端的行为由实现决定。

tape.anchors

无参数。按记录顺序返回 anchor 名称；没有时返回 (no anchors)。

tape.handoff

tape.handoff(name="handoff", summary="")

参数	类型	说明
name	str	anchor 名称
summary	str	保存到 state.summary 的文本

写入 anchor 并移动默认上下文起点，旧记录仍保留。不会自动生成摘要；默认上下文在 anchor 之后读取，边界 anchor 本身不进入模型输入；以 anchor=None 读取时，默认选择器会把 anchor 转为 assistant 消息 [Anchor created: <name>]: <state JSON>。

tape.reset

tape.reset(archive=False)

清空当前 Tape 并创建新的 session/start anchor。archive=True 时先将主 Tape 和 sidecar 归档到 bub.home/tapes/。

子 Agent

subagent

subagent(prompt, model=None, session="temp", allowed_tools=None, allowed_skills=None)

参数	类型	说明
prompt	str | list	子 Agent 的初始输入
model	str | None	本次子运行的 provider:model；默认沿用当前配置
session	str	子 Agent 的会话策略
allowed_tools	list[str] | None	可用工具；默认继承父 Agent 的工具，但排除 subagent
allowed_skills	list[str] | None	可发现的技能；[] 禁用技能发现

工具名支持运行时名称和模型别名；技能名不区分大小写。

session	行为
temp	创建 temp/<id> 会话，不合并新产生的 Tape 条目
inherit	使用当前 session_id，写入同一会话历史
其他字符串	使用指定的会话 ID

返回结构：

{
    "session_id": "temp/1a2b3c4d",
    "output": "...",
    "errors": [],
}

output 只汇总文本增量。temp 只隔离对话记录和模型上下文，不隔离文件、网络或进程副作用。

代码模式 与 spill

run_code

run_code(code, timeout_seconds=120)

在 代码模式 中执行 Python。使用 await tools.<name>(key=value) 调用工具；只有 print() 输出和显式附加的媒体进入结果。

attach_image / attach_audio / attach_video

attach_image(image)
attach_audio(audio)
attach_video(video)

将图片、音频或视频附加到当前 run_code 调用的结果。对应参数接受 republic.Image、republic.Audio 或 republic.Video 对象，也可传入字符串，指定当前 Environment 中的文件路径、http(s) / gs URL 或 data URL；本地文件通过当前环境解析和读取。

这些工具的 exposure 为 "code"，只能在 run_code 内调用。每次调用将媒体追加到结果并返回确认字符串。

spill.read

spill.read(handle, cursor=0, count=1, from_end=False)

参数	类型	说明
handle	str	原工具输出中的 spill 句柄
cursor	int	块位置
count	int	读取块数，每次最多 4 块
from_end	bool	是否从末尾向前读取

返回 next_cursor 和 complete；complete=True 表示已到达当前方向的边界。

spill 只在当前工具集包含 spill.read 时创建。阈值由 BUB_SPILL_THRESHOLD 控制；设为 0 时停止创建新 spill，已有结果仍可读取。

超出阈值的大型工具结果写入 spill sidecar，主对话只保留预览和句柄。Sidecar 是与会话 Tape 配套的另一份 Tape：随主 Tape 一起分支、合并和重置，但它的条目不会进入主上下文。概念见 Sidecar。

会话命令

这些工具的 exposure 为 command，只能通过文本命令调用：

命令	参数	作用
,help	无	列出内部命令和命令前缀
,model	model_id	切换当前会话模型
,reasoning_effort	reasoning_effort	设置当前会话推理力度
,code_mode	enable=true / false	开关当前会话的 代码模式
,quit	无	清理待处理消息、运行中任务和后台 Shell

命令前缀由 BUB_COMMAND_PREFIX 决定。会话设置从下一次 Turn 起生效，并持久化在会话 Tape 中。