# MediaGo Core

> 多任务下载系统 - Go (Gin) 实现

## 🚀 快速导航

### 📖 核心文档

- **[快速开始（5 分钟）](QUICKSTART.md)** - 新手必读
- **[完整使用文档](README_core.md)** - API 与配置详解
- **[最终交付总结](FINAL_SUMMARY.md)** - 项目概览

### 🔧 技术文档

- **[实现总结](IMPLEMENTATION_SUMMARY.md)** - 技术细节与核心特性
- **[项目结构](PROJECT_STRUCTURE.md)** - 架构与模块关系
- **[交付清单](DELIVERY_CHECKLIST.md)** - 验收标准

---

## ⚡ 快速开始

### 使用 NPM Scripts（推荐）

```bash
# 安装依赖
pnpm install

# 查看所有可用命令
pnpm run help

# 运行开发服务器
pnpm dev

# 编译当前平台的开发版本
pnpm run build
```

### 传统方式

```bash
# 安装依赖
go mod tidy

# 运行服务
go run ./cmd/server
```

### Docker 部署

```bash
# Docker Compose
docker-compose up -d
```

---

## 🎯 核心特性

- ✅ **JSON 配置**（从 YAML 迁移）
- ✅ **进度节流**（200ms + 0.5%）
- ✅ **并发控制**（动态调整）
- ✅ **事件驱动**（SSE 实时推送）
- ✅ **Swagger 文档**（完整的 API 文档）
- ✅ **Gulp 构建系统**（模块化 TypeScript 任务）
- ✅ **Docker 支持**（一键部署）

---

## 📖 API 文档

项目集成了 **Swagger API 文档**，提供了完整的接口说明和在线测试功能。

### 访问 Swagger UI

```bash
# 1. 启动服务
gulp dev

# 2. 访问 Swagger UI
# http://localhost:8080/swagger/index.html
```

### 生成 Swagger 文档

```bash
# 安装 swag 工具
gulp devTools

# 生成文档
gulp devSwagger

# 或手动生成
swag init -g cmd/server/main.go -o docs --parseDependency --parseInternal
```

### API 端点列表

- `POST /api/tasks` - 创建下载任务
- `POST /api/tasks/:id/stop` - 停止任务
- `POST /api/config` - 更新配置
- `GET /api/events` - SSE 事件流
- `GET /swagger/*any` - Swagger UI

---

## 📦 支持的下载类型

1. **M3U8** - HLS 流媒体下载
2. **Bilibili** - B站视频下载
3. **Direct** - 直接文件下载（aria2c）

---

## 🛠️ 可用命令

### 开发任务

```bash
pnpm dev                    # 启动开发服务器
pnpm run build              # 编译当前平台的开发版本
```

### NPM 包构建

```bash
pnpm run build:core         # 构建 Core NPM 包（包含所有平台二进制）
pnpm run build:deps         # 构建 Deps NPM 包（包含依赖工具）
pnpm run npm:build          # 构建所有 NPM 包（Core + Deps）

# 别名（更明确的命名）
pnpm run npm:build:core     # 同 build:core
pnpm run npm:build:deps     # 同 build:deps
```

### NPM 包发布

```bash
pnpm run npm:publish        # 发布所有 NPM 包
pnpm run npm:publish:core   # 仅发布 Core NPM 包
pnpm run npm:publish:deps   # 仅发布 Deps NPM 包
```

### 帮助命令

```bash
pnpm run help               # 显示所有可用的 Gulp 任务和说明
pnpm run tasks              # 显示 Gulp 任务树（技术视图）
```

---

## 📦 发布指南

### 1. 开发阶段

```bash
# 启动开发服务器
pnpm dev

# 快速编译当前平台
pnpm run build
```

### 2. 构建 NPM 包

`pnpm run npm:build` 会执行以下步骤：

1. 清理旧的构建产物
2. 构建所有平台的二进制文件
3. 生成 NPM 包的 package.json、README 和 install.js
4. 复制二进制文件和依赖工具到对应的包目录

构建完成后，NPM 包文件位于 `./npm/@mediago/`。

#### 指定版本号

