跳到主要内容

连接器参考

本页定义连接器的约定：manifest 字段、配置 schema、SDK 生命周期、文档字段、state 和本地验证。入门教程见构建连接器。

Manifest​

manifest.json 用来向 Gety 声明连接器。Gety 会在安装连接器时读取 manifest，因此修改 manifest 后需要重新安装连接器。

字段必填说明
id是稳定的连接器 ID。必须匹配 ^[a-z0-9][a-z0-9_-]*$：以小写字母或数字开头，后面可使用小写字母、数字、_ 或 -。不能使用大写字母、点号，也不能以 _ 或 - 开头。
name是Gety 连接器列表和安装对话框中显示的名称。
version是连接器的 SemVer 版本。
min_gety_app_version是连接器要求的最低 Gety 应用版本，使用 SemVer。
entry是连接器根目录内构建入口的相对路径，通常是 dist/main.js。
capabilities是非空数组，声明 Gety 支持的集成能力。轮询型数据来源声明 ["data-source"]；这是当前唯一支持的值。未知值会被拒绝。
description否安装对话框中显示的简短描述。
author否作者对象，例如 { "name": "Gety" }。
icon否连接器根目录内 PNG 或 SVG 图标的相对路径。Gety 会在连接器列表和安装对话框中显示它。
schedule否更新策略。省略时，Gety 使用默认 interval 更新方式。见 Schedule。
config否配置表单 schema。见配置字段。
doc_link否声明文档如何打开。见 Doc link。
schema.extra_gety_indexed_fields否让额外的 metadata 字段可搜索。见索引字段。

entry 和 icon 必须位于连接器根目录内。manifest 中出现未知字段会被拒绝。

Schedule​

schedule 控制 Gety 如何轮询来源。

形式行为
{ "strategy": "manual" }Gety 不会自动轮询。用户仍可点击立即更新。
{ "strategy": "interval", "interval_seconds": 3600 }每隔 interval_seconds 秒轮询一次。低于 60 的值会按 60 处理。
{ "strategy": "daily", "time": "09:00" }每天在 time 指定的本地时间轮询一次。支持 HH:mm 和 HH:mm:ss。

配置字段​

config.fields 是有序数组。每个字段都会在 Gety 的安装和配置界面中渲染为一个输入项，并成为 this.config 上带类型的属性。

属性必填说明
id是字段键，会成为生成的 ManifestConfig 类型上的属性。
title是UI 中显示的标签。
type是输入类型。可选值为 text、password、number、checkbox、dropdown 或 directory。
description否显示在字段下方的说明文字。
placeholder否文本类输入框的占位文本。
required否是否必填，默认为 false。
default_value否字段为空时的预填值。值的类型必须与字段类型匹配。
optionsdropdown 必填有序数组，形如 { "value": "...", "label": "..." }。

字段类型：

类型适合用途
text单行文本，例如 URL 或用户名。
passwordAPI key 和 token。值会在 UI 中遮蔽。
number数值。
checkbox布尔开关。
dropdown从有序 options 中选择一个固定值。
directory通过选择器选中的本地文件夹路径。
处理 API key

API key 和 token 应使用 type: "password"。本地验证时，示例 runner 会把字段 ID 映射为环境变量：将字段路径转为大写，先尝试带 GETY_CONFIG_ 前缀的名称，再尝试不带前缀的名称：

  • api_key 会先读取 GETY_CONFIG_API_KEY，再读取 API_KEY。
  • auth.api_key 会先读取 GETY_CONFIG_AUTH_API_KEY，再读取 AUTH_API_KEY。

doc_link 为整个连接器统一声明文档如何打开。

{ "kind": "url", "field": "url" }
属性说明
kindurl 打开浏览器链接；file 打开本地文件路径。
field从哪个文档字段或 metadata 键读取链接值。

解析规则：

  • field 可以是核心文档字段（id、parent_id、title、content 或 doc_type），也可以是直接的 metadata 键。
  • "field": "url" 会读取 metadata.url。请使用直接键，不要写成 "metadata.url" 这样的点路径。
  • 值缺失、为空或不是字符串时，该文档没有链接。
  • url 链接会在浏览器中打开。Gety 不会抓取其内容。
  • file 链接必须是稳定的本地路径，不能是临时缓存文件。

打开、展示和复制操作由 doc_link 决定，而不是 content_format。content_format 只控制 Gety 如何渲染文本预览。

索引字段​

Gety 始终索引 title 和 content。schema.extra_gety_indexed_fields 可以让额外的 metadata 键参与搜索。每一项都需要同时提供 field 和 strategy：

{
  "schema": {
    "extra_gety_indexed_fields": [
      { "field": "status", "strategy": "fast_text" }
    ]
  }
}
策略适合用途
fast_text短值，需要精确、子串、模糊或拼音匹配，例如名称、标签、文件夹、状态。
full_text较长文本，需要 SQLite FTS5 关键词搜索、BM25 排名和分词。
semantic需要按语义匹配的文本。依赖 embedding 模型。

SDK 生命周期​

