# web-dev-course-kit

**Repository Path**: liuyang8660/web-dev-course-kit

## Basic Information

- **Project Name**: web-dev-course-kit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitee-harvest

一个零运行时依赖的 Node.js CLI，用于批量导出 Gitee 公开仓库的：

- 全部分支；
- 各分支可达的 Commit（按 SHA 去重并记录所属分支）；
- 每个 Commit 的文件变更、增删行数和变更状态；
- open、closed、merged Pull Request；
- Pull Request 与 Commit 的关联关系。

## 环境与运行

需要 Node.js 20 或更高版本。仓库列表每行一个学生，字段用**英文逗号、分号或制表符（Tab）**分隔为「学号,姓名,仓库地址」，支持空行和 `#` 注释；仓库地址支持 `owner/repo`、HTTPS 链接或 SSH 地址。也兼容仅写 `owner/repo` 的旧格式（此时没有学号/姓名，输出目录回退为 `owner__repo`）。

```text
# students.txt
# 学号,姓名,仓库地址
2023010101,张三,gesang-tsering/web-blog
2023010102,李四,https://gitee.com/owner/repo
2023010103,王五,git@gitee.com:owner2/repo2.git
# 旧式：仅 owner/repo（无学号姓名，目录回退为 owner__repo）
owner/legacy-repo
```

无 Token 也能抓取公开仓库：

```powershell
node src/index.js collect --repos students.txt --out output --start 20260929 --end 20261003
```

`--start` 与 `--end` 是必填参数，用于只收录时间窗口内的提交与 Pull Request。例如
`--start 20260929 --end 20261003` 表示「从 2026 年 9 月 29 日凌晨零点开始，到 2026 年 10 月 3 日凌晨零点结束（不含 10 月 3 日当天）」。裸日期按 `--timezone` 指定的时区解释为当天 00:00，默认时区为 `Asia/Shanghai`（中国时区），可用 `--timezone local` 改为当前机器时区，或指定任意 IANA 时区。

可选的只读 Token 应通过环境变量提供，避免进入 shell 历史：

```powershell
$env:GITEE_TOKEN = "<read-only-token>"
node src/index.js collect --repos repositories.txt --out output --start 20260929 --end 20261003 --strict
```

也可以把 Token 放在项目根目录的 `.env` 文件里（不会被提交进版本库，已写入 `.gitignore`）：

```text
GITEE_TOKEN=<read-only-token>
```

工具会自动读取 `.env` 文件，Token 取值优先级为：`--token` 显式参数 > 真实环境变量 > `.env` 文件。`.env` 中的变量名可通过 `--token-env` 修改。仓库为公开时也可完全不带 Token。

常用选项：

```text
--start DATE              必填。窗口起点（YYYYMMDD 或 YYYY-MM-DD），含当天 00:00
--end DATE                必填。窗口终点（YYYYMMDD 或 YYYY-MM-DD），不含当天 00:00
--timezone TZ             解释起止日期的 IANA 时区，默认 Asia/Shanghai
--token-env NAME          Token 的环境变量名，默认 GITEE_TOKEN（同时决定 .env 中读取的键名）
--token VALUE             直接提供 Token；仅在安全的非交互环境中使用
.env 文件                 自动读取项目根目录 .env 中的 Token（变量名见 --token-env）；该文件已被 .gitignore 忽略
--min-interval-ms N       API 请求最小间隔，默认 800 ms
--per-page N              分页大小，1–100，默认 100
--max-retries N           网络、408、429、5xx 的最大重试次数，默认 5
--resume / --no-resume    使用或忽略现有检查点
--strict                  任何仓库不完整时以非零状态退出
--base-url URL            API 基地址，默认 https://gitee.com/api/v5
```

### 时间窗口的过滤语义

