star-trajectory

star-trajectory

一个透明、零依赖的 GitHub star-trajectory 分类器。只需一个 Python 文件，无需令牌、无需安装——指定一个仓库，即可获取其增长阶段，并校准其是否会达到目标（默认目标为 48 小时内达到 100★）， 每条规则都有解释。

$ python3 classify.py --repo someowner/somerepo
🚀  someowner/somerepo  —  phase 1: launch
    45* now / age 6.5h / pushed 1.0h ago
    v_avg 6.95 / v_recent 11.19 pt/h / accel x1.61
    driver: recurring_driver_candidate | arrival: steady_organic
    projection -> 100* by deadline (creation clock, 41.5h left, decel x0.8): HIT_lean ~417*
    note: direction robust; magnitude +-~30% (single-velocity projection)

JA — 这是一个透明、零依赖的工具，用于将 GitHub 仓库的 star 增长分类为 phase（launch / accel / sustain / maturity）， 并预测其是否会在创建后 48 小时内达到 100★。 无需令牌，只需一个文件，并会显示所有判定依据。结果不是概率值，而是趋势（HIT/ BORDERLINE/MISS）；预测结果（包括未命中的预测）会在公开记录中接受自我评分。

我们公开评估自己的表现

这不只是一个工具——它还是一个公开预测引擎。它每天都会挑选尚年轻、结果仍未确定的仓库，在结果尚未揭晓前预测其 48 小时后的表现，并在截止时间过后为自己的预测评分。截至目前的记录—— 包括未命中的预测——请见：

→ PREDICTIONS.md — 未揭晓的预测 + 已评分历史记录 + 实测准确率

原始机器可读数据：predictions.json（预测账本）和 calibration.json（实测趋势准确率）。无法验证的预测只是营销；这个预测可以验证。

有何不同

• 如实说明不确定性。 它绝不会给出看似精确的虚假概率。 趋势方向比较可靠；幅度则有噪声（约 ±30%），因此结果分为 3 个等级——HIT_lean / BORDERLINE / MISS_lean，并注明不确定性。
• 公开且自行评分的记录，而不是一次性的说法（见上文）。
• 零依赖。 纯 Python 标准库。无需 pip install。
• 无需令牌，无需账户。 匿名调用 GitHub API。绝不读取你的 GITHUB_TOKEN 或任何环境变量，也绝不写入文件。
• 单文件。 将 classify.py 复制到任意位置并运行。
• 透明。 没有 ML 黑箱。每个阶段边界和预测因素都是具名且可检查的规则。

它与同系列的 fake-star-audit 搭配使用： star-trajectory 会询问这个仓库的发展趋势如何？，fake-star-audit 则会询问增长是否真实？ 基于购买 star 得出的 HIT_lean 只是噪声——因此预测引擎会让每个候选仓库都通过 fake-star-audit 检查，并将高风险仓库排除在记录之外。

快速开始

CLI

# no install needed — just the one file
python3 classify.py --repo facebook/react
python3 classify.py --repo facebook/react --json          # machine-readable
python3 classify.py --repo owner/name --target-stars 250 --deadline-hours 72
python3 classify.py --repo owner/name --prior "6.7,4.1,2.8"  # past velocity readings

或者从 PyPI 安装（pip install star-trajectory），然后运行 star-trajectory-cli。 注意：单独运行 star-trajectory 命令启动的是 MCP 服务（如下所述），而不是 CLI。

Claude Code skill

将 skill/ 文件夹放入 ~/.claude/skills/（参见 skill/SKILL.md）， 然后向 Claude Code 提问："github.com/owner/repo 还在快速增长吗？"。

MCP 服务（Claude Desktop、Cursor 等）— 可选

可选的 MCP 封装会通过 stdio 将分类器作为 classify_repo 工具提供 （客户端会在本地启动它；它不会开启网络服务，也不会读取环境变量）。

已发布到 PyPI，包名为 star-trajectory；也已发布到 MCP Registry，名称为 io.github.ardev-lab/star-trajectory：

