Github-Star-Manager/README.zh-CN.md

Star Manager

English README

Star Manager 是一个本地优先（local-first）的 Web 应用，用于整理你的 GitHub Star 仓库与 Star Lists，并支持可选的 LLM 辅助分类。

为什么使用 Star Manager

当 Star 仓库数量变多后，手工维护列表效率低且容易不一致。Star Manager 可以帮助你：

• 从 GitHub 同步 Star 仓库与 Star Lists。
• 使用 OpenAI 兼容接口批量分类仓库。
• 在写回前查看变更差异预览。
• 将更新写回 GitHub，并查看进度与失败原因。
• 将工作数据保存在浏览器本地（Dexie + IndexedDB）。

核心能力

• GitHub 同步与进度反馈：
  • 拉取 Star 仓库与 Star Lists。
  • 扫描列表成员关系。
  • 失败列表支持重试。
• 分类流程：
  • 两阶段分类（仓库打标 + 标签压缩）。
  • 支持测试模式（小样本）与单标签严格模式。
  • 支持与现有 Star Lists 或历史分类运行结果对比。
• 写回流程：
  • 应用前预览仓库 Current 与 After 列表差异。
  • 写回时可自动创建缺失列表。
  • 支持“应用前重新规划”开关。
  • 对未 Star 仓库提供确认逻辑。
• 本地编辑：
  • 支持在 UI 中为单个仓库手动调整列表归属。
• 国际化：
  • 支持中英 UI，自动识别浏览器语言，也可手动覆盖。

运行前准备

• Node.js 20+（建议 LTS）
• pnpm
• GitHub Personal Access Token（PAT）
• 可选：OpenAI 兼容的 LLM 服务端点（用于分类）

快速开始

pnpm install
pnpm dev

构建与预览：

pnpm build
pnpm preview

配置说明

1）GitHub PAT

在应用中：

1. 打开 Settings 或 Connect PAT。
2. 粘贴 PAT。
3. 校验并保存。

该 PAT 需要能够读取你的 Star 仓库，并具备对应 Star Lists 操作能力。若校验失败，请优先检查 token 权限范围与账号功能可用性。

2）LLM（可选）

在 Settings -> LLM Configuration 中配置：

• baseUrl（默认：https://api.openai.com/v1）
• apiKey
• model（默认：gpt-4o-mini）
• temperature
• maxTokens

可以直接使用默认 Prompt，也可以按需自定义：

• 默认打标模式
• 严格单标签模式
• 基于 Existing Lists 的约束模式
• 中英文 Prompt 变体

使用指南

第一步：获取 GitHub Personal Access Token

1. 访问 https://github.com/settings/tokens。
2. 点击 Generate new token → Generate new token (classic)。
3. 填写一个描述性名称（如 star-manager）。
4. 授予以下权限范围：
   • repo — 勾选 repo 下的所有权限
   • user — 勾选 user 下的所有权限
5. 点击 Generate token 并复制生成的 Token。

获取 Token 后，打开应用并点击 Sync Star Lists，验证 Token 是否正常工作、能否成功同步你的 Star 仓库列表。

第二步：配置应用

GitHub Token

1. 打开应用的 Settings 页面（或点击 Connect PAT）。
2. 粘贴在第一步生成的 Token。
3. 点击 Validate 进行验证并保存。

LLM 配置

1. 在 Settings → LLM Configuration 中填写：
   • Base URL — 你的 OpenAI 兼容 LLM 服务端点地址。
   • API Key — 你的 LLM API 密钥。
   • Model Name — 用于分类的模型名称。
2. 点击 Run Classification 开始分类流程。
3. 建议先使用 测试模式（Test Mode） 运行小样本，确认模型工作正常后再处理全部仓库。

第三步：应用更新至 GitHub

1. 分类完成后，查看差异预览（Diff Preview）。
2. 点击 Apply Updates，将分类结果（Star List 分配）推送到你的 GitHub 账号。
3. 应用会自动创建缺失的 Star Lists，并更新仓库的列表归属关系。

项目结构

src/app/
  App.tsx                 # 主界面
  core/                   # 用例与编排逻辑
  services/               # GitHub / LLM 客户端
  data/                   # Dexie 数据层与响应式查询辅助
  store/                  # 偏好设置与 LLM 配置存储
  ui/                     # UI 组件与弹窗
  i18n/                   # 国际化资源与语言处理
  styles/                 # 样式文件

数据与隐私

• 本地优先存储：
  • 应用数据保存在浏览器 IndexedDB（数据库名：star-manager）。
  • 偏好设置与 LLM 配置保存在浏览器 localStorage。
• PAT 与 LLM API Key 存储在本地浏览器环境中。
• 应用直接从前端调用 GitHub 与你配置的 LLM 服务。
• 请避免导出或分享包含敏感字段的浏览器存储数据。

常见问题排查

• Star Lists API not available for this token/account
  • 当前账号或 token 可能无法访问 Star Lists 的 GraphQL 字段。
• PAT 校验失败
  • 请检查 token 内容、权限范围，必要时重新生成。
• LLM 测试或分类失败
  • 检查 baseUrl、apiKey、model 以及 /chat/completions 兼容性。
• 同步后没有仓库
  • 确认账号确实有 Star 仓库，并检查同步流程是否完成。

已知限制与路线图

短期规划包括：

• 增量同步，减少重复拉取与重复计算。
• 更完善的速率限制与失败恢复策略。
• 更清晰的错误归因（权限、Token、网络）。
• README 缓存策略落地（ETag/hash 与截断规则）。
• 当前尚未配置 lint / test 脚本。

贡献

欢迎提交 Issue 和 PR。对于较大改动，建议先通过 Issue 讨论范围与方案。

本地常用命令：

pnpm dev
pnpm build
pnpm preview

许可证

AGPL-3.0 license