# kite

**Repository Path**: jr-soft/kite

## Basic Information

- **Project Name**: kite
- **Description**: Kite 是一款现代 命令行下载工具：兼顾 wget 的稳定与脚本友好、aria2 / KGet Turbo 的大文件并行能力，同时提供 清晰的 CLI、强可观测性、可扩展钩子。名字寓意在云端与本地之间稳定、可控地「放线收线」。
主要用户：脚本自动化、CI/CD 拉取制品、开发者日常下载、大文件传输。
形态：默认 轻量、单二进制、无运行时依赖；
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kite

轻量命令行 **HTTP(S) 下载** 工具：单连接 / 分片、断点续传、代理、批量与 **NDJSON** 可观测输出。行为以 [开发文档.md](./docs/开发文档.md) 与 [最终方案.md](./docs/最终方案.md) 为准。

**当前版本：v1.0.0**（与 `kite -V` 一致；发版时请打同名 tag）。

---

## 从源码构建

```bash
go build -o kite ./cmd/kite
```

Windows：

```powershell
go build -o kite.exe ./cmd/kite
```

### 交叉编译示例

```bash
GOOS=linux   GOARCH=amd64 go build -o kite-linux-amd64 ./cmd/kite
GOOS=darwin  GOARCH=arm64 go build -o kite-darwin-arm64 ./cmd/kite
GOOS=windows GOARCH=amd64 go build -o kite-windows-amd64.exe ./cmd/kite
```

---

## 退出码（与 `docs/开发文档.md` §0.1 一致）

| 码 | 含义 |
|----|------|
| 0 | 成功（单任务或批量全部成功） |
| 1 | 通用失败（未分类、`--on-success` 执行失败等） |
| 2 | 用法错误（非法参数、多 URL 与 `-o` 冲突等） |
| 3 | 网络 / HTTP 失败 |
| 4 | 本地 I/O 失败 |
| 5 | SHA256 校验失败（`--sha256` / `--checksum`） |

批量任务中 **任一 URL 失败** 时，进程退出码与失败任务一致（通常为 **3**）。

---

## 命令行参数表

> 与 `kite -h` 保持一致；长参数与简写如下。

| 长参数 | 简写 | 说明 |
|--------|------|------|
| `--help` | `-h` | 帮助 |
| `--version` | `-V` | 版本号 |
| `--output` | `-o` | 输出路径或文件名（**多 URL 时不可用**） |
| `--directory` | `-P` | 保存目录；文件名为 URL 推断（无路径段时为 **`index`**） |
| `--continue` | `-c` | 断点续传（**单连接**；需 HTTP 206） |
| `--split` / `--threads` | `-n` | 分片连接数（默认 1；不支持 Range 时自动单连接） |
| `--user-agent` | `-U` | User-Agent |
| `--header` | `-H` | 请求头 `Name: Value`，可重复 |
| `--referer` | | Referer |
| `--proxy` | | 代理 URL（`http` / `https` / `socks5` / `socks5h`） |
| `--proxy-auth` | | `user:password` |
| `--no-check-certificate` | | 跳过 TLS 校验（stderr 警告） |
| `--input` | | URL 列表文件（每行一个；空行与 `#` 行为注释） |
| `--max-concurrent` | | 多任务并发上限（0=自动：多 URL 默认 5，单 URL 为 1） |
| `--output-format` | | `human`（默认）或 `json`（NDJSON，见下表） |
| `--quiet` | `-q` | 减少 stderr 提示 |
| `--limit-rate` | | 总限速，如 `500k`、`2m`（多连接均分） |
| `--timeout` | | 单次请求总超时（秒；0 表示不设整包超时） |
| `--retry` | | 额外重试次数（5xx / 429 / 可重试网络错误） |
| `--retry-delay` | | 重试间隔秒数（`--retry>0` 且未指定时默认 1） |
| `--retry-exponential` | | 指数退避（与 `Retry-After`、固定间隔取较大值，单次等待上限 120s） |
| `--sha256` / `--checksum` | | 期望 SHA256（64 位 hex），失败退出码 **5** |
| `--on-success` | | 成功后执行的 shell（**等同你亲自执行**；见下文） |

---

## `--output-format json`（NDJSON 事件）

每行一个 JSON 对象（`encoding/json` 默认 UTF-8）。单 URL 时 **省略** `task_id`；批量时带 **`task_id`**（从 1 递增）。

| `type` | 字段 | 说明 |
|--------|------|------|
| `start` | `url`, `dest`, `task_id?` | 任务开始 |
| `progress` | `url`, `received`, `total?` | 进度（`total` 未知时省略） |
| `done` | `url`, `dest`, `bytes`, `task_id?` | 成功落盘且钩子成功后 |
| `error` | `url`, `code`, `message`, `task_id?` | 失败（`code` 对齐退出码语义） |

人类进度条只写到 **stderr**；JSON 模式下 **`done`** 在 **`--on-success`** 成功之后发出。

---

## `--on-success` 安全说明

- Windows：`cmd /C <命令>`；Unix：`sh -c <命令>`。  
- **不要**拼接不可信输入；仅用于可信脚本。  
- 子进程环境变量：**`KITE_DEST`**（本地文件路径）、**`KITE_URL`**；工作目录为 `KITE_DEST` 所在目录。

---

## 用法示例

```bash
kite https://example.com/file.zip
kite -o my.zip https://example.com/file.zip
kite -P ./downloads https://example.com/file.zip
kite -n 8 https://example.com/large.iso
kite -c -o partial.bin https://example.com/large.iso
kite --limit-rate 2m -n 4 https://example.com/file.zip
kite --input urls.txt -P ./out --max-concurrent 3
kite --output-format json https://example.com/file.zip > events.ndjson
kite --sha256 <64位hex> https://example.com/file.zip
kite --on-success "echo ok" https://example.com/file.zip
```

---

## CI 与质量

- GitHub Actions：见 [.github/workflows/ci.yml](./.github/workflows/ci.yml)（**Ubuntu / Windows** 矩阵：`gofmt`、`go vet`、`go test`）。  
- **internal 包**合并语句覆盖率门禁：`bash scripts/coverage_check.sh`（默认下限 **58%**，可通过 **`COVERAGE_MIN`** 调整）。  
- 开发文档中的 **≥80%** 为持续目标；提高下限前请先补充测试。  
- 本地可选用 [`golangci-lint`](https://golangci-lint.run/)（未在 CI 中强制）。

---

## 说明文档（`docs/`）

- [最终方案.md](./docs/最终方案.md) — 产品 / CLI 基线  
- [开发文档.md](./docs/开发文档.md) — 分步开发与验收  
- [方案1.md](./docs/方案1.md)、[方案2.md](./docs/方案2.md) — 前期讨论稿