核心功能
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 构建最小权限沙盒。