1. 项目概述

Composio 是一个强大的 AI Agent 工具集成平台，旨在为 AI Agent 提供可靠、可扩展的工具调用能力。该项目采用 TypeScript 与 Python 双语言架构，通过统一的接口设计实现了跨平台、跨框架的工具调用支持。

Composio 的核心价值主张包括：

• 工具抽象层：统一的工具定义和调用机制，支持多种 AI Agent 框架
• 本地工具支持：提供本地 CLI 工具集成，可在本地环境中执行工具
• 权限管理：完整的工具权限审批流程，确保工具调用的安全性
• Provider 系统：灵活的工具包装和修改器机制，支持自定义工具行为

2. 仓库结构

Composio 采用 Monorepo 结构组织代码，主要分为 TypeScript 包和 Python SDK 两大部分。

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 工具和应用开发支持：

资料来源：ts/README.md:1-50

2.2 Python SDK 结构

Python 部分位于 python/ 目录，提供 Python 语言的 SDK 支持：

资料来源：python/README.md:1-20

3. 核心系统架构

3.1 工具系统

Composio 的工具系统是其核心组成部分，支持工具的发现、注册、调用和权限管理。

graph LR
    A[工具声明] --> B[本地工具注册表]
    A --> C[远程工具索引]
    
    B --> D[工具执行器]
    C --> D
    
    D --> E[权限检查]
    E --> F[执行结果]
    
    B -.-> G[toCustomTool 转换]
    C -.-> H[createToolkitIndex 索引]

#### 工具声明结构

工具通过声明式接口定义，包含以下关键属性：

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）进行过滤和分组：

const toolkitMatchesFilter = (
  toolkit: LocalToolkitDeclaration,
  requestedToolkits?: ReadonlyArray<string>
): 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 框架构建，提供模块化的命令定义和子命令支持。

#### 根命令帮助

根命令提供全局选项和帮助信息：

资料来源：ts/packages/cli/src/commands/root-help.ts:1-50

#### 子命令结构

CLI 采用树形命令结构：

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]

#### 常用命令示例

资料来源：ts/packages/cli/src/services/command-hints.ts:1-80

3.3 权限管理系统

Composio 实现了完整的工具权限审批流程，确保工具调用的安全可控。

sequenceDiagram
    participant CLI as CLI 客户端
    participant Server as 权限服务器
    participant User as 用户
    
    CLI->>Server: 请求执行工具
    Server->>User: 显示权限确认页面
    User->>Server: 选择权限决策
    Server->>CLI: 返回决策结果

#### 权限决策类型

资料来源：ts/packages/cli/src/services/tool-permissions.ts:1-60

#### 权限确认页面

系统通过本地 HTTP 服务器展示权限确认页面：

<h1>Allow ${toolSlug}?</h1>
<p>Composio CLI is requesting permission to execute this tool${accountLabel ? ` for ${accountLabel}` : ''}.</p>

3.4 Provider 系统

Provider 系统提供了工具包装和修改的扩展机制，允许开发者自定义工具的行为。

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 类型

资料来源：ts/packages/providers/README.md:1-80

#### 工具修改器

Provider 使用修改器（Modifiers）来调整工具的 Schema 和行为：

type ProviderOptions<TProvider> =
  TProvider extends BaseComposioProvider<infer TToolCollection, infer TTool, infer TMcpResponse>
    ? TProvider extends BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>
      ? AgenticToolOptions
      : ToolOptions
    : never;

修改器支持的钩子函数：

4. 核心组件详解

4.1 终端 UI 服务

TerminalUI 提供统一的命令行输出接口：

interface TerminalUI {
  readonly output: (data: string, options?: { force?: boolean }) => Effect<void>;
  readonly intro: (title: string) => Effect<void>;
  readonly outro: (message: string) => Effect<void>;
  readonly log: {
    readonly info: (message: string) => Effect<void>;
    readonly success: (message: string) => Effect<void>;
    readonly warn: (message: string) => Effect<void>;
    readonly error: (message: string) => Effect<void>;
    readonly step: (message: string) => Effect<void>;
  };
  readonly note: (message: string, title?: string) => Effect<void>;
  readonly withSpinner: <A, E, R>(message: string, effect: Effect<A, E, R>) => Effect<A>;
}

资料来源：ts/packages/cli/src/services/terminal-ui.ts:1-40

4.2 错误处理机制

系统使用 Effect 框架进行错误处理：

export const captureErrorsFrom = <E>(cause: Cause<E>): 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 配置加载系统

系统支持从文件加载和解析配置：

graph LR
    A[配置文件] --> B[ConfigLoader]
    B --> C[Path 解析]
    C --> D[Primitive 解析]
    D --> E[split 分割]
    E --> F[Array<A>]

支持的分隔符解析功能，允许用户自定义分隔符来拆分配置值。

资料来源：ts/packages/cli/src/effects/from-lazy-json.ts:1-50

4.4 工具包索引

工具包索引系统提供工具的分组和类型化支持：

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<ToolkitName, ToolkitIndexData>;

资料来源：ts/packages/cli/src/generation/create-toolkit-index.ts:1-30

5. 开发指南

5.1 环境准备

# 安装依赖
pnpm install

# 安装 peer 依赖
pnpm check:peer-deps

资料来源：ts/README.md:1-50

5.2 创建新 Provider

# 创建非智能体 Provider
pnpm create:provider <provider-name>

# 创建智能体 Provider
pnpm create:provider <provider-name> --agentic

Provider 创建后的结构：

<provider-name>/
├── src/
│   └── index.ts      # Provider 实现
├── package.json      # 包配置
├── tsconfig.json     # TypeScript 配置
├── tsup.config.ts    # 构建配置
└── README.md         # 文档

资料来源：ts/README.md:50-80

5.3 创建示例代码

pnpm create:example <example-name>

5.4 本地工具配置

本地工具支持灵活的配置文件管理：

配置完成后可运行：

composio local-tools doctor --toolkits <toolkit-name>