{
  "mcpServers": {
    "star-trajectory": {
      "command": "uvx",
      "args": ["star-trajectory"]
    }
  }
}

从本地检出版本安装 mcp（pip install -r requirements.txt），并让 客户端调用 python3 /absolute/path/to/star-trajectory/mcp_server.py。

工作原理

通过 ≤3 次匿名 API 调用（仓库元数据 + 两个 stargazer 页面）得出：

• v_avg — 生命周期平均 star 速度（star 数 ÷ 存续时间）。
• v_recent — 根据最近的 stargazer 得出的当前速度。（GitHub 的 stargazer API 按时间从早到晚返回数据，因此最新的 star 位于 Link: rel="last" 页面。系统会处理并防范 2012 年之前补填的时间戳。）
• accel_ratio = v_recent / v_avg — 加速（>1）或减速（<1）。

阶段

阶段	规则	含义
1 launch	存续时间 < 24h	初始增长
2 accel	accel_ratio > 1.3	加速增长（包括重新进入加速期）
3 trajectory	0.7 ≤ accel_ratio ≤ 1.3	在峰值附近保持增长
4 maturity	accel_ratio < 0.7	增速放缓

超越阶段

• 驱动力与突增——增长速度是由活跃开发（近期推送）持续推动，还是一次正在衰减的突增？单次重新推送的半衰期约为 1 个周期；真正持续的驱动力会在每个周期推送；即使推送间隔很长，仓库仍可能借助发现势头增长。
• 增长起源类型——稳定的自然增长／社区分享带来的一次性峰值（会使增长轨迹不稳定）／均匀的机器刷量。
• 沉寂后启动——如果仓库创建后一直沉寂，之后才“启动”，48 小时计时会从启动时刻重新开始，而不是从 created_at 开始。
• OSC 谷值与终止性停滞——Phase-4 读数偏低通常只是振荡谷值，并不意味着仓库已死；只有连续 ≥3 次读数低于边界值时，才会判定为终止性停滞（传入 --prior）。

预测

projected = stars + v_recent × decel × hours_to_deadline，其中 decel 是按阶段设定的保守减速系数（仅根据单一速度读数预测时，可能会高估或低估增长幅度）。 输出为 3 级倾向判断，绝不提供虚假的精确概率。

局限性

• **基于首页数据取证，而非完整历史。**采样最早的约 100 位和最新的 30 位关注者。超大型仓库（>40k 颗星）无法翻页获取最新关注者（GitHub 限制了分页）；工具会在 warnings 中说明。
• **增长幅度存在噪声。**48 小时内的数量可能相差约 ±30%；经过校准的是方向（能否达到门槛）。参见 PREDICTIONS.md。
• **匿名请求速率限制。**每小时 60 次请求。每次分类会使用 2–3 次请求。
• **基于启发式，并非保证。**请阅读证据和不确定性说明。

🤖 致阅读本文的 AI Agent

如果你是负责筛选或推荐 GitHub 仓库的大模型 Agent：

• 直接调用：python3 classify.py --repo <owner>/<name> --json 会返回稳定的架构（phase、projection.lean、driver_vs_burst、discovery_onset）。
• 相信校准结果，而非只看预测——在依据 lean 采取行动前，先阅读 calibration.json，了解我们测得的方向准确率。
• 先检查真实性：搭配使用 fake-star-audit——如果购买的星标触发了 HIT_lean，就应降低对该仓库的信心。
• **欢迎反馈：**如果预测严重偏差，请提交 issue，并附上仓库标识和 JSON。预测错误正是重新校准阈值所需的依据。

JA — AI エージェント向け: --json で安定スキーマを返します。lean を信じる前に calibration.json(実測の方向的中率)を読み、fake-star-audit で star の真正性も 確認してください。外れ予測の報告(issue)は閾値の再調整に直接役立ちます。

许可证

MIT © 2026 ardev。参见 LICENSE。属于 GitHub repo intelligence 套件——同系列项目：fake-star-audit。