Skip to content
BranchesTags

Repository files navigation

GitHub Picks

GitHub Picks 是一个中文开源项目情报引擎：从多个发现源持续收集候选仓库，再用 GitHub 事实、工程健康度、组织质量和风险证据生成每日榜单与中文分析。它不把 Star 总量直接等同于项目价值。

GitHub Picks 是独立、非官方项目，与 GitHub, Inc. 不存在隶属或合作关系。当前 v0.1.0 评分仍是实验版本，不能替代正式的技术选型、安全审查或许可证审查。

当前完成范围

当前仓库已经跑通数据与网站两段纵向闭环：

  1. 多信源发现候选项目；
  2. 获取 GitHub 仓库事实和近期事件；
  3. 获取可用的 OpenSSF Scorecard 结果；
  4. 计算八维评分、置信度和独立风险扣分；
  5. 生成综合榜、趋势榜、新项目榜、隐藏宝石榜、活跃榜和五个方向榜；
  6. 输出可回放的 JSON、中文 Markdown 和运行清单；
  7. 用本地 AI 模型基于事实包生成逐项目推荐理由，并记录模型、Prompt 版本、分析版本和证据哈希；
  8. 从实时日报历史静态生成今日榜、近 7/30/90/180 天持续价值榜和逐日历史查询；
  9. 生成五个方向榜、仓库分析页和信源状态页；
  10. 通过桌面/移动端导航、WCAG AA 自动扫描和 GitHub Pages 构建门禁；
  11. 从同一批 live 日报生成匿名只读的静态 v1 API；
  12. 提供可安装的 github-picks Agent Skill，用中文查询最新、周期、方向、历史和仓库证据。

网站、公开 API 和 Agent 都以稳定的 report.json 契约为唯一事实入口，不重复计算分数。Agent 个性化只做可解释的保序筛选，不生成新的排行榜。Obsidian 接入、定时推送和其他外部投递仍是独立的后续能力。

快速开始

要求 Node.js 24.15.x 和 pnpm 11.18.0。

nvm use
pnpm install

先跑不访问网络的证据回放：

pnpm picks:daily --date 2026-08-03 --mode replay

再跑当天实时采集：

pnpm picks:daily

推荐为持续运行提供 GitHub Token，减少匿名额度不足造成的降级：

GITHUB_TOKEN="$(gh auth token)" pnpm picks:daily

如需生成并强制校验 AI 推荐理由，可连接本机 Ollama；模型不可用或任一输出未通过事实边界校验时，本次运行不会覆盖既有日报：

GITHUB_TOKEN="$(gh auth token)" \
GITHUB_PICKS_AI_MODEL="qwen3-vl:8b" \
GITHUB_PICKS_AI_REQUIRED=true \
pnpm picks:daily

未配置模型时，流水线会明确标记 ai-analysis: degraded 并展示“规则事实摘要”，不会把规则拼接冒充为 AI 结果。

默认结果写入 artifacts/daily/YYYY-MM-DD/。可用 --output、--config、--raw 和 --replay-manifest 显式指定路径。

正式发布先写入隔离目录并执行确定性门禁，避免失败运行覆盖已发布日报：

report_date="$(TZ=Asia/Shanghai date +%F)"
daily_stage_dir="$(mktemp -d)"
GITHUB_TOKEN="$(gh auth token)" \
GITHUB_PICKS_AI_PROVIDER=ollama \
GITHUB_PICKS_AI_MODEL=qwen3-vl:8b \
GITHUB_PICKS_AI_REQUIRED=true \
pnpm picks:daily --date "$report_date" --mode live --output "$daily_stage_dir"
pnpm picks:publish-check -- "$daily_stage_dir" "$report_date"

当前维护实例通过本地 Codex 自动化在北京时间每天 10:00、14:00、20:00 执行上述正式发布链路。本机、Codex 或 Ollama 不可用时会明确失败且不补造错过的历史观测；产物提升、Git 提交和 Pages 验证步骤见每日数据流水线。

启动中文网站：

pnpm --filter @github-picks/web dev

本地地址为 http://localhost:3000/。生产静态导出使用：

pnpm --filter @github-picks/web build

产物位于 apps/web/out/；Pages 子路径、自定义域名和失败恢复见静态网站运行手册。

网站时间入口：

  • /：最新实时日报；
  • /rankings/7d/、/rankings/30d/、/rankings/90d/、/rankings/180d/：周期持续价值榜；
  • /history/：按已存档日期查询；
  • /history/YYYY-MM-DD/：指定日期的不可变日报快照；
  • /agent/：安装、验证并使用 GitHub Picks Agent Skill。

周期榜不重算每日发布分。它先比较窗口内的上榜覆盖率，再比较平均发布分和平均名次，并明确展示实际日报覆盖天数。历史不足 30/90/180 天时不会把缺失日期当成零分。

Agent 与公开 API