资料来源：ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-60

6. Python SDK 文档生成

Composio 使用 Griffe 工具从 Python 源码自动生成文档：

cd python
uv run --with griffe python scripts/generate-docs.py

文档生成流程：

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 技术栈

7.2 Python 技术栈

8. 总结

Composio 是一个设计精良的 AI Agent 工具集成平台，其架构特点包括：

1. 模块化设计：通过 Monorepo 结构实现代码的高内聚低耦合
2. 类型安全：全面使用 TypeScript 提供类型保障
3. 函数式编程：采用 Effect 框架实现纯函数式错误处理
4. 扩展性强：Provider 系统支持自定义工具包装行为
5. 双语言支持：同时提供 TypeScript 和 Python SDK

通过本项目，开发者可以快速构建基于 AI Agent 的应用，享受统一工具调用接口带来的便利。

概述

Composio 提供了统一的工具抽象层，使 AI 代理能够访问超过 250+ 的外部应用工具。通过 Composio SDK，开发者可以：

• 快速集成 OpenAI、Anthropic、LangChain 等主流 AI 框架
• 获取并管理可用的应用工具
• 使用 schema 修饰器转换工具架构
• 通过 CLI 工具进行本地开发和调试

环境要求

安装配置

TypeScript SDK 安装

Composio 的 TypeScript SDK 提供两种安装方式：完整包安装和按需安装 资料来源：ts/packages/cli/src/commands/root-help.ts:1-50

# 完整安装
pnpm add @composio/core @composio/cli

# 仅安装核心包
pnpm add @composio/core

Python SDK 安装

pip install composio-core

环境变量配置

创建 .env 文件并配置以下环境变量 资料来源：ts/examples/tool-router/README.md:10-20

# 必需的环境变量
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

# 交互式初始化
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

修饰器

Composio 支持强大的修饰器（Modifiers）功能，用于转换工具 schema 和执行行为 资料来源：python/README.md:60-100

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

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 集成

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 tools list

# 列出特定工具包的工具
composio tools list --toolkit github

# JSON 格式输出
composio tools list --json

工具信息查询

# 查看工具详情
composio tools info GITHUB_CREATE_REPO

# 获取工具执行 schema
composio execute GITHUB_CREATE_REPO --get-schema

执行工具

# 执行工具（交互式）
composio execute GITHUB_CREATE_REPO

# 执行工具（传入参数）
composio execute GITHUB_CREATE_REPO -d '{"name": "my-repo", "private": true}'

账户连接

# 连接第三方账户
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 configure <toolkit-slug> \
  --command /path/to/tool \
  --authenticated

# 禁用工具
composio local-tools configure <toolkit-slug> --disable

# 启用工具
composio local-tools configure <toolkit-slug> --enable

列出本地工具

# 基本列表
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

开发命令

# 初始化开发环境
composio dev init

# 在 Playgroun 中执行工具
composio dev playground-execute <slug> \
  --user-id <user-id> \
  -d '{}'

# 获取执行 schema
composio dev playground-execute <slug> --get-schema

# 查看工具执行日志
composio dev logs tools <log_id>

# 查看触发器日志
composio dev logs triggers <log_id>

工具包管理

发现工具包

# 列出所有工具包
composio toolkits list

# 搜索工具包
composio toolkits search <keyword>

# 查看工具包详情
composio toolkits info <toolkit-name>

管理工具包版本

# 查看工具包版本
composio toolkits version <toolkit-name>

# 设置特定版本
COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00

工作流程图

基本集成流程

graph TD
    A[初始化 Composio SDK] --> B[配置 API Key]
    B --> C[获取可用工具]
    C --> D[选择工具包]
    D --> E[执行工具操作]
    E --> F{操作成功?}
    F -->|是| G[返回结果]
    F -->|否| H[错误处理]

CLI 工具执行流程

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. 错误处理

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 注册账号并获取 API Key。

Q: 工具执行失败怎么办？

1. 使用 composio local-tools doctor 检查本地环境
2. 使用 composio tools info <slug> 确认工具参数正确
3. 查看 composio dev logs tools <log_id> 获取详细错误信息

Q: 如何使用自定义 Provider？

参考 Provider 创建文档，使用 pnpm run create-provider <name> 创建自定义 Provider。

下一步

• 深入阅读 工具包文档
• 了解 Schema 修饰器的高级用法
• 探索 OpenAI 集成示例
• 加入 Discord 社区 获取帮助

概述

Composio 是一个多语言 Agent 工具集成平台，支持通过统一的 SDK 接口调用外部工具和服务。系统架构采用分层设计，核心层负责工具路由和执行管理，Provider 层提供灵活的扩展机制，CLI 层提供命令行交互能力。本文档基于源码分析，阐述 Composio 的整体架构设计、各核心模块职责以及跨语言 SDK 的实现机制。

架构分层

Composio 系统采用四层架构设计，从上到下依次为：

graph TD
    subgraph SDK层
        TS_SDK[TypeScript SDK<br/>composio.ts]
        PY_SDK[Python SDK<br/>sdk.py]
    end

    subgraph 核心层
        TR_TypeScript[ToolRouter<br/>TypeScript]
        TR_Python[ToolRouter<br/>Python]
    end

    subgraph Provider层
        CP[ComposioProvider]
        BaseProvider[BaseComposioProvider]
        AgenticProvider[BaseAgenticProvider]
    end

    subgraph CLI层
        CLI[Composio CLI]
        LocalRegistry[本地工具注册表<br/>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 与后端服务通信。

主要配置选项：

#### Python SDK

Python SDK 位于 python/composio/sdk.py，采用类式设计，提供 Composio 类作为主要入口。Python SDK 通过 openai 库实现与 OpenAI 生态的集成，同时支持自定义 LLM 客户端。

工具路由器

工具路由器（ToolRouter）是架构的核心组件，负责工具的注册、查询和路由。

#### TypeScript ToolRouter

ToolRouter.ts 实现了 TypeScript 端的工具路由逻辑。路由器维护一个工具索引（ToolkitIndex），将工具按照所属工具包（Toolkit）进行分组管理。

关键数据结构：

export type ToolkitIndex = Record<ToolkitName, ToolkitIndexData>;

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 都继承自此类：

class NonAgenticProvider extends BaseNonAgenticProvider {
  async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise<Tool>;
  async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]>;
  async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise<Tool>;
}

