Composio CLI 本地工具二进制资产（local-tools-binaries）构建与交付指南

Composio CLI 本地工具二进制资产（local-tools-binaries）构建与交付指南

【免费下载链接】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

Composio CLI 在提供本地化 AI Agent 工具能力时，需要随 CLI 一起分发平台相关的可执行文件与动态库（sidecar）。ts/packages/cli-local-tools/local-tools-binaries/正是这类"本地工具二进制资产"的构建产物目录：它在本地工具二进制构建期间生成，服务于 Beeper iMessage、Peekaboo（macOS GUI 自动化）以及 Composio 原生 UI sidecar 等第一方本地工具集成。读完本文，你将掌握该目录的职责边界、三类原生二进制的上游来源与构建命令、平台覆盖策略，以及源码中二进制解析与自修复的运行机制，能够独立完成本地工具二进制的构建与排查。

目录职责：可执行文件与动态库的统一落点

ts/packages/cli-local-tools/local-tools-binaries/README.md开篇即明确了该目录的定位：平台特定的可执行文件和动态库资产（platform-specific executable and dynamic-library assets），用于两类消费方：

• 第一方本地工具集成（first-party local tool integrations）：例如 Peekaboo CLI、imessage-cli 这类由 CLI 封装的本地命令工具；
• CLI 原生 sidecar（CLI native sidecars）：例如 Composio 原生 UI 辅助进程，由 Bun 编译出的 Composio CLI 在需要时拉起，承担认证流程、工具选择器等桌面交互。

这些资产不随源码提交，而是在build:local-tool-binaries构建任务中动态生成。目录在仓库中的实际形态也印证了这一点：当前保留在 git 中的只有各产物的LICENSE.txt与NOTICE.md（如 beeper-imessage/NOTICE.md、peekaboo/NOTICE.md、composio-native-ui/NOTICE.md），而实际的.zip/可执行文件在构建与发布流程中才被生成。

该目录会随 npm 包一起发布：在 ts/packages/cli-local-tools/package.json 的files字段中，dist与local-tools-binaries被显式声明为发布内容，说明消费方（如通过 npm 安装该包的其他模块）可以依赖此目录中的资产存在。

版本与来源管理：源码固定、许可留存、产物不提交

README 明确给出三条工程规范，这也是本地二进制供应链管理的核心：

1. 不提交生成的可执行文件（Do not commit generated executables）——产物体积大且可重建，入库会造成仓库膨胀与漂移；
2. 许可与通知文件保留在 git 中（Keep notices/licenses in git）——每个产物的NOTICE.md记录了上游版本、固定 commit、构建命令与许可信息，保证合规可追溯；
3. 源码以 git submodule 固定（pin source with git submodules）——上游源码固定到具体 commit，而不是浮动跟随上游主线；在 CLI 发布任务（CLI release jobs）中，打包产物前重新生成二进制（regenerate binaries before packaging artifacts）。

以 Beeper iMessage 为例，beeper-imessage/NOTICE.md 记录了完整溯源链：二进制来自 Composio 对 Beeper platform-imessage 的 fork（ComposioHQ/platform-imessage），上游版本0.21.0，固定 submodule commit364445a1b3089ad9fe293d5951efe160c5677c42，许可为 MIT。Peekaboo 的 peekaboo/NOTICE.md 同样固定了上游版本3.0.0-beta4与 submodule commit31e66e8d02656141d18f60bf3b46b24c2b9bc785。

三类原生二进制来源

README 列出了当前（current）的三类原生二进制来源：

Beeper iMessage：vendor/platform-imessage

iMessage 本地工具依赖 Beeper 的imessage-cli（Composio fork 构建）。从 src/toolkits/beeper-imessage.ts 源码可见，工具声明中固定了IMESSAGE_CLI_BINARY_ID = 'beeper-imessage-cli'与IMESSAGE_CLI_VERSION = '0.21.0'，并定义了dataDir、useSecondaryInstance、verbose等基础输入参数。其 NOTICE 指出，imessage-cli为 macOS arm64/x64 的 stripped release 构建，运行时可能请求 Messages Data、Accessibility、Contacts、Automation 等系统权限。

Peekaboo：vendor/peekaboo

