fork-intelligence

Fork 情报

在 GitHub 分叉生态系统中发现有价值工作的系统化方法。仅按星标筛选会漏掉 60%–100% 的实质性分叉 — 此技能通过分支级差异分析、交叉引用上游 PR 和特定领域的启发式方法，找出真正重要的内容。

已在 10 个涵盖 Python、Rust、TypeScript、C++/Python 和 Node.js 的仓库中进行实证验证（tensortrade、backtesting.py、kokoro、pymoo、firecrawl、barter-rs、pueue、dukascopy-node、ArcticDB、flowsurface）。

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方法 — 请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

首先 — TodoWrite 任务模板

必须：在进行任何分叉分析之前，选择并加载合适的模板。

模板 A — 完整分析（新仓库）

1. Get upstream baseline (stars, forks, default branch, last push)
2. List all forks with pagination, note timestamp clusters
3. Filter to unique-timestamp forks (skip bulk mirrors)
4. Check default branch divergence (ahead_by/behind_by)
5. Check non-default branches for all forks with recent push or >1 branch
6. Evaluate commit content, author emails, tags/releases
7. Cross-reference upstream PR history from fork owners
8. Tier ranking and cross-fork convergence analysis
9. Produce report with actionable recommendations

模板 B — 快速扫描（仅分诊）

1. Get upstream baseline
2. List forks, filter by timestamp clustering
3. Check default branch divergence only
4. Report forks with ahead_by > 0

模板 C — 定向评估分叉（特定分叉）

1. Compare fork vs upstream on all branches
2. Examine commit messages and changed files
3. Check for tags/releases, open issues, PRs
4. Assess cherry-pick viability

---

信号优先级顺序

根据在 10 个仓库中的实证可靠性排序。详情请参阅 signal-priority.md。

排名	信号	可靠性	可发现的内容
1	分支级差异	最高	功能分支上的工作（占实质性分叉的 50% 以上）
2	交叉引用上游 PR	高	通过变基/强制推送进行的工作，无法通过 compare API 发现
3	分叉上的标签/版本发布	高	独立维护意图
4	提交者邮箱域名	高	机构贡献者（@company.com）
5	时间戳聚类	中	排除 85% 以上的镜像噪声
6	跨分叉趋同	中	揭示上游尚未满足的需求
7	星标	最低	通常与实际价值负相关

---

流程 — 7 个步骤

步骤 1：上游基线

UPSTREAM="OWNER/REPO"
gh api "repos/$UPSTREAM" --jq '{forks_count, pushed_at, default_branch, stargazers_count}'

步骤 2：列出所有分叉 + 时间戳聚类

# List all forks with activity signals
gh api "repos/$UPSTREAM/forks" --paginate \
  --jq '.[] | {full_name, pushed_at, stargazers_count, default_branch}'

时间戳聚类：与上游具有完全相同 pushed_at 的分叉，是通过 GitHub 分叉机制创建且从未改动的批量镜像。按 pushed_at 分组 — 时间戳独特的分叉值得调查。仅此一项就能排除 85% 以上的噪声。

# Filter to unique-timestamp forks (skip bulk mirrors)
gh api "repos/$UPSTREAM/forks" --paginate \
  --jq '.[] | {full_name, pushed_at, stargazers_count}' | \
  jq -s 'group_by(.pushed_at) | map(select(length == 1)) | flatten'

步骤 3：默认分支差异

BRANCH=$(gh api "repos/$UPSTREAM" --jq '.default_branch')

# For each candidate fork
gh api "repos/$UPSTREAM/compare/$BRANCH...FORK_OWNER:$BRANCH" \
  --jq '{ahead_by, behind_by, status}'

status 字段的含义：

• identical — 纯镜像，跳过
• behind — 过期镜像，跳过
• diverged — 有原创提交且落后于上游（值得关注）
• ahead — 有原创提交，且与上游同步（少见，最有价值）

重要：始终从上游仓库的角度进行比较（repos/UPSTREAM/compare/...）。反向比较（repos/FORK/compare/...）在某些仓库中会返回 404。

步骤 4：非默认分支分析（关键）

这是方法论上最大的一项改进。 在测试的全部 10 个仓库中，最有价值的分叉工作有 50% 以上仅存在于功能分支上。

示例：

