7.7 KiB
Purpose
定义 GitHub 同步内容如何进入 SkillHub 的版本、扫描、审核和发布流程，使上游变化可追溯，同时不冲击普通用户提交的审核队列。
ADDED Requirements
Requirement: 同步内容 SHALL 使用独立审核队列
新同步 Skill 和内容变化形成的新版本 SHALL 进入安全扫描与人工同步审核，审核通过前不得发布或替换当前已发布版本。同步审核 SHALL 与普通用户提交审核分开呈现；可按仓库和运行批次归组，但每个 Skill SHALL 独立批准或拒绝。审核权限 SHALL 沿用现有 SkillHub 角色规则。
首期 SHALL NOT 提供切换人工审核与自动发布的配置项；无人审核时，待审内容仍不得自动进入市场。自动审核能力须在独立需求中明确检查与误判处理后再评估。
Scenario: 自动发现新 Skill
- WHEN 自动发现并采集到一个此前未发布的有效 Skill 包
- THEN 系统创建待审内容并显示在同步审核队列
- AND 在审核通过前，该 Skill 不作为已发布市场内容展示
Scenario: 上游更新待审
- WHEN 已发布 Skill 的上游内容发生变化
- THEN 当前已发布版本继续可用，新内容独立等待扫描及同步审核
Requirement: 同一 Skill SHALL 只有一个当前可批准的同步目标
同一 Skill 已有待审同步目标时，新上游 revision SHALL 取代其可批准资格；系统 SHALL 保留旧目标及决策历史供审计，仅最新目标可被批准。已拒绝的相同内容指纹 SHALL 不因周期同步反复创建待审项；内容变化或显式重试后才可再次提交。
Scenario: 待审期间上游再更新
- WHEN Skill 的新 revision 到达，而旧 revision 仍待审
- THEN 旧目标不再可批准，最新目标成为唯一可批准对象
- AND 旧快照和审核历史保持可查
Scenario: 相同拒绝内容再次出现
- WHEN 周期同步再次得到此前已拒绝且内容指纹相同的包
- THEN 系统不重复创建待审项
Requirement: 同步审核 SHALL 提供可核对的内容差异
首次导入 SHALL 展示文件树与内容预览；更新 SHALL 展示相对上次已发布版本的文件新增、修改、删除及可预览文本差异。审核信息 SHALL 展示来源仓库、固定 commit、Skill 路径、安全扫描结果、许可证或 NOTICE 信息及发起者/运行记录。审核者 SHALL 不得直接编辑上游采集内容。同步审核与普通技能审核 SHALL 共用一致的详情页框架：顶部显示对象说明、来源摘要及始终可见的安全和许可证状态；中部通过“技能内容”“变更对比”“来源与安全”“审核记录”Tab 访问适用信息，完整安全卡片与发现项位于“来源与安全”Tab，顶部状态可直达该 Tab；底部审核意见和批准/退回操作在切换 Tab 与滚动时保持可见。没有扫描结果 SHALL 显示明确空态，不得暗示安全通过。同步项 SHALL 展示独立持久化的内容修订号和短 Git commit；完整内部版本标识须可追溯但不得作为溢出的主展示标签。
Scenario: 审核更新
- WHEN 审核者打开一个上游更新的待审项
- THEN 界面展示与上次已发布版本的逐文件变化和 GitHub commit 来源
- AND 审核者可逐个 Skill 批准或拒绝，但不能改写采集文件
Scenario: 在审核页逐文件核对变化
- WHEN 审核者进入“变更对比”并选择一个可预览的变更文件
- THEN 页面以占据主内容宽度的单栏视图展示该文件差异，并保持文件切换入口和底部审核栏可用
- AND 页面只按需读取所选文件内容；首次导入无基线时展示新增文件内容，二进制或超限文件展示明确的不可预览原因
Scenario: 查看安全发现项并作出决定
- WHEN 审核者在顶部看到扫描状态并进入“来源与安全”Tab
- THEN 完整安全结论、发现项和许可证证据可核对，缺失或加载失败不会显示为通过
- AND 审核意见在切换 Tab 后仍保留，原有扫描和许可证阻断规则继续生效
Requirement: GitHub 同步内容 SHALL 使用独立的内容修订号
每个 Skill 的首次采集内容 SHALL 记为第 1 次修订。相对该 Skill 最近同步目标的内容 SHA-256 变化时，修订号 SHALL 递增；同内容的审核重试 SHALL 沿用原修订号，Git commit 变化但内容不变 SHALL 不产生新修订。内容回退到更早的 SHA-256，但与最近同步目标不同，SHALL 产生新修订。修订号 SHALL 随 Skill 版本持久化，审核页和市场来源信息展示该号。现有技术版本字段 SHALL 保留，继续用于安装和精确版本定位；上游自报版本仅作为来源元数据，不参与修订排序。
Scenario: 拒绝后重新审核相同内容
- WHEN 管理员要求对已拒绝且内容 SHA-256 未变化的 GitHub Skill 重新审核
- THEN 新审核目标沿用原内容修订号，技术版本仍保持唯一
Scenario: 内容回退
- WHEN 某 Skill 的内容从 A 变为 B 后又回到 A
- THEN 回退后的目标获得更大的修订号
Requirement: 同步 SHALL 保留来源权利与许可证信息
系统 SHALL 保留和展示仓库或技能包的许可证、NOTICE 与来源署名，不得将第三方内容标记为 SkillHub 自有许可证。平台 @github 来源的许可证缺失或无法识别时 SHALL 阻止自动公开发布，待具有现有审核权限的平台人员明确处理；TEAM 来源 SHALL 呈现相同警告和人工审核信息。
Scenario: 平台 Skill 缺少可识别许可证
- WHEN
@github来源的待审 Skill 无可识别许可证 - THEN 系统在审核页显示阻塞原因，并要求平台人员明确处理后才能公开发布
Requirement: 同步冲突 SHALL 阻断自动绑定
同一 namespace 中 Skill 坐标冲突或多个来源指向同一 Skill 时，系统 SHALL 阻断自动导入并交给该 namespace 的管理员处理，不得覆盖现有 Skill。确认是同一 Skill 的情况下，具有权限的管理员 SHALL 能把来源绑定到既有 Skill ID，并留下审计记录。单个 Skill SHALL 只有一个权威同步来源。
Scenario: 同名冲突
- WHEN 新来源 Skill 的目标坐标已属于另一个 Skill 或来源
- THEN 系统将该 Skill 标记为冲突，其他 Skill 继续处理
- AND namespace 管理员获得处理入口，现有内容保持不变
Scenario: 人工确认绑定
- WHEN 有权限的管理员确认新来源应绑定到既有 Skill ID
- THEN 系统记录操作者和绑定依据，并从后续固定 revision 更新该 Skill
Requirement: 路径变化与消失 SHALL 不误删 Skill
同一仓库旧 Skill 路径消失时，仅当新路径的完整技能包内容哈希存在唯一匹配，系统 SHALL 自动认定路径移动；否则进入人工确认。上游目录删除、部分扫描或来源停用 SHALL NOT 自动删除、撤回或隐藏已发布 Skill，也不得仅凭目录消失创建删除审核项。
Scenario: 唯一路径移动
- WHEN 同仓库旧路径消失，且只有一个新路径的完整包哈希与旧包相同
- THEN 系统更新来源路径绑定并保留 Skill ID 和历史版本
- AND 自动移动或管理员确认同内容移动不替换当前内容审核目标；已有待审仍可批准或拒绝，已拒绝的当前内容仍可显式重审
- AND 真正新内容取代目标后，旧审核仍不可决定；随后内容回退为相同哈希也不能恢复旧审核资格
Scenario: 上游删除目录
- WHEN 完整扫描确认上游某个 Skill 目录不再存在
- THEN 系统记录上游缺失，但不删除已发布 Skill 或创建删除审核项