GitHub Trending Overlay

这是一个 Pi extension：通过 /github-trending 打开一个自适应终端窗口的 overlay，浏览 GitHub Trending，并由 AI 模型归纳每个项目的概述 / 功能 / 场景。

/github-trending                 # 今日全部语言
/github-trending typescript      # 今日 TypeScript
/github-trending python weekly   # Python 本周趋势
/github-trending go --no-ai      # 跳过 AI 分析，只显示页面原始简介

AI 归纳（本版本重点）

每个仓库展示三段由当前会话模型现场归纳的中文内容：

| 字段 | 内容 | 生成要求 | | --- | --- | --- | | 概述 | 这个项目是做什么的、解决什么问题 | 45-80 字，一句话说清 | | 功能 | 核心功能/能力要点 | 3-5 点，60-120 字，具体到能力而非形容词 | | 场景 | 适用的领域、使用场景、对什么工作有帮助 | 40-90 字，给出明确判断 |

实现细节：

• 分析依据是 仓库名称 + 页面简介 + 语言/star + README 摘要（小节标题 + 正文开头），而不是让模型照抄 README；
• 提示词明确禁止输出"未明确/未提供/N/A"这类占位内容，也禁止把语言列表、徽章、安装命令当成项目概述（这正是旧版本的噪声来源）；
• 返回内容会做校验：空字段、占位符、损坏 JSON 都会被丢弃，对应仓库标记为分析失败并提示重试；
• 每批 6 个仓库合并成一次模型调用，最多 5 个 README 并发抓取，结果写入 ~/.pi/agent/cache/github-trending-analysis.json（默认 7 天有效），再次打开不再重复调用模型；
• README 走 raw.githubusercontent.com 而不是 GitHub API，避免消耗未认证的 60 次/小时配额；
• 选择模型顺序：环境变量 PI_TRENDING_MODEL（provider/modelId）→ 可用且已鉴权的轻量模型（deepseek-flash / haiku / flash / mini）→ 当前会话模型。

自适应布局

• Overlay 使用终端宽度的 96%、顶部对齐，高度取 终端行数 - 8，底部固定留 8 行给 pi 的输入框与状态栏，不会再盖住输入区；render() 每次都会重新读取终端行列数，缩放窗口后自动重排；
• 概述/功能/场景全部按显示宽度换行（中英文混排都不切断），不再出现 ... 截断；仓库名与 star/语言信息在窄窗口下也会自动折到第二行；
• 可见仓库数量由窗口高度决定；选中项能放下就整块显示，放不下就钉在块首（保证总能看到项目名与序号），↑/↓（或 j/k）移动选择时自动滚动；
• 顶部右侧显示 已完成/总数 或 AI 分析进度，底部快捷键提示在窄窗口下按优先级取舍，不会显示成省略号。

视觉分层

• 每个项目一组底色：从主题自身的面板底色出发，按 6 个色相循环叠色（约 22% 强度），相邻项目一眼可分；
• 同一项目内的概述 / 功能 / 场景三层底色：叠色强度递增（10% / 17% / 24%），既区分条目又不抢文字对比度；
• 选中项目底色加强到 42%，配合 ▸ 标记 与 accent 色加粗项目名；
• 每个项目带递增序号（1. 2. … 右对齐补位），项目名 加粗 + accent 色；
• 底色只针对内容区，且每行以 \x1b[49m 收尾，不会渗到边框或下一行；亮色/暗色主题会自动适配（从主题的 customMessageBg 解析出基线色再判断亮暗）。
• 如果终端渲染底色异常，可用 PI_TRENDING_BG=off（或标准的 NO_COLOR）关闭全部底色。

快捷键

| 键 | 作用 | | --- | --- | | ↑/↓、j/k | 切换仓库，自动滚动 | | PgUp/PgDn、u/d | 翻页 | | Home/End、g/G | 跳到首/尾 | | Enter | 把选中仓库的 URL 填入输入框 | | r | 重新抓取（同时重跑未命中缓存的分析） | | Esc/q | 关闭 |

其他

• 支持 daily、weekly、monthly，默认 daily；语言参数直接对应 GitHub Trending 的语言过滤；
• --no-ai（或 -n）关闭 AI 分析，只显示 Trending 页面原始简介；
• Trending 页面使用内存缓存 + ETag/Last-Modified 条件请求，5 分钟内不重复抓取；
• 请求使用固定的现代 Chrome 文档请求头（Accept、Accept-Language、Sec-Fetch-*、Client Hints），不伪造 Cookie、登录态、代理或其他反爬绕过信息；GitHub 的限流和访问策略仍然适用。

环境变量

| 变量 | 作用 | | --- | --- | | PI_TRENDING_MODEL | 指定分析用的模型，格式 provider/modelId | | PI_TRENDING_CACHE | 覆盖分析缓存文件路径（便于测试） | | PI_TRENDING_BG | 设为 off 关闭项目/条目底色（NO_COLOR 同样生效） |

安装

pi install npm:@ganziliang/pi-github-trending-overlay
# 或从本地目录安装
pi install ./github-trending-overlay

开发调试：

pi -e ./github-trending-overlay/extensions/github-trending.ts

测试

覆盖三块不依赖网络与真实模型的行为：换行算法、Trending/README 解析与 AI 输出校验、overlay 在多种终端尺寸下的排版（含底色分层、序号与加粗、输入区留白），以及"抓 README → 分批调用模型 → 缓存 → 失败/中断"整条链路（模型与网络均为桩）。

npm test

需要 Node 22.7+（使用内置 --experimental-transform-types）。如果解析不到 @earendil-works/pi-tui，用 PI_TUI_PATH 指向它的 dist/index.js。