• flowsurface/aviu16：7,000 行的 GPU 着色器热力图仅在 shader-heatmap 上
• ArcticDB/DerThorsten：在 conda_build、clang、apple_changes 上有 147 个提交
• pueue/FrancescElies：时长显示功能仅在 cesc/duration 上
• barter-rs：前 12 个分叉中有 6 个仅在功能分支上有工作

# List branches on a fork
gh api "repos/FORK_OWNER/REPO/branches" --jq '.[].name' | head -20

# Check divergence on a specific branch
gh api "repos/$UPSTREAM/compare/$BRANCH...FORK_OWNER:FEATURE_BRANCH" \
  --jq '{ahead_by, behind_by, status}'

需要检查分支的分叉启发式条件：

• 任何 pushed_at 晚于上游，但默认分支上的 ahead_by == 0 的分叉
• 任何分支数量大于 1 的分叉
• 分支数 > 10 时应提高警惕 — 可能存在不简单的工作（ArcticDB：Rohan-flutterint 有 197 个分支）

步骤 5：评估提交内容

gh api "repos/$UPSTREAM/compare/$BRANCH...FORK_OWNER:BRANCH" \
  --jq '.commits[] | {sha: .sha[:8], message: .commit.message | split("\n")[0], date: .commit.committer.date[:10], author: .commit.author.email}'

关注点：

• 提交邮箱域名可揭示机构贡献者（@man.com、@quantstack.net）
• 从 ahead_by 数量中减去合并提交（例如，akeda2/pueue 显示领先 35 个提交，但其中 28 个是上游合并）
• 构建系统变更（CMakeLists.txt、Cargo.toml、pyproject.toml）表明正在启用平台支持
• Protocol Buffer 架构变更表明存在架构级功能
• 源代码变更同时附带测试文件，说明相关工作意在用于生产环境

步骤 6：Fork 特有信号

# Tags/releases (strongest independent maintenance signal)
gh api "repos/FORK_OWNER/REPO/tags" --jq '.[].name' | head -10
gh api "repos/FORK_OWNER/REPO/releases" --jq '.[] | {tag_name, name, published_at}' | head -5

# Open issues on the fork (signals independent project maintenance)
gh api "repos/FORK_OWNER/REPO/issues?state=open" --jq 'length'

# Check if repo was renamed (strong divergence intent signal)
gh api "repos/FORK_OWNER/REPO" --jq '.name'

信号	强度	示例
Fork 上的标签／发行版	最高	pueue/freesrz93 有 6 个发行版
针对上游的未关闭 PR	高	有评审背景的正式提案
Fork 上的未关闭议题	高	独立的项目维护
仓库重命名	中	flowsurface/sinaha81 更名为 volume_flow
构建配置变更	高（编译型语言）	Cargo.toml、CMakeLists.txt 差异
描述变更	弱	许多只是为了显眼而重命名，没有代码变更

步骤 7：跨 Fork 趋同 + 上游 PR 历史

# Check upstream PRs from fork owners
gh api "repos/$UPSTREAM/pulls?state=all" --paginate \
  --jq '.[] | select(.head.repo.fork) | {number, title, state, user: .user.login}'

跨 Fork 趋同：多个 Fork 独立解决同一问题，说明上游存在未满足的需求：

• firecrawl：3 个 Fork 采用了 Patchright 来防检测
• flowsurface：3 个 Fork 独立添加了技术指标
• kokoro：2 个独立实现了批量推理
• barter-rs：4 个 Fork 添加了 Bybit 支持

交叉核对上游 PR 可发现：

• 在 compare API 中不可见的变基／强制推送工作
• 已合并到上游的工作（Fork 显示领先 0 个提交，但曾具有重要意义）
• 包含有价值代码且仍由 Fork 维护的已拒绝 PR

---

等级分类

运行完工作流后，将 Fork 分为以下等级：

等级	标准	操作
等级 1：重大扩展	新功能、架构变更、超过 10 个原创提交	深入评估，筛选可拣选的提交
等级 2：针对性功能	聚焦的新增内容、错误修复、2-10 个提交	拣选单个提交
等级 3：基础设施	CI/CD、打包、部署、文档	评估是否适用于你的设置
等级 4：历史贡献	已合并到上游，或已过时但曾具有重要意义	作为背景记录，无需采取行动

特定领域模式

不同代码库会表现出不同的分叉行为。完整详情请参阅 domain-patterns.md。

