Composio CLI Local Tools本地工具包架构与版本演进全解析【免费下载链接】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/composiooutput文章关于 composio/cli-local-toolscomposio/cli-local-tools是 Composio 仓库中一个专门承载「本地工具与本地工具包声明」的 TypeScript 包位于 ts/packages/cli-local-tools。它的定位与云端托管的工具不同它把运行在用户自己机器上macOS、Linux、Windows的 CLI 程序、原生二进制、MCP Server 和动态库统一声明为可被 AI Agent 调用的工具并把这些本地工具接入 Composio CLI 的 Tool Router 搜索与执行会话。从包描述Local tool and toolkit declarations for the Composio CLI.见 package.json可以看出这个包是 CLI 侧本地工具的声明层 执行层它既负责描述这个工具长什么样、支持哪些平台、如何被调用也负责真正把命令 spawn 出去、把 MCP Server 连起来、甚至通过 Bun FFI 加载原生动态库。本文将以该包的 CHANGELOG.md 为主线结合仓库源码梳理这个包从 0.0.2 到 0.1.0 的演进脉络深入解析其核心架构、四种执行模型、CLI 子命令与本地元数据机制。一、版本演进总览composio/cli-local-tools目前的版本历史非常短只有 5 个版本0.0.2 → 0.1.0但每个版本都承载着明确的架构决策。整体时间线如下版本变更类型核心内容0.0.2Minor首次落地本地工具基础框架接入 Tool Router新增 Beeper iMessage、Chrome DevTools、Peekaboo 三个本地工具包0.0.3Patch仅依赖升级composio/core0.9.10.0.4Patch仅依赖升级composio/core0.10.00.0.5Patch仅依赖升级composio/core0.11.00.1.0Minor破坏性变更全面迁移为 ESM-only移除 CommonJS 入口与.cjs产物要求 Node.js ≥ 22.22.3依赖升级至composio/core0.12.0从源码结构看该包的正式功能面在 0.0.2 一次成型后续 0.0.30.0.5 是跟随composio/core的依赖演进而 0.1.0 则是一次影响所有消费者的打包与运行时策略调整。下面逐一拆解。二、0.1.0ESM-only 破坏性迁移0.1.0 是当前最新版本也是唯一一次包含Minor Changes的破坏性变更Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x release line: consumers must use Node.js 22.22.3 or newer. CommonJS callers can only rely on Nodes nativerequire(esm)interop, and the SDK no longer ships custom CommonJS compatibility machinery or.cjsartifacts.这段描述包含三个关键决策ESM-only包不再提供 CommonJS 入口发布产物只含 ESM 模块。Node 版本门槛消费者必须使用 Node.js22.22.3 或更新版本才能获得完整的 ESM 支持与原生require(esm)互操作。移除 CJS 兼容机制不再内置自定义的 CommonJS 兼容层也不再发布.cjs产物。CommonJS 调用方只能依赖 Node 原生的require(esm)互操作能力。这一决策在 package.json 中有完整的落地证据{ name: composio/cli-local-tools, version: 0.1.0, type: module, main: dist/index.mjs, module: dist/index.mjs, types: dist/index.d.mts, exports: { .: { types: ./dist/index.d.mts, default: ./dist/index.mjs } }, files: [dist, local-tools-binaries] }可以看到type: module明确整个包按 ESM 语义解析入口统一为dist/index.mjsmain与module指向同一文件类型声明为.d.mtsfiles字段把dist与local-tools-binaries一起发布——后者就是随包分发的本地工具二进制目录。对消费方的影响对于通过包管理器安装该依赖的使用者0.1.0 之后需要注意若你的项目是 ESMtype: module或使用.mjs直接import即可若你的项目是 CommonJS不能再用require(composio/cli-local-tools)直接加载必须依赖 Node 22.22.3 的原生require(esm)互操作并且需要注意 ESM 的顶层语义如异步加载、无__dirname等对调用方式的影响从源码看包内部大量使用了node:前缀的 ESM 导入node:fs/promises、node:child_process、node:path等见 src/runtime.ts并对 MCP SDK 使用动态import()这些都依赖完整的 ESM 运行时。同时0.1.0 还同步更新了 8 组依赖提交552859a、a0bef5d、23f9053、dfd7a08、507318d、025a657、6a4cb54、4b76dbf、cbbad15将composio/core从 0.11.0 提升到0.12.0——这是它直接依赖的唯一运行时核心包另一个核心依赖是modelcontextprotocol/sdk用于 MCP 类本地工具的调用。三、0.0.2本地工具框架的诞生0.0.2 是这个包的「奠基版本」一条提交79ac220同时带入了四大能力Beeper iMessage 本地工具包可重建的 sidecar 二进制来自 ComposioHQ 的 platform-imessage 子模块并封装了更高层的包装器用于紧凑的会话发现、联系人感知的会话搜索、发送校验以及主实例反应reaction准备。Chrome DevTools 本地工具基于官方chrome-devtools-mcp包及其有状态的chrome-devtoolsCLI 守护进程的一等公民支持。本地工具基础包脚手架接入 Tool Router 的搜索/执行会话并对外暴露composio local-tools list|doctor|configure|meta四个子命令分别用于发现、就绪检查、设置提示与本地元数据状态。Peekaboo macOS 本地工具内置 darwin-arm64 的 Peekaboo CLI 二进制。这四条能力共同勾勒出这个包的完整功能面。下面结合源码逐一深入。3.1 内置的三个本地工具包在 src/registry.ts 中内置工具包被声明为一个明确的数组export const localToolkitDeclarations: ReadonlyArrayLocalToolkitDeclaration [ beeperImessageToolkit, chromeDevtoolsToolkit, peekabooToolkit, ];对应实现位于 src/toolkits/beeper-imessage.ts、src/toolkits/chrome-devtools.ts 与 src/toolkits/peekaboo.ts每个文件都配有同名的.test.ts测试。以 Beeper iMessage 为例beeper-imessage.ts 中可以看到典型的本地工具声明结构内置二进制标识beeper-imessage-cli版本锁定为0.21.0命令执行超时COMMAND_TIMEOUT_MS 120_000发送校验轮询间隔500ms、超时8s会话扫描默认最多翻页10页、上限50页使用 zod 定义输入参数dataDiriMessage CLI 状态目录默认临时目录、useSecondaryInstance默认使用次要 Messages.app 实例反应等 UI 相关工具默认切回主实例因为需要可见的会话视图、verbose是否开启详细日志输出统一封装为cliOutput结构ok、commandName、callId、durationMs、result、stdout、stderr。这些细节说明本地工具并非简单包一层命令而是带有完整的输入校验、超时控制、输出规整与平台差异化行为。3.2 平台声明与匹配本地工具天然与操作系统强绑定因此包内定义了细粒度的平台类型 src/platform.tsexport type LocalCliPlatform | all | darwin | linux | win32 | darwin-arm64 | darwin-x64 | linux-arm64 | linux-x64 | win32-arm64 | win32-x64;detectCliPlatform()根据process.platform与process.arch探测当前平台例如 darwin arm64 →darwin-arm64supportsCliPlatform()则判断某个工具的platforms声明是否覆盖当前平台——规则是声明包含all、包含精确平台或包含当前平台的家族平台如darwin可覆盖darwin-arm64。例如 Peekaboo 的声明只面向darwin-arm64因此在其他平台上运行composio local-tools doctor时该工具会被标记为unsupported。3.3 四种执行模型LocalToolDeclaration中最重要的字段是execution它决定了工具运行时如何被真正执行。根据 src/types.ts共支持四种kindkind执行方式典型场景command通过spawn启动本地命令CLI 程序、sidecar 二进制native在进程内执行 JS 函数需要精细控制或直接操作 Node API 的工具mcp通过 MCP SDK 连接 stdio MCP Server封装任意 MCP Server 的能力ffi通过 Bundlopen加载动态库直接调用.dylib/.so/.dllcommand子进程执行src/runtime.ts 中的runLocalCommand是 command 模型的核心实现使用node:child_process的spawn启动进程捕获 stdout/stderr支持stdin注入、cwd、环境变量合并{ ...process.env, ...invocation.env }支持timeoutMs超时超时后发送SIGTERM退出码非 0 时抛出包含 exitCode/signal/stderr 的详细错误parseJson为 true 时尝试把 stdout 按 JSON 解析失败则回退为原始文本。命令的解析支持静态值与函数值两种形式LocalCommandValue并且可以引用内置二进制LocalBundledBinaryRef——此时会先解析随包分发的二进制路径若不存在再回退到fallbackCommand如 PATH 中的命令。mcpMCP Server 桥接runLocalMcpTool动态导入modelcontextprotocol/sdk的Client与StdioClientTransport用spawn拉起server.command如chrome-devtools守护进程然后若声明了toolName调用client.callTool({ name, arguments })并返回结构化结果若未声明toolName则返回listTools()的结果——此时该本地工具本身就是一个MCP 工具发现器。finally块中总会尝试client.close()保证 MCP 连接被及时释放。ffiBun 动态库调用runLocalFfiTool使用bun:ffi的dlopen加载动态库库路径可以是绝对路径也可以是LocalBundledBinaryRef先解析随包二进制再回退到fallbackCommand符号声明LocalFfiSymbolDeclaration把LocalFfiTypechar/i8/u32/i64/f32/ptr/cstring/void等 17 种映射为 Bun 的FFIType重要限制该执行模型要求运行在 Bun 运行时中源码会显式检查globalThis.Bun否则抛错 Local FFI execution requires the Bun runtime used by the packaged Composio CLI.。native进程内函数LocalNativeExecution直接提供execute(input, context)函数并可选携带readiness前置命令供composio local-tools doctor做就绪检查。它是四种模型里最灵活、也最接近普通 SDK 工具的一种。3.4 slug 归一化与 Tool Router 接入本地工具接入 Tool Router 的核心机制在 src/registry.ts所有本地工具统一使用LOCAL_前缀slug 通过normalizeLocalToolSlug归一化LOCAL_${TOOLKIT}_${TOOL}其中非字母数字字符替换为下划线、整体转大写createLocalToolRouterExperimentalPayload把声明的本地工具包转换为 Tool Router 的 experimental payload 结构custom_toolkits其中每个工具都携带slug、name、description、input_schema与可选的output_schemaresolveLocalTool支持三种 slug 匹配方式完整归一化 slug、纯工具 slug、toolkit_tool组合并返回supported布尔值与最终 slugexecuteLocalToolBySlug提供按 slug 直接执行的入口执行前会用inputParams.safeParse做参数校验失败时给出字段级错误信息。同时工具/工具包的描述会被自动追加平台说明Local CLI platforms: darwin-arm64.这种描述注入平台信息的做法让 Agent 在收到工具描述时就能立刻判断当前平台是否可用。四、composio local-tools四个子命令背后的机制0.0.2 的 CHANGELOG 明确提到了composio local-tools list|doctor|configure|meta四个子命令。虽然命令本身在 CLI 包中实现但本包为它们提供了全部底层能力4.1 list发现本地工具list依赖 src/registry.ts 的声明查询能力getAllLocalToolkitSlugs()返回全部内置工具包 sluggetLocalToolkitDeclarations({ currentPlatform, toolkits })按平台过滤工具包并进一步过滤每个工具包内不支持当前平台的工具最后丢弃没有任何可用工具的空工具包isLocalToolkitSlug/isLocalToolSlug用于判断某个 slug 是否属于本地工具。也就是说list展示的内容是平台感知的——在 Linux 上你不会看到只为 macOS 设计的 Peekaboo。4.2 doctor就绪状态检查doctor对应 src/readiness.ts 中的checkLocalToolkitsReadiness它会为每个工具生成一份LocalToolReadiness报告状态共六种状态含义ready依赖就绪可直接执行unsupported当前平台不支持disabled被~/composio/local_tools.json元数据禁用missing依赖缺失命令不在 PATH、内置二进制缺失等not_implemented尚未实现unknown无法静态判定native 包装器需运行时自检就绪检查的核心是findExecutableOnPath它会对绝对路径/含分隔符的命令直接检查可执行性对普通命令名遍历PATH目录逐一探测在 Windows 上还会按PATHEXT.EXE;.CMD;.BAT;.COM补全扩展名对内置二进制引用通过resolveBundledBinary检查随包二进制是否存在。工具包层面的状态则由所有工具状态按优先级聚合readyunknownnot_implementedmissingdisabledunsupported取最严重者。报告同时携带messages与hints例如命令缺失时会提示SetLOCAL_BEEPER_IMESSAGE_XXX.installation.commandorbeeper-imessage.installation.commandin ~/composio/local_tools.json to override the binary.这直接衔接了configure子命令的作用。4.3 configure / meta本地元数据状态这两个子命令围绕 src/meta.ts 实现。元数据文件默认位于~/composio/local_tools.json可通过COMPOSIO_LOCAL_TOOLS_PATH环境变量或显式 path 覆盖结构如下{ version: 1, updatedAt: 2026-09-11T00:00:00.000Z, tools: { LOCAL_BEEPER_IMESSAGE_XXX: { disabled: false, installation: { command: /path/to/imessage-cli, version: 0.21.0 }, authenticated: true, updatedAt: 2026-09-11T00:00:00.000Z } }, toolkits: { peekaboo: { disabled: false } } }每个条目LocalToolMetaEntry支持的关键字段字段作用disabled禁用该工具/工具包doctor 会标记为disabledinstallation.command覆盖 CLI 类本地工具实际使用的命令/二进制路径installation.path/installation.version记录二进制路径与版本authenticated/auth记录认证状态与认证数据type、account、env、datanotes/metadata自由文本说明与扩展元数据实现细节上值得注意工具条目按finalSlug.toUpperCase()存储与读取工具包条目按slug.toLowerCase()存储与读取读写两侧保持一致的归一化策略文件不存在时返回空的元数据对象而非报错ENOENT分支每次写入都会自动把version固定为LOCAL_TOOLS_META_VERSION 1并刷新updatedAtcommandOverride的优先级在 runtime.ts 中体现工具级installation.command优先于工具包级最终覆盖声明的默认命令。这个文件是configure写入与meta读取两个子命令的共享存储也是本地工具可配置、可禁用、可审计的落点。五、内置二进制与安全解压5.1 随包二进制解析本地工具往往依赖平台二进制本包通过 src/bundled-binaries.ts 管理这些「内置二进制」默认包根目录为local-tools-binaries对应的仓库目录是 local-tools-binaries内含 beeper-imessage、composio-native-ui、peekaboo 三个子目录各带 LICENSE 与 NOTICE解析时依次探测三个候选位置打包 CLI JS 旁的 sidecar 目录、作为普通依赖安装时的包根目录、以及独立 Bun 可执行文件的同级目录支持COMPOSIO_LOCAL_TOOLS_BIN_DIR环境变量直接指定每个二进制目标声明LocalBundledBinaryTarget包含platforms哪些平台可用、path相对包根路径与executable是否需要标记可执行位执行前会调用ensureBundledBinaryExecutable确保二进制具备执行权限。从仓库布局看local-tools-binaries目录中的二进制通过构建脚本生成package.json 提供了build:beeper-imessage、build:peekaboo、build:composio-native-ui与汇总的build:local-tool-binaries四个脚本。其中 composio-native-ui 的原生部分是 Swift 实现见 native/composio-native-ui 的Package.swift与main.swift。5.2 ZIP 安全解压由于 sidecar 二进制通常以压缩包形式分发包内专门实现了 src/extract-zip-safely.ts配套测试在 src/extract-zip-safely.test.ts测试夹具包含benign.zip、symlink-absolute.zip、symlink-relative.zip三个样本见 src/zip-fixtures。从测试夹具命名可以推断安全解压的核心关注点是符号链接攻击恶意 ZIP 可能通过绝对路径符号链接或相对路径符号链接把文件写到解压目录之外经典的 Zip Slip 变体。这与 test/managed-block-fixtures 等安装类测试的防御思路一脉相承体现了 Composio 在本地工具分发链路中对安全性的重视。六、测试、构建与质量保障包内测试使用 Vitestvitest.config.tspackage.json中定义了{ scripts: { build: tsdown, test: vitest run, typecheck: tsc --noEmit -p ./tsconfig.src.json } }测试覆盖的关键面包括三个工具包的声明与行为测试beeper-imessage.test.ts、chrome-devtools.test.ts、peekaboo.test.ts内置二进制解析测试bundled-binaries.test.ts注册表 slug 归一化与解析测试registry.test.tsZIP 安全解压测试extract-zip-safely.test.tsSwift 系统补丁脚本测试scripts/swift-system-patches.test.ts。依赖方面运行时依赖仅三个composio/core核心 SDK、modelcontextprotocol/sdkMCP 桥接、extract-zip安全解压、zod输入 schemachrome-devtools-mcp出现在 devDependencies 中固定 1.8.0说明它主要在构建/测试期使用。七、从 CHANGELOG 看包的演进规律把这五个版本的 CHANGELOG 放在一起可以读出清晰的演进节奏功能一次性成型0.0.2 完成了从零到完整框架的跨越——声明体系types.ts、平台探测platform.ts、执行运行时runtime.ts、注册表registry.ts、就绪检查readiness.ts、元数据meta.ts、内置二进制bundled-binaries.ts与三个具体工具包同时落地说明这个包在设计阶段就有完整的架构规划。跟随核心包演进0.0.3 ~ 0.0.5 三次 Patch 都是纯粹的依赖升级composio/core0.9.1 → 0.10.0 → 0.11.0本地工具声明层保持稳定——这也侧面说明LocalToolDeclaration等接口在设计上足够前瞻未随核心包频繁变更。一次有准备的破坏性变更0.1.0 的 ESM-only 迁移发生在 0.x 版本线内属于破坏性但被明确文档化的变更。它同时给出迁移路径Node 22.22.3 原生require(esm)并同步把composio/core升到 0.12.0属于一次打包策略 运行时门槛的整体升级。对于正在使用 Composio CLI 本地工具的开发者0.1.0 意味着升级后请确保运行环境满足 Node ≥ 22.22.3且项目入口遵循 ESM 语义对于只通过composioCLI 命令local-tools list|doctor|configure|meta使用本地工具的用户这些变更由 CLI 打包产物消化通常无感。八、总结composio/cli-local-tools是 Composio CLI 本地能力的中枢包。它用一套统一的声明模型工具包 → 工具 → 执行模型把四种迥异的本地执行方式——子进程命令、进程内原生函数、MCP Server 桥接、Bun FFI 动态库——收敛为 Agent 可直接调用的LOCAL_*工具并通过local_tools.json元数据与doctor就绪检查让本地工具的安装、配置、诊断全程可控。其版本演进0.0.2 奠基 → 依赖跟进 → 0.1.0 ESM-only则展示了 monorepo 中工具包典型的生命周期先确立稳定抽象再随核心依赖稳步迭代最后在合适的时机完成一次影响面清晰、迁移路径明确的破坏性升级。想要深入了解实现细节的读者可以直接从 src/index.ts 的导出清单出发沿types → platform → meta → runtime → bundled-binaries → readiness → registry的顺序阅读源码。/output文章【免费下载链接】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），仅供参考