mirror of
https://github.com/iflytek/skillhub.git
synced 2026-11-16 09:21:18 +00:00
103 lines
10 KiB
Markdown
103 lines
10 KiB
Markdown
# 技能同步统一管理入口
|
||
|
||
本文记录已确认的统一管理产品决策。正式任务见 [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),不将产品确认或局部验证表述为全部场景通过。
|