#### BaseAgenticProvider

Agentic Provider 继承自基础 Provider，增加了对 Agentic 工具的支持。Agentic 工具具有更复杂的执行流程，能够在执行前后进行上下文干预：

class AgenticProvider extends BaseAgenticProvider {
  async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise<Tool>;
  async getTools(modifiers?: ModifiersParams): Promise<Tool[]>;
}

#### ComposioProvider

ComposioProvider.ts 是 SDK 与外部服务通信的主要入口，它组合了多个底层 Provider 的能力：

graph LR
    ComposioProvider -->|持有| BaseComposioProvider
    ComposioProvider -->|持有| BaseAgenticProvider
    ComposioProvider -->|调用| ComposioToolkitsRepository
    ComposioProvider -->|调用| HTTPClient

Provider 的选择通过类型推断实现，SDK 根据传入的 Provider 类型自动选择合适的工具选项类型：

export type ProviderOptions<TProvider> =
  TProvider extends BaseComposicProvider<infer TToolCollection, infer TTool, infer TMcpResponse>
    ? TProvider extends BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>
      ? AgenticToolOptions
      : ToolOptions
    : never;

工具包版本管理

Composio 支持通过环境变量对工具包版本进行精细化控制。每个工具包可以指定特定版本或使用最新版本。

版本覆盖机制

版本覆盖通过 ToolkitVersionOverrides 类型管理：

export type ToolkitVersionOverrides = Map<Lowercase<string>, string>;

版本分组与验证

版本分组逻辑将具有相同版本的工具包聚合在一起，便于批量处理：

export const groupByVersion = (
  specs: ReadonlyArray<ToolkitVersionSpec>
): Map<string, Lowercase<string>[]> => {
  const grouped = new Map<string, Lowercase<string>[]>();
  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 验证版本有效性并在遇到错误时提供友好的错误信息。

环境变量配置

工具包版本可通过以下格式的环境变量配置：

版本值 "latest" 表示使用最新版本，不会被添加到版本映射中。

Schema 修饰器

Schema 修饰器（Schema Modifiers）允许在工具执行的不同阶段对请求和响应进行处理。这是实现日志记录、参数转换、结果过滤等功能的基础机制。

修饰器类型

interface SchemaModifiersParams {
  modifySchema?: (context: SchemaModificationContext) => SchemaModificationResult;
  beforeExecute?: (context: ExecutionContext) => ExecutionContext;
  afterExecute?: (context: ExecutionContext) => ExecutionContext;
}

执行流程

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）负责管理所有本地工具的定义和元数据：

export const getAllLocalToolkitSlugs = (
  options: { readonly declarations?: ReadonlyArray<LocalToolkitDeclaration> } = {}
): ReadonlyArray<string> =>
  declarationsFor(options.declarations).map(toolkit => toolkit.slug.toLowerCase());

工具匹配与过滤

注册表提供多种匹配工具的方法：

本地工具执行

本地工具通过统一的执行函数处理：

const executeLocalTool = async (
  execution: LocalToolExecution,
  input: Record<string, unknown>,
  options: ExecuteLocalToolOptions
) => {
  // 处理工具执行逻辑
};

错误处理机制

Composio 使用 Effect 库进行函数式错误处理，通过 captureErrorsFrom 函数将 Effect 的 Cause 转换为友好的错误信息：

export const captureErrorsFrom = <E>(cause: Cause<E>): 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 子程序。命令通过模块化组织，核心命令包括：

TypeScript 生成命令

ts.generate.cmd.ts 实现了 composio generate ts 命令，用于生成 TypeScript 类型定义文件：

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 <name> 创建 Provider 骨架
2. 在 src/index.ts 中实现必要方法
3. 注册 Provider 到 SDK

# 创建非 Agentic Provider
pnpm create:provider my-provider

# 创建 Agentic Provider
pnpm create:provider my-provider --agentic

数据流总结

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 接口，系统能够灵活适应不同的使用场景和集成需求。

概述

Composio TypeScript SDK 是用于与 Composio 平台交互的核心开发工具包，为 AI Agent 提供工具调用、工具包管理、账户连接等功能。该 SDK 构建于 Effect 框架之上，采用函数式编程范式，支持类型安全的工具操作和灵活的扩展机制。 资料来源：ts/README.md

核心架构

系统组件关系

graph TD
    A[ComposioClient] --> B[ToolRouter]
    A --> C[ConnectedAccounts]
    B --> D[Toolkits]
    B --> E[Tools]
    D --> E
    F[Providers] --> E
    G[CLI Tools] --> E

包结构概览

资料来源：ts/README.md, ts/packages/ts-builders/README.md

核心模型

Tools（工具）

Tool 模型代表单个可执行工具，是 SDK 的基本操作单元。每个工具包含以下属性：

资料来源：ts/packages/core/src/models/Tools.ts, ts/packages/cli/src/generation/create-toolkit-index.ts

Toolkits（工具包）

Toolkit 是工具的逻辑分组容器，提供组织和管理相关工具的能力：

export type ToolkitIndex = Record<ToolkitName, ToolkitIndexData>;

工具包数据包含版本管理和工具集合映射，支持按名称动态访问工具定义。 资料来源：ts/packages/cli/src/generation/create-toolkit-index.ts

ToolRouterSession（会话路由）

ToolRouterSession 负责管理工具调用的生命周期，包括参数验证、执行和结果处理：

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 管理用户与第三方服务的授权连接，是工具执行认证的基础：

资料来源：ts/packages/core/src/models/ConnectedAccounts.ts

Provider 机制

Provider 类型

SDK 支持两种 Provider 类型，分别适用于不同的 AI 框架集成场景：

资料来源：ts/packages/providers/README.md, ts/packages/core/src/types/modifiers.types.ts

Provider 方法

#### 非 Agentic Provider

class NonAgenticProvider extends BaseNonAgenticProvider {
  async wrapTool(
    toolSlug: string, 
    tool: Tool, 
    modifiers?: SchemaModifiersParams
  ): Promise<Tool>;

  async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]>;

  async getToolBySlug(
    slug: string, 
    modifiers?: SchemaModifiersParams
  ): Promise<Tool>;
}

