核心用法
roadrunner（简称 rr）是 Beeper Desktop 的命令行接口，通过本地 API 与 Matrix 统一消息平台交互。主要功能覆盖四大领域：
1. 聊天管理：列表现有聊天、搜索（支持参与者、时间、未读等过滤）、创建新对话、归档/取消归档
2. 消息操作：列出消息历史、搜索关键词、发送/编辑消息、上传附件、监听实时消息流（tail/wait）
3. 联系人：按账户搜索和解析联系人，处理多账户场景下的身份歧义
4. 提醒与状态：设置聊天提醒、查看全局未读汇总、获取连接状态
Agent 友好特性：
--agent标志强制 JSON 输出、信封错误格式、无交互模式、只读安全默认--readonly可完全禁止写入操作--enable-commands白名单机制限制可执行命令范围- 信封错误包含
error.hint字段，支持智能重试决策
显著优点
- 协议统一：通过 Matrix 桥接 iMessage、WhatsApp、Signal 等 15+ 聊天服务，单 CLI 管理多端
- 自动化友好：完整的 JSON 输出、分页控制、游标导航、请求 ID 追踪和去重窗口机制
- 安全沙盒：细粒度权限控制（只读模式、命令白名单、强制确认），降低自动化风险
- 实时能力：消息 tail 轮询、条件等待（wait）、草稿预填充等交互式场景支持
潜在缺点与局限性
- 依赖桌面端：必须保持 Beeper Desktop 运行，无法独立作为守护进程
- 搜索语义弱：关键词搜索为字面量匹配，无向量或语义搜索能力
- 认证摩擦：需手动从 App 设置提取 Token，环境变量配置对非技术用户门槛较高
- 生态封闭：仅支持 Beeper 自有协议栈，无法扩展至其他 Matrix homeserver
- 历史扩展限制：
!字符在 bash/zsh 触发历史展开，需特殊处理引号或关闭扩展
适合人群
- 需要将聊天数据集成到工作流（CI/CD 通知、客服工单、日志监控）的开发者
- 使用 Beeper 作为主力 IM 工具，希望实现批量操作或自动化响应的高级用户
- 构建聊天机器人、消息归档、合规审计系统的工程师
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 误发消息 | 自动化脚本目标 ID 错误导致消息发错聊天 | 强制 `--readonly` 预演，确认 recipient 后再解除 |
| Token 泄露 | `BEEPER_TOKEN` 环境变量被日志/进程列表捕获 | 使用专用 secret 管理工具，禁止在对话中粘贴 |
| 数据残留 | 下载媒体或草稿文件本地留存 | 定期清理 `--download-dir`，敏感内容启用临时目录 |
| 竞态写入 | 非幂等操作（发送、创建聊天）重复执行 | 使用 `--request-id` + `--dedupe-window` 严格去重 |
| 服务中断 | Beeper Desktop 崩溃或网络波动 | 封装重试逻辑，区分 `CONNECTION_ERROR` 与其他错误码 |