# https://github.com/ComposioHQ/composio 项目说明书 生成时间：2026-05-14 00:23:05 UTC ## 目录 - [项目介绍](#intro) - [快速入门指南](#quickstart) - [系统架构](#architecture) - [TypeScript SDK 详解](#ts-sdk) - [Python SDK 详解](#py-sdk) - [工具包系统](#toolkits) - [自定义工具开发](#custom-tools) - [AI 框架提供商集成](#providers) - [MCP 协议集成](#mcp) - [CLI 命令行工具](#cli) ## 项目介绍 ### 相关页面 相关主题：[快速入门指南](#quickstart), [系统架构](#architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/ComposioHQ/composio/blob/main/README.md) - [ts/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/README.md) - [ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts) - [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md) - [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts) - [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts) - [ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts)
# 项目介绍 ## 1. 项目概述 Composio 是一个强大的 AI Agent 工具集成平台，旨在为 AI Agent 提供可靠、可扩展的工具调用能力。该项目采用 TypeScript 与 Python 双语言架构，通过统一的接口设计实现了跨平台、跨框架的工具调用支持。 Composio 的核心价值主张包括： - **工具抽象层**：统一的工具定义和调用机制，支持多种 AI Agent 框架 - **本地工具支持**：提供本地 CLI 工具集成，可在本地环境中执行工具 - **权限管理**：完整的工具权限审批流程，确保工具调用的安全性 - **Provider 系统**：灵活的工具包装和修改器机制，支持自定义工具行为 ## 2. 仓库结构 Composio 采用 Monorepo 结构组织代码，主要分为 TypeScript 包和 Python SDK 两大部分。 ```mermaid graph TD A[composio 仓库根目录] --> B[ts/ - TypeScript Monorepo] A --> C[python/ - Python SDK] B --> D[packages/cli - CLI 核心] B --> E[packages/cli-local-tools - 本地工具] B --> F[packages/core - 核心类型定义] B --> G[packages/providers - Provider 基类] B --> H[examples/ - 示例代码] C --> I[composio/ - Python SDK 源码] C --> J[scripts/ - 文档生成脚本] ``` ### 2.1 TypeScript Monorepo 结构 TypeScript 部分位于 `ts/` 目录，包含完整的 CLI 工具和应用开发支持： | 目录/包 | 说明 | 主要功能 | |---------|------|----------| | `packages/cli` | CLI 核心包 | 命令行接口、权限管理、会话控制 | | `packages/cli-local-tools` | 本地工具包 | 本地工具注册和执行 | | `packages/core` | 核心类型包 | 类型定义、修改器接口 | | `packages/providers` | Provider 基类 | 工具包装基类实现 | | `examples/` | 示例代码 | 各功能模块的使用示例 | 资料来源：[ts/README.md:1-50]() ### 2.2 Python SDK 结构 Python 部分位于 `python/` 目录，提供 Python 语言的 SDK 支持： | 目录/文件 | 说明 | |-----------|------| | `composio/` | SDK 核心源码 | | `scripts/generate-docs.py` | 文档生成工具 | | `docs/` | 生成的文档输出目录 | 资料来源：[python/README.md:1-20]() ## 3. 核心系统架构 ### 3.1 工具系统 Composio 的工具系统是其核心组成部分，支持工具的发现、注册、调用和权限管理。 ```mermaid graph LR A[工具声明] --> B[本地工具注册表] A --> C[远程工具索引] B --> D[工具执行器] C --> D D --> E[权限检查] E --> F[执行结果] B -.-> G[toCustomTool 转换] C -.-> H[createToolkitIndex 索引] ``` #### 工具声明结构 工具通过声明式接口定义，包含以下关键属性： ```typescript interface LocalToolDeclaration { slug: string; // 工具唯一标识 name: string; // 工具显示名称 description: string; // 工具描述 inputParams: InputParams; // 输入参数定义 outputParams?: OutputParams; // 输出参数定义 execution: ExecutionConfig; // 执行配置 platforms: LocalCliPlatform[]; // 支持的平台 } ``` 资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-100]() #### 工具注册与过滤 系统支持按工具包（Toolkit）进行过滤和分组： ```typescript const toolkitMatchesFilter = ( toolkit: LocalToolkitDeclaration, requestedToolkits?: ReadonlyArray ): boolean => { if (!requestedToolkits || requestedToolkits.length === 0) return true; const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase())); return requested.has(toolkit.slug.toLowerCase()); }; ``` ### 3.2 CLI 命令系统 CLI 系统采用 Effect 框架构建，提供模块化的命令定义和子命令支持。 #### 根命令帮助 根命令提供全局选项和帮助信息： | 标志 | 说明 | |------|------| | `-h, --help [mode]` | 显示命令帮助（simple, default, full） | | `--version` | 显示版本信息 | | `--install-skill` | 手动安装 composio skill | 资料来源：[ts/packages/cli/src/commands/root-help.ts:1-50]() #### 子命令结构 CLI 采用树形命令结构： ```mermaid graph TD A[composio] --> B[dev] A --> C[execute] A --> D[search] A --> E[tools] A --> F[toolkits] A --> G[triggers] A --> H[orgs] B --> B1[init] B --> B2[playground-execute] B --> B3[logs] E --> E1[list] E --> E2[info] F --> F1[List] F --> F2[Info] F --> F3[Search] F --> F4[Version] ``` #### 常用命令示例 | 命令 | 功能 | |------|------| | `composio search ` | 按用途搜索工具 | | `composio tools list ` | 列出工具包中的工具 | | `composio tools info ` | 查看工具详细信息 | | `composio execute -d '{}'` | 执行工具调用 | | `composio link ` | 链接账户 | | `composio dev init` | 初始化开发环境 | 资料来源：[ts/packages/cli/src/services/command-hints.ts:1-80]() ### 3.3 权限管理系统 Composio 实现了完整的工具权限审批流程，确保工具调用的安全可控。 ```mermaid sequenceDiagram participant CLI as CLI 客户端 participant Server as 权限服务器 participant User as 用户 CLI->>Server: 请求执行工具 Server->>User: 显示权限确认页面 User->>Server: 选择权限决策 Server->>CLI: 返回决策结果 ``` #### 权限决策类型 | 决策 | 说明 | 有效期 | |------|------|--------| | `Allow for this session` | 会话级别允许 | 当前会话 | | `Allow once` | 单次允许 | 一次性 | | `Deny` | 拒绝 | 永久拒绝 | 资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-60]() #### 权限确认页面 系统通过本地 HTTP 服务器展示权限确认页面： ```html

Allow ${toolSlug}?

Composio CLI is requesting permission to execute this tool${accountLabel ? ` for ${accountLabel}` : ''}.