#### Agentic Provider

Agentic Provider 在非 Agentic 基础上增加执行修饰符支持：

type beforeExecuteModifier = (
  toolSlug: string,
  params: Record<string, unknown>
) => Record<string, unknown>;

type afterExecuteModifier = (
  toolSlug: string,
  response: ToolExecuteResponse
) => ToolExecuteResponse;

资料来源：ts/packages/providers/README.md, ts/packages/core/src/types/modifiers.types.ts

内置 Providers

资料来源：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 类型存根：

composio generate ts
composio generate ts --type-tools
composio generate ts --toolkits gmail slack

生成器支持以下选项：

资料来源：ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts, ts/packages/cli/src/commands/generate/generate.cmd.ts

文档生成

SDK 使用 TypeDoc 从源代码提取 JSDoc 注释生成 MDX 文档：

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 工具的注册和管理能力：

export const getAllLocalToolkitSlugs = (
  options?: { declarations?: ReadonlyArray<LocalToolkitDeclaration> }
): ReadonlyArray<string>;

export const getLocalCustomToolkits = (
  options?: {
    currentPlatform?: LocalCliPlatform;
    toolkits?: ReadonlyArray<string>;
    declarations?: ReadonlyArray<LocalToolkitDeclaration>;
  }
): ReadonlyArray<CustomToolkit>;

本地工具支持跨平台声明和动态平台检测。 资料来源：ts/packages/cli-local-tools/src/registry.ts

环境变量配置

资料来源：ts/README.md, ts/packages/cli/src/commands/init.cmd.ts

工具包版本管理

CLI 提供工具包版本覆盖验证机制：

const { validatedOverrides, warnings } = yield* client.validateToolkitVersions(
  versionOverrides,
  toolkitSlugsFilter
);

验证器支持批量验证并在检测到无效版本时提供友好的错误提示。 资料来源：ts/packages/cli/src/effects/validate-toolkit-versions.ts

项目语言检测

SDK 自动检测项目语言环境：

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

快速开始

安装

pnpm add @composio/core

初始化客户端

import { Composio } from "@composio/core";

const client = new Composio();

获取工具

const tools = await client.getTools({ 
  toolkits: ["github"] 
});

执行工具

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

概述

Composio Python SDK 是一个强大的工具集成框架，为开发者提供了与外部服务（如 GitHub、Gmail、Google 等）交互的统一接口。该 SDK 允许 AI 代理通过标准化的工具调用方式访问数百种第三方服务，同时支持自定义提供者、本地工具和复杂的认证配置。资料来源：python/README.md

核心架构

SDK 初始化

Composio SDK 的初始化是整个集成的起点，支持多种配置选项：

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

架构流程图

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 进行筛选：

# 获取特定工具包中的所有工具
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

工具分类

资料来源：ts/packages/cli-local-tools/src/registry.ts

修饰器系统

Composio SDK 支持强大的修饰器系统，允许在工具模式转换和执行过程中进行干预。

模式修饰器

模式修饰器（Schema Modifiers）允许在工具模式被使用前进行转换：

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

执行修饰器

执行修饰器允许在工具执行前和执行后进行拦截处理：

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

修饰器类型系统

export type ProviderOptions<TProvider> =
  TProvider extends BaseComposioProvider<infer TToolCollection, infer TTool, infer TMcpResponse>
    ? TProvider extends BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>
      ? AgenticToolOptions
      : ToolOptions
    : never;

资料来源：ts/packages/core/src/types/modifiers.types.ts

提供者系统

提供者架构

Composio SDK 使用提供者模式来适配不同的 AI 框架：

classDiagram
    class BaseComposioProvider {
        <<abstract>>
        +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 提供者实现：

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 的集成：

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 的集成示例：

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

创建自定义提供者

// 非代理类型提供者
class NonAgenticProvider extends BaseNonAgenticProvider {
  async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise<Tool>;
  async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]>;
  async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise<Tool>;
}

// 代理类型提供者
class AgenticProvider extends BaseAgenticProvider {
  async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise<Tool>;
  async getTools(modifiers?: ModifiersParams): Promise<Tool[]>;
  async create_mcp_server(tools: Tool[]): Promise<any>;
}

资料来源：ts/packages/providers/README.md

本地工具系统

本地工具注册表

Composio CLI 本地工具系统使用注册表模式管理本地可执行工具：

export const getAllLocalToolkitSlugs = (
  options: { readonly declarations?: ReadonlyArray<LocalToolkitDeclaration> } = {}
): ReadonlyArray<string> =>
  declarationsFor(options.declarations).map(toolkit => toolkit.slug.toLowerCase());

本地工具标识

