# 官方深度探索增量设计 状态:本增量实现与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`验证;这些受控测试不等于旧二进制部署混跑验收。完整部署升级、历史数据兼容、混跑防护和回退操作须针对交付提交验收。