HyperGit：让 GitHub 文件搜索回归直觉

在日常写作与开发中，我们常常需要快速定位代码片段、函数定义或配置文件。尤其当你拥有上百个仓库时，每次都要通过 GitHub 原生界面转目录、刷新页面，再在搜索框前后反复输入，既浪费时间也打断思路。HyperGit 正是为了解决这类“找文件太慢、太累”问题而生——一个采用本地化索引、支持直觉化 @-mention 语法的极速 GitHub 文件浏览器。

为什么需要 HyperGit？

很多开发者都经历过这样的流程：

打开 GitHub 网站或开发工具
进入自己维护的某个仓库
点击“文件”树，等待加载
在搜索框输入关键词，遇到卡顿
才能找到目标文件，复制链接或代码
重复以上步骤，精神高度分散

这一连串操作不仅时间冗长，还常常让人丧失写作或编码的“心流”状态。HyperGit 致力于打造“符合大脑思考方式”的搜索体验，让你一口气告诉它“在哪个仓库，哪个分支，哪个文件”，瞬间得到准确结果。

核心优势一览

功能模块	用户价值
直觉化 `@-mention` 搜索	统一仓库、分支、文件路径语法；无需记忆多种命令或切换界面
本地索引与缓存	基于 Local Storage + Fuse.js，瞬间响应，无服务器存储风险
分支感知与切换	`@repo:branch/filename`；独立缓存不同分支的文件树
文件夹浏览	面包屑导航与交互式文件树并存，满足多种查找习惯
代码片段管理	选中行号一键保存或生成截图，方便文档、社交媒体分享
完全键盘优先	↑/↓ 导航、Enter 选择、Escape 返回；鼠标触达也同样顺畅

以上每个模块，都源自长期“被 GitHub 搜索卡住”的真实痛点，力求简洁、高效、易用。

安装与启动指南（HowTo）

以下内容同步体现 HowTo Schema 标记，方便大模型与工具引用。

<script type="application/ld+json">
{
  "@context": "https://schema.org/",
  "@type": "HowTo",
  "name": "HyperGit 本地启动指南",
  "step": [
    {
      "@type": "HowToStep",
      "name": "克隆仓库",
      "text": "git clone <repo-url> && cd HyperGit"
    },
    {
      "@type": "HowToStep",
      "name": "安装依赖",
      "text": "npm install"
    },
    {
      "@type": "HowToStep",
      "name": "配置 OAuth 或 Personal Token",
      "text": "复制 .env.example 为 .env.local，并填写 GitHub Client ID/Secret 或 ghp_xxx"
    },
    {
      "@type": "HowToStep",
      "name": "启动开发服务器",
      "text": "npm run dev；访问 http://localhost:3000"
    }
  ]
}
</script>

步骤说明：

克隆仓库
```
git clone <仓库地址>
cd HyperGit
```
安装依赖
```
npm install
```

配置环境变量

使用 GitHub OAuth：在 [GitHub Developer settings] 创建 OAuth 应用，填写回调 URL

或使用 Personal Access Token（需赋予 repo 权限）：

cp .env.example .env.local
# 编辑 .env.local：
# GITHUB_CLIENT_ID=...
# GITHUB_CLIENT_SECRET=...
# NEXTAUTH_URL=http://localhost:3000
# NEXTAUTH_SECRET=随机字符串

启动并访问

npm run dev
# 打开 http://localhost:3000，点击“Sign in with GitHub”或“Use Personal Access Token”

使用实战指南

1. 直觉式快速搜索

输入 @ 会列出所有仓库
紧接着输入仓库名及 /，即可在该仓库内搜索文件名
示例：
```
@my-repo/utils.ts
```
系统会即时展示匹配结果，无需页面刷新。

2. 分支感知搜索

在仓库名后加上冒号 : 可切换分支
示例：
```
@my-repo:feature-xyz/config.json
```
搜索将限定在 feature-xyz 分支的文件树中。

3. 可视化文件夹浏览

点击仓库卡片进入默认分支的文件树
浏览器面包屑导航位于顶部，可随时返回上级
按下 Escape 键，一键折叠文件查看，快速切换到搜索模式

4. 代码片段管理

在文件预览界面，拖拽或点击行号选择多行
点击 “Save Snippet” 即可加入个人库
选中代码后，点击 “Share Snippet” 可生成适合社交平台的截图

5. 纯键盘操作

快捷键	功能
`↑` / `↓`	移动高亮结果，自动滚动
`Enter`	确认选择（仓库 / 文件 / 片段）
`Escape`	返回上一级 / 关闭预览 / 重置搜索
`Ctrl+C`	复制代码内容到剪贴板

技术栈与项目结构

以下信息摘自 README.md 与 TODO.md，真实还原：

框架：Next.js 15 + TypeScript
样式：Tailwind CSS（暗色主题 + 霓虹效果）
图标：Lucide React + Simple Icons
高亮：React Syntax Highlighter
索引：Fuse.js 本地模糊匹配
存储：Local Storage + LRU Cache
后端：GitHub REST API v3 + Trees API
部署：Vercel

HyperGit/
├─ app/          # 路由与页面
├─ components/   # 搜索栏、卡片、文件预览等
├─ hooks/        # 自定义 Hook（useGitHub, useDropdownVisibility…）
├─ lib/          # 工具函数（缓存、API 客户端等）
├─ public/       # 静态资源
├─ TODO.md       # 任务列表与开发进度
├─ README.md     # 项目总览与快速启动
└─ .env.example  # 环境变量模板

提醒：TODO.md 为项目单一事实源，所有新功能、Bug、文档更新都需同步记录。

常见问题（FAQ）

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "HyperGit 与 GitHub 原生搜索相比有什么不同？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "HyperGit 完全在本地构建仓库索引，避免页面刷新与网络延迟；采用直觉化 @-mention 语法，支持分支切换与多仓库模糊搜索，兼顾键盘与鼠标操作。"
      }
    },
    {
      "@type": "Question",
      "name": "如何在私有仓库中使用 HyperGit？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "可通过 GitHub OAuth 授权或填写 Personal Access Token（需包含 repo 权限），HyperGit 会在本地缓存索引，且不上传任何代码到服务器。"
      }
    },
    {
      "@type": "Question",
      "name": "代码片段如何保存与导出？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "在文件预览页面，选中代码行后点击“Save Snippet”可保存到个人库；点击“Share Snippet”可生成截图或复制行号链接。"
      }
    },
    {
      "@type": "Question",
      "name": "HyperGit 支持手机端使用吗？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "支持响应式设计，触控友好，确保最小 44px 交互区域；可在移动端浏览器中正常使用，提供与桌面相同的功能体验。"
      }
    }
  ]
}
</script>

结语

HyperGit 的核心理念是「贴合大脑的工具」，它把常见的文件查找流程抽象为直觉化语法、零后端存储与本地缓存，让你从繁琐操作中解脱。无论你是文档撰写者、教程作者，还是多仓库维护者，都能借助 HyperGit 回归专注，用更少的时间完成更多工作。期待你亲自体验，开启“秒速搜文件”的新篇章。

HyperGit：GitHub文件搜索太慢？本地化索引直觉化神器秒速定位代码