-d '{}'` | 执行工具调用 |\n| `composio link ` | 链接账户 |\n| `composio dev init` | 初始化开发环境 |\n\n资料来源：[ts/packages/cli/src/services/command-hints.ts:1-80]()\n\n### 3.3 权限管理系统\n\nComposio 实现了完整的工具权限审批流程，确保工具调用的安全可控。\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 客户端\n participant Server as 权限服务器\n participant User as 用户\n \n CLI->>Server: 请求执行工具\n Server->>User: 显示权限确认页面\n User->>Server: 选择权限决策\n Server->>CLI: 返回决策结果\n```\n\n#### 权限决策类型\n\n| 决策 | 说明 | 有效期 |\n|------|------|--------|\n| `Allow for this session` | 会话级别允许 | 当前会话 |\n| `Allow once` | 单次允许 | 一次性 |\n| `Deny` | 拒绝 | 永久拒绝 |\n\n资料来源：[ts/packages/cli/src/services/tool-permissions.ts:1-60]()\n\n#### 权限确认页面\n\n系统通过本地 HTTP 服务器展示权限确认页面：\n\n```html\nAllow ${toolSlug}?
\nComposio CLI is requesting permission to execute this tool${accountLabel ? ` for ${accountLabel}` : ''}.
\n```\n\n### 3.4 Provider 系统\n\nProvider 系统提供了工具包装和修改的扩展机制，允许开发者自定义工具的行为。\n\n```mermaid\ngraph TD\n A[BaseComposioProvider] --> B[BaseNonAgenticProvider]\n A --> C[BaseAgenticProvider]\n \n B --> D[wrapTool]\n B --> E[getTools]\n B --> F[getToolBySlug]\n \n C --> G[wrapTool (Agentic)]\n C --> H[getTools (Agentic)]\n C --> I[getToolBySlug (Agentic)]\n```\n\n#### Provider 类型\n\n| Provider 类型 | 用途 | 主要方法 |\n|---------------|------|----------|\n| `BaseNonAgenticProvider` | 非智能体 Provider | `wrapTool`, `getTools`, `getToolBySlug` |\n| `BaseAgenticProvider` | 智能体 Provider | `wrapTool`, `getTools`, `getToolBySlug` |\n\n资料来源：[ts/packages/providers/README.md:1-80]()\n\n#### 工具修改器\n\nProvider 使用修改器（Modifiers）来调整工具的 Schema 和行为：\n\n```typescript\ntype ProviderOptions =\n TProvider extends BaseComposioProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n修改器支持的钩子函数：\n\n| 钩子函数 | 触发时机 | 用途 |\n|----------|----------|------|\n| `modifySchema` | Schema 生成时 | 修改输入输出结构 |\n| `beforeExecute` | 执行前 | 参数预处理 |\n| `afterExecute` | 执行后 | 结果后处理 |\n\n## 4. 核心组件详解\n\n### 4.1 终端 UI 服务\n\nTerminalUI 提供统一的命令行输出接口：\n\n```typescript\ninterface TerminalUI {\n readonly output: (data: string, options?: { force?: boolean }) => Effect;\n readonly intro: (title: string) => Effect;\n readonly outro: (message: string) => Effect;\n readonly log: {\n readonly info: (message: string) => Effect;\n readonly success: (message: string) => Effect;\n readonly warn: (message: string) => Effect;\n readonly error: (message: string) => Effect;\n readonly step: (message: string) => Effect;\n };\n readonly note: (message: string, title?: string) => Effect;\n readonly withSpinner: (message: string, effect: Effect) => Effect;\n}\n```\n\n资料来源：[ts/packages/cli/src/services/terminal-ui.ts:1-40]()\n\n### 4.2 错误处理机制\n\n系统使用 Effect 框架进行错误处理：\n\n```typescript\nexport const captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: (): readonly PrettyError[] => [],\n dieCase: (_, unknownError) => [parseError(unknownError)],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n parallelCase: (_, l, r) => [...l, ...r],\n sequentialCase: (_, l, r) => [...l, ...r],\n });\n```\n\n资料来源：[ts/packages/cli/src/effect-errors/logic/errors/capture-errors-from-cause.ts:1-20]()\n\n### 4.3 配置加载系统\n\n系统支持从文件加载和解析配置：\n\n```mermaid\ngraph LR\n A[配置文件] --> B[ConfigLoader]\n B --> C[Path 解析]\n C --> D[Primitive 解析]\n D --> E[split 分割]\n E --> F[Array]\n```\n\n支持的分隔符解析功能，允许用户自定义分隔符来拆分配置值。\n\n资料来源：[ts/packages/cli/src/effects/from-lazy-json.ts:1-50]()\n\n### 4.4 工具包索引\n\n工具包索引系统提供工具的分组和类型化支持：\n\n```typescript\nexport type CreateToolkitIndexInput = Simplify<{\n slug: string;\n version?: string;\n typeableTools:\n | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }\n | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };\n triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>;\n}>;\n\nexport type ToolkitIndex = Record;\n```\n\n资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts:1-30]()\n\n## 5. 开发指南\n\n### 5.1 环境准备\n\n```bash\n# 安装依赖\npnpm install\n\n# 安装 peer 依赖\npnpm check:peer-deps\n```\n\n资料来源：[ts/README.md:1-50]()\n\n### 5.2 创建新 Provider\n\n```bash\n# 创建非智能体 Provider\npnpm create:provider \n\n# 创建智能体 Provider\npnpm create:provider --agentic\n```\n\nProvider 创建后的结构：\n\n```\n/\n├── src/\n│ └── index.ts # Provider 实现\n├── package.json # 包配置\n├── tsconfig.json # TypeScript 配置\n├── tsup.config.ts # 构建配置\n└── README.md # 文档\n```\n\n资料来源：[ts/README.md:50-80]()\n\n### 5.3 创建示例代码\n\n```bash\npnpm create:example \n```\n\n### 5.4 本地工具配置\n\n本地工具支持灵活的配置文件管理：\n\n| 配置项 | 说明 |\n|--------|------|\n| `command` | 安装命令 |\n| `disabled` | 是否禁用 |\n| `authenticated` | 是否需要认证 |\n\n配置完成后可运行：\n\n```bash\ncomposio local-tools doctor --toolkits \n```\n\n资料来源：[ts/packages/cli/src/commands/local-tools/commands/local-tools.configure.cmd.ts:1-60]()\n\n## 6. Python SDK 文档生成\n\nComposio 使用 Griffe 工具从 Python 源码自动生成文档：\n\n```bash\ncd python\nuv run --with griffe python scripts/generate-docs.py\n```\n\n文档生成流程：\n\n```mermaid\ngraph LR\n A[Python 源码] -->|griffe 提取| B[结构化数据]\n B -->|transform| C[MDX 文件]\n C --> D[docs/content/reference/sdk-reference/python/]\n```\n\n资料来源：[python/scripts/README.md:1-30]()\n\n## 7. 项目技术栈\n\n### 7.1 TypeScript 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| Effect | 函数式错误处理和 Effect 编程 |\n| Effect/Cli | CLI 命令行框架 |\n| TypeScript | 类型系统 |\n| tsup | 构建工具 |\n\n### 7.2 Python 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| Griffe | Docstring 解析 |\n| MDX | 文档格式 |\n\n## 8. 总结\n\nComposio 是一个设计精良的 AI Agent 工具集成平台，其架构特点包括：\n\n1. **模块化设计**：通过 Monorepo 结构实现代码的高内聚低耦合\n2. **类型安全**：全面使用 TypeScript 提供类型保障\n3. **函数式编程**：采用 Effect 框架实现纯函数式错误处理\n4. **扩展性强**：Provider 系统支持自定义工具包装行为\n5. **双语言支持**：同时提供 TypeScript 和 Python SDK\n\n通过本项目，开发者可以快速构建基于 AI Agent 的应用，享受统一工具调用接口带来的便利。\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[TypeScript SDK 详解](#ts-sdk), [Python SDK 详解](#py-sdk), [AI 框架提供商集成](#providers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ts/examples/tool-router/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/examples/tool-router/README.md)\n- [python/README.md](https://github.com/ComposioHQ/composio/blob/main/python/README.md)\n- [ts/packages/cli/src/commands/root-help.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/commands/root-help.ts)\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [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)\n- [ts/packages/cli/src/services/command-hints.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli/src/services/command-hints.ts)\n \n\n# 快速入门指南\n\nComposio 是一个强大的 AI 代理工具集成平台，支持多种主流 AI 框架（如 OpenAI、LangChain 等）。本指南将帮助您快速上手 Composio，掌握核心概念、安装配置、工具使用以及 CLI 命令行工具的基本操作。\n\n## 概述\n\nComposio 提供了统一的工具抽象层，使 AI 代理能够访问超过 250+ 的外部应用工具。通过 Composio SDK，开发者可以：\n\n- 快速集成 OpenAI、Anthropic、LangChain 等主流 AI 框架\n- 获取并管理可用的应用工具\n- 使用 schema 修饰器转换工具架构\n- 通过 CLI 工具进行本地开发和调试\n\n## 环境要求\n\n| 组件 | 最低版本要求 |\n|------|-------------|\n| Node.js | >= 18.0.0 |\n| Python | >= 3.10 |\n| pnpm | >= 8.0.0 |\n\n## 安装配置\n\n### TypeScript SDK 安装\n\nComposio 的 TypeScript SDK 提供两种安装方式：完整包安装和按需安装 资料来源：[ts/packages/cli/src/commands/root-help.ts:1-50]()\n\n```bash\n# 完整安装\npnpm add @composio/core @composio/cli\n\n# 仅安装核心包\npnpm add @composio/core\n```\n\n### Python SDK 安装\n\n```bash\npip install composio-core\n```\n\n### 环境变量配置\n\n创建 `.env` 文件并配置以下环境变量 资料来源：[ts/examples/tool-router/README.md:10-20]()\n\n```bash\n# 必需的环境变量\nCOMPOSIO_API_KEY=your_api_key_here\n\n# 可选配置\nOPENAI_API_KEY=your_openai_key # OpenAI 集成必需\nOPENAI_MODEL=gpt-4o # 模型覆盖\nCOMPOSIO_BASE_URL=https://api.composio.dev # 自定义 API 地址\nCOMPOSIO_LOG_LEVEL=info # 日志级别\nCOMPOSIO_DISABLE_TELEMETRY=true # 禁用遥测\n```\n\n### CLI 初始化\n\n使用 `composio init` 命令初始化项目 资料来源：[ts/packages/cli/src/commands/init.cmd.ts:1-30]()\n\n```bash\n# 交互式初始化\ncomposio init\n\n# 或指定项目目录\ncomposio init --cwd ./my-project\n```\n\n初始化过程会提示您选择组织、创建项目，并自动生成 `.env.local` 配置文件。\n\n## 核心概念\n\n### 工具与工具包\n\nComposio 中的工具（Tool）是执行特定操作的最小单元，工具包（Toolkit）是相关工具的集合。每个工具都有唯一的 slug 标识符，格式为 `{TOOLKIT}_{ACTION}`，例如 `GITHUB_CREATE_REPO`。\n\n### Provider 提供商\n\nProvider 是 Composio SDK 与不同 AI 框架之间的桥梁。目前支持的提供商包括 资料来源：[ts/packages/providers/README.md:1-40]()\n\n| Provider 类型 | 说明 |\n|--------------|------|\n| OpenAIProvider | OpenAI Agents SDK 集成 |\n| AnthropicProvider | Anthropic Claude 集成 |\n| LangChainProvider | LangChain 框架集成 |\n\n### 修饰器\n\nComposio 支持强大的修饰器（Modifiers）功能，用于转换工具 schema 和执行行为 资料来源：[python/README.md:60-100]()\n\n```python\nfrom composio import schema_modifier\n\n@schema_modifier(tools=[\"HACKERNEWS_GET_USER\"])\ndef modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool:\n schema[\"description\"] = \"增强版用户查询\"\n return schema\n```\n\n## 快速开始示例\n\n### TypeScript 工具路由器\n\n以下示例展示如何使用 TypeScript SDK 进行工具路由 资料来源：[ts/examples/tool-router/src/index.ts:1-50]()\n\n```typescript\nimport { Composio } from \"@composio/core\";\n\nasync function main() {\n // 初始化 SDK\n const client = new Composio({\n apiKey: process.env.COMPOSIO_API_KEY,\n });\n\n // 获取所有可用工具\n const tools = await client.tools.list();\n\n // 获取特定工具\n const githubTool = await client.tools.get({\n slug: \"GITHUB_CREATE_REPO\",\n app: \"github\"\n });\n\n // 执行工具\n const result = await client.execute(\"github_create_repo\", {\n name: \"my-new-repo\",\n description: \"Repository created via Composio\"\n });\n}\n```\n\n### Python OpenAI Agents 集成\n\n```python\nfrom composio import Composio\nfrom openai import OpenAI\n\nclient = Composio(api_key=\"your_api_key\")\nopenai_client = OpenAI()\n\n# 获取工具\ntools = client.tools.get_tools(apps=[\"github\", \"slack\"])\n\n# 在 OpenAI Agents 中使用\nassistant = openai_client.beta.assistants.create(\n model=\"gpt-4o\",\n tools=tools\n)\n```\n\n## CLI 命令参考\n\n### 常用命令速查\n\n| 命令 | 功能 |\n|------|------|\n| `composio init` | 初始化新项目 |\n| `composio tools list` | 列出所有可用工具 |\n| `composio tools info ` | 查看工具详情 |\n| `composio execute ` | 执行指定工具 |\n| `composio link ` | 连接第三方账户 |\n| `composio local-tools list` | 列出本地工具 |\n\n### 工具列表命令\n\n```bash\n# 列出所有工具\ncomposio tools list\n\n# 列出特定工具包的工具\ncomposio tools list --toolkit github\n\n# JSON 格式输出\ncomposio tools list --json\n```\n\n### 工具信息查询\n\n```bash\n# 查看工具详情\ncomposio tools info GITHUB_CREATE_REPO\n\n# 获取工具执行 schema\ncomposio execute GITHUB_CREATE_REPO --get-schema\n```\n\n### 执行工具\n\n```bash\n# 执行工具（交互式）\ncomposio execute GITHUB_CREATE_REPO\n\n# 执行工具（传入参数）\ncomposio execute GITHUB_CREATE_REPO -d '{\"name\": \"my-repo\", \"private\": true}'\n```\n\n### 账户连接\n\n```bash\n# 连接第三方账户\ncomposio link github\ncomposio link slack\n\n# 查看已连接账户\ncomposio accounts list\n```\n\n## 本地 CLI 工具\n\nComposio 支持本地 CLI 工具扩展，允许 Tool Router 搜索和执行本地工具 资料来源：[ts/packages/cli-local-tools/src/registry.ts:1-60]()\n\n### 本地工具命令\n\n| 命令 | 功能 |\n|------|------|\n| `composio local-tools list` | 列出已注册本地工具包 |\n| `composio local-tools doctor` | 检查本地工具就绪状态 |\n| `composio local-tools configure` | 配置本地工具 |\n\n### 配置本地工具\n\n```bash\n# 配置工具包\ncomposio local-tools configure \\\n --command /path/to/tool \\\n --authenticated\n\n# 禁用工具\ncomposio local-tools configure --disable\n\n# 启用工具\ncomposio local-tools configure --enable\n```\n\n### 列出本地工具\n\n```bash\n# 基本列表\ncomposio local-tools list\n\n# 包含不支持当前平台的工具\ncomposio local-tools list --all-platforms\n\n# 过滤特定工具包\ncomposio local-tools list --toolkits mytoolkit\n\n# JSON 格式输出\ncomposio local-tools list --json\n```\n\n## 开发模式\n\nComposio 提供开发模式用于本地调试和测试 资料来源：[ts/packages/cli/src/commands/root-help.ts:40-80]()\n\n### 开发命令\n\n```bash\n# 初始化开发环境\ncomposio dev init\n\n# 在 Playgroun 中执行工具\ncomposio dev playground-execute \\\n --user-id \\\n -d '{}'\n\n# 获取执行 schema\ncomposio dev playground-execute --get-schema\n\n# 查看工具执行日志\ncomposio dev logs tools \n\n# 查看触发器日志\ncomposio dev logs triggers \n```\n\n## 工具包管理\n\n### 发现工具包\n\n```bash\n# 列出所有工具包\ncomposio toolkits list\n\n# 搜索工具包\ncomposio toolkits search \n\n# 查看工具包详情\ncomposio toolkits info \n```\n\n### 管理工具包版本\n\n```bash\n# 查看工具包版本\ncomposio toolkits version \n\n# 设置特定版本\nCOMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00\n```\n\n## 工作流程图\n\n### 基本集成流程\n\n```mermaid\ngraph TD\n A[初始化 Composio SDK] --> B[配置 API Key]\n B --> C[获取可用工具]\n C --> D[选择工具包]\n D --> E[执行工具操作]\n E --> F{操作成功?}\n F -->|是| G[返回结果]\n F -->|否| H[错误处理]\n```\n\n### CLI 工具执行流程\n\n```mermaid\ngraph TD\n A[composio 命令] --> B{子命令类型}\n B -->|tools| C[工具操作]\n B -->|execute| D[执行工具]\n B -->|local-tools| E[本地工具]\n B -->|dev| F[开发模式]\n \n C --> C1[list/信息查询]\n D --> D1[权限检查]\n D1 --> D2[执行工具]\n E --> E1[配置/列表/诊断]\n F --> F1[Playground/日志]\n```\n\n## 最佳实践\n\n### 1. 项目结构组织\n\n```\nmy-agent-project/\n├── .env.local # 本地环境变量\n├── composio.config.ts # SDK 配置\n├── src/\n│ ├── index.ts # 入口文件\n│ └── tools/ # 工具封装\n└── package.json\n```\n\n### 2. 安全管理\n\n- 使用环境变量存储 API Key，避免硬编码\n- 使用 `.env.local` 存储项目级敏感信息\n- 通过 CLI 的权限确认功能控制工具执行\n\n### 3. 错误处理\n\n```typescript\nimport { ComposioSDKError } from \"@composio/core\";\n\ntry {\n const result = await client.execute(\"tool_slug\", params);\n} catch (error) {\n if (error instanceof ComposioSDKError) {\n console.error(`SDK Error: ${error.message}`);\n }\n}\n```\n\n### 4. 性能优化\n\n- 预加载常用工具到 `session.tools()`\n- 使用 `SessionPreset.DIRECT_TOOLS` 预加载所有允许的工具\n- 避免在循环中频繁调用工具获取接口\n\n## 常见问题\n\n### Q: 如何获取 API Key？\n\n访问 [Composio Dashboard](https://app.composio.dev) 注册账号并获取 API Key。\n\n### Q: 工具执行失败怎么办？\n\n1. 使用 `composio local-tools doctor` 检查本地环境\n2. 使用 `composio tools info ` 确认工具参数正确\n3. 查看 `composio dev logs tools ` 获取详细错误信息\n\n### Q: 如何使用自定义 Provider？\n\n参考 [Provider 创建文档](ts/packages/providers/README.md)，使用 `pnpm run create-provider ` 创建自定义 Provider。\n\n## 下一步\n\n- 深入阅读 [工具包文档](ts/packages/cli/src/commands/toolkits/toolkits.cmd.ts)\n- 了解 [Schema 修饰器](python/README.md)的高级用法\n- 探索 [OpenAI 集成示例](python/examples/tool_router/openai_agents.py)\n- 加入 [Discord 社区](https://discord.gg/composio) 获取帮助\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[TypeScript SDK 详解](#ts-sdk), [Python SDK 详解](#py-sdk), [工具包系统](#toolkits)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/composio.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/composio.ts)\n- [ts/packages/core/src/provider/ComposioProvider.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/provider/ComposioProvider.ts)\n- [python/composio/sdk.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/sdk.py)\n- [ts/packages/core/src/models/ToolRouter.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ToolRouter.ts)\n- [python/composio/core/models/tool_router.py](https://github.com/ComposioHQ/composio/blob/main/python/composio/core/models/tool_router.py)\n- [ts/packages/cli-local-tools/src/registry.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/cli-local-tools/src/registry.ts)\n- [ts/packages/providers/README.md](https://github.com/ComposioHQ/composio/blob/main/ts/packages/providers/README.md)\n- [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)\n \n\n# 系统架构\n\n## 概述\n\nComposio 是一个多语言 Agent 工具集成平台，支持通过统一的 SDK 接口调用外部工具和服务。系统架构采用分层设计，核心层负责工具路由和执行管理，Provider 层提供灵活的扩展机制，CLI 层提供命令行交互能力。本文档基于源码分析，阐述 Composio 的整体架构设计、各核心模块职责以及跨语言 SDK 的实现机制。\n\n## 架构分层\n\nComposio 系统采用四层架构设计，从上到下依次为：\n\n| 层级 | 名称 | 职责 | 主要实现 |\n|------|------|------|----------|\n| 1 | SDK 层 | 对外提供统一的工具调用接口 | `composio.ts`、`sdk.py` |\n| 2 | 核心层 | 工具路由、Schema 修饰、Provider 管理 | `ToolRouter.ts`、`tool_router.py` |\n| 3 | Provider 层 | 工具封装、Schema 转换、执行拦截 | `ComposioProvider.ts` |\n| 4 | CLI 层 | 命令行工具、本地工具注册 | `registry.ts` |\n\n```mermaid\ngraph TD\n subgraph SDK层\n TS_SDK[TypeScript SDK
composio.ts]\n PY_SDK[Python SDK
sdk.py]\n end\n\n subgraph 核心层\n TR_TypeScript[ToolRouter
TypeScript]\n TR_Python[ToolRouter
Python]\n end\n\n subgraph Provider层\n CP[ComposioProvider]\n BaseProvider[BaseComposioProvider]\n AgenticProvider[BaseAgenticProvider]\n end\n\n subgraph CLI层\n CLI[Composio CLI]\n LocalRegistry[本地工具注册表
registry.ts]\n end\n\n subgraph 外部服务\n API[Composio API]\n MCP[MCP Server]\n end\n\n TS_SDK --> TR_TypeScript\n PY_SDK --> TR_Python\n TR_TypeScript --> CP\n TR_Python --> CP\n CP --> BaseProvider\n CP --> AgenticProvider\n CLI --> LocalRegistry\n CP --> API\n CP --> MCP\n```\n\n## 核心模块\n\n### SDK 入口\n\nComposio 提供 TypeScript 和 Python 两种 SDK 入口，两者在设计思想上保持一致，但实现细节根据语言特性有所差异。\n\n#### TypeScript SDK\n\nTypeScript SDK 的核心入口位于 `composio.ts`，该文件导出一个统一的 `Composio` 类。SDK 初始化时接受配置参数，包括 API 密钥、基础 URL、日志级别等。SDK 内部持有 `ComposioTool` 实例用于工具管理，并通过 `ComposioProvider` 与后端服务通信。\n\n主要配置选项：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `apiKey` | `string` | Composio API 密钥 |\n| `baseURL` | `string` | API 基础地址，默认为 Composio 官方服务 |\n| `toolkitVersionOverrides` | `Map` | 工具包版本覆盖 |\n| `logLevel` | `LogLevel` | 日志级别：silent、error、warn、info、debug |\n| `disableTelemetry` | `boolean` | 是否禁用遥测数据 |\n\n#### Python SDK\n\nPython SDK 位于 `python/composio/sdk.py`，采用类式设计，提供 `Composio` 类作为主要入口。Python SDK 通过 `openai` 库实现与 OpenAI 生态的集成，同时支持自定义 LLM 客户端。\n\n### 工具路由器\n\n工具路由器（ToolRouter）是架构的核心组件，负责工具的注册、查询和路由。\n\n#### TypeScript ToolRouter\n\n`ToolRouter.ts` 实现了 TypeScript 端的工具路由逻辑。路由器维护一个工具索引（ToolkitIndex），将工具按照所属工具包（Toolkit）进行分组管理。\n\n关键数据结构：\n\n```typescript\nexport type ToolkitIndex = Record;\n\nexport type ToolkitIndexData = Simplify<{\n slug: string;\n version?: string;\n typeableTools: \n | { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }\n | { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };\n triggerTypes: Record<`${ToolkitName}_${string}`, TriggerType>;\n}>;\n```\n\n路由器通过 `createToolkitIndex` 函数从输入数据构建索引，该函数接收版本映射（versionMap）用于工具包版本控制。\n\n#### Python ToolRouter\n\nPython 端在 `python/composio/core/models/tool_router.py` 中实现对应的路由器功能。Python 版本同样维护工具索引，但使用 Python 原生的字典和类结构。\n\n### Provider 体系\n\nProvider 是 Composio 架构中实现工具封装和执行拦截的关键组件。系统定义了两种 Provider 类型：\n\n#### BaseComposioProvider\n\n基础 Provider 实现了工具的包装和获取逻辑。所有非 Agentic Provider 都继承自此类：\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: SchemaModifiersParams): Promise;\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n async getToolBySlug(slug: string, modifiers?: SchemaModifiersParams): Promise;\n}\n```\n\n#### BaseAgenticProvider\n\nAgentic Provider 继承自基础 Provider，增加了对 Agentic 工具的支持。Agentic 工具具有更复杂的执行流程，能够在执行前后进行上下文干预：\n\n```typescript\nclass AgenticProvider extends BaseAgenticProvider {\n async wrapTool(toolSlug: string, tool: Tool, modifiers?: ModifiersParams): Promise;\n async getTools(modifiers?: ModifiersParams): Promise;\n}\n```\n\n#### ComposioProvider\n\n`ComposioProvider.ts` 是 SDK 与外部服务通信的主要入口，它组合了多个底层 Provider 的能力：\n\n```mermaid\ngraph LR\n ComposioProvider -->|持有| BaseComposioProvider\n ComposioProvider -->|持有| BaseAgenticProvider\n ComposioProvider -->|调用| ComposioToolkitsRepository\n ComposioProvider -->|调用| HTTPClient\n```\n\nProvider 的选择通过类型推断实现，SDK 根据传入的 Provider 类型自动选择合适的工具选项类型：\n\n```typescript\nexport type ProviderOptions =\n TProvider extends BaseComposicProvider\n ? TProvider extends BaseAgenticProvider\n ? AgenticToolOptions\n : ToolOptions\n : never;\n```\n\n## 工具包版本管理\n\nComposio 支持通过环境变量对工具包版本进行精细化控制。每个工具包可以指定特定版本或使用最新版本。\n\n### 版本覆盖机制\n\n版本覆盖通过 `ToolkitVersionOverrides` 类型管理：\n\n```typescript\nexport type ToolkitVersionOverrides = Map, string>;\n```\n\n### 版本分组与验证\n\n版本分组逻辑将具有相同版本的工具包聚合在一起，便于批量处理：\n\n```typescript\nexport const groupByVersion = (\n specs: ReadonlyArray\n): Map[]> => {\n const grouped = new Map[]>();\n for (const spec of specs) {\n const existing = grouped.get(spec.toolkitVersion);\n if (existing) {\n existing.push(spec.toolkitSlug);\n } else {\n grouped.set(spec.toolkitVersion, [spec.toolkitSlug]);\n }\n }\n return grouped;\n};\n```\n\n版本验证通过 `validateToolkitVersionOverrides` 函数执行，该函数会调用 API 验证版本有效性并在遇到错误时提供友好的错误信息。\n\n### 环境变量配置\n\n工具包版本可通过以下格式的环境变量配置：\n\n| 环境变量 | 说明 | 示例 |\n|----------|------|------|\n| `COMPOSIO_TOOLKIT_VERSION_` | 指定工具包版本 | `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00` |\n\n版本值 `\"latest\"` 表示使用最新版本，不会被添加到版本映射中。\n\n## Schema 修饰器\n\nSchema 修饰器（Schema Modifiers）允许在工具执行的不同阶段对请求和响应进行处理。这是实现日志记录、参数转换、结果过滤等功能的基础机制。\n\n### 修饰器类型\n\n```typescript\ninterface SchemaModifiersParams {\n modifySchema?: (context: SchemaModificationContext) => SchemaModificationResult;\n beforeExecute?: (context: ExecutionContext) => ExecutionContext;\n afterExecute?: (context: ExecutionContext) => ExecutionContext;\n}\n```\n\n### 执行流程\n\n```mermaid\ngraph TD\n A[接收工具调用] --> B{有 modifySchema?}\n B -->|是| C[应用 Schema 修饰]\n B -->|否| D[使用原始 Schema]\n C --> E{有 beforeExecute?}\n D --> E\n E -->|是| F[执行 beforeExecute]\n E -->|否| G[调用工具]\n F --> G\n G --> H{有 afterExecute?}\n H -->|是| I[执行 afterExecute]\n H -->|否| J[返回结果]\n I --> J\n```\n\n## 本地工具系统\n\nComposio CLI 提供本地工具注册和管理能力，允许用户定义和执行本地命令行工具。\n\n### 本地工具注册表\n\n本地工具注册表（`registry.ts`）负责管理所有本地工具的定义和元数据：\n\n```typescript\nexport const getAllLocalToolkitSlugs = (\n options: { readonly declarations?: ReadonlyArray } = {}\n): ReadonlyArray =>\n declarationsFor(options.declarations).map(toolkit => toolkit.slug.toLowerCase());\n```\n\n### 工具匹配与过滤\n\n注册表提供多种匹配工具的方法：\n\n| 方法 | 用途 |\n|------|------|\n| `toolkitMatchesFilter` | 检查工具包是否匹配过滤器 |\n| `isLocalToolkitSlug` | 验证是否为本地工具包 |\n| `isLocalToolSlug` | 验证是否为本地工具 |\n| `resolveLocalTool` | 根据 slug 解析本地工具 |\n\n### 本地工具执行\n\n本地工具通过统一的执行函数处理：\n\n```typescript\nconst executeLocalTool = async (\n execution: LocalToolExecution,\n input: Record,\n options: ExecuteLocalToolOptions\n) => {\n // 处理工具执行逻辑\n};\n```\n\n## 错误处理机制\n\nComposio 使用 Effect 库进行函数式错误处理，通过 `captureErrorsFrom` 函数将 Effect 的 Cause 转换为友好的错误信息：\n\n```typescript\nexport const captureErrorsFrom = (cause: Cause): readonly PrettyError[] =>\n reduceWithContext(cause, undefined, {\n emptyCase: (): readonly PrettyError[] => [],\n dieCase: (_, unknownError) => [parseError(unknownError)],\n failCase: (_, error) => [parseError(error)],\n interruptCase: () => [],\n parallelCase: (_, l, r) => [...l, ...r],\n sequentialCase: (_, l, r) => [...l, ...r],\n });\n```\n\n## CLI 命令架构\n\nComposio CLI 采用 Effect 框架构建命令系统，每个命令都是一个 Effect 子程序。命令通过模块化组织，核心命令包括：\n\n| 命令 | 功能 |\n|------|------|\n| `composio execute` | 执行指定工具 |\n| `composio tools list` | 列出工具包中的工具 |\n| `composio tools info` | 查看工具详情 |\n| `composio local-tools` | 管理本地工具 |\n| `composio dev init` | 初始化开发环境 |\n| `composio dev playground-execute` | 操场执行工具 |\n\n### TypeScript 生成命令\n\n`ts.generate.cmd.ts` 实现了 `composio generate ts` 命令，用于生成 TypeScript 类型定义文件：\n\n```mermaid\ngraph LR\n A[generate ts 命令] --> B{指定 --output-dir?}\n B -->|是| C[写入指定目录]\n B -->|否| D[查找 @composio/core]\n C --> E{指定 --transpiled?}\n D --> E\n E -->|是| F[生成 .ts + .js]\n E -->|否| G[仅生成 .ts]\n F --> H[完成]\n G --> H\n```\n\n## Provider 扩展机制\n\nComposio 支持通过创建自定义 Provider 来扩展系统功能。创建新 Provider 的标准流程：\n\n1. 使用 `pnpm create:provider ` 创建 Provider 骨架\n2. 在 `src/index.ts` 中实现必要方法\n3. 注册 Provider 到 SDK\n\n```bash\n# 创建非 Agentic Provider\npnpm create:provider my-provider\n\n# 创建 Agentic Provider\npnpm create:provider my-provider --agentic\n```\n\n## 数据流总结\n\n```mermaid\ngraph TD\n subgraph 用户代码\n User[用户调用 SDK]\n end\n\n subgraph SDK 层\n Composio_SDK[Composio SDK]\n end\n\n subgraph 核心层\n ToolRouter[ToolRouter]\n ToolkitIndex[ToolkitIndex]\n end\n\n subgraph Provider 层\n Provider[ComposioProvider]\n MCP_Client[MCP Client]\n end\n\n subgraph 外部\n API[Composio API]\n MCP_Server[MCP Server]\n end\n\n User --> Composio_SDK\n Composio_SDK --> ToolRouter\n ToolRouter --> ToolkitIndex\n Composio_SDK --> Provider\n Provider --> API\n Provider --> MCP_Client\n MCP_Client --> MCP_Server\n```\n\nComposio 的架构设计强调模块化、可扩展性和跨语言一致性。通过清晰的层次划分和标准化的 Provider 接口，系统能够灵活适应不同的使用场景和集成需求。\n\n---\n\n\n\n## TypeScript SDK 详解\n\n### 相关页面\n\n相关主题：[Python SDK 详解](#py-sdk), [AI 框架提供商集成](#providers), [工具包系统](#toolkits)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ts/packages/core/src/index.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/index.ts)\n- [ts/packages/core/src/models/Tools.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Tools.ts)\n- [ts/packages/core/src/models/Toolkits.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/Toolkits.ts)\n- [ts/packages/core/src/models/ToolRouterSession.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ToolRouterSession.ts)\n- [ts/packages/core/src/models/ConnectedAccounts.ts](https://github.com/ComposioHQ/composio/blob/main/ts/packages/core/src/models/ConnectedAccounts.ts)\n- [ts/docs/api/tools.md](https://github.com/ComposioHQ/composio/blob/main/ts/docs/api/tools.md)\n \n\n# TypeScript SDK 详解\n\n## 概述\n\nComposio TypeScript SDK 是用于与 Composio 平台交互的核心开发工具包，为 AI Agent 提供工具调用、工具包管理、账户连接等功能。该 SDK 构建于 Effect 框架之上，采用函数式编程范式，支持类型安全的工具操作和灵活的扩展机制。 资料来源：[ts/README.md]()\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[ComposioClient] --> B[ToolRouter]\n A --> C[ConnectedAccounts]\n B --> D[Toolkits]\n B --> E[Tools]\n D --> E\n F[Providers] --> E\n G[CLI Tools] --> E\n```\n\n### 包结构概览\n\n| 包名称 | 路径 | 职责 |\n|--------|------|------|\n| `@composio/core` | `packages/core` | 核心 SDK，包含所有核心模型和服务 |\n| `@composio/cli` | `packages/cli` | 命令行工具，支持项目初始化和类型生成 |\n| `@composio/providers` | `packages/providers/*` | AI 框架集成（OpenAI、LangChain、Vercal 等） |\n| `@composio/ts-builders` | `packages/ts-builders` | TypeScript AST 构建工具，用于生成类型存根 |\n| `@composio/cli-local-tools` | `packages/cli-local-tools` | 本地 CLI 工具注册表 |\n\n资料来源：[ts/README.md](), [ts/packages/ts-builders/README.md]()\n\n## 核心模型\n\n### Tools（工具）\n\n`Tool` 模型代表单个可执行工具，是 SDK 的基本操作单元。每个工具包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `slug` | `string` | 工具唯一标识符 |\n| `name` | `string` | 工具显示名称 |\n| `description` | `string` | 工具功能描述 |\n| `inputParams` | `InputParameter[]` | 输入参数定义 |\n| `outputParams` | `OutputParameter[]` | 输出参数定义 |\n| `toolkit` | `Toolkit` | 所属工具包 |\n| `triggers` | `Trigger[]` | 触发器配置 |\n\n资料来源：[ts/packages/core/src/models/Tools.ts](), [ts/packages/cli/src/generation/create-toolkit-index.ts]()\n\n### Toolkits（工具包）\n\n`Toolkit` 是工具的逻辑分组容器，提供组织和管理相关工具的能力：\n\n```typescript\nexport type ToolkitIndex = Record;\n```\n\n工具包数据包含版本管理和工具集合映射，支持按名称动态访问工具定义。 资料来源：[ts/packages/cli/src/generation/create-toolkit-index.ts]()\n\n### ToolRouterSession（会话路由）\n\n`ToolRouterSession` 负责管理工具调用的生命周期，包括参数验证、执行和结果处理：\n\n```mermaid\nsequenceDiagram\n Agent->>ToolRouterSession: requestToolCall(toolSlug, params)\n ToolRouterSession->>Tool: validateParams(params)\n Tool-->>ToolRouterSession: validatedParams\n ToolRouterSession->>Tool: execute(validatedParams)\n Tool-->>ToolRouterSession: executionResult\n ToolRouterSession->>Agent: formattedResponse\n```\n\n资料来源：[ts/packages/core/src/models/ToolRouterSession.ts]()\n\n### ConnectedAccounts（连接账户）\n\n`ConnectedAccounts` 管理用户与第三方服务的授权连接，是工具执行认证的基础：\n\n| 属性 | 说明 |\n|------|------|\n| `accountId` | 账户唯一标识 |\n| `integrationId` | 集成标识 |\n| `connectionStatus` | 连接状态 |\n| `credentials` | 加密凭证 |\n| `metadata` | 额外元数据 |\n\n资料来源：[ts/packages/core/src/models/ConnectedAccounts.ts]()\n\n## Provider 机制\n\n### Provider 类型\n\nSDK 支持两种 Provider 类型，分别适用于不同的 AI 框架集成场景：\n\n| Provider 类型 | 基类 | 用途 |\n|---------------|------|------|\n| 非 Agentic | `BaseNonAgenticProvider` | 基础工具包装和模式转换 |\n| Agentic | `BaseAgenticProvider` | 支持完整执行流程修饰符 |\n\n资料来源：[ts/packages/providers/README.md](), [ts/packages/core/src/types/modifiers.types.ts]()\n\n### Provider 方法\n\n#### 非 Agentic Provider\n\n```typescript\nclass NonAgenticProvider extends BaseNonAgenticProvider {\n async wrapTool(\n toolSlug: string, \n tool: Tool, \n modifiers?: SchemaModifiersParams\n ): Promise;\n\n async getTools(modifiers?: SchemaModifiersParams): Promise;\n\n async getToolBySlug(\n slug: string, \n modifiers?: SchemaModifiersParams\n ): Promise;\n}\n```\n\n#### Agentic Provider\n\nAgentic Provider 在非 Agentic 基础上增加执行修饰符支持：\n\n```typescript\ntype beforeExecuteModifier = (\n toolSlug: string,\n params: Record\n) => Record;\n\ntype afterExecuteModifier = (\n toolSlug: string,\n response: ToolExecuteResponse\n) => ToolExecuteResponse;\n```\n\n资料来源：[ts/packages/providers/README.md](), [ts/packages/core/src/types/modifiers.types.ts]()\n\n### 内置 Providers\n\n| Provider | 包路径 | AI 框架 |\n|----------|--------|---------|\n| OpenAI Provider | `packages/providers/openai` | OpenAI |\n| LangChain Provider | `packages/providers/langchain` | LangChain |\n| Vercel Provider | `packages/providers/vercel` | Vercel AI SDK |\n| Claude Agent SDK Provider | `packages/providers/claude-agent-sdk` | Anthropic Claude Agent SDK |\n\n资料来源：[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]()\n\n## 类型生成系统\n\n### TypeScript 类型存根\n\nCLI 提供 `composio generate ts` 命令用于生成 TypeScript 类型存根：\n\n```bash\ncomposio generate ts\ncomposio generate ts --type-tools\ncomposio generate ts --toolkits gmail slack\n```\n\n生成器支持以下选项：\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--compact` | 生成单个模块文件 | `false` |\n| `--transpiled` | 同时生成转译后的 JavaScript | 写入 `node_modules` 时为 `true` |\n| `--output-dir` | 指定输出目录 | `@composio/core` 包路径 |\n| `--toolkits` | 仅包含指定工具包 | 全部工具包 |\n\n资料来源：[ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts](), [ts/packages/cli/src/commands/generate/generate.cmd.ts]()\n\n### 文档生成\n\nSDK 使用 TypeDoc 从源代码提取 JSDoc 注释生成 MDX 文档：\n\n```mermaid\ngraph LR\n A[src/models/*.ts] -->|TypeDoc| B[JSON AST]\n B -->|generate-docs.ts| C[MDX 文件]\n C --> D[docs/content/reference/sdk-reference/typescript/]\n```\n\n工作流程由 GitHub Actions 自动化触发：`.github/workflows/generate-sdk-docs.yml` 监听 `ts/packages/core/src/**` 变更并自动创建 PR。 资料来源：[ts/packages/core/scripts/README.md]()\n\n## 本地工具注册\n\n`@composio/cli-local-tools` 包提供本地 CLI 工具的注册和管理能力：\n\n```typescript\nexport const getAllLocalToolkitSlugs = (\n options?: { declarations?: ReadonlyArray }\n): ReadonlyArray