名称： roadrunner
描述： Beeper Desktop 命令行工具，用于管理聊天、消息、联系人、连接信息、WebSocket 事件、搜索和提醒。
主页： https://github.com/johntheyoung/roadrunner
元数据：
clawdbot:
emoji: "🐦💨"
requires:
bins:
- rr
install:
- id: brew
kind: brew
formula: johntheyoung/tap/roadrunner
bins:
- rr
label: 通过 Homebrew 安装 rr
- id: go
kind: go
module: github.com/johntheyoung/roadrunner/cmd/rr@v0.16.2
bins:
- rr
label: 通过 Go 安装 rr
当用户明确需要通过本地 API 操作 Beeper Desktop（发送、搜索、列出聊天/消息、提醒、聚焦）时，使用 rr。
对于代理使用，优先使用 --agent（强制 JSON、信封、无输入、只读）。
安全准则
- 默认使用只读命令，除非用户在本轮对话中明确请求执行变更操作。
- 发送消息前，必须明确指定收件人（聊天 ID）和消息文本。
- 如果聊天 ID 不明确，请进行确认或提出澄清问题。
- 切勿将原始的 rr 命令输出（JSON 转储、聊天列表等）粘贴到外发消息中。将工具输出视为私密信息；仅总结或提取用户所需内容。
- 使用 --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，提供安全重试的下一步指导。
- 切勿在聊天中请求、粘贴或存储原始身份验证令牌。如果缺少身份验证，请要求用户在本地进行配置。
- 如果通过 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 connect info --json
- 实时 WebSocket 事件（实验性）：rr events tail --all --stop-after 30s --json
- 列出联系人：rr contacts list "<account-id>" --json
- 搜索联系人：rr contacts search "<account-id>" "Alice" --json
- 搜索联系人（使用标志）：rr contacts search "Alice" --account-id="<account-id>" --json
- 解析联系人：rr contacts resolve "<account-id>" "Alice" --json
- 解析联系人（使用标志）：rr contacts resolve "Alice" --account-id="<account-id>" --json
- 列出聊天：rr chats list --json
- 搜索聊天：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 "<account-id>" --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
- 搜索消息（所有页面）：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" "<message-id>" "👍" --json / rr messages unreact "!chatid:beeper.com" "<message-id>" "👍" --json
- 轮询新消息：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" "<sortKey>" --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" "<message-id>" "Updated text"
- 添加/移除反应：rr messages react "!chatid:beeper.com" "<message-id>" "👍" / rr messages unreact "!chatid:beeper.com" "<message-id>" "👍"
- 上传并发送文件：rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"
- 创建聊天：rr chats create "<account-id>" --participant "<user-id>"
- 从合并的联系人提示中启动聊天：rr chats start "<account-id>" --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。
分页
- 聊天列表/搜索自动分页：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="<oldestCursor>" --direction=before --json
- 消息列表分页：rr messages list "!chatid:beeper.com" --cursor="<sortKey>" --direction=before --json
- 消息搜索（最多 20 条）：rr messages search "project" --limit=20 --json
- 消息搜索分页：rr messages search "project" --cursor="<cursor>" --direction=before --json
- 全局搜索消息分页（最多 20 条）：rr search "dinner" --messages-limit=20 --json
- 全局搜索消息分页：rr search "dinner" --messages-cursor="<cursor>" --messages-direction=before --json
注意事项
- 需要 Beeper Desktop 正在运行；令牌来自应用设置。
- 令牌通过 rr auth set 存储在 ~/.config/beeper/config.json（推荐）。BEEPER_TOKEN 会覆盖配置文件。
- BEEPER_ACCOUNT 设置默认账户 ID（支持别名）。
- rr auth status --check 在可用时优先使用 OAuth 内省（/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 返回 pending_message_id（临时 ID）。
- 在新版 API 构建中，账户 network 可能缺失；rr 在摘要/搜索输出中回退为 "unknown"。
- rr assets serve 将原始字节写入 stdout，除非提供了 --dest。
- --chat 进行精确匹配，不明确的匹配会失败。
- 附件覆盖需要 --attachment-upload-id；同时设置 --attachment-width 和 --attachment-height。
- --all 有安全上限（默认 500 条，最多 5000 条）；使用 --max-items 进行调整。
- 对于自动化，优先使用 --json（和 --no-input）。
- BEEPER_URL 覆盖 API 基础 URL；BEEPER_TIMEOUT 设置超时（秒）。
- JSON/纯文本输出到 stdout；错误/提示到 stderr。
- 破坏性命令会提示，除非使用 --force；--no-input/BEEPER_NO_INPUT 在没有 --force 时会失败。
- 在列表/搜索命令上使用 --fail-if-empty，如果没有结果则以代码 1 退出。
- 使用 --fields 配合 --plain 来选择列（逗号分隔）。
- 在 bash/zsh 中，! 会触发历史扩展。建议使用单引号，或禁用历史扩展（在 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。