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

120 lines
16 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限定验收已完成;产品决定见[需求](deep-discovery.md),当前测试范围、资源边界与剩余事项见[验收追踪](verification.md)和[任务清单](tasks.md)。
## 1. 职责与持久状态
Java 保存平台策略配置、策略版本、任务快照、查询检查点、候选与出处、额度观测、租约和重试时间。Go 领取任务快照,执行查询、受限作者扩展、仓库检查与采集并上报。沿用现有任务体系,不新增轮次领域对象,不引入消息队列或 Go 私有任务库。
官方策略为随版本交付的受控查询集合,与管理员自定义规则隔离。平台只配置启停、预算档位、排除项。查询保留稳定标识及版本,记录类型、渠道、频率类别和来源;默认模板不得覆盖自定义条件。部署版本之间的策略格式须可识别,不兼容的 Go 不领取无法执行的任务。
## 2. 搜索执行与覆盖
- 精准仓库线索、生态线索、README 线索分别形成可跟踪查询;宽泛补漏低频执行,不以热门或最低星数作为全部渠道的硬门槛。
- 首次启用、新增查询或扩大查询条件须补搜历史;日常增量保留重叠窗口,低频历史补漏用于索引延迟和仅元数据变化。
- 查询使用固定截止时间与适用范围。每页候选持久化成功后推进检查点;不能因单页失败推进成功边界。
- 单次仓库搜索超过可访问结果上限或返回不完整时,按时间拆分;时间无法继续拆分时尝试适用的次级范围。分片设置工作预算和终止边界,仍不完整则保存缺口并退避,不无限拆分或虚报完成。
- 固定时间窗不等于 GitHub 索引快照;使用重叠与补漏减小翻页漂移,不能承诺全站穷尽。
- 作者扩展只由确认含有效技能的仓库触发,按作者去重并记录复查进度,只自动扩展一层。扩展所得新作者不递归扩散;大型组织分页与其他工作公平分配资源。
- 代码搜索不作为首期默认渠道;单独核实语法、索引边界与额度,不能套用仓库搜索的分片限定词。
### 时间子分片实施约束
Java 持久保存根范围、父子关系、固定策略快照和各子段完成状态;同一长期查询仍只运行一个活动任务,子段顺序领取,不增加管理员操作。Go 提交两个整秒、互不重叠且完整覆盖父段的半开时间范围,Java 在租约事务内核验并交接。父段拆分不推进长期覆盖边界,所有叶子完整完成后才推进根范围的覆盖;缺口、预算暂停和检查点恢复均保留原范围。
首个实现采用最大深度 32、每根最多 126 个子节点的有界初值,根节点加子节点至多 127 个;子任务只获得剩余深度和节点预算,不能递归重置预算。历史窗口横跨多年,过低的拆分深度会让最近的密集区间一直停在多年窗口内,因此深度允许按需细分到秒;节点总数和每任务请求预算分别限制持久工作量和单次执行量。它们是防止工作失控的未校准初值,不是召回保证。不能继续拆分时明确记录缺口;有缺口的叶子退避期间,应允许同根其他待处理叶子执行,不能由单个不可完成区间永久阻塞全部兄弟。根覆盖仍需所有叶子完成。每查询只保留一个未结束根,根完成后的诊断树可在下次新根创建时清理,长期覆盖和出处不删除。策略退休允许已存在根续完,但不新建根。
有缺口的当前执行以 `PARTIAL` 结算,叶子保存缺口原因、检查点与最早重试时间。待处理兄弟优先运行;无待处理兄弟时才重试到期缺口。重试优先复用已终结的原任务,租约代际继续增加,不重复增长任务/运行历史;若原诊断任务已按保留期清理,则从持久叶子恢复。固定查询、策略、范围和截止时间保持不变,仅在新尝试前按根剩余额度收紧分片预算。缺口退避计数不能因任务复用或清理而归零。
### 作者一层扩展
作者使用 GitHub 稳定账号 ID 标识;login 仅为可更新坐标。实际包校验成功后保存仓库与账号的有效种子证据,且必须具有非作者扩展的官方搜索出处才能触发动态作者查询。动态查询按 namespace 与账号 ID 去重,只扩展一层,不因扩展命中的仓库递归扩散;后来独立搜索命中且具真实验证证据的仓库可以成为普通种子。
Go 按稳定 ID 获取当前名称,枚举时逐仓核对 owner ID,末页再次确认名称没有在分页期间变化;若名称变动导致分页不可靠则保存缺口重查,不误报完整。规范名称经首批空回报送到 Java,最新作者排除项据此生效。旧采集器省略 owner ID 时清除无法证明的身份关联,不拼接旧 ID 与新名称。
作者枚举使用公共仓库列表及 CORE 资源,不施加搜索的 pushed 过滤、十页上限或时间二分。正 int32 页码配合单次请求/候选预算保存续页进度;预算至少容纳身份查询、列表页和末页身份复核。作者任务不进入时间分片账本;完成表示本次列表枚举结束,仅安排下一次复查,不推进搜索时间覆盖。查询快照的范围字段仅标识该次执行,不表示列表具有时间一致性快照。缺口按 RETRY_WAIT 保存检查点并退避。
动态作者查询不随静态关键词目录退休;任务额外要求 `official-owner/v1`,不由只声明搜索能力的采集器领取。生产Go工作池现声明完整能力;Java配置保持默认关闭,启用后才领取官方任务。
## 3. 预算、凭证与暂停
复用部署额度、并发、候选容量和包准入上限。节省/均衡/加速调节官方探索可占用的工作预算,不取消任何渠道。调度在保护既有来源更新的同时,给历史补搜和宽泛发现有限但持续的机会。正常预算用尽保存进度并公平续排,不统一延后固定长时间;真正限流按恢复依据延后,候选满与待审容量满分开处理。
凭证按资源类别和可确认的限额主体管理最近观测。不得汇总同主体 token 余额;主体不明时不能承诺额度独立。次级限流按响应退避并收紧共享并发。凭证失效、未知、普通额度耗尽和次级冷却分开记录。凭证池的资源额度观察与下述平台任务预算预约分别执行;平台预约不代表锁定了GitHub侧的可用配额。
主限流持久状态按服务端租约绑定的凭证与资源记录;匿名主限流单独保存,不阻断后来配置的认证凭证。Go进程内保护按token摘要与资源隔离,不保存明文键;同一配置槽更换token不能继承旧token的进程冷却。认证失败仅停用对应凭证,次级限流与额度回报持久化失败仍触发共享保护。不同token可能属于同一GitHub主体,未知主体只允许尝试未确认耗尽的凭证,不累加余额或承诺独立额度。
探索关闭与排除项变更由 Java 在领取和关键接收阶段检查;已登记来源及其他独立入口不被连带暂停。在途操作到可恢复边界结束,已确认上传或接收不删除、不回滚,后续工作暂停;旧租约写入被拒绝。
### 官方探索档位的执行约束(D7a 实施合同)
Java 以一条持久的平台预算记录控制官方发现的领取节奏。首期采用固定份额预约,不新增队列或逐 HTTP 请求许可接口:每次成功领取官方任务,按该快照 `maxRequests` 预约逻辑 API 调用预算,并计算下次最早领取时间。多个 Java/Go 实例共用数据库状态;同一平台最多一个未过期的官方发现租约。旧任务续领、租约过期接管均重新预约,续租不重复预约。
| 档位 | 初始逻辑 API 调用预算/小时 | 10 次请求一份时的最短领取间隔 |
| --- | ---: | ---: |
| 节省 | 60 | 600 秒 |
| 均衡 | 180 | 200 秒 |
| 加速 | 360 | 100 秒 |
这些是经小范围公网试运行后保留的本系统保守初值,不是 GitHub 的额度。12次三档请求成本观察均成功;另一次Java真实领取后的Go发现批次完成9页、816唯一候选,均衡档预留10请求并持久保留200秒间隔。其余档位的预约差异由PostgreSQL回归覆盖;不将短批次结果解释为长期吞吐或召回率保证。没有闲置累积或补发额度,未使用的份额不退款;崩溃和响应丢失不增加可用预算。预约明细按任务保留期随任务清理,平台最早领取时间独立保留,不随任务删除重置。数据库时间为预约依据,进程重启、启停和切换档位不重置既有最早领取时间。档位变更作用于下一份成功预约,在途任务保留原快照与预算;从节省改为加速也可能先等待上一份的剩余间隔。
领取事务按配置、平台预算、任务、凭证的固定锁顺序处理;只有实际可以向 worker 交付的租约才扣份额。凭证不可用、额度冷却或候选容量阻断不能被记成成功预约。官方预算受阻时,其他自定义发现入口仍能领取。预算时间到且无官方在途租约时,优先交付一份官方任务,随后在预算间隔内继续原自定义入口顺序。官方组内按最久未成功领取的查询安排,跨续领和任务替换保留公平性,不因低档位取消 README、宽泛发现或作者渠道。
后台沿用 `BUDGET` 等待原因,最早领取时间仅表示允许 Go 重新领任务;若仍有活跃租约、服务离线、额度或容量受限,则继续等待相应条件。不修改覆盖边界或把正常预算等待标成覆盖缺口。
预算计量范围为官方搜索和作者枚举的逻辑 API 调用,不包含其后仓库 Tree、文件下载、上传,也不精确计量 HTTP 重定向。它约束任务准入速率,不保证逐秒请求均匀;单份内仍可能连续发出最多 `maxRequests` 次调用。已有主额度、共享次级冷却、候选容量和包准入保护继续生效。首期不承诺既有来源更新的绝对 SLA。
## 4. 策略升级与恢复
任务固定策略版本、查询版本与窗口。新任务采用新策略;兼容查询保留检查点,新增或语义改变的查询建立独立历史补搜进度。无法迁移的检查点不能悄悄跳过范围:记录重扫原因,从可证明安全的边界重放并依赖候选去重。旧快照须保留到在途任务结束,升级不得自动开启已停用探索。
Java 存储到期时间,Go 轮询领取后才执行重试。离线时显示等待采集服务而非宣称正在请求 GitHub;租约过期后可接管,同一范围允许重放但不重复生成业务结果。心跳只说明最近联系,不证明任务处理正常;运行详情同时展示最近进度与等待原因。
## 5. 页面和查询性能
当前页面结构以[统一管理方案](unified-admin.md)为准:总览、仓库、运行记录三个页签;自动探索配置与折叠进度在采集配置抽屉中,旧独立探索链接重定向。近期成果与当前积压口径分别保留,最近运行复用现有详情。列表服务端过滤和稳定排序(发现时间加唯一标识),每页 20 条;沿用现有分页方式并实测深分页,必要时改为游标,不提供无界全量接口。抽屉按需查询,历史和路径结果独立分页。
聚合与列表解耦,明确刷新时间,禁止每次翻页重算全部历史。索引根据真实查询计划设计,不能仅靠前端虚拟滚动处理数据库扫描问题。新结果提示刷新,不自动重排;请求取消、超时和隐藏页面停止轮询遵循现有前端模式。
近期成果依据持久事件时间计数:首次发现、首次确认有效、首次成功采集新 Skill;内容更新单独计版本。当前积压按当前状态统计,不与近期时间过滤混用。官方探索带来的候选与其他入口重复命中时,保留归因但同范围去重,不宣称独占贡献。具体统计字段和历史数据缺失处理写入 API 合同。
## 6. 接口变更清单
1. 平台官方探索配置读取与更新,配置版本及权限校验。
2. 概览、渠道覆盖、分页候选、按需候选详情、关联来源和审核导航。
3. 任务快照携带策略/查询身份、兼容版本、查询范围与可恢复进度。
4. 候选回报携带多渠道出处;幂等与进度确认保持一致。
5. 等待反馈区分资源限流、容量、服务联系状态和任务进度。
具体路径、字段与实现状态以 `docs/api/github-deep-discovery.openapi.yaml`、对应 MD 及现有 Java–Go 内部合同为准;Web 类型已从运行时生成,验证入口和边界见 [verification.md](verification.md)。
## 7. 验证矩阵与判定
| 场景 | 必须观察到的结果 |
|---|---|
| 名称无特征、README 有线索 | 新渠道能补回有效仓库,并留下出处 |
| 零星、长期不活跃、多 Skill 仓库 | 不因统一星数门槛遗漏;逐包处理 |
| 作者仓库超过一页 | 完整续页、作者去重、一层扩展有界 |
| 搜索超过上限/结果不完整 | 分片或明确缺口,不虚报全量完成 |
| 多规则重复命中 | 单候选、多出处;不重复版本或待审项 |
| 限流和多 token | 只延后受影响工作,遵守共享主体和次级退避 |
| Go 强停、网络断开、多个实例接管 | 检查点恢复、旧租约拒绝、重复回报幂等 |
| 探索关闭/排除/重开 | 未登记候选暂停续跑,独立来源不受影响 |
| 策略升级 | 配置不被覆盖;新查询补历史;旧任务不混版本 |
| 排除整页命中及批次重放 | 不创建被排除新候选;原请求摘要不变;原ID仍计当前代际预算;成功确认页可前进 |
| 候选转正式来源后再次领取 | 来源自己的启停生效;探索停用/排除不误停来源,HEAD_ONLY可正常执行 |
| 暂停与包验证并发 | 已准入包可结算;新准入被阻止;task/摄入/路径/来源锁顺序无相互等待环 |
| 子分片回报响应丢失及租约接管 | 同一拆分幂等,不重复创建子段;恢复原范围;旧租约不能推进新任务 |
| 多叶子中一个缺口或暂停 | 根覆盖不前进;已完成叶子不重搜;重开后只续未完成工作 |
| 子分片达到深度/节点上限 | 保存明确缺口并有界退避;不递归重置预算、不虚报完成 |
| 审核积压/候选满/资源不足 | 保存进度、按各层保护线暂停,不无限排队 |
| 大候选列表与详情 | 有界响应、稳定分页、无全量前端加载、查询可解释 |
| 新旧策略对照 | 记录请求量、耗时、独有有效仓库与技能数,不以命中数冒充收益 |
小范围试验先固定样本集、资源环境和观察窗口,覆盖上述边界;再采用相同预算对照查询效率、完成范围对照召回收益。规模测试使用分档候选数据量,记录数据库执行计划、接口延迟和浏览器交互;具体阈值需在基线测量后冻结,未达标不宣称性能验收通过。代码搜索需展示独有有效召回及其请求成本,不明显则不纳入默认策略。
建议先固定数据库/Java资源、1k/10k合成候选、多个出处与热仓路径样本,分别记录单请求和8并发的p95、错误率、分页total及查询计划;阈值在本次交付验收前冻结。此基线不构成生产SLA。
## 8. 发布与回退
先发布向后兼容的持久字段和协议,再发布 Go 能力及页面;默认不开启官方探索。试运行通过后管理员启用。出现问题先关闭官方探索保留进度,既有来源继续更新;不通过删除候选、版本或任务历史回退。V112 使用新的分片账本,策略执行代次随之升级,以阻止旧调度器重排新根;这不保证旧 Java 接收路径理解新分片。首次启用官方能力前必须整体完成 Java 与 Go 升级,不支持新旧 Java 混跑处理本次官方任务;早期显式 opt-in 的 Go 也不能继续领取包含 126 个累计子节点预算的新快照。旧客户端的空心跳仍可接收;V119之后平台领取另需 `platform-pause/v1`,无能力声明的legacy领取只沿用TEAM原规则;这与本次官方任务不支持新旧Java混跑是两个边界。官方能力过滤由`GithubOfficialDeepDiscoveryIntegrationTest`验证,策略代次与快照保留由`GithubOfficialRecoveryBoundaryIntegrationTest`验证;这些受控测试不等于旧二进制部署混跑验收。完整部署升级、历史数据兼容、混跑防护和回退操作须针对交付提交验收。