领域	主要模式	示例
科学/ML	研究人员分叉实现后发布，随后销声匿迹，几乎没有社交互动	pymoo：300 文件的分叉项目，获 0 颗星
交易/金融	交易所连接器占主导地位；最佳分叉项目是私有的	barter-rs：4 个独立的 Bybit 实现
基础设施/开发工具	自托管/移除 SaaS 是主要主题	firecrawl：devflowinc/firecrawl-simple（630 颗星）
C++/Python 混合	功能开发存在于分支上；电子邮件域名可揭示所属机构	ArcticDB：@man.com、@quantstack.net
Node.js 库	检查是否以独立软件包的形式发布到 npm	dukascopy-node：kyo06 发布了 dukascopy-node-plus
Rust CLI	Cargo.toml 差异是可靠的快速筛选方式；“超集”分叉会新增子命令	pueue：freesrz93 新增了 7 个子命令

---

快速扫描流程（5 分钟初步筛选）

快速初步筛选任何新代码库：

UPSTREAM="OWNER/REPO"
BRANCH=$(gh api "repos/$UPSTREAM" --jq '.default_branch')

# 1. Baseline
gh api "repos/$UPSTREAM" --jq '{forks_count, pushed_at, stargazers_count}'

# 2. Forks with unique timestamps (skip mirrors)
gh api "repos/$UPSTREAM/forks" --paginate \
  --jq '.[] | {full_name, pushed_at, stargazers_count}' | \
  jq -s 'group_by(.pushed_at) | map(select(length == 1)) | flatten | sort_by(.pushed_at) | reverse'

# 3. Check ahead_by for each candidate
# (loop over candidates from step 2)

# 4. Check upstream PRs from fork authors
gh api "repos/$UPSTREAM/pulls?state=all" --paginate \
  --jq '.[] | select(.head.repo.fork) | {number, title, state, user: .user.login}'

---

已知限制

限制	影响	解决方法
GitHub compare API 限制为 250 次提交	差异很大的分叉项目可能会被截断	使用 gh api repos/FORK/commits?per_page=1 获取总数
无法看到私有分叉项目	交易公司会将最佳成果保密	接受此限制
强制推送的分支会导致 compare API 出错	即使有大量工作，也会显示领先 0 次提交	交叉核对上游 PR 历史
重命名的分叉项目可能导致 API 调用失败	旧 URL 可能返回 404	使用 gh api repos/FORK_OWNER/REPO --jq '.name' 检测重命名
大型分叉生态中的速率限制	>1000 个分叉 = 需要进行大量 API 调用	使用时间戳聚类，将调用次数减少 85% 以上
维护者的开发分叉看起来像独立开发	分支名称与上游 PR 一一对应	将分支名称与上游 PR 分支名称交叉核对

---

报告模板

最终分析报告请使用以下结构：

# Fork Analysis Report: OWNER/REPO

**Repository**: OWNER/REPO (N stars, M forks)
**Analysis date**: YYYY-MM-DD

## Fork Landscape Summary

| Metric                                | Value  |
| ------------------------------------- | ------ |
| Total forks                           | N      |
| Pure mirrors                          | N (X%) |
| Divergent forks (ahead on any branch) | N      |
| Substantive forks (meaningful work)   | N      |
| Stars-only miss rate                  | X%     |

## Tiered Ranking

### Tier 1: Major Extensions

(fork details with ahead_by, key features, files changed)

### Tier 2: Targeted Features

...

### Tier 3: Infrastructure/Packaging

...

## Cross-Fork Convergence Patterns

(themes that multiple forks independently implemented)

## Actionable Recommendations

- Cherry-pick candidates
- Feature inspiration
- Security fixes

---

修改后检查清单

修改此技能后：

1. YAML frontmatter 有效（描述中不含冒号）
2. 描述中的触发关键词是最新的
3. 所有 ./references/ 链接都有效
4. 流程步骤的编号一致
5. 已在真实代码库上测试 Shell 命令
6. 将变更追加到 evolution-log.md

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。 — 找到此 SKILL.md 的规范路径，然后再进行编辑。
1. 哪里失败了？ — 修复导致问题的指令。
2. 哪些地方比预期更有效？ — 将其提升为推荐做法。
3. 哪里出现了偏差？ — 修复任何与实际情况不再一致的脚本、参考资料或依赖项。
4. 记录下来。 — 在演进日志中记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。