ThierryRakotomanana/GitCharta

## 📖 目录 - [概述](#-overview) - [安全与隐私](#-security--privacy) - [核心功能](#-key-features) - [技术栈](#-tech-stack) - [前置条件](#-prerequisites) - [快速开始](#-quick-start) - [用法](#-usage) - [工作原理](#-how-it-works) - [路线图](#-roadmap) - [贡献](#-contributing) - [许可证](#-license) - [作者与联系方式](#-author--contact) ## 🎯 概述 ### 痛点 GitHub 只提供原始的关注者和正在关注列表：让你一无所知。它们无法展示你的社交网络实际上有什么共同文化，或者你的影响力延伸到了哪里，而且你很容易就会跟丢那些**非互惠关系**：你关注了但对方从未关注你的账号。 ### 解决方案 **GitCharta** 将你的社交网络数据转化为一张可探索的世界地图。只需指定任何 GitHub 账号，它就会绘制出： - 🌍 你的**受众**在物理位置上的分布 - 🌍 你**学习对象**的所在地 - 👻 他们之中哪些是**幽灵粉**：没有任何互惠的单向关注（没有关注你） 你不需要任何准备工作即可尝试：只需一个用户名，共享的速率限制演示 token 就能为你生成地图。当你想要更高的限制时，随时添加你自己的 Personal Access Token；关于这究竟会改变什么以及不会改变什么，请参阅[安全与隐私](#-security--privacy)。 ### 为什么这很重要 | 对象 | 价值 | | ------------------------------------ | ------------------------------------------ | | **开源维护者** | 了解你的项目的地理覆盖范围 | | **正在拓展人脉的开发者** | 发现与你的作品互动的人群模式 | | **任何对自身社交图谱感兴趣的人** | 清理你不再需要的单方面“关注” | ## 🔒 安全与隐私 将 token 粘贴到随机网站通常是不明智的建议，因此这里详细说明了每种模式的具体工作原理，以及你该如何亲自验证，而不是仅仅听信我们的一面之词。 ### 如果使用你自己的 PAT | 声明 | 含义 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **不涉及后端** | 请求直接从你的浏览器发送到 `api.github.com` 和 `api.github.com/graphql`。在此路径中永远不会调用 GitCharta 的后端。 | | **仅存于内存中** | 你的 PAT 仅存在于当前会话的 JavaScript 状态中：**不会**被持久化到 `localStorage`、`sessionStorage` 或 cookies 中。刷新或关闭标签页后即被丢弃。 | | **开源** | 不要只听信这份 README 的说明：阅读源码，或者 fork 并在本地运行。 | ### 如果不使用（演示模式） | 声明 | 含义 | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **无需 token** | 你只需一个 GitHub 用户名即可生成地图。 | | **服务端的共享 token** | 你的请求通过 GitCharta 的后端进行中继，该后端会附加一个由所有演示用户共享的服务器端 token。在高负载下预计会出现节流限制。 | | **无需暴露个人信息** | 在这种模式下你没有提供任何凭据，因此后端不可能泄露属于你的 PAT。 | 你可以随时切换模式：在会话中途粘贴 PAT，GitCharta 就会在该会话的剩余时间内完全弃用后端。 **在粘贴任何 token 之前，请自行验证：** 1. 打开浏览器的 DevTools → **Network** 标签页。 2. 粘贴 token（最好是仅具有 `read:user` 权限的一次性 token）并生成地图。 3. 确认每一个附加了你的 token 的传出请求都只发送到了 `api.github.com` / `api.github.com/graphql`。一旦提供了 PAT，发往 GitCharta 自身后端的请求应该完全消失。 ## ✨ 核心功能 | 类别 | 描述 | | ----------------- | -------------------------------------------------------------------------------------------------------- | | 👥 **关注者** | 关注你的开发者的地理分布 | | 🔭 **正在关注** | 你关注并从中学习的人的所在地 | | 👻 **幽灵粉** | 非互惠关系：你关注但未关注你的账号 | | 📍 **未知位置** | 专门为没有可用公开位置的账号提供的视图，这样就不会有人凭空从地图上消失 | | 📊 **统计数据** | 一目了然的数字：映射的账户总数、热门国家、幽灵粉比例等 | ## 🛠️ 技术栈 | 层级 | 技术 | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 前端 | `React, Vite, TypeScript` | | 地图 / 可视化 | `Custom Geocoding & D3` | | 数据源 | [GitHub GraphQL API](https://docs.github.com/en/graphql) (主要) + [GitHub REST API](https://docs.github.com/en/rest) (填补 GraphQL 遗漏的字段) | | 后端 (演示 token 代理) | `TBD` ：一个仅将共享 token 保留在服务端的小型 serverless 函数 | | 托管 / 部署 | `Vercel` ：静态前端，外加用于演示 token 后端的 serverless 函数 | | 包管理器 | `npm` | ## ✅ 前置条件 开箱即用，无需任何前置条件。GitCharta 内置了一个共享的演示 token，因此只需指定一个 GitHub 用户名即可工作，你无需进行任何设置：只是在所有演示用户之间有速率限制。 可选，如果你想要更高的限制或完全跳过后端： - 一个 **GitHub Personal Access Token (PAT)** ：见下文。 ### 生成 Personal Access Token（可选） 1. 前往 **GitHub → Settings → Developer settings → Personal access tokens**。 2. 生成一个具有以下 scope 的新 token： | Scope | 为什么需要它 | | ----------- | --------------------------------------------- | | `read:user` | 读取你的个人资料以及关注者/正在关注数据 | ## 🚀 快速开始 ### 选项 A：使用在线应用（最快） 无需安装，无需 token。打开 **[github-audience-atlas.vercel.app](https://github-audience-atlas.vercel.app/)**，输入用户名，然后直接前往[用法](#-usage)。随时添加你自己的 PAT 以跳过共享的演示限制：关于这具体会如何改变浏览器发出的请求，请参阅[安全与隐私](#-security--privacy)。 ### 选项 B：在本地运行 ``` # 1. Clone 仓库 git clone https://github.com/ThierryRakotomanana/github-audience-atlas.git cd # 2. 安装依赖 npm install # 3. 启动 app npm run dev ``` 这种方式默认会让你进入 BYO-PAT 模式：由于本地没有配置共享 token，你需要在 UI 中粘贴自己的 token。要在本地也体验演示/共享 token 流程，请在下方设置 `DEMO_GITHUB_TOKEN`。 ### 环境变量 | 变量 | 使用者 | 是否必需 | 描述 | | ------------------- | ------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `DEMO_GITHUB_TOKEN` | 仅后端 | 仅当你想在本地运行共享演示 token 流程时才需要 | 后端使用此 token 来处理未提供自己 PAT 的访问者的请求。永远不会被打包或暴露给客户端。 | ``` # .env.example DEMO_GITHUB_TOKEN=your_shared_token_here ``` ## 💻 用法 1. **启动**应用：打开[在线版本](https://github-audience-atlas.vercel.app/)，或者在本地运行 `npm run dev`。 2. **输入**你想要映射的 GitHub 用户名。 3. _（可选）_ **粘贴**你自己的 Personal Access Token 以跳过共享的演示限制。 4. 点击 **Generate Map**，在交互式地球仪上探索你的社交网络。 ## 🧩 工作原理 总体而言，该应用程序遵循以下 pipeline： ``` flowchart LR A[Username + optional PAT] --> B{PAT provided?} B -->|Yes| C[Browser calls GitHub API directly] B -->|No| D[Browser calls GitCharta backend] D --> E[Backend attaches shared token] C --> F[GraphQL : bulk fetch followers / following] E --> F F --> G{Fields missing?} G -->|Yes| H[REST fallback fills the gaps] G -->|No| I[Categorize: Follower / Following / Ghost] H --> I I --> J[Resolve location per profile] J --> K[Render map + stats] ``` 1. **输入**：你提供一个要映射的 GitHub 用户名，以及可选的你自己的 PAT。 2. **路由**：使用 PAT 时，你的浏览器直接与 GitHub 通信。如果没有，请求将通过 GitCharta 的后端，该后端会附加一个共享的、速率受限的 token：由于你没有提供任何凭据，因此你自己的凭据绝不会出现在此路径中。 3. **获取**：首先查询 GitHub GraphQL API，因为它拉取关注者、正在关注列表和个人资料字段所需的往返次数比 REST 少得多。GraphQL 遗漏的任何内容都会通过针对性的 REST 调用来补全。 4. **分类**：对账号进行交叉比对，以识别出关注者、正在关注列表和非互惠的“幽灵粉”。 5. **解析**：使用每个账号的公开位置字段将其放置在地图上；没有位置的账号则会被放入专门的未知位置视图中，而不是凭空消失。 6. **渲染**：结果将连同统计面板一起绘制在可交互探索的世界地图上。 ## 🗺️ 路线图 计划在即将发布的版本中推出： | 状态 | 功能 | 描述 | 备注 | | ------ | ------------------------ | ----------------------------------------------------------------------- | -------------------------------- | | ⬜ | **地图截图** | 将你的地图导出为图片，以便分享或放入 README | | | ⬜ | **缩放和平移** | 放大查看任何区域，而不是眯着眼睛看整个世界 | | | ⬜ | **Stargazer 地图** | 映射那些 star 了你的 repo 的人，而不仅仅是你的关注者 | | | ⬜ | **GitHub 个人资料徽章** | 将你的地图的实时徽章直接嵌入到你的 GitHub README 中 | | | ⬜ | **覆盖率徽章** | 展示你的受众覆盖了全球多大比例的徽章 | | | ⬜ | **直接取消关注** | 直接在地图界面上取消关注“幽灵粉” | 需要 `user:follow` PAT scope | | ⬜ | **高级颜色模式** | 热力图、雷达视图，以及“Contribution Green”主题 | | | ⬜ | **UI/UX 大修** | 对界面和用户流程的持续改进 | | 有想法吗？[创建一个 issue](../../issues) 来建议新功能。 ## 📄 许可证 ## 👤 作者与联系方式 由 **Thierry Rakotomanana** 构建和维护。 如果你觉得这个项目有用，可以考虑关注：我们会定期分享新的工具和开源贡献。 [](https://github.com/ThierryRakotomanana) [](https://twitter.com/ThieryRakt)

标签：D3.js, React, Syscalls, 暗色界面, 社交网络, 自动化攻击