/github-star-manager

变更日志 (CHANGELOG.md)

本文档记录 github-star-manager 技能的所有变更。

[0.6.6] - 2026-09-24

修复

• 导出脚本网络重试加固（重要）：star_tracker.py 全部 14 处裸 requests.get/put/delete 改走新增的 _request_with_retry() 封装——指数退避重试（2s 起步、60s 封顶、最多 8 次），覆盖网络异常（ProxyError/RemoteDisconnected/Timeout 等）与 429/5xx 状态码，429 尊重 Retry-After 头。事故背景：全量导出 673 仓（约 2000+ 次请求）在代理环境下连续两晚失败——首次 HTTP 503 隧道错误（处理到 multica-ai/multica 时）、次次 RemoteDisconnected，裸调用一次即崩，长窗口任务必折。修复后全量导出 681 仓一次通过、零失败
• 导出产物路径不再随 cwd 漂移：main.py 导出 Dashboard 与 config 原写入相对路径 output/，从其他目录（如仓库根）启动时产物散落工作区、污染共享仓库（实测：scripts/output/ 出现 data.js/dashboard.html 两个 untracked 脏文件）；现统一锚定技能自身 output/ 目录（StarTracker.CACHE_DIR，已被 .gitignore 覆盖）。dashboard_generator.py 模板查找同步从相对路径改为锚定技能目录，否则非技能根目录启动时永远走简化模板

改进

• 对话模块消歧经验扩充（3 条实战模式入 SKILL.md）：① owner 拼写修正——截图直读 owner 404 时先怀疑 OCR 误读，按 repo 名搜索锁定真身并用星数量级与截图侧栏数字互证（实测 webadderalorg→webadderallorg/Recordly）；② 社交账号名 ↔ GitHub owner 互证——博主昵称与 owner 名的派生关系作中优先级佐证（实测：耳朵→erduo1998-cell、姚老师→yaojingang、文森特→Vincentwei1021）；③ 改名仓库识别——旧名 404 时查 API 301 重定向，返回的 full_name 即新名，已在库则跳过（实测：erduo-hyperframes-broll→erduo-broll-loop-engineering）
• SKILL.md Dashboard 使用说明同步产物路径变化

[0.6.5] - 2026-09-23

改进

• 消歧协议重排（重要）：证据优先级明确为「来源亲授全称 > 语义比对 > 排除规则 > 版本轨迹」，Star 数量级从第 1 位降为第 5 位仅参考信号、永不单独定论。实测反例：taste-skill 同名的 Leonxlnx 版 8.9 万⭐ 比目标 senlindesign 版（366⭐）高两个数量级，若按旧协议"数量级快筛"会 star 错；实际靠语义比对 + 作者评论区亲授全称锁定

新增

• 评论区/回复作为提取源：作者在评论区亲授的 owner/repo 全称是最高优先级证据，优先于一切启发式消歧
• 半截 URL 补全策略：owner 确定而 name 截断（如 mcncarl/jianyi…）时，列该 owner 名下仓库按名称前缀 + description 语义匹配补全（实测：jianyi…→jianying-headless，yichen…→yichen-skills）
• 批量 star 执行模式：一次内容提取出多个仓库时循环"查重→star→回读"，单仓失败不阻断，最后汇总成功/跳过/失败

背景

四连 star 实战（taste-skill、jianying-headless、yichen-skills、hypit）中，数量级启发式首次遇到同名高星反例，暴露 0.6.4 协议的优先级缺陷；同时半截 URL 补全、评论区提取、批量执行三种实战模式均未成文，本次一并固化。

[0.6.4] - 2026-09-23

新增

• 同名候选消歧协议：社交内容（截图/帖子）常只给项目名，同名候选多为 fork/搬运/衍生项目。对话模块新增四步锚定：Star 数量级判别（原仓库通常高 1–2 个数量级）、图片语义锚定（截图功能场景与候选 description 比对，而非只提取项目名文字）、衍生仓库排除（后缀/自述"基于上游"）、版本交叉核对（内容提到版本号时查 releases/tags）
• 消歧兜底：候选无法唯一确定时不凭猜测 star，列出候选与判断依据请用户确认