连接器是一个默认导出的类，继承 Connector<Config, 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 onLoad(): Promise<void> {
    // Optional. Runs once in a fresh runtime process before poll().
  }

  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(toDoc(item))),
        state: { cursor: page.next_cursor },
      };
      cursor = page.next_cursor;
    }
  }
}
成员说明
this.configGety 安装或配置表单注入的带类型配置，结构由 config.fields 决定。
this.lastStateGety 持久化的上次成功轮询进度。首次运行时为 undefined。
this.signalAbortSignal。用户禁用或重启连接器时会触发中止。请传给 fetch。
onLoad()可选，可为 async。每个全新的运行时进程中，在 poll() 前运行一次。
poll()必填的 async generator，产出 PollResult 批次。

生命周期要点：

  • 每次计划轮询都会启动一个新的连接器运行时进程。
  • 类字段不会跨轮询保留。需要持久化的数据应放入 state，或显式写入磁盘缓存。

WireDoc 字段​

用 upsert(doc) 创建或更新文档，用 del(id) 删除文档。

upsert({
  id: issue.id,
  title: issue.title,
  content: markdown,
  content_format: 'markdown',
  doc_type: 'linear:issue',
  doc_updated_at: issue.updatedAt,
  original_file_size: markdown.length,
  metadata: {
    url: issue.url,
    created_at: issue.createdAt,
    status: issue.status,
  },
});
字段必填说明
id是稳定的文档 ID，多次轮询之间保持不变。
title是文档标题。始终会被索引。
content否Gety 用来索引和预览的文本。
content_format否plaintext（默认）或 markdown。markdown 会在文本预览中启用 Markdown 渲染。它只控制渲染方式，不代表来源类型，也不决定文档如何打开。只有真正的 Markdown 内容才应使用 markdown。
doc_type否外部记录通常写成 <namespace>:<type>，例如 linear:issue。只有文档确实像文件、并且需要按文件扩展名展示时，才使用 file:<ext>。不要为了得到 Markdown 预览就把外部记录标成文件；应设置真实的记录类型，并用 content_format 控制渲染。
doc_updated_at否来源文档的更新时间，必须是带 Z 或偏移量的 RFC 3339 时间。不要使用索引时间。
parent_id否父文档 ID，用于层级关系。
hide_from_search否从搜索结果中隐藏文档，但保留它用于父级或关系数据。
original_file_size否字节大小，用于展示。
metadata否任意键值映射。metadata.url 是常用链接目标。metadata.created_at 如果存在，必须是 RFC 3339 字符串，否则轮询会失败。额外键可通过 schema.extra_gety_indexed_fields 参与搜索。

只有 id 和 title 必填；未设置的其他字段不会发送给 Gety。Gety 将文档内容限制在约 10 MB。请按分页或分块产出，不要产出巨大的单个文档或 metadata。

Poll 和 state​

poll() 产出 PollResult 批次。每个批次包含 updates 和可选的 state 检查点。

yield {
  updates: [
    upsert(docA),
    upsert(docB),
    del(staleId),
  ],
  state: { cursor: page.next_cursor },
};

规则：

  • 先产出更新，再提交检查点。 每批中的 state 应表示该批更新之后到达的进度。它会成为下次轮询的 lastState。
  • 不要提前推进 state。 不要为尚未产出的文档提交 state。如果轮询在某个批次之后失败，Gety 会从最后提交的 state 重试。
  • 只根据真实信号删除。 只有来源明确表明文档已消失或离开范围时，才调用 del(id)。
  • 在可重试边界产出。 远程 API 通常按分页或持久游标产出；本地枚举则按可安全重试的文件或分块产出。
  • 谨慎处理时间戳游标。 保留足够 state，避免漏掉时间戳相同的更新。
  • 分页或流式处理来源。 Gety 可以安全地把过大的输出拆分到多条消息中，但连接器仍应分页或流式处理来源数据，不要把所有数据都留在内存里。

验证​

安装前运行示例项目的验证任务：

deno task verify

verify 会运行 fix、check、test 和 build：

  • fix 运行格式化和 lint 修复。
  • check 生成配置类型并进行类型检查。
  • test 运行测试。
  • build 生成 Gety 加载的打包入口。

也可以单独运行各步骤：

deno task fix
deno task check
deno task test
deno task build

用本地 runner 演练真实生命周期：

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

Runner 会把增量 state 持久化到 dev/.runner/state.json。--reset-state 会忽略该文件，便于测试干净的首次轮询。每次运行都会在 dev/runs/<timestamp>/ 下写入快照：

dev/runs/<timestamp>/
  summary.json
  state.before.json
  state.after.json
  updates.json
  deletes.json
  docs/
    0001-<doc_type>__<doc_id>.md
    0001-<doc_type>__<doc_id>.json

content_format: "markdown" 时内容文件为 .md，其他情况下为 .txt。文档没有内容时不会生成内容文件。配套 .json 文件始终会生成。请检查 ID 是否稳定、内容是否符合预期、metadata.url 是否正确、时间戳是否符合 RFC 3339、删除操作是否正确，以及前后 state 是否符合预期。

编辑 src/index.ts 后，运行 deno task build，再在 Gety 中点击重启加载新的 dist/main.js。

最后于 更新