- 提交（commit）按 **提交时间 `committed_at`** 过滤；窗口外的提交不会收录，也不会再去请求其详情（节省请求）。
- Pull Request 按 **创建时间 `created_at`** 过滤；窗口外的 PR 整条跳过（既不收录 PR，也不拉取其提交）。
- 落在窗口内的 PR，其提交同样按提交时间过滤：窗口外的提交不会被计入。
- 边界为左闭右开 `[start, end)`：起点当天 00:00 含入，终点当天 00:00 排除。

所有请求会限速；对于临时网络错误、408、429 和 5xx，工具会采用带抖动的指数退避。日志和错误中会脱敏 Token。

### 结果汇总表（report）

采集完成后，不必重新拉取，可直接根据 `--out` 中已有的结果生成「每个学生一行」的汇总表：

```powershell
node src/index.js report --repos students.txt --out output
```

输出默认是 Markdown 表格（同时写入 `output/result-table.md`），每行一个学生，包含：学号、姓名、仓库、提交数、PR 数、采集状态（`成功` / `空仓库` / `失败` / `未采集`）。也可用 `--format csv` 输出 CSV（写入 `output/result-table.csv`），或用 `--write 路径` 指定输出文件。

`collect` 命令在采集结束时**既会在终端打印、也会自动写盘**同一张汇总表（默认 `output/result-table.md`，同样支持 `--format` / `--write`）。也就是说，单独跑一次 `collect` 就能同时拿到「各学生数据目录 + 汇总表文件」。`report` 子命令则保留给「免爬重出 / 切换 md↔csv」这类场景使用。

## 输出与恢复

每个学生写入独立目录：若仓库列表里提供了学号与姓名，目录名为 `学号-姓名`（如 `output/2023010101-张三/`）；若为旧式仅 `owner/repo`，目录名回退为 `owner__repo`。每个目录内：

```text
branches.json
commits.json
pull_requests.json
pr_commits.json
changes.json
manifest.json
```

`commits.json` 的每条记录以 SHA 为唯一键，包含 `branches` 和 `files`；每个文件记录 `filename`、`previous_filename`、`status`、`additions`、`deletions`、`changes`，以及 **`patch`**——该文件本次改动的 unified diff（Gitee 在 commit 详情里返回），用于直接查看「改了哪几行、怎么改的」。`pr_commits.json` 是 `{ pr_number, sha, position }` 的关联表，因此不会重复保存 Commit 正文。

`changes.json` 是为批改/评审设计的摊平视图：把「每个 commit 改动的每个文件」展开成一行，便于逐条核对作业。每条记录包含：

```text
commit_sha        所属提交
committed_at      提交时间
message           提交说明
author_name       作者
author_email      作者邮箱
pr_numbers        该提交所属的 PR 编号列表（未关联 PR 则为空）
filename          被改动的文件
previous_filename 改名前的文件名（若有）
status            改动类型（added / modified / deleted / renamed ...）
additions         新增行数
deletions         删除行数
changes           变更行数
patch             该文件的具体 diff
```

`manifest.json` 包含计数、失败项、`partial` 状态，以及 `time_range`（本次采集的时间窗口：起点/终点毫秒、时区与可读标签）。除 `manifest.json` 外，其余每个 JSON 也会带上 `time_range` 元信息，方便按窗口归档与核对。

抓取过程会在 `output/.state/{owner}__{repo}.json` 写入原子检查点。重复运行时，默认会恢复未完成的 Commit 详情和 PR 关联；最终五个 JSON 会先写入暂存目录，再整体发布，避免交付半截结果。`manifest.json` 包含计数、失败项和 `partial` 状态。

## 完整性边界

Gitee 的 PR Commit 接口被文档标注为最多返回 250 条 Commit。若响应正好达到 250 条，本工具会把该 PR 标为 `commit_collection_status: "possibly_truncated"`，记录失败原因并将仓库结果标记为 partial；`--strict` 会非零退出。它不会把可能不完整的 API 响应宣称为全量。

## 验证

```powershell
npm test
npm run check
```

测试采用 Node 内置测试框架，不需要安装第三方依赖。