GitHubChoice

GitHubChoice 是一个本地优先的 GitHub 项目发现网站。它不要求用户先写出准确的搜索词，而是通过双卡二选一、收藏和跳过，逐步学习用户对技术方向、编程语言和项目作者的偏好。

用户数据默认只保存在浏览器中；GitHub 或模型服务不可用时，网站仍可使用内置项目与本地摘要继续工作。

项目预览

阅读导航

• 第一次使用：从快速开始开始，不需要先配置密钥。
• 希望长期保存 Token 或 API Key：阅读密钥配置（可选）。
• 启动或配置没有生效：查看常见问题。

功能特性

• 双卡探索：从两个项目中选择更感兴趣的一项，保留胜者并替换另一张卡片。
• 可解释推荐：根据 Topics、语言和作者权重排序，并展示推荐理由。
• 避免重复：已展示项目会被记录，喜欢、跳过和撤销不会让它重新进入推荐池。
• 收藏与导出：管理收藏项目，并将收藏列表导出为 JSON。
• README 分析 Agent：可选使用 OpenAI Responses API 或兼容的 Chat Completions API，生成中文用途总结和典型落地场景。
• 离线兜底：GitHub API 不可用时使用内置精选项目；未配置模型时使用项目元数据摘要。
• 本地优先：偏好、收藏和浏览历史保存在浏览器 localStorage，无需注册或登录。
• 响应式与无障碍适配：支持窄屏布局，并遵循 reduced motion、reduced transparency 等系统偏好。

快速开始

如果你不熟悉命令行，并且使用 Windows，请优先选择“一键启动”。首次运行不需要配置任何 Token 或 API Key。

Windows 一键启动

1. 安装 Node.js 22.13.0 或更高版本。
2. 下载项目 ZIP 并解压，或者使用 Git 克隆本仓库。
3. 打开解压后的 GitHubChoice 文件夹。
4. 双击 start-githubchoice.bat。

脚本会在首次运行时执行 npm ci 安装依赖，然后启动本地服务，并在网站就绪后自动打开 http://localhost:3000。运行期间请保留命令行窗口；在窗口中按 Ctrl+C 可停止服务。

脚本固定使用 3000 端口。如果端口已被占用，它会提示你先关闭占用该端口的程序。

命令行启动

环境要求：Node.js >=22.13.0，以及随 Node.js 安装的 npm。

git clone 
cd GitHubChoice
npm ci
npm run dev

然后访问 http://localhost:3000。`` 请替换为仓库发布后的实际地址。

密钥配置（可选）

不配置任何密钥也能使用：GitHub 请求会使用匿名额度，README 区域显示根据项目元数据生成的基础摘要。只有在你希望查看更多不同项目，或希望 Agent 阅读 README 并生成更具体的中文介绍时，才需要继续配置。

Token 和 API Key 可以理解为服务生成的专用密码，用来证明请求来自你的账户。任何拿到它的人都可能消耗你的额度，因此不要公开或发送给他人。

应该选哪种配置方式

配置优先级为：当前标签页的网页配置 > 服务端 .env.local > 无密钥兜底。网页中显示“使用服务端配置”时，只表示没有使用网页临时配置；出于安全考虑，网站不会显示服务端保存的 Token 或 Key。

方法一：长期保存到 .env.local（推荐）

.env.local 是项目根目录中的本地配置文件。它与 README.md、package.json 位于同一文件夹，并已被 .gitignore 忽略，不会正常提交到 Git 仓库。

.env.local 适用于在自己电脑上运行项目。部署到 Cloudflare 或其他托管平台时，应在平台的 Secrets 或环境变量设置中填写相同变量，不要把 .env.local 上传到服务器或提交到仓库。

1. 先关闭正在运行的 GitHubChoice。
2. 在项目根目录复制配置模板。

Windows PowerShell：

Copy-Item .env.example .env.local
notepad .env.local

macOS 或 Linux：

cp .env.example .env.local

也可以直接复制 .env.example 文件，并将副本重命名为 .env.local。如果 Windows 没有显示文件扩展名，请在文件资源管理器中开启“查看 → 显示 → 文件扩展名”，避免文件实际变成 .env.local.txt。

3. 在 .env.local 中填写自己的值：

# 可选：提高 GitHub Search API 限额
GITHUB_TOKEN=你的_GitHub_Token

# 可选：启用 README Agent
OPENAI_API_URL=模型服务的_API_URL
OPENAI_API_KEY=模型服务的_API_Key
OPENAI_MODEL=模型服务的模型名称

4. 保存文件，重新运行 start-githubchoice.bat 或 npm run dev。环境变量只在服务启动时读取，因此不重启不会生效。

填写时注意：

• = 两边不要加空格。
• 不要保留“你的_”等示例文字，也不要填写尖括号。
• 一般不需要给 Token 或 Key 加引号。
• GitHub Token 与 Agent 配置可以只配置其中一项。
• 不要把真实密钥发给他人、贴到 Issue、截图或提交到 Git。

获取 GitHub Token

1. 登录 GitHub，打开 Personal access tokens 设置。
2. 创建一个新 Token。这个项目只读取公开仓库，建议使用权限最小、有效期较短且可随时撤销的 Token。
3. GitHub 只会完整显示 Token 一次，请立即将它填入 .env.local 的 GITHUB_TOKEN= 后面。

配置 Token 后，GitHub Search API 通常仍有约 30 次/分钟的认证限额，并不代表项目数量永远不会耗尽。应用会缓存每次取得的候选，因此正常使用时请求频率远低于每次点击一次请求。

