# 官方 GitHub 深度探索接口增量(D2) > V119统一管理补充:平台全部任务现在还要求 `platform-pause/v1`。当前Go声明四项官方能力加平台暂停能力,缺少后者的旧实例不能领取 `@github` 任务,也不显示为兼容实例。TEAM规则不变。管理员入口合并至“技能同步 → 采集配置”,详见[统一管理接口](github-sync-admin.md#统一技能同步管理)。 管理端机器可读合同见 [管理 OpenAPI](github-deep-discovery.openapi.yaml),Java–Go见 [内部 OpenAPI](github-sync-internal.openapi.yaml)。本文固定当前协议;验证入口和限制见[验证说明](../../openspec/changes/add-github-skill-sync/verification.md)。 正式行为以 [需求](../../openspec/changes/add-github-skill-sync/deep-discovery.md)、[设计](../../openspec/changes/add-github-skill-sync/deep-discovery-design.md) 为准。本文固定字段与交互合同,物理表、索引与迁移见同一 OpenSpec 下的[持久化设计](../../openspec/changes/add-github-skill-sync/deep-discovery-storage.md)。 ## 1. 已核对的实现基线 | 代码 | 当前事实 | D2 增量 | | --- | --- | --- | | `server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/AdminGithubSyncController.java` | `/api/v1/admin/github-sync`,`SUPER_ADMIN`,已有来源/运行/水位/周期接口 | 独立AdminGithubDeepDiscoveryController已实现配置GET/PUT与六个读模型接口,并完成受控HTTP验证 | | `server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/ApiResponse.java`、`PageResponse.java` | `code/msg/data/timestamp/requestId`,成功 code=0;分页 `items/total/page/size` | 保持包装,分页增加 `asOf` | | `server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/GithubSyncInternalController.java` | claim已扩展可选capabilities并按持久能力过滤;官方响应与legacy互斥;官方批次与仓库控制已接线 | 增加能力过滤、独立官方快照和出处;202不变 | | `github-sync-go/internal/controlplane/client.go` | Go生产工作池声明四项官方能力,执行官方客户端与循环 | 启用前全部Java/Go升级;实例能力心跳已持久化并验证 | | `server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/GithubSyncWorkerHeartbeatController.java`、`repository/GithubSyncWorkerPresenceRepository.java` | 保留legacy全局联系时间,同时保存实例ID、协议与能力 | 官方在线判定使用实例能力和最近联系;心跳不证明业务正在推进 | Web SDK 已从当前 Java 运行时 `/v3/api-docs` 生成。管理页面使用生成类型;Go wire 类型与内部合同保持同步。受控集成验证不替代真实 GitHub 搜索效果对照,完整边界见[验证说明](../../openspec/changes/add-github-skill-sync/verification.md)。 ## 2. 管理端路径与授权 共同前缀:`/api/v1/admin/github-sync/deep-discovery`。所有读写仅 `SUPER_ADMIN`,范围固定为公共 `@github`,不接受客户端指定 namespace。写入沿用会话、CSRF 与审计;记录用户字符串 ID、配置版本及规范化差异。响应 `Cache-Control: no-store`,不包含凭证、租约、上传票据、原始查询响应或异常正文。 | 方法 | 相对路径 | data及实施状态 | | --- | --- | --- | | GET | `/configuration` | 当前启停、预算、排除项及version;已实现,隔离HTTP验证通过 | | PUT | `/configuration` | 整体保存后的配置;请求含expectedVersion;已实现,隔离HTTP验证通过 | | GET | `/summary?from=...&until=...` | 近期成果、当前积压、联系状态、等待原因、最多5个近期runId | | GET | `/progress` | 当前策略各渠道的持久分片计数、最近业务进度和额度观测 | | GET | `/repositories` | 仓库摘要分页 | | GET | `/repositories/{repositoryId}` | 按需详情及关联sourceId/runId | | GET | `/repositories/{repositoryId}/provenance` | 出处分页 | | GET | `/repositories/{repositoryId}/paths` | 最近逐路径结果及Skill/version/review ID分页 | 没有“执行一次”接口。既有 `/runs/{runId}` 及其 `/tasks`、`/paths` 继续承担运行详情;本次不另造运行对象。历史清理后的关联runId可失效,详情返回404时页面提示历史已清理。导航使用现有权限校验,不能拼造未经实现的前端路由。 错误沿用 `ApiResponse` 数值 code,HTTP 400 为参数不合法,401未登录,403权限或CSRF不满足,404目标不在可见官方范围,409配置版本冲突。当前配置接口沿用GlobalExceptionHandler,以HTTP状态码作为数值code;配置冲突使用DomainConflictException及本地化消息。前端不得匹配翻译后的msg。 ## 3. 配置并发、排除与预算 V108迁移持久初始化 `version=1, enabled=false, budgetProfile=BALANCED, exclusions=[], strategyVersion=null, updatedBy=null`;strategyVersion在官方目录调度首次事务对账后设为已交付目录的真实版本;这表示目录已装载,不表示结果接收/执行链路完成。三个预算档位是 `ECONOMY/BALANCED/ACCELERATED`。这些值仅命名档位,当前预约节奏以预算设计为准,部署方仍须结合实际额度校准,不能把加速理解为绕过水位或删除探索渠道。 PUT 请求例(示意数据): ```json {"expectedVersion":1,"enabled":true,"budgetProfile":"BALANCED","exclusions":[{"kind":"OWNER","value":"example"},{"kind":"REPOSITORY","value":"sample/skills"}]} ``` 在同一事务中比较 expectedVersion 与当前 version;相同且有效则保存并递增 version,过期则409且不写任何字段。即便重复相同内容也先比较版本,不静默覆盖其他管理员操作。客户端重新读取并让管理员确认合并,不自动重试旧表单。官方策略升级只更新 strategyVersion,不能覆盖启停、预算和排除项;管理员配置的实际保存才递增version,策略版本单独演进;运行任务同时记录两者。 排除项最多1000条,OWNER 为登录名,REPOSITORY 为 `owner/name`;按合法 GitHub 坐标格式校验、统一大小写并去重,拒绝URL、通配符与查询语法。规范化后整体替换;返回规范化列表。排除按本次已核实的当前坐标匹配,不承诺旧名字跟随改名或转移。 调度语义:关闭/排除停止官方新发现及官方独占未登记候选的后续采集,保留候选、出处、进度。已登记来源按自身设置继续;其他独立启用入口需要的候选继续。取消排除或重开自动续排,不能复活已失效的租约。 ## 4. 有界列表与按需详情 - 沿用 `page=0,size=20`;size为1–100,page为0–1000,且 `page*size<=100000`。超出返回400,提示缩小筛选;上限是合同防护,不是深分页性能已达标的证明。默认全部状态,服务端支持 q(owner/name,最长200)、status、channel、paused,多个条件取交集。 - 仓库按 `(firstDiscoveredAt DESC, candidateId DESC)` 稳定排序,firstDiscoveredAt为候选全局首次发现时间;candidateId为本地候选ID,详情仍按稳定repositoryId定位。首次缺省asOf使用服务器时间,后续沿用响应asOf,仅纳入 `firstDiscoveredAt<=asOf` 的候选。出处按 `(lastSeenAt DESC,id DESC)`、路径按 `(skillPath ASC)`,均继续分页。 - asOf是插入截止时间,**不是历史一致性快照**:已有记录的状态、排序时间与过滤条件仍可能变化,跨页可发生移动。客户端固定当前显示页,提示有新数据后手动刷新,禁止轮询自动重排;一致性快照或游标迁移要依据D3执行计划/规模测量另行收敛,不能暗示当前设计消除了页间漂移。 - total仅统计同过滤范围,不在每页重新计算业务成果聚合;实施时采用匹配索引和受限计数/缓存策略,缓存窗口须公开在观测时间中。所有列表最多100项,详情只含摘要;出处、路径、正文、日志不一起打包。 - progress最多3个默认渠道、100项额度观测;若主体超过上限,`quotaObservationsTruncated=true`,不得把截断后列表当完整额度池。等待项每组最多32项;同原因/工作类别合并。 - 关闭抽屉保留筛选与位置;页面离开或隐藏时停止轮询,请求不叠加。每次返回observedAt,asOf和observedAt作用不同。 ## 5. 成果、积压与等待口径 近期区间 `[from,until)`,UTC时间,最长90天,from