Composio Beeper iMessage 本地二进制组件imessage-cli 的构建、授权与使用指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读imessage-cli是 Composio CLI 本地工具体系中负责读写 macOS 本地 iMessage 数据的原生二进制组件。它基于 Composio 对 Beeper platform-imessage 的 fork 构建以 stripped release 二进制形式随composio/cli-local-tools包分发供 Beeper iMessage 本地工具集beeper-imessage.ts在调用时通过运行时解析并执行。本文从 NOTICE.md 出发完整讲解该二进制的来源与版本、构建命令、依赖的 Swift 构建链路、权限模型以及它在 Composio 本地工具框架中的解析与执行机制帮助读者掌握从源码构建到实际调用的完整技术细节。组件概述一个随包分发的原生 CLI sidecarimessage-cli属于composio/cli-local-tools包中的本地工具二进制资产local tool binary assets。local-tools-binaries/README.md 明确指出该目录存放平台相关的可执行文件与动态库资产用于第一方本地工具集成和 CLI 原生 sidecar并强调不要提交生成的可执行文件许可证与 NOTICE 文档保留在 git 中源码通过ts/packages/cli-local-tools/vendor/下的 git submodule 固定版本二进制在 CLI 发布任务打包前重新生成。当前原生二进制来源有三个Beeper iMessagevendor/platform-imessageComposioHQ/platform-imessage forkPeekaboovendor/peekabooComposio native UI sidecar仓库内的 Swift packagets/packages/cli-local-tools/native/composio-native-uiLinux CLI 产物不包含这些原生 sidecarChrome DevTools 是基于 npm/npx 的集成也不使用该目录。也就是说imessage-cli是一个仅面向 macOS 的本地 sidecar这一点与 beeper-imessage.ts 中platforms: [darwin-arm64]的声明完全一致。来源、版本与许可证信息NOTICE.md 记录了该二进制组件的完整溯源信息项目值上游 forkComposioHQ/platform-imessage上游版本0.21.0上游 submodule commit364445a1b3089ad9fe293d5951efe160c5677c42许可证MIT上游仓库中的license.txt配套的 LICENSE.txt 展示了 MIT 许可证全文版权声明为 Copyright (c) 2020-2023 Texts.com, 2023- Automattic Inc说明该代码源出 BeeperTexts.com并被 Automattic 接管后由 Composio fork 维护。值得注意的是IMESSAGE_CLI_VERSION 0.21.0在 beeper-imessage.ts 中被硬编码为常量与 NOTICE.md 中的上游版本一致测试用例 beeper-imessage.test.ts 也断言version命令输出包含platform-imessage 0.21.0。这意味着版本号在编译期与运行期是双重固定的任何 fork 版本升级都需要同步更新 NOTICE、源码常量与测试断言三处。构建命令与 Swift 构建链路包级构建入口NOTICE.md 给出的构建命令是pnpm --filter composio/cli-local-tools build:beeper-imessage -- --target darwin-arm64|darwin-x64该脚本映射到 package.json 中的build:beeper-imessage: bun run ./scripts/build-beeper-imessage-binaries.ts即实际执行者是 build-beeper-imessage-binaries.ts一个 Bun 脚本。底层 Swift 构建命令NOTICE.md 记录了 underlying Swift 构建命令swift build -c release --product imessage-cli --arch arm64 swift build -c release --product imessage-cli --arch x86_64对照 build-beeper-imessage-binaries.ts仓库当前 targets 表只声明了darwin-arm64swiftArch: arm64产物路径.build/arm64-apple-macosx/release/imessage-cli。这与 NOTICE.md 中--target darwin-arm64|darwin-x64的说明存在差异——从源码结构看当前版本默认只构建并分发 arm64 一种架构x86_64 属于文档保留的历史/可选目标。因此在实际使用中应优先确认当前composio/cli-local-tools发布产物实际携带的架构。构建流程的四个关键阶段从 build-beeper-imessage-binaries.ts 的main()可以看出完整构建流水线平台校验ensurePlatform构建必须在 macOS 上进行且需要 Swift toolchain否则直接抛错——这是 macOS-only 组件的硬性前提。submodule 就绪ensureSubmodule若vendor/platform-imessage下没有Package.swift自动执行git submodule update --init --recursive -- ts/packages/cli-local-tools/vendor/platform-imessage。submodule 的 commit 由 git 固定保证可复现构建。BetterSwiftAX 补丁patchBetterSwiftAxForCurrentSdk这是最有意思的工程细节。构建会先swift package resolve然后对.build/checkouts/BetterSwiftAX/Sources/AccessibilityControl下的 7 个文件AccessibilityAction.swift、AccessibilityAttributeKey.swift、AccessibilityNotification.swift、AccessibilityParameterizedAttributeKey.swift、AccessibilityRole.swift、AccessibilitySubrole.swift、AccessibilityValue.swift做正则替换把kAX...形式的 Accessibility 常量引用改写为字符串字面量如AXRole。原因在脚本注释中说明BetterSwiftAX 0.1.0 引用的 Accessibility 常量在 GitHub runner 的 macOS SDK 上并非一致导出Swift 将 AX 常量暴露为不带k前缀和类别后缀的字符串因此需要在编译前把 resolved checkout 打上字面量补丁。编译与分发buildTarget/copyLicense/writeNotice执行swift build -c release --product imessage-cli --arch arch把产物复制到local-tools-binaries/beeper-imessage/platform/imessage-cli并chmod 755同时把上游 license 复制为LICENSE.txt最后由脚本自动生成 NOTICE.md——也就是说我们正在阅读的这份 NOTICE 本身就是构建产物的一部分其内容版本号、commit、许可证声明会在每次构建时被重新写入保持与 submodule 状态严格同步。可复现性设计writeNotice从 submodule 实时读取package.json的 version 与git rev-parse HEAD的 commit写入 NOTICE.md。这保证了只要 submodule 指针不变构建出的二进制与 NOTICE 声明就一一对应。这也是该组件可追溯性的核心——0.21.0 commit364445a1...是定位任何问题、核对二进制来源的唯一指纹。二进制的运行时解析与执行NOTICE.md 只负责声明来源与构建信息真正让imessage-cli跑起来的是composio/cli-local-tools的运行时层。理解这一层才能完整回答这个二进制在 Agent 场景中如何被调用。工具集的二进制声明在 beeper-imessage.ts 中工具集声明了 bundled binarybundledBinaries: [ { id: beeper-imessage-cli, description: Beeper platform-imessage imessage-cli 0.21.0., targets: [ { platforms: [darwin-arm64], path: beeper-imessage/darwin-arm64/imessage-cli }, ], }, ],二进制 idbeeper-imessage-cli与local-tools-binaries/beeper-imessage/目录对应。工具执行时runtime.ts 中的commandValueToInvocation会调用resolveBundledBinary解析实际路径。解析顺序与兜底机制bundled-binaries.ts的resolveBundledBinary遵循如下解析顺序在getLocalToolsBundleRootCandidates()返回的候选目录中查找目标平台路径支持通过COMPOSIO_LOCAL_TOOLS_BIN_DIR环境变量覆盖或从 CLI JS 所在目录、包根目录、独立 Bun 可执行文件旁查找。若未找到且处于 standalone Bun 可执行场景尝试从 GitHub Release 资产composio-darwin-*.zip下载并校验 SHA-256 checksum 后安全解压extractZipSafely负责防范 zip slip 类路径穿越见 extract-zip-safely.ts。若声明了fallbackCommand且其包含路径分隔符且存在则使用 fallback。全部失败则返回exists: false由上层报错。对 Beeper iMessage 而言beeper-imessage.ts 中的执行描述为command: { bundledBinary: IMESSAGE_CLI_BINARY_ID, // beeper-imessage-cli fallbackCommand: imessage-cli, // PATH 中的同名命令 },即优先使用随包分发的二进制如果解析失败且用户自行在 PATH 中安装了imessage-cli则回退到系统命令。工具集 setup 中还提供了显式覆盖方式composio local-tools configure BEEPER_IMESSAGE --command /path/to/imessage-cli或编辑~/composio/local_tools.json。调用与输出解析runtime.ts中runLocalCommand负责实际的 spawn 执行。每个工具调用都附加了全局参数buildGlobalArgs见 beeper-imessage.ts--data-dir可选状态目录默认临时目录、--no-use-secondary-instance当useSecondaryInstancefalse时、--no-events本地工具是一次性调用默认不保持 DB 事件监听、--verbose。CLI 输出采用[callId] ok commandName (durationms) JSON 的格式由parseImessageCliOutputbeeper-imessage.ts解析正则匹配成功行、剥离 ANSI 转义、提取 callId 与 durationMs并把后续 stdout 尝试按 JSON 解析为结构化结果。该解析逻辑与 upstream imessage-cli 的输出协议强耦合属于本地工具框架中的命令适配层。权限模型macOS 系统权限依赖NOTICE.md 最后一段明确指出二进制为 stripped release 构建需要访问本地 macOS Messages 数据并且根据命令不同可能弹出 Messages Data、Accessibility、Contacts、Automation 等权限请求。源码实现 中对此有更细化的说明只读工具列会话、读消息等需要Messages Data权限变更类工具发送、回复、删除等需要Messages Data Accessibility部分设置流程还可能需要Contacts或Automation权限授权入口是LOCAL_BEEPER_IMESSAGE_AUTHORIZE对应imessage-cli authorize可选目标为all | accessibility | contacts | messages-data | automation默认all它会打开 macOS 系统提示或系统设置页面是本地侧对接链接/授权 iMessage 工具集的方式未来的本地工具授权抽象计划将其路由到composio link BEEPER_IMESSAGE实例策略大多数读/发工具使用 secondary Messages.app 实例useSecondaryInstance默认true而 Reaction表情回应类工具默认使用 primary 实例因为上游 UI 自动化需要可见的 transcript 视图工具会先执行select-thread准备 transcript 再执行react/unreact。这一点在工具参数 schema 中也有印证baseInputbeeper-imessage.ts默认useSecondaryInstance: true而primaryInstanceInput第 38-45 行默认false并专门用于 reaction 类工具。工具能力清单这个二进制支撑了哪些 Agent 能力综合 beeper-imessage.tsimessage-cli支撑的本地工具集BEEPER_IMESSAGE包含以下能力维度系统与授权类VERSION打印 bundled CLI 版本不触碰 Messages.appAUTHORIZE检查/请求四种系统权限CURRENT_USER返回本机 iMessage 身份需要 Messages Data。查询类只读LIST_THREADS从本地 Messages 数据库列出普通收件箱会话默认 compact 输出并带pageInfo.nextBefore分页游标compactfalse返回上游原始输出includeRaw可在 compact 下附带原始页FIND_THREAD按联系人姓名、电话/邮箱、会话标题或参与者查找会话支持recipients必须同时存在的收件人集合与maxPages默认 10 页、上限 50 页每页 25 条GET_THREAD/LIST_MESSAGES/GET_MESSAGE单会话/消息获取支持before/after游标二者互斥SEARCH_MESSAGES文本搜索本地消息默认还扫描会话参与者与通讯录姓名如搜 Nikos 能命中对应会话。变更类写入真实 Messages 状态CREATE_THREAD_AND_SEND/SEND_MESSAGE建会话并发送/向已有会话发送文本REPLY_TO_MESSAGE/SEND_FILE/REPLY_WITH_FILE回复与文件附件EDIT_MESSAGE/UNDO_SEND编辑/撤销发送上游支持 macOS Ventura 及以上REACT_TO_MESSAGE/UNREACT_FROM_MESSAGE标准表情回应heart|like|dislike|laugh|emphasize|questionMARK_READ/MARK_UNREAD/MUTE_THREAD/UNMUTE_THREAD会话状态管理SEND_TYPING_STATUS/NOTIFY_ANYWAY/DELETE_THREAD输入状态、notify-anyway 与删除删除要求confirm: true。值得单独强调的是发送验证机制sendVerificationSEND_MESSAGE会先读取当前消息页作为排除集发送命令成功后再以 500ms 间隔轮询本地 Messages 数据库默认超时 8 秒、上限 30 秒直到观察到与发送文本匹配的新消息返回sentMessage/sentMessageId与sendVerification.status取值observed_sent_message、command_succeeded_but_sent_message_not_observed_yet、not_requested。这个设计让 Agent 不必因为会话预览未刷新就盲目重试直接解决了发了但不确定是否成功的经典痛点beeper-imessage.ts。此外resolveContactNames默认 true会在 compact 输出中通过osascript调用 macOS Contacts 应用做通讯录名称解析把会话参与者的电话/邮箱映射为人名标签搜索时也能用姓名匹配会话beeper-imessage.ts。测试与验证方式仓库为这套工具集提供了两层验证Schema 级单元测试beeper-imessage.test.ts断言工具集暴露LIST_THREADS、FIND_THREAD、SEND_MESSAGE、AUTHORIZE等 slug并验证LOCAL_BEEPER_IMESSAGE_SEND_MESSAGE的 schema 含threadId/text/verifySent属性、LIST_THREADS含compact/resolveContactNames、REACT_TO_MESSAGE含prepareTranscript。真实二进制集成测试同一文件第 25-38 行仅在COMPOSIO_REAL_LOCAL_TOOLS_TESTS1且平台为 darwin 时运行——解析 bundled 二进制并确认存在然后执行LOCAL_BEEPER_IMESSAGE_VERSION并断言输出包含platform-imessage 0.21.0。这个测试直接验证了NOTICE 声明版本 源码常量版本 实际二进制输出版本三者一致。使用前提与注意事项综合 NOTICE.md、local-tools-binaries/README.md 与源码声明实际使用该组件需要满足平台macOSdarwin-arm64Linux/Windows 无法使用构建额外要求 macOS Swift toolchain数据本机 Messages.app 已配置 iMessage 并登录权限按工具类别授予 Messages Data只读/ Accessibility变更/ Contacts、Automation按需通过AUTHORIZE或imessage-cli authorize触发版本一致性二进制版本固定为 0.21.0submodule commit364445a1...升级 fork 需要同步更新 NOTICE、源码版本常量与测试断言只读仓库约束当前仓库不提交生成的可执行文件二进制由 CLI 发布任务在打包前重新生成开发者本地如需体验可按照上文构建命令自行产出或使用composio local-tools configure指向自建的imessage-cli。总结imessage-cli是 Composio 将真实世界通信能力接入 Agent 的关键一环它通过 submodule 固定上游源码、以 Swift 构建脚本产出 stripped 二进制、以 NOTICE LICENSE 保证可追溯与合规、以 bundled-binary 解析层实现随包分发与兜底回退、以 macOS 权限模型约束读写边界最终以 20 个本地工具的形式让 Agent 能够在授权范围内读写真实 iMessage 数据。理解这份 NOTICE 背后的工程链路也就理解了 Composio本地工具 sidecar这一类组件的完整生命周期——从 fork、构建、分发到运行时解析与权限授权。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考