skillhub/openspec/changes/add-github-skill-sync/specs/github-source-management/spec.md

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 仅向管理员提供启停、资源预算档位与排除项，内部查询集合、渠道搭配、分页和补漏节奏由系统维护；具体范围参见 深度探索需求澄清。首期预置规则初始停用，管理员可在同一配置区域查看、编辑和启用；明确添加精选仓库 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 不产生重复采集来源或绕过暂停