介绍
# roadrunner (rr)
当用户明确希望通过本地 API 操作 Beeper Desktop 时（发送、搜索、列出聊天/消息、提醒、focus），请使用 `rr`。 对于代理使用，优先使用 `--agent`（强制 JSON、envelope、no-input、readonly）。
安全 - 除非用户在此轮中明确请求修改操作，否则默认为只读命令。 - 发送前需要明确的接收方（聊天 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"` - Envelope 错误可能包含 `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 "[email protected]" --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 "[email protected]" --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`。 - 仅在使用 `--download-media` 时才会填充 `downloaded_attachments`。 - `rr messages send` 返回 `pending_message_id`（临时 ID）。 - 在较新的 API 版本中，账户 `network` 可能缺失；`rr` 在摘要/搜索输出中回退为 `"unknown"`。 - 除非提供 `--dest`，否则 `rr assets serve` 将原始字节写入 stdout。 - `--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`；如果没有 `--force`，`--no-input`/`BEEPER_NO_INPUT` 将失败。 - 在列表/搜索命令上使用 `--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`。 - Envelope 错误代码：`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`。