核心用法
roadrunner（rr）是一款面向 Beeper Desktop 的命令行接口，允许用户通过本地 API 直接操作聊天应用。核心能力覆盖四大领域：
1. 聊天管理：列出、搜索、创建聊天，支持按参与者、活动时间、未读状态筛选；归档/取消归档聊天。
2. 消息操作：发送、编辑消息，支持附件上传与下载；消息搜索、分页浏览、实时轮询（tail/wait）。
3. 联系人处理：跨账户搜索联系人、解析模糊名称至具体用户 ID。
4. 辅助功能：全局搜索、未读汇总、应用聚焦、提醒设置。
典型工作流
- 安全模式优先：使用
--agent强制 JSON 输出、只读模式、无交互；配合--enable-commands白名单限制可操作范围。 - 认证配置：通过
BEEPER_TOKEN环境变量注入令牌，避免在命令历史中暴露凭证。 - 分页与批量：
--all+--max-items实现自动分页，适合导出大量历史消息；--download-media可同步下载附件。
显著优点
- 深度集成 Beeper 生态：直接调用 Beeper Desktop 本地 API，延迟低、功能完整，覆盖官方客户端大部分核心能力。
- 自动化友好：全面的
--json输出、结构化错误信封（--envelope）、环境变量支持，适合脚本编写和 CI/CD 场景。 - 安全机制完善：内置
--readonly、--agent、命令白名单、防重放（--request-id+--dedupe-window）等多重保护。 - 跨平台支持：提供 Homebrew 和 Go 模块两种安装方式，覆盖 macOS 和主流 Linux 发行版。
潜在缺点与局限性
- 依赖桌面端运行：必须保持 Beeper Desktop 应用开启，无法独立作为后台服务运行。
- 认证门槛：需手动从 Beeper 设置中提取 API Token，对普通用户不够友好；Token 管理不当存在泄露风险。
- Matrix ID 复杂性：聊天 ID 采用 Matrix 格式（
!chatid:beeper.com），名称解析偶有歧义，需配合--scope=participants或contacts resolve二次确认。 - 搜索语义局限：消息搜索为字面匹配，不支持语义或模糊搜索；全局搜索单页上限 20 条，需手动处理分页。
- Shell 特殊字符：
!在 bash/zsh 中触发历史扩展，需额外注意引号或关闭历史扩展。
适合人群
- 高级用户与极客：习惯命令行、需要批量处理消息或自动化工作流。
- 开发者与运维：需集成 Beeper 消息至内部系统、监控告警或日志归档。
- 多账号管理者：同时维护个人与工作 Beeper 账户，需快速切换与汇总视图。
常规风险
- 凭证泄露：
BEEPER_TOKEN若写入 shell 历史或日志文件，可能被恶意程序读取。 - 误操作风险：
--force与--no-input组合可能绕过确认提示，导致消息误发或聊天归档。 - 数据完整性：非幂等操作（发送消息、创建聊天、上传资源）在网络异常时可能重复执行，需依赖
--request-id与--dedupe-window防重。 - 隐私合规：导出聊天记录与媒体文件时，需遵守相关数据保护法规及平台服务条款。