From 56719d7df6614e1c84b488e7dc62f6863baf315a Mon Sep 17 00:00:00 2001
From: shumengya <mail@smyhub.com>
Date: Tue, 23 Jun 2026 22:05:41 +0800
Subject: [PATCH] docs: add comprehensive README and MIT LICENSE

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 LICENSE   |  21 +++++++++
 README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 LICENSE
 create mode 100644 README.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d17fa7b
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shumengya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..677a443
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# GitHeatMap
+
+> 桌面贡献热力图小挂件 —— 把 GitHub / Gitea 的提交热力图放到桌面常驻显示。
+
+基于 **Tauri 2 + Rust + 原生前端** 构建的轻量级桌面挂件，仓库内含两个独立变体：
+
+| 变体 | 产品名 | 数据来源 | 目录 |
+|------|--------|----------|------|
+| GitHub HeatMap | `GitHub HeatMap` | GitHub 贡献日历 | `github/` |
+| Gitea HeatMap | `Gitea HeatMap` | Gitea `/api/v1/users/{user}/heatmap` | `gitea/` |
+
+两个变体共用一套 Cargo workspace，可分别打包为独立的 `.exe`。
+
+## 功能特性
+
+- 🟩 **桌面常驻挂件** — 600×108 无边框、透明背景的小窗口，贴在桌面即可一眼看到贡献热力图
+- 🖱️ **自由拖拽** — 拖动窗口任意位置，自动记忆坐标（写入 `data/*_config.json`）
+- 🎨 **明暗主题** — 内置深色 / 浅色主题，托盘或设置面板一键切换
+- 🔔 **系统托盘** — 显示 / 隐藏 / 刷新 / 置顶 / 设置 / 退出，左键单击托盘唤出窗口
+- ❌ **关闭即隐藏** — 点击关闭按钮隐藏到托盘而非退出，保持常驻
+- 🔑 **Token 可选** — 公开数据免认证；私有实例或受限访问时填入 Access Token
+- ⚡ **原生体积小** — 前端为零依赖原生 HTML/CSS/JS + Canvas 渲染，启动快、占用低
+
+## 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 桌面框架 | [Tauri 2](https://v2.tauri.app/) |
+| 后端 | Rust（`reqwest` 请求、`serde` 序列化） |
+| 前端 | 原生 HTML / CSS / JavaScript（`withGlobalTauri`） |
+| 热力图渲染 | Canvas 2D |
+| 配置存储 | exe 同级 `data/` 目录下 JSON |
+
+## 快速开始
+
+### 环境要求
+
+- [Node.js](https://nodejs.org/) ≥ 18
+- [Rust](https://www.rust-lang.org/tools/install) 工具链
+-（Windows）[Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/)
+
+### 开发运行
+
+分别进入对应变体目录：
+
+```bash
+# GitHub 变体
+cd github
+npm install
+npm run tauri dev
+
+# Gitea 变体
+cd gitea
+npm install
+npm run tauri dev
+```
+
+### 一键构建（Windows）
+
+仓库根目录提供 `build.bat`，会依次生成图标并打包两个变体：
+
+```bat
+build.bat
+```
+
+产物位于 `target/release/`：
+
+```
+target/release/
+├── github-heatmap.exe
+└── gitea-heatmap.exe
+```
+
+> 也可单独进入 `github/` 或 `gitea/` 执行 `npm run tauri build`。
+
+### 生成图标
+
+```powershell
+powershell -ExecutionPolicy Bypass -File generate-icons.ps1
+```
+
+脚本会基于内置的 GitHub / Gitea 矢量 Logo 生成各尺寸图标。
+
+## 配置说明
+
+配置文件保存在 **与 exe 同级** 的 `data/` 目录中：
+
+- GitHub 变体：`data/github_config.json`
+- Gitea 变体：`data/gitea_config.json`
+
+示例（Gitea）：
+
+```json
+{
+  "server": "https://git.shumengya.top",
+  "username": "shumengya",
+  "token": "",
+  "window_x": 558,
+  "window_y": 186,
+  "theme": "dark"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `server` | Gitea 服务器地址（GitHub 变体无需此项） |
+| `username` | 要展示热力图的用户名 |
+| `token` | Access Token，可选；私有数据或避免限流时填写 |
+| `window_x` / `window_y` | 窗口位置，拖动后自动记忆 |
+| `theme` | `dark` / `light` |
+
+也可直接在挂件的**设置面板**或**托盘菜单**中修改，无需手动编辑文件。
+
+## 项目结构
+
+```text
+GitHeatMap/
+├── github/                 # GitHub 变体
+│   ├── frontend/           # 原生前端（index.html / main.js / style.css）
+│   └── src-tauri/          # Rust 后端 + Tauri 配置
+├── gitea/                  # Gitea 变体（结构同上）
+├── generate-icons.ps1      # 图标生成脚本
+├── build.bat               # 一键构建两个变体
+├── Cargo.toml              # Cargo workspace
+└── README.md
+```
+
+## 许可证
+
+MIT