embersparks_obsidian-github-stars-manager/USAGE_GUIDE.md

# GitHub Stars Manager 使用指南

## 目录

- [快速开始](#快速开始)
- [详细功能介绍](#详细功能介绍)
- [高级用法](#高级用法)
- [常见问题](#常见问题)
- [最佳实践](#最佳实践)

## 快速开始

### 第一次使用

1. **安装插件**
   - 从 Obsidian 社区插件商店搜索 "GitHub Stars Manager"
   - 点击安装并启用

2. **配置 GitHub 访问令牌**
   ```
   设置 → 社区插件 → GitHub Stars Manager → GitHub 个人访问令牌 (PAT)
   ```
   - 访问 [GitHub 设置页面](https://github.com/settings/tokens)
   - 创建新的 Classic Token
   - 优先勾选最小权限：读取公开星标仓库通常只需要 `read:user` 和 `public_repo`
   - 只有确实需要访问私有仓库相关数据时，才考虑使用更宽泛的 `repo` 权限
   - 复制令牌到插件设置中

3. **打开插件视图**
   - 点击左侧面板的 🌟 图标
   - 或使用命令面板搜索 "GitHub Stars Manager"

4. **首次同步**
   - 点击工具栏上的"同步"按钮
   - 等待仓库数据加载完成

## 详细功能介绍

### 🔍 搜索与筛选

#### 搜索框功能
- **实时搜索**：输入关键词即时过滤仓库
- **多字段匹配**：搜索仓库名称、描述、语言
- **清除按钮**：鼠标悬停搜索框显示×按钮，快速清空

```
搜索示例：
- "react" - 查找包含 react 的仓库
- "python machine learning" - 查找 Python 机器学习相关项目
- "typescript" - 查找 TypeScript 项目
```

#### 标签筛选
- **点击标签**：激活标签筛选，只显示包含该标签的仓库
- **多标签筛选**：支持同时选择多个标签
- **标签高亮**：搜索匹配的标签会高亮显示
- **清除筛选**：点击"清除全部"按钮移除所有标签筛选

### 📊 排序功能

工具栏提供四种排序方式：

| 图标 | 排序方式 | 说明 |
|------|---------|------|
| 📅 | 最近添加 | 按星标时间排序（最新在前）|
| ⭐ | Star 数量 | 按星标数量排序（数量多在前）|
| 🍴 | Fork 数量 | 按 Fork 数量排序（数量多在前）|
| 🔤 | 字母顺序 | 按仓库名称字母顺序排序 |

**排序方向**：点击当前激活的排序按钮可切换升序/降序

### 🏷️ 标签管理

#### 添加标签
1. 点击仓库卡片右下角的"编辑"按钮
2. 在"标签"字段输入标签名称
3. 多个标签用逗号分隔：`frontend, react, typescript`
4. 点击"保存"

#### 标签自动着色
插件为标签自动分配颜色，支持 12 种预设颜色：
- 蓝色、粉色、青色、绿色、橙色、紫色
- 红色、橙红、亮绿、青蓝、紫蓝、玫红

#### 使用现有标签
编辑仓库时会显示"现有标签"列表，点击快速添加：
```
现有标签示例：
[frontend] [backend] [mobile] [ai/ml] [tool] [library]
```

### 📝 笔记功能

#### 添加仓库笔记
1. 在编辑对话框的"笔记"字段添加个人备注
2. 支持 Markdown 格式
3. 可记录：
   - 使用体验
   - 重要功能点
   - 个人评价
   - 学习计划

#### 关联 Obsidian 笔记
1. 点击"链接笔记"按钮
2. 搜索并选择现有笔记文件
3. 建立双向关联：
   - 仓库卡片显示关联笔记链接
   - 笔记中可回跳到仓库

### 🎨 界面布局

插件使用一套稳定一致的界面样式，并跟随 Obsidian 当前外观；插件内不再提供独立的主题切换按钮。

#### 卡片布局
- 简洁的 Obsidian 原生卡片样式
- 响应式瀑布流布局
- 支持浅色和深色外观
- 适合快速浏览大量仓库

#### 交互优化
- 工具栏集中放置同步、搜索、账号筛选、统计和标签筛选能力
- 标签芯片支持快速筛选和管理
- 仓库卡片显示头像、标签、笔记、链接、星标数、分叉数和更新时间等信息
- 悬停反馈清晰，减少布局跳动

### 👥 多账号管理

#### 添加新账号
1. 点击工具栏右侧的"账号"下拉菜单
2. 点击"添加账号"按钮
3. 输入账号信息：
   - 显示名称（自定义）
   - GitHub 用户名
   - 个人访问令牌

#### 管理账号
- **启用/禁用**：使用切换开关控制账号同步
- **编辑信息**：修改显示名称或更新令牌
- **删除账号**：移除不再需要的账号

#### 账号状态显示
- 头像和用户名
- 最后同步时间
- 启用/禁用状态

### 📤 导出功能

#### 导出选项
支持多种格式导出星标仓库：
- **JSON**：完整数据导出
- **CSV**：表格格式，便于分析
- **Markdown**：文档格式，便于分享
- **纯文本**：简洁列表格式

#### 导出步骤
1. 点击工具栏的"导出"按钮
2. 选择要导出的仓库（支持全选）
3. 选择导出格式
4. 点击"确认导出"

#### 导出内容
包含以下信息：
- 仓库基本信息（名称、描述、URL）
- 统计数据（星标数、Fork数）
- 个人数据（标签、笔记）
- 时间信息（创建时间、更新时间）

## 高级用法

### 🔄 同步策略

#### 自动同步
- 插件启动时自动同步
- 可在设置中关闭自动同步

#### 手动同步
- 点击"同步"按钮立即更新
- 支持多账号并行同步
- 显示同步进度和状态

#### 增量同步
- 仅同步变化的仓库
- 保留本地标签和笔记
- 提高同步效率

### 🎯 高级搜索

#### 搜索技巧
```
搜索语法示例：
- 精确匹配：使用引号 "exact match"
- 排除内容：使用减号 -unwanted
- 语言搜索：language:python
- 组合搜索：react typescript -vue
```

#### 筛选组合
- 搜索 + 标签筛选同时生效
- 排序 + 筛选结果联动
- 实时预览筛选结果数量

### 📊 数据管理

#### 数据存储
- 本地存储在 Obsidian 配置文件中
- 支持跨设备同步（通过 Obsidian 同步）
- 数据格式：JSON

#### 数据备份
建议定期备份：
```
路径：.obsidian/plugins/github-stars-manager/data.json
```

#### 数据迁移
- 导出所有数据为 JSON
- 在新环境导入配置
- 保持标签和笔记完整性

## 常见问题

### ❓ 令牌相关问题

**Q: 提示令牌无效？**
A: 检查以下几点：
- 令牌是否复制完整
- 是否选择了所需权限：公开星标通常需要 `read:user` 和 `public_repo`，私有仓库相关数据才需要 `repo`
- 令牌是否已过期
- 是否使用了 Classic Token（非 Fine-grained）

**Q: 同步失败？**
A: 可能原因：
- 网络连接问题
- GitHub API 限制
- 令牌权限不足
- 仓库数量过多

### 🔧 界面问题

**Q: 仓库卡片显示不全？**
A: 尝试以下解决方案：
- 调整 Obsidian 窗口大小
- 切换 Obsidian 的浅色/深色外观查看效果
- 检查插件是否为最新版本

**Q: 搜索结果不准确？**
A: 搜索范围包括：
- 仓库名称
- 仓库描述  
- 主要语言
- 自定义标签

### 💾 数据问题

**Q: 标签丢失？**
A: 可能原因：
- 误操作删除
- 同步时覆盖
- 数据文件损坏

解决方案：
- 从备份恢复数据
- 重新添加标签
- 导出现有数据备份

**Q: 同步后仓库数量不对？**
A: 检查：
- 是否有私有仓库（需要额外权限）
- 令牌是否有足够权限
- 是否开启了多账号

## 最佳实践

### 🏷️ 标签命名建议

#### 按技术分类
```
前端：frontend, react, vue, angular
后端：backend, nodejs, python, java
移动端：mobile, ios, android, flutter
```

#### 按用途分类
```
工具：tool, utility, cli, devtool  
学习：learning, tutorial, example
工作：work, project, production
个人：personal, hobby, experiment
```

#### 按状态分类
```
状态：active, archived, todo, done
优先级：high, medium, low
质量：excellent, good, average
```

### 📋 仓库管理建议

#### 定期整理
- 每月清理不再关注的仓库
- 更新标签分类
- 完善仓库笔记

#### 笔记记录
建议记录：
- **首次印象**：为什么关注这个项目
- **核心功能**：项目的主要特性
- **使用场景**：什么时候会用到
- **学习价值**：能学到什么技术
- **相关项目**：类似的替代方案

#### 导出备份
- 每月导出一次完整数据
- 按分类导出不同标签的仓库
- 定期检查备份文件完整性

### 🎯 工作流建议

#### 日常使用
1. 早上查看新增的星标仓库
2. 为新仓库添加合适的标签
3. 记录重要仓库的使用笔记
4. 定期整理和清理无用仓库

#### 学习计划
1. 使用"learning"标签标记学习资源
2. 按技术栈分类整理
3. 制定学习计划和进度跟踪
4. 关联到学习笔记

#### 项目管理
1. 为工作项目创建专门标签
2. 记录使用的开源库和工具
3. 建立技术栈知识库
4. 分享优秀项目给团队

---

🎉 **恭喜！** 您已经掌握了 GitHub Stars Manager 的所有功能。开始享受更好的星标仓库管理体验吧！

有其他问题？欢迎在 [GitHub Issues](https://github.com/EmberSparks/obsidian-github-stars-manager/issues) 中提出。