跳到主要内容

构建连接器

连接器可以索引 Gety 默认不覆盖的内容。本指南会带你从示例项目开始，把连接器安装到 Gety 中。完整字段和 API 说明见连接器参考。

了解当前能力范围​

连接器是一个 Deno 和 TypeScript 程序。它轮询某个来源，并产出文档供 Gety 索引。

它可以：

  • 从稳定、可访问的来源拉取数据，例如网页 API、本地枚举或内部服务
  • 索引带有稳定 ID、标题和 metadata 的文本内容
  • 用持久化 state 跟踪增量进度，并新增、更新或删除文档

它不能：

  • 在 Gety 中添加自己的 UI，manifest 声明的配置字段除外
  • 在用户打开结果时，按需抓取、提取或缓存远程文件
  • 为每个文档使用不同的动态链接规则；文档链接需要在 manifest 中统一声明

如果来源只提供文件，而这些文件还需要 Gety 之后再抓取和提取，请不要这样设计。应当把连接器已经拿到的文本写入 content，再把稳定的 URL 或文件路径放到 metadata 中。

例如，Notion 就适合作为连接器场景：使用 Notion API 作为稳定来源，借助 souvikinator/notion-to-md 这类库把 Notion blocks 转换为 Markdown，再把 Markdown 作为索引内容添加到 Gety。

媒体播放器通常不适合作为连接器场景。它主要是交互式 UI，而不是稳定的文本来源。没有可靠 API、稳定本地文件或持久 ID 的来源，也不适合用连接器做增量同步。

前置条件​

开始前，请先安装：

  • Git，用于克隆示例连接器。
  • Deno，用于构建、测试和运行连接器。

使用 AI Agent 创建 Gety 连接器​

如果你的 AI 编程工具支持 Skills，优先使用 Gety 的连接器 skill。它会把连接器约定、示例项目流程和验证步骤交给 Agent。

npx skills add gety-ai/gety-skills --skills create-gety-connector

然后告诉 Agent 你想索引什么：

请使用 create-gety-connector skill，为 [数据来源] 创建一个 Gety 连接器。开始写代码前，如果缺少必要信息，请先向我确认。

如果你的 AI 编程工具不支持 Skills，可以把下面这段复制到聊天窗口：

为 [数据来源] 创建一个 Gety 连接器。请使用 https://docs.gety.ai/build-a-connector.md 作为实现流程，并使用 https://docs.gety.ai/connector-reference.md 作为完整的连接器约定和字段参考。开始写代码前，如果缺少必要信息，请先向我确认。

不要把 API key 等密钥粘贴到聊天中。密钥应放在连接器配置字段或本地 .env 文件中。

如果你要手动构建，请继续阅读下面的步骤。

从示例开始​

克隆示例连接器。不要从零手写项目骨架；示例已经包含构建脚本、生成的配置类型、本地 runner 和验证任务。

git clone https://github.com/gety-ai/gety-sample-connector my-connector
cd my-connector

查看项目结构​

manifest.json          # 连接器元数据和配置 schema
src/index.ts           # 连接器实现
src/index.test.ts      # 单元测试
src/gen/manifest.d.ts  # 生成的配置类型；不要编辑
dist/main.js           # Gety 加载的构建入口
deno.json              # build、check、test、verify、runner 等任务
dev/runner.ts          # 本地生命周期 runner
scripts/build.ts       # esbuild 打包脚本

Gety 实际加载的是 dist/main.js。修改 src/index.ts 后，需要运行 deno task build；只改源码不会更新已构建的连接器。

先规划文档契约​

写代码前，先确定来源如何映射为 Gety 文档。请提前明确这些点：

  • 来源及其认证方式。
  • 在多次轮询之间保持稳定的文档 ID。
  • 每条记录如何映射到 title、content 和 metadata。
  • 如何检测并删除已删除或已归档的记录。
  • 用户选中搜索结果时打开的链接。

编写最小 manifest​

manifest.json 告诉 Gety 如何安装和运行连接器：