``` ### 3.4 Provider 系统 Provider 系统提供了工具包装和修改的扩展机制，允许开发者自定义工具的行为。 ```mermaid graph TD A[BaseComposioProvider] --> B[BaseNonAgenticProvider] A --> C[BaseAgenticProvider] B --> D[wrapTool] B --> E[getTools] B --> F[getToolBySlug] C --> G[wrapTool (Agentic)] C --> H[getTools (Agentic)] C --> I[getToolBySlug (Agentic)] ``` #### Provider 类型 | Provider 类型 | 用途 | 主要方法 | |---------------|------|----------| | `BaseNonAgenticProvider` | 非智能体 Provider | `wrapTool`, `getTools`, `getToolBySlug` | | `BaseAgenticProvider` | 智能体 Provider | `wrapTool`, `getTools`, `getToolBySlug` | 资料来源：[ts/packages/providers/README.md:1-80]() #### 工具修改器 Provider 使用修改器（Modifiers）来调整工具的 Schema 和行为： ```typescript type ProviderOptions = TProvider extends BaseComposioProvider ? TProvider extends BaseAgenticProvider ? AgenticToolOptions : ToolOptions : never; ``` 修改器支持的钩子函数： | 钩子函数 | 触发时机 | 用途 | |----------|----------|------| | `modifySchema` | Schema 生成时 | 修改输入输出结构 | | `beforeExecute` | 执行前 | 参数预处理 | | `afterExecute` | 执行后 | 结果后处理 | ## 4. 核心组件详解 ### 4.1 终端 UI 服务 TerminalUI 提供统一的命令行输出接口： ```typescript interface TerminalUI { readonly output: (data: string, options?: { force?: boolean }) => Effect; readonly intro: (title: string) => Effect; readonly outro: (message: string) => Effect; readonly log: { readonly info: (message: string) => Effect; readonly success: (message: string) => Effect; readonly warn: (message: string) => Effect; readonly error: (message: string) => Effect; readonly step: (message: string) => Effect; }; readonly note: (message: string, title?: string) => Effect; readonly withSpinner: (message: string, effect: Effect) => Effect; } ``` 资料来源：[ts/packages/cli/src/services/terminal-ui.ts:1-40]() ### 4.2 错误处理机制 系统使用 Effect 框架进行错误处理： ```typescript export const captureErrorsFrom = (cause: Cause): readonly PrettyError[] => reduceWithContext(cause, undefined, { emptyCase: (): readonly PrettyError[] => [], dieCase: (_, unknownError) => [parseError(unknownError)], failCase: (_, error) => [parseError(error)], interruptCase: () => [], parallelCase: (_, l, r) => [...l, ...r], sequentialCase: (_, l, r) => [...l, ...r], }); ``` 资料来源：[ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts:1-20]() ### 4.3 配置加载系统 系统支持从文件加载和解析配置： ```mermaid graph LR A[配置文件] --> B[ConfigLoader] B --> C[Path 解析] C --> D[Primitive 解析] D --> E[split 分割] E --> F[Array] ``` 支持的分隔符解析功能，允许用户自定义分隔符来拆分配置值。 资料来源：[ts/packages/cli/src/effects/from-lazy-json.ts:1-50]() ### 4.4 工具包索引 工具包索引系统提供工具的分组和类型化支持： ```typescript export type CreateToolkitIndexInput = Simplify<{ slug: string; version?: string; typeableTools: | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> } | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> }; triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>; }>; export type ToolkitIndex = Record; ``` 资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:1-30]() ## 5. 开发指南 ### 5.1 环境准备 ```bash # 安装依赖 pnpm install # 安装 peer 依赖 pnpm check:peer-deps ``` 资料来源：[ts/README.md:1-50]() ### 5.2 创建新 Provider ```bash # 创建非智能体 Provider pnpm create:provider # 创建智能体 Provider pnpm create:provider --agentic ``` Provider 创建后的结构： ``` / ├── src/ │ └── index.ts # Provider 实现 ├── package.json # 包配置 ├── tsconfig.json # TypeScript 配置 ├── tsup.config.ts # 构建配置 └── README.md # 文档 ``` 资料来源：[ts/README.md:50-80]() ### 5.3 创建示例代码 ```bash pnpm create:example ``` ### 5.4 本地工具配置 本地工具支持灵活的配置文件管理： | 配置项 | 说明 | |--------|------| | `command` | 安装命令 | | `disabled` | 是否禁用 | | `authenticated` | 是否需要认证 | 配置完成后可运行： ```bash composio local-tools doctor --toolkits ``` 资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-60]() ## 6. Python SDK 文档生成 Composio 使用 Griffe 工具从 Python 源码自动生成文档： ```bash cd python uv run --with griffe python scripts/generate-docs.py ``` 文档生成流程： ```mermaid graph LR A[Python 源码] -->|griffe 提取| B[结构化数据] B -->|transform| C[MDX 文件] C --> D[docs/content/reference/sdk-reference/python/] ``` 资料来源：[python/scripts/README.md:1-30]() ## 7. 项目技术栈 ### 7.1 TypeScript 技术栈 | 技术 | 用途 | |------|------| | Effect | 函数式错误处理和 Effect 编程 | | Effect/Cli | CLI 命令行框架 | | TypeScript | 类型系统 | | tsup | 构建工具 | ### 7.2 Python 技术栈 | 技术 | 用途 | |------|------| | Griffe | Docstring 解析 | | MDX | 文档格式 | ## 8. 总结 Composio 是一个设计精良的 AI Agent 工具集成平台，其架构特点包括： 1. **模块化设计**：通过 Monorepo 结构实现代码的高内聚低耦合 2. **类型安全**：全面使用 TypeScript 提供类型保障 3. **函数式编程**：采用 Effect 框架实现纯函数式错误处理 4. **扩展性强**：Provider 系统支持自定义工具包装行为 5. **双语言支持**：同时提供 TypeScript 和 Python SDK 通过本项目，开发者可以快速构建基于 AI Agent 的应用，享受统一工具调用接口带来的便利。 --- ## 快速入门指南 ### 相关页面 相关主题：[TypeScript SDK 详解](#ts-sdk), [Python SDK 详解](#py-sdk), [AI 框架提供商集成](#providers)
相关源码文件 以下源码文件用于生成本页说明： - [ts/examples/tool-router/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/examples/tool-router/README.md) - [python/README.md](https://github.com/ComposioHQ/composio/blob/main/python/README.md) - [ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts) - [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts) - [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md) - [ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts) - [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)
# 快速入门指南 Composio 是一个强大的 AI 代理工具集成平台，支持多种主流 AI 框架（如 OpenAI、LangChain 等）。本指南将帮助您快速上手 Composio，掌握核心概念、安装配置、工具使用以及 CLI 命令行工具的基本操作。 ## 概述 Composio 提供了统一的工具抽象层，使 AI 代理能够访问超过 250+ 的外部应用工具。通过 Composio SDK，开发者可以： - 快速集成 OpenAI、Anthropic、LangChain 等主流 AI 框架 - 获取并管理可用的应用工具 - 使用 schema 修饰器转换工具架构 - 通过 CLI 工具进行本地开发和调试 ## 环境要求 | 组件 | 最低版本要求 | |------|-------------| | Node.js | >= 18.0.0 | | Python | >= 3.10 | | pnpm | >= 8.0.0 | ## 安装配置 ### TypeScript SDK 安装 Composio 的 TypeScript SDK 提供两种安装方式：完整包安装和按需安装 资料来源：[ts/packages/cli/src/commands/root-help.ts:1-50]() ```bash # 完整安装 pnpm add @composio/core @composio/cli # 仅安装核心包 pnpm add @composio/core ``` ### Python SDK 安装 ```bash pip install composio-core ``` ### 环境变量配置 创建 `.env` 文件并配置以下环境变量 资料来源：[ts/examples/tool-router/README.md:10-20]() ```bash # 必需的环境变量 COMPOSIO_API_KEY=your_api_key_here # 可选配置 OPENAI_API_KEY=your_openai_key # OpenAI 集成必需 OPENAI_MODEL=gpt-4o # 模型覆盖 COMPOSIO_BASE_URL=https://api.composio.dev # 自定义 API 地址 COMPOSIO_LOG_LEVEL=info # 日志级别 COMPOSIO_DISABLE_TELEMETRY=true # 禁用遥测 ``` ### CLI 初始化 使用 `composio init` 命令初始化项目 资料来源：[ts/packages/cli/src/commands/init.cmd.ts:1-30]() ```bash # 交互式初始化 composio init # 或指定项目目录 composio init --cwd ./my-project ``` 初始化过程会提示您选择组织、创建项目，并自动生成 `.env.local` 配置文件。 ## 核心概念 ### 工具与工具包 Composio 中的工具（Tool）是执行特定操作的最小单元，工具包（Toolkit）是相关工具的集合。每个工具都有唯一的 slug 标识符，格式为 `{TOOLKIT}_{ACTION}`，例如 `GITHUB_CREATE_REPO`。 ### Provider 提供商 Provider 是 Composio SDK 与不同 AI 框架之间的桥梁。目前支持的提供商包括 资料来源：[ts/packages/providers/README.md:1-40]() | Provider 类型 | 说明 | |--------------|------| | OpenAIProvider | OpenAI Agents SDK 集成 | | AnthropicProvider | Anthropic Claude 集成 | | LangChainProvider | LangChain 框架集成 | ### 修饰器 Composio 支持强大的修饰器（Modifiers）功能，用于转换工具 schema 和执行行为 资料来源：[python/README.md:60-100]() ```python from composio import schema_modifier @schema_modifier(tools=["HACKERNEWS_GET_USER"]) def modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool: schema["description"] = "增强版用户查询" return schema ``` ## 快速开始示例 ### TypeScript 工具路由器 以下示例展示如何使用 TypeScript SDK 进行工具路由 资料来源：[ts/examples/tool-router/src/index.ts:1-50]() ```typescript import { Composio } from "@composio/core"; async function main() { // 初始化 SDK const client = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, }); // 获取所有可用工具 const tools = await client.tools.list(); // 获取特定工具 const githubTool = await client.tools.get({ slug: "GITHUB_CREATE_REPO", app: "github" }); // 执行工具 const result = await client.execute("github_create_repo", { name: "my-new-repo", description: "Repository created via Composio" }); } ``` ### Python OpenAI Agents 集成 ```python from composio import Composio from openai import OpenAI client = Composio(api_key="your_api_key") openai_client = OpenAI() # 获取工具 tools = client.tools.get_tools(apps=["github", "slack"]) # 在 OpenAI Agents 中使用 assistant = openai_client.beta.assistants.create( model="gpt-4o", tools=tools ) ``` ## CLI 命令参考 ### 常用命令速查 | 命令 | 功能 | |------|------| | `composio init` | 初始化新项目 | | `composio tools list` | 列出所有可用工具 | | `composio tools info ` | 查看工具详情 | | `composio execute ` | 执行指定工具 | | `composio link ` | 连接第三方账户 | | `composio local-tools list` | 列出本地工具 | ### 工具列表命令 ```bash # 列出所有工具 composio tools list # 列出特定工具包的工具 composio tools list --toolkit github # JSON 格式输出 composio tools list --json ``` ### 工具信息查询 ```bash # 查看工具详情 composio tools info GITHUB_CREATE_REPO # 获取工具执行 schema composio execute GITHUB_CREATE_REPO --get-schema ``` ### 执行工具 ```bash # 执行工具（交互式） composio execute GITHUB_CREATE_REPO # 执行工具（传入参数） composio execute GITHUB_CREATE_REPO -d '{"name": "my-repo", "private": true}' ``` ### 账户连接 ```bash # 连接第三方账户 composio link github composio link slack # 查看已连接账户 composio accounts list ``` ## 本地 CLI 工具 Composio 支持本地 CLI 工具扩展，允许 Tool Router 搜索和执行本地工具 资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-60]() ### 本地工具命令 | 命令 | 功能 | |------|------| | `composio local-tools list` | 列出已注册本地工具包 | | `composio local-tools doctor` | 检查本地工具就绪状态 | | `composio local-tools configure` | 配置本地工具 | ### 配置本地工具 ```bash # 配置工具包 composio local-tools configure \ --command /path/to/tool \ --authenticated # 禁用工具 composio local-tools configure --disable # 启用工具 composio local-tools configure --enable ``` ### 列出本地工具 ```bash # 基本列表 composio local-tools list # 包含不支持当前平台的工具 composio local-tools list --all-platforms # 过滤特定工具包 composio local-tools list --toolkits mytoolkit # JSON 格式输出 composio local-tools list --json ``` ## 开发模式 Composio 提供开发模式用于本地调试和测试 资料来源：[ts/packages/cli/src/commands/root-help.ts:40-80]() ### 开发命令 ```bash # 初始化开发环境 composio dev init # 在 Playgroun 中执行工具 composio dev playground-execute \ --user-id \ -d '{}' # 获取执行 schema composio dev playground-execute --get-schema # 查看工具执行日志 composio dev logs tools # 查看触发器日志 composio dev logs triggers ``` ## 工具包管理 ### 发现工具包 ```bash # 列出所有工具包 composio toolkits list # 搜索工具包 composio toolkits search # 查看工具包详情 composio toolkits info ``` ### 管理工具包版本 ```bash # 查看工具包版本 composio toolkits version # 设置特定版本 COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00 ``` ## 工作流程图 ### 基本集成流程 ```mermaid graph TD A[初始化 Composio SDK] --> B[配置 API Key] B --> C[获取可用工具] C --> D[选择工具包] D --> E[执行工具操作] E --> F{操作成功?} F -->|是| G[返回结果] F -->|否| H[错误处理] ``` ### CLI 工具执行流程 ```mermaid graph TD A[composio 命令] --> B{子命令类型} B -->|tools| C[工具操作] B -->|execute| D[执行工具] B -->|local-tools| E[本地工具] B -->|dev| F[开发模式] C --> C1[list/信息查询] D --> D1[权限检查] D1 --> D2[执行工具] E --> E1[配置/列表/诊断] F --> F1[Playground/日志] ``` ## 最佳实践 ### 1. 项目结构组织 ``` my-agent-project/ ├── .env.local # 本地环境变量 ├── composio.config.ts # SDK 配置 ├── src/ │ ├── index.ts # 入口文件 │ └── tools/ # 工具封装 └── package.json ``` ### 2. 安全管理 - 使用环境变量存储 API Key，避免硬编码 - 使用 `.env.local` 存储项目级敏感信息 - 通过 CLI 的权限确认功能控制工具执行 ### 3. 错误处理 ```typescript import { ComposioSDKError } from "@composio/core"; try { const result = await client.execute("tool_slug", params); } catch (error) { if (error instanceof ComposioSDKError) { console.error(`SDK Error: ${error.message}`); } } ``` ### 4. 性能优化 - 预加载常用工具到 `session.tools()` - 使用 `SessionPreset.DIRECT_TOOLS` 预加载所有允许的工具 - 避免在循环中频繁调用工具获取接口 ## 常见问题 ### Q: 如何获取 API Key？ 访问 [Composio Dashboard](https://app.composio.dev) 注册账号并获取 API Key。 ### Q: 工具执行失败怎么办？ 1. 使用 `composio local-tools doctor` 检查本地环境 2. 使用 `composio tools info ` 确认工具参数正确 3. 查看 `composio dev logs tools ` 获取详细错误信息 ### Q: 如何使用自定义 Provider？ 参考 [Provider 创建文档](ts/packages/providers/README.md)，使用 `pnpm run create-provider ` 创建自定义 Provider。 ## 下一步 - 深入阅读 [工具包文档](ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts) - 了解 [Schema 修饰器](python/README.md)的高级用法 - 探索 [OpenAI 集成示例](python/examples/tool_router/openai_agents.py) - 加入 [Discord 社区](https://discord.gg/composio) 获取帮助 --- ## 系统架构 ### 相关页面 相关主题：[TypeScript SDK 详解](#ts-sdk), [Python SDK 详解](#py-sdk), [工具包系统](#toolkits)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/core/src/composio.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/composio.ts) - [ts/packages/core/src/provider/ComposioProvider.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/provider/ComposioProvider.ts) - [python/composio/sdk.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/sdk.py) - [ts/packages/core/src/models/ToolRouter.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ToolRouter.ts) - [python/composio/core/models/tool_router.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/tool_router.py) - [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts) - [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md) - [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts)
# 系统架构 ## 概述 Composio 是一个多语言 Agent 工具集成平台，支持通过统一的 SDK 接口调用外部工具和服务。系统架构采用分层设计，核心层负责工具路由和执行管理，Provider 层提供灵活的扩展机制，CLI 层提供命令行交互能力。本文档基于源码分析，阐述 Composio 的整体架构设计、各核心模块职责以及跨语言 SDK 的实现机制。 ## 架构分层 Composio 系统采用四层架构设计，从上到下依次为： | 层级 | 名称 | 职责 | 主要实现 | |------|------|------|----------| | 1 | SDK 层 | 对外提供统一的工具调用接口 | `composio.ts`、`sdk.py` | | 2 | 核心层 | 工具路由、Schema 修饰、Provider 管理 | `ToolRouter.ts`、`tool_router.py` | | 3 | Provider 层 | 工具封装、Schema 转换、执行拦截 | `ComposioProvider.ts` | | 4 | CLI 层 | 命令行工具、本地工具注册 | `registry.ts` | ```mermaid graph TD subgraph SDK层 TS_SDK[TypeScript SDK
composio.ts] PY_SDK[Python SDK
sdk.py] end subgraph 核心层 TR_TypeScript[ToolRouter
TypeScript] TR_Python[ToolRouter
Python] end subgraph Provider层 CP[ComposioProvider] BaseProvider[BaseComposioProvider] AgenticProvider[BaseAgenticProvider] end subgraph CLI层 CLI[Composio CLI] LocalRegistry[本地工具注册表
registry.ts] end subgraph 外部服务 API[Composio API] MCP[MCP Server] end TS_SDK --> TR_TypeScript PY_SDK --> TR_Python TR_TypeScript --> CP TR_Python --> CP CP --> BaseProvider CP --> AgenticProvider CLI --> LocalRegistry CP --> API CP --> MCP ``` ## 核心模块 ### SDK 入口 Composio 提供 TypeScript 和 Python 两种 SDK 入口，两者在设计思想上保持一致，但实现细节根据语言特性有所差异。 #### TypeScript SDK TypeScript SDK 的核心入口位于 `composio.ts`，该文件导出一个统一的 `Composio` 类。SDK 初始化时接受配置参数，包括 API 密钥、基础 URL、日志级别等。SDK 内部持有 `ComposioTool` 实例用于工具管理，并通过 `ComposioProvider` 与后端服务通信。 主要配置选项： | 参数 | 类型 | 说明 | |------|------|------| | `apiKey` | `string` | Composio API 密钥 | | `baseURL` | `string` | API 基础地址，默认为 Composio 官方服务 | | `toolkitVersionOverrides` | `Map` | 工具包版本覆盖 | | `logLevel` | `LogLevel` | 日志级别：silent、error、warn、info、debug | | `disableTelemetry` | `boolean` | 是否禁用遥测数据 | #### Python SDK Python SDK 位于 `python/composio/sdk.py`，采用类式设计，提供 `Composio` 类作为主要入口。Python SDK 通过 `openai` 库实现与 OpenAI 生态的集成，同时支持自定义 LLM 客户端。 ### 工具路由器 工具路由器（ToolRouter）是架构的核心组件，负责工具的注册、查询和路由。 #### TypeScript ToolRouter `ToolRouter.ts` 实现了 TypeScript 端的工具路由逻辑。路由器维护一个工具索引（ToolkitIndex），将工具按照所属工具包（Toolkit）进行分组管理。 关键数据结构： ```typescript export type ToolkitIndex = Record; export type ToolkitIndexData = Simplify<{ slug: string; version?: string; typeableTools: | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> } | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> }; triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>; }>; ``` 路由器通过 `createToolkitIndex` 函数从输入数据构建索引，该函数接收版本映射（versionMap）用于工具包版本控制。 #### Python ToolRouter Python 端在 `python/composio/core/models/tool_router.py` 中实现对应的路由器功能。Python 版本同样维护工具索引，但使用 Python 原生的字典和类结构。 ### Provider 体系 Provider 是 Composio 架构中实现工具封装和执行拦截的关键组件。系统定义了两种 Provider 类型： #### BaseComposioProvider 基础 Provider 实现了工具的包装和获取逻辑。所有非 Agentic Provider 都继承自此类： ```typescript class NonAgenticProvider extends BaseNonAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise; async getTools(modifiers?: SchemaModifiersParams): Promise; async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise; } ``` #### BaseAgenticProvider Agentic Provider 继承自基础 Provider，增加了对 Agentic 工具的支持。Agentic 工具具有更复杂的执行流程，能够在执行前后进行上下文干预： ```typescript class AgenticProvider extends BaseAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise; async getTools(modifiers?: ModifiersParams): Promise; } ``` #### ComposioProvider `ComposioProvider.ts` 是 SDK 与外部服务通信的主要入口，它组合了多个底层 Provider 的能力： ```mermaid graph LR ComposioProvider -->|持有| BaseComposioProvider ComposioProvider -->|持有| BaseAgenticProvider ComposioProvider -->|调用| ComposioToolkitsRepository ComposioProvider -->|调用| HTTPClient ``` Provider 的选择通过类型推断实现，SDK 根据传入的 Provider 类型自动选择合适的工具选项类型： ```typescript export type ProviderOptions = TProvider extends BaseComposicProvider ? TProvider extends BaseAgenticProvider ? AgenticToolOptions : ToolOptions : never; ``` ## 工具包版本管理 Composio 支持通过环境变量对工具包版本进行精细化控制。每个工具包可以指定特定版本或使用最新版本。 ### 版本覆盖机制 版本覆盖通过 `ToolkitVersionOverrides` 类型管理： ```typescript export type ToolkitVersionOverrides = Map, string>; ``` ### 版本分组与验证 版本分组逻辑将具有相同版本的工具包聚合在一起，便于批量处理： ```typescript export const groupByVersion = ( specs: ReadonlyArray ): Map[]> => { const grouped = new Map[]>(); for (const spec of specs) { const existing = grouped.get(spec.toolkitVersion); if (existing) { existing.push(spec.toolkitSlug); } else { grouped.set(spec.toolkitVersion, [spec.toolkitSlug]); } } return grouped; }; ``` 版本验证通过 `validateToolkitVersionOverrides` 函数执行，该函数会调用 API 验证版本有效性并在遇到错误时提供友好的错误信息。 ### 环境变量配置 工具包版本可通过以下格式的环境变量配置： | 环境变量 | 说明 | 示例 | |----------|------|------| | `COMPOSIO_TOOLKIT_VERSION_` | 指定工具包版本 | `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00` | 版本值 `"latest"` 表示使用最新版本，不会被添加到版本映射中。 ## Schema 修饰器 Schema 修饰器（Schema Modifiers）允许在工具执行的不同阶段对请求和响应进行处理。这是实现日志记录、参数转换、结果过滤等功能的基础机制。 ### 修饰器类型 ```typescript interface SchemaModifiersParams { modifySchema?: (context: SchemaModificationContext) => SchemaModificationResult; beforeExecute?: (context: ExecutionContext) => ExecutionContext; afterExecute?: (context: ExecutionContext) => ExecutionContext; } ``` ### 执行流程 ```mermaid graph TD A[接收工具调用] --> B{有 modifySchema?} B -->|是| C[应用 Schema 修饰] B -->|否| D[使用原始 Schema] C --> E{有 beforeExecute?} D --> E E -->|是| F[执行 beforeExecute] E -->|否| G[调用工具] F --> G G --> H{有 afterExecute?} H -->|是| I[执行 afterExecute] H -->|否| J[返回结果] I --> J ``` ## 本地工具系统 Composio CLI 提供本地工具注册和管理能力，允许用户定义和执行本地命令行工具。 ### 本地工具注册表 本地工具注册表（`registry.ts`）负责管理所有本地工具的定义和元数据： ```typescript export const getAllLocalToolkitSlugs = ( options: { readonly declarations?: ReadonlyArray } = {} ): ReadonlyArray => declarationsFor(options.declarations).map(toolkit => toolkit.slug.toLowerCase()); ``` ### 工具匹配与过滤 注册表提供多种匹配工具的方法： | 方法 | 用途 | |------|------| | `toolkitMatchesFilter` | 检查工具包是否匹配过滤器 | | `isLocalToolkitSlug` | 验证是否为本地工具包 | | `isLocalToolSlug` | 验证是否为本地工具 | | `resolveLocalTool` | 根据 slug 解析本地工具 | ### 本地工具执行 本地工具通过统一的执行函数处理： ```typescript const executeLocalTool = async ( execution: LocalToolExecution, input: Record, options: ExecuteLocalToolOptions ) => { // 处理工具执行逻辑 }; ``` ## 错误处理机制 Composio 使用 Effect 库进行函数式错误处理，通过 `captureErrorsFrom` 函数将 Effect 的 Cause 转换为友好的错误信息： ```typescript export const captureErrorsFrom = (cause: Cause): readonly PrettyError[] => reduceWithContext(cause, undefined, { emptyCase: (): readonly PrettyError[] => [], dieCase: (_, unknownError) => [parseError(unknownError)], failCase: (_, error) => [parseError(error)], interruptCase: () => [], parallelCase: (_, l, r) => [...l, ...r], sequentialCase: (_, l, r) => [...l, ...r], }); ``` ## CLI 命令架构 Composio CLI 采用 Effect 框架构建命令系统，每个命令都是一个 Effect 子程序。命令通过模块化组织，核心命令包括： | 命令 | 功能 | |------|------| | `composio execute` | 执行指定工具 | | `composio tools list` | 列出工具包中的工具 | | `composio tools info` | 查看工具详情 | | `composio local-tools` | 管理本地工具 | | `composio dev init` | 初始化开发环境 | | `composio dev playground-execute` | 操场执行工具 | ### TypeScript 生成命令 `ts.generate.cmd.ts` 实现了 `composio generate ts` 命令，用于生成 TypeScript 类型定义文件： ```mermaid graph LR A[generate ts 命令] --> B{指定 --output-dir?} B -->|是| C[写入指定目录] B -->|否| D[查找 @composio/core] C --> E{指定 --transpiled?} D --> E E -->|是| F[生成 .ts + .js] E -->|否| G[仅生成 .ts] F --> H[完成] G --> H ``` ## Provider 扩展机制 Composio 支持通过创建自定义 Provider 来扩展系统功能。创建新 Provider 的标准流程： 1. 使用 `pnpm create:provider ` 创建 Provider 骨架 2. 在 `src/index.ts` 中实现必要方法 3. 注册 Provider 到 SDK ```bash # 创建非 Agentic Provider pnpm create:provider my-provider # 创建 Agentic Provider pnpm create:provider my-provider --agentic ``` ## 数据流总结 ```mermaid graph TD subgraph 用户代码 User[用户调用 SDK] end subgraph SDK 层 Composio_SDK[Composio SDK] end subgraph 核心层 ToolRouter[ToolRouter] ToolkitIndex[ToolkitIndex] end subgraph Provider 层 Provider[ComposioProvider] MCP_Client[MCP Client] end subgraph 外部 API[Composio API] MCP_Server[MCP Server] end User --> Composio_SDK Composio_SDK --> ToolRouter ToolRouter --> ToolkitIndex Composio_SDK --> Provider Provider --> API Provider --> MCP_Client MCP_Client --> MCP_Server ``` Composio 的架构设计强调模块化、可扩展性和跨语言一致性。通过清晰的层次划分和标准化的 Provider 接口，系统能够灵活适应不同的使用场景和集成需求。 --- ## TypeScript SDK 详解 ### 相关页面 相关主题：[Python SDK 详解](#py-sdk), [AI 框架提供商集成](#providers), [工具包系统](#toolkits)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/core/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/index.ts) - [ts/packages/core/src/models/Tools.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Tools.ts) - [ts/packages/core/src/models/Toolkits.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Toolkits.ts) - [ts/packages/core/src/models/ToolRouterSession.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ToolRouterSession.ts) - [ts/packages/core/src/models/ConnectedAccounts.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ConnectedAccounts.ts) - [ts/docs/api/tools.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/api/tools.md)
# TypeScript SDK 详解 ## 概述 Composio TypeScript SDK 是用于与 Composio 平台交互的核心开发工具包，为 AI Agent 提供工具调用、工具包管理、账户连接等功能。该 SDK 构建于 Effect 框架之上，采用函数式编程范式，支持类型安全的工具操作和灵活的扩展机制。 资料来源：[ts/README.md]() ## 核心架构 ### 系统组件关系 ```mermaid graph TD A[ComposioClient] --> B[ToolRouter] A --> C[ConnectedAccounts] B --> D[Toolkits] B --> E[Tools] D --> E F[Providers] --> E G[CLI Tools] --> E ``` ### 包结构概览 | 包名称 | 路径 | 职责 | |--------|------|------| | `@composio/core` | `packages/core` | 核心 SDK，包含所有核心模型和服务 | | `@composio/cli` | `packages/cli` | 命令行工具，支持项目初始化和类型生成 | | `@composio/providers` | `packages/providers/*` | AI 框架集成（OpenAI、LangChain、Vercal 等） | | `@composio/ts-builders` | `packages/ts-builders` | TypeScript AST 构建工具，用于生成类型存根 | | `@composio/cli-local-tools` | `packages/cli-local-tools` | 本地 CLI 工具注册表 | 资料来源：[ts/README.md](), [ts/packages/ts-builders/README.md]() ## 核心模型 ### Tools（工具） `Tool` 模型代表单个可执行工具，是 SDK 的基本操作单元。每个工具包含以下属性： | 属性 | 类型 | 说明 | |------|------|------| | `slug` | `string` | 工具唯一标识符 | | `name` | `string` | 工具显示名称 | | `description` | `string` | 工具功能描述 | | `inputParams` | `InputParameter[]` | 输入参数定义 | | `outputParams` | `OutputParameter[]` | 输出参数定义 | | `toolkit` | `Toolkit` | 所属工具包 | | `triggers` | `Trigger[]` | 触发器配置 | 资料来源：[ts/packages/core/src/models/Tools.ts](), [ts/packages/cli/src/generation/create-toolkit-index.ts]() ### Toolkits（工具包） `Toolkit` 是工具的逻辑分组容器，提供组织和管理相关工具的能力： ```typescript export type ToolkitIndex = Record; ``` 工具包数据包含版本管理和工具集合映射，支持按名称动态访问工具定义。 资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts]() ### ToolRouterSession（会话路由） `ToolRouterSession` 负责管理工具调用的生命周期，包括参数验证、执行和结果处理： ```mermaid sequenceDiagram Agent->>ToolRouterSession: requestToolCall(toolSlug, params) ToolRouterSession->>Tool: validateParams(params) Tool-->>ToolRouterSession: validatedParams ToolRouterSession->>Tool: execute(validatedParams) Tool-->>ToolRouterSession: executionResult ToolRouterSession->>Agent: formattedResponse ``` 资料来源：[ts/packages/core/src/models/ToolRouterSession.ts]() ### ConnectedAccounts（连接账户） `ConnectedAccounts` 管理用户与第三方服务的授权连接，是工具执行认证的基础： | 属性 | 说明 | |------|------| | `accountId` | 账户唯一标识 | | `integrationId` | 集成标识 | | `connectionStatus` | 连接状态 | | `credentials` | 加密凭证 | | `metadata` | 额外元数据 | 资料来源：[ts/packages/core/src/models/ConnectedAccounts.ts]() ## Provider 机制 ### Provider 类型 SDK 支持两种 Provider 类型，分别适用于不同的 AI 框架集成场景： | Provider 类型 | 基类 | 用途 | |---------------|------|------| | 非 Agentic | `BaseNonAgenticProvider` | 基础工具包装和模式转换 | | Agentic | `BaseAgenticProvider` | 支持完整执行流程修饰符 | 资料来源：[ts/packages/providers/README.md](), [ts/packages/core/src/types/modifiers.types.ts]() ### Provider 方法 #### 非 Agentic Provider ```typescript class NonAgenticProvider extends BaseNonAgenticProvider { async wrapTool( toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams ): Promise; async getTools(modifiers?: SchemaModifiersParams): Promise; async getToolBySlug( slug: string, modifiers?: SchemaModifiersParams ): Promise; } ``` #### Agentic Provider Agentic Provider 在非 Agentic 基础上增加执行修饰符支持： ```typescript type beforeExecuteModifier = ( toolSlug: string, params: Record ) => Record; type afterExecuteModifier = ( toolSlug: string, response: ToolExecuteResponse ) => ToolExecuteResponse; ``` 资料来源：[ts/packages/providers/README.md](), [ts/packages/core/src/types/modifiers.types.ts]() ### 内置 Providers | Provider | 包路径 | AI 框架 | |----------|--------|---------| | OpenAI Provider | `packages/providers/openai` | OpenAI | | LangChain Provider | `packages/providers/langchain` | LangChain | | Vercel Provider | `packages/providers/vercel` | Vercel AI SDK | | Claude Agent SDK Provider | `packages/providers/claude-agent-sdk` | Anthropic Claude Agent SDK | 资料来源：[ts/packages/providers/openai/package.json](), [ts/packages/providers/langchain/package.json](), [ts/packages/providers/vercel/package.json](), [ts/packages/providers/claude-agent-sdk/package.json]() ## 类型生成系统 ### TypeScript 类型存根 CLI 提供 `composio generate ts` 命令用于生成 TypeScript 类型存根： ```bash composio generate ts composio generate ts --type-tools composio generate ts --toolkits gmail slack ``` 生成器支持以下选项： | 选项 | 说明 | 默认值 | |------|------|--------| | `--compact` | 生成单个模块文件 | `false` | | `--transpiled` | 同时生成转译后的 JavaScript | 写入 `node_modules` 时为 `true` | | `--output-dir` | 指定输出目录 | `@composio/core` 包路径 | | `--toolkits` | 仅包含指定工具包 | 全部工具包 | 资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts](), [ts/packages/cli/src/commands/generate/generate.cmd.ts]() ### 文档生成 SDK 使用 TypeDoc 从源代码提取 JSDoc 注释生成 MDX 文档： ```mermaid graph LR A[src/models/*.ts] -->|TypeDoc| B[JSON AST] B -->|generate-docs.ts| C[MDX 文件] C --> D[docs/content/reference/sdk-reference/typescript/] ``` 工作流程由 GitHub Actions 自动化触发：`.github/workflows/generate-sdk-docs.yml` 监听 `ts/packages/core/src/**` 变更并自动创建 PR。 资料来源：[ts/packages/core/scripts/README.md]() ## 本地工具注册 `@composio/cli-local-tools` 包提供本地 CLI 工具的注册和管理能力： ```typescript export const getAllLocalToolkitSlugs = ( options?: { declarations?: ReadonlyArray } ): ReadonlyArray; export const getLocalCustomToolkits = ( options?: { currentPlatform?: LocalCliPlatform; toolkits?: ReadonlyArray; declarations?: ReadonlyArray; } ): ReadonlyArray; ``` 本地工具支持跨平台声明和动态平台检测。 资料来源：[ts/packages/cli-local-tools/src/registry.ts]() ## 环境变量配置 | 变量名 | 说明 | 必填 | |--------|------|------| | `COMPOSIO_API_KEY` | Composio API 密钥 | 是 | | `COMPOSIO_BASE_URL` | 自定义 API 基础 URL | 否 | | `COMPOSIO_LOG_LEVEL` | 日志级别（silent/error/warn/info/debug） | 否 | | `COMPOSIO_DISABLE_TELEMETRY` | 禁用遥测（设为 "true"） | 否 | | `COMPOSIO_TOOLKIT_VERSION_` | 工具包版本覆盖 | 否 | | `DEVELOPMENT` | 开发模式标志 | 否 | | `CI` | CI 环境标志 | 否 | 资料来源：[ts/README.md](), [ts/packages/cli/src/commands/init.cmd.ts]() ## 工具包版本管理 CLI 提供工具包版本覆盖验证机制： ```typescript const { validatedOverrides, warnings } = yield* client.validateToolkitVersions( versionOverrides, toolkitSlugsFilter ); ``` 验证器支持批量验证并在检测到无效版本时提供友好的错误提示。 资料来源：[ts/packages/cli/src/effects/validate-toolkit-versions.ts]() ## 项目语言检测 SDK 自动检测项目语言环境： ```typescript const envDetector = yield* ProjectEnvironmentDetector; const env = yield* envDetector.detectProjectEnvironment(cwd); ``` 检测逻辑按优先级检查： 1. TypeScript 文件（`.ts`、`.tsx`、`.mts`、`.cts`） 2. Python 文件（`.py`、`.pyw`、`.pyi`、`.pyx`） 忽略目录包括：`node_modules`、`__pycache__`、`.venv`、`venv` 等。 资料来源：[ts/packages/cli/src/services/env-lang-detector.ts]() ## 快速开始 ### 安装 ```bash pnpm add @composio/core ``` ### 初始化客户端 ```typescript import { Composio } from "@composio/core"; const client = new Composio(); ``` ### 获取工具 ```typescript const tools = await client.getTools({ toolkits: ["github"] }); ``` ### 执行工具 ```typescript const result = await client.execute({ tool: "github_create_repository", params: { name: "my-repo", description: "Repository description" } }); ``` ## 最佳实践 1. **类型安全**：始终使用 TypeScript 并确保所有方法和参数的类型定义完整 2. **错误处理**：为 API 调用和工具执行实现适当的错误处理机制 3. **Provider 选择**：根据 AI 框架选择合适的 Provider 以获得最佳集成体验 4. **版本管理**：使用环境变量指定具体工具包版本以便复现性 5. **本地工具**：利用 `@composio/cli-local-tools` 扩展 CLI 功能 资料来源：[ts/packages/providers/README.md]() --- ## Python SDK 详解 ### 相关页面 相关主题：[TypeScript SDK 详解](#ts-sdk), [AI 框架提供商集成](#providers), [工具包系统](#toolkits)
相关源码文件 以下源码文件用于生成本页说明： - [python/README.md](https://github.com/ComposioHQ/composio/blob/main/python/README.md) - [python/scripts/README.md](https://github.com/ComposioHQ/composio/blob/main/python/scripts/README.md) - [python/providers/claude_agent_sdk/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/claude_agent_sdk/README.md) - [python/providers/google/README.md](https://github.com/ComposioHQ/composio/blob/main/python/providers/google/README.md) - [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts) - [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts) - [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)
# Python SDK 详解 ## 概述 Composio Python SDK 是一个强大的工具集成框架，为开发者提供了与外部服务（如 GitHub、Gmail、Google 等）交互的统一接口。该 SDK 允许 AI 代理通过标准化的工具调用方式访问数百种第三方服务，同时支持自定义提供者、本地工具和复杂的认证配置。资料来源：[python/README.md]() ## 核心架构 ### SDK 初始化 Composio SDK 的初始化是整个集成的起点，支持多种配置选项： ```python from composio import Composio from composio.providers.openai import OpenAIProvider composio = Composio( api_key="your-api-key", # Composio API 密钥 base_url="https://api.composio.dev", # 自定义 API 基础 URL timeout=60, # 请求超时时间（秒） max_retries=3, # 最大重试次数 allow_tracking=True, # 启用/禁用遥测 file_download_dir="./downloads", # 文件下载目录 provider=OpenAIProvider(), # 自定义提供者 toolkit_versions={"github": "12202025_01"} # 工具包版本 ) ``` 资料来源：[python/README.md]() ### 架构流程图 ```mermaid graph TD A[用户代码] --> B[Composio SDK] B --> C[工具获取层] C --> D[提供者层] D --> E{提供者类型} E -->|OpenAI| F[OpenAIProvider] E -->|Claude| G[ClaudeAgentSDKProvider] E -->|Google| H[GoogleProvider] F --> I[MCP 服务器] G --> I H --> I I --> J[AI 代理] J --> K[工具执行] K --> L[外部服务 API] ``` ## 工具与工具包系统 ### 工具获取 Composio 提供了灵活的工具获取机制，支持按工具包、工具名称或用户 ID 进行筛选： ```python # 获取特定工具包中的所有工具 tools = composio.tools.get( user_id="default", toolkits=["gmail", "github"] ) # 获取单个工具 tool = composio.tools.get( user_id="default", slug="HACKERNEWS_GET_USER" ) ``` 资料来源：[python/providers/claude_agent_sdk/README.md]() ### 工具分类 | 分类方式 | 说明 | 示例 | |---------|------|------| | 按工具包 | 同一服务的一组工具 | `gmail` 包含 `SEND_EMAIL`, `FETCH_EMAILS` 等 | | 按工具名称 | 单个具体工具 | `GITHUB_STAR_REPOSITORY` | | 按用户 | 按用户隔离的工具实例 | `user_id` 参数控制 | | 本地工具 | CLI 本地执行工具 | `LOCAL_TOOL_*` 前缀 | 资料来源：[ts/packages/cli-local-tools/src/registry.ts]() ## 修饰器系统 Composio SDK 支持强大的修饰器系统，允许在工具模式转换和执行过程中进行干预。 ### 模式修饰器 模式修饰器（Schema Modifiers）允许在工具模式被使用前进行转换： ```python from composio import schema_modifier from composio.types import Tool @schema_modifier(tools=["HACKERNEWS_GET_USER"]) def modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool: schema["description"] = "Enhanced HackerNews user lookup" schema["parameters"]["properties"]["include_karma"] = { "type": "boolean", "description": "Include user karma in response", "default": True } return schema # 使用修饰器获取工具 tools = composio.tools.get( user_id="default", slug="HACKERNEWS_GET_USER", modifiers=[modify_schema] ) ``` 资料来源：[python/README.md]() ### 执行修饰器 执行修饰器允许在工具执行前和执行后进行拦截处理： ```python from composio import before_execute, after_execute @before_execute(tools=["GITHUB_CREATE_ISSUE"]) def validate_issue_params(context): # 执行前验证参数 return context.params @after_execute(tools=["GITHUB_CREATE_ISSUE"]) def process_issue_result(context): # 执行后处理结果 return context.result ``` 资料来源：[python/README.md]() ### 修饰器类型系统 ```typescript export type ProviderOptions = TProvider extends BaseComposioProvider ? TProvider extends BaseAgenticProvider ? AgenticToolOptions : ToolOptions : never; ``` 资料来源：[ts/packages/core/src/types/modifiers.types.ts]() ## 提供者系统 ### 提供者架构 Composio SDK 使用提供者模式来适配不同的 AI 框架： ```mermaid classDiagram class BaseComposioProvider { <> +wrapTool() +getTools() +getToolBySlug() } class BaseNonAgenticProvider { +wrapTool(toolSlug, tool, modifiers?) } class BaseAgenticProvider { +wrapTool(toolSlug, tool, modifiers?) +create_mcp_server() } class OpenAIProvider { +wrapTool() } class ClaudeAgentSDKProvider { +wrapTool() +create_mcp_server() } class GoogleProvider { +wrapTool() } BaseComposioProvider <|-- BaseNonAgenticProvider BaseComposioProvider <|-- BaseAgenticProvider BaseNonAgenticProvider <|-- OpenAIProvider BaseAgenticProvider <|-- ClaudeAgentSDKProvider BaseAgenticProvider <|-- GoogleProvider ``` ### OpenAI Provider 标准的 OpenAI 提供者实现： ```python from composio import Composio from composio.providers.openai import OpenAIProvider composio = Composio(provider=OpenAIProvider()) tools = composio.tools.get(user_id="default", toolkits=["github"]) ``` 资料来源：[python/README.md]() ### Claude Agent SDK Provider 与 Claude Code Agents SDK 的集成： ```python import asyncio from composio import Composio from composio_claude_agent_sdk import ClaudeAgentSDKProvider from claude_agent_sdk import query, ClaudeAgentOptions composio = Composio(provider=ClaudeAgentSDKProvider()) async def main(): tools = composio.tools.get( user_id="default", toolkits=["gmail"], ) mcp_server = composio.provider.create_mcp_server(tools) async for message in query( prompt="Fetch my latest email from Gmail", options=ClaudeAgentOptions( mcp_servers={"composio": mcp_server} ) ): print(message) ``` 资料来源：[python/providers/claude_agent_sdk/README.md]() ### Google Provider 与 Google AI 的集成示例： ```python from composio import ComposioToolset from composio.google import App toolset = ComposioToolset() actions = toolset.get_tools(apps=[App.GITHUB]) task = "Star a repo composiohq/composio on GitHub" response = chat.send_message(task) result = toolset.handle_response(response) ``` 资料来源：[python/providers/google/README.md]() ### 创建自定义提供者 ```typescript // 非代理类型提供者 class NonAgenticProvider extends BaseNonAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise; async getTools(modifiers?: SchemaModifiersParams): Promise; async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise; } // 代理类型提供者 class AgenticProvider extends BaseAgenticProvider { async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise; async getTools(modifiers?: ModifiersParams): Promise; async create_mcp_server(tools: Tool[]): Promise; } ``` 资料来源：[ts/packages/providers/README.md]() ## 本地工具系统 ### 本地工具注册表 Composio CLI 本地工具系统使用注册表模式管理本地可执行工具： ```typescript export const getAllLocalToolkitSlugs = ( options: { readonly declarations?: ReadonlyArray } = {} ): ReadonlyArray => declarationsFor(options.declarations).map(toolkit => toolkit.slug.toLowerCase()); ``` ### 本地工具标识 本地工具使用特殊前缀进行标识： ```typescript const LOCAL_TOOL_PREFIX = "LOCAL_TOOL_"; const normalizeLocalToolSlug = ( toolSlug: string, toolkitSlug?: string ): string => toolkitSlug ? `${LOCAL_TOOL_PREFIX}${normalizeSegment(toolkitSlug)}_${normalizeSegment(toolSlug)}` : `${LOCAL_TOOL_PREFIX}${normalizeSegment(toolSlug)}`; ``` ### 本地工具过滤 ```typescript const toolkitMatchesFilter = ( toolkit: LocalToolkitDeclaration, requestedToolkits?: ReadonlyArray ): boolean => { if (!requestedToolkits || requestedToolkits.length === 0) return true; const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase())); return requested.has(toolkit.slug.toLowerCase()); }; ``` 资料来源：[ts/packages/cli-local-tools/src/registry.ts]() ## 工具包管理 ### 工具包发现命令 CLI 提供了完整的工具包管理命令： ```bash # 列出所有可用工具包 composio toolkits list # 查看工具包详情 composio toolkits info # 搜索工具包 composio toolkits search # 查看工具包版本 composio toolkits version ``` 资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts]() ### 工具包索引创建 ```mermaid graph LR A[工具数据] --> B[groupByToolkits] B --> C[Record.fromEntries] C --> D[Record.mapEntries] D --> E[ToolkitIndex] F[版本映射] --> D ``` 工具包索引数据结构： ```typescript export type ToolkitIndexData = Simplify<{ slug: string; version?: string; typeableTools: | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> } | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> }; triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>; }>; export type ToolkitIndex = Record; ``` 资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts]() ## 认证与账户管理 ### 工具权限请求 当执行需要认证的工具时，系统会启动权限请求流程： ```typescript const requestPermissionInBrowser = (params: { readonly toolSlug: string; readonly accountLabel?: string; }): Promise => new Promise((resolve, reject) => { const token = crypto.randomUUID(); // 启动 HTTP 服务器等待用户响应 }); ``` 权限选项包括： | 选项 | 说明 | |------|------| | Allow for this session | 本次会话内允许所有调用 | | Allow once | 仅允许本次调用 | | Deny | 拒绝本次调用 | 资料来源：[ts/packages/cli/src/services/tool-permissions.ts]() ### 账户链接 ```bash # 链接工具包账户 composio link ``` ## 项目初始化 ### 初始化流程 ```mermaid sequenceDiagram participant User participant CLI participant API participant FileSystem User->>CLI: composio init CLI->>API: 获取会话信息 API-->>CLI: 返回 API 密钥 CLI->>FileSystem: 创建 .env.local FileSystem-->>CLI: 确认文件创建 CLI->>User: 显示成功消息 ``` 初始化过程会自动： 1. 检测项目环境（TypeScript/Python） 2. 创建本地环境文件 `.env.local` 3. 配置项目 API 密钥 4. 设置测试用户 ID ```bash composio dev init ``` 资料来源：[ts/packages/cli/src/commands/init.cmd.ts]() ## SDK 文档生成 ### Python 文档生成器 使用 Griffe 从 Python 源码提取文档： ```bash cd python uv run --with griffe python scripts/generate-docs.py ``` 生成流程： ```mermaid graph LR A[composio/**/*.py] -->|griffe| B[结构化数据] B -->|generate-docs.py| C[MDX 文件] C --> D[docs/content/reference/sdk-reference/python/] ``` ### 配置选项 | 配置项 | 说明 | |--------|------| | `EXPECTED_CLASSES` | 类名到 Composio 属性的映射 | | `CLASS_MODULES` | 要搜索的模块列表 | | `DECORATORS_TO_DOCUMENT` | 要记录的装饰器列表 | 资料来源：[python/scripts/README.md]() ## 常见使用模式 ### 基础工具调用 ```python from composio import Composio composio = Composio() # 获取工具 tools = composio.tools.get( user_id="user123", toolkits=["github"] ) # 执行工具 result = composio.tools.execute( tool_name="GITHUB_STAR_REPOSITORY", params={ "owner": "composiohq", "repo": "composio" } ) ``` ### 触发器使用 ```bash # 列出触发器 composio triggers list # 查看触发器详情 composio triggers info ``` ### 开发调试 ```bash # 在 Playground 中执行 composio dev playground-execute "" --user-id "" # 查看工具日志 composio dev logs tools # 查看触发器日志 composio dev logs triggers ``` ## 配置参考 ### 初始化参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `api_key` | string | 必需 | Composio API 密钥 | | `base_url` | string | `https://api.composio.dev` | API 基础 URL | | `timeout` | int | 60 | 请求超时（秒） | | `max_retries` | int | 3 | 最大重试次数 | | `allow_tracking` | bool | True | 启用遥测 | | `file_download_dir` | string | `./downloads` | 下载目录 | | `provider` | Provider | OpenAIProvider | AI 提供者 | | `toolkit_versions` | dict | {} | 工具包版本映射 | ### 环境变量 | 变量名 | 说明 | |--------|------| | `COMPOSIO_API_KEY` | Composio API 密钥 | | `COMPOSIO_TEST_USER_ID` | 测试用户 ID | | `ANTHROPIC_API_KEY` | Claude API 密钥（使用 Claude Provider 时） | ## 相关资源 - [官方文档](https://docs.composio.dev) - [Discord 社区](https://discord.gg/composio) - [GitHub Issues](https://github.com/composio/composio/issues) --- ## 工具包系统 ### 相关页面 相关主题：[自定义工具开发](#custom-tools), [TypeScript SDK 详解](#ts-sdk), [Python SDK 详解](#py-sdk)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts) - [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts) - [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts) - [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts) - [ts/packages/cli/src/effects/toolkit-version-overrides.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts) - [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)
# 工具包系统 ## 概述 工具包系统（Toolkit System）是 Composio 框架的核心组件之一，负责组织和封装一组相关的工具（Tools），供 AI Agent 在执行任务时调用。每个工具包代表一个功能领域，如 Gmail、Slack、GitHub 等，为 Agent 提供与外部服务交互的能力。 工具包系统的主要职责包括： - **工具组织**：将相关工具归类到同一个工具包中，便于管理和发现 - **版本管理**：支持同一工具包的多个版本，允许开发者使用特定版本或最新版本 - **本地工具支持**：提供本地 CLI 工具包扩展，允许在本地环境中执行自定义工具 - **权限管理**：为每个工具包的执行提供权限控制和确认机制 ## 架构设计 ### 核心组件关系 ```mermaid graph TD subgraph "工具包系统架构" A[ToolkitIndex] --> B[ToolkitName] A --> C[ToolIndex] D[Tool] --> E[Action] F[TriggerType] --> G[Trigger] H[LocalToolkitDeclaration] --> I[LocalTool] end subgraph "提供者层" J[BaseComposioProvider] --> K[BaseAgenticProvider] J --> L[NonAgenticProvider] K --> M[SchemaModifiersParams] L --> N[ToolOptions] end ``` ### 工具包索引结构 工具包索引（ToolkitIndex）是一个 TypeScript 类型别名，定义为： ```typescript export type ToolkitIndex = Record; ``` `ToolkitIndexData` 包含以下字段： | 字段 | 类型 | 说明 | |------|------|------| | `slug` | `string` | 工具包唯一标识符 | | `version` | `string \| undefined` | 版本覆盖（仅当非 'latest' 时存在） | | `typeableTools` | `Record<${ToolkitName}_${string}, Tool>` | 工具集合（带类型或不带类型） | | `triggerTypes` | `Record<${ToolkitName}_${string}, TriggerType>` | 触发器类型集合 | 资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:1-18]() ### 工具包索引创建流程 ```mermaid sequenceDiagram participant Input as CreateToolkitIndexInput participant Group as groupByToolkits participant Map as Record.mapEntries participant Output as ToolkitIndex Input->>Group: 原始工具数据 Group->>Group: 按工具包名称分组 Group->>Map: 分组后的数据 Map->>Map: 提取版本覆盖 Map->>Map: 处理类型化工具 Map->>Output: 最终索引结构 ``` ## 工具包类型 ### 远程工具包 远程工具包（Remote Toolkits）是由 Composio 服务器托管的工具包，通过 API 获取工具定义和执行能力。 **特性**： - 集中管理和更新 - 支持版本控制 - 可通过 CLI 命令查询和操作 ### 本地工具包 本地工具包（Local Toolkits）是在本地环境中运行的工具包，允许开发者定义自定义工具直接在本地执行。 **核心数据结构**： ```typescript interface LocalToolkitDeclaration { slug: string; name: string; description: string; platforms: ReadonlyArray; tools: ReadonlyArray; setup?: LocalToolkitSetup; source?: ToolkitSource; } ``` 资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-50]() **本地工具注册流程**： ```mermaid graph TD A[LocalToolkitDeclaration] --> B{requestedToolkits存在?} B -->|是| C[转为小写Set] B -->|否| D[返回true] C --> E{slug小写化} E --> F{包含在requested中?} F -->|是| D F -->|否| G[返回false] ``` ## 版本管理 ### 版本覆盖机制 工具包版本覆盖允许开发者在配置中指定特定工具包的版本，而不是使用默认的最新版本。 **配置格式**： ```typescript type ToolkitVersionOverrides = Map, string>; ``` **版本分组逻辑**： ```mermaid graph LR A[ToolkitVersionSpec] --> B{版本为latest?} B -->|是| C[跳过] B -->|否| D[添加到versionMap] A --> E[groupByVersion] E --> F[Map: version -> slugs[]] ``` **核心函数**： ```typescript export const buildVersionMapFromSpecs = ( specs: ReadonlyArray ): ToolkitVersionOverrides => { const versionMap = new Map, string>(); for (const spec of specs) { if (spec.toolkitVersion !== 'latest') { versionMap.set(spec.toolkitSlug, spec.toolkitVersion); } } return versionMap; }; ``` 资料来源：[ts/packages/cli/src/effects/toolkit-version-overrides.ts:1-40]() ### 版本验证 Composio 提供了版本验证机制，确保指定的版本覆盖有效： - 验证工具包标识符是否正确 - 检查指定版本是否存在 - 对无效版本提供友好的错误提示 ## CLI 命令 ### 工具包发现命令 `composio toolkits` 是工具包发现命令的入口点，支持以下子命令： | 命令 | 说明 | |------|------| | `toolkits list` | 列出所有可用的工具包 | | `toolkits info` | 显示特定工具包的详细信息 | | `toolkits search` | 搜索工具包 | | `toolkits version` | 管理工具包版本 | 资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:1-25]() ### 命令示例 ```bash # 列出所有工具包 composio tools list # 查看特定工具包信息 composio tools info "" # 执行工具包中的工具 composio execute "" -d '{}' # 获取工具执行模式 composio execute "" --get-schema # 链接账户 composio link ``` 资料来源：[ts/packages/cli/src/services/command-hints.ts:1-50]() ## 提供者集成 ### 提供者类型层次 ```mermaid classDiagram class BaseComposioProvider~TToolCollection, TTool, TMcpResponse~ { <> } class BaseAgenticProvider~TToolCollection, TTool, TMcpResponse~ { <> } class NonAgenticProvider { ToolOptions } class AgenticProvider { AgenticToolOptions } BaseComposioProvider <|-- BaseAgenticProvider BaseComposioProvider <|-- NonAgenticProvider BaseAgenticProvider <|-- AgenticProvider ``` ### 提供者选项类型 ```typescript export type ProviderOptions = TProvider extends BaseComposioProvider ? TProvider extends BaseAgenticProvider ? AgenticToolOptions : ToolOptions : never; ``` 资料来源：[ts/packages/core/src/types/modifiers.types.ts:1-20]() ### 创建自定义提供者 开发者可以通过以下命令创建新的提供者： ```bash # 创建非代理提供者 pnpm create:provider # 创建代理提供者 pnpm create:provider --agentic ``` **生成的文件结构**： ``` / ├── src/ │ └── index.ts # 提供者实现 ├── package.json # 包配置 ├── tsconfig.json # TypeScript 配置 ├── tsup.config.ts # 构建配置 └── README.md # 文档 ``` **必需方法（非代理提供者）**： ```typescript class NonAgenticProvider extends BaseNonAgenticProvider { async wrapTool( toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams ): Promise; async getTools(modifiers?: SchemaModifiersParams): Promise; async getToolBySlug( slug: string, modifiers?: SchemaModifiersParams ): Promise; } ``` **必需方法（代理提供者）**： ```typescript class AgenticProvider extends BaseAgenticProvider { async wrapTool( toolSlug: string, tool: Tool, modifiers?: ModifiersParams ): Promise; async getTools(modifiers?: ModifiersParams): Promise; } ``` 资料来源：[ts/packages/providers/README.md:1-80]() ## 本地工具配置 ### 本地工具元数据管理 本地工具支持通过 `local_tools.json` 文件进行配置： ```json { "toolkits": { "": { "disabled": false, "installation": { "command": "npm install my-toolkit" } } }, "tools": { "": { "disabled": false, "authenticated": true, "installation": { "command": "pip install my-tool" } } } } ``` ### 工具包就绪状态检查 ```mermaid graph TD A[开始就绪检查] --> B{平台支持?} B -->|否| C[status: unsupported] B -->|是| D{工具包禁用?} D -->|是| E[status: disabled] D -->|否| F[检查工具状态] F --> G{所有工具就绪?} G -->|是| H[status: ready] G -->|否| I[status: needs_setup] ``` **就绪状态类型**： | 状态 | 说明 | 可能原因 | |------|------|----------| | `ready` | 可用 | 所有依赖已安装 | | `disabled` | 已禁用 | 在配置中被禁用 | | `unsupported` | 不支持 | 当前平台不兼容 | | `needs_setup` | 需设置 | 部分工具未配置 | ## 权限管理 ### 权限确认流程 ```mermaid sequenceDiagram participant Agent as AI Agent participant CLI as Composio CLI participant Server as Permission Server participant User as User Agent->>CLI: 请求执行工具 CLI->>Server: 发起权限请求 Server->>User: 显示确认页面 User->>Server: 选择操作 Server-->>CLI: 返回决策 CLI->>CLI: 执行或拒绝 ``` ### 权限决策选项 | 选项 | 说明 | 有效期 | |------|------|--------| | Allow for this session | 允许 | 当前会话 | | Allow once | 允许一次 | 单次执行 | | Deny | 拒绝 | 单次执行 | 资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-80]() ## 数据模型 ### 工具包模型（Python） ```python class Toolkit(BaseModel, Generic[Tool]): id: str name: str description: str slug: str logo: Optional[str] version: str categories: List[str] tools: List[Tool] enabled: bool = True def get_action(self, action_slug: str) -> Tool: ... def filter_tools(self, actions: List[str]) -> "Toolkit[Tool]": ... ``` ### 自定义工具模型 ```typescript export interface CustomTool { slug: string; name: string; description: string; inputParams: Param[]; outputParams?: Param[]; execute: (input: Record) => Promise; } ``` ## 工作流程 ### 工具包发现与执行流程 ```mermaid graph TD A[开发者请求工具包] --> B{本地工具包?} B -->|是| C[查询本地注册表] B -->|否| D[调用 API 获取] C --> E{工具包存在?} D --> F{工具包存在?} E -->|否| G[返回错误] F -->|否| G E -->|是| H[验证版本] F -->|是| H H --> I{版本有效?} I -->|否| J[返回警告] I -->|是| K[加载工具定义] K --> L[检查权限] L --> M{权限已授权?} M -->|否| N[请求确认] M -->|是| O[执行工具] N --> P[用户确认] P -->|允许| O P -->|拒绝| Q[终止] ``` ## 配置参考 ### 环境变量配置 | 变量 | 说明 | 示例 | |------|------|------| | `COMPOSIO_API_KEY` | API 密钥 | `sk-xxx` | | `COMPOSIO_TOOLKIT_VERSION_*` | 工具包版本覆盖 | `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00` | ### CLI 配置选项 | 选项 | 说明 | 默认值 | |------|------|--------| | `--compact` | 生成单模块文件 | false | | `--transpiled` | 生成转译后的 JS | 依赖输出目录 | | `--output-dir` | 输出目录 | node_modules/@composio/core | | `--toolkits` | 过滤工具包 | 全部 | ## 最佳实践 ### 工具包开发 1. **遵循命名约定**：工具包 slug 应使用小写字母和连字符 2. **版本控制**：在 `package.json` 中指定版本范围 3. **平台支持**：明确声明支持的平台列表 4. **错误处理**：提供有意义的错误消息和恢复建议 ### 性能优化 1. **按需加载**：使用工具包过滤避免加载全部工具 2. **版本锁定**：在生产环境中使用固定版本而非 'latest' 3. **本地缓存**：利用本地工具包减少网络请求 ## 相关资源 - [自定义工具和工具包文档](https://github.com/ComposioHQ/composio/blob/main/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx) - [工具包索引文档](https://github.com/ComposioHQ/composio/blob/main/docs/content/toolkits/index.mdx) - [CLI 工具命令参考](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts) - [版本覆盖机制](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/effects/toolkit-version-overrides.ts) --- ## 自定义工具开发 ### 相关页面 相关主题：[工具包系统](#toolkits), [MCP 协议集成](#mcp)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/core/src/models/CustomTools.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/CustomTools.ts) - [python/composio/core/models/custom_tools.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/custom_tools.py) - [ts/examples/custom-tools/src/simple.ts](https://github.com/ComposioHQ/composio/blob/main/ts/examples/custom-tools/src/simple.ts) - [python/examples/custom_tools.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/custom_tools.py) - [docs/content/docs/tools-direct/custom-tools.mdx](https://github.com/ComposioHQ/composio/blob/main/docs/content/docs/tools-direct/custom-tools.mdx)
# 自定义工具开发 ## 概述 自定义工具（Custom Tools）允许开发者扩展 Composio 的工具生态系统，创建符合特定业务需求的专用工具。通过自定义工具接口，开发者可以定义工具的名称、描述、输入输出参数以及具体的执行逻辑，从而实现与外部系统或内部服务的集成。 Composio 支持多种工具创建方式，包括基于函数的自定义工具、工具包（Toolkit）组合以及本地 CLI 工具集成。这种灵活性使得开发者能够根据不同的使用场景选择最合适的工具定义方式。 ## 核心概念 ### 自定义工具的数据结构 自定义工具的核心模型包含以下关键属性： | 属性名 | 类型 | 描述 | |--------|------|------| | `name` | string | 工具的显示名称 | | `description` | string | 工具功能的详细描述 | | `slug` | string | 工具的唯一标识符 | | `inputParams` | InputParams | 工具的输入参数定义 | | `outputParams` | OutputParams | 工具的输出参数定义（可选） | | `execute` | ExecuteFunction | 工具的执行逻辑 | ### 工具包（Toolkit） 工具包是多个相关工具的集合，用于组织和管理具有相似功能或服务于同一目标的自定义工具。工具包提供了更高层次的抽象，便于批量处理和分类管理。 ## 架构设计 ### 工具执行流程 ```mermaid graph TD A[用户请求执行工具] --> B[验证输入参数] B --> C{参数校验} C -->|通过| D[权限检查] C -->|失败| E[返回错误] D --> F{权限状态} F -->|已授权| G[执行工具逻辑] F -->|需授权| H[请求权限] H --> I{用户授权} I -->|允许| G I -->|拒绝| J[返回拒绝错误] G --> K[返回执行结果] K --> L[记录执行日志] ``` ### 工具创建流程 ```mermaid graph TD A[定义工具元数据] --> B[创建工具实例] B --> C[配置执行函数] C --> D[注册到工具系统] D --> E[可用性验证] E --> F[工具已就绪] ``` ## TypeScript 实现 ### 创建自定义工具 在 TypeScript 中，使用 `createCustomTool` 函数创建自定义工具。该函数接受工具的唯一标识符（slug）和一个配置对象。 ```typescript import { createCustomTool } from '@composio/core'; const myTool = createCustomTool({ slug: 'my-custom-tool', name: 'My Custom Tool', description: 'Executes custom logic based on provided parameters', inputParams: { param1: { type: 'string', description: 'First parameter', required: true, }, param2: { type: 'number', description: 'Second parameter', required: false, default: 42, }, }, execute: async (params) => { // 自定义执行逻辑 const result = await performOperation(params.param1, params.param2); return result; }, }); ``` ### 创建自定义工具包 使用 `createCustomToolkit` 函数将多个相关工具组合成一个工具包： ```typescript import { createCustomToolkit } from '@composio/core'; const myToolkit = createCustomToolkit('my-toolkit', { name: 'My Custom Toolkit', description: 'A collection of custom tools for my use case', tools: [myTool, anotherTool, thirdTool], }); ``` ### 本地 CLI 工具 对于需要本地执行的工具，Composio 提供了本地工具声明机制： ```typescript import { LocalToolDeclaration, LocalToolkitDeclaration, executeLocalTool } from '@composio/cli-local-tools'; const localTool: LocalToolDeclaration = { slug: 'local-command', name: 'Local Command Tool', description: 'Executes a local shell command', inputParams: { command: { type: 'string', description: 'The command to execute', required: true, }, }, execution: { type: 'command', command: async (params) => { const { exec } = await import('child_process'); return new Promise((resolve, reject) => { exec(params.command, (error, stdout, stderr) => { if (error) reject(error); else resolve({ stdout, stderr }); }); }); }, }, }; ``` 本地工具支持多种执行类型，包括命令执行、脚本执行和函数执行。平台支持情况通过 `platforms` 属性进行配置。 ## Python 实现 ### 创建自定义工具 在 Python 中，使用 `CustomTool` 类创建自定义工具： ```python from composio import CustomTool, InputParam my_tool = CustomTool( name="my_custom_tool", description="Executes custom logic based on provided parameters", parameters={ "param1": InputParam( type="string", description="First parameter", required=True ), "param2": InputParam( type="number", description="Second parameter", required=False, default=42 ) }, action=lambda params: perform_operation( params["param1"], params.get("param2", 42) ) ) ``` ### 创建自定义工具包 使用 `CustomToolkit` 类组合多个工具： ```python from composio import CustomToolkit my_toolkit = CustomToolkit( name="my_custom_toolkit", description="A collection of custom tools", tools=[my_tool, another_tool] ) ``` ### 异步执行支持 Python 版本支持异步工具定义： ```python import asyncio from composio import CustomTool async_tool = CustomTool( name="async_tool", description="An asynchronous tool", parameters={ "url": InputParam(type="string", description="URL to fetch") }, action=lambda params: asyncio.to_thread(fetch_data, params["url"]) ) ``` ## 输入参数配置 ### 参数类型 | 类型 | 描述 | 适用场景 | |------|------|----------| | `string` | 字符串类型参数 | 文本输入、URL、标识符 | | `number` | 数值类型参数 | 数量、索引、阈值 | | `boolean` | 布尔类型参数 | 开关选项、标志位 | | `object` | 对象类型参数 | 复杂配置、嵌套数据 | | `array` | 数组类型参数 | 列表输入、多选项 | ### 参数属性 | 属性 | 类型 | 描述 | |------|------|------| | `type` | string | 参数的数据类型 | | `description` | string | 参数用途说明 | | `required` | boolean | 是否必填，默认 false | | `default` | any | 默认值 | | `enum` | array | 枚举可选值 | ## 工具权限管理 Composio 提供了工具权限验证机制，确保工具执行的安全性： ```mermaid sequenceDiagram participant Client participant Composio participant Tool participant User Client->>Composio: 请求执行工具 Composio->>Tool: 验证权限 Tool-->>Composio: 需要授权 Composio->>User: 展示权限请求 User-->>Composio: 授权决策 alt 已授权 Composio->>Tool: 执行工具 Tool-->>Client: 返回结果 else 未授权 Composio-->>Client: 返回权限错误 end ``` 权限请求支持三种模式： | 模式 | 描述 | |------|------| | 会话级授权 | 允许在当前会话中重复执行 | | 单次授权 | 仅允许本次执行 | | 拒绝 | 阻止本次执行 | ## 工具发现与注册 ### 注册表机制 Composio 维护一个工具注册表，用于管理所有可用的工具和工具包： | 函数 | 用途 | |------|------| | `getLocalToolkitDeclarations` | 获取本地工具包声明列表 | | `getLocalCustomToolkits` | 获取本地自定义工具包 | | `isLocalToolkitSlug` | 验证工具包标识符是否有效 | | `isLocalToolSlug` | 验证工具标识符是否有效 | ### 工具过滤 支持按工具包名称过滤工具： ```typescript const declarations = getLocalToolkitDeclarations({ toolkits: ['gmail', 'slack'], currentPlatform: 'linux', }); ``` ## 最佳实践 ### 工具设计原则 1. **单一职责**：每个工具应专注于完成一个特定任务 2. **清晰的描述**：提供详尽的工具和参数描述，便于 AI 理解 3. **适当的参数**：避免过多必填参数，提供合理的默认值 4. **错误处理**：在执行函数中妥善处理异常情况 5. **类型安全**：使用正确的参数类型并提供验证 ### 命名规范 | 元素 | 规范 | 示例 | |------|------|------| | 工具名称 | 小写下划线分隔 | `fetch_user_data` | | 工具包名称 | 小写下划线分隔 | `user_management` | | 参数名称 | 小写下划线分隔 | `user_id` | | 枚举值 | 小写下划线分隔 | `status_active` | ### 安全性考虑 - 避免在工具描述中包含敏感信息 - 对外部输入进行严格验证 - 使用环境变量存储凭据而非硬编码 - 实现最小权限原则 ## 示例项目 ### TypeScript 完整示例 ```typescript import { createCustomTool, createCustomToolkit } from '@composio/core'; // 定义数据获取工具 const fetchData = createCustomTool('fetch_data', { name: 'Fetch Data', description: '从指定源获取数据', inputParams: { source: { type: 'string', description: '数据源标识', required: true, }, format: { type: 'string', description: '返回格式 (json/xml)', required: false, default: 'json', }, }, execute: async (params) => { const response = await fetch(`${params.source}?format=${params.format}`); return response.json(); }, }); // 定义数据处理工具 const processData = createCustomTool('process_data', { name: 'Process Data', description: '处理和分析数据', inputParams: { data: { type: 'object', description: '待处理的数据对象', required: true, }, operation: { type: 'string', description: '操作类型 (transform/filter/aggregate)', required: true, }, }, execute: async (params) => { return applyOperation(params.data, params.operation); }, }); // 创建工具包 const dataToolkit = createCustomToolkit('data_processing', { name: 'Data Processing Toolkit', description: '数据获取和处理工具集', tools: [fetchData, processData], }); ``` ### Python 完整示例 ```python from composio import CustomTool, CustomToolkit, InputParam # 定义文件操作工具 file_tool = CustomTool( name="file_operations", description="文件系统操作工具", parameters={ "operation": InputParam( type="string", description="操作类型 (read/write/delete)", required=True, enum=["read", "write", "delete"] ), "path": InputParam( type="string", description="文件路径", required=True ), "content": InputParam( type="string", description="文件内容 (write操作时需要)", required=False ) }, action=lambda params: execute_file_operation( params["operation"], params["path"], params.get("content") ) ) # 创建工具包 file_toolkit = CustomToolkit( name="file_operations_kit", description="文件系统操作工具集", tools=[file_tool] ) ``` ## 调试与测试 ### 本地工具诊断 Composio CLI 提供了工具诊断命令： ```bash # 检查工具就绪状态 composio local-tools doctor --toolkits # 列出所有本地工具 composio local-tools list --all-platforms ``` ### 日志查看 查看工具执行日志： ```bash # 查看工具执行日志 composio dev logs tools # 查看触发器执行日志 composio dev logs triggers ``` ## 集成与使用 ### 在代理中使用自定义工具 ```typescript import { Composio } from '@composio/core'; const client = Composio(); // 注册自定义工具包 client.register(myToolkit); // 获取配置好的代理 const agent = client.getAgent({ instruction: '使用我的自定义工具完成数据处理任务', }); ``` ### 配置本地工具元数据 通过 `~/composio/local_tools.json` 配置文件自定义工具行为： ```json { "toolkits": { "my-toolkit": { "disabled": false, "installation": { "command": "pip install my-toolkit-dependency" } } } } ``` ## 相关资源 - 官方文档：[Custom Tools Guide](https://docs.composio.dev/tools-direct/custom-tools) - TypeScript 示例：[ts/examples/custom-tools](https://github.com/ComposioHQ/composio/tree/main/ts/examples/custom-tools) - Python 示例：[python/examples/custom_tools.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/custom_tools.py) - API 参考：[CustomTools.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/CustomTools.ts) --- ## AI 框架提供商集成 ### 相关页面 相关主题：[TypeScript SDK 详解](#ts-sdk), [Python SDK 详解](#py-sdk), [MCP 协议集成](#mcp)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md) - [ts/packages/core/src/types/modifiers.types.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/types/modifiers.types.ts) - [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts) - [ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts) - [ts/packages/cli/src/services/terminal-ui.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/terminal-ui.ts) - [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)
# AI 框架提供商集成 ## 概述 AI 框架提供商（Provider）是 Composio 架构中的核心抽象层，负责将 Composio 的工具和功能与各类 AI 框架（如 OpenAI、Anthropic、LangChain 等）进行集成。提供商层作为中间件，封装了工具的获取、包装和执行逻辑，使开发者能够以统一的方式在不同的 AI 框架中使用 Composio 的工具集合。 Composio 的提供商系统设计为可扩展的架构，支持两种类型的提供商： - **非代理型提供商（Non-Agentic Provider）**：适用于直接将工具集成到 AI 框架的场景 - **代理型提供商（Agentic Provider）**：适用于需要更复杂代理行为和上下文管理的场景 资料来源：[ts/packages/providers/README.md:1-30]() ## 架构设计 ### 整体架构图 ```mermaid graph TD subgraph "客户端层" User[用户应用] CLI[Composio CLI] end subgraph "提供商层" OpenAIProv[OpenAI Provider] AnthropicProv[Anthropic Provider] LangChainProv[LangChain Provider] CustomProv[自定义 Provider] end subgraph "核心层" BaseNonAgentic[BaseNonAgenticProvider] BaseAgentic[BaseAgenticProvider] BaseComposio[BaseComposioProvider] end subgraph "工具层" Tools[Composio 工具集] Toolkits[工具包] Triggers[触发器] end User --> OpenAIProv User --> AnthropicProv User --> LangChainProv CLI --> BaseAgentic OpenAIProv --> BaseNonAgentic AnthropicProv --> BaseNonAgentic LangChainProv --> BaseAgentic CustomProv --> BaseComposio BaseNonAgentic --> Tools BaseAgentic --> Tools BaseComposio --> Tools ``` ### 提供商继承体系 ```mermaid graph LR A[BaseComposioProvider] --> B[BaseAgenticProvider] A --> C[BaseNonAgenticProvider] B --> D[Agentic Provider 实现] C --> E[Non-Agentic Provider 实现] ``` ## 提供商类型系统 ### 类型层次结构 Composio 使用 TypeScript 的条件类型系统来定义提供商的选项类型，确保类型安全性和正确的继承关系。 ```typescript export type ProviderOptions = TProvider extends BaseComposioProvider ? TProvider extends BaseAgenticProvider ? AgenticToolOptions : ToolOptions : never; ``` 资料来源：[ts/packages/core/src/types/modifiers.types.ts:1-50]() ### Schema 修饰器 提供商支持通过 Schema 修饰器来修改工具的输入输出格式： ```typescript _GET_REPOS', { modifySchema: (context) => context.schema, beforeExecute: (context) => context.params, afterExecute: (context) => context.result }); ``` ## 非代理型提供商 ### 必需方法 非代理型提供商必须实现以下接口： ```typescript class NonAgenticProvider extends BaseNonAgenticProvider { // 使用 Schema 修饰器包装工具 async wrapTool( toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams ): Promise; // 获取所有可用工具 async getTools(modifiers?: SchemaModifiersParams): Promise; // 根据 slug 获取特定工具 async getToolBySlug( slug: string, modifiers?: SchemaModifiersParams ): Promise; } ``` ### 使用场景 非代理型提供商适用于以下场景： | 场景 | 描述 | 示例 | |------|------|------| | 简单工具调用 | 直接调用单个工具 | `provider.getToolBySlug('gmail_send_email')` | | 批量工具获取 | 获取多个工具进行处理 | `provider.getTools()` | | Schema 定制 | 修改工具的输入输出结构 | 使用 `modifiers` 参数 | 资料来源：[ts/packages/providers/README.md:30-50]() ## 代理型提供商 ### 必需方法 代理型提供商需要实现更复杂的方法集： ```typescript class AgenticProvider extends BaseAgenticProvider { // 使用修饰器包装工具 async wrapTool( toolSlug: string, tool: Tool, modifiers?: ModifiersParams ): Promise; // 获取所有可用工具 async getTools(modifiers?: ModifiersParams): Promise; } ``` ### 代理型特性 代理型提供商相比非代理型增加了以下能力： - **上下文管理**：自动维护执行上下文和状态 - **触发器支持**：集成 Composio 的触发器系统 - **增强的错误处理**：基于 Effect 的错误处理机制 资料来源：[ts/packages/providers/README.md:50-70]() ## 创建新的提供商 ### 目录结构 使用提供的脚本可以快速创建新的提供商： ```bash # 创建非代理型提供商 pnpm run create-provider # 创建代理型提供商 pnpm run create-provider --agentic ``` 脚本将创建以下目录结构： ``` / ├── src/ │ └── index.ts # 提供商实现 ├── package.json # 包配置 ├── tsconfig.json # TypeScript 配置 ├── tsup.config.ts # 构建配置 └── README.md # 提供商文档 ``` ### 文件模板 **package.json 配置** ```json { "name": "@composio/", "version": "0.0.1", "main": "./dist/index.js", "types": "./dist/index.d.ts" } ``` 资料来源：[ts/packages/providers/README.md:10-30]() ## 工具包装机制 ### 包装流程 ```mermaid sequenceDiagram participant User as 用户 participant Provider as Provider participant Modifiers as Schema修饰器 participant Tool as Composio Tool User->>Provider: wrapTool(toolSlug, tool, modifiers) Provider->>Tool: 加载工具定义 Provider->>Modifiers: 应用 Schema 修改 Modifiers-->>Provider: 修改后的 Schema Provider->>Tool: 应用 beforeExecute 修改 Provider-->>User: 包装后的工具 ``` ### 修饰器参数 | 参数 | 类型 | 描述 | |------|------|------| | `modifySchema` | `Function` | 修改工具的输入输出 Schema | | `beforeExecute` | `Function` | 工具执行前的参数处理 | | `afterExecute` | `Function` | 工具执行后的结果处理 | ## 与 CLI 的集成 ### 命令行接口 Composio CLI 提供了完整的工具执行和查看命令： | 命令 | 描述 | 示例 | |------|------|------| | `composio execute` | 执行指定工具 | `composio execute "gmail_send_email" -d '{}'` | | `composio tools list` | 列出工具包中的工具 | `composio tools list "gmail"` | | `composio tools info` | 查看工具详细信息 | `composio tools info ""` | | `composio execute --get-schema` | 获取工具 Schema | `composio execute "slack_send" --get-schema` | 资料来源：[ts/packages/cli/src/services/command-hints.ts:1-60]() ### 工具权限系统 CLI 提供了交互式权限确认机制： ```mermaid graph TD A[执行工具请求] --> B{权限检查} B -->|已授权| D[执行工具] B -->|未授权| C[浏览器授权页面] C --> E[用户决策] E -->|Allow| F[允许本次会话] E -->|Allow Once| G[仅本次允许] E -->|Deny| H[拒绝执行] ``` 权限页面提供了三个选项： - **Allow for this session**：当前会话内允许所有调用 - **Allow once**：仅允许本次调用 - **Deny**：拒绝本次调用 资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-50]() ## 本地工具集成 ### 注册表架构 本地工具通过注册表系统进行管理，与提供商架构协同工作： ```mermaid graph TD subgraph "本地工具注册表" Decl[工具声明] Toolkit[工具包声明] Platform[平台标识] end Decl --> Toolkit Toolkit --> Platform ``` ### 工具匹配逻辑 ```typescript const toolkitMatchesFilter = ( toolkit: LocalToolkitDeclaration, requestedToolkits?: ReadonlyArray ): boolean => { if (!requestedToolkits || requestedToolkits.length === 0) return true; const requested = new Set(requestedToolkits.map(slug => slug.toLowerCase())); return requested.has(toolkit.slug.toLowerCase()); }; ``` 本地工具 slug 格式为：`LOCAL_TOOL_PREFIX + toolkitSlug + _ + toolSlug` 资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-80]() ### 平台支持 工具可以指定支持的平台集合： ```typescript const descriptionWithPlatform = ( description: string, platforms: ReadonlyArray ): string => `${description}\n\nLocal CLI platforms: ${formatSupportedPlatforms(platforms)}.`; ``` ## 工具包版本管理 ### 版本覆盖机制 Composio 支持对工具包进行版本控制： ```typescript export const groupByVersion = ( specs: ReadonlyArray ): Map[]> => { const grouped = new Map[]>(); for (const spec of specs) { const existing = grouped.get(spec.toolkitVersion); if (existing) { existing.push(spec.toolkitSlug); } else { grouped.set(spec.toolkitVersion, [spec.toolkitSlug]); } } return grouped; }; ``` ### 版本规范处理 | 场景 | 行为 | |------|------| | 指定版本号 | 如 `20250901_00` | | latest | 使用最新版本 | | 混合规范 | 按版本分组处理 | 版本映射仅包含非 `latest` 的版本规范作为覆盖项。 资料来源：[ts/packages/core/src/types/modifiers.types.ts:1-50]() ## 终端 UI 服务 ### 日志级别 CLI 提供结构化的日志输出： | 方法 | 用途 | 输出符号 | |------|------|----------| | `ui.log.info` | 信息日志 | 蓝色标记 | | `ui.log.success` | 成功日志 | 绿色标记 | | `ui.log.warn` | 警告日志 | 黄色标记 | | `ui.log.error` | 错误日志 | 红色标记 | | `ui.log.step` | 步骤日志 | 绿色步骤标记 | ```typescript readonly log: { readonly info: (message: string) => Effect.Effect; readonly success: (message: string) => Effect.Effect; readonly warn: (message: string) => Effect.Effect; readonly error: (message: string) => Effect.Effect; readonly step: (message: string) => Effect.Effect; }; ``` ### 交互式选择 ```typescript select: ( message: string, options: ReadonlyArray<{ value: unknown; label: string; hint?: string }> ) => Effect.Effect ``` 支持用户从列表中选择选项，并在非交互模式下返回默认值。 资料来源：[ts/packages/cli/src/services/terminal-ui.ts:1-80]() ## 错误处理机制 ### 错误捕获流程 ```mermaid graph TD A[Effect 执行] --> B{Cause 分析} B -->|emptyCase| D[返回空错误数组] B -->|dieCase| E[解析未知错误] B -->|failCase| F[解析 Effect 错误] B -->|interruptCase| G[忽略中断] B -->|parallelCase| H[合并并行错误] B -->|sequentialCase| I[合并顺序错误] ``` ### 错误解析 ```typescript export const captureErrorsFrom = (cause: Cause): readonly PrettyError[] => reduceWithContext(cause, undefined, { emptyCase: (): readonly PrettyError[] => [], dieCase: (_, unknownError) => [parseError(unknownError)], failCase: (_, error) => [parseError(error)], interruptCase: () => [], parallelCase: (_, l, r) => [...l, ...r], sequentialCase: (_, l, r) => [...l, ...r], }); ``` ## 最佳实践 ### 1. 扩展 BaseProvider 始终从对应的基类继承以确保类型安全性和功能完整性。 ### 2. 实现必需方法 确保所有必需方法都正确实现，包括参数验证和错误处理。 ### 3. 使用 Schema 修饰器 通过 `modifySchema`、`beforeExecute`、`afterExecute` 实现工具的自定义行为。 ### 4. 类型脚本生成 对于需要类型提示的场景，使用 `composio generate ts` 命令生成完整的 TypeScript 类型定义。 ### 5. 权限管理 集成时注意工具权限系统，确保用户能够正确授权工具执行。 ## 总结 AI 框架提供商集成是 Composio 连接各类 AI 框架的桥梁，通过统一的抽象层，开发者可以轻松地将 Composio 的工具能力集成到 OpenAI、Anthropic、LangChain 等主流 AI 框架中。提供商系统的可扩展设计允许开发者创建自定义提供商以满足特定需求，同时保持与现有系统的高度兼容性。 --- ## MCP 协议集成 ### 相关页面 相关主题：[AI 框架提供商集成](#providers), [工具包系统](#toolkits)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/core/src/models/MCP.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/MCP.ts) - [python/composio/core/models/mcp.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/mcp.py) - [ts/examples/mcp/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/examples/mcp/src/index.ts) - [python/examples/mcp.py](https://github.com/ComposioHQ/composio/blob/main/python/examples/mcp.py) - [docs/content/docs/single-toolkit-mcp.mdx](https://github.com/ComposioHQ/composio/blob/main/docs/content/docs/single-toolkit-mcp.mdx) - [docs/content/reference/api-reference/mcp/index.mdx](https://github.com/ComposioHQ/composio/blob/main/docs/content/reference/api-reference/mcp/index.mdx)
# MCP 协议集成 MCP（Model Context Protocol）协议集成是 Composio 框架的核心功能之一，它为 AI 模型提供了标准化的工具调用和上下文管理能力。通过 MCP 协议，Composio 能够将各种第三方工具和服务桥接到 AI 代理的运行环境中，实现跨平台、跨服务的统一工具调用体验。 ## 核心概念 ### 什么是 MCP 协议 MCP 是一种专为 AI 模型设计的通信协议，它定义了 AI 模型与外部工具之间交互的标准方式。该协议允许 AI 模型通过统一的接口发现、调用和管理各种工具，同时保持类型安全和参数验证能力。 Composio 的 MCP 集成层负责将框架内的工具系统转换为 MCP 兼容的格式，使任何支持 MCP 协议的 AI 客户端都能直接使用 Composio 提供的全部工具能力。 ### 架构定位 ``` ┌─────────────────────────────────────────────────────────────┐ │ AI 客户端 │ │ (Claude Desktop, Cursor, etc.) │ └─────────────────────┬───────────────────────────────────────┘ │ MCP 协议 ▼ ┌─────────────────────────────────────────────────────────────┐ │ Composio MCP 服务器 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ 工具发现 │ │ 参数验证 │ │ 执行引擎 │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ └─────────────────────┬───────────────────────────────────────┘ │ 内部 API ▼ ┌─────────────────────────────────────────────────────────────┐ │ Composio 工具生态 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │ │ Gmail │ │ Slack │ │ Notion │ │ 300+ 更多工具 │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 数据模型 ### TypeScript 实现 Composio 的 TypeScript MCP 模型定义在 `ts/packages/core/src/models/MCP.ts` 中，提供了完整的类型定义和接口规范。 | 类/接口 | 用途 | 关键属性 | |---------|------|----------| | `MCPClient` | MCP 协议客户端封装 | `connection`, `tools`, `requests` | | `MCPServer` | MCP 协议服务端实现 | `port`, `host`, `handlers` | | `MCPTool` | MCP 工具表示 | `name`, `description`, `inputSchema`, `outputSchema` | | `MCPRequest` | 工具调用请求 | `id`, `tool`, `params`, `timestamp` | | `MCPResponse` | 工具调用响应 | `id`, `result`, `error`, `duration` | ### Python 实现 Python 端的 MCP 模型位于 `python/composio/core/models/mcp.py`，采用 dataclass 风格的类型定义，与 TypeScript 版本保持功能对齐。 | 类/接口 | 用途 | 关键属性 | |---------|------|----------| | `MCPClient` | Python MCP 客户端 | `connection`, `tools`, `callbacks` | | `MCPServer` | Python MCP 服务器 | `host`, `port`, `routes` | | `MCPTool` | Python 工具定义 | `name`, `description`, `input_schema`, `output_schema` | | `MCPRequest` | Python 请求对象 | `id`, `method`, `params`, `jsonrpc_version` | ## 工作流程 ### 工具发现流程 当 AI 客户端连接到 Composio MCP 服务器时，系统按以下流程完成工具发现： ```mermaid sequenceDiagram participant Client as AI 客户端 participant Server as MCP 服务器 participant Registry as 工具注册表 participant Toolkit as 工具包 Client->>Server: 建立 MCP 连接 Server->>Registry: 查询可用工具 Registry->>Toolkit: 加载工具包 Toolkit-->>Registry: 返回工具列表 Registry-->>Server: 返回合并的工具清单 Server-->>Client: 发送 tools/list 响应 Client->>Server: 发起工具调用请求 Server->>Toolkit: 调用目标工具 Toolkit-->>Server: 返回执行结果 Server-->>Client: 发送工具响应 ``` ### 工具执行流程 ```mermaid graph TD A[接收 MCP 请求] --> B{验证请求格式} B -->|格式错误| C[返回 JSON-RPC 错误] B -->|格式正确| D{验证工具存在} D -->|工具不存在| E[返回 -32601 错误] D -->|工具存在| F{验证参数} F -->|参数无效| G[返回参数验证错误] F -->|参数有效| H[执行工具逻辑] H --> I[捕获执行异常] I -->|有异常| J[返回错误响应] I -->|正常执行| K[返回成功结果] ``` ## 使用方式 ### TypeScript 示例 在 `ts/examples/mcp/src/index.ts` 中提供了完整的使用示例： ```typescript import { Composio } from "@composio/core"; import { MCPServer } from "@composio/core/mcp"; async function main() { const client = new Composio(); // 创建 MCP 服务器 const server = new MCPServer({ port: 3000, host: "localhost" }); // 注册工具 await server.registerTools(await client.getTools()); // 启动服务器 await server.start(); console.log("MCP 服务器运行在 http://localhost:3000"); } main(); ``` ### Python 示例 `python/examples/mcp.py` 展示了 Python 环境下的使用方式： ```python from composio import Composio from composio.mcp import MCPServer def main(): client = Composio() # 创建 MCP 服务器实例 server = MCPServer( host="localhost", port=3000 ) # 注册可用工具 server.register_tools(client.get_tools()) # 启动服务 server.start() print("MCP 服务器已启动") if __name__ == "__main__": main() ``` ## 单工具包 MCP 模式 Composio 支持将单个工具包暴露为独立的 MCP 服务，这种模式称为 `single-toolkit-mcp`。适用于需要隔离权限或简化配置的部署场景。 ```mermaid graph LR A[AI 客户端] -->|MCP| B[单一工具包 MCP 服务器] B --> C[指定工具包] C --> D[该工具包下的所有工具] ``` 配置示例： ```yaml # 单工具包 MCP 配置 mcp: mode: single-toolkit toolkit: gmail tools: - send_email - read_emails ``` ## API 参考 ### 核心类 #### MCPServer | 参数 | 类型 | 必需 | 默认值 | 说明 | |------|------|------|--------|------| | `host` | `string` | 是 | - | 服务器监听地址 | | `port` | `number` | 是 | - | 服务器监听端口 | | `tools` | `MCPTool[]` | 否 | `[]` | 初始加载的工具列表 | | `auth` | `AuthConfig` | 否 | - | 认证配置 | #### MCPTool | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `name` | `string` | 是 | 工具唯一标识 | | `description` | `string` | 是 | 工具功能描述 | | `inputSchema` | `JSONSchema` | 是 | 输入参数模式 | | `outputSchema` | `JSONSchema` | 否 | 输出结果模式 | | `handler` | `Function` | 是 | 工具执行函数 | ### JSON-RPC 接口 MCP 协议基于 JSON-RPC 2.0 规范实现，支持以下标准方法： | 方法名 | 用途 | 请求参数 | 响应类型 | |--------|------|----------|----------| | `tools/list` | 列出所有可用工具 | `{}` | `ToolListResponse` | | `tools/call` | 调用指定工具 | `ToolCallRequest` | `ToolCallResponse` | | `tools/schema` | 获取工具参数模式 | `{ name: string }` | `SchemaResponse` | ## 配置选项 ### 服务端配置 | 配置项 | 类型 | 说明 | 可选值 | |--------|------|------|--------| | `strict_mode` | `boolean` | 启用严格参数验证 | `true` / `false` | | `timeout` | `number` | 工具调用超时时间(毫秒) | 默认 `30000` | | `rate_limit` | `RateLimitConfig` | 请求速率限制 | - | | `cors` | `CORSConfig` | 跨域资源共享配置 | - | ### 客户端配置 | 配置项 | 类型 | 说明 | |--------|------|------| | `server_url` | `string` | MCP 服务器地址 | | `api_key` | `string` | API 认证密钥 | | `timeout` | `number` | 请求超时时间 | | `retries` | `number` | 失败重试次数 | ## 错误处理 MCP 协议定义了标准化的错误码体系： | 错误码 | 名称 | 说明 | |--------|------|------| | `-32700` | Parse Error | JSON 解析失败 | | `-32600` | Invalid Request | 无效的请求格式 | | `-32601` | Method Not Found | 方法不存在 | | `-32602` | Invalid Params | 参数无效 | | `-32603` | Internal Error | 服务器内部错误 | | `-32000` | Tool Execution Error | 工具执行失败 | ## 与主流 AI 客户端集成 ### Claude Desktop 在 `~/.config/claude-desktop/claude_desktop_config.json` 中添加配置： ```json { "mcpServers": { "composio": { "command": "npx", "args": ["@composio/core", "mcp", "--port", "8080"] } } } ``` ### Cursor IDE 在 Cursor 设置中配置 MCP 服务器地址为 `http://localhost:8080` 即可。 ## 最佳实践 ### 性能优化 1. **工具分页加载**：大型工具集建议使用分页加载，避免首次连接超时 2. **结果缓存**：对频繁调用的工具启用结果缓存，减少重复执行 3. **连接复用**：保持长连接以减少握手开销 ### 安全建议 1. **参数验证**：始终启用 `strict_mode` 进行参数校验 2. **密钥管理**：通过环境变量而非硬编码方式配置 API 密钥 3. **权限隔离**：生产环境建议使用单工具包模式限制暴露范围 ## 相关文档 - [单一工具包 MCP 文档](docs/content/docs/single-toolkit-mcp.mdx) - [MCP API 参考](docs/content/reference/api-reference/mcp/index.mdx) - [Composio 核心概念](../getting-started/concepts.md) --- ## CLI 命令行工具 ### 相关页面 相关主题：[工具包系统](#toolkits)
相关源码文件 以下源码文件用于生成本页说明： - [ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts) - [ts/packages/cli/src/services/tool-permissions.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/tool-permissions.ts) - [ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts) - [ts/packages/cli/src/commands/init.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/init.cmd.ts) - [ts/packages/cli/src/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/cli-local-tools/src/registry.ts) - [ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts) - [ts/packages/cli/src/commands/tools/tools.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/tools/tools.cmd.ts) - [ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts) - [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts) - [ts/packages/cli/src/generation/create-toolkit-index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/generation/create-toolkit-index.ts)
# CLI 命令行工具 Composio CLI 是 Composio 平台提供的命令行界面工具，为开发者提供了一套完整的命令行接口，用于工具发现、执行、日志查看、项目初始化等操作。CLI 基于 TypeScript/Effect 框架开发，提供了丰富的交互式体验和灵活的扩展机制。 ## 架构概览 Composio CLI 采用模块化架构设计，核心组件包括命令解析层、服务层和数据层。整个系统以 Effect 函数式编程库为基础，实现了声明式的命令定义和错误处理。 ```mermaid graph TD A[CLI 入口] --> B[命令路由层] B --> C[toolkits 命令组] B --> D[tools 命令组] B --> E[triggers 命令组] B --> F[logs 命令组] B --> G[local-tools 命令组] B --> H[init 命令] C --> I[list - 列出工具包] C --> J[info - 工具包详情] C --> K[search - 搜索工具包] C --> L[version - 版本信息] G --> M[list - 列出本地工具] G --> N[configure - 配置本地工具] G --> O[doctor - 诊断检查] ``` ## 核心命令结构 ### 命令组织方式 CLI 使用 Effect 框架的 Command 模块进行命令定义，每个命令都是一个独立的 Effect 对象，通过组合子命令形成树状结构。 ```typescript export const toolkitsCmd = Command.make('toolkits').pipe( Command.withDescription('Discover and inspect Composio toolkits.'), Command.withSubcommands([ toolkitsCmd$List, toolkitsCmd$Info, toolkitsCmd$Search, toolkitsCmd$Version, ]) ); ``` 资料来源：[ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:14-23]() ### 根命令层级 | 命令组 | 功能描述 | 子命令 | |--------|----------|--------| | `toolkits` | 发现和检查 Composio 工具包 | list, info, search, version | | `tools` | 工具浏览和详情查看 | list, info | | `triggers` | 触发器相关操作 | list, info | | `connected-accounts` | 账户连接管理 | link, list, remove | | `logs` | 日志查看 | tools, triggers | | `local-tools` | 本地工具管理 | list, configure, doctor | | `dev` | 开发调试命令 | init, playground-execute | | `execute` | 执行工具 | - | 资料来源：[ts/packages/cli/src/commands/tools/tools.cmd.ts:3-10]() ## 全局选项与帮助系统 ### 全局 Flags CLI 提供了一系列全局选项，用于控制命令行为： | Flag | 说明 | 可用模式 | |------|------|----------| | `-h, --help [mode]` | 显示帮助信息 | simple, default, full | | `--version` | 显示 CLI 版本 | - | | `--install-skill [skill-name]` | 手动安装 composio skill | claude, codex, openclaw | 资料来源：[ts/packages/cli/src/commands/root-help.ts:1-15]() ### 帮助级别解析 帮助系统支持三种显示模式，通过 `parseHelpLevel` 函数进行解析： ```typescript const parseHelpLevel = (token?: string): HelpLevel | undefined => { if (!token) return undefined; if (token === 'simple') return 'simple'; if (token === 'default') return 'default'; if (token === 'verbose') return 'full'; return HELP_LEVELS.find(level => level === token); }; ``` 帮助信息支持尾随参数传递，例如 `composio command --help simple` 会被正确解析为显示简化帮助。 资料来源：[ts/packages/cli/src/commands/root-help.ts:1-100]() ## 工具权限管理 ### 权限请求流程 当 CLI 执行需要授权的工具时，会启动一个本地 HTTP 服务器，显示浏览器内嵌的权限请求页面。 ```mermaid sequenceDiagram 用户执行工具 --> CLI: 请求权限 CLI --> HTTP服务器: 启动本地服务 HTTP服务器 --> 用户浏览器: 显示权限页面 用户 --> 浏览器: 选择 Allow/Deny 浏览器 --> HTTP服务器: 发送决策 HTTP服务器 --> CLI: 返回权限决策 CLI --> 工具执行: 执行或拒绝 ``` ### 权限选项 权限页面提供三个选项： - **Allow for this session** - 在当前会话中允许 - **Allow once** - 仅允许本次执行 - **Deny** - 拒绝执行 资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-50]() ## 本地工具注册表 ### 本地工具解析机制 本地工具使用特殊前缀 `LOCAL_TOOL_PREFIX` 进行标识，注册表提供了完整的解析和过滤功能。 ```typescript export const isLocalToolSlug = ( toolSlug: string, options: { readonly declarations?: ReadonlyArray } = {} ): boolean => { const upper = toolSlug.toUpperCase(); if (!upper.startsWith(LOCAL_TOOL_PREFIX)) return false; return ( resolveLocalTool(toolSlug, { includeUnsupported: true, declarations: options.declarations }) !== null ); }; ``` ### 工具包过滤 注册表支持按名称过滤工具包，并自动检测当前平台支持情况： ```typescript export const getLocalToolkitDeclarations = ( options: { readonly currentPlatform?: LocalCliPlatform; readonly toolkits?: ReadonlyArray; readonly declarations?: ReadonlyArray; } = {} ): ReadonlyArray => { const currentPlatform = options.currentPlatform ?? detectCliPlatform(); return declarationsFor(options.declarations) .filter(toolkit => toolkitMatchesFilter(toolkit, options.toolkits)) .filter(toolkit => supportsCliPlatform(toolkit.platforms, currentPlatform)) .map(toolkit => ({ ...toolkit, tools: toolkit.tools.filter(tool => supportsCliPlatform(tool.platforms, currentPlatform)), })) .filter(toolkit => toolkit.tools.length > 0); }; ``` ### 工具 Slug 规范化 本地工具使用规范化格式：`LOCAL_TOOL_PREFIX + toolkit_slug + _ + tool_slug` 资料来源：[ts/packages/cli/src/cli-local-tools/src/registry.ts:1-150]() ## 项目初始化 ### 初始化流程 `init` 命令负责项目配置，包括环境变量设置和 API key 管理。 ```mermaid flowchart LR A[运行 init] --> B{检查 .env.local} B -->|不存在| C[创建 .env.local] B -->|存在| D[检查现有配置] C --> E[获取全局 API Key] D --> E E --> F{有 API Key?} F -->|否| G[跳过配置] F -->|是| H[获取会话信息] H --> I[创建项目 API Key] I --> J[写入环境变量] ``` ### 环境变量管理 初始化命令会检查并设置以下环境变量： - `COMPOSIO_API_KEY` - 项目 API key - `COMPOSIO_TEST_USER_ID` - 测试用户 ID ```typescript const hasProjectApiKey = /^COMPOSIO_API_KEY=.*/m.test(existingEnvContent); const hasTestUserId = /^COMPOSIO_TEST_USER_ID=.*/m.test(existingEnvContent); ``` 资料来源：[ts/packages/cli/src/commands/init.cmd.ts:1-100]() ## 工具包索引生成 ### 索引数据结构 工具包索引将所有工具和触发器按工具包名称分组存储： ```typescript export type ToolkitIndex = Record; export type ToolkitIndexData = Simplify<{ slug: string; version?: string; typeableTools: | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> } | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> }; triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>; }>; ``` ### 索引创建流程 索引创建通过 `createToolkitIndex` 函数实现，自动从工具前缀提取工具包名称： ```typescript export function createToolkitIndex(input: CreateToolkitIndexInput): Simplify { const { versionMap } = input; return pipe( input, groupByToolkits, Record.fromEntries, Record.mapEntries((value, key) => { const stripPrefix = String.slice(key.length + 1); const { slug } = value.toolkit; const version = versionMap?.get(String.toLowerCase(slug)); // ... }) ); } ``` 资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:1-80]() ## 命令提示系统 ### 提示数据结构 命令提示系统为每个命令提供示例用法和相关链接： ```typescript type CommandHint = { example: (params: Record) => string; links: ReadonlyArray; }; ``` ### 常用命令示例 | 命令 | 示例 | |------|------| | 搜索工具 | `composio search ""` | | 执行工具 | `composio execute "" -d '{}'` | | 获取 Schema | `composio execute "" --get-schema` | | 初始化项目 | `composio dev init` | | 查看日志 | `composio dev logs tools ""` | 资料来源：[ts/packages/cli/src/services/command-hints.ts:1-80]() ## 日志系统 ### 日志命令组 日志命令提供对工具和触发器执行历史的访问： ```typescript export const logsCmd = Command.make('logs').pipe( Command.withDescription('Inspect trigger and tool execution logs.'), Command.withSubcommands([logsCmd$Triggers, logsCmd$Tools]) ); ``` | 子命令 | 功能 | |--------|------| | `logs tools` | 查看工具执行日志 | | `logs triggers` | 查看触发器执行日志 | 资料来源：[ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts:1-20]() ## TypeScript 类型生成 ### 生成命令选项 `composio generate ts` 命令支持多种配置选项： | 选项 | 说明 | 默认值 | |------|------|--------| | `--compact` | 输出单模块文件 | false | | `--transpiled` | 同时输出转译后的 JS | true (无 output-dir 时) | | `--output-dir` | 指定输出目录 | node_modules/@composio/core | | `--toolkits` | 过滤特定工具包 | 全部 | ### 约束条件 - 输出目录不能指向 `node_modules` 内部 - 未指定 `--output-dir` 时自动使用 `@composio/core` 包目录 - 如启用 `--transpiled`，会同时生成 ESM 格式的 JavaScript 文件 资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts:1-30]() ## 本地工具配置 ### 配置命令 `local-tools configure` 命令允许修改工具元数据： ```typescript export const localToolsCmd$Configure = Command.make( 'configure', { selector, command, disable, enable, authenticated, unauthenticated, json }, ({ selector, command, disable, enable, authenticated, unauthenticated, json }) => Effect.gen(function* () { const target = resolveTarget(selector); // ... }) ); ``` ### 可配置项 | 配置项 | 说明 | |--------|------| | `command` | 设置安装命令 | | `disable` / `enable` | 启用/禁用工具 | | `authenticated` / `unauthenticated` | 设置认证状态 | 配置后可通过 `composio local-tools doctor` 进行诊断验证。 资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-80]() ## 错误处理 ### Effect 错误捕获 CLI 使用 Effect 框架的错误处理机制，通过 `captureErrorsFrom` 函数收集错误信息： ```typescript export const captureErrorsFrom = (cause: Cause): readonly PrettyError[] => reduceWithContext(cause, undefined, { emptyCase: (): readonly PrettyError[] => [], dieCase: (_, unknownError) => [parseError(unknownError)], failCase: (_, error) => [parseError(error)], interruptCase: () => [], parallelCase: (_, l, r) => [...l, ...r], sequentialCase: (_, l, r) => [...l, ...r], }); ``` 资料来源：[ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts:1-25]() ## 快速参考 ### 常用命令速查 ```bash # 搜索工具 composio search "send email" # 列出工具包 composio toolkits list # 查看工具详情 composio tools info # 执行工具 composio execute -d '{"param": "value"}' # 获取工具 schema composio execute --get-schema # 初始化项目 composio dev init # 诊断本地工具 composio local-tools doctor # 查看执行日志 composio dev logs tools # 生成 TypeScript 类型 composio generate ts --toolkits gmail --toolkits slack --- --- ## Doramagic 踩坑日志 项目：ComposioHQ/composio 摘要：发现 12 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops。 ## 1. 安装坑 · 来源证据：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: CLI - v0.2.25 release missing binary assets — upgrade command silently no-ops - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_54d53b3e2a6e4cf4a3e4783f824ed87b | https://github.com/ComposioHQ/composio/issues/3269 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 2. 安全/权限坑 · 来源证据：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shar… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK returns successful but file is never shared to channel (channels:[], shares:{}) - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_1b88beb594aa433eb998eac3b16a20e0 | https://github.com/ComposioHQ/composio/issues/3422 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 3. 安全/权限坑 · 来源证据：[Feature] Custom auth configs shouldn't require a dev project to use - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Custom auth configs shouldn't require a dev project to use - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_1d62ba62e77b47ff88b50d2db41a8cf7 | https://github.com/ComposioHQ/composio/issues/3271 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 4. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `composio` 与安装入口 `@composio/core` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。 - 复现命令：`npm install @composio/core` - 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。 - 证据：identity.distribution | github_repo:762304524 | https://github.com/ComposioHQ/composio | repo=composio; install=@composio/core ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:762304524 | https://github.com/ComposioHQ/composio | README/documentation is current enough for a first validation pass. ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | last_activity_observed missing ## 7. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium ## 8. 安全/权限坑 · 存在安全注意事项 - 严重度：medium - 证据强度：source_linked - 发现：No sandbox install has been executed yet; downstream must verify before user use. - 对用户的影响：用户安装前需要知道权限边界和敏感操作。 - 建议检查：转成明确权限清单和安全审查提示。 - 防护动作：安全注意事项必须面向用户前置展示。 - 证据：risks.safety_notes | github_repo:762304524 | https://github.com/ComposioHQ/composio | No sandbox install has been executed yet; downstream must verify before user use. ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:762304524 | https://github.com/ComposioHQ/composio | no_demo; severity=medium ## 10. 安全/权限坑 · 来源证据：@composio/core@0.10.0 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/core@0.10.0 - 对用户的影响：可能影响升级、迁移或版本选择。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_66f9d5fd557f41c7845ca5dd7d93ae6f | https://github.com/ComposioHQ/composio/releases/tag/%40composio/core%400.10.0 | 来源类型 github_release 暴露的待验证使用条件。 ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:762304524 | https://github.com/ComposioHQ/composio | release_recency=unknown