OpenCore文档与知识连接器

GitHub

以 Markdown 格式查看

索引内容

GitHub 连接器会索引一个 GitHub 用户或组织名下仓库中的内容。可以填写逗号分隔的仓库列表，也可以选择全部按 owner 列举。Owner 为组织时，全部可以列举 token 可见的组织仓库。Owner 为用户时，它调用 /users/{user}/repos，只列举公开仓库；用户 owner 下的私有仓库必须明确填写 repository name。

GitHub 数据索引行为
Pull request每个 PR 会成为一个文档，可搜索文本是 PR 正文。文档标识由 PR 编号与标题组成；状态、标签、作者、经办人、合并状态，以及若干时间戳和计数会成为元数据。Review、评论、diff 与 commit 内容不会加入文本。
Issue每个非 PR issue 会成为一个文档，可搜索文本是 issue 正文。标题与编号用于标识文档，状态、标签、作者、经办人与时间戳会成为元数据。Issue 评论不会被索引。
仓库文档选择包含文档时，OpenCore 只读取仓库默认分支。它接受 .md、.mdx、.markdown、.rst、.txt，以及 README、LICENSE、CHANGELOG、CODEOWNERS 等常见无扩展名文件。源码与数据/配置类扩展名会被有意排除。
文件限制超过 1,000,000 字节的文件，以及位于内置依赖/构建路径分段下的文件会被跳过。GitHub 截断超大型递归树时，OpenCore 会索引已返回的路径，并报告树不完整失败。
分支没有分支字段。文档文件只来自当前默认分支；PR 与 issue 属于整个仓库，不按分支筛选。

必须至少选择 pull request、issue 或文档中的一项。连接器不会为仓库概览单独创建可搜索文档。

前置条件

  • 创建专用 GitHub access token，使其能读取每个选定仓库及已启用的 PR、issue 与 contents API。
  • 当前连接器凭据只有一个 access-token 字段，不包含 GitHub App ID、installation ID、client secret 或 private-key 字段；不要把 App private key 粘贴到 token 字段。
  • 对于受 SAML SSO 保护的组织仓库，应为该组织授权 token。
  • 记录准确的仓库 owner；使用明确范围时，还应记录每个不带 owner 前缀的仓库名。如果 owner 是用户，请记录每个所需私有仓库并明确填写，因为全部不会列举这些仓库。
  • 对于 GitHub Enterprise，由部署运维人员把部署级 GITHUB_CONNECTOR_BASE_URL 设置为实例 API base URL。未设置时，客户端使用 GitHub.com。管理表单不能为单个连接器设置主机。
  • 允许 OpenCore worker 访问所选 GitHub API 主机，并允许用户浏览器访问对应 Web 主机上的结果链接。
  • 如果使用自动同步权限，token 还必须能够读取仓库可见性、collaborator、outside collaborator、team、组织成员，以及把 GitHub 身份匹配到 OpenCore 用户所需的邮箱值。

凭据

方式OpenCore 凭据值认证行为
GitHub access tokengithub_access_token: <GITHUB_ACCESS_TOKEN>OpenCore 会把 token 传给 GitHub API 客户端。验证、内容读取，以及启用自动同步时的权限读取会使用同一个 token。

GitHub.com 与 GitHub Enterprise 由部署配置选择，不由凭据值选择。当前连接器 schema 没有独立的 GitHub App 凭据流程。不同 token 类型与服务器使用的 scope 名称可能不同；应验证实际目标仓库，并在适用时验证权限端点，而不能只依赖名义上的 scope 标签。

在 OpenCore 中配置

  1. 在管理后台打开连接器，选择 GitHub，并创建 access-token 凭据。
  2. 在仓库 Owner 中填写一个准确的 GitHub 用户或组织。
  3. 选择指定仓库并填写一个或多个逗号分隔的仓库名，或选择全部按 owner 列举。Owner 为组织时，它会请求 token 可见的组织仓库。Owner 为用户时，它使用 /users/{user}/repos 且只返回公开仓库；用户私有仓库应在指定仓库中填写。全部并非账号级全范围：配置的 owner 仍然是边界。
  4. 至少选择一种内容：pull request、issue 或文档。仅当默认分支文档文件策略符合预期内容时才选择文档。
  5. 选择文档访问方式。仅在自动同步权限可用且仓库级映射已完成测试时使用它。否则，受限仓库应使用 OpenCore 私有群组；仅当每个 OpenCore 账号都可以搜索全部选定内容时才使用公开。
  6. 设置刷新与清理选项，创建连接器并启动索引。

首次 checkpoint 调用会解析已配置仓库，保存其 ID 与首个仓库，然后在不产生内容的情况下返回。后续调用会逐个仓库推进 PR、issue 与文件分页。