版本号获取优先级：**环境变量 VERSION > Git Tag > 'dev'**

```bash
# 方法 1: 使用环境变量（推荐）
VERSION=1.2.3 pnpm run npm:build

# 方法 2: 使用 Git Tag
git tag v1.2.3
pnpm run npm:build  # 会自动使用 v1.2.3

# 方法 3: 分别指定 Core 和 Deps 版本
CORE_VERSION=1.2.3 DEPS_VERSION=1.0.0 pnpm run npm:build
```

#### 单独构建 Core 或 Deps

```bash
# 只构建 Core 包
VERSION=1.2.3 pnpm run build:core

# 只构建 Deps 包
VERSION=1.0.0 pnpm run build:deps
```

### 3. 发布到 NPM

> 发布前请先执行 `pnpm run npm:build` 确保包已准备好，并且已经完成 `npm login`。

```bash
# 发布所有 NPM 包（Core + Deps）
pnpm run npm:publish

# 仅发布 Core 包
pnpm run npm:publish:core

# 仅发布 Deps 包
pnpm run npm:publish:deps
```

#### NPM 包结构

生成的 NPM 包：

- `@mediago/core` - 主包（根据平台自动安装对应的二进制包）
- `@mediago/core-darwin-x64` - macOS x64 二进制
- `@mediago/core-darwin-arm64` - macOS ARM64 二进制
- `@mediago/core-linux-x64` - Linux x64 二进制
- `@mediago/core-linux-arm64` - Linux ARM64 二进制
- `@mediago/core-win32-x64` - Windows x64 二进制
- `@mediago/core-win32-arm64` - Windows ARM64 二进制
- `@mediago/deps` - 依赖工具主包
- `@mediago/deps-*` - 各平台的依赖工具包

**详细说明**: 查看 [版本号管理指南](docs/VERSION_GUIDE.md)

---

## 📦 发布包的使用

### Windows

1. 解压 zip 文件
2. 双击运行 `mediago-core.exe`

### Linux/macOS

1. 解压 zip 文件
2. 在终端中运行：
   ```bash
   cd mediago-core-xxx
   chmod +x mediago-core
   ./start.sh
   ```

### NPM 安装

```bash
npm install @mediago/core
# or
pnpm add @mediago/core
# or
yarn add @mediago/core

# 运行
npx @mediago/core
```

---

## 🔧 环境变量说明

发布包中的程序会自动使用相对路径查找下载器工具：

- `./bin/N_m3u8DL-RE` (或 `.exe`)
- `./bin/BBDown` (或 `.exe`)
- `./bin/aria2c` (或 `.exe`)

用户无需配置任何环境变量即可运行！

可选的环境变量：

- `MEDIAGO_M3U8_BIN` - M3U8 下载器路径
- `MEDIAGO_BILIBILI_BIN` - Bilibili 下载器路径
- `MEDIAGO_DIRECT_BIN` - 直接下载器路径
- `MEDIAGO_LOG_LEVEL` - 日志级别 (debug/info/warn/error)
- `MEDIAGO_LOG_DIR` - 日志目录路径
- `MEDIAGO_SERVER_ADDR` - 服务器监听地址 (默认 :8080)

---

## 🏗️ 项目架构

### 目录结构

```
mediago-core/
├── cmd/
│   └── server/           # 主程序入口
├── internal/             # 内部包
│   ├── api/             # API 路由和处理器
│   ├── config/          # 配置管理
│   ├── download/        # 下载器实现
│   ├── events/          # 事件系统
│   └── task/            # 任务管理
├── configs/             # 配置文件
├── scripts/             # 构建脚本 (TypeScript)
│   ├── config.ts        # 配置常量和平台定义
│   ├── utils.ts         # 工具函数（文件操作、模板渲染等）
│   ├── dev.ts           # 开发任务
│   ├── release.ts       # 发布构建（完整发布包）
│   └── npm.ts           # NPM 包管理（元数据生成 + 组装 + 发布）
├── templates/           # NPM 包模板文件
│   ├── *.json.tpl       # package.json 模板
│   ├── *.md.tpl         # README.md 模板
│   └── *.js.tpl         # install.js 模板
├── gulpfile.ts          # Gulp 主入口
├── .bin/                # 下载器工具（按平台）
├── bin/                 # 编译产物（二进制文件）
├── npm/                 # NPM 包构建输出
│   └── @mediago/        # NPM scope
│       ├── core/        # Core 主包
│       ├── core-*/      # 各平台 Core 包
│       ├── deps/        # Deps 主包
│       └── deps-*/      # 各平台 Deps 包
└── release/             # 完整发布包
```

