xiaoski/PicoBot

Fork 0

xiaoxixi e45980a282 feat: add cancellable sleep tool

2026-08-06 08:38:43 +08:00

10 KiB

Raw Blame History

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`
`prompt`	run 必填	子任务描述
`mode`	否	`inline`, `background`, `parallel`，默认 `inline`
`allowed_tools`	否	子 Agent 可用工具列表；默认只读工具集
`max_iterations`	否	最大迭代次数，默认 99
`timeout_secs`	否	超时秒数，默认 3600
`tasks`	parallel 必填	并行子任务数组
`task_id`	查询/取消必填	后台任务 ID
`plan_item_id`	否	将 inline/background 子 Agent 绑定到当前计划子项；parallel 数组中的每项也可分别绑定

默认只读工具集：file_read、file_search、content_search、web_fetch、http_request、calculator。

todo — Session 任务计划

仅用于明确的复杂、多轮或并行任务。create 创建当前 session 唯一的 active plan；view 查看；append 增加子项；update 修改子项状态；close 完成或取消计划。普通闲聊和单步操作不应创建计划。子 Agent 始终被过滤掉 todo 和 delegate，计划结构只由主 Agent 管理。

browser — 浏览器自动化

默认注册；设置 browser.enabled=false 后不注册。PicoBot 上层包装统一 action 和结构化媒体，底层逐次调用 agent-browser --json；每个 PicoBot dialog 映射到一个不透明的 agent-browser session，同 dialog 串行、不同 dialog 可并发。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`
`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 字符上限。

依赖缺失时必须把错误和处置命令返回给用户，不能声称已浏览，也不能在工具内部静默安装：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。

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`	百分位数

10 KiB Raw Blame History Unescape Escape