公开 API 基址为 https://aicode-nexus.github.io/github-picks/api/v1，由 Pages 构建从已校验的 live 日报确定性生成。常用入口包括：

  • reports/latest.json：最新日报；
  • reports/index.json 与 reports/YYYY-MM-DD.json：历史索引和指定日期；
  • rankings/7d.json、30d.json、90d.json、180d.json：周期榜；
  • directions/{direction}.json：五个技术方向的最新榜；
  • repositories/{owner}/{repo}.json：已收录仓库的最近事实和历史观测。

网页教程位于 https://aicode-nexus.github.io/github-picks/agent/，包含安装、示例提问、验证和故障排查。

安装兼容 Codex 的项目级 Skill：

DISABLE_TELEMETRY=1 npx -y skills@1.5.21 add AICode-Nexus/github-picks \
  --skill github-picks --agent codex --yes --copy

把 --global 加到命令中可安装为用户级 Skill。安装后可直接提问：

  • “今天最值得关注的 5 个 GitHub 开源项目是什么？说明理由和风险。”
  • “近 30 天安全与软件供应链方向有哪些持续值得看的项目？不要按 Star 重排。”
  • “比较 owner/repo-a 和 owner/repo-b 的工程成熟度和公开风险证据。”

Skill 只访问固定域名下的匿名只读 API，不需要 GitHub Token、API Key、Cookie、账号、私有仓库或本地文件。公共排名由日报决定；方向、语言和场景偏好只产生原榜的保序子集。完整端点、Schema 版本、发布校验与恢复步骤见 Agent 与公开 API 运行手册。

评分框架

总分由八个维度构成，权重固定在 config/picks.yaml：

维度 权重 主要判断
实用价值 18 问题边界、文档入口、主题和交付信号
活跃度 18 活跃日、真人参与者、事件多样性和近期推送
组织与维护者 15 组织身份、连续维护、参与者和治理代理信号
工程质量 14 许可证、Scorecard、评审和发布实践
真实采用 10 Fork、Watcher、参与者和独立讨论，而非只看 Star
安全与合规 10 许可证、Scorecard、安全策略和生命周期
趋势动量 10 Star 速度、外部榜单位置和独立社区讨论
创新与时效 5 项目年龄、近期交付和生态扩展性

Star 存量对总分的最大直接贡献为 1.5 分，Star 速度最大直接贡献为 3 分。高频出现的优质组织和持续维护会加分，但综合榜同一组织最多保留两个项目。缺失事实采用中性先验并降低置信度；许可证缺失、长期停更和归档等明确事实进入独立风险通道。

当前信源

实际运行中的发现源包括 GitHub Trending、GitHub Search、GitTrend、HubLens、Hacker News 和 AI Hot；配置候选仅在外部源降级时保障五个方向都有可采项目，不提供榜单名次、速度或独立信源加分。AI Hot 通过匿名 v1 API 补充过去 24 小时内直接指向 GitHub 仓库的 AI 资讯信号；媒体文章和无法严格映射 owner/repo 的内容不会进入候选池。AI Hot 的时间顺序与条目分数不参与仓库评分。

事实层当前使用 GitHub REST 和 OpenSSF Scorecard。AI 推荐理由只消费这份已结构化事实包，不参与打分或改变名次；网站会区分“AI 推荐理由”和降级后的“规则事实摘要”。

更完整的端点、额度、降级和恢复说明见 docs/runbooks/daily-pipeline.md。首次实时运行与修复后的对照见 docs/research/daily/2026-08-03-first-live-run.md。已提交实时日报历史见 artifacts/daily/。

工程结构

config/picks.yaml                 方向、信源、权重和限额
packages/picks-core/              数据契约、评分、分析和榜单
workers/daily/                    采集、原始快照、补全和日报流水线
apps/web/                         Next.js 中文静态情报网站
.agents/skills/github-picks/      可安装的 GitHub Picks Agent Skill
artifacts/daily/                  可提交的 JSON/Markdown 日报
artifacts/raw/                    不提交的内容寻址原始响应
.github/workflows/pages.yml       GitHub Pages 验证与部署
docs/runbooks/                    运行与故障恢复说明
docs/research/                    观测证据和验证记录

artifacts/daily/ 同时是网站的历史存储边界：只读查询层会排除 mode: replay，同一天存在多次实时运行时只公开 generatedAt 最新的一份。历史索引与周期榜均在静态构建时生成，浏览器不会直接读取文件系统或重新评分。

验证

pnpm format
TURBO_FORCE=true pnpm check
pnpm --filter @github-picks/web test:e2e

仓库使用证据回放测试保证离线可复现；实时报告始终标记采集模式、生成时间和信源健康状态。网站构建只接受最新的 mode: "live" 报告，回放数据永不公开发布。

About

Evidence-driven GitHub open-source intelligence and daily recommendations

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages