基础使用

本页介绍从登录到日常整理的完整流程。分类注册表和 AI 任务属于高级功能，分别参阅分类与正式注册表和AI 智能分类。

1. 登录与会话

打开生产应用后点击“使用 GitHub 登录”。浏览器会：

1. 生成随机 state 和 PKCE verifier；
2. 跳转 GitHub OAuth 授权页；
3. 回到 StarHub 根路径；
4. 由 Cloudflare OAuth API 在服务端兑换 GitHub Token；
5. 把 Token 保存到当前标签页的 sessionStorage。

会话从创建起最长保留 12 小时。关闭标签页、浏览器清理会话数据、主动退出或跨标签页收到退出通知后，需要重新登录。

TIP

StarHub 会申请读取 Stars 所需权限。取消 Star 还要求 token 具备相应 GitHub scope；权限不足时界面会说明而不是伪装成功。

截图待补：OAuth 登录流程 展示登录按钮、GitHub 授权页和登录后的同步状态；截图必须隐藏 URL 中可能出现的临时 code/state。

2. 首次同步

登录成功后 StarHub 自动分页读取 Stars。顶部会显示同步进度，例如“同步中（9500 个仓库）”。

同步采用权威快照：

• 第 1 页用于确认总页数；
• 后续页面按小并发批次获取；
• 所有页面成功后，才在单一事务中替换 repos；
• 部分失败、网络中断、取消或超时会保留上一次完整快照；
• 已取消 Star 的仓库会从本地快照移除，同时清理对应分类关系和重点标记。

不要在同步进行中反复刷新。仓库很多时，首次同步取决于 GitHub API 速率限制和网络延迟。

3. 主界面区域

顶部栏

• 当前同步状态和仓库数量；
• 全局搜索框；
• 文档、主题与用户入口；
• 设置和退出登录。

左侧栏

• 全部仓库：当前本地完整快照；
• 重点项目：独立重点标记；
• 未分类：当前没有任何 repoTags 关系的仓库；
• 分类：分类列表与每类仓库数量；
• 语言：根据仓库主语言生成的筛选列表；
• AI 分类按钮：创建或打开实验性分类任务；
• 新建分类：创建普通分类。

“未分类”目前表示没有任何普通或正式分类关系，不等同于未来 D2 规划中的“没有正式分类”智能队列。

仓库列表

仓库卡片展示名称、描述、语言、更新时间、Star、Fork 和分类摘要。列表头提供：

• 选择模式；
• 完整集合排序；
• 升序/降序；
• 50、100、200、500、1000 条分页；
• 批量分类和批量重点标记。

排序在分页前作用于完整筛选结果，不是只重排当前页。

详情面板

点击仓库后，右侧显示：

• 仓库名称、描述和关闭按钮；
• 标记重点、打开 GitHub、取消 Star；
• About 网站和 GitHub Pages；
• 语言、Star、Fork、许可证、更新时间；
• 当前分类编辑；
• README 预览。

快速切换仓库时，StarHub 会取消前一个 README 和 Pages 请求，并忽略晚到的旧响应。

截图待补：主界面标注图 使用编号标出顶部栏、分类栏、仓库列表、批量工具、分页和详情面板。

4. 搜索、筛选与排序

搜索会匹配仓库名称、完整名称、描述和语言，并与左侧语言、分类、未分类或重点筛选共同作用。

排序字段：

字段	升序含义	降序含义
重点优先	较早标记优先	最近标记优先
更新时间	较旧更新优先	最近更新优先
Star 数	少到多	多到少
创建时间	较早创建优先	最近创建优先
项目名称	A–Z	Z–A

详细规则见搜索与筛选。

5. 重点项目

重点项目用于标记需要经常回看的仓库，不创建新的分类关系。

单个标记

打开仓库详情，点击“标记重点”；再次点击即可取消。

批量标记

1. 点击仓库列表顶部“选择”；
2. 勾选当前页仓库；
3. 打开“重点项目”下拉菜单；
4. 选择批量标记或取消。

查看和排序

点击左侧“重点项目”只显示重点仓库，也可以选择“重点优先”排序。重点数据随备份 v4 导出。

截图待补：重点项目 展示详情按钮、左侧筛选和批量菜单三个入口。

6. 普通分类与批量操作

创建普通分类

点击左侧分类标题后的“+”，填写名称、颜色和可选 Emoji。普通分类适合临时或轻量整理；需要稳定 ID、别名和 AI 边界时应使用正式注册表。

单仓库编辑

在详情面板选择或移除分类。一个仓库可以属于多个分类。

批量添加或替换

1. 进入选择模式；
2. 勾选当前页仓库；
3. 点击批量分类；
4. 选择“添加”或“设置/替换”语义；
5. 确认后按仓库串行提交。

如果部分失败，失败仓库保持选中，可直接重试。选择替换模式但不选择任何分类会清空所选仓库的分类，界面会再次确认。

7. 取消 Star

点击详情摘要卡片中的“取消 Star”。成功后：

• GitHub 端取消 Star；
• 本地仓库立即移除；
• 对应分类关系和重点标记清理；
• 当前详情关闭；
• 分页自动调整。

后台同步进行时，操作会先取消当前同步，避免旧快照把仓库重新写回。

8. 设置页

设置页包括：

• 分类预设编辑和同步到实际分类；
• AI 服务商、Key、API 地址、模型、批次和连接测试；
• 导出、导入、检查数据库和清空全部数据；
• 各 AI 服务商申请入口。

分类预设是帮助创建分类的模板，不等同于正式注册表。正式注册表由主页“分类工具 → 导入分类”管理。

9. 推荐的日常流程

1. 登录并等待完整同步；
2. 先备份旧数据；
3. 创建普通分类或导入正式注册表；
4. 使用 100–200 个随机样本测试 AI；
5. 人工审核，疑难项再读取 README；
6. 分段写入并抽查；
7. 对需要持续关注的仓库标记重点；
8. 定期导出备份。

下一步

• 搜索与筛选
• 分类与正式注册表
• AI 智能分类
• 数据管理