13 KiB
GitHub Skill 采集 Go 服务:产品需求
已实现增量:官方深度探索扩展原有元数据发现范围,新增 README 与有界作者扩展,采用统一技能同步后台中的采集配置抽屉和独立探索开关。产品决定见需求,技术合同见增量设计,当前验收范围见验收追踪。下文仅元数据搜索及只按自定义规则启停的原有入口边界不适用于官方探索;自定义规则继续兼容。
Issue #516 的 Go 服务产品视角。跨服务的正式行为与验收以本变更的 三份行为规格 为准,技术取舍见 design.md;本文只描述服务要交付的运行能力、操作体验与衡量方式,不维护第二套 API 或任务清单。
1. 产品定位
Go 服务是随 SkillHub 私有化部署的公开 GitHub 采集执行端。它与 SkillHub 位于同一代码仓库,根目录有独立的 Go 服务目录和独立镜像,首期默认单副本。平台管理员仍在 SkillHub 后台配置来源、查看运行反馈;Java 保存配置、任务、凭证、来源账本、版本与审核,Go 主动领取任务,完成 GitHub 访问、固定 revision、Skill 包采集和结果回报。Go 服务不提供面向用户的独立后台,也不拥有 Skill 发布权限。
服务的价值是把搜索、仓库树枚举、文件下载和限流等待从 SkillHub 主服务移出,同时让平台能持续发现社区 Skill,而不要求管理员逐仓库逐文件操作。
2. 使用者与要完成的事
| 使用者 | 在 SkillHub 中做什么 | Go 服务要提供的结果 |
|---|---|---|
| 平台管理员 | 配置搜索规则、精选仓库、精选 GitHub 用户或组织;查看运行与额度 | 按规则持续发现公开仓库,报告命中、有效 Skill、延后、错误和下次可运行时间 |
| TEAM 管理员 | 在本 TEAM namespace 登记公开仓库、暂停或重扫来源 | 仅处理本 TEAM 明确登记的仓库,逐 Skill 回报状态,保留 TEAM 归属 |
| 同步审核者 | 在独立队列审查新 Skill 和更新 | 获得固定 commit、完整包、逐文件变化、来源与许可证证据;Go 不决定审核结果 |
| 私有化部署运维者 | 部署、升级、排查采集问题 | 一个可独立启停的 Go 容器;健康与任务进度可观察,重启后继续,不要求 GitHub Actions 或新的队列组件 |
3. 首期能力
3.1 多类来源入口,一条仓库采集流水线
官方深度探索、自定义搜索规则、精选仓库、精选用户或组织均只产生公开 GitHub 仓库坐标。TEAM 首期只登记具体公开仓库。发现入口的结果按 GitHub repository ID 去重;自动搜索或精选用户发现的仓库在确认存在有效 Skill 候选后才成为正式来源。管理员明确登记的仓库可先呈现“待首次扫描”。同一仓库在 @github 与 TEAM 下分别形成来源绑定,不共享审核决定。
官方深度探索从仓库名称、描述、topic、README 线索及有效仓库作者的一层扩展获取候选,再检查仓库树中的 SKILL.md;自定义规则继续保持元数据条件。全站代码搜索先进行独立试验,不作为首期默认渠道。界面说明索引和搜索范围仍存在覆盖边界。
后台自定义规则使用关键词/topic 两类结构化条件,分别标记核心或扩展优先级。Go 将每项编译为独立的仓库搜索查询,按仓库 ID 去重并记录命中条件;规则版本与增量/全量搜索窗口在领取时固定,分页续跑不能因管理员改规则而换查询。核心条件先使用预算,扩展条件在剩余额度内运行;查询结果截断或标记不完整时应分片或明确延后,不能把遗漏当作完成。
Go 服务使用一个部署,内部区分“发现”和“仓库同步”工作。Java 按后台配置与目标周期生成任务;Go 轮询领取。仓库任务在固定 commit 上一次枚举该仓库所有可见 SKILL.md,逐 Skill 包采集和回报,不要求 Java 再按 Skill 拆任务。
3.2 可恢复的逐包采集
每个 SKILL.md 所在目录是一个 Skill 包;嵌套 Skill 自成包,不并入父包。Go 在固定 commit 上只取得需要的文件到受限本地临时目录,按当前有效发布政策逐包检查文件数、单文件和包总大小,拒绝符号链接和 Git submodule;随后逐包打包上传到隔离临时对象存储,只把 uploadId、路径、commit、大小和摘要回报 Java。Java 用自己的存储适配器读取对象,不依赖 Go 提供的预签名下载链接。一个包失败时,其他包继续;下次从固定 commit 重试失败路径。Java 独立复核、计算正式内容指纹、创建待审版本,并在消费后清理临时对象。
树枚举被截断时,Go 按子树继续;部分子树仍无法读取时,已完整发现的 Skill 继续采集,未完成范围明确标记并续跑。扫描不完整、仓库临时不可达或 Go 重启都不能被解释为 Skill 已被上游删除。
大仓库先通过固定 commit 的树元数据定位 SKILL.md、预估各候选包文件数与大小,再针对合格目录下载文件;blob:none 仍会占用 Git 树元数据空间,因此每仓库目录和总临时磁盘受预算及部署工作区容量约束。Go 在每批开始前预留 Git 元数据、选中包文件、归档和安全余量,并在下载、归档及清理后检查实际占用。逐包上传并持久回报后清理本地文件;达到预算时保存路径游标、释放目录并从同一 commit 分批继续。若当前容量连固定 commit 元数据或一个合规包都处理不了,后台显示容量阻塞并等待配置调整,避免同一条件下立即重试;不能无限制整仓下载,也不能当作 Skill 已删除。
3.3 自动调度与反馈
广泛搜索默认每 7 天做一次去除增量时间窗口的全量搜索,以补找遗漏的仓库线索;仍遵守额度、处理预算与可恢复检查点,不代表整仓下载。
后台配置的是三类目标周期:已登记仓库更新默认约每 24 小时、精选用户或组织发现默认约每 24 小时、广泛搜索默认约每 72 小时;后台可按类别调整。预置搜索规则初始停用;管理员可在同一后台页面查看、修改和启用,明确添加的精选仓库可直接安排同步。官方探索独立启停,自定义规则各自启停;另外提供仅约束平台 @github 的安全暂停/恢复,不控制 TEAM、不重写独立入口开关,合同见 统一管理;Java 只为已启用入口创建任务,Go 领取固定策略或规则快照执行。运行时结合 GitHub 额度、执行容量、审核积压与 namespace 公平性控制当轮工作量;已有来源更新和明确精选仓库优先,同时为官方探索的历史补搜和扩展查询保留有界的调度机会,避免永久饥饿。超出预算的候选留待续跑,不能静默丢弃。手动重扫会合并重复请求,也不能越过限流或审核反压。这些周期是目标时间,不保证在 GitHub 限流或审核积压时准点执行。
“积压”按 namespace、repository ID、Skill 路径统计当前最新且未解决的同步项,覆盖已接收、校验/扫描中、待审核和待管理员处理冲突;已批准、拒绝或被取代的历史项不计。全平台达到高水位时停止所有新包采集准入;只有某个 namespace 达到高水位时只暂停该范围。Go 在下载每个包前向 Java 申请准入,已开始的包可结算,下一个包不得继续。已启用的仓库搜索与精选用户或组织枚举仍可在额度及候选预算内继续,但只保存去重的仓库线索,不读取新候选仓库树或形成待审项;候选满时保存游标并延后。已登记仓库仍可低成本查看最新 commit,并在后台标记“发现更新、待采集”。积压回落到低水位后重新核对候选仓库与已登记来源的当前 revision,采集最新内容,不补齐每个中间 commit。
首期不使用历史审核结果自动调整各搜索规则份额。服务记录规则命中、有效 Skill、实际额度消耗和延后原因,供管理员判断规则效果及后续优化。
Go 服务停机或被关闭时,人工上传、市场浏览和既有审核继续可用。Java 合并同一来源的待执行任务,后台按兼容执行能力汇总实例联系状态,显示等待采集服务及最近联系时间;不能由单实例失联推断全部服务停机;恢复后按正常限流和审核反压续跑,不把未执行的轮次记为成功。
系统级 GitHub 凭证失效时,后台标记并提示,不再将其用于任务;可使用其他健康凭证,已配置凭证池仍无可用凭证时等待修复,不自动退回匿名;未配置任何凭证时可使用匿名额度。凭证失效与 GitHub 限流分别展示,限流时遵守 GitHub 返回的重试时间,不靠切换凭证掩盖限流。
4. Go 与 SkillHub 的产品边界
| 事项 | Go 服务 | SkillHub Java |
|---|---|---|
| 来源/规则/凭证配置 | 领取当次所需的有效配置 | 保存、授权、加密、展示配置 |
| 调度与任务状态 | 主动领取、续租、回报和停止 | 创建任务、租约、检查点、重试与公平调度 |
| GitHub 访问 | 搜索、公开状态核对、固定 commit、树与包采集 | 核对结果与来源身份,不直接承担高负载采集 |
| 内容与对象 | 每个 Skill 上传一个临时包,回报完整性信息 | 签发短时上传票据,复核并写入正式版本存储 |
| Skill 业务 | 回报候选路径、采集状态与错误 | 忽略规则最终判断、冲突、内容哈希、扫描、审核和发布 |
| 管理反馈 | 回报进度、额度、截断、失败和可重试时间 | 在平台/TEAM 后台与独立审核队列呈现、审计 |
Go 的输入与输出是任务和采集事实,不是“已经审核的 Skill”。Java 可以拒绝任何 Go 回报的包;Go 的成功只表示采集完成。
服务间只开放版本化 HTTP/JSON 内部任务合同,Go 使用独立服务身份调用 Java;GitHub Token 仅用于公开 GitHub 读取,不作为服务身份。GitHub 搜索与树枚举走 REST,包文件通过受限 Git 局部获取,固定 revision 不可取得时不混用新内容。
Go 上传并回报一个包后,Java 先持久记录摄入结果并确认接收,再由可恢复后台任务独立完成包校验、扫描与待审版本创建。因此后台需区分“已采集并交付”“处理中”“待同步审核”“处理失败”;不能把 Go 任务完成显示为已发布。Go 到 GitHub 的访问允许部署者统一配置出站 HTTP 代理,不提供逐来源代理设置。
5. 后台应看得到什么
Go 没有独立 UI;SkillHub 管理后台需要把 Go 的运行事实展示为以下四个问题:
- 目前在做什么:任务类型、来源、固定 commit、开始时间、已处理/延后 Skill 数、当前阶段。
- 为什么没有继续:GitHub 限流与 reset、审核积压、超出当轮预算、树不完整、包超限、来源不可达,均有明确原因和下次可运行时间。
- 能做什么:按权限暂停/恢复来源或单个 Skill 路径、手动重扫、调整搜索条件与忽略路径;不可用操作说明限制原因。
- 采集后去了哪里:来源详情逐 Skill 显示未变化、待扫描、待同步审核、已发布、失败或冲突,并链接到对应审核记录。
后台分平台管理视图和 TEAM 自身视图;TEAM 无法读取平台 Token 或其他 TEAM 的运行详情。同步审核与普通提交审核分开呈现。
6. 首期成功标准
- 配置一个精选公开仓库后,不依赖 CLI 或 GitHub Actions,Go 能通过 Java 任务接口发现其中多个 Skill,分别回报、上传和触发 Java 后续审核。
- 上游未变化不产生冗余版本;上游变化不会在审核通过前替换已发布版本;一个包失败不阻断兄弟包。
- GitHub 限流、部分树失败、Go 重启、重复回报和凭证缺失均有可观察状态与恢复路径;已发布 Skill 不因采集失败而消失。
- 管理员能从后台解释每轮发现了什么、为何延后、下一次何时可运行、哪些包进入同步审核;Token 和 Skill 正文不出现在日志或任务历史。
- 在本地文件存储及 S3/MinIO 模式下,Go 都无需正式对象存储管理凭证即可上传临时包;私有化部署只增加一个 Go 服务容器。
- 先用少量公开仓库验证单 Skill、多 Skill、嵌套与较大仓库,再用受控样本逐级验证约 1000 个已登记仓库、10000 个 Skill 路径的容量目标;这是验收基线,不是产品硬上限,也不要求对 GitHub 公网做无控制压测。
- 首次部署或升级后,预置搜索规则未启用时不产生广泛搜索任务;管理员在后台启用规则后生效,明确添加精选仓库无需等待规则启用。
- 审核积压达到高水位时,后续包无法取得采集准入;已登记仓库只检查并记录最新 commit,已启用发现任务仅记录有预算的仓库线索。积压回落后重新固定当前 revision 处理,且另一未触发高水位的 TEAM 不被误暂停。
7. 后续候选
TEAM 自有公开 API 凭证与团队自动搜索、Gitee/私有仓库、MCP/DSH 来源、用户提交来源建议、外部目录种子,以及基于审核结果的搜索规则自动调权均不在首期。先保留来源与凭证的作用域扩展点,后续按独立需求评估。