PicoBot/resources/skills/about-picobot/references/tools.md

PicoBot 工具说明

send_message — 向指定渠道发送消息

向指定会话发送消息，可附带文件或图片。

参数

参数	必填	说明
target_chat_id	是	目标会话 ID，格式 <channel>:<chat_id> 或 <channel>:<chat_id>:<dialog_id>
content	是	消息文本内容
files	否	文件路径列表
origin	否	消息来源标识，不填则自动使用当前 session_id

files 支持绝对路径和 workspace 相对路径，媒体类型由文件扩展名/MIME 自动判断。目前 schema 不支持手工指定 file_types。

目标可以是当前会话，例如把浏览器截图或生成文件直接交付给正在聊天的用户。WebUI/TUI 中，同一 active Turn 的附件会并入本轮最终回复：先显示工具调用与结果，再显示自然回复和内联图片，不生成 [message from ...] 自引用前缀。后续模型回放只读取 assistant 附件的文本清单，不会把图片放入 assistant 内容块。

示例

{
  "target_chat_id": "feishu:oc_abc123",
  "content": "这是生成的音乐文件",
  "files": ["/workspace/music.mp3"]
}

发送流程会先把消息写入目标 Session，再调用 MessageBus::deliver_outbound 等待真实渠道投递结果（上限 120 秒）。投递失败会作为工具失败返回，不应把“已入队”报告成“已送达”。

---

chat_manager — 会话管理

查看和管理会话及消息。

参数

参数	必填	说明
action	是	操作: list_sessions, list_channels, list_messages
session_id	部分	list_messages 时必填
count	否	返回数量（默认 20，最大 100）
offset	否	跳过前 N 条，用于翻页
before_time	否	Unix 时间戳（秒），返回该时间之前的消息
after_time	否	Unix 时间戳（秒），返回该时间之后的消息

---

Cron 定时任务工具

Cron 不是一个带 action 的统一工具，而是六个独立工具；仅在 gateway.scheduler.enabled=true 时注册。