背景

实测两起截图 star 案例（mono-color-skill 3250⭐ vs 0~3⭐ 搬运；native-subtitle-quote-image 795⭐ vs 5/7⭐ 衍生）均依赖上述锚定手法锁定原仓库，但原 SKILL.md 仅有一行"上下文相关性验证"，无可操作判据，本次将实战验证过的协议固化。

[0.6.3] - 2026-09-23

修复

• 对话模块 star 命令在 gh 2.83.0 不可用：SKILL.md 中 gh repo star owner/repo 实际报 unknown command "star" for "gh repo"（该子命令并非所有 gh 版本都有），改用 REST API gh api -X PUT user/starred/owner/repo，幂等且跨版本可用
• star 结果验证语义：补充检查是否已 star 的响应语义（HTTP 204 = 已 star，404 = 未 star），并要求 star 后以 GET 回读 204 为完成标准，不以 PUT 退出码为准
• frontmatter 版本滞后：SKILL.md version 停留在 0.6.1，与 CHANGELOG 已发布的 0.6.2 脱节，本次一并同步到 0.6.3

[0.6.2] - 2026-05-10

修复

• description 为 null 时自动重试：增量同步和首次同步时，对 description 为 null 的项目自动调用 GitHub API 重新抓取最新元数据，同时刷新 language、topics、homepage 等字段（Closes #9）
• star 变化触发元数据刷新：检测到新增 star 时，同时刷新该项目的 description、language、topics 等元数据，确保存量项目改名后数据同步更新
• 数据质量日志：新增 log_null_descriptions() 方法，记录哪些项目 description 为 null 并输出到 output/data_quality.log，方便排查数据质量问题

新增方法

[0.6.1] - 2026-04-10

修复

• 文档路径修正：环境配置示例统一改为当前目录结构
  • cp .env.example .env 修正为 cp assets/.env.example .env
  • pip install -r requirements.txt 修正为 pip install -r assets/requirements.txt
• 配置目录口径统一：首次复制配置目录统一为 ~/.github-star-manager/

文档完善

• references/api-guide.md 与 references/dev-guide.md 中的旧名称 github-star-tracker 已同步改为 github-star-manager
• 开发指南中的测试目录示例改为当前目录 skills/github-star-manager

[0.6.0] - 2026-02-28

重构（Skill 整合）

新增（对话模块）

对话模块功能

• 从各种内容来源（URL/截图/文字）中自动提取 GitHub 仓库引用
• 智能匹配：直接匹配 + 按名称搜索 + 上下文相关性验证
• 自动检查是否已 Star，避免重复
• 使用 GitHub CLI (gh) 执行 Star 操作

删除

• 删除 github-auto-star 独立 Skill，功能已整合到 github-star-manager

[0.5.1] - 2026-02-14

修复（Dashboard UI 问题修复）

增强（时间筛选扩展）

重构（项目命名）

模板文件更新

• assets/dashboard.example.html - 同步 Dashboard 修复和默认显示
• assets/.env.example - 更新标题为 GitHub Stars Tracker

[0.5.0] - 2026-02-14

新增（数据维度增强 + 双重活跃度筛选）

数据字段清单

基本信息：

• full_name, name, owner, html_url, description, homepage

时间维度（关键）：

• starred_at - 用户何时 star 的
• created_at - 仓库创建时间
• updated_at - 最后更新时间
• pushed_at - 最后推送时间
• local_fetched_at - 本地抓取时间

统计数据：

• stargazers_count, forks_count, watchers_count, open_issues_count

分类信息：

• language, topics, license, visibility

项目特征：

• is_fork, is_archived, is_template, has_wiki, has_pages, has_discussions

使用示例

# 重新初始化获取完整数据（27个字段）
python scripts/main.py --init --user cat-xierluo

