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/composioComposio CLI 在提供本地化 AI Agent 工具能力时需要随 CLI 一起分发平台相关的可执行文件与动态库sidecar。ts/packages/cli-local-tools/local-tools-binaries/正是这类本地工具二进制资产的构建产物目录它在本地工具二进制构建期间生成服务于 Beeper iMessage、PeekaboomacOS 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 原生 sidecarCLI 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 明确给出三条工程规范这也是本地二进制供应链管理的核心不提交生成的可执行文件Do not commit generated executables——产物体积大且可重建入库会造成仓库膨胀与漂移许可与通知文件保留在 git 中Keep notices/licenses in git——每个产物的NOTICE.md记录了上游版本、固定 commit、构建命令与许可信息保证合规可追溯源码以 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 的 forkComposioHQ/platform-imessage上游版本0.21.0固定 submodule commit364445a1b3089ad9fe293d5951efe160c5677c42许可为 MIT。Peekaboo 的 peekaboo/NOTICE.md 同样固定了上游版本3.0.0-beta4与 submodule commit31e66e8d02656141d18f60bf3b46b24c2b9bc785。三类原生二进制来源README 列出了当前current的三类原生二进制来源Beeper iMessagevendor/platform-imessageiMessage 本地工具依赖 Beeper 的imessage-cliComposio 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 等系统权限。Peekaboovendor/peekabooPeekaboo 提供 macOS 屏幕捕获与 GUI 自动化能力。在 src/toolkits/peekaboo.ts 中工具集peekabooToolkit声明了bundledBinariesid 为peekaboo-cli目标路径为peekaboo/darwin-arm64/peekaboo仅支持darwin-arm64平台并附带fallbackCommand: peekaboo即系统 PATH 中缺失内置二进制时的回退命令。其setup.install明确要求 macOS 15、Screen Recording截屏/读取类工具与 Accessibility点击/输入/窗口/菜单自动化权限。Composio 原生 UI sidecarnative/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-arm64Linux 侧同理支持linux-x64、linux-arm64含bun-linux-*、composio-linux-*前缀。归一后的目标通过--target name传入若不传则依据当前宿主自动探测macOS arm64 →darwin-arm64macOS x64 →darwin-x64Linux 同理。例如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 中的脚本别名子脚本底层构建说明build:beeper-imessage-binaries.tsswift build -c release --product imessage-cli --arch arm64/--arch x86_64构建 imessage-cli见 beeper-imessage/NOTICE.mdbuild:peekaboo-binaries.tsswift build --arch arm64\|x86_64 -c release -Xswiftc -Osize -Xswiftc -wmo -Xlinker -dead_strip自Apps/CLI目录构建 Peekaboo CLI带体积优化与 dead-strip 链接优化见 peekaboo/NOTICE.mdbuild:composio-native-ui-binaries.tsswift build -c release --product composio-native-ui --arch arm64/--arch x86_64构建仓库内 Swift 包见 composio-native-ui/NOTICE.md注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()依次检查环境变量COMPOSIO_LOCAL_TOOLS_BIN_DIR显式指定优先级最高模块目录下的local-tools-binaries/Bundled CLI JS / 解包后的 CLI sidecar 位置包根目录下的local-tools-binaries/composio/cli-local-tools作为普通依赖、JS 位于dist/时的布局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.platformprocess.arch归一为darwin-arm64、darwin-x64、linux-arm64、linux-x64、win32-*等LocalCliPlatform值supportsCliPlatform()再做家族级兼容判断如darwin匹配所有 darwin 变体。解析优先级与自修复。resolveBundledBinary()的查找顺序为在候选根目录中寻找与当前平台匹配的二进制命中即返回source: bundled若均未命中且满足条件独立 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 类路径逃逸将解压产物原子替换到安装目录随后重试解析若内置二进制缺失且声明提供了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 产物不包含原生 sidecarbuild-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 testvitest即可执行上述全部测试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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考