Roadrunner

核心用法

roadrunner（rr）是 Beeper Desktop 的命令行接口，允许用户在不打开 GUI 的情况下完成聊天操作、消息管理、联系人搜索与提醒设置。核心工作流围绕「认证 → 查询 → 操作」展开：首次使用需通过 rr auth set <token> 配置 Beeper 令牌，随后即可调用 rr chats list、rr messages send、rr search 等子命令完成操作。工具支持 JSON 输出（--json）、结构化错误包装（--envelope）和只读模式（--readonly），便于脚本集成与自动化场景。

显著优点

• 功能覆盖面广：涵盖聊天列表、消息收发、附件上传下载、全局搜索、提醒设置等 20+ 操作场景
• 自动化友好：--agent 模式专为 AI agent 设计，强制 JSON 输出、禁用交互、提供错误封装；--enable-commands 允许细粒度权限控制
• 安全设计：--readonly 完全阻止写操作，--force 与 --no-input 组合防止意外破坏性操作，历史命令中的 ! 字符也有明确风险提示
• 分页与流式：支持 --all 自动分页、 --tail 轮询监听、--wait 条件阻塞，满足批处理与实时性需求

潜在缺点与局限

• 依赖 Beeper Desktop：必须保持桌面客户端运行，CLI 本身不独立连接云端，这限制了纯服务器/无头环境的使用
• Token 管理负担：需手动从 Beeper 设置中提取令牌，且存储在本地明文 JSON，多设备同步或 CI 场景下需额外安全管控
• 搜索语义局限：消息搜索为字面词匹配，非语义/向量检索；联系人 resolve 对模糊名称严格失败，需先 search 再 resolve
• 生态成熟度：由个人开发者维护（johntheyoung），非 Beeper 官方项目，长期维护与兼容性存在不确定性

适合人群

• Beeper 重度用户，希望用键盘工作流替代 GUI 操作
• 需要批量导出聊天记录、自动化消息发送的开发者/运营人员
• 构建 Beeper 集成 bot 或内部工具的工程师
• 熟悉 CLI 与 JSON 处理、具备基本 Matrix/Beeper 概念的技术用户

常规风险

• 认证凭证泄露：BEEPER_TOKEN 拥有完整账号权限，环境变量或配置文件泄露将导致消息被读取/发送、附件被下载
• 消息误发风险：CLI 无二次确认（除非未指定 --force），脚本错误或参数错位可能导致消息发往错误聊天
• 本地文件权限：~/.config/beeper/config.json 及下载的附件目录需严格限制访问权限
• API 变更兼容：Beeper Desktop 的本地 API 非公开契约，版本升级可能破坏 CLI 功能

核心用法

roadrunner（rr）是 Beeper Desktop 的官方命令行接口，提供对聊天应用的全功能程序化控制。该 Skill 为纯文档型包装器，整理并规范了 rr 工具的核心命令集，涵盖四大能力域：

1. 账户与联系人管理

• rr accounts list 查看多账户状态
• rr contacts search/resolve 搜索并解析联系人 ID
• 支持账户别名设置，便于多账户切换

2. 聊天操作

• rr chats list/search 列出或搜索聊天会话
• rr chats create 创建单聊或群组（支持预设标题和欢迎消息）
• rr chats archive 归档/取消归档会话
• 支持按未读状态、活动时段、参与者等维度过滤

3. 消息全生命周期

• rr messages list/search 浏览和搜索历史消息
• rr messages send 发送文本、回复、附件（支持上传 ID 或文件路径）
• rr messages send-file 一键上传并发送文件
• rr messages edit 编辑已发送消息
• rr messages tail/wait 实时监听新消息或等待特定内容
• 支持草稿预填（rr focus --draft-text）

4. 高级功能

• 全局搜索（rr search）跨会话检索
• 提醒设置（rr reminders set/clear）
• 附件管理（上传、下载、流式读取）
• 未读汇总与状态监控

显著优点

• 功能完备：覆盖 Beeper Desktop 本地 API 的完整能力，是官方 CLI 的标准化封装
• Agent 友好：内置 --agent 模式，强制 JSON 输出、信封错误结构、无交互式输入，专为自动化场景设计
• 安全控制丰富：支持 --readonly 只读锁定、--enable-commands 命令白名单、--force/--no-input 防误触机制
• 多格式输出：JSON（推荐自动化）、Plain（人工阅读）、Envelope（结构化错误）灵活切换
• 分页与流控：自动分页（--all）、游标导航、安全上限（默认 500，最大 5000）防止资源耗尽
• 跨平台安装：Homebrew 和 Go 两种官方安装渠道

潜在缺点与局限性

• 外部依赖硬性要求：必须本地运行 Beeper Desktop 并获取有效 Token，无独立运行能力
• 配置门槛：需手动设置 BEEPER_TOKEN 等环境变量或配置文件，首次配置较繁琐
• 搜索语义限制：消息搜索为字面匹配，不支持语义/模糊搜索
• ID 操作复杂度：Matrix 格式的 chat ID（如 !chatid:beeper.com）和 message ID 对用户不友好，常需先搜索再解析
• Bash 兼容性注意：ID 中的 ! 会触发历史扩展，需用单引号包裹或关闭 shell 历史扩展
• 个人维护风险：T2 级别来源（个人开发者），长期维护稳定性低于企业级项目

适合人群

• 自动化工作流开发者：需将 Beeper 聊天集成到 CI/CD、运维告警、客服系统的工程师
• 多账户管理员：同时管理多个 Beeper 账户（iMessage、Slack、WhatsApp 等聚合）的高级用户
• 消息归档与审计需求：需批量导出聊天记录、媒体附件的企业合规场景
• ChatOps 实践者：希望在终端/编辑器中完成消息收发而不切换 GUI 的效率用户

常规风险

• Token 泄露风险：BEEPER_TOKEN 拥有完整账户权限，存储于 ~/.config/beeper/config.json 需确保文件权限 600
• 误操作风险：messages send/edit 等命令无二次确认（除非省略 --force），脚本中建议显式校验 recipient
• API 变更风险：Beeper Desktop 本地 API 非公开稳定接口，升级客户端可能导致 CLI 失效
• 消息合规风险：自动化发送可能违反平台反垃圾策略或企业通讯合规要求
• Shell 注入风险：命令拼接时若未正确处理含空格或特殊字符的聊天标题/消息内容，可能导致参数解析异常