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

103 lines
10 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.

# 技能同步统一管理入口
本文记录已确认的统一管理产品决策。正式任务见 [tasks.md](tasks.md) 的 U 节,领域术语见 [glossary.md](glossary.md),验证入口见 [verification.md](verification.md)。
## 1. 目标与范围
平台管理员只面对一个「技能同步」入口,以少量配置使系统持续发现、采集及更新公开GitHub技能,并能查看结果、定位异常和进入独立同步审核队列。自动探索属于采集方式,不再作为另一套并列产品。
本轮包含前端页面整合、统一仓库服务端查询、平台采集安全暂停/恢复,以及必要的Java/Go协议和文档调整。不改变审核发布规则、namespace归属、TEAM权限、公开仓库限制和现有来源调度策略。没有确认任何新增托管平台、自动发布、一次性探索按钮或全站召回承诺。
## 2. 页面框架
固定标题「技能同步」,说明当前来源为GitHub;顶部提供「采集配置」「系统设置」入口。日常只有三个页签:
| 页签 | 默认内容 | 详情与操作 |
|---|---|---|
| 概览 | 平台采集状态、Go在线状态、已登记仓库/待验证线索/未解决同步项、需要处理的问题、最近活动 | 暂停/恢复平台采集;问题直达相关配置;活动直达运行详情;未解决项入口直达既有同步审核队列,并说明数量还包含阻塞等未解决状态 |
| 仓库 | 全部发现方式、全部处理状态的统一分页列表 | 按发现方式及处理状态筛选;仓库详情抽屉展示出处、检查/采集结果、技能状态和对应运行/审核链接 |
| 运行记录 | 真实运行按时间排序的统一列表 | 显示工作类型、目标、状态、结果摘要和创建时间;支持类型/状态筛选;查询、分页、任务及错误细节按需展开 |
概览以运行情况及需要处理的问题为主,不堆积空卡片和默认展开的渠道图表。正常时明确显示运行正常;额度冷却等可自动恢复状态说明等待原因及可靠的预计时间,不一律标为需要人工修复。Go离线、平台手动暂停、容量暂停和GitHub额度等待分别展示,不相互冒充。
运行记录中的发现仓库、检查更新、采集技能应从真实run/task语义映射,不能虚构全站探索轮次,也不能把一个包含多个阶段的真实运行拆成多条假记录。多任务运行的主类型及详情展示按[接口合同](unified-admin-contract.md)执行。
## 3. 采集配置和首次准备
采集配置以抽屉打开,突出两个常用入口:
- 自动探索:状态、简短成果及启停,渠道进度折叠查看;配置表单保留预算档位、排除项,系统维护查询和补漏策略。
- 指定仓库:已添加目标及「添加仓库」。只要求GitHub仓库URL或owner/repo,目标固定@github;复用已有周期、忽略和容量策略,不重复填写。
指定账号、自定义搜索规则放入「其他采集方式」按需展开,保留已有能力,不拆成普通/高级两套配置。系统设置抽屉维护凭证、水位及调度等公共配置;同一配置只有一处维护入口。复杂内容在抽屉中分区,不堆入单一大弹窗。
首次进入显示基于真实状态的准备清单:采集服务、容量配置、可选凭证、是否有启用的采集方式。缺项直达具体设置,已配置项无需重复填写,完成后清单收起;无凭证可以匿名运行,需说明额度限制,不能直接算错误。不强制向导,不擅自启用探索,不以自动填入未经确认的水位代替配置。
添加仓库保存后由系统自动安排检查,不保证瞬间执行。平台暂停时可以保存,并显示等待平台采集恢复。重复添加关联同一仓库并展示既有状态,不能重复创建或擅自恢复暂停状态。详情只提供实际支持的单仓库设置,不把未实现的逐仓库周期配置说成现有能力。
## 4. 统一仓库模型与查询
「指定仓库」取代产品文案中的「精选仓库」,表示管理员主动选择,不表示质量认证;既有CURATED_REPOSITORY协议值不因文案更名盲目调整。
自动探索搜索命中先作为待验证线索,管理员指定的仓库可先登记正式来源再扫描。两者进入采集后共用包获取、校验、扫描、审核及后续更新流程。发现方式与处理状态分别表达,仓库登记不等于存在有效Skill或已经发布。
同namespace内按稳定repository ID关联候选与正式来源,一仓库一行并保留全部命中出处;不同namespace仍独立。列表默认每页20,服务端完成筛选、排序、去重、total和分页,不在浏览器拼接两套分页结果。现有官方探索查询限定官方出处,不能直接作为统一列表使用;须覆盖指定仓库、指定账号、自定义规则及官方探索的适用数据。尚未解析repository ID的指定入口状态应能在配置中看见,不应伪造统一仓库身份。
统一查询的字段、稳定排序及关联边界见接口合同;SQL与HTTP性能须在交付验收中测量,不能仅以分页字段存在推断性能。
## 5. 平台采集安全暂停
按钮固定为「暂停平台采集/恢复平台采集」,仅超级管理员操作,只影响平台@github,TEAM不受此开关控制。TEAM仍受原有共享额度和容量规则约束,不能据此承诺资源完全隔离。
- 暂停后停止领取新的平台发现、检查和下载任务。
- 在途采集到安全检查点停止并持久保存进度,不等待整个大仓库完成。
- 已上传并被Java接收的包继续校验、扫描及进入待审;人工审核与已发布技能使用不受影响。
- 展示暂停中与已暂停,不能保存控制字段后立即伪称所有worker停止。
- 恢复从原进度继续,不启用原本独立停用的入口或来源。
决策理由:管理员需要一个控制平台采集负载的入口,但不应以停止平台服务来影响TEAM,也不应丢弃已接收成果。前端批量关闭入口会破坏原启停意图;Go离线状态、自动探索开关和容量暂停都不具备此语义,因此需要独立的持久控制。
平台控制API及Java/Go协议已实现,暂停时效、租约/离线判定、安全检查点、已接收边界与代际一致性以[接口合同](unified-admin-contract.md)为准。不得仅因数据库状态更新就宣称在途任务已停止。本轮未加入独立仓库暂停按钮。
## 6. 主要使用流程
1. 首次配置:打开概览→查看准备清单→补必要配置→启用自动探索或添加指定仓库→系统自动安排工作。
2. 日常观察:概览确认运行/等待原因→仓库看结果→按需进入运行或审核,不必逐一阅读任务技术日志。
3. 指定目标:采集配置→添加仓库→系统显示已保存/等待/检查状态→在统一列表查看同一仓库。
4. 排查异常:问题入口→相关仓库或运行详情→根据真实原因定位配置;自动重试的工作显示恢复条件,不要求反复点击重试。
5. 暂停恢复:暂停平台采集→暂停中→到安全检查点后已暂停→恢复平台采集;TEAM继续原流程,已接收包继续处理。
## 7. 路由、展示及性能约束
保留/dashboard/github-sync主路由,侧栏只有技能同步;sourceId/runId旧深链继续可用。旧/dashboard/github-deep-discovery兼容进入主入口并定位自动探索配置/状态。页签、筛选和必要分页状态支持刷新与前进后退;抽屉跳转详情后返回不丢列表位置。
复用现有色彩token、小尺寸按钮、Radix抽屉/页签和分页组件,不增加无依据的生产依赖。不直接嵌套带整页标题/轮询的旧页面;抽取内容组件,统一路由负责组织。使用已有生成类型和TanStack Query;详情按需读取,隐藏页签或浏览器隐藏时停轮询,同参数查询共享缓存,禁止全量加载仓库/文件。
保留SUPER_ADMIN前后台鉴权及TEAM现有入口,清楚区分空态、无配置、加载失败、离线、限流及容量暂停。更新中英文等现有语言,不仅修改中文菜单。
接口与状态设计见[实施合同](unified-admin-contract.md)。
## 8. 实施与验收顺序
1. 根据已确认产品规则补齐平台暂停与统一仓库查询的接口、持久状态及回退设计;更新现有OpenAPI/MD及spec,不维护另一份正式需求。
2. 实施并验证服务端合同,再接页面抽取、三页签、配置抽屉及旧路由兼容;保留可独立检查的阶段。
3. 验证服务端去重/分页/权限/性能、平台暂停与TEAM隔离、在途安全暂停、重启/租约过期/恢复及已接收包继续处理。
4. 验证1440px/390px和浅深色,首次准备、添加/重复仓库、统一运行列表、错误引导、返回筛选、隐藏页签无多余轮询。区分真实只读与受控接口证据。
5. Web定向/全量测试、typecheck、lint、build,变更服务端的相关及必要扩大回归;OpenSpec严格校验和diff检查。最终构建与集成验收应绑定交付提交。
## 9. 已确认决策索引
| 问题 | 用户选择 | 结论 |
|---|---|---|
| Q1 | A | 概览、仓库、运行记录三个日常页签 |
| Q2 | A | 真实状态准备清单,不强制向导 |
| Q3 | A | 增加统一暂停能力,作用范围由Q6限定 |
| Q4 | A | 指定仓库/添加仓库命名 |
| Q5 | A | 默认全部仓库统一列表,后端分页去重 |
| Q6 | 不包括TEAM | 仅暂停平台@github |
| Q7 | A | 在途安全暂停,已接收包继续,恢复原进度 |
| Q8 | A | 突出自动探索/指定仓库,其他方式按需展开 |
| Q9 | A | 添加仓库仅填地址,沿用策略,重复添加不重建 |
| Q10 | A | 真实运行统一列表,按类型和状态筛选 |
| Q11 | A | 概览以运行情况、简短统计及待处理问题为主 |
原五页签、仅前端整合、全局暂停等早期草案已被以上决定取代。产品决策和技术协议已实施;实际验收范围与未覆盖边界见[验证说明](verification.md),不将产品确认或局部验证表述为全部场景通过。