Peekaboo 提供 macOS 屏幕捕获与 GUI 自动化能力。在 src/toolkits/peekaboo.ts 中，工具集peekabooToolkit声明了bundledBinaries：id 为peekaboo-cli，目标路径为peekaboo/darwin-arm64/peekaboo，仅支持darwin-arm64平台，并附带fallbackCommand: 'peekaboo'（即系统 PATH 中缺失内置二进制时的回退命令）。其setup.install明确要求 macOS 15+、Screen Recording（截屏/读取类工具）与 Accessibility（点击/输入/窗口/菜单自动化）权限。

Composio 原生 UI sidecar：native/composio-native-ui

与前两者不同，这是仓库内自带的 Swift package，位于 ts/packages/cli-local-tools/native/composio-native-ui/。其 Package.swift 使用swift-tools-version: 6.0，平台下限为 macOS 13，产物为名为composio-native-ui的可执行文件。根据 composio-native-ui/NOTICE.md，该 sidecar 是 Bun 编译出的 Composio CLI 在认证流程、工具选择器等桌面场景下拉起的原生 macOS UI 表面（当前脚手架实现为在活动屏幕右下角打开一个小型 AppKit 面板）。

构建命令与 target 参数详解

README 给出的两条 macOS sidecar 构建命令：

pnpm --filter @composio/cli-local-tools build:local-tool-binaries -- --target darwin-arm64 pnpm --filter @composio/cli-local-tools build:local-tool-binaries -- --target darwin-x64

入口脚本是 ts/packages/cli-local-tools/scripts/build-local-tool-binaries.ts，其内部逻辑值得展开：

target 别名归一化。脚本内置了一张别名表，将bun-darwin-arm64、composio-darwin-aarch64、darwin-aarch64等历史/变体命名统一归一为darwin-arm64，Linux 侧同理支持linux-x64、linux-arm64（含bun-linux-*、composio-linux-*前缀）。归一后的目标通过--target <name>传入；若不传，则依据当前宿主自动探测（macOS arm64 →darwin-arm64，macOS x64 →darwin-x64，Linux 同理）。例如：

pnpm --filter @composio/cli-local-tools build:local-tool-binaries -- --target darwin-arm64 pnpm --filter @composio/cli-local-tools build:local-tool-binaries -- --target composio-linux-x64

平台门槛与跳过策略。脚本对非darwin-*目标直接跳过（打印 "Skipping native local-tool binary build for non-macOS target"）；对darwin-x64也明确跳过（"unsupported target"）；若目标为 darwin 但当前宿主不是 macOS，则抛错——因为构建 Swift sidecar 必须运行在带 Swift 工具链的 macOS runner 上。这就是 README 中"Linux CLI artifacts 跳过原生 sidecars"的源码级体现。

三个子构建依次执行。构建逻辑按顺序委托给三个脚本（对应 package.json 中的脚本别名）：

注：README 与 NOTICE 中的 build 命令展示了基于 Bun 的bun run ./scripts/...实现（package.json 中build:beeper-imessage等即为bun run ./scripts/build-*-binaries.ts），而pnpm --filter @composio/cli-local-tools build:local-tool-binaries是 pnpm workspace 下的统一入口，二者最终走同一套脚本。

运行时如何解析这些二进制资产

构建产物最终要被 CLI 运行时找到并执行。解析逻辑集中在 src/bundled-binaries.ts：

候选根目录（bundle root）探测。getLocalToolsBundleRootCandidates()依次检查：

1. 环境变量COMPOSIO_LOCAL_TOOLS_BIN_DIR（显式指定，优先级最高）；
2. 模块目录下的local-tools-binaries/（Bundled CLI JS / 解包后的 CLI sidecar 位置）；
3. 包根目录下的local-tools-binaries/（@composio/cli-local-tools作为普通依赖、JS 位于dist/时的布局）；
4. process.execPath所在目录下的local-tools-binaries/（独立 Bun 可执行文件 zip/install 布局，资产与编译产物同目录）。

平台匹配。工具声明通过 src/types.ts 中的LocalBundledBinaryDeclaration（含id、targets）与LocalBundledBinaryTarget（含platforms、相对 bundle root 的path、executable标记）描述资产；src/platform.ts 的detectCliPlatform()将process.platform+process.arch归一为darwin-arm64、darwin-x64、linux-arm64、linux-x64、win32-*等LocalCliPlatform值，supportsCliPlatform()再做家族级兼容判断（如darwin匹配所有 darwin 变体）。