配置 README Agent

1. 在支持 OpenAI-compatible API 的模型服务商处获取 API URL、API Key 和模型名称，并确认账户可以正常使用 API。
2. 将 base URL 或完整端点填入 OPENAI_API_URL= 后面。
3. 将 Key 填入 OPENAI_API_KEY= 后面。
4. 将模型名称填入 OPENAI_MODEL= 后面。模型调用可能产生费用，具体以服务商计费页面为准。

服务端与网页端使用相同的 URL 规则：完整地址以 /responses 结尾时使用 Responses API，以 /chat/completions 结尾时使用 Chat Completions API；只填写 base URL 时自动补全 /chat/completions。如果不填写 OPENAI_API_URL，则保留原有行为，使用 OpenAI 官方 Responses API 地址。

方法二：在网页设置中临时配置

1. 启动 GitHubChoice。
2. 打开页面顶部的“设置”。
3. 在“GitHub API”中填写 GitHub Token，或在“README 分析 Agent”中填写 API URL、API Key 和模型。
4. 点击对应的保存按钮。保存后只显示 Key 或 Token 的末四位，不会再次显示完整内容。

网页配置保存在当前标签页的 sessionStorage：

• 刷新当前页面通常不会丢失。
• 关闭标签页、关闭浏览器、结束无痕窗口或清除网站数据后会丢失。
• 网页配置优先于 .env.local；点击“改用服务端配置”即可清除临时配置。
• GitHub Token 只通过同源请求临时交给服务端；Agent Key 只在发起摘要请求时使用。两者都不会进入偏好数据、日志或收藏导出文件。

自定义 Agent URL 的规则：

• 完整地址以 /responses 结尾时使用 Responses API。
• 完整地址以 /chat/completions 结尾时使用 Chat Completions API。
• 只填写 base URL 时自动补全 /chat/completions。
• API URL 必须使用 HTTPS；本机服务可使用 localhost、127.0.0.1 或 ::1 的 HTTP 地址。

工作方式

1. 首次进入时从 14 类方向中选择 2–5 个兴趣标签。
2. 应用从 GitHub Search API 或内置目录取得候选项目。
3. 比较、收藏和跳过操作调整 Topics、语言与作者权重。
4. 候选项目按当前画像评分，同时保留一定探索空间。
5. 同一项目连续胜出 3 次后，两张卡片都会刷新，避免推荐停滞。

推荐逻辑位于 app/lib/preference.ts，规则与权重均可直接检查，不依赖远程用户画像或向量数据库。

项目结构

app/
  api/projects/route.ts  # GitHub 项目搜索与内置数据兜底
  api/summary/route.ts   # README 获取及模型摘要
  lib/                   # 项目目录、数据类型和偏好算法
  GitHubChoiceApp.tsx    # 主要界面与本地状态
tests/                   # 偏好算法、Agent API 和渲染测试
worker/                  # Cloudflare Worker 入口
start-githubchoice.bat   # Windows 一键启动脚本

开发命令

提交改动前建议运行：

npm run build
npm test
npm run lint

数据与安全

• 浏览器持久化键为 githubchoice:v1。清除该站点的浏览器存储会删除偏好、历史和收藏。
• 服务端的 GITHUB_TOKEN 和 OPENAI_API_KEY 不会发送到浏览器。
• 设置页输入的 GitHub Token 与 Agent Key 仅保存在当前标签页的 sessionStorage，不会进入用户状态或导出文件。
• 仓库 README 被视为不可信外部内容；分析提示会要求模型忽略其中的操作指令。
• OpenAI Responses API 请求使用 store: false。
• GitHub 或模型请求失败不会阻断核心浏览流程。

常见问题

我完全不懂 Token 和 API Key，可以跳过配置吗？

可以。直接运行项目即可。GitHubChoice 会使用 GitHub 匿名 API、内置候选和基础摘要，不会因为缺少密钥而无法使用。

双击脚本后提示找不到 Node.js

安装 Node.js 22.13.0 或更高版本，关闭已打开的命令行窗口，再重新双击脚本。

提示端口 3000 已被占用

关闭正在使用 3000 端口的本地服务后重试。也可以通过命令行使用其他端口：

npm run dev -- --port 3001

可以只配置 GitHub Token 或只配置 README Agent 吗？

可以，两项配置互不依赖。只配置 GITHUB_TOKEN 会提高 GitHub API 额度，但仍使用基础摘要；只配置 OPENAI_API_URL、OPENAI_API_KEY 和 OPENAI_MODEL 会启用 README Agent，而 GitHub 项目搜索继续使用匿名额度。

为什么修改 .env.local 后没有生效？

先确认文件位于项目根目录、名称不是 .env.local.txt，并检查 = 两边没有空格。然后完全停止并重新启动 GitHubChoice，因为服务只在启动时读取环境变量。

刷新或重启后，网页设置里的 Token 不见了怎么办？

刷新同一标签页通常会保留配置；关闭标签页或浏览器后可能丢失。如果希望长期保存，请改用 .env.local。不要为了省事把 Token 写进浏览器 localStorage。

配置 GitHub Token 后还会出现候选轮换吗？

仍有可能。Token 会提高 API 限额，候选缓存也会减少请求次数，但 GitHub Search 仍有速率限制和结果数量上限。网络故障、筛选条件过窄或大量项目已经展示过时，应用仍可能使用内置候选或轮换较早项目。

当前范围

项目目前是本地优先的 MVP，尚未提供账号登录、多设备同步、向量推荐或 GitHub OAuth。当前进度和后续计划见 PROJECT_STATUS.md。