Roadrunner

核心用法

roadrunner (rr) 是 Beeper Desktop 的官方命令行接口，让用户无需打开 GUI 即可操控跨平台即时通讯（支持 iMessage、WhatsApp、Signal 等 15+ 网络）。核心能力覆盖四大领域：

1. 聊天管理：chats list/search/resolve/get 浏览与定位对话，--inbox=primary 可过滤主收件箱，--unread-only 仅看未读。
2. 消息操作：messages list/search/send/edit/tail 实现消息查询、发送、编辑与实时监听；--download-media 自动拉取附件到本地。
3. 全局搜索：rr search "keyword" 支持跨聊天全文检索，可限定时间范围、发送者、媒体类型。
4. 焦点与提醒：rr focus 唤起桌面应用并预填充草稿；rr reminders set/clear 设置聊天提醒。

Agent 友好设计：--agent 标志强制启用 JSON 输出、信封错误结构、无交互模式与只读安全策略，适合脚本集成。--readonly、--enable-commands 提供细粒度权限控制，防止误操作。

显著优点

• 多协议统一：通过 Matrix 桥接，单一 CLI 管理十余个消息网络，告别各平台独立客户端。
• 结构化输出：所有命令支持 --json，配合 --envelope 返回标准错误码（AUTH_ERROR、NOT_FOUND 等），便于程序化重试。
• 安全机制完善：破坏性操作需显式 --force；--request-id + --dedupe-window 防止非幂等写入重复执行；环境变量注入 token 避免硬编码。
• 高效批量处理：--all --max-items=5000 自动分页拉取，适合备份或审计场景。

潜在局限

• 依赖 Beeper Desktop：必须保持桌面应用运行，CLI 仅作为本地 API 封装，无法独立工作。
• 搜索语义有限：messages search 为字面词匹配，不支持向量语义或模糊拼音。
• 身份验证门槛：需从 Beeper Desktop 导出 token（BEEPER_TOKEN），首次配置略显繁琐。
• 平台锁定：深度绑定 Beeper 生态，迁移至其他 Matrix 方案需重写工作流。

适合人群

• 自动化爱好者：希望用脚本批量发送通知、备份聊天记录、构建个人消息搜索引擎。
• 多账号运营者：社交媒体管理、客服团队需同时监控多个 iMessage/WhatsApp 商业账号。
• 隐私敏感用户：倾向本地 token 认证、拒绝云端 SaaS 消息托管的技术用户。

常规风险

| 风险类型 | 说明 |

|---------|------|

| 数据泄露 | 若 `BEEPER_TOKEN` 被写入 shell history 或日志文件，可能导致账号被盗用。建议 `set +H` 禁用 bash 历史扩展。 |

| 误发消息 | 脚本 bug 或错误的 `chat-id` 可能导致消息发送至错误对象，建议先用 `--readonly` 验证。 |

| 速率限制 | 高频调用本地 API 可能触发 Beeper Desktop 内部限流，表现为 `CONNECTION_ERROR`。 |

| 附件安全 | `--download-media` 拉取的外部文件需常规杀毒扫描，防范恶意 payload。 |

核心用法

roadrunner（简称 rr）是一款面向 Beeper Desktop 的命令行封装工具，通过本地 API 实现聊天管理、消息收发、全局搜索、提醒设置等功能。该 Skill 为纯 Markdown 文档型，本身不含可执行代码，仅提供详细的 CLI 使用指南与安全规范。用户需自行安装 rr 二进制工具（通过 Homebrew 或 Go 模块），并配置 BEEPER_TOKEN 环境变量完成认证。

显著优点

1. 功能覆盖全面：支持聊天列表、消息搜索、联系人解析、草稿编辑、附件上传下载、消息轮询（tail/wait）等高级操作，满足自动化脚本与批量处理需求。
2. 安全设计周到：内置 --agent（强制 JSON + 只读安全模式）、--readonly（写保护）、--enable-commands（命令白名单）等机制，降低误操作风险；文档明确禁止在聊天中粘贴原始 JSON 输出或泄露 BEEPER_TOKEN。
3. 自动化友好：所有命令支持 --json 结构化输出，配合 --no-input 和 --envelope 错误封装，便于集成到 CI/CD 或 Agent 工作流。
4. 分页与去重机制：提供 --all 自动分页、--request-id 与 --dedupe-window 防重复写入，适合处理大量历史消息。

潜在缺点与局限性

• 外部依赖强耦合：必须安装 rr 二进制且保持版本兼容；Skill 本身无法执行任何操作，仅作指令参考。
• 来源可信度受限：维护者 johntheyoung 为 GitHub 个人开发者账号（T3 级别），rr 工具的供应链安全需用户自行评估。
• 语义搜索缺失：消息搜索为字面量匹配，不支持语义理解；联系人解析在名称歧义时会严格失败。
• Beeper Desktop 必须运行：依赖本地 API，无法独立连接云端服务。

适合人群

• 需要批量导出聊天记录、自动化消息发送的高级 Beeper 用户
• 开发集成 Beeper 能力的自动化 Agent 或脚本开发者
• 熟悉命令行、注重隐私控制（本地 API 不走云端）的技术用户

常规风险

• Token 泄露风险：BEEPER_TOKEN 具备完整账户权限，需严格通过环境变量注入，避免硬编码或日志残留。
• 命令注入风险：发送消息时若直接拼接 shell 变量，可能触发特殊字符（如 $、!）的转义或历史扩展；文档建议使用 --stdin <<'EOF' 传递文本。
• 误写操作风险：发送、编辑、创建聊天等变更操作需显式开启，默认只读模式可有效防护，但用户仍需确认目标 Chat ID 准确性。
• 供应链风险：rr 二进制非官方 Beeper 产品，需关注上游仓库更新与安全公告，优先通过签名渠道安装。