概览
连接器可以让 Gety 索引常规本地文件索引之外的内容，例如网页服务、内部工具或其他工作流中的数据。
连接器适合做什么
Gety 可以搜索你电脑上的文件。连接器则会额外接入一个可搜索的数据来源：它从来源拉取记录，把记录转换成可搜索文档，再按计划交给 Gety 索引。
适合使用连接器的场景包括：
- 把外部工具和本地文件放在一起搜索
- 让数据保留在原系统中，不需要手动复制成文件
- 为连接到 Gety 的 AI 工具提供更多本地搜索上下文
只安装可信连接器
连接器是在你电脑上本地运行的代码。它会读取你为它填写的配置，并且可以使用权限允许的网络、文件和程序。
大多数连接器在沙箱中运行：它们只能做作者在连接器 manifest 中声明的事，安装前你会先审查这些权限。没有声明权限的连接器以完全权限运行，可以访问你能访问的一切。详见审查权限。
只安装来自可信来源的连接器。安装前，先确认它会访问哪个来源、请求了哪些权限。连接器可以把读取到的数据发送到权限允许的任何主机。Gety 本身不会把连接器的数据上传到 Gety 服务器。
安装连接器
精选连接器、从 GitHub 或 npm 安装，以及权限审查，需要 Gety 0.7.0 或更新版本。
打开 Gety → 设置 → 连接器，在 安装连接器 下选择安装方式：
| 方式 | 适合安装 |
|---|---|
| 精选连接器 | 从列表中挑选 Gety 官方或社区的连接器 |
| 从远程安装 | 发布在 GitHub Release 或 npm 上的连接器 |
| 从本地文件夹安装 | 你电脑上的连接器文件夹，例如你正在开发的连接器 |
无论选择哪种方式，Gety 都会先进行同样的权限审查，然后才安装。允许权限后，填写连接器需要的配置项（例如 API key），再点击安装。之后 Gety 会在后台开始索引。
安装精选连接器
- 点击精选连接器。
- 选择官方标签页查看 Gety 维护的连接器，或选择社区标签页查看其他作者发布的连接器。
- 点击目标连接器旁的安装。
- 审查权限，填写配置，然后点击安装。
每个条目都会显示连接器的版本和发布时间，Gety 从 npm 安装的正是这个版本。安装后，它和其他 npm 连接器一样，作者发布新版本后你可以更新它。详见更新连接器。
社区条目会显示作者的 GitHub 头像和名称，点击可以打开作者的 GitHub 主页。Gety 维护者会在每个版本上架前审核，但社区连接器仍然是作者的代码，也可能请求完全权限。安装前请检查它的权限。
没有你想要的连接器？点击社区标签页底部的创造并发布你的连接器，或参阅构建连接器。
Gety 维护以下官方连接器：
| 连接器 | npm 包 | 索引内容 |
|---|---|---|
| Linear | @gety-connectors/linear | 把云端 Linear Issue 转换为 Markdown 文档；开启评论索引后也会包含评论。 |
| Codex | @gety-connectors/codex | 把本地 Codex session JSONL 日志转换为 Markdown 文档。 |
| Google Chrome | @gety-connectors/chrome | 本地 Chrome 书签和浏览历史。 |
| Claude Code | @gety-connectors/claude-code | 把本地 Claude Code session JSONL 日志转换为 Markdown 文档；也可以选择包含 subagent session。 |
| Notion | @gety-connectors/notion | 把共享给 Notion 集成的页面转换为 Markdown 文档。 |
| 飞书 | @gety-connectors/lark | 通过本机已登录的 lark-cli，索引飞书云文档和聊天记录。 |
从 GitHub 或 npm 安装
- 点击从远程安装。
- 选择 GitHub 或 npm 标签页，输入连接器的地址。
- 点击继续。
- 审 查权限，填写配置，然后点击安装。
| 来源 | 支持的地址 | 默认安装 |
|---|---|---|
| GitHub | owner/repo、仓库链接（例如 https://github.com/owner/repo），或某个 Release 的链接（例如 https://github.com/owner/repo/releases/tag/v1.2.0） | 仓库的最新 Release |
| npm | name、@scope/name、name@版本号，或 npmjs.com 上的包页面链接（例如 https://www.npmjs.com/package/name） | 包的最新版本 |
要安装其他版本（例如预发布版本），在 GitHub 上输入那个 Release 的链接，在 npm 上输入 name@版本号。
GitHub 仓库或 npm 包必须是公开的，并且作者需要按 Gety 的发布约定发布。Gety 会把连接器下载到自己的文件夹，校验下载内容后从那里运行。
从本地文件夹安装
- 点击从本地文件夹安装。
- 选择包含连接器
manifest.json的文件夹。如果你下载的是 ZIP 文件，请先解压。 - 审查权限，填写配置，然后点击安装。
Gety 直接运行这个文件夹中的代码，所以请保留这个文件夹。重新构建连接器代码后，点击更多操作（⋯）→ 重启加载新代码。Gety 只在安装时读取 manifest.json， 修改 manifest 后需要删除连接器并重新安装。
审查权限
安装前，Gety 会显示审查 名称 的权限对话框。对话框会显示连接器的来源（GitHub 仓库和 Release、npm 包和版本，或本地文件夹），并按网络、读取文件、环境变量、运行程序分组列出连接器可以做的事。
- 对沙箱连接器，未列出的权限一律拒绝。
- 标有来自『配置项』配置项的权限，跟随你在该配置项中填写的值。之后修改这个配置项，访问范围也随之改变，不会再次审查。
- 颜色表示风险：只访问列出的主机或只读取列出的文件夹为绿色，高风险为黄色，完全权限为红色。
安装以下连接器前，Gety 会再次确认授予高风险权限？：
- 会运行程序的连接器。连接器运行的程序不受沙箱限制，可以访问你能访问的内容。
- 可以与任意主机通信的连接器，数据可以发送到任何地方。
- 可以读取主目录中所有文件的连接器。
- 没有声明权限的连接器。Gety 会显示此连接器不在沙箱中运行，可以访问你能访问的一切。
在任何一步点击取消，Gety 都不会安装，也不会保存你填写的任何配置。
安装后要查看连接器的权限，点击它所在行的权限盾牌按钮。高风险连接器的盾牌为黄色，完全权限的连接器为红色。没有声明权限的连接器（包括在 Gety 0.7.0 之前安 装的连接器）继续以完全权限运行。
了解沙箱连接器默认拥有的能力
每个沙箱连接器都有一些无需声明的能力，审查对话框不会列出。沙箱连接器始终可以：
- 读取自己的代码。
- 读写自己的数据文件夹（多次同步之间会保留），以及一个临时文件夹（每次同步结束后由 Gety 删除）。
- 读取环境变量
TMPDIR、TMP和TEMP，它们指向这个临时文件夹。 - 读取基本系统信息：主目录路径、处理器数量、内存、操作系统版本、运行时间、系统负载和磁盘空间。
- 使用自己的本地存储和缓存。
沙箱连接器始终不能：在这些文件夹之外写入文件，加载本地库，读取电脑名称、网络接口或用户账户，或者加载安装包之外的代码。
管理已安装的连接器
已安装的连接器列在已安装连接器下，显示版本和同步状态。每一行有以下操作：
| 操作 | 作用 |
|---|---|
| 权限 | 查看连接器拥有的权限。 |
| 配置 | 修改连接器的配置和同步计划。 |
| 更多操作（⋯） | 打开包含以下操作的菜单。 |
| 开关 | 启用或禁用连接器。禁用的连接器不会同步，Gety 会保留它的配置。 |
更多操作（⋯）菜单包含：
重启和完全重建索引只在连接器启用时出现。立即同步只在连接器已启用、正在运行并且没有在同步时出现。
如果 Gety 无法加载某个连接器，它所在的行会显示原因，并改为提供一个删除按钮。
配置连接器
带有必填配置项 的连接器，需要在安装完成前配置，例如 API key、服务器地址或文件夹路径。之后要修改配置，点击连接器所在行的配置，修改配置项后保存。Gety 会保存配置并重启连接器。
选择同步计划
每个连接器都会声明默认的同步计划。要修改它，点击配置，然后选择同步计划：
| 计划 | 行为 |
|---|---|
| 手动 | 仅在你点击更多操作（⋯）→ 立即同步时同步。 |
| 间隔（秒） | 每隔固定秒数同步一次，例如每 3600 秒。 |
| 每天 | 每天在你设置的**每天时间（HH:mm:ss）**同步一次，使用本地时间。 |
完全重建索引
如果同步后连接器的结果仍然错误或不完整，点击更多操作（⋯）→ 完全重建索引。Gety 会删除该连接器的全部文 档，然后从头重新同步。期间搜索结果可能不完整。
更新连接器
Gety 为从 npm 安装的连接器（包括精选连接器）提供版本管理。每次打开“连接器”设置页面，Gety 都会检查它们的更新；点击检查更新可以再次检查。有可用更新时，更多操作（⋯）上会出现一个圆点，鼠标悬停会显示有新版本 版本号。Gety 不会自动安装更新。
更新连接器或切换到其他版本：
- 点击更多操作（⋯）→ 版本管理。
- 选择一个版本。Gety 会显示它的更新说明，以及切换会带来的变化。
- 点击切换到此版本。
版本列表使用以下标签：
| 标签 | 含义 |
|---|---|
| 当前 | 连接器正在运行的版本。 |
| 最新 | 作者在 npm 上标记为最新的版本。 |
| 预发布 | 预览版本，例如 1.3.0-beta.1。 |
| 已弃用 | 作者已撤回这个版本，但你仍然可以切换到它。 |
| 需要 Gety 版本号 | 这个版本需要更新的 Gety，请先升级 Gety。 |
| 不可用 | 这个版本不符合连接器的发布约定，无法安装。 |
Gety 提供的更新，是比当前版本新、不是预发布、没有弃用、并且与你的 Gety 兼容的版本中最高的一个。要安装预发布版本或旧版本，在列表中选择它即可。
切换版本时：
- 你的配置会保留。如果新版本新增了必填配置项、删除了某个配置项，或要把某个配置项重置为默认值，Gety 会在切换前列出来，并请你填写需要填写的配置项。
- 如果新版本需要更多权限，切换前你需要审查新增的权限。
- 已同步的文档会保留。降级时，或者新版本的同步格式或索引字段发生变化时，Gety 会删除该连接器的全部文档并从头同步，并在切换前告诉你。
- 连接器自己的数据文件夹会保留。
- 如果下载或校验新版本失败，连接器会保持当前版本。如果 Gety 显示已切换到 版本号，但启动失败，说明新版本已经安装；点击更多操作（⋯）→ 重启重新启动它。
从 GitHub 或本地文件夹安装的连接器没有版本管理。要把 GitHub 连接器换成另一个 Release，先删除它，再安装那个 Release。本地文件夹的连接器，更新文件夹中的代码后点击更多操作（⋯）→ 重启即可。
排查问题
连接器无法安装
安装对话框会显示原因。常见原因：
- 这个连接器已经安装，可以在「已安装连接器」中管理它。 Gety 按 manifest 中的 ID 识别连接器，与来源无关。要从另一个来源安装同一个连接器，例如改为从精选连接器安装之前从下载的文件夹安装的连接器，请先删除已安装的那个。
- 这个版本需要 Gety 版本号 或更新版本。 升级 Gety，或安装这个连接器的旧版本。
- Release 或 npm 包不符合连接器的发布约定。请把提示信息反馈给连接器作者。
- 从本地文件夹安装时，确认你选择的是连接器根目录，也就是包含
manifest.json的文件夹。
连接器没有结果
- 确认连接器已启用。
- 检查必填配置是否正确，尤其是 API key。
- 点击更多操作（⋯）→ 立即同步，等待同步结束后再搜索。
- 如果状态显示权限错误，参阅同步因权限错误失败。
结果不是最新的
点击更多操作（⋯）→ 立即同步运行一次同步。如果连接器仍然像是卡住了，点击更多操作（⋯）→ 重启。如果同步后结果仍然错误，完全重建索引。
同步因权限错误失败
连接器尝试做了权限不允许的事。状态会说明具体是什么，例如 permission denied: net access to "api.example.com:443" is not granted by the connector's manifest。
如果这项权限来自某个配置项（例如服务器地址），请检查你填写的值。否则，请把这条信息反馈给连接器作者：作者需要声明这项权限并发布新版本。
搜索结果打不开
为安全起见，Gety 不会打开连接器文档中的以下链接：
- 位于任何连接器目录（包括代码目录和数据目录）中的文件。Gety 会提示为安全起见，Gety 不打开连接器目录中的文件。
- 不存在的文件。
- 指向其他电脑、而不是本地路径的
file:链接。 - 在 Windows 上，不在本地磁盘上的文件。
要找到连接器目录中的文件，请改用打开文件所在目录。
连接器索引不符合预期
如果连接器索引的内容和你的预期不一致，请向连接器作者提交 Issue。说明连接器版本、可以公开的配置、你的预期，以及一个不符合预期的结果示例。
构建自己的连接器
Gety 还没有覆盖你需要的数据来源？参阅构建连接器。