### 构建脚本架构

所有构建脚本都使用 TypeScript 编写，职责清晰：

- **config.ts** - 配置变量、常量和平台定义
- **utils.ts** - 通用工具函数（文件操作、命令执行、模板渲染等）
- **dev.ts** - 开发环境任务（开发服务器、快速编译）
- **release.ts** - 发布构建任务（构建二进制、打包完整发布包）
- **npm.ts** - NPM 包完整流程（元数据生成、组装、发布）

---

## 📚 完整文档列表

| 文档                                                   | 说明                 | 适合人群   |
| ------------------------------------------------------ | -------------------- | ---------- |
| [QUICKSTART.md](QUICKSTART.md)                         | 5 分钟快速启动       | 所有人     |
| [docs/VERSION_GUIDE.md](docs/VERSION_GUIDE.md)         | 版本号管理指南       | 发布者     |
| [SWAGGER_GUIDE.md](SWAGGER_GUIDE.md)                   | Swagger API 文档指南 | API 开发者 |
| [README_core.md](README_core.md)                       | 完整使用文档         | API 使用者 |
| [FINAL_SUMMARY.md](FINAL_SUMMARY.md)                   | 最终交付总结         | 项目经理   |
| [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) | 实现总结             | 架构师     |
| [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)           | 项目结构             | 维护者     |
| [DELIVERY_CHECKLIST.md](DELIVERY_CHECKLIST.md)         | 交付清单             | QA 测试    |

---

## 🎉 项目状态

**✅ 已完成，可直接运行**

- 代码：~700 行（8+ 个 Go 文件）
- 文档：~70 KB（7+ 份文档）
- 构建任务：30+ 个 Gulp 任务
- API 文档：完整 Swagger 支持
- 测试：完整客户端页面
- 脚本：模块化 TypeScript

---

## ❓ 常见问题

### Q: 如何只打包特定平台？

A: 可以修改 `scripts/config.ts` 中的 `BUILD_PLATFORMS` 数组，注释掉不需要的平台。

### Q: 下载器工具从哪里来？

A: 从项目根目录的 `.bin/<platform>/<arch>/` 目录复制。确保这些文件存在且可执行。

### Q: 如何添加新的下载器工具？

A: 将工具放入 `.bin/<platform>/<arch>/` 目录，它会自动被复制到发布包中。

### Q: 为什么使用 pnpm 而不是 npm？

A: pnpm 更快、更节省磁盘空间。当然你也可以使用 npm 或 yarn，只需将 `pnpm` 替换即可。

### Q: 如何自定义构建流程？

A: 编辑 `scripts/` 目录下的 TypeScript 文件。所有任务都是模块化的，职责清晰，易于修改和扩展。

### Q: Core 和 Deps 包有什么区别？

A:

- **Core 包**：包含 mediago-core 的二进制文件和配置
- **Deps 包**：包含依赖的下载工具（N_m3u8DL-RE、BBDown、aria2c、yt-dlp）
- 分开发布可以单独更新，减少不必要的下载

---

## 📞 获取帮助

有问题？查看文档：

1. **新手入门** → [QUICKSTART.md](QUICKSTART.md)
2. **API 文档** → [SWAGGER_GUIDE.md](SWAGGER_GUIDE.md) 或访问 http://localhost:8080/swagger/index.html
3. **API 调用** → [README_core.md](README_core.md)
4. **故障排查** → [README_core.md#故障排查](README_core.md#故障排查)

---

**版本：** v1.0.0
**最后更新：** 2025-01-24
**构建工具：** Gulp + TypeScript