# 查看 Dashboard（包含活跃度筛选）
open output/dashboard.html

技术改进

• save_latest() 方法重写，保存完整仓库信息
• get_starred_repos() 添加 include_starred_at 参数，使用 application/vnd.github.star+json 获取 starred_at
• Dashboard 添加活跃度统计卡片和筛选下拉框
• JavaScript 添加 getActivityCategory() 和 updateActivityStats() 函数

[0.4.2] - 2026-02-12

新增（输出目录规范）

使用说明

运行 --export 后，生成的文件位于 output/ 目录：

• output/projects.json - 导出的项目数据
• output/dashboard.html - 可视化面板

打开 output/dashboard.html 即可查看数据可视化。

[0.4.1] - 2026-02-12

修复（目录结构规范化）

• 配置文件散落在根目录 → 移至 assets/ 目录符合 SKILL-GUIDE.md 规范
• 文档路径引用错误 → 更新 SKILL.md 和 CHANGELOG.md 中的路径

变更内容

• 移动 dashboard.example.html → assets/dashboard.example.html
• 移动 projects.example.json → assets/projects.example.json
• 移动 categories.yaml → assets/categories.yaml
• 移动 tags.json → assets/tags.json
• 更新 scripts/main.py 中的模板路径引用
• 更新 SKILL.md 配置文件说明

[0.4.0] - 2026-02-12

新增（分类与标签系统）

使用示例

# 导出数据（现在包含分类和标签）
python scripts/main.py --export

# 编辑分类配置
vim ~/.github-star-tracker/categories.yaml

# 添加新标签
python scripts/main.py --add-tag "游戏引擎" --color "#f472b6"

# 按分类查看
# 然后在 Dashboard 中点击对应分类标签

技术改进

• 新增 assets/categories.yaml 和 assets/tags.json 配置文件
• StarTracker 添加 _load_categories(), _load_tags(), get_categories_map() 方法
• StarTracker 添加 _match_category() 方法，根据关键词智能匹配分类
• get_starred_repos() 返回的每个仓库包含 category 和 matched_keywords 字段
• Dashboard 全面重构，支持标签云、分类筛选、搜索

[0.3.1] - 2026-02-12

修复

改进

• 默认 limit 从 100 提升到 9999（获取全部）
• Dashboard 修复本地文件加载问题
• --user 参数改为可选，未提供时自动获取

[0.3.0] - 2026-02-12

新增（Star 管理功能）

使用示例

# 单个操作
python scripts/main.py --star owner/repo           # 添加 Star
python scripts/main.py --unstar owner/repo        # 取消 Star

# 清理陈旧项目
python scripts/main.py --cleanup --days 90         # 预览（默认）
python scripts/main.py --cleanup --days 90 --execute  # 实际执行

# 批量操作
python scripts/main.py --batch-unstar repos.json   # 批量取消
python scripts/main.py --batch-star repos.json    # 批量添加

技术改进

• StarTracker 类新增 star_repo(), unstar_repo(), is_starred() 等方法
• 添加 --execute 安全确认机制，避免误操作
• 所有破坏性操作（取消 Star）默认预览，需要 --execute 确认

[0.2.0] - 2026-02-12

新增

• HTML Dashboard：实现信息密集型可视化面板，支持一屏浏览大量项目
• 数据导出功能：新增 --export 命令，生成 projects.json 供 Dashboard 使用
• 状态筛选：支持按活跃度（活跃/近期更新/长期未更）和价值（高/中）筛选
• 搜索功能：支持按项目名、描述、标签进行关键词搜索
• 示例文件机制：创建 dashboard.example.html 作为模板，首次运行自动复制

改进

• 从 knowledge-retention skill 重构，移除社交媒体截图转化功能
• 专注核心功能：更新追踪、版本检测、活跃度分析
• 卡片点击展开详情：显示创建时间、Forks、Issues 等信息

技术优化

• 使用 CSS 变量管理主题色值
• 响应式布局，支持移动端浏览
• 本地 JSON 数据缓存，减少 API 请求