本地工具使用特殊前缀进行标识：

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)}`;

本地工具过滤

const toolkitMatchesFilter = (
  toolkit: LocalToolkitDeclaration,
  requestedToolkits?: ReadonlyArray<string>
): 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 提供了完整的工具包管理命令：

# 列出所有可用工具包
composio toolkits list

# 查看工具包详情
composio toolkits info <toolkit-name>

# 搜索工具包
composio toolkits search <query>

# 查看工具包版本
composio toolkits version <toolkit-name>

资料来源：ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts

工具包索引创建

graph LR
    A[工具数据] --> B[groupByToolkits]
    B --> C[Record.fromEntries]
    C --> D[Record.mapEntries]
    D --> E[ToolkitIndex]
    
    F[版本映射] --> D

工具包索引数据结构：

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<ToolkitName, ToolkitIndexData>;

资料来源：ts/packages/cli/src/generation/create-toolkit-index.ts

认证与账户管理

工具权限请求

当执行需要认证的工具时，系统会启动权限请求流程：

const requestPermissionInBrowser = (params: {
  readonly toolSlug: string;
  readonly accountLabel?: string;
}): Promise<PermissionDecision> =>
  new Promise((resolve, reject) => {
    const token = crypto.randomUUID();
    // 启动 HTTP 服务器等待用户响应
  });

权限选项包括：

资料来源：ts/packages/cli/src/services/tool-permissions.ts

账户链接

# 链接工具包账户
composio link <toolkit>

项目初始化

初始化流程

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

composio dev init

资料来源：ts/packages/cli/src/commands/init.cmd.ts

SDK 文档生成

Python 文档生成器

使用 Griffe 从 Python 源码提取文档：

cd python
uv run --with griffe python scripts/generate-docs.py

生成流程：

graph LR
    A[composio/**/*.py] -->|griffe| B[结构化数据]
    B -->|generate-docs.py| C[MDX 文件]
    C --> D[docs/content/reference/sdk-reference/python/]

配置选项

资料来源：python/scripts/README.md

常见使用模式

基础工具调用

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"
    }
)

触发器使用

# 列出触发器
composio triggers list <toolkit>

# 查看触发器详情
composio triggers info <trigger-slug>

开发调试

# 在 Playground 中执行
composio dev playground-execute "<slug>" --user-id "<user-id>"

# 查看工具日志
composio dev logs tools <log_id>

# 查看触发器日志
composio dev logs triggers <log_id>

配置参考

初始化参数

环境变量

相关资源

• 官方文档
• Discord 社区
• GitHub Issues

概述

工具包系统（Toolkit System）是 Composio 框架的核心组件之一，负责组织和封装一组相关的工具（Tools），供 AI Agent 在执行任务时调用。每个工具包代表一个功能领域，如 Gmail、Slack、GitHub 等，为 Agent 提供与外部服务交互的能力。

工具包系统的主要职责包括：

• 工具组织：将相关工具归类到同一个工具包中，便于管理和发现
• 版本管理：支持同一工具包的多个版本，允许开发者使用特定版本或最新版本
• 本地工具支持：提供本地 CLI 工具包扩展，允许在本地环境中执行自定义工具
• 权限管理：为每个工具包的执行提供权限控制和确认机制

架构设计

核心组件关系

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 类型别名，定义为：

export type ToolkitIndex = Record<ToolkitName, ToolkitIndexData>;

ToolkitIndexData 包含以下字段：

资料来源：ts/packages/cli/src/generation/create-toolkit-index.ts:1-18

工具包索引创建流程

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）是在本地环境中运行的工具包，允许开发者定义自定义工具直接在本地执行。

核心数据结构：

interface LocalToolkitDeclaration {
  slug: string;
  name: string;
  description: string;
  platforms: ReadonlyArray<LocalCliPlatform>;
  tools: ReadonlyArray<LocalToolDeclaration>;
  setup?: LocalToolkitSetup;
  source?: ToolkitSource;
}

资料来源：ts/packages/cli-local-tools/src/registry.ts:1-50

本地工具注册流程：

graph TD
    A[LocalToolkitDeclaration] --> B{requestedToolkits存在?}
    B -->|是| C[转为小写Set]
    B -->|否| D[返回true]
    C --> E{slug小写化}
    E --> F{包含在requested中?}
    F -->|是| D
    F -->|否| G[返回false]

版本管理

版本覆盖机制

工具包版本覆盖允许开发者在配置中指定特定工具包的版本，而不是使用默认的最新版本。

配置格式：

type ToolkitVersionOverrides = Map<Lowercase<string>, string>;

版本分组逻辑：

graph LR
    A[ToolkitVersionSpec] --> B{版本为latest?}
    B -->|是| C[跳过]
    B -->|否| D[添加到versionMap]
    A --> E[groupByVersion]
    E --> F[Map: version -> slugs[]]

核心函数：

export const buildVersionMapFromSpecs = (
  specs: ReadonlyArray<ToolkitVersionSpec>
): ToolkitVersionOverrides => {
  const versionMap = new Map<Lowercase<string>, 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 是工具包发现命令的入口点，支持以下子命令：

资料来源：ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts:1-25

命令示例

# 列出所有工具包
composio tools list

# 查看特定工具包信息
composio tools info "<slug>"

# 执行工具包中的工具
composio execute "<slug>" -d '{}'

# 获取工具执行模式
composio execute "<slug>" --get-schema

# 链接账户
composio link <toolkit>

资料来源：ts/packages/cli/src/services/command-hints.ts:1-50

提供者集成

提供者类型层次

classDiagram
    class BaseComposioProvider~TToolCollection, TTool, TMcpResponse~ {
        <<abstract>>
    }
    class BaseAgenticProvider~TToolCollection, TTool, TMcpResponse~ {
        <<abstract>>
    }
    class NonAgenticProvider {
        ToolOptions
    }
    class AgenticProvider {
        AgenticToolOptions
    }
    
    BaseComposioProvider <|-- BaseAgenticProvider
    BaseComposioProvider <|-- NonAgenticProvider
    BaseAgenticProvider <|-- AgenticProvider

提供者选项类型

export type ProviderOptions<TProvider> =
  TProvider extends BaseComposioProvider<infer TToolCollection, infer TTool, infer TMcpResponse>
    ? TProvider extends BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>
      ? AgenticToolOptions
      : ToolOptions
    : never;

资料来源：ts/packages/core/src/types/modifiers.types.ts:1-20

创建自定义提供者

开发者可以通过以下命令创建新的提供者：

# 创建非代理提供者
pnpm create:provider <provider-name>

# 创建代理提供者
pnpm create:provider <provider-name> --agentic

生成的文件结构：

<provider-name>/
├── src/
│   └── index.ts      # 提供者实现
├── package.json      # 包配置
├── tsconfig.json     # TypeScript 配置
├── tsup.config.ts    # 构建配置
└── README.md         # 文档

必需方法（非代理提供者）：

class NonAgenticProvider extends BaseNonAgenticProvider {
  async wrapTool(
    toolSlug: string, 
    tool: Tool, 
    modifiers?: SchemaModifiersParams
  ): Promise<Tool>;

  async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]>;

  async getToolBySlug(
    slug: string, 
    modifiers?: SchemaModifiersParams
  ): Promise<Tool>;
}

必需方法（代理提供者）：

class AgenticProvider extends BaseAgenticProvider {
  async wrapTool(
    toolSlug: string, 
    tool: Tool, 
    modifiers?: ModifiersParams
  ): Promise<Tool>;

  async getTools(modifiers?: ModifiersParams): Promise<Tool[]>;
}

资料来源：ts/packages/providers/README.md:1-80

本地工具配置

本地工具元数据管理

本地工具支持通过 local_tools.json 文件进行配置：

{
  "toolkits": {
    "<toolkit-slug>": {
      "disabled": false,
      "installation": {
        "command": "npm install my-toolkit"
      }
    }
  },
  "tools": {
    "<tool-slug>": {
      "disabled": false,
      "authenticated": true,
      "installation": {
        "command": "pip install my-tool"
      }
    }
  }
}

工具包就绪状态检查

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]

就绪状态类型：

权限管理

权限确认流程

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: 执行或拒绝

权限决策选项

资料来源：ts/packages/cli/src/services/tool-permissions.ts:1-80

数据模型

工具包模型（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]": ...

自定义工具模型

export interface CustomTool {
  slug: string;
  name: string;
  description: string;
  inputParams: Param[];
  outputParams?: Param[];
  execute: (input: Record<string, unknown>) => Promise<unknown>;
}

工作流程

工具包发现与执行流程

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[终止]

配置参考

环境变量配置

CLI 配置选项

最佳实践

工具包开发

1. 遵循命名约定：工具包 slug 应使用小写字母和连字符
2. 版本控制：在 package.json 中指定版本范围
3. 平台支持：明确声明支持的平台列表
4. 错误处理：提供有意义的错误消息和恢复建议

性能优化

1. 按需加载：使用工具包过滤避免加载全部工具
2. 版本锁定：在生产环境中使用固定版本而非 'latest'
3. 本地缓存：利用本地工具包减少网络请求

相关资源

• 自定义工具和工具包文档
• 工具包索引文档
• CLI 工具命令参考
• 版本覆盖机制

概述

自定义工具（Custom Tools）允许开发者扩展 Composio 的工具生态系统，创建符合特定业务需求的专用工具。通过自定义工具接口，开发者可以定义工具的名称、描述、输入输出参数以及具体的执行逻辑，从而实现与外部系统或内部服务的集成。

Composio 支持多种工具创建方式，包括基于函数的自定义工具、工具包（Toolkit）组合以及本地 CLI 工具集成。这种灵活性使得开发者能够根据不同的使用场景选择最合适的工具定义方式。

核心概念

自定义工具的数据结构

自定义工具的核心模型包含以下关键属性：

工具包（Toolkit）

工具包是多个相关工具的集合，用于组织和管理具有相似功能或服务于同一目标的自定义工具。工具包提供了更高层次的抽象，便于批量处理和分类管理。

架构设计

工具执行流程

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[记录执行日志]

工具创建流程

graph TD
    A[定义工具元数据] --> B[创建工具实例]
    B --> C[配置执行函数]
    C --> D[注册到工具系统]
    D --> E[可用性验证]
    E --> F[工具已就绪]

TypeScript 实现

创建自定义工具

在 TypeScript 中，使用 createCustomTool 函数创建自定义工具。该函数接受工具的唯一标识符（slug）和一个配置对象。

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 函数将多个相关工具组合成一个工具包：

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 提供了本地工具声明机制：

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 类创建自定义工具：

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 类组合多个工具：

from composio import CustomToolkit

my_toolkit = CustomToolkit(
    name="my_custom_toolkit",
    description="A collection of custom tools",
    tools=[my_tool, another_tool]
)

异步执行支持

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"])
)

输入参数配置

参数类型

参数属性

工具权限管理

Composio 提供了工具权限验证机制，确保工具执行的安全性：

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 维护一个工具注册表，用于管理所有可用的工具和工具包：

工具过滤

支持按工具包名称过滤工具：

const declarations = getLocalToolkitDeclarations({
  toolkits: ['gmail', 'slack'],
  currentPlatform: 'linux',
});

最佳实践

工具设计原则

1. 单一职责：每个工具应专注于完成一个特定任务
2. 清晰的描述：提供详尽的工具和参数描述，便于 AI 理解
3. 适当的参数：避免过多必填参数，提供合理的默认值
4. 错误处理：在执行函数中妥善处理异常情况
5. 类型安全：使用正确的参数类型并提供验证

命名规范

安全性考虑

• 避免在工具描述中包含敏感信息
• 对外部输入进行严格验证
• 使用环境变量存储凭据而非硬编码
• 实现最小权限原则

示例项目

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 完整示例

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 提供了工具诊断命令：

# 检查工具就绪状态
composio local-tools doctor --toolkits <toolkit-name>

# 列出所有本地工具
composio local-tools list --all-platforms

日志查看

查看工具执行日志：

# 查看工具执行日志
composio dev logs tools <log_id>

# 查看触发器执行日志
composio dev logs triggers <log_id>

集成与使用

在代理中使用自定义工具

import { Composio } from '@composio/core';

const client = Composio();

// 注册自定义工具包
client.register(myToolkit);

// 获取配置好的代理
const agent = client.getAgent({
  instruction: '使用我的自定义工具完成数据处理任务',
});

配置本地工具元数据

通过 ~/composio/local_tools.json 配置文件自定义工具行为：

{
  "toolkits": {
    "my-toolkit": {
      "disabled": false,
      "installation": {
        "command": "pip install my-toolkit-dependency"
      }
    }
  }
}

相关资源

• 官方文档：Custom Tools Guide
• TypeScript 示例：ts/examples/custom-tools
• Python 示例：python/examples/custom_tools.py
• API 参考：CustomTools.ts

概述

AI 框架提供商（Provider）是 Composio 架构中的核心抽象层，负责将 Composio 的工具和功能与各类 AI 框架（如 OpenAI、Anthropic、LangChain 等）进行集成。提供商层作为中间件，封装了工具的获取、包装和执行逻辑，使开发者能够以统一的方式在不同的 AI 框架中使用 Composio 的工具集合。

Composio 的提供商系统设计为可扩展的架构，支持两种类型的提供商：

• 非代理型提供商（Non-Agentic Provider）：适用于直接将工具集成到 AI 框架的场景
• 代理型提供商（Agentic Provider）：适用于需要更复杂代理行为和上下文管理的场景

资料来源：ts/packages/providers/README.md:1-30

架构设计

整体架构图

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

提供商继承体系

graph LR
    A[BaseComposioProvider] --> B[BaseAgenticProvider]
    A --> C[BaseNonAgenticProvider]
    B --> D[Agentic Provider 实现]
    C --> E[Non-Agentic Provider 实现]

提供商类型系统

类型层次结构

Composio 使用 TypeScript 的条件类型系统来定义提供商的选项类型，确保类型安全性和正确的继承关系。

export type ProviderOptions<TProvider> =
  TProvider extends BaseComposioProvider<infer TToolCollection, infer TTool, infer TMcpResponse>
    ? TProvider extends BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>
      ? AgenticToolOptions
      : ToolOptions
    : never;

资料来源：ts/packages/core/src/types/modifiers.types.ts:1-50

Schema 修饰器

提供商支持通过 Schema 修饰器来修改工具的输入输出格式：

_GET_REPOS', {
  modifySchema: (context) => context.schema,
  beforeExecute: (context) => context.params,
  afterExecute: (context) => context.result
});

非代理型提供商

必需方法

非代理型提供商必须实现以下接口：

class NonAgenticProvider extends BaseNonAgenticProvider {
  // 使用 Schema 修饰器包装工具
  async wrapTool(
    toolSlug: string, 
    tool: Tool, 
    modifiers?: SchemaModifiersParams
  ): Promise<Tool>;

  // 获取所有可用工具
  async getTools(modifiers?: SchemaModifiersParams): Promise<Tool[]>;

  // 根据 slug 获取特定工具
  async getToolBySlug(
    slug: string, 
    modifiers?: SchemaModifiersParams
  ): Promise<Tool>;
}

使用场景

非代理型提供商适用于以下场景：

资料来源：ts/packages/providers/README.md:30-50

代理型提供商

必需方法

代理型提供商需要实现更复杂的方法集：

class AgenticProvider extends BaseAgenticProvider {
  // 使用修饰器包装工具
  async wrapTool(
    toolSlug: string, 
    tool: Tool, 
    modifiers?: ModifiersParams
  ): Promise<Tool>;

  // 获取所有可用工具
  async getTools(modifiers?: ModifiersParams): Promise<Tool[]>;
}

代理型特性

代理型提供商相比非代理型增加了以下能力：

• 上下文管理：自动维护执行上下文和状态
• 触发器支持：集成 Composio 的触发器系统
• 增强的错误处理：基于 Effect 的错误处理机制

资料来源：ts/packages/providers/README.md:50-70

创建新的提供商

目录结构

使用提供的脚本可以快速创建新的提供商：

# 创建非代理型提供商
pnpm run create-provider <your-provider-name>

# 创建代理型提供商
pnpm run create-provider <your-provider-name> --agentic

脚本将创建以下目录结构：

<provider-name>/
├── src/
│   └── index.ts      # 提供商实现
├── package.json      # 包配置
├── tsconfig.json     # TypeScript 配置
├── tsup.config.ts    # 构建配置
└── README.md         # 提供商文档

文件模板

package.json 配置

{
  "name": "@composio/<provider-name>",
  "version": "0.0.1",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

资料来源：ts/packages/providers/README.md:10-30

工具包装机制

包装流程

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: 包装后的工具

修饰器参数

与 CLI 的集成

命令行接口

Composio CLI 提供了完整的工具执行和查看命令：

资料来源：ts/packages/cli/src/services/command-hints.ts:1-60

工具权限系统

CLI 提供了交互式权限确认机制：

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

本地工具集成

注册表架构

本地工具通过注册表系统进行管理，与提供商架构协同工作：

graph TD
    subgraph "本地工具注册表"
        Decl[工具声明]
        Toolkit[工具包声明]
        Platform[平台标识]
    end
    
    Decl --> Toolkit
    Toolkit --> Platform

工具匹配逻辑

const toolkitMatchesFilter = (
  toolkit: LocalToolkitDeclaration,
  requestedToolkits?: ReadonlyArray<string>
): 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

平台支持

工具可以指定支持的平台集合：

const descriptionWithPlatform = (
  description: string,
  platforms: ReadonlyArray<LocalCliPlatform>
): string => `${description}\n\nLocal CLI platforms: ${formatSupportedPlatforms(platforms)}.`;

工具包版本管理

版本覆盖机制

Composio 支持对工具包进行版本控制：

export const groupByVersion = (
  specs: ReadonlyArray<ToolkitVersionSpec>
): Map<string, Lowercase<string>[]> => {
  const grouped = new Map<string, Lowercase<string>[]>();
  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;
};

版本规范处理

版本映射仅包含非 latest 的版本规范作为覆盖项。

资料来源：ts/packages/core/src/types/modifiers.types.ts:1-50

终端 UI 服务

日志级别

CLI 提供结构化的日志输出：

readonly log: {
  readonly info: (message: string) => Effect.Effect<void>;
  readonly success: (message: string) => Effect.Effect<void>;
  readonly warn: (message: string) => Effect.Effect<void>;
  readonly error: (message: string) => Effect.Effect<void>;
  readonly step: (message: string) => Effect.Effect<void>;
};

交互式选择

select: (
  message: string,
  options: ReadonlyArray<{ value: unknown; label: string; hint?: string }>
) => Effect.Effect<unknown>

支持用户从列表中选择选项，并在非交互模式下返回默认值。

资料来源：ts/packages/cli/src/services/terminal-ui.ts:1-80

错误处理机制

错误捕获流程

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[合并顺序错误]

错误解析

export const captureErrorsFrom = <E>(cause: Cause<E>): 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 协议

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 中，提供了完整的类型定义和接口规范。

Python 实现

Python 端的 MCP 模型位于 python/composio/core/models/mcp.py，采用 dataclass 风格的类型定义，与 TypeScript 版本保持功能对齐。

工作流程

工具发现流程

当 AI 客户端连接到 Composio MCP 服务器时，系统按以下流程完成工具发现：

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: 发送工具响应

工具执行流程

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 中提供了完整的使用示例：

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 环境下的使用方式：

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。适用于需要隔离权限或简化配置的部署场景。

graph LR
    A[AI 客户端] -->|MCP| B[单一工具包 MCP 服务器]
    B --> C[指定工具包]
    C --> D[该工具包下的所有工具]

配置示例：

# 单工具包 MCP 配置
mcp:
  mode: single-toolkit
  toolkit: gmail
  tools:
    - send_email
    - read_emails

API 参考

核心类

#### MCPServer

#### MCPTool

JSON-RPC 接口

MCP 协议基于 JSON-RPC 2.0 规范实现，支持以下标准方法：

配置选项

服务端配置

客户端配置

错误处理

MCP 协议定义了标准化的错误码体系：

与主流 AI 客户端集成

Claude Desktop

在 ~/.config/claude-desktop/claude_desktop_config.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 文档
• MCP API 参考
• Composio 核心概念

架构概览

Composio CLI 采用模块化架构设计，核心组件包括命令解析层、服务层和数据层。整个系统以 Effect 函数式编程库为基础，实现了声明式的命令定义和错误处理。

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 对象，通过组合子命令形成树状结构。

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

根命令层级

资料来源：ts/packages/cli/src/commands/tools/tools.cmd.ts:3-10

全局选项与帮助系统

全局 Flags

CLI 提供了一系列全局选项，用于控制命令行为：

资料来源：ts/packages/cli/src/commands/root-help.ts:1-15

帮助级别解析

帮助系统支持三种显示模式，通过 parseHelpLevel 函数进行解析：

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 服务器，显示浏览器内嵌的权限请求页面。

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 进行标识，注册表提供了完整的解析和过滤功能。

export const isLocalToolSlug = (
  toolSlug: string,
  options: { readonly declarations?: ReadonlyArray<LocalToolkitDeclaration> } = {}
): boolean => {
  const upper = toolSlug.toUpperCase();
  if (!upper.startsWith(LOCAL_TOOL_PREFIX)) return false;
  return (
    resolveLocalTool(toolSlug, { includeUnsupported: true, declarations: options.declarations }) !==
    null
  );
};

工具包过滤

注册表支持按名称过滤工具包，并自动检测当前平台支持情况：

export const getLocalToolkitDeclarations = (
  options: {
    readonly currentPlatform?: LocalCliPlatform;
    readonly toolkits?: ReadonlyArray<string>;
    readonly declarations?: ReadonlyArray<LocalToolkitDeclaration>;
  } = {}
): ReadonlyArray<LocalToolkitDeclaration> => {
  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 管理。

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

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

工具包索引生成

索引数据结构

工具包索引将所有工具和触发器按工具包名称分组存储：

export type ToolkitIndex = Record<ToolkitName, ToolkitIndexData>;

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 函数实现，自动从工具前缀提取工具包名称：

export function createToolkitIndex(input: CreateToolkitIndexInput): Simplify<ToolkitIndex> {
  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

命令提示系统

提示数据结构

命令提示系统为每个命令提供示例用法和相关链接：

type CommandHint = {
  example: (params: Record<string, string>) => string;
  links: ReadonlyArray<string>;
};

常用命令示例

资料来源：ts/packages/cli/src/services/command-hints.ts:1-80

日志系统

日志命令组

日志命令提供对工具和触发器执行历史的访问：

export const logsCmd = Command.make('logs').pipe(
  Command.withDescription('Inspect trigger and tool execution logs.'),
  Command.withSubcommands([logsCmd$Triggers, logsCmd$Tools])
);

资料来源：ts/packages/cli/src/commands/logs-cmd/logs.cmd.ts:1-20

TypeScript 类型生成

生成命令选项

composio generate ts 命令支持多种配置选项：

约束条件

• 输出目录不能指向 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 命令允许修改工具元数据：

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);
      // ...
    })
);

可配置项

配置后可通过 composio local-tools doctor 进行诊断验证。

资料来源：ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-80

错误处理

Effect 错误捕获

CLI 使用 Effect 框架的错误处理机制，通过 captureErrorsFrom 函数收集错误信息：

export const captureErrorsFrom = <E>(cause: Cause<E>): 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

快速参考

常用命令速查

# 搜索工具
composio search "send email"

# 列出工具包
composio toolkits list

# 查看工具详情
composio tools info <tool-slug>

# 执行工具
composio execute <tool-slug> -d '{"param": "value"}'

# 获取工具 schema
composio execute <tool-slug> --get-schema

# 初始化项目
composio dev init

# 诊断本地工具
composio local-tools doctor

# 查看执行日志
composio dev logs tools <log-id>

# 生成 TypeScript 类型
composio generate ts --toolkits gmail --toolkits slack

Pitfall Log / 踩坑日志

项目：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/[email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：@composio/[email protected]
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：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