8.6 KiB
官方深度探索:需求澄清
状态:本页记录已确认的产品行为;官方深度探索实现及D1–D9限定验收已完成。当前证据与限制统一见验收追踪,整个同步功能的剩余事项见任务清单。既有采集、更新、审核流程继续遵循原规格。
已确认的产品边界
- 提供官方内置的深度探索方式,部署后默认关闭,管理员首次启用后持续自动执行,不增加“执行一次”按钮。
- 关闭深度探索停止该途径的新仓库发现;已登记的有效仓库继续按来源设置更新。精选仓库及自定义搜索规则由自己的启停设置控制。
- 后台仅提供启停、资源预算档位和排除项;查询集合、渠道搭配、分页和补漏节奏由系统维护。自定义搜索规则保留为独立补充入口。
- 深度探索开关不是所有 GitHub 同步的总开关。其预算仍受部署额度、候选容量和采集准入约束。
- 首期仅平台管理员配置官方深度探索,目标为公共
@githubnamespace;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与验收追踪。代码搜索继续保留为备选;未来若启用,仍需验证完整包有效性、内容重复率及对应额度合同。长期公网稳定性和全站召回率未由小样本试验证明。
设计约束
- 不新增必须由用户理解或操作的“轮次”对象。
- 不把更多命中等同于更多有效技能,不把搜索完成等同于 GitHub 全量覆盖。
- 首期渠道、预算和调度参数按当前设计合同执行;代码搜索保持备选,不自动扩展首期范围。
- 执行合同及实现状态见 deep-discovery-design.md、API 文档及 tasks.md;不能仅据需求描述推断任意部署环境已通过验收。