skillhub/openspec/changes/add-github-skill-sync/deep-discovery.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

75 lines
8.6 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.

# 官方深度探索:需求澄清
状态:本页记录已确认的产品行为;官方深度探索实现及D1–D9限定验收已完成。当前证据与限制统一见[验收追踪](verification.md),整个同步功能的剩余事项见[任务清单](tasks.md)。既有采集、更新、审核流程继续遵循原规格。
## 已确认的产品边界
- 提供官方内置的深度探索方式,部署后默认关闭,管理员首次启用后持续自动执行,不增加“执行一次”按钮。
- 关闭深度探索停止该途径的新仓库发现;已登记的有效仓库继续按来源设置更新。精选仓库及自定义搜索规则由自己的启停设置控制。
- 后台仅提供启停、资源预算档位和排除项;查询集合、渠道搭配、分页和补漏节奏由系统维护。自定义搜索规则保留为独立补充入口。
- 深度探索开关不是所有 GitHub 同步的总开关。其预算仍受部署额度、候选容量和采集准入约束。
- 首期仅平台管理员配置官方深度探索,目标为公共 `@github` namespace;TEAM 不单独配置官方探索,继续使用既有来源能力。
- 关闭探索保留候选和检查点,暂停尚未成为正式来源的候选后续采集;在途工作到安全检查点暂停,重开后续跑。其他独立启用入口仍需要的候选不受影响。
- 探索排除项只排除指定仓库或作者的新发现,不暂停已登记来源;既有来源暂停和 Skill 目录忽略继续使用各自配置。
- 首期默认探索渠道采用仓库名称/描述/Topic、README 搜索以及有效仓库作者的一层扩展,配合历史补搜、分页与周期补漏。代码搜索先小范围验证,满足上线条件后再纳入默认策略;不阻塞主要渠道。
- 资源预算提供“节省/均衡/加速”,默认均衡;档位只影响执行速度和资源分配,不删减探索渠道或覆盖范围。加速仍受额度、容量和既有仓库更新资源保护约束,当前保守初值及小范围校验结论见设计第3节。
- 新增探索排除项也暂停命中的未登记候选后续采集,保留记录和进度;取消排除后可继续。其他独立启用入口仍需要的候选不受影响,已登记来源不受影响。
- 官方策略随 SkillHub 版本升级自动采用,保留管理员的启停、预算与排除项;新增查询自动补搜历史,尽量复用既有进度,在途任务继续使用固定策略版本。
- 官方深度探索采用独立后台页面,集中展示配置和结果;不采用仅嵌入“来源与发现”页面的方案。产品图用于布局评审,不代表已有实现或真实运行数据。
- 代码搜索先做对照试验:确认能补回其他渠道遗漏的有效仓库,且请求成本、限流恢复与去重可控,再通过后续版本纳入默认策略;效果不明显则保留为备选。
- 本次创建本地 Trellis 规划任务;OpenSpec 为正式需求来源,Trellis 只保留执行索引。
## 已选定的页面结构
- 采用独立探索页面搭配配置弹窗,主页面展示状态与成果,不铺开全部配置表单。
- 顶部展示探索启停、预算摘要与当前状态;数据摘要区分仓库和技能,不以搜索命中数代替导入数量。
- 中间通过“探索进展/发现仓库”切换,探索进展展示渠道工作及等待原因,页面提供最近运行与详情入口。
- 配置弹窗集中编辑启停、节省/均衡/加速档位和仓库/作者排除项。
- 暂停状态明确说明进度已保留、已登记仓库继续更新。
- 采用紧凑按钮、表格、细边框与少量状态色;两张概念图采用统一主页面结构,图二仅作为配置弹窗及暂停状态参考。
- 图片中的日期、数量、仓库和状态是示例,不是已验证事实;近期新增与当前待审数量须明确区分。统计口径见下文及 API 合同,已验证的性能样本和资源边界见验收追踪。
## 列表、抽屉与性能边界
已确认:仓库点击后打开详情抽屉,展示命中渠道、检查结果、未导入原因及后续安排;存在对应来源或审核记录时提供跳转,关闭抽屉保留列表筛选和位置。
已确认:主页面显示渠道当前工作、已完成查询分片、待处理工作及暂停原因;查询与分页细节放入运行详情。总量未知不显示完成百分比,不宣称覆盖全部 GitHub。
已确认:默认展示全部状态的可查询结果,按最近发现排序,每页 20 条;不是一次性加载全部记录。采用服务端搜索、筛选及分页,接口限制最大页大小;详情点击后按需加载。分页方式与既有接口风格协调,大数据下验证深分页成本,不能依赖浏览器全量过滤。
性能设计约束:列表只返回摘要,不附带全部命中历史、日志或技能内容;抽屉中的长列表继续分页。聚合统计独立查询或缓存,不随每页重复全表计算;查询采用匹配过滤和稳定排序的索引,具体方案需结合现有数据库验证。后台执行不应导致表格自动重排、跳页或丢失选中项;轮询在隐藏页面或离开后停止,避免请求叠加。实现和有限性能验收见验收追踪;这些约束不构成所有部署规模的性能保证。
## 已确认的统计和等待反馈
- 近期成果按所选时间段统计新增候选仓库、首次确认有效仓库及新采集技能;同仓库多渠道命中去重,已有技能内容变化单列更新版本。
- 当前积压展示此刻待检查仓库与待审版本,不受近期成果的时间筛选影响。
- 等待额度或容量时展示原因、受影响工作、仍可继续工作及相关配置或审核入口;有可靠时间才显示预计可重试时间,否则显示恢复条件。系统自动续跑,不要求反复手动重试。
### 多凭证额度反馈
额度不是实时保证值:基于 GitHub 响应头的最近观测,并展示观测时间;缺失或过期标为未知,不伪装成零余额。不开高频额度探测或实时推送系统。按请求资源类别区分仓库搜索与普通仓库读取,不能将单个凭证限流直接呈现为全部探索暂停。
多 token 不等于多份独立额度,同一身份可能共享限额,不累加各 token 剩余额度。调度选择当前请求资源可用的凭证;全部适用凭证不可用才延后对应工作。限额主体无法确认时按未知处理,不累加余额;平台预算预约与凭证额度观察分开,具体合同见设计第3节,不承诺其他工具共用凭证时的精确余额。
普通额度耗尽时隔离受影响资源与额度主体;遇到次级限流遵守 Retry-After 或退避,必要时收紧共享并发,不能不断切换 token 继续冲击同一限制。界面优先展示“最近观测/等待额度/冷却中/状态未知”,重置时间只表示预计可重试,不承诺届时一定恢复。
依据:https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api
## 已确认的采集服务离线行为
- Go 不可用时不执行 GitHub 请求;Java 和数据库正常时保留任务、候选、重试时间和检查点。
- 到达重试时间仅意味着允许再次领取,不意味着已执行。页面优先显示“等待采集服务恢复”,不继续承诺准时重试。
- 执行中断后从已确认保存的检查点恢复,未确认的部分可能重做;租约到期允许其他实例接管,旧租约不得写入,业务接收保持幂等。
- 探索配置启用与执行服务在线是两个维度;心跳超时表示联系中断,不能据此断言进程已关闭。多实例须按可执行能力汇总,不能因单实例离线宣布全部离线。
- Go 恢复并满足凭证、准入和排队条件后自动领取续跑。Java 不负责拉起 Go 进程,进程恢复由部署工具或运维负责。
## 实施与验证入口
预算初值、小范围代码搜索对照、运行反馈以及策略升级/恢复的约定验收已记录在[任务清单D1–D9](tasks.md)与[验收追踪](verification.md)。代码搜索继续保留为备选;未来若启用,仍需验证完整包有效性、内容重复率及对应额度合同。长期公网稳定性和全站召回率未由小样本试验证明。
## 设计约束
- 不新增必须由用户理解或操作的“轮次”对象。
- 不把更多命中等同于更多有效技能,不把搜索完成等同于 GitHub 全量覆盖。
- 首期渠道、预算和调度参数按当前设计合同执行;代码搜索保持备选,不自动扩展首期范围。
- 执行合同及实现状态见 deep-discovery-design.md、API 文档及 tasks.md;不能仅据需求描述推断任意部署环境已通过验收。