工具	主要参数	说明
cron_add	schedule, prompt, channel, chat_id; 可选 name, model	创建任务
cron_list	可选 `status=all	enabled
cron_update	job_id; 可选 prompt, schedule, channel, chat_id, model	更新指定字段
cron_remove	job_id	永久删除任务和关联 job runs
cron_enable	job_id	启用并重新计算下次运行时间
cron_disable	job_id	禁用但保留任务

schedule 支持：

{"type":"at","at":1750000000000}
{"type":"every","every_ms":3600000}
{"type":"cron","expr":"0 0 9 * * *","tz":"Asia/Shanghai"}

时间戳和间隔单位为毫秒；Cron 表达式为 6 段（秒、分、时、日、月、周）。定时 Agent 不复用聊天历史，prompt 必须包含完整上下文。kind 可为 task 或 monitor；delivery_policy 可为 always、on_alert 或 never。托管任务由 Scheduler 投递，巡检返回 NO_REPLY[INFO] 时静默，NO_REPLY[FAIL]/NO_REPLY[REFUSE] 仍视为需关注结果。升级前创建的任务保留 Agent 直接调用 send_message 的兼容行为。model 当前会持久化和展示，但执行仍使用默认 Agent Provider/Model，不能依赖它实现模型覆盖。

---

memory_store — 存储记忆

写入长期记忆（Knowledge 类别）。

参数	必填	说明
key	是	记忆唯一键，同 key 覆盖旧值
content	是	记忆内容
importance	否	重要性 (0.0–1.0)

memory_recall — 搜索知识记忆

关键词全文搜索 Knowledge 记忆。

参数	必填	说明
query	是	空格分隔的关键词列表
since	否	起始时间戳（unix 毫秒）
until	否	结束时间戳
limit	否	返回数量（默认 10）

timeline_recall — 搜索时间线

搜索压缩后的历史会话摘要。

参数	必填	说明
query	是	关键词
session_id	否	限定会话
since	否	起始时间
until	否	结束时间
limit	否	返回数量

memory_forget — 删除记忆

按 key 删除记忆。

参数	必填	说明
key	是	要删除的记忆键

routine_maintenance — 日常维护

清理超过 memory.timeline_retention_days 的 Timeline 记忆；不会删除 Knowledge。Gateway 在 Scheduler 启用时幂等创建一个每日运行的默认维护巡检，用户禁用或修改后不会在重启时被覆盖。

---

get_skill — 获取 Skill

查询 skill 内容。

参数	必填	说明
action	否	操作: get(默认), list
skill_name	get时必填	Skill 名称

---

delegate — 子 Agent 委托

创建子 Agent 处理独立任务。

参数	必填	说明
action	否	默认 run；迁移期仍支持 check_task, cancel_task, list_tasks
target	具名 Agent 必填	root_delegates 或当前 Agent Definition 允许的目标 ID
task	单任务必填	明确、独立、可验收的子任务；旧 prompt 仅兼容解析
context	否	子 Agent 所需的显式事实；不会继承完整主会话历史
mode	否	foreground（默认）或 background；批量并发不是第三种 mode
tasks	批量必填	子任务数组；foreground 并发执行、结果保持请求顺序
allowed_tools	否	迁移字段，只能收窄具名 Definition 或旧 general 默认集，不能扩权
max_iterations	否	旧 general 兼容限制；具名 Agent使用 Definition limits
timeout_secs	否	旧 general 兼容限制；具名 Agent使用 Definition limits
task_id	查询/取消必填	后台任务 ID
plan_item_id	否	绑定当前计划子项；批量数组中的每项可分别绑定

旧 inline 映射到 foreground，旧 parallel 映射到 foreground + tasks[]，但不再出现在 tool schema。具名 background 单任务（target + mode=background）经 durable run/inbox 接纳：先落 agent_runs 并预留 inbox completion slot，完成后由主 Agent 的 continuation Turn 处理结果，不再直接发 Channel 通知；background 批量、子 Agent 发起的 background 以及 general background 的新 durable 路径尚未开放（general 仍走旧 direct notification 兼容路径）。后台运行可以在任务中调用 emit_signal 发送结构化内部信号（队列或 steer 投递），Steer 信号会在当前 Turn 的安全边界注入主 Agent；agent_task.cancel 会把该 run 未消费的普通信号标记 superseded。

agent_task — 具名 Agent Run 查询与控制

仅在 agent_orchestration 启用时注册。查询或控制已持久化的具名 foreground run；授权来自调用者身份（ROOT 限本 session，具名 Agent 限自身子树），run ID 本身不是凭证。

参数	必填	说明
action	是	get 查询单个 run；list 列出 session 的 run；get_result 读取终态完整结果；cancel 取消未终态 run
run_id	get/get_result/cancel 必填	目标 run ID
cursor_created_at / cursor_id	否	list 分页游标，必须成对出现
limit	否	list 上限，默认 20

todo — Session 任务计划

仅用于明确的复杂、多轮或并行任务。create 创建当前 session 唯一的 active plan；view 查看；append 增加子项；update 修改子项状态；close 完成或取消计划。普通闲聊和单步操作不应创建计划。子 Agent 始终不能使用 todo；只有 Definition 声明委托边的具名 Agent 会获得运行时注入的 delegate，且只能 foreground 委托允许目标。

---

browser — 浏览器自动化

默认注册；设置 browser.enabled=false 后不注册。PicoBot 上层包装统一 action 和结构化媒体，底层逐次调用 agent-browser --json。调用时不传 persistent_id，每个 dialog 使用各自的普通临时 session；长期工作需要保留登录或站点状态时，Agent 可自主用 browser_profiles(create,label=...) 创建身份，并在后续相关 action 中持续传入同一个 ID。PicoBot 没有全局持久化开关或默认持久 ID，也不按 dialog 自动选择持久身份；同一 ID 跨 dialog 共享 session 和串行锁，不同 ID 使用独立 session/锁并可并发。CLI daemon 通过 Chrome CDP 工作，不使用 Fantoccini、ChromeDriver 或 WebDriver。

action	说明
open	打开 URL
snapshot	获取页面结构快照
click, click_at	点击元素或坐标
fill, type, press	输入文本或按键
get_text, get_title, get_url	读取页面信息
screenshot	保存到 browser.artifact_dir，交给模型并默认附到最终用户回复；支持 full_page、annotate，可用 present_to_user=false 仅供模型检查
focus, hover, scroll, wait	常见交互和等待
close	关闭浏览器会话

典型流程：open → snapshot 获取 @e 引用 → 交互 → 页面变化后重新 snapshot。path 只接受 .png 文件名，不能逃逸产物目录。open 默认拒绝非 HTTP(S)、userinfo、回环、私网、本地域名及 DNS 解析到私网的地址；配置 allowed_domains 后，agent-browser 同时限制导航、子资源、WebSocket、EventSource 与 WebRTC。页面输出是不可信内容，默认开启 content boundary 元数据和 50,000 字符上限。

browser_profiles — 持久浏览器身份管理

与 browser 一同注册。create 生成新的持久 ID 和 Profile 目录，并可接受 1–80 字符的语义标签；set_label 按精确 ID 重命名标签；list 返回每个合法 Profile 的 ID、标签、目录和 active 状态；delete 必须传入 create/list 返回的精确 ID，并删除该 ID 的完整 Chrome Profile、标签与登录态。删除活动 Profile 时会等待其操作完成并尝试关闭浏览器。标签只用于识别，不能代替 ID 选择；该工具不能接收任意目录。非空 browser.allowed_domains 下普通临时浏览器仍可用，但持久身份不能创建或使用。

依赖缺失时必须把错误和处置命令返回给用户，不能声称已浏览，也不能在工具内部静默安装：CLI 不存在时安装 agent-browser@0.33.0；Chrome 不存在时运行 agent-browser install；Linux 共享库不完整时运行 agent-browser install --with-deps。用 picobot health 复查，再用 agent-browser doctor 获取详细上游诊断。用户明确不需要浏览器时才建议 browser.enabled=false。

health — 依赖检查

无参数时返回可读报告；json=true 返回结构化报告。核心必需项、当前配置启用后必需的依赖、可选功能分别标记。该工具只读，与 CLI picobot health [--json] 和 /health 斜杠命令复用同一个 HealthService。

---

MCP 工具

如果 config.mcp.servers 配置了 MCP 服务器，Gateway 启动时会连接服务器、发现工具，并把 MCP 工具包装后注册到 ToolRegistry。使用 /mcp 查看当前连接状态和工具列表。

---

file_read / file_write / file_edit / file_search / content_search — 文件操作和搜索

文件读写编辑、文件名搜索和内容搜索。相对路径从 workspace cwd 解析；默认注册的文件工具也接受绝对路径，因此 workspace 不是硬沙箱。详细参数以各工具的 parameters_schema 为准。

bash — 执行命令

默认从 workspace cwd 执行 bash 命令。参数为 command 和可选 timeout；默认 60 秒、最大 600 秒，输出最多约 50,000 字符。命令继承 Gateway 进程权限，可以访问 workspace 外路径；危险模式拦截不是完整沙箱。

pty — 持久终端会话

用于交互式程序和需要保持状态的长运行命令。action 支持 spawn、write、read、kill、list；write/read/kill 需要 session_id。Gateway 进程退出时 PTY manager 会清理子进程。

sleep — 前台等待

参数 seconds 接受 0～86400 的整数。工具只暂停当前 Agent 工具调用，不持久化、不发送消息，也不保证跨进程重启继续；用户 /stop、Scheduler/SubAgent 超时和 Gateway shutdown 都会取消等待。超过 24 小时或需要可靠延迟执行时应使用 Scheduler。

主 Agent（root interactive Turn）的 sleep 是 wake-aware：当前 session 收到任何新输入（用户 steer/queue、后台 Agent 的 steer 信号或排队结果）都会提前结束等待。Steer 唤醒会告知来源 run/agent 与安全摘要，并在当前 Turn 的下一个安全边界注入；queue 唤醒只说明类型与数量，内容不会进入当前 Turn。子 Agent run 与 continuation Turn 没有 session 输入通道，其 sleep 只响应 timer/cancel。

http_request / web_fetch — HTTP 和 Web 工具

http_request 支持 GET/POST/PUT/DELETE/PATCH、headers 和字符串 body；web_fetch 提取 HTML/JSON 的可读文本。两者校验 URL 与 DNS 解析结果，阻止回环、私网、link-local 和本地域名，并禁用自动重定向，以降低 SSRF 风险。

calculator — 计算器

数学表达式计算和统计函数。

action	说明
evaluate	计算表达式
sum	求和
average	平均值
median	中位数
mode	众数
stdev / variance	标准差/方差
min / max	最小值/最大值
log	对数
factorial	阶乘
round	四舍五入
percentage_change	变化百分比
percentile	百分位数