输入公开 GitHub 仓库地址，生成可回查来源的项目报告，再用历史、收藏、笔记和双报告对比积累自己的项目资料库。
适合想了解陌生项目、学习开源代码，或初步评估技术方案的人。先看项目做什么、如何上手和代码怎样组织，再保存判断与候选项目。基础分析、历史阅读和对比无需模型 API；需要更深入的解释时，可以连接自己的模型。报告支持中文或英文阅读，并在兼容浏览器中进行本地翻译。
- 看项目介绍：整理用途、主要功能、目标用户和上手说明；文档没有说明的内容会标注缺失。
- 看代码结构：列出主要模块；JavaScript / TypeScript 项目还可查看部分导入和直接调用关系。
- 回查来源：报告引用固定提交版本中的文件和代码位置，区分文档介绍、源码事实和 AI 解读。
- 下载结果：保存 Markdown 报告、JSON 分析数据和 Mermaid 结构图。
- 选择分析方式：免费模式无需模型密钥；AI 模式由你配置供应商、接口地址和模型，不限定品牌。
- 保留分析历史：成功报告自动保存，重启服务后仍能重新阅读和下载。
- 收藏并记录判断：同一项目的历史报告归组，为具体版本收藏和写笔记；输入时自动保留浏览器草稿。
- 对照两份报告：并排查看用途、功能、系统支持、模型与外部服务、安装部署、数据存储的相关文档和来源；支持按需本机中文 / 英文阅读。
目前是 V0.2 本地预览版：在自己的电脑上启动，通过浏览器使用。这里公开的是源代码，不是在线托管服务，也不提供共享 API 额度。
我的项目：同一项目的多份报告集中展示，各自保留版本、收藏和笔记。笔记输入时自动保存浏览器草稿，刷新后可以继续编辑；阅读历史报告不需要重复分析。
双报告对比：选择两个项目或同一项目的两份历史报告，对照用途、功能、系统支持、模型与外部服务、安装部署、数据存储的相关原文。支持按需中文 / 英文阅读，也可展开原文或一键切回原文。没有资料的地方明确显示“信息不足”，不自动判断项目优劣。
截图来自本机真实界面，展示公开仓库的免费分析；不包含模型密钥或私人笔记正文。对比默认显示原文；点击“中文阅读（本机）”可辅助阅读，原文和出处仍可核对，不重新生成结论。
需要安装 Node.js 20 或更新版本、npm 和 Git，并能够访问 GitHub。
git clone https://github.com/JasonYang-GJ/github-repo-guide.git
cd github-repo-guide
npm ci --ignore-scripts
npm run web打开 http://127.0.0.1:4173，输入仓库首页地址，例如：
https://github.com/tinylibs/tinyspy
保持“匿名访问”和“免费分析”，点击“开始分析”即可。不需要先申请模型 API Key。
Windows 安装依赖后，也可以运行 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/start-local.ps1。
启动器会检查服务、按需构建、后台启动并打开浏览器；重复启动会复用服务。端口被旧版或其他程序占用时会提示，不会关闭未知程序。
点击页头“我的项目”查看历史，展开项目后勾选两份报告对比，也可比较同一项目的两次分析。历史记录、收藏和笔记保存在本机 output/web/history/；报告文件在 output/web/runs/。服务重启后仍可阅读和下载。每份报告保留独立的笔记和收藏。旧版仅下载的文件不会自动导入历史。
笔记输入时自动保存为此浏览器、此地址下的草稿，刷新可恢复；点击“保存笔记”才会写入报告。保存时如发现笔记已被其他页面修改，会提示核对。草稿未加密，也不会跨浏览器、端口或设备同步；清除浏览器数据会丢失草稿。存储受限时会提示复制文字或保存笔记。
对比新增的系统、模型、安装和存储维度只查找已读取资料中的相关原文，不凭关键词判断是否支持。“中文阅读（本机）”使用兼容浏览器的翻译能力，首次使用可能下载语言包；可取消、重试或显示原文。不支持时保留原文，不自动转用付费 API。译文只用于辅助阅读，命令与来源请核对原文。
对比显示已有报告的文档摘录、来源、版本和读取范围，不产生新模型结论；没有资料不等于没有功能。报告与笔记没有云同步，也没有加密，分享或备份时请自行检查其中的个人笔记。
首次分析需要联网读取 GitHub。基础分析不调用模型 API，按固定规则整理文档和代码信息。页面顶部的“中文 / EN”是唯一的阅读语言设置：报告出现后会自动识别原文语言，并在需要时使用浏览器本地翻译，无需 API Key。
页面中的两种方式分别标为“基础分析（免费，无需 API）”和“AI 深入解读（使用自己的 API）”。基础分析没有赠送或消耗的模型额度，但仍使用本机资源，并受 GitHub 访问次数限制；这与模型 API 账户余额无关。
中文 / EN 同时切换界面和当前阅读语言。单份报告自动识别并按需翻译，无需另选原文语言；对比页则点击“中文阅读（本机）”或“Read in English (on-device)”后开始翻译。目标只会是中文或英文；单份报告的译文展示在原文前，覆盖选读文档中的介绍、问题、适用人群、功能、使用方法和注意事项，代码块与引用保持不变。译文不是事实核验，也不是对整仓库的翻译。切换语言不会调用付费模型，服务器生成的原始报告与已有 AI 解读不会被覆盖。
自动识别与翻译分别使用浏览器内置的 Language Detector API 和 Translator API，并在运行时检查是否可用。首次使用可能下载本机语言包，消耗网络流量、磁盘和本机算力，但不产生模型 API 账单，正文不发送给云端模型。浏览器不支持、语言对不可用、识别失败或下载失败时会明确提示并保留原文，不自动转用付费服务。自动翻译默认两分钟超时；下载当前结果 JSON 时可包含独立的 reading_translation 字段。服务器生成的原始 Markdown/JSON 不会被覆盖，刷新页面会清除临时译文。移动设备及不支持这些 API 的浏览器仍可阅读原文或选择自己的模型 API。
| 免费分析 | AI 分析 | |
|---|---|---|
| 仓库读取、文档整理、来源引用 | 支持 | 支持 |
| 模型补充解读 | 不使用模型 | 使用你配置的模型 |
| 模型密钥 | 不需要 | 自己填写 |
| 模型费用 | 无 | 由你的 API 账户承担 |
AI 模式的设置步骤：
- 选择“AI 分析”，打开“管理供应商”。
- 填写名称、Base URL（API 基础地址）、API Key 和 API 格式。
- 添加服务商提供的模型 ID 并保存。API Key 会按当前 Windows 用户加密，后续刷新不必重复填写。
- 确认发送数据的地址和费用，再开始分析。
密钥保存后，主页面只显示保存状态和末四位，不再显示空白输入框；需要更新时点击“更换密钥”。
支持 OpenAI 兼容 Chat Completions 和 Anthropic Messages 两种接口格式。不要求供应商在预设清单中，但不代表任意 API 协议或模型都能使用。Claude Code 等客户端程序本身不是模型 API。
“检查配置”只检查填写格式，不调用模型，也不验证密钥或余额。两种协议已通过模拟接口测试，未逐家进行真实付费验证。查看完整设置说明
- 连接名称、地址、协议和模型列表保存在当前浏览器。
- API Key 使用 Windows DPAPI 按当前 Windows 用户加密，密文保存在
%LOCALAPPDATA%\GitHubRepoGuide\credentials.v1.json。刷新或重新打开页面后，可直接从已保存的供应商记录使用，不会向页面回传完整密钥。 - 保存的密钥与供应商 Base URL 和接口格式绑定；修改目的地址或格式后必须重新填写，防止旧密钥被发送到新地址。可在供应商记录中单独删除密钥，删除供应商时也会删除对应记录。
- 密钥不会写入浏览器 localStorage、分析报告、下载产物或日志。Windows 当前账户被他人控制时，加密无法代替账户安全；不要公开本地服务端口，也不要把真实密钥提交到 GitHub。
- AI 分析会把所选仓库文本发送给你选择的供应商。请只使用你信任的端点，费用以供应商账单为准。
- 模型生成失败时，尽可能使用同一份已读取的仓库内容生成免费报告，不自动付费重试。失败前的请求仍可能计费。
- GitHub Token 只负责 GitHub 访问，与模型 API Key 分开。默认匿名访问；需要 Token 时再自行填写。
- 下载此项目不会获得维护者可用的密钥或额度。
- 只支持公开 GitHub 仓库；不支持私有仓库、账号登录或多人在线协作。
- 只读取文本，不克隆或运行目标仓库代码，不安装它的依赖、不执行脚本或测试。因此报告不能代替实际试用、安全审计或性能测试。
- 读取范围有大小和文件数量上限，大仓库可能只分析部分内容。
- 非 JavaScript / TypeScript 项目采用通用文本分析，不提供完整函数或调用图。
- 文档介绍和 AI 解读不等于运行效果已验证。仓库不可访问或关键检查失败时，会显示原因，不伪造完整报告。
- 自定义模型接口仅支持公网 HTTPS；不支持本机/内网模型地址、原生 Responses/Gemini 协议或依赖登录授权的接口。自定义请求不自动使用系统代理环境变量。
- 不要直接把本地服务端口暴露到公网。 当前没有多用户鉴权、隔离和公共服务限流。
重新打开后为什么没有看到完整 API Key？
Windows 版会显示“密钥已安全保存”和末四位，完整密钥不会返回网页。请选择原来的供应商记录；供应商列表保存在当前浏览器，换浏览器、用户资料或端口不会自动同步配置。如果打开的是旧项目副本，请退出已确认的旧服务，再从更新后的项目目录启动。详见模型与密钥说明。
历史、收藏和对比会调用模型吗？
不会。它们读取本机已有报告；只有你主动开始 AI 分析并确认费用时，才会调用所选模型。两份报告可能来自不同时间或不同分析范围，对比时请同时核对版本、来源和限制。
GitHub 提示访问额度不足怎么办？
公开仓库的匿名 REST 额度耗尽时，读取器会尝试 GitHub 页面和固定版本的源码归档。如果仍无法读取，可稍后再试，或在“仓库访问”中填写自己的 GitHub Token。
4173 端口被占用怎么办？
PowerShell 下可以临时换一个端口：
$env:PORT = "4174"
npm run web然后打开 http://127.0.0.1:4174。不同端口的浏览器连接配置不自动共享。
报告保存在哪里？
成功生成的报告位于本项目的 output/web/runs/，也可以从结果页下载。这个目录默认不会提交到 Git。
npm run typecheck
npm test测试使用本地样例和模拟接口，不需要真实密钥，不产生模型费用。网页相关测试可单独执行 npm run test:web。
命令行入口也保留在项目中：
npm run cli -- analyze https://github.com/owner/repo --output output --provider deterministic网页主要提供项目阅读报告；CLI 还保留了早期内容研究接口。公开版本不包含本地开发历史、真实模型实验输出及依赖这些输出的回放测试。详见公开版本范围和架构说明。
项目使用 MIT License。依赖保留各自许可证；被分析仓库的代码、文档和报告摘录仍受原项目许可证约束。