增量运行时，PR 与 issue 按更新时间排序。OpenCore 会先把轮询起点向前移动三小时、终点向后移动一天，再进行筛选。对于文件，会把调整后的起点与仓库 pushed_at 比较；仓库足够新时会重新列举当前默认分支文档集。因此，向任何分支推送都可能触发默认分支文档的重新处理。

权限

Access token 决定 OpenCore 可以摄取什么。自动同步权限可用且已选择时，当前 Enterprise 实现会把一条仓库级访问记录应用到该仓库内的每个 PR、issue 与文件文档：

  • 公开仓库映射为 OpenCore 公开访问。
  • 私有仓库映射为仓库 collaborator、outside collaborator 与仓库 team 对应的群组。
  • Internal 仓库映射为组织成员群组。

这是仓库级同步，不是分支、issue 或 PR 级授权，也不会复现粒度更细的源规则。群组成员根据 GitHub 邮箱值构建；如果 collaborator、team 成员或组织成员没有可用邮箱，他们可能不会出现在同步后的 OpenCore 群组中。依赖自动同步前，应同时测试允许与拒绝用户。

未使用自动同步时，用户搜索时不会检查 GitHub 访问权限。私有使用分配给连接器的 OpenCore 群组；公开会让每个 OpenCore 账号都能搜索全部已索引文档。如果 OpenCore 访问模式比源端更宽，用户可能可以搜索自己无法在 GitHub 打开的 PR、issue 或文件。

验证

  1. 验证连接器并检查实际解析出的仓库列表。组织使用全部时，确认每个预期的 token 可见组织仓库都存在。用户使用全部时，应预期只返回公开仓库，并确认每个所需私有仓库均已明确配置。
  2. 持续执行 checkpoint 调用直到运行完成，然后针对每个已启用内容类型，搜索一个选定 PR 正文、一个 issue 正文，以及一个默认分支 README 或文档文件。
  3. 确认 PR 评论、review、diff、issue 评论、源码文件、超大文档，以及只存在于非默认分支的文档均不存在。
  4. 打开结果链接，确认它们指向预期 GitHub.com 或 GitHub Enterprise 主机；对于文件，还应确认链接使用当前默认分支。
  5. 对 PR 或 issue 做一次增量修改，确认它能在连接器三小时起点重叠范围内出现。推送一个选定文档，并确认默认分支文件已更新。
  6. 如果使用自动同步，请测试公开仓库，以及有代表性的私有或 Internal 仓库用户，包括源端邮箱不可用的成员。未使用自动同步时，应测试每个已分配 OpenCore 群组和一个群组外用户。

故障排除

症状检查项
验证返回 401替换无效或已过期的 GitHub access token。
验证返回 403授予 token 对仓库与所需 API 的访问权限。对于受 SAML 保护的组织，确认 token 已获该组织授权。
Owner 或仓库返回 404检查准确的 owner 与仓库名、token 可见性，以及部署级 GitHub Enterprise API base URL。
逗号分隔的仓库只有部分被索引连接器会记录无法访问的仓库名；只要至少一个已配置仓库有效，它就可能继续。逐一检查名称与 token 授权；不要把部分成功当成完整范围验证。
全部遗漏了仓库先确认 owner 类型。组织 owner 会列举 token 可见的组织仓库，应检查实际列表与 token 访问。用户 owner 使用 /users/{user}/repos，只返回公开仓库；请在指定仓库中明确添加所需用户私有仓库。
首次运行没有产生文档第一个 checkpoint 只缓存仓库 ID。继续运行，让 PR、issue 与文件阶段执行。
README 被索引但源码没有这是预期行为。包含文档使用文档扩展名/文件名 allowlist 与默认分支，并不是通用源码索引器。
超大型仓库缺少部分文档检查连接器失败中是否有 GitHub 递归树截断，并检查 1,000,000 字节限制、被排除的路径分段、不支持的扩展名或非文本内容。
最近变更的条目出现在名义轮询窗口外PR 与 issue 轮询使用三小时起点重叠和一天终点扩展。仓库文件处理使用 pushed_at，它可能因为向任意分支推送而变化。
自动同步拒绝了合法源端用户确认仓库可见性映射、team/collaborator 成员关系，以及 GitHub 是否返回与 OpenCore 账号匹配的可用邮箱。如果无法安全解析源端身份，请改用明确的 OpenCore 私有群组。
用户可以搜索自己无法在 GitHub 打开的内容自动同步已禁用/不可用，或连接器被设为公开/分配范围过宽。受支持时启用并测试自动同步，否则应使用更窄的 OpenCore 私有群组与仓库范围。

相关页面