连接器

Open Connector 将认证 Provider与Toolkit分开建模。这一区分很重要：Provider 负责凭证如何收集、保存、刷新和注入；Toolkit 定义 Agent 可以调用的可执行工具。二者经常使用同一个 slug，但并不互为同义词。

当前目录模型

目录对象	负责什么	运行时表示
认证 Provider	OAuth/API Key/Basic 方式、连接字段、出站代理规则、凭证校验和 Provider 元数据。	`ProviderConfig` 经校验后 seed 到 `provider_config`。
Toolkit	面向 Agent 的工具元数据和可执行操作。它可以引用同 slug 的 Provider、另一个 Provider，或暂时没有认证 Provider。	Registry 和官方 Toolkit 工件发布到 Toolkit Catalog。
Connection	某个用户在一个项目范围内、针对一个已选 Provider 认证方式的加密凭证集合。	独立于两类 Catalog 对象单独存储。

运行时目录不再只有 GitHub 和 Telegram。它包含生成的 Provider Catalog，以及官方和生成的 Toolkit。请使用带认证的 Toolkit discovery 接口或实时 API 文档查看当前部署实际提供的内容。

旧的扁平 Connector 结构——顶层只有一个 authMode、authorizationUrl、tokenUrl 和 credentials——已经废弃。认证现在放在 authMethods 数组中，因此一个 Provider 可以同时提供 OAuth 和个人 Token 两种流程。

认证方式

authMethods 的每一项都有命名空间 id，例如 github.oauth2，并标记为 available 或带原因的 unavailable。可用方式包含以下 kind：

Kind	用户提供什么	Broker 做什么
`oauth2`	浏览器授权；配置了时也可使用 client credentials。	构建授权 URL、交换和刷新 Token，再加密保存。
`api_key`	长期 API Key 或 Token。	加密保存用户提供的字段，并注入到已配置请求中。
`basic`	用户名/密码或等价的 key/secret 对。	加密保存两个值，并注入 Basic Auth 凭证或配置的请求字段。

不可用方式仍会出现在目录中以说明覆盖范围，但在所需 runtime adapter 实现前不能连接。

Provider 配置

ProviderConfig 仍是认证 Provider 的内部类型；它的当前结构如下。必填字段是 slug、displayName、authMethods 和 proxy.baseUrl。

字段	用途
`authMethods`	一个或多个命名认证方式。OAuth 选项放在 `method.oauth2`；API Key/Basic 字段放在 `method.credentials`。
`connectionConfig`	每条连接的非默认字段，例如租户 hostname 或 account ID。敏感字段可以标记为 `secret`。
`proxy`	Provider 级 base URL、允许列表、请求模板和可选的凭证校验请求。单个 method 可附加自己的 header/query/body 模板。
`description`、`logoDomain`、`appUrl`、`authGuideUrl`、`documentationUrl`	展示给用户和 Agent 的目录元数据。
`version`、`deprecated`、`categories`、`changelog`	生命周期与发现元数据。

OAuth Provider 示例

import type { ProviderConfig } from "@open-connector/catalog";

export const myCrm = {
  slug: "my-crm",
  displayName: "My CRM",
  authMethods: [
    {
      id: "my-crm.oauth2",
      displayName: "My CRM OAuth",
      kind: "oauth2",
      status: "available",
      oauth2: {
        authorizationUrl: "https://app.mycrm.com/oauth/authorize",
        tokenUrl: "https://app.mycrm.com/oauth/token",
        defaultScopes: ["contacts:read", "contacts:write"],
        scopeSeparator: " ",
      },
    },
  ],
  proxy: {
    baseUrl: "https://api.mycrm.com/v2",
    headers: { authorization: "Bearer ${accessToken}" },
  },
  documentationUrl: "https://developers.mycrm.com/api",
  categories: ["crm"],
} satisfies ProviderConfig;

API Key Provider 示例

凭证字段放在 method 内，而不是 Provider 根级。method 级模板允许不同认证方式使用不同注入规则，同时共享 Provider base URL。

export const myApi = {
  slug: "my-api",
  displayName: "My API",
  authMethods: [
    {
      id: "my-api.api_key",
      displayName: "API key",
      kind: "api_key",
      status: "available",
      credentials: {
        apiKey: {
          type: "string",
          title: "API key",
          description: "Key from account settings",
          secret: true,
        },
      },
      proxy: { headers: { authorization: "Bearer ${apiKey}" } },
    },
  ],
  proxy: {
    baseUrl: "https://api.example.com/v1",
    verification: { method: "GET", endpoints: ["/me"] },
  },
} satisfies ProviderConfig;

使用已部署目录

Provider Catalog 应作为受版本控制的目录数据维护；服务启动时会校验并幂等 seed 认证 Provider。Toolkit 作为 Registry 工件独立维护和发布。不要为了表达认证而创建 Toolkit，也不要假设一个 Provider 会自动拥有可执行工具。

Agent 或集成的正常顺序是：

发现 Toolkit 及其支持的认证方式。
为选中的方式创建或选择 Auth Config。
在用户和项目范围内创建 Connection。
通过该 Connection 调用工具。

准确的已部署 discovery 和调用路由请查看 API 参考；凭证生命周期请查看已连接账户。