{
  "id": "my_connector",
  "name": "My Connector",
  "version": "0.1.0",
  "min_gety_app_version": "0.5.1",
  "capabilities": ["data-source"],
  "entry": "dist/main.js",
  "description": "Indexes documents from My Connector.",
  "schedule": { "strategy": "interval", "interval_seconds": 3600 },
  "doc_link": { "kind": "url", "field": "url" },
  "config": {
    "fields": [
      {
        "id": "api_key",
        "title": "API Key",
        "type": "password",
        "required": true,
        "description": "Create this token in the service settings."
      }
    ]
  }
}

所有 manifest 字段见连接器参考。

实现 src/index.ts​

连接器是一个继承 Connector<Config, State> 的类。你需要把 poll() 实现为 async generator，产出成批的文档更新和 state 检查点。

import { Connector, type PollResult, del, upsert } from '@gety-ai/connector-sdk';
import type { ManifestConfig } from './gen/manifest.d.ts';

type State = {
  cursor?: string;
};

export default class MyConnector extends Connector<ManifestConfig, State> {
  async *poll(): AsyncGenerator<PollResult, void, unknown> {
    let cursor = this.lastState?.cursor;

    for await (const page of fetchPages(this.config.api_key, cursor, this.signal)) {
      yield {
        updates: [
          ...page.items.map((item) =>
            upsert({
              id: item.id,
              title: item.title,
              content: item.body,
              content_format: 'markdown',
              doc_type: 'my:item',
              doc_updated_at: item.updatedAt,
              metadata: { url: item.url },
            }),
          ),
          ...page.removed.map((id) => del(id)),
        ],
        state: { cursor: page.next_cursor },
      };
      cursor = page.next_cursor;
    }
  }
}

要点：

  • upsert(doc) 新增或更新文档。只有 id 和 title 必填；id 必须在多次轮询之间保持稳定。
  • del(id) 在来源明确表明文档已消失时删除文档。
  • this.config 包含用户在 manifest 配置字段中填写的值。
  • this.lastState 包含上次成功轮询进度提交的 state。
  • this.signal 会在用户禁用或重启连接器时触发中止。能传给 fetch 时，应传进去。

管理 state 和批次​

每批更新都应带上一个 state 检查点，并且这个 state 应位于该批更新之后。Gety 会把它持久化为下次轮询的 lastState，这样轮询失败时可以从最后提交的位置继续。

不要在产出对应文档之前推进 state。应按来源可安全重试的边界产出，例如 API 分页或持久游标。

避免这些写法​

这些写法可能会造成内存压力或链接失效：

  • 一次性把所有远程数据读入内存。应尽量改为分页或流式处理来源。
  • 在 doc_link 中使用临时 URL。链接在轮询结束后必须保持稳定。
  • 把大块数据放进 metadata。metadata 应保持精简，正文请通过 content 索引。
  • 在构造函数中读取 this.config。配置会在 Gety 注入之后，于 onLoad()、poll() 等生命周期方法中可用。

本地验证​

安装连接器前，先运行示例项目的验证任务：

deno task verify

verify 会运行格式化、lint 修复、配置类型生成、类型检查、测试和构建。然后用本地 runner 演练连接器生命周期：

cp .env.example .env
deno task runner -- --reset-state

Runner 会调用 onLoad() 和 poll()，并把每次运行的输出写入 dev/runs/<timestamp>/，包括文档、更新、删除和 state 快照。重点检查 ID 是否稳定、内容是否符合预期、metadata 是否正确、时间戳是否符合 RFC 3339。--reset-state 会忽略已保存的 runner state，方便你测试一次干净的首次轮询。

如果 .env 需要 API key 等密钥，请自己编辑文件。不要把密钥粘贴到和 Agent 的聊天中。

安装到 Gety​

  1. 运行 deno task build，刷新 dist/main.js。
  2. 打开 Gety → 设置 → 连接器，安装你的连接器文件夹。
  3. 在安装对话框中填写必填配置项。
  4. 确认安装。
  5. 让 Gety 按连接器的更新策略运行。手动策略需要点击立即更新。

之后修改代码时，需要再次运行 deno task build，再在 Gety 中点击重启加载新的构建产物。

下一步​

完整约定，包括 manifest 字段、配置字段类型、SDK 生命周期和 WireDoc 字段，见连接器参考。

最后于 更新