roadrunner (rr)

使用rr当用户明确希望通过本地API操作Beeper Desktop时（发送、搜索、列出聊天/消息、提醒、焦点）。 优先使用--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 describe messages send --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
• 列出聊天（JSON行格式）：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 "<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
• 搜索消息（JSON行格式）：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" "<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>" "更新的文本"
• 消息添加/移除反应：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 "见附件"
• 创建聊天：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。
• 使用--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="<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桌面版正在运行；令牌来自应用设置。
• 令牌存储在~/.config/beeper/config.json通过rr auth set（推荐）。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）。
• Accountnetwork字段在较新的API构建中可能缺失；rr在摘要/搜索输出中会回退到"unknown"。
• rr assets serve会将原始字节写入标准输出，除非使用了--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基础URL；BEEPER_TIMEOUT设置超时时间（以秒为单位）。
• JSON/纯文本输出发送到标准输出；错误/提示信息发送到标准错误输出。
• 除非使用--force，否则破坏性命令会提示确认；--no-input/BEEPER_NO_INPUT在没有--force的情况下会失败。
• 在列表/搜索命令中使用--fail-if-empty，如果无结果则以代码1退出。
• 配合--plain使用--fields以选择列（逗号分隔）。
• 在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验证错误,连接错误,内部错误.
• 重试策略：重试连接错误时采用退避策略；不要盲目重试认证错误/验证错误；重试前刷新ID未找到.
• 非幂等写入操作：消息发送,文件发送,聊天创建,聊天启动,资源上传,资产上传-以Base64编码.
• 使用--request-id/BEEPER_REQUEST_ID来标记信封元数据，以便追踪跨重试尝试。
• 使用--dedupe-window/BEEPER_DEDUPE_WINDOW来阻止具有重复请求ID的非幂等写入。
• 本地冒烟测试：make test-agent-smoke。