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。