Open Connector

连接器

Runtime Catalog 中 Toolkit、执行定义与已连接账户的关系。

Open Connector 只有一个可连接的目录身份：Toolkit。Toolkit 自己拥有认证方式、端点配置、展示元数据和 Agent 可调用的工具；运行时不再有独立的 Provider 或 Auth Provider 层。

Runtime Catalog 模型

目录对象负责什么运行时表示
Toolkit Definition名称、发现元数据、authMethods、可选连接字段和可信 API 端点。runtime_toolkit_catalog 中的一行。
Tool Definition面向 Agent 的输入/输出 Schema、scope、tag 与生命周期。tool_catalog 中的一行。
ExecutionDefinition声明式 HTTP/GraphQL 请求映射，或命名 custom executor。Tool 行的 JSONB；仅在执行时加载。
Trigger Type事件 Schema 和懒加载 transport key。trigger_type_catalog 中的一行。
Connection用户在某个项目范围内、针对所选 Toolkit 认证方式的加密凭证。独立于目录保存。

生成后的 catalog artifact 位于 packages/tool-registry/artifacts/<toolkit>/catalog.gen.json，根 release manifest 记录经过校验的完整集合。Server 只读取 PostgreSQL Runtime Catalog，不会回退到静态 tool 模块。

认证方式

每个 Toolkit 包含 authMethods 数组。每项都有命名空间 id，例如 github.oauth2，并标记为 available 或带原因的 unavailable。

Kind用户提供什么Open Connector 做什么
oauth2浏览器授权；配置后也可使用 client credentials。构建授权 URL、交换和刷新 Token，再加密保存。
api_key长期 API Key 或 Token。加密保存，并按所选方式的请求模板注入。
basic用户名/密码或等价 key/secret。加密保存两个字段，并按配置注入请求。

端点默认值不包含凭证；凭证注入属于所选认证方式，因此 ExecutionDefinition 可以无 secret 地携带和发布。

Artifact 示例

以下精简 artifact 定义一个 Toolkit 和一个声明式 HTTP Tool；生成的 OpenAPI 和 GraphQL Tool 使用同一结构。

{
  "version": "v1",
  "toolkit": {
    "slug": "my-crm",
    "name": "My CRM",
    "authMethods": [{ "id": "my-crm.oauth2", "kind": "oauth2", "status": "available" }],
    "endpoints": {
      "api": { "baseUrl": "https://api.mycrm.com/v2", "allowedBaseUrls": [], "defaultHeaders": {} }
    }
  },
  "tools": [{
    "definition": { "slug": "MY_CRM_CONTACTS_LIST", "toolkit_slug": "my-crm", "name": "List contacts" },
    "executionDefinition": { "version": "v1", "kind": "http", "endpointKey": "api", "method": "GET", "path": "/contacts" }
  }],
  "triggerTypes": []
}

发布并使用已部署目录

生成 artifact 后，显式发布 release 到 Server 使用的数据库：

pnpm tools:generate-official
pnpm tools:build-catalog-release
DATABASE_URL='postgres://…' pnpm tools:publish-catalog

发布会校验 artifact digest，并原子地投影到 PostgreSQL。它与 Server 启动和数据库迁移分离，因此运行中的服务不会悄悄改变可执行目录。

Agent 或集成的一般顺序是：

  1. 发现 Toolkit 及其支持的认证方式。
  2. 为该 Toolkit 和认证方式创建或选择 Auth Config。
  3. 为用户和项目范围创建 Connection。
  4. 通过该 Connection 执行 Tool。

具体 discovery 与执行路由见 API reference；凭证生命周期见 Connected accounts。

On this page

Runtime Catalog 模型认证方式Artifact 示例发布并使用已部署目录