skillhub/openspec/changes/add-github-skill-sync/tasks.md
XiaoSeS 27c1dcf971 docs(github-sync): align review and revision task status
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-20 16:03:02 +08:00

95 lines
14 KiB
Markdown
Raw Permalink 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.

## 1. 领域模型与迁移
- [x] 1.0 新增 `skillhub-github-sync` Maven 功能模块并接入 parent/app/infra 依赖与 server Dockerfile;验证依赖方向为 app、infra → github-sync → domain/storage,且不新增 Java 进程。
- [x] 1.1 增加系统管理的 `CATALOG` namespace 与 `@github` 初始化、保留 slug 和系统 actor;验证已有同名 namespace 会明确阻断且不改动用户数据。
- [x] 1.2 增加 GitHub 来源、发现入口、规则版本、仓库 ID、namespace 归属与来源级可见范围模型;验证同 namespace 去重和跨 namespace 独立绑定。
- [x] 1.3 增加发现运行、仓库任务、租约、检查点、逐 Skill 结果和重试时间持久化;验证并发领取只有一个有效租约且重放不产生重复记录。
- [x] 1.4 为审核记录增加普通/同步来源判别及同步目标关联,迁移旧数据为普通审核;验证普通审核查询结果不变。
- [x] 1.5 增加系统级公开 GitHub 凭证密文、版本化密钥与健康状态支持;验证无密钥无法解密、轮换可读旧密文、认证失效可标记并提示、配额耗尽不误标失效、API/日志只返回脱敏信息。
## 2. Java 控制面与服务间合同
- [x] 2.1 实现平台规则、精选仓库、精选用户或组织的配置与无副作用预览 API;规则只接受关键词/topic 条件及核心/扩展优先级,变更生成新版本并固定增量/全量搜索窗口,预置规则初始停用。验证首次部署/升级不自动广泛搜索、规则启用后生效、精选仓库可直接同步、权限、规则版本、去重、预览不创建来源及原始 GitHub 查询被拒绝。
- [x] 2.2 实现 TEAM 公开仓库来源配置、来源级可见范围和暂停/恢复 API;验证越权拒绝、默认可见性及已发布 Skill 不变。
- [x] 2.3 实现默认约 24/24/72 小时、后台按类别可调的任务目标周期,以及广泛搜索默认 7 天全量重查、来源级待执行任务合并、人工触发合并、来源优先级、TEAM 公平性和未解决同步项高低水位;按最新 `(namespace, repository ID, Skill 路径)` 计数并原子预留未完成包准入,高水位停止新包采集,但已启用发现任务可有预算地保存仓库线索,已登记仓库只查 HEAD;分别记录已观察与已完整处理 commit,低水位后重新核对当前 revision;验证并发任务不越过准入线、候选预算有界、不同 namespace 反压隔离和 Go 离线不重复堆积。
- [x] 2.4 在 `docs/api/github-sync-internal.openapi.yaml` 定义独立于 Web 公开 API 的版本化 HTTP/JSON 内部领取、续租、逐包采集准入、临时上传授权、逐包回报、完成/失败合同,并使 Java/Go 合同样例保持一致;在 Spring Security 为内部路由单独验证服务身份、限制权限并处理无会话请求,不依赖未注册的 `IdempotencyInterceptor`;逐包回报只在持久摄入记录成功后确认接收,验证过期租约、重复/冲突回报、准入占位释放、密钥轮换、非机器身份和不兼容版本。
- [x] 2.5 实现有预算、按 GitHub repository ID 去重的待验证仓库线索、发现游标及到正式来源的转换,并处理仓库 rename/transfer 对账;验证高水位只积累有界线索、不检查新候选树,低水位后重新核对当前仓库状态,无有效 Skill 的搜索候选不进入正式来源。
- [x] 2.6 为 S3/MinIO 与本地存储提供短时、限对象 key 的上传票据,Java 以 `uploadId` 定位暂存对象,不接收 Go 提供的任意下载链接;实现隔离暂存区容量告警与清理补偿。验证 Go 无管理凭证仍可逐包上传、越权 key 被拒绝、本地流式入口执行大小硬上限、S3/MinIO 超额对象在 Java 摄入前被拒绝并清理。
- [x] 2.7 实现可恢复的运行检查点、同 commit 失败路径重试和 `retryAt`,验证执行端重启后不重做已完成 Skill 包。
- [x] 2.8 已完成运行/任务详情默认保留 90 天,未完成任务与恢复数据豁免按期清理,来源/审核审计沿用原生命周期;验证清理不会破坏续跑或审核追溯,容器日志保留交部署环境管理。
## 3. Go 发现与采集服务
- [x] 3.1 在仓库根目录建立独立 Go module 与单二进制,按控制面客户端、GitHub 访问、发现、仓库包采集和 worker 分层;建立含 Git CLI/CA 证书、非 root 运行的镜像、健康/指标入口和两个有界工作池;验证默认单副本在本地 Compose 可启动、停机不再领取新任务并释放在途资源。
- [x] 3.2 实现带匿名/系统凭证选择的 GitHub 客户端、资源类别额度跟踪、认证失效回报、限流退避与脱敏日志;用 HTTP fixture 验证认证失败、仓库不可读、403/429 限流、reset、健康凭证回退和匿名公开读取,确保不以轮换规避限流。
- [x] 3.3 实现关键词/topic 条件的独立仓库搜索查询、核心/扩展预算顺序、精选用户或组织公开仓库枚举及精选仓库探测;首期只用仓库元数据召回线索,不做 README/全站代码搜索,再以仓库树验证 `SKILL.md`。验证固定窗口与规则版本、去重、增量与全量轮次、1,000 结果上限和 `incomplete_results` 不误记成功,并说明元数据缺少线索时可能漏召回。
- [x] 3.4 实现固定 commit、递归树枚举与截断后子树续查;验证部分子树失败仍处理完整子树且结果标记为不完整。
- [x] 3.5 实现独立 Skill 根识别、嵌套子树排除、已确认的 10 个默认候选忽略目录和来源级追加规则;Go 在固定 commit 上仅把所需包文件取到受限本地临时目录,按当前有效发布政策预检文件数、单文件与包总量,逐包打包上传;验证 `test/` 候选被忽略而父包测试文件保留,且不下载无限制整仓。
- [x] 3.6 实现先 Tree 元数据枚举/预检、后受限 Git CLI 的 blobless 局部获取、固定 commit 校验、稀疏读取及逐 Skill 包归档,拒绝符号链接与 submodule;对 `.git`、检出文件和归档施加每仓库/进程总临时磁盘预算,逐包清理,逼近预算时保存 `pathCheckpoint`、释放目录并从同一 commit 续跑;若容量不足以处理一个合规包,回报容量阻塞且同配置下不立即重试。验证大仓库不会无界下载或占满本地磁盘,单包失败不阻断兄弟包。
- [x] 3.7 实现领取、续租、逐包采集准入、短时上传、逐包结果与运行额度回报,并支持已登记仓库的仅 HEAD 检查模式;验证高水位后不再启动新包下载或创建待审项、已获准包可结算、未处理路径保存检查点,以及固定 commit 失败路径重试的幂等和临时对象摘要。
## 4. SkillHub 导入、版本与审核
- [x] 4.1 建立可恢复的逐包摄入记录与后台消费流程,对临时采集包以有界流式读取重新校验摘要、路径、文件数/大小、`SKILL.md`、忽略规则和许可证证据;验证已接收回报在 Java 重启后续跑,伪造回报不创建 Skill 或版本。
- [x] 4.2 实现规范化包内容与许可证证据的内容指纹;验证同内容不升版、仅 commit 变化不升版、许可证变化可被发现。
- [x] 4.3 以 namespace 和系统 actor 创建来源绑定及待审 Skill 版本,接入现有 Scanner;验证 `@github` 全局可见、TEAM 默认 `NAMESPACE_ONLY` 且审核前不发布。
- [x] 4.4 实现最新待审目标取代旧目标资格、相同拒绝指纹抑制和审计保留;验证待审期间连续两次上游变化仅最新可批准。
- [x] 4.5 实现同 namespace slug 冲突阻断、经授权的既有 Skill ID 绑定及唯一内容哈希路径移动;验证不覆盖他人 Skill、不误合并跨 namespace 来源。
- [x] 4.6 实现目录消失、部分扫描、来源暂停及不可达恢复语义;验证所有场景均不自动删除或撤回已发布 Skill。
- [x] 4.7 在同步审核中提供首次文件树、更新逐文件差异、来源 commit、许可证/NOTICE、扫描与操作者信息;验证审核者不能修改上游采集内容且许可证阻塞可见。
## 5. 管理后台与市场展示
- [x] 5.1 增加平台 GitHub 同步总览、规则编辑/预览、精选入口、来源列表、运行与额度、凭证管理;分别展示已采集交付、Java 处理中、待同步审核和处理失败,通过页面验证空态、延后、失败和手动触发反馈。
- [x] 5.2 在 TEAM namespace 管理视图增加公开仓库来源及逐 Skill 状态,验证团队管理员只看到本团队数据和可用操作。
- [x] 5.3 在审核区增加与普通审核分离的同步队列,按仓库/运行分组但逐 Skill 决策;验证现有普通审核列表仍仅显示普通项。
- [x] 5.4 在市场 Skill 详情展示 GitHub 来源、固定 commit、许可证/NOTICE 与同步状态允许公开的信息;验证 TEAM 私有或仅 namespace 可见来源不会泄露给无权用户。
- [x] 5.5 按产品图重组平台 GitHub 同步总览、来源发现与运行详情,并提供公开 `@github` 技能专页;运行详情必须使用当轮任务和逐路径事实,公开页数量只统计市场可见已发布 Skill。
- [x] 5.6 统一普通技能与 GitHub 同步技能审核详情布局:顶部技能说明及安全/许可证摘要,中部内容、变更、来源与安全、记录 Tab,底部固定审核意见与操作;GitHub 逐文件差异占满主内容宽度,完整安全发现项在对应 Tab 中,长技术版本仅在折叠信息中显示。
- [x] 5.7 为 GitHub 同步技能持久化内容修订号,并在审核和市场展示;保留技术版本作为安装坐标。同内容显式重试沿用修订号,内容变化及回退递增。
审核详情布局与内容修订号的勾选表示实现已完成;每次交付仍须以最终提交执行独立代码审查、接口与浏览器验收,不以历史结果代替本次验证。
## 6. 部署、文档与跨服务验收
- [ ] 6.1 为开发/发布 Compose、Helm、基础 K8s 和现有镜像发布矩阵接入默认单副本的 Go 服务、专用服务密钥、GitHub 凭证密钥、标准 GitHub 出站 HTTP 代理及专用受限临时目录配置;验证可关闭采集、内部 Java 通信不误走代理、镜像目标架构可构建,并在小容量临时磁盘下安全停止/续跑,且无需新增队列/KMS/mTLS 组件即可在本地存储和 S3 两种模式运行。
- [x] 6.2 编写中文管理员配置与运行手册,明确公开仓库范围、Token 权限、无 TLS 部署风险、停用/恢复、限流与故障排查;验证文档命令和配置字段与实际部署一致。
- [x] 6.3 先用少量真实公开仓库验证单/多 Skill、嵌套与较大仓库的采集边界,再用受控 fixture 和合成任务逐级验证约 1000 仓库、10000 Skill 路径的容量基线;同时覆盖搜索、精选用户、部分树、无变化、更新待审、路径冲突、不可达和恢复,分别记录公网请求数与本地容量证据。
- [x] 6.4 检查日志、指标、普通 API 和任务记录的凭证与内容泄漏路径;验证 Token、Authorization 与完整 Skill 正文不出现于这些输出。
- [x] 6.5 运行 OpenSpec 严格校验、相关后端/Go/Web 检查并建立规格到验收结果的追踪表;记录尚未完成的环境验证与原因。
## 官方深度探索增量(已授权,实施与运行验收中)
需求:[deep-discovery.md](deep-discovery.md);设计与验收:[deep-discovery-design.md](deep-discovery-design.md)。既有任务勾选不代表本增量完成;具体实现与验证按下列任务独立追踪。
以下为既有功能任务完成记录。main 整合后的交付须按 [验证说明](verification.md) 重新验证,不能继承历史运行结论。持续公网吞吐和生产 SLA 不属于已验证保证。
- [x] D1a 用户整体确认产品与设计方向,授权进入实施。
- [x] D1b 在verification.md增量索引冻结可执行验收与协议兼容边界;逐项区分受控运行、公网试验和未完成验收,不代表全部场景通过。
- [x] D2 定义配置、分页/抽屉、策略快照、出处和等待反馈合同,同步 OpenAPI 与 MD;完成静态解析、引用及旧完成接口兼容性对照,交叉审查的暂停合同问题已修复。此项不代表 API 已实现或运行验收通过。
- [x] D3 Java 持久状态、去重归因、公平续排、统计查询和权限实现。
- [x] D4 Go 执行官方查询、README、作者一层扩展、分片与恢复实现;策略目录由 Java 统一维护。
- [x] D5 多凭证限流及采集服务离线/多实例恢复完善。
- [x] D6 探索配置、列表抽屉和运行反馈实现;后续 U 节将其并入统一技能同步入口。
- [x] D7 执行设计矩阵、对照召回、限定规模性能及停机恢复验证,完成预算初值的小范围校验。
- [x] D8 已完成公开GitHub小范围代码搜索对照与固定抽样Tree核查;存在新增仓库也存在同blob复制,首期保留备选。未宣称完整包有效性或独立额度恢复通过。
- [x] D9 更新部署/操作说明,记录可回退条件和证据,交付人工预览。
## U. 技能同步入口整合(实现及验收)
方案见[统一管理入口](unified-admin.md)。审核合同保持;Q3/Q6/Q7确认新增平台@github采集安全暂停/恢复,TEAM不受该开关控制,技术合同已冻结于 unified-admin-contract.md。
- [x] U1 抽取可复用页面内容,统一三页签、配置抽屉与URL状态,保留sourceId/runId及旧探索路由兼容。
- [x] U2 整合来源配置、统一仓库列表、运行视图和设置,侧栏仅保留技能同步入口。
- [x] U3 收敛查询与轮询,保留分页、筛选、详情按需加载、权限及错误状态。
- [x] U4 补组件/导航回归、桌面窄屏及浅深色浏览器验证,更新文案和使用指南。
- [x] U5 Java/Go相关质量门、Web质量门、OpenSpec校验与最新预览复查;按实际结果回填证据。
- [x] U6 实施平台@github采集安全暂停/恢复合同;验证持久状态、在途检查点、已接收包继续处理、TEAM不被暂停及原停用来源不被恢复(Q3/Q6/Q7已确认,技术合同已冻结于 unified-admin-contract.md)。
- [x] U7 补齐统一仓库服务端分页/筛选/去重及多出处展示,使用指定仓库产品名称(Q4/Q5已确认)。