skillhub/openspec/changes/add-github-skill-sync/specs/github-source-management/spec.md
XiaoSeS 2df4c913cb feat(github-sync): add continuous public repository discovery and skill sync
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-20 14:40:46 +08:00

241 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## Purpose
定义公开 GitHub 来源如何被发现、登记、归属和管理,使平台社区目录与团队来源拥有清晰的权限、可见性和持续同步边界。
## ADDED Requirements
### Requirement: 平台 SHALL 提供官方探索与可配置的公开 GitHub 来源入口
官方深度探索 SHALL 使用仓库名称、描述、topic、README 线索与有效仓库作者的一层扩展,配合历史补搜和周期补漏,再检查候选仓库树中的 `SKILL.md`。自定义规则继续使用关键词和 topic 条件。首期默认策略 SHALL NOT 依赖全站代码搜索;代码搜索经独立对照试验确认增量有效召回、请求成本和限流恢复后,才可通过后续版本纳入。规则预览与运行反馈 SHALL 说明搜索索引与线索范围存在覆盖边界,不保证全站穷尽。
后台自定义搜索规则 SHALL 由可编辑的关键词与 topic 条件组成,每个条件区分核心或扩展优先级;管理员 SHALL NOT 被要求输入原始 GitHub 查询表达式。各条件独立搜索,候选按 GitHub repository ID 合并,核心条件优先使用发现预算;条件优先级 SHALL NOT 直接决定发布资格。规则变更 SHALL 生成新版本,已领取任务使用其固定快照与固定增量/全量搜索窗口,不因后台编辑改变本轮语义。
平台 SHALL 支持官方深度探索、结构化规则自动搜索、管理员指定精选仓库、管理员指定精选 GitHub 用户或组织。精选用户或组织 SHALL 持续检查其公开仓库;自动发现的仓库 SHALL 在确认存在有效 Skill 候选后,按 GitHub repository ID 去重并登记来源,无需仓库级人工确认。管理员明确指定的精选仓库 SHALL 可先登记为待首次扫描来源。发现分数 SHALL NOT 直接批准发布 Skill。
审核积压达到高水位期间,仓库搜索和精选用户或组织枚举的结果 SHALL 只成为有预算、可去重的待验证线索;此时不得因搜索命中创建正式来源。低水位恢复后 SHALL 重新检查仓库当前公开状态与 Skill 候选,再沿正常流程登记来源。
#### Scenario: 搜索发现有效公开仓库
- **WHEN** 启用的搜索规则发现一个可公开读取且包含有效 `SKILL.md` 的仓库
- **THEN** 系统自动登记或复用对应来源,并安排采集
- **AND** 不因此发布任何 Skill
#### Scenario: 多个搜索条件命中同一仓库
- **WHEN** 核心关键词与扩展 topic 条件都命中同一 GitHub repository ID
- **THEN** 本轮只建立一个候选,保留两个条件的命中出处
- **AND** 条件优先级只影响先后顺序,不直接批准或拒绝 Skill
#### Scenario: 精选用户出现新仓库
- **WHEN** 平台管理员配置的精选用户或组织新增公开仓库,且其中存在有效 Skill 候选
- **THEN** 系统与搜索来源使用相同的仓库去重和采集流程
#### Scenario: 同一仓库被多个入口发现
- **WHEN** 搜索规则、精选用户或精选仓库指向同一 GitHub repository ID
- **THEN** 同一目标 namespace 中只形成一条来源记录
- **AND** 来源记录保留各发现入口的出处信息
### Requirement: 来源 SHALL 归属明确的 namespace
平台自动发现和平台精选来源 SHALL 归不可由普通用户删除的 `@github` 平台 namespace,其审核通过的 Skill SHALL 全局可见。TEAM 管理员 SHALL 能为本团队登记公开 GitHub 仓库;TEAM 来源及 Skill SHALL 归该 TEAM namespace,不自动合并到 `@github`。同步 Skill 的业务归属 SHALL 是对应 namespace,不归配置管理员个人。同一仓库在不同 namespace 中 SHALL 保持独立的来源绑定与审核结果。
#### Scenario: 团队登记平台已采集的仓库
- **WHEN** TEAM 管理员在本团队登记一个已存在于 `@github` 的公开仓库
- **THEN** 系统在 TEAM 中建立独立来源绑定,且不复用平台的发布审核决定
#### Scenario: 非平台管理员修改平台发现规则
- **WHEN** 无平台管理权限的用户尝试修改自动搜索规则、精选用户或组织
- **THEN** 系统拒绝操作,并保持规则不变
#### Scenario: 配置管理员离开团队
- **WHEN** 登记 TEAM 来源的管理员退出团队
- **THEN** 来源及已同步 Skill 仍归 TEAM namespace,并由现有 TEAM 管理角色继续管理
### Requirement: TEAM 来源 SHALL 使用来源级可见性
TEAM 来源 SHALL 有一个适用现有 SkillHub 可见范围的来源级配置,默认 `NAMESPACE_ONLY`。来源可见范围的修改 SHALL 只作用于之后导入的 Skill 或版本,不得静默改变已发布 Skill 的可见性。GitHub 仓库公开状态 SHALL NOT 直接决定 SkillHub 可见范围。
#### Scenario: 团队来源首次导入
- **WHEN** TEAM 管理员登记公开仓库但未设置来源可见范围
- **THEN** 后续新 Skill 默认使用 `NAMESPACE_ONLY`
#### Scenario: 修改来源可见范围
- **WHEN** TEAM 管理员修改来源可见范围
- **THEN** 系统明确说明该设置仅影响后续导入
- **AND** 已发布 Skill 的可见范围保持不变
### Requirement: 来源与发现规则 SHALL 分别管理生命周期
规则变更或停用 SHALL 只影响未来发现,不自动停用已登记来源。来源 SHALL 可暂停同步;单个 Skill 路径 SHALL 能通过来源忽略路径规则停止后续采集,移除该忽略项后可恢复,未单独排除的路径继承来源状态;停用或移除来源 SHALL 停止后续同步,并保留已经创建的 Skill、版本、来源出处与运行历史。已经停用的来源 SHALL NOT 因再次被搜索命中而自动重新启用。
#### Scenario: 停用发现规则
- **WHEN** 管理员停用一个搜索规则
- **THEN** 该规则停止产生新来源,而此前登记的来源仍按自身状态同步
#### Scenario: 停用来源后再次命中
- **WHEN** 已停用来源对应的仓库再次被任一发现入口命中
- **THEN** 系统保留停用状态,不自动恢复同步或改变已发布 Skill
#### Scenario: 只暂停一个 Skill 路径
- **WHEN** 管理员暂停仓库中的某个 Skill 路径
- **THEN** 该路径停止后续同步,同仓库其他路径继续处理
- **AND** 已发布版本保持不变
### Requirement: 后台 SHALL 提供统一配置和反馈入口
平台后台 SHALL 在统一的 GitHub 同步管理区域呈现规则预览、启停、精选来源、仓库来源、运行结果、延后与失败原因。TEAM 管理员 SHALL 只能查看和操作有权限的 TEAM 来源。规则界面 SHALL 使用结构化条件,不要求管理员编写 GitHub 搜索表达式。自定义广泛搜索 SHALL 只执行后台已启用的规则及目标周期。官方深度探索 SHALL 作为内置方式提供独立启停,首次默认停用;其开关 SHALL 仅控制该探索途径,不作为所有 GitHub 同步的全局开关。关闭探索 SHALL 不暂停已登记有效仓库的更新,也不影响精选仓库及独立自定义规则。官方探索 SHALL 仅向管理员提供启停、资源预算档位与排除项,内部查询集合、渠道搭配、分页和补漏节奏由系统维护;具体范围参见 [深度探索需求澄清](../../deep-discovery.md)。首期预置规则初始停用,管理员可在同一配置区域查看、编辑和启用;明确添加精选仓库 SHALL 不受预置搜索规则启用状态影响。
平台运行详情 SHALL 按运行 ID 展示该轮任务及逐 Skill 路径结果,并分别分页;发现运行可以没有 Skill 路径。逐路径结果 SHALL 关联当轮任务、仓库、采集结果及对应摄入/审核状态,不得用来源的最新状态冒充历史运行结果。已按保留策略清理的运行详情不再作为可查看运行返回。
#### Scenario: 平台启用官方深度探索
- **WHEN** 平台管理员首次启用内置深度探索
- **THEN** 系统以公共 `@github` namespace 为目标持续发现公开仓库
- **AND** 首期 TEAM 不提供独立官方探索配置,继续使用既有来源管理能力
#### Scenario: 停用和恢复官方深度探索
- **WHEN** 管理员关闭官方深度探索
- **THEN** 系统保留候选及检查点,暂停该途径尚未登记为正式来源的候选后续采集,在途操作到安全检查点暂停
- **AND** 已登记来源继续按自身配置更新,其他独立启用入口仍需要的候选不受影响
- **WHEN** 管理员重新开启官方深度探索
- **THEN** 系统从保留的进度继续处理,不清空候选重新搜索
#### Scenario: 排除探索仓库或作者
- **WHEN** 管理员在官方探索排除项中配置仓库或作者
- **THEN** 系统排除该探索途径对其新仓库的发现,不据此暂停已登记来源
- **AND** 对命中的未登记候选暂停后续采集并保留记录和进度,取消排除后可继续;其他独立启用入口仍需要的候选不受影响
- **AND** 来源暂停与 Skill 目录忽略仍使用现有独立配置
#### Scenario: 调整官方探索预算档位
- **WHEN** 管理员配置官方探索资源预算
- **THEN** 系统提供节省、均衡、加速三个档位,默认均衡
- **AND** 档位只调整执行速度和资源分配,不删减探索渠道或覆盖范围
- **AND** 加速仍受部署额度、候选容量、采集准入与既有来源更新的资源保护约束
#### Scenario: 官方策略随产品升级
- **WHEN** SkillHub 升级引入新版官方探索策略
- **THEN** 系统自动采用新策略,保留管理员启停、预算与排除配置
- **AND** 新增查询自动安排历史补搜并尽量复用兼容进度,停用状态不被升级恢复
- **AND** 在途任务保持固定策略版本,不中途混用新旧策略
#### Scenario: 查看官方深度探索
- **WHEN** 平台管理员进入官方深度探索
- **THEN** 系统在统一技能同步后台集中展示配置及结果,与既有来源和运行详情保持关联;旧独立探索页面重定向到采集配置抽屉
- **AND** 主页面通过总览/仓库/运行记录切换内容;启停、预算与排除项在采集配置抽屉集中编辑,探索进度按需展开
- **AND** 仓库数、技能数、近期新增与当前待审数量明确区分,不用搜索命中数代替导入成果
#### Scenario: 分页查看发现仓库
- **WHEN** 管理员打开发现仓库列表
- **THEN** 默认包含所有状态的可查询结果,按最近发现排序,每页 20 条
- **AND** 搜索、状态和渠道筛选及分页在服务端完成,不向浏览器返回完整候选集合进行筛选
- **AND** 列表只加载摘要,详情按需加载;后台新增结果不自动跳页或丢失筛选与选中项
#### Scenario: 查看探索仓库详情
- **WHEN** 管理员点击探索仓库
- **THEN** 系统按需加载详情抽屉,展示命中渠道、检查结果、未导入原因及后续安排
- **AND** 存在关联来源或审核记录时提供相应入口,关闭抽屉保留列表筛选与位置
#### Scenario: 展示探索覆盖进度
- **WHEN** 管理员查看探索进展
- **THEN** 系统展示渠道工作、已完成查询分片、待处理工作与暂停原因,查询和分页细节进入运行详情
- **AND** 总量未知时不显示完成百分比,不将当前计划范围完成描述为 GitHub 全量覆盖
#### Scenario: 区分近期成果与当前积压
- **WHEN** 管理员切换近期成果时间范围
- **THEN** 新增候选、首次确认有效仓库及新采集技能按所选时间统计,同仓库多渠道命中去重,更新版本单列
- **AND** 当前待检查仓库与待审版本独立展示,不受该时间筛选影响
#### Scenario: 反馈探索等待原因
- **WHEN** 探索因额度或容量限制延后
- **THEN** 系统展示原因、受影响工作、仍可继续的工作及相关配置或审核入口
- **AND** 有可靠依据才显示预计可重试时间,否则展示恢复条件;满足条件后自动续跑
#### Scenario: 采集服务不可用时等待和接管
- **WHEN** 官方探索已启用但无可用 Go 执行实例
- **THEN** Java 保留任务与已确认检查点,页面显示等待采集服务恢复,不将到期重试时间描述为实际执行
- **AND** 心跳超时只表示联系中断,单实例离线不代表全部实例离线
- **WHEN** Go 恢复或其他实例领取过期租约任务
- **THEN** 从已保存进度继续;未确认部分可重放,旧租约写入拒绝,业务接收幂等
#### Scenario: 预览规则
- **WHEN** 平台管理员预览尚未启用或已编辑的搜索规则
- **THEN** 后台展示可解释的预估命中结果和规则条件
- **AND** 预览本身不登记来源或创建待审 Skill
#### Scenario: 采集服务离线时打开规则预览
- **WHEN** 平台后台检测到 Go 采集服务离线或无法确认状态
- **THEN** 规则预览操作不可提交,并明确说明服务状态
- **AND** 已排队、执行中、延后重试和失败的预览分别显示对应状态,不将排队误称为正在搜索 GitHub
- **AND** 管理员仍可将新规则保存为停用状态
#### Scenario: 后台启用预置规则
- **WHEN** 管理员在 GitHub 同步管理区域启用一条预置搜索规则
- **THEN** Java 依据该规则和配置的目标周期生成发现任务,Go 后续领取执行
- **AND** 无需再启用官方探索;执行仍受平台采集安全暂停、额度及容量控制
#### Scenario: 首次部署或升级尚未启用规则
- **WHEN** 系统已预置搜索规则且官方探索与所有自定义搜索规则均未启用
- **THEN** 不产生广泛搜索任务
- **AND** 管理员明确添加的精选公开仓库仍可进入同步流程
#### Scenario: 查看来源失败
- **WHEN** 来源采集失败或被延期
- **THEN** 有权限的管理员能看到当前状态、最近尝试、原因和下一次可运行时间
### Requirement: 市场 SHALL 展示可公开的 GitHub 来源
已发布同步 Skill 的详情 SHALL 展示来源仓库、Skill 路径、固定 commit 与可公开的许可证信息。无权访问 TEAM Skill 的用户 SHALL 不能通过来源展示接口获得其仓库绑定或运行状态。
市场 SHALL 提供单独的公开 GitHub 技能入口,仅检索已发布且当前用户可见的 `@github` Skill,并支持站内搜索、排序和分页;展示数量 SHALL 来自实际市场查询,不得把发现候选、待审包或仓库线索计入已发布 Skill 数量。
该入口的人类可见名称 SHALL 为“开源技能”,并明确标注首期内容仅来自 GitHub 公开仓库;现有 `/github` 路由和 `@github` 过滤范围保持不变,不暗示已接入其他代码托管平台。
#### Scenario: 查看平台同步 Skill
- **WHEN** 用户查看一个已发布的 `@github` Skill
- **THEN** 页面展示可核对的 GitHub 来源与许可证信息
#### Scenario: 无权访问团队来源
- **WHEN** 无 TEAM 权限的用户请求仅团队可见 Skill 的来源详情
- **THEN** 系统沿用现有 Skill 可见性规则拒绝或过滤该信息
### Requirement: 凭证配置 SHALL 只服务于公开读取
平台管理员 SHALL 可配置零个或多个系统级公开 GitHub API 凭证;无凭证时公开仓库同步 SHALL 仍可在匿名额度内运行。认证失效的凭证 SHALL 标记不可用并在后台提示,系统 SHALL 可选用另一健康系统凭证;已配置凭证池但无健康可用凭证时 SHALL 延后任务并提示修复,不自动降级为匿名;仅未配置任何凭证时使用匿名额度。凭证认证失效、仓库访问失败和 GitHub 限流 SHALL 分别展示。系统 SHALL 不接受本期来源的个人 OAuth 或私有仓库凭证;凭证值 SHALL 不出现在普通页面响应、任务历史、日志或指标中。
#### Scenario: 未配置凭证
- **WHEN** 系统未配置 GitHub 凭证
- **THEN** 公开来源发现与同步可使用匿名访问,并按实际额度延后任务
#### Scenario: 系统凭证失效
- **WHEN** GitHub 确认当前系统凭证认证失效
- **THEN** 系统不再把该凭证分配给任务,并在后台提示管理员更新
- **AND** 后续公开读取可使用其他健康系统凭证;若池内均不可用(含全部被停用),则等待凭证修复,不自动切换为匿名
#### Scenario: 凭证达到额度限制
- **WHEN** GitHub 对某凭证返回限流或重试时间,而非认证失效
- **THEN** 系统保留该凭证的健康状态并按限流规则延后任务
- **AND** 不通过连续切换凭证规避限流
#### Scenario: 仓库变为私有
- **WHEN** 已登记公开仓库不再可公开读取
- **THEN** 系统将来源标记为访问失败并进入恢复策略
- **AND** 不使用其他凭证尝试私有访问
### Requirement: 平台 SHALL 提供单一技能同步入口和统一仓库列表
平台管理员 SHALL 通过「技能同步」的概览、仓库、运行记录三个页签查看工作,采集配置与系统设置 SHALL 按需打开。自动探索 SHALL 是采集方式之一,指定仓库 SHALL 表达管理员指定而非质量认证。仓库列表 SHALL 覆盖平台适用的自动探索、指定仓库、指定账号和自定义搜索规则结果,以namespace和稳定repository ID去重,保留多出处,通过服务端筛选及分页,不在浏览器拼接独立分页结果。
首次准备 SHALL 根据真实配置和服务状态提示缺项,凭证可选,不强制向导或擅自启用探索。添加指定仓库 SHALL 只要求仓库URL或owner/repo,固定平台@github,沿用已配置的公共策略;重复添加 SHALL 复用仓库记录而不改变既有暂停意图。运行列表 SHALL 展示真实运行及其类型、目标、状态和结果,不虚构全站探索轮次。概览 SHALL 区分需要人工处理和可自动恢复的等待。
#### Scenario: 同一仓库由多个入口发现
- **WHEN** 平台自动探索和指定仓库指向同一个稳定repository ID
- **THEN** 统一仓库列表仅显示一行,保留两种出处并返回准确分页总数
- **AND** TEAM相同仓库不合并到平台仓库行
#### Scenario: 首次配置和旧链接兼容
- **WHEN** 管理员打开未配置完成的技能同步页面
- **THEN** 准备清单显示真实缺项并可定位配置,不把无凭证直接判为错误
- **AND** 既有sourceId/runId深链与旧探索入口继续可达对应内容
#### Scenario: 已存在的指定仓库在平台暂停时再次添加
- **WHEN** 管理员提交已经存在的仓库地址且平台采集已暂停
- **THEN** 系统复用仓库、保留出处和已有启停状态,并显示等待平台采集恢复
- **AND** 不产生重复采集来源或绕过暂停