skillhub/openspec/changes/add-github-skill-sync/specs/github-sync-review/spec.md
XiaoSeS 7a043fe868 fix(github-sync): retain review targets across content-preserving path moves
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-20 14:52:28 +08:00

99 lines
7.7 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 同步内容如何进入 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 或创建删除审核项