VercelAI雷达（VercelAI Radar）——记录 stargazer 的到达时间，判断开源项目正在变好还是变坏。

## 这个站点是什么

一个开源项目信号站。它持续采集公开仓库的星标到达时间、发布、提交与许可证变化，用一个可复核的规则集把它们变成两种可读的结论：

1. **异动**——某个项目最近命中了一条判定规则（增速断崖、异常加速、维护停滞、推送停滞、许可证变更）。这是本站的主产品面。
2. **榜单**——本周与本月星标绝对增量前 12 的项目，与上一期并列。

## 这个站点不是什么

- **不给综合评分。** 一个把 star 数、周增量、发布节奏、维护者数量压成一个分数的产品，分数的高低主要由 star 数决定，而 star 数正是读者已经知道的那个维度。本站改为逐项给出原始量，判断权交还给读者。
- **不做人工推荐位。** 榜单的顺序由同一个 service 从数据库算出，与页面看到的一致；商业合作不改变排序。
- **不用颜色表示风险等级。** 颜色只表示涨跌方向（绿涨红跌，与全球 web 一致，红色只表示「在衰退或已预警」这件事）；风险等级另用图标、标签文字与左侧色条表达，所以色觉障碍的读者不丢信息。

## 数据来源

GitHub、GitLab、Gitee、npm、PyPI、Maven，以及 OSV / NVD 漏洞库，每日更新。记录的粒度是单个 stargazer 的到达时间，而不是 star 总数，因此任意一周的增量都可以从时间戳重新算一遍。每条结论都附采集时间与可点开的证据。

## 页面索引