解析优先级与自修复。resolveBundledBinary()的查找顺序为：

1. 在候选根目录中寻找与当前平台匹配的二进制，命中即返回（source: 'bundled'）；
2. 若均未命中且满足条件（独立 Bun 可执行文件且未显式设置COMPOSIO_LOCAL_TOOLS_BIN_DIR），触发安装后自修复：读取安装目录下的release-tag.txt（或环境变量GITHUB_TAG），从 GitHub Releases 下载与当前平台对应的资产包（如composio-darwin-aarch64.zip），并：
   • 通过checksums.txt中的 SHA-256 对下载内容做校验（verifyChecksum）；
   • 使用extractZipSafely安全解压（该模块另有 extract-zip-safely.ts 与 zip-fixtures 中的 symlink 攻击测试用例，防止 zip-slip 类路径逃逸）；
   • 将解压产物原子替换到安装目录，随后重试解析；
3. 若内置二进制缺失，且声明提供了fallbackCommand（如 Peekaboo 的peekaboo）且该命令存在，则回退到 PATH 命令（source: 'fallback'）。

在 src/runtime.ts 的commandValueToInvocation()中，LocalBundledBinaryRef会被解析为实际命令路径，解析到的内置二进制还会经ensureBundledBinaryExecutable()（src/bundled-binaries.ts）补充可执行权限位（非 Windows 平台，缺失则补0o755）。最终，本地工具以LOCAL_前缀的 slug 注册进自定义工具集（见 src/registry.ts 的LOCAL_TOOL_PREFIX与localToolkitDeclarations，内置三个工具集：beeper-imessage、chrome-devtools、peekaboo）。

平台覆盖与边界

README 明确了两条边界，与源码行为一一对应：

• Linux CLI 产物不包含原生 sidecar：build-local-tool-binaries.ts对非darwin-*目标直接跳过；Peekaboo 工具声明也仅标注platforms: ['darwin-arm64']。因此 Linux 上的composio local-tools类能力不会依赖本目录中的原生二进制。
• Chrome DevTools 不经过本目录：它是基于 npm/npx 的集成（chrome-devtools-mcp出现在 package.json 的 devDependencies 中，工具声明见 src/toolkits/chrome-devtools.ts），通过 MCP 服务器方式运行，因此无需平台可执行文件资产。

此外从源码推断，darwin-x64 目前在统一构建入口中也被显式跳过（尽管 NOTICE 保留了 x86_64 的 Swift 构建说明），实际交付面以 darwin-arm64 为主；具体支持的组合以各工具声明的platforms字段为准，运行时可通过supportsCliPlatform校验（不支持的平台上调用会抛出带支持平台清单的错误，见 src/registry.ts 的executeLocalToolBySlug）。

验证与测试

仓库为这套机制配备了完整测试，可作为构建/接入后的验证手段：

• src/bundled-binaries.test.ts：覆盖 bundle root 候选探测、平台匹配、fallback 与自修复路径的解析逻辑；
• src/registry.test.ts：验证工具集过滤、slug 归一化与平台支持判定；
• src/toolkits/peekaboo.test.ts 与 src/toolkits/beeper-imessage.test.ts：对 CLI 参数组装、输出解析做断言；
• src/extract-zip-safely.test.ts：配合 zip-fixtures 中的benign.zip、symlink-absolute.zip、symlink-relative.zip，验证自修复解压环节对符号链接逃逸的防护。

在包根目录运行pnpm --filter @composio/cli-local-tools test（vitest）即可执行上述全部测试；pnpm --filter @composio/cli-local-tools typecheck可做类型级校验。

小结

local-tools-binaries目录是 Composio CLI 本地工具能力的二进制交付中枢：源码以 submodule 固定、许可文档入库、生成产物在发布任务中重建，构成了可追溯的供应链管理闭环；构建入口通过 target 别名与平台门槛统一了三类 macOS sidecar 的产出；运行时则通过 bundle-root 探测、平台匹配、GitHub Release 自修复与安全解压，确保产物在安装后始终可用。理解这一目录，就等于理解了 Composio 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