# git-download-helper

**Repository Path**: eispy/git-download-helper

## Basic Information

- **Project Name**: git-download-helper
- **Description**: Git 极速下载器（uTools 插件）

一键识别 GitHub 链接，通过镜像/代理前缀加速，自动复制拼接地址并唤起外部下载器（FluxDown / Internet Download Manager）下载，告别 Raw / Release 文件下载缓慢问题。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-08
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Git 极速下载器（uTools 插件）

一键识别 GitHub 链接，通过镜像/代理前缀加速，自动复制拼接地址并唤起外部下载器（FluxDown / Internet Download Manager）下载，告别 Raw / Release 文件下载缓慢问题。

## 功能特性

- **一键下载**：复制 GitHub 链接 → 唤起 uTools → 回车「Git 加速下载」，自动完成「复制拼接地址 + 唤起默认下载器添加任务」，无需二次点击
- **剪贴板自动匹配**：uTools 唤起时自动识别剪贴板中的 GitHub 链接（多 URL 时取第一个）
- **双下载器支持**：
  - **FluxDown**（默认）：通过本机 HTTP API（takeover 接管端点）添加任务，无需 API Token，桌面版未运行时会自动拉起
  - **IDM**：命令行参数唤起（`/n /d "{url}"`），可编辑安装路径
- **前缀/镜像管理**：内置 `v6.gh-proxy.org`，支持增删改自定义镜像前缀；下载地址 = 默认前缀 + GitHub 链接
- **数据同步**：前缀配置随 uTools 账号云同步；下载器配置（含 API Token）仅保存在本机，不进云端
- **设置页**：基础设置 / 下载器设置 / 前缀设置 / 使用说明 四个 Tab

## 环境要求

- Windows
- uTools（5.x 及以上）
- 下载器至少安装其一：FluxDown 桌面版 或 Internet Download Manager

## 安装

1. 在项目根目录执行 `npm run build`，生成 `dist/` 插件目录
2. uTools → 设置 → 插件应用 → 开发者工具 → 添加插件，选择 `dist/` 目录
3. （开发调试请见下文「开发」）

## 快速使用

1. 在浏览器中复制一个 GitHub 链接（Release 下载 / Raw 文件等）
2. 唤起 uTools（默认 `Alt + Space`）
3. 回车选择「Git 加速下载」
4. 插件自动完成：复制拼接后的加速地址（如 `https://v6.gh-proxy.org/https://github.com/...`）+ 唤起默认下载器添加任务

> 设置入口：uTools 搜索框输入 `git设置` 进入设置页。

## 配置说明

### 基础设置

- **默认下载器**：FluxDown（默认）或 IDM
- **默认前缀**：下载时拼接在 GitHub 链接前的镜像地址

### 下载器设置

| 下载器 | 说明 |
| :--- | :--- |
| FluxDown | 需安装并打开 FluxDown 桌面版；API 地址默认 `http://127.0.0.1:17800`；若在 FluxDown「设置 → API 服务」启用了 Token，请填入「API Token」（可选） |
| IDM | 填写 `IDMan.exe` 完整路径（默认 `C:\Program Files (x86)\Internet Download Manager\IDMan.exe`） |

FluxDown 默认安装路径：`%LOCALAPPDATA%\Programs\FluxDown\flux_down.exe`（可修改）。

### 前缀设置

- 支持新增、删除、编辑镜像前缀
- 下载地址 = 前缀 + GitHub 链接；新增后未填写地址的前缀不会被保存

### 数据同步

- **前缀配置**随 uTools 账号云同步（需在 uTools 中开启「数据同步」）
- **下载器配置**仅保存在本机（`userData/git-download-helper-downloaders.json`），不会同步

## 开发

```bash
npm install        # 安装依赖
npm run dev        # 启动 Vite 开发服务器（localhost:5173）
npm run build      # 构建到 dist/
```

uTools 开发者工具 → 添加插件，选择 `public/` 目录（`plugin.json` 中 `development.main` 指向 localhost:5173，preload 从插件目录加载）；正式使用加载 `dist/`。

### 目录结构

```
public/
  plugin.json            # 插件配置（regex 匹配指令 + git设置 功能指令）
  preload/services.js    # preload：配置读写、FluxDown HTTP API、IDM spawn 唤起
src/
  App.vue                # 路由（git-download / git-settings，空路由兜底设置页）
  views/
    Download.vue         # 下载页（自动复制拼接地址 + 唤起下载器）
    Settings.vue         # 设置页（四 Tab）
  utils/url.js           # GitHub URL 提取/校验
```

## 技术要点

- **匹配机制**：`plugin.json` 中 `type: "regex"` 匹配指令，uTools 唤起时剪贴板内容自动参与匹配
- **FluxDown 集成**：官方无 CLI 下载命令，走本机 HTTP API `POST /download`（takeover 接管端点），只需 `X-FluxDown-Client` 头，Token 可选；探活用无鉴权 `/ping`
- **IDM 集成**：参数模板拆 token + `child_process.spawn` 参数数组（不经 shell，防注入）
- **存储拆分**：前缀存 `utools.dbStorage`（随账号同步）；下载器存本机文件（含 API Token，避免进云端）；老配置自动迁移
- **URL 提取**：正则提取剪贴板/输入中第一个标准 GitHub URL，多 URL 与多余文字场景安全

## 常见问题

- **找不到下载器程序**：到「下载器设置」核对安装路径（FluxDown 默认 `%LOCALAPPDATA%\Programs\FluxDown\flux_down.exe`）
- **FluxDown 服务不可用**：确认已打开 FluxDown 桌面版，或检查 API 地址是否为 `http://127.0.0.1:17800`
- **创建任务被拒**：FluxDown 启用了 API Token 但插件未填写或填写错误
- **打开插件空白**：确认 uTools 加载的是 `dist/`（构建产物）且已重新加载；开发模式需 `npm run dev` 运行中；页面顶部红色横幅会显示具体 JS 错误
- **未配置默认下载器/前缀**：到「基础设置」选择

## 相关文档

- [需求说明书](docs/需求说明书.md)
- [开发规划](docs/开发规划.md)