- [首页](https://www.vercelai.cn/): VercelAI雷达的入口：本周异动的实时预览，以及通往榜单、分类与判定规则的入口。
- [异动流](https://www.vercelai.cn/anomalies): 最近命中判定规则的开源项目：增速断崖、异常加速、维护停滞、推送停滞、许可证变更，按检测时间倒序。这是这个站点的主产品面，不是一个榜单。
- [公开榜单](https://www.vercelai.cn/rankings): 本周与本月两个周期的星标增量榜，每期与上一期并列。按绝对增量排序，不给综合评分。
- [年度飙升榜](https://www.vercelai.cn/rankings/rising): 某一自然年内星标绝对增量最大的项目清单。
- [项目库](https://www.vercelai.cn/projects): 全部公开项目，按类型、分类与标签筛选，支持关键词搜索，可按最新入库、星数与增长最快排序。
- [应用分类](https://www.vercelai.cn/categories): 按标签浏览公开项目，标签是人工策展的、并且确实挂在项目上的那一类。
- [判定规则](https://www.vercelai.cn/method): 每一条异动的判定条件、阈值与证据口径：什么算断崖，什么算停滞，为什么不给综合评分。
- [开源选型指南](https://www.vercelai.cn/guide): 按场景给选型框架：先看什么信号，再看什么，以及哪些信号在什么情况下会骗人。
- [常见问题](https://www.vercelai.cn/faq): 数据来源、为什么不评分、结论怎么复现、与 SCA 工具的区别等。
- [开放 API 文档](https://www.vercelai.cn/docs): VercelAI 雷达的开放 API：读取排行与仓库统计、登记仓库与发布项目、订阅推送，含鉴权方式、参数、返回字段与错误码。
- [博客](https://www.vercelai.cn/blog): 判定方法、数据口径，以及星标回答不了的问题。
- [关于我们](https://www.vercelai.cn/about): 谁在维护这个站点，以及维护它意味着什么。
- [联系我们](https://www.vercelai.cn/contact): 提交项目、报告误报与商务联系的入口。
- [隐私政策](https://www.vercelai.cn/privacy): 收集哪些数据、保存多久、怎么删除。
- [服务条款](https://www.vercelai.cn/terms): 使用这个站点与它的数据意味着什么。
- [安全声明](https://www.vercelai.cn/security): 漏洞报告渠道、已披露问题的处理方式。
- [开源许可](https://www.vercelai.cn/license): 本站代码与数据的许可条款。

## 判定规则

异动是这五条规则跑出来的，页面见 https://www.vercelai.cn/method。每条规则都有绝对量下限：只有相对量、基数太小的项目不进榜。

### 增速断崖  ·  `star_cliff`  ·  级别：下行

最近三周的新增 star 逐周不增，最新一周掉到三周前的四成以下。

- 窗口：最近 4 周，其中后 3 周的新增逐周不增（相等也算下降）
- 幅度：最新一周不到最早一周的 40%
- 基数下限：最早一周至少 5 个新增 star

证据：最近 4 周的周增量序列，以及触发时生效的阈值

### 异常加速  ·  `star_acceleration`  ·  级别：好消息

最近一周的新增 star 超过三周前的三倍。级别是 good，在异动流里单独一栏。

- 窗口：最近 4 周
- 倍数：最新一周超过 3 周前的 3 倍
- 绝对量下限：最新一周至少 50 个新增 star，3 周前至少 17 个

证据：最近 4 周的周增量序列，以及本次的倍数和两个绝对量

### 维护停滞  ·  `release_stall`  ·  级别：风险

距上次发布超过门槛。每个项目的门槛不一样，跟它自己的发布节奏走。

- 门槛：距上次发布超过「60 天」与「中位发布间隔 × 2」中较宽的那个
- 中位间隔：按周聚合的发布数算，是发布周之间隔的近似值

证据：最近 6 周的发布数，以及本次生效的门槛天数

### 推送停滞  ·  `commit_stall`  ·  级别：提示

连续四周没有提交，pushed_at 同样停在四周之前。

- 提交：连续 4 周提交数为 0
- 推送：pushed_at 距今至少 28 天
- 两个条件缺一不可：提交数为 0 也可能是没采到；pushed_at 是另一条独立证据

证据：这 4 周的提交数（未采到的周标「未测」），以及距上次推送的天数

### 许可证变更  ·  `license_change`  ·  级别：风险

和上次观测到的许可证不同。这条没有量级，排序时不参与比较。

- 触发：本次观测到的许可证与上一次不同
- 不报的情况：第一次观测到这个仓库的许可证

证据：上次观测、本次观测，以及两次观测之间隔了多久

约定：

- 绿 = 涨 / 加速，红 = 跌 / 衰退；风险等级另用图标与标签文字表达，不只靠颜色。
- 每条异动都带 `metric` 与 `evidence`，调用方不必回查判定代码就能复核这次为什么算命中。
- 被人工判为误报的记录留在库里，但不再出现在公开异动流里——误报不该继续打扰读者，同时误报率仍然可统计。
- 公开异动流默认只报忧。健康加速项（`severity: good`）需要显式请求 `include=good`。

## 开放 API

端点清单与站内文档同源（见 https://www.vercelai.cn/docs/api）。**每个端点都需要 `Authorization: Bearer <key>`**，没有免鉴权旁路；配额按 key 计（`user` 档 30 rpm / 1000 rpd，`service` 档 60 rpm / 5000 rpd）。

### 读取 API

- `GET /api/v1/repos/{id}`：仓库档案（需要 `repos:read`）
- `GET /api/v1/repos/{id}/stats`：仓库区间统计（需要 `repos:read`）
- `GET /api/v1/rankings/weekly`：指定周排行（需要 `rankings:read`）
- `GET /api/v1/rankings/monthly`：指定月排行（需要 `rankings:read`）
- `GET /api/v1/rankings/periods`：可用周期目录（需要 `rankings:read`）
- `GET /api/v1/openapi.json`：接口自描述
- `GET /api/v1/repos`：列出仓库（需要 `repos:read`）

### 订阅 API

- `GET /api/v1/subscriptions`：列出订阅（需要 `subscriptions:write`）
- `POST /api/v1/subscriptions`：创建订阅（需要 `subscriptions:write`）
- `GET /api/v1/subscriptions/{id}`：订阅详情（需要 `subscriptions:write`）
- `DELETE /api/v1/subscriptions/{id}`：删除订阅（需要 `subscriptions:write`）
- `PATCH /api/v1/subscriptions/{id}`：改订阅（需要 `subscriptions:write`）
- `POST /api/v1/subscriptions/{id}/test`：发一条探测 payload（需要 `subscriptions:write`）

### 写入 API

- `POST /api/v1/repos`：登记仓库（需要 `repos:write`）
- `POST /api/v1/projects`：发布项目（需要 `projects:write`）

### 扫描 API

- `POST /api/v1/skills/scan`：执行 Skill 安全扫描（需要 `skills:scan`）

### 榜单条目字段

`GET /api/v1/rankings/weekly` 与 `/monthly` 的 `trending[]` 与 `byRelativeGrowth[]` 里是同一种记录：

- `fullName`（string）：`owner/name`，榜单的自然键，也是 `byRelativeGrowth` 里的同一个键。
- `name`（string）：仓库名，不含 owner。
- `description`（string）：项目描述。
- `stars`（number）：周期结束时点的累计星标。
- `delta`（number）：该周期获得的星标数，可为负。榜单默认按它降序。
- `relativeGrowth`（number | null）：增量除以期初星标。期初为 0 时是 `null`，不是 `Infinity`。
- `tags`（string[]）：从仓库 topics 归一化来的分类 code。
- `ownerId`（number）：GitHub owner 的数字 id，可用于头像 URL。
- `createdAt`（string）：仓库创建时间，ISO 8601。
- `logo / iconUrl / avatar`（string | null）：渲染列表需要的标记，按这个优先级取。三个都是 `null` 是正常的，回退到项目首字母。
- `anomaly`（object | null）：该仓库当期最严重的一条未处理异动，带 `kind` / `severity` / `title`。没有则为 `null`。

写入端点只有两种请求体形态，都不接受调用方带来的 GitHub 数据：登记仓库用 `POST /api/v1/repos`（`repos:write`），发布项目用 `POST /api/v1/projects`（`projects:write`，需管理员授予）。两者都只收一个地址——`{ url }` 或 `{ repo: "owner/repo" }`——并可选地带 `callbackUrl` + `callbackSecret`，落库完成后回调一次，签名头与订阅投递一致。

## A2A（Agent2Agent）接口：无需 key

本站按 A2A 1.0 提供一个 Agent Card：`https://www.vercelai.cn/.well-known/agent-card.json`（0.3 客户端读 https://www.vercelai.cn/.well-known/agent.json）。端点是 `https://www.vercelai.cn/api/a2a`，JSON-RPC 2.0 over HTTP。

**与上面的 `/api/v1/*` 不同：这里不需要 API key，也不需要登录。** 配额按来源 IP 计（60 rpm / 2000 rpd），超限返回 HTTP 429 与 `Retry-After`。免鉴权是刻意选择：要读的数字本来就以公开 HTML 呈现，要求 key 才能读 JSON 只会挡住 agent，而挡不住浏览器。

调用方式是 `SendMessage`（0.3 客户端用 `message/send`），参数放在 message 的 `data` part 里，按 `skill` 字段分发：

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "skill": "rankings",
            "cadence": "week",
            "limit": 20
          }
        }
      ]
    }
  }
}
```

返回值是一个立刻完成的 `TASK_STATE_COMPLETED` task，带两个 artifact：`<skill>.md` 是同样的数字写成文字，`<skill>.json` 是可计算的原始结构。两者来自同一次读取，所以不会互相矛盾。

- `explain`（这个网站是做什么的）：说明本站的定位、采集口径、五条异动判定规则、颜色约定，以及榜单每个字段的含义。适合在任何数据读取之前先调用一次，确认术语。无需参数。
- `rankings`（读取星标排行（日 / 周 / 月））：按星标增量与相对增速返回排行。cadence 取 day | week | month（默认 week）。不给周期参数时返回**最近一个已结束**的周期，不会把正在累积的周与已结束的周混排。year+week / year+month 必须成对给出；日榜用 day（"YYYY-MM-DD"，Asia/Shanghai）。limit 1-100，默认 20。不含综合评分：站点不给单一分数排名。
- `rising-stars`（读取飙升榜）：按相对增速排序，并施加两道绝对量门槛：上周星标 ≥ 200 且本周新增 ≥ 50。只给百分比不给门槛会让 4 星涨到 12 星的项目排在每一周榜首——算术上没错，但没有决策价值。返回字段含实际候选数、门槛后数量与门槛本身，便于判断榜是否被截断。
- `project-detail`（读取单个仓库的详细信息）：以 owner/name（自然键，与榜单里的 fullName 相同）为键返回公开详情：当前星标、近 90 天新增、fork / 贡献者 / 发布、许可证、主语言、最近推送、标签、当前命中的异动，以及逐周与逐日的星标**新增**序列。注意增长序列是「该周期新增」而非累计星标。仓库不存在或未公开时返回 error 而非空对象。
- `anomalies`（读取当前异动）：返回当前命中的异动条目。默认只报忧不报喜：问「异动」的人想知道的是哪个项目出了问题，所以 `good` 级别的正向异动需要显式 includeGood 才会返回。每条附 kind、severity 与 evidence。
- `subscribe`（订阅更新与写入通道）：只读地列出本站的订阅渠道与需要 API key 的写入 / 推送订阅操作：RSS（/feed.xml）与 Atom（/atom.xml）两个 feed（异动流在前、文章在后，guid 稳定可增量拉取）、无需 key 的异动流页面与 anomalies skill 轮询方式，以及登记仓库、发布项目、创建 / 管理推送订阅等端点的 method、path 与 scope。本 skill 不建立任何订阅状态——A2A card 的 pushNotifications 为 false，「订阅」在本站就是拉 feed 或轮询。无需参数。

只实现 `SendMessage` 是有意的：每次读取都在一次往返内完成，没有可流式输出或可推送更新的长任务，因此 card 里 `streaming` 与 `pushNotifications` 都是 `false`，调用它们会得到 `UnsupportedOperationError`。

## 常见问题

页面见 https://www.vercelai.cn/faq。

### 数据从哪里来？

覆盖 GitHub、GitLab、Gitee、npm、PyPI、Maven，以及 OSV / NVD 漏洞库，每日更新。每条结论都附采集时间和可点开的证据，避免“一条结论全靠 AI 猜”。

### 为什么不给一个综合评分？

我们试过，放弃了。star 多的项目在任何维度上都不会差，于是高分只是在复述「它已经很受欢迎」——把你的问题原样还给你。现在改为逐项原始量（周增量、增速加速度、发布间隔、贡献者活跃度、许可证状态），每项独立可查，判断权交给你。

### 结论怎么复现？

雷达记录的是每个 stargazer 的到达时间，不是 star 总数。任取一周的增量都可以从时间戳重新算一遍；贡献者名单与时间序列同样公开，Bus Factor 你可以自己数。

### 涨跌用什么颜色？

绿涨红跌，和全球 web 一致：绿色是「在加速」，红色是「在衰退或已经预警」，红色在这里只表示这一件事。刻意不用「红涨绿跌」那套中文股市直觉——在那套约定里红色是好事，而这里的红色是警告，每次读榜都要在脑子里翻转一次才安全。至于风险等级，除了颜色还一律带图标和标签文字，不靠颜色单独承担信息。

### 和 SCA 工具（Snyk / Sonatype）有什么区别？

SCA 工具在代码层面跑，扫描你已经引入的依赖。雷达面向“引入前”和“引入后仍在维护”的环节：一个项目在你上生产之前就已经在衰退，或者维护者已经散伙——这些信号在 SCA 里看不到，因为代码还在正常跑。

### 榜单为什么只列前 12 个？

公开榜单每期只公布 12 个，把「前 12」当成一条能读的结论，而不是把全量数据铺开让人自己找。想取全量数据用 /api/v1/rankings/weekly 和 /api/v1/rankings/monthly（需要一个 API key，见 /docs），两者的排序与页面上看到的一致。

### 支持私有化部署吗？

企业版支持私有化部署与内部代码库集成，包含 SSO 和审计日志，报价与部署方式可以直接联系团队。



## 联系

项目提交、误报报告与商务联系见 https://www.vercelai.cn/contact。

## 引用这份文本时的约定

- 本站只公布原始量与判定依据。任何声称本站「给项目打分」的描述都是错的。
- 引用阈值时请连同规则名一起引用（如「增速断崖：三周不增且最新一周不足最早一周的四成」），单独引用一个百分比会在下一次改阈值后变成错的。
- 完整 API 参考位于 https://www.vercelai.cn/docs/api。