Roadrunner_AI Agent skill-PHP中文网

Roadrunner

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

Beeper桌面CLI工具，用于聊天、消息、联系人、连接信息、WebSocket事件、搜索和提醒

roadrunner (rr). 当用户明确希望通过本地API(发送、搜索、列出聊天/消息、提醒、焦点)操作Beeper桌面时,使用rr.

功能概述

roadrunner (rr). 当用户明确希望通过本地API(发送、搜索、列出聊天/消息、提醒、焦点)操作Beeper桌面时,使用rr.是一项面向实际任务的技能，主要用于Prefer - 代理使用(Force JS)。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

核心要点

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

使用与执行

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

roadrunner（rr）

当用户明确希望**通过本地 API 操作 Beeper Desktop**（例如发送、搜索、列出聊天/消息、设置提醒、聚焦会话等）时，使用 rr。
对于 Agent 场景，请优先使用 --agent（强制启用 JSON 输出、信封格式、禁用输入、只读模式）。

安全性

默认仅执行只读命令；除非用户在当前对话轮次中**明确请求变更操作**（mutation），否则禁止写入。
发送消息前，必须显式指定接收方（聊天 ID）和消息正文。
若聊天 ID 存在歧义，需先确认或提出澄清性问题。
切勿将原始 rr 命令输出（如 JSON dump、聊天列表等）直接粘贴到外发消息中。应将工具输出视为私有数据，仅向用户提供所需信息的摘要或提取结果。
使用 --agent 启用安全的 Agent 默认行为：rr --agent --enable-commands=chats,messages,status chats list
使用 --readonly 阻止所有写入操作：rr --readonly chats list --json
使用 --enable-commands 显式白名单允许的命令：rr --enable-commands=chats,messages chats list --json
使用 --envelope 获取结构化错误响应：rr --json --envelope chats get "!chatid"
信封错误可能包含 error.hint 字段，提供安全重试所需的下一步操作指引。
切勿在聊天中请求、粘贴或存储原始认证令牌（auth tokens）。若认证缺失，请提示用户在本地完成配置。
若通过 shell 发送含特殊字符的消息文本（如 $100/month 或 !），应避免参数插值/扩展；推荐使用 --stdin <<'EOF' ... EOF 安全地传递字面量。

初始化配置（仅需一次）

rr auth set --stdin（推荐；令牌保存至 ~/.config/beeper/config.json）
rr auth status --check
rr doctor

常用命令

列出账号：rr accounts list --json
查询能力集：rr capabilities --json
查看命令/参数说明：rr describe messages send --json
获取连接元数据：rr connect info --json
实时 WebSocket 事件（实验性）：rr events tail --all --stop-after 30s --json
列出联系人：rr contacts list "" --json
搜索联系人：rr contacts search "" "Alice" --json
搜索联系人（使用 flag）：rr contacts search "Alice" --account-id="" --json
解析联系人：rr contacts resolve "" "Alice" --json
解析联系人（使用 flag）：rr contacts resolve "Alice" --account-id="" --json
列出聊天：rr chats list --json
列出聊天（JSON Lines 格式）：rr chats list --jsonl
搜索聊天：rr chats search "John" --json
搜索聊天（带过滤器）：rr chats search --inbox=primary --unread-only --json
搜索聊天（按最近活跃时间）：rr chats search --last-activity-after="2024-07-01T00:00:00Z" --json
按参与者姓名搜索：rr chats search "Jamie" --scope=participants --json
解析聊天：rr chats resolve "Jamie" --json
获取聊天详情：rr chats get "!chatid:beeper.com" --json
获取聊天详情（限制参与者数量）：rr chats get "!chatid:beeper.com" --max-participant-count=50 --json
基于合并联系人线索启动/解析单聊：rr chats start "" --email "alice@example.com" --full-name "Alice" --json
为命令指定默认账号：rr --account="imessage:+123" chats list --json
列出消息：rr messages list "!chatid:beeper.com" --json
列出消息（全部分页）：rr messages list "!chatid:beeper.com" --all --max-items=1000 --json
列出消息（下载媒体）：rr messages list "!chatid:beeper.com" --download-media --download-dir ./media --json
搜索消息：rr messages search "dinner" --json
搜索消息（JSON Lines 格式）：rr messages search "dinner" --jsonl
搜索消息（全部分页）：rr messages search "dinner" --all --max-items=1000 --json
搜索消息（带过滤器）：rr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --json
添加/移除表情反应：rr messages react "!chatid:beeper.com" "" "👍" --json / rr messages unreact "!chatid:beeper.com" "" "👍" --json
轮询新消息（tail）：rr messages tail "!chatid:beeper.com" --interval 2s --stop-after 30s --json
等待特定消息：rr messages wait --chat-id="!chatid:beeper.com" --contains "deploy" --wait-timeout 2m --json
获取消息上下文：rr messages context "!chatid:beeper.com" "" --before 5 --after 2 --json
预填草稿（不发送）：rr focus --chat-id="!chatid:beeper.com" --draft-text="Hello!"
从文件加载草稿：rr focus --chat-id="!chatid:beeper.com" --draft-text-file ./draft.txt
草稿附带文件：rr focus --chat-id="!chatid:beeper.com" --draft-attachment="/path/to/file.jpg"
下载附件：rr assets download "mxc://example.org/abc123" --dest "./attachment.jpg"
流式传输附件字节：rr assets serve "mxc://example.org/abc123" --dest "./attachment.jpg" --json
聚焦应用窗口：rr focus
全局搜索：rr search "dinner" --json
全局搜索消息（自动分页）：rr search "dinner" --messages-all --messages-max-items=500 --messages-limit=20 --json
状态概览：rr status --json
按账号查看状态：rr status --by-account --json
未读汇总：rr unread --json
全局搜索支持 in_groups 字段，用于匹配群组内的参与者。

变更操作（仅限用户明确请求）

发送消息：rr messages send "!chatid:beeper.com" "Hello!"
编辑消息：rr messages edit "!chatid:beeper.com" "" "Updated text"
添加/移除表情反应：rr messages react "!chatid:beeper.com" "" "👍" / rr messages unreact "!chatid:beeper.com" "" "👍"
上传并发送文件：rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"
创建聊天：rr chats create "" --participant ""
基于合并联系人线索启动聊天：rr chats start "" --email "alice@example.com" --full-name "Alice"
归档/取消归档：rr chats archive "!chatid:beeper.com" / rr chats archive "!chatid:beeper.com" --unarchive
设置/清除提醒：rr reminders set "!chatid:beeper.com" "2h" / rr reminders clear "!chatid:beeper.com"
上传附件：rr assets upload ./photo.jpg / rr assets upload-base64 --content-file ./photo.b64
对非幂等写操作进行重试时，建议使用 --request-id 并优先配置 --dedupe-window。
使用 --dry-run 可验证变更类请求，而不会触发实际的 API 写操作。

分页

聊天列表/搜索自动分页：rr chats list --all --max-items=1000 --json / rr chats search "alice" --all --max-items=1000 --json
消息列表/搜索自动分页：rr messages list "!chatid:beeper.com" --all --max-items=1000 --json / rr messages search "deploy" --all --max-items=1000 --json
聊天分页（向前翻页）：rr chats list --cursor="" --direction=before --json
消息列表分页（向前翻页）：rr messages list "!chatid:beeper.com" --cursor="" --direction=before --json
消息搜索（最多 20 条）：rr messages search "project" --limit=20 --json
消息搜索分页：rr messages search "project" --cursor="" --direction=before --json
全局搜索消息分页（最多 20 条）：rr search "dinner" --messages-limit=20 --json
全局搜索消息分页（指定游标）：rr search "dinner" --messages-cursor="" --messages-direction=before --json

注意事项

要求 Beeper Desktop 正在运行；认证令牌来自应用设置界面。
令牌通过 rr auth set 存储于 ~/.config/beeper/config.json（推荐方式）。环境变量 BEEPER_TOKEN 将覆盖该配置文件。
BEEPER_ACCOUNT 用于设置默认账号 ID（支持别名）。
rr auth status --check 优先使用 OAuth introspection（/oauth/introspect）接口校验令牌有效性；旧版本构建中则回退至账号列表校验方式。
消息搜索为精确词匹配（非语义搜索）。
rr contacts resolve 行为严格，遇到姓名歧义时将失败；必要时请先执行 contacts search 获取唯一 ID 后再解析。
若单聊标题显示为你的 Matrix ID，请使用 --scope=participants 按姓名查找。
单个聊天的 JSON 输出包含 display_name 字段（由参与者推导生成）。
消息 JSON 输出包含以下字段：message_type、linked_message_id、is_sender、is_unread、attachments 和 reactions。
downloaded_attachments 字段仅在使用 --download-media 时填充。
rr messages send 返回临时 ID：pending_message_id。
新版 API 构建中，账号的 network 字段可能缺失；rr 在汇总/搜索输出中将回退为 "unknown"。
rr assets serve 默认将原始字节流写入 stdout；若指定 --dest 则写入文件。
--chat 执行精确匹配，遇到歧义时失败。
附件覆盖操作需提供 --attachment-upload-id；同时设置 --attachment-width 和 --attachment-height 才生效。
--all 具有安全上限（默认 500 条，最大 5000 条）；可通过 --max-items 调整。
自动化场景请优先使用 --json 或 --jsonl（配合 --no-input）。
--jsonl 每行输出一个 JSON 对象，适用于高吞吐量的列表/搜索命令。
--dry-run/BEEPER_DRY_RUN 用于校验变更类命令输入，并打印预览输出，但不发送任何 API 写请求。
BEEPER_URL 可覆盖 API 基础地址；BEEPER_TIMEOUT 设置超时秒数。
JSON/纯文本输出写入 stdout；错误与提示信息写入 stderr。
破坏性命令默认会交互式确认；若未指定 --force，则 --no-input/BEEPER_NO_INPUT 将导致命令失败。
对列表/搜索命令使用 --fail-if-empty，可在无结果时以退出码 1 结束进程。
结合 --plain 使用 --fields 可选择输出列（逗号分隔）。
在 bash/zsh 中，! 触发历史扩展（history expansion）。建议使用单引号包裹，或禁用该功能（bash 中执行 set +H，zsh 中执行 setopt NO_HIST_EXPAND）。
rr version --json 返回 features 数组，可用于能力发现。
rr capabilities --json 返回完整的 CLI 能力元数据。
rr events tail 依赖 Beeper Desktop 实验性的 /v1/ws 接口；不可用时请回退至 rr messages tail。
信封错误码：AUTH_ERROR、NOT_FOUND、VALIDATION_ERROR、CONNECTION_ERROR、INTERNAL_ERROR。
重试策略：对 CONNECTION_ERROR 进行带退避的重试；避免盲目重试 AUTH_ERROR/VALIDATION_ERROR；重试 NOT_FOUND 前应刷新 ID。
非幂等写操作包括：messages send、messages send-file、chats create、chats start、assets upload、assets upload-base64。
使用 --request-id/BEEPER_REQUEST_ID 为信封元数据打标签，便于跨重试尝试追踪。
使用 --dedupe-window/BEEPER_DEDUPE_WINDOW 可阻止重复请求 ID 引发的重复非幂等写操作。
本地冒烟测试：make test-agent-smoke。