Roadrunner

核心用法

roadrunner（rr）是 Beeper Desktop 的非官方 CLI 工具，通过本地 API 与 Beeper 客户端交互。核心功能覆盖四大模块：

1. 账户与联系人管理：rr accounts list 查看绑定账户，rr contacts search/resolve 跨账户搜索联系人
2. 聊天操作：rr chats list/search/create/archive 管理会话，--scope=participants 可按参与者名称查找
3. 消息处理：rr messages list/search/send/tail/wait 支持发送、轮询、条件等待等高级操作，--download-media 可自动下载附件
4. 工作流增强：rr focus 控制应用焦点与草稿，rr reminders 设置聊天提醒，rr unread 汇总未读

安全特性突出：--agent 模式强制 JSON 输出与只读安全策略，--readonly 完全禁止写入，--enable-commands 实现命令白名单，--envelope 提供结构化错误封装。

显著优点

• 自动化友好：完整的 JSON API、--no-input 无人值守、stdin/文件输入、环境变量覆盖（BEEPER_TOKEN/BEEPER_ACCOUNT）
• 功能深度：消息上下文查询、条件等待（--contains + --wait-timeout）、附件下载、草稿预填充
• 多账户支持：账户别名机制，跨平台（iMessage/Slack/WhatsApp 等）统一操作
• 分页与过滤：cursor 分页、时间范围、媒体类型、发件人等精细过滤

潜在局限

• 依赖桌面端：必须保持 Beeper Desktop 运行，无法独立工作
• 搜索语义弱：消息搜索为字面词匹配，非语义/向量搜索
• 联系人解析严格：contacts resolve 遇歧义名称直接失败，需先 search 再按 ID 操作
• 生态封闭：仅限 Beeper 平台，无法桥接其他 Matrix 客户端

适合人群

• 需批量处理消息的高级用户
• 构建个人自动化工作流的开发者
• 偏好终端效率、反感 GUI 切换的键盘派

常规风险

• Token 泄露：~/.config/beeper/config.json 存储凭证，需严格权限控制
• 意外发送：--force 与 --no-input 组合可能绕过确认，建议生产环境用 --readonly 或白名单
• 历史扩展冲突：bash/zsh 的 ! 触发历史展开，需用单引号或禁用该特性
• API 稳定性：非官方工具，随 Beeper 更新可能中断

核心用法

roadrunner（简称 rr）是 Beeper Desktop 的命令行接口封装文档，用于在终端环境中管理跨平台即时通讯。

主要功能模块：

• 账户管理：rr accounts list 查看多平台账号，rr accounts alias set 设置别名简化调用
• 聊天操作：rr chats list/search/get 浏览与检索对话，rr chats create 创建单聊或群聊，rr chats archive 归档管理
• 消息处理：rr messages list/search/send 支持发送文本、回复、从文件/标准输入读取内容，rr messages tail/wait 实现消息轮询与条件等待
• 智能搜索：rr search 全局搜索跨聊天内容，rr contacts search/resolve 联系人查询与解析
• 提醒与聚焦：rr reminders set/clear 设置聊天提醒，rr focus 控制应用焦点与草稿预填充
• 媒体下载：rr messages list --download-media 批量下载附件，rr assets download 单独获取媒体文件

关键安全机制：

• --agent 模式强制启用 JSON 输出、信封错误、无交互、只读限制，专为自动化场景设计
• --readonly 完全阻断写入操作
• --enable-commands 白名单机制精确控制允许执行的命令范围
• Token 存储于 ~/.config/beeper/config.json，可通过 BEEPER_TOKEN 环境变量覆盖

显著优点

1. 多平台统一：整合 iMessage、WhatsApp、Signal、Slack、Matrix 等 15+ 协议于单一 CLI
2. 自动化友好：完整 JSON API、结构化错误信封、分页游标、退出码控制（--fail-if-empty）
3. 灵活输入：支持文本直接传入、文件读取、管道输入三种消息来源
4. 精细搜索：按时间范围、发件人、媒体类型、已读状态等多维度过滤
5. 安全设计：破坏性操作需 --force 确认，支持 --no-input 非交互模式

潜在局限

1. 依赖外部工具：仅提供文档指引，必须独立安装 rr CLI（通过 Homebrew 或 Go）
2. Beeper Desktop 前置：需保持桌面应用运行作为 API 服务端
3. 搜索语义限制：消息搜索为字面匹配，不支持自然语言语义理解
4. Shell 兼容性问题：聊天 ID 中的 ! 字符触发 bash/zsh 历史扩展，需特殊处理
5. 个人开发者维护：T3 来源，长期维护稳定性依赖单一开发者

适合人群

• 开发者与运维工程师：需要将 Beeper 集成到自动化工作流
• 多平台通讯重度用户：追求键盘驱动的高效聊天管理
• 数据归档需求者：批量导出消息与媒体附件
• CLI 爱好者：偏好终端操作胜过图形界面

常规风险

• Token 泄露风险：认证令牌存储于本地文件，共享设备需额外防护
• 误操作发送：虽有多重确认机制，自动化脚本中仍可能因参数错误导致消息误发
• 服务可用性依赖：Beeper Desktop 未运行时 CLI 完全不可用
• Matrix ID 混淆：群聊标题可能显示自身 ID，需用 --scope=participants 辅助定位