StarHub

Appearance

后续路线图与维护者接手说明 ​

更新时间：2026-08-04

1. 接手时先建立基线 ​

bash
git switch main
git pull --ff-only
npm ci
npm run check

随后阅读：

  1. 项目状态；
  2. 架构与数据流；
  3. 数据管理；
  4. AI 分类审计；
  5. 本文各阶段的完成定义。

生产是否为最新版本，以 /StarHub/deployment-info.json 的提交 SHA 为准。不要根据本地分支名或旧 PR 文档推断。

2. 绝不能破坏的系统不变量 ​

  1. repoTags 是仓库—分类关系唯一事实来源；
  2. 分类安全重命名不改变稳定 ID；
  3. 合并、备份导入和批量 AI 写入使用事务与 dataMutationQueue；
  4. AI 不能创建分类名称或 category ID，只能选任务注册表；
  5. 未通过 Schema、批次 ID 和注册表版本校验的输出不得写库；
  6. GitHub Client Secret 永远只在服务端 Secret；GitHub token 和 AI Key 不进备份；
  7. 产品面向所有用户，不把维护者个人分类表设为默认真理；
  8. 重点标记独立于分类和 AI；
  9. 新持久表必须同时进入清空、导入、备份策略、升级、测试和文档；
  10. 规划功能必须明确标为规划，不能写成已上线。

3. P0 热修：统一数据清理语义 ​

这是下一位维护者最先完成的任务，先于 D2。

当前问题 ​

完整备份导入和设置页“清空全部数据”会处理 repos、tags、repoTags、重点标记和迁移快照，但没有同步清除：

  • classificationTasks；
  • classificationTaskItems；
  • classificationReadmeCache。

实施目标 ​

  • 提取单一 clearApplicationData() 或等价数据库服务；
  • 明确两种模式：清空全部、只清理 AI 历史/缓存；
  • 完整备份导入在同一受控流程中清除与新数据不兼容的任务；
  • 清理期间禁止新的同步、分类或迁移写入；
  • 失败时保留原数据或明确恢复备份，不留下半清理；
  • 设置页显示将被清除的范围和不可恢复警告；
  • 中英文文案、单元测试、数据文档和变更日志同步更新。

验收 ​

  • 8 张表清空后的数量符合所选模式；
  • 导入新备份后看不到旧任务和旧 README 缓存；
  • sessionStorage 的 GitHub/AI 凭据是否保留由明确选项决定，不隐式处理；
  • 失败注入测试证明无半写入状态；
  • 大数据量清理有进度或至少不会让 UI 假死。

4. D2：未分类仓库批量处理与持续分类 ​

目标不是再次运行一次“全量任务”，而是建立持续增量工作流。

D2-A 队列规划与可解释范围 ​

  • 定义待处理为“无任何关系”“无正式分类”“低置信度待复核”等不同队列，避免一个“未分类”概念混用；
  • 用户可按同步时间、语言、Stars、重点标记和随机抽样选择范围；
  • 创建前预览仓库数、预计批次、粗略 token、README 候选上限和注册表版本；
  • 已在活动任务、已提交或已忽略的仓库不重复入队；
  • 用纯函数与单元测试先实现队列规划，再接 UI。

D2-B 持续增量 ​

  • 同步完成后只把新且未分类的 Stars 加入候选，不自动调用 AI；
  • 用户确认后创建新任务；
  • 保存上次处理水位和忽略原因；
  • 支持只重试失败、只处理新仓库和手工加入队列；
  • 旧任务注册表版本失效时提示创建新任务，不静默迁移结果。

D2-C README 二阶段收口 ​

  • 候选策略维持“低置信度或人工标错”，允许用户手动加入；
  • 显示缓存命中、GitHub 请求数、输入字符、token 和费用估计；
  • 404、超大 README、非文本内容、GitHub 限流分别记录；
  • 增强后保留原结果与差异，允许回退第一轮；
  • 设置缓存过期与显式清理入口。

D2 验收 ​

  • 17k 级数据不会重复处理已分类仓库；
  • 关闭页面后可恢复任务与分段；
  • 任意失败都能定位到仓库和原因；
  • 新同步仓库不会未经同意自动花费 AI token；
  • 提交当前结果后任务结束，剩余仓库通过新任务继续；
  • 注册表外 category ID 始终被拒绝。

5. D3：评测、成本与模型适配 ​

人工金标准 ​

  • 建立 200–500 个经人工确认的通用测试集；
  • 数据分层覆盖语言生态、Web、AI/ML、GIS/遥感、DevOps、文档、交叉领域和信息不足项目；
  • 分类 ID 与正式测试注册表版本绑定；
  • 私有或个人数据不得提交公共仓库。

指标 ​

text
Accuracy / Macro-F1
未分类率 / 低置信度率
未知或无效输出率
第一轮与 README 增强的增益
人工修改率与主要混淆对
输入/输出 Token、费用和耗时
失败、重试与取消比例

界面与 README 不应在没有可复现评测时承诺固定“95% 准确率”。

供应商适配 ​

  • 能力表区分严格 JSON Schema、JSON object 和普通文本；
  • 推荐模型、参数名和验证日期独立配置；
  • 自定义模型 ID 保留，但连接测试不自动持久化 Key；
  • 供应商错误规范化为限流、超时、认证、上下文和输出校验类别；
  • 模型列表变化不要求数据库迁移。
  • 为 sessionStorage 中的 AI Key 增加独立创建时间与过期校验；迁移时只保留当前会话有效 Key，不再依赖标签页是否关闭。

6. D4：可靠性、可观测性与性能 ​

  • 为同步、详情 README、AI 请求和写入建立统一取消/超时/重试策略；
  • 任务事件日志仅存安全元数据，不存 Key、token 或完整敏感内容；
  • 增加存储用量、缓存用量和任务历史清理界面；
  • 17k、50k 仓库数据基准：首次加载、搜索、排序、分页、分类计数与迁移；
  • 限制大型 DOM、深度响应式对象和重复全表扫描；
  • 增加浏览器性能回归方案和异常 README 样本；
  • 对多标签页写入增加明确的锁或只读提示。

7. D5：产品完成度、国际化与发布 ​

  • 审计全部用户可见字符串、aria-label、错误兜底和日期/数字格式；
  • 新版桌面和窄屏截图，覆盖登录、首页、详情、分类治理、AI 审核、README 增强、重点标记和设置；
  • 补充键盘操作、焦点管理、对比度和屏幕阅读器测试；
  • 定义版本号、release notes、备份兼容矩阵和数据库升级说明；
  • 评估是否启用 PWA；未完成离线数据策略前保持禁用；
  • 跨设备同步与团队协作单独设计威胁模型、冲突模型和隐私政策，不能直接复用 OAuth Function。

8. 文档维护规范 ​

每批变更至少更新：

  • 对应用户指南；
  • README.md 与必要的 README.en.md；
  • docs/CHANGELOG.md；
  • PROJECT_STATUS.md 的完成项或限制；
  • 本文的后续状态；
  • 数据、部署或排障文档（如行为受影响）；
  • 中英文 UI 文案。

截图可以暂缺，但必须留下明确占位：入口、状态、数据量和验收内容。详见文档维护规范。

9. 每个 PR 的完成定义 ​

  • 功能范围小且可独立回滚；
  • 数据迁移有旧数据测试与失败测试；
  • npm run check 全部通过；
  • PR 描述含数据影响、安全影响、人工步骤和截图；
  • 中英文主流程一致；
  • 合并后 main CI、Pages 部署和公网验证通过；
  • deployment-info.json 指向合并提交；
  • 文档分别写清“本批已完成、未完成、后续接手点”。

10. 建议执行顺序 ​

text
P0 AI 历史表清理一致性
→ D2-A 队列定义与预览
→ D2-B 新仓库持续分类
→ D2-C README 增强收口
→ D3 人工评测与供应商能力表
→ D4 性能、配额与可观测性
→ D5 国际化、无障碍、截图和正式发布

若资源有限，优先级始终是：数据不丢失 > AI 不越权 > 任务可恢复 > 部署可验证 > 性能与视觉完善。

基于 MIT 许可发布

Copyright © 2024–2026 StarHub