Roadrunner

核心功能

roadrunner（简称 rr）是面向 Beeper Desktop 的本地 API 命令行客户端，允许用户在不离开终端的情况下完成聊天管理、消息操作、全局搜索和提醒设置。它通过本地 HTTP 接口与 Beeper Desktop 通信，所有数据流均停留在本地网络层。

主要优势

• 完整的 chat ops 覆盖：支持聊天列表、消息收发、联系人解析、附件上传下载、草稿聚焦等高频操作
• 安全的 agent 模式：--agent 强制启用 JSON 输出、信封错误、无交互、只读，降低自动化风险
• 细粒度权限控制：--readonly、--enable-commands 允许白名单式命令限制，防止误操作
• 可靠的错误处理：--envelope 返回结构化错误，含 error.hint 指引重试策略
• 防重复提交：--request-id 与 --dedupe-window 为幂等性操作提供保障

局限性与风险

• 依赖 Beeper Desktop：必须保持桌面客户端运行，无法独立工作
• 认证令牌管理：需手动从 Beeper 设置提取 token，存在本地存储风险（~/.config/beeper/config.json）
• 命令注入隐患：消息内容若直接拼接到 shell 命令，可能触发 $ 变量扩展或 ! 历史展开
• 搜索语义限制：消息搜索为字面词匹配，非语义/向量搜索
• ID 管理复杂：Matrix chat ID 格式（!chatid:beeper.com）对人类不友好，易出错

适用人群

• 需要批量导出聊天记录或附件的高级用户
• 开发自动化工作流（如消息监控、定时提醒）的技术用户
• 偏好终端操作、追求效率的 Beeper 重度用户

安全建议

始终优先使用 --stdin 方式传入敏感数据，避免在 shell history 中留下 token；发送消息时使用 heredoc 或 --stdin 绕过 shell 转义；生产自动化建议组合 --agent --readonly --enable-commands 构建最小权限沙盒。

核心功能

roadrunner（简称 rr）是 Beeper Desktop 的官方命令行工具，提供对本地 Beeper API 的完整访问能力。核心能力包括：

• 聊天管理：列出、搜索、创建聊天，支持按参与者、时间、未读状态筛选
• 消息操作：发送、编辑、搜索消息，支持附件上传下载，可轮询实时消息流
• 全局搜索：跨所有聊天记录的全文检索，支持分页和高级过滤
• 提醒与草稿：设置聊天提醒、预填草稿消息并附加文件
• 多账户支持：管理多个 Beeper 账户，支持账户别名和默认账户切换

显著优点

1. 功能完整：覆盖 Beeper Desktop 绝大部分核心功能，替代 GUI 操作的高效方式
2. 安全设计：提供 --readonly、--agent、--enable-commands 等沙箱机制，防止误操作
3. 结构化输出：原生支持 --json 输出，配合 --envelope 错误包装，便于自动化集成
4. 幂等性保障：支持 --request-id 和 --dedupe-window 防止重复写入
5. 灵活认证：支持 stdin 安全输入 token，配置文件隔离，环境变量覆盖

潜在局限

• 依赖本地 Beeper Desktop：必须保持桌面应用运行，无法独立使用
• 搜索语义有限：消息搜索为字面词匹配，不支持语义或模糊搜索
• 个人开发者维护：非官方组织账号，长期维护稳定性存疑
• 生态较新：GitHub Stars 仅 5 个，社区验证和最佳实践积累有限

适合人群

• 需要自动化 Beeper 工作流的高级用户（如定时消息、批量归档）
• 开发集成 Beeper 消息能力的第三方工具开发者
• 偏好 CLI 效率、需脚本化消息管理的极客用户
• 在 headless 环境或远程服务器管理 Beeper 的技术运维人员

常规风险

• token 泄露风险：认证令牌存储于本地配置文件，需确保 ~/.config/beeper/config.json 权限正确（建议 600）
• shell 注入风险：消息内容若包含 $、! 等特殊字符，需使用 --stdin <<'EOF' 语法避免插值
• 误发送风险：--no-input 模式下 destructive 操作需配合 --force，否则可能阻塞或失败
• 历史扩展冲突：bash/zsh 中 ! 触发历史扩展，建议用单引号或禁用该特性