# 历史作品库构建报告

生成时间：2026-06-21

## 1. 数据来源

- CSV：`data/history_projects.csv`
- CSV 记录数：`28`
- 历史仓库目录：`data/history_repos/`
- 历史分析输出：`outputs/history/`
- Clone 状态文件：`outputs/history_fetch_status.json`
- Import 状态文件：`outputs/history_import_status.json`

## 2. 本次执行内容

本次按完整历史库流程执行：

1. 全量读取 `data/history_projects.csv` 中的 28 个 2025 历史项目。
2. 使用 `scripts/fetch_repos.py` 尝试 clone 到 `data/history_repos/`。
3. 对已存在或 clone 成功的仓库执行 `scripts/import_history.py` 静态分析导入。
4. 对所有成功导入目录执行 `scripts/validate_outputs.py` schema 校验。

执行过程中未写入任何账号、密码或 token，也未对历史仓库运行构建、测试或二进制程序。

## 3. Clone 结果

- 总记录数：`28`
- 新 clone 成功：`23`
- 跳过已存在：`2`
- clone 失败：`3`
- 最终本地可用仓库数：`25`

### Clone 失败列表

| repo_id | source_url | 错误 |
| --- | --- | --- |
| `history_2025_002` | `https://gitlab.eduxiji.net/educg-group-36002-2710490/starry-mix` | `fatal: could not read Username for 'https://gitlab.eduxiji.net': Device not configured` |
| `history_2025_022` | `https://gitlab.eduxiji.net/educg-group-36002-2710490/T202510486995158-3041` | `fatal: could not read Username for 'https://gitlab.eduxiji.net': Device not configured` |
| `history_2025_028` | `https://gitlab.eduxiji.net/educg-group-36002-2710490/bakaos` | `fatal: could not read Username for 'https://gitlab.eduxiji.net': Device not configured` |

说明：这 3 个仓库需要 GitLab 认证或访问权限；脚本已按要求记录失败并继续处理后续项目。

## 4. Import 结果

- 总记录数：`28`
- 成功生成静态分析 JSON：`25`
- 导入失败：`3`
- 跳过：`0`
- 失败原因：对应 clone 失败仓库的 `local_path` 不存在。

成功导入的仓库：

`history_2025_001`, `history_2025_003`, `history_2025_004`, `history_2025_005`, `history_2025_006`, `history_2025_007`, `history_2025_008`, `history_2025_009`, `history_2025_010`, `history_2025_011`, `history_2025_012`, `history_2025_013`, `history_2025_014`, `history_2025_015`, `history_2025_016`, `history_2025_017`, `history_2025_018`, `history_2025_019`, `history_2025_020`, `history_2025_021`, `history_2025_023`, `history_2025_024`, `history_2025_025`, `history_2025_026`, `history_2025_027`

## 5. Validation 结果

- 已校验仓库目录数：`25`
- validation 通过：`25`
- validation 失败：`0`
- 是否满足 `validation_passed >= 5`：是

每个通过校验的仓库目录下均生成了 `validation_report.json`。

## 6. 2023-2024 扩容批次

执行时间：2026-06-23

本批次使用 `history_projects_2023_2024_additions.csv` 补充 2024 年总决赛开源作品和 2023 年优秀作品。根目录中的新增 CSV 已复制到 `data/history_projects_2023_2024_additions.csv`，并通过 `scripts/merge_history_projects.py` 幂等合并到 `data/history_projects.csv`。

### 元数据合并

- 原始 `data/history_projects.csv` 记录数：`28`
- 新增 CSV 记录数：`39`
- 2024 年记录数：`29`
- 2023 年记录数：`10`
- 因 `repo_id` 重复跳过：`0`
- 因规范化 `source_url` 重复跳过：`0`
- 实际新增记录数：`39`
- 合并后总记录数：`67`

合并前已备份 `data/history_projects.csv` 到本地 `data/history_projects.backup.<timestamp>.csv`，该备份文件不提交 Git。

### Clone 结果

新增 39 条中：

- clone 成功：`35`
- 已存在跳过：`0`
- clone 失败：`4`

失败项目：

| repo_id | source_url | 分类 |
| --- | --- | --- |
| `history_2024_003` | `https://gitlab.eduxiji.net/educg-group-26010-2376550/T202410287992637-1454` | `not_found_or_permission` |
| `history_2024_013` | `https://gitlab.eduxiji.net/educg-group-26010-2376550/T202418123993075-2940` | `not_found_or_permission` |
| `history_2023_003` | `https://gitlab.eduxiji.net/202310007101563/Alien` | `not_found_or_permission` |
| `history_2023_009` | `https://gitlab.eduxiji.net/404/OSKernel2023-SOS` | `not_found_or_permission` |

这些仓库由 GitLab 返回项目不存在或无访问权限；脚本已记录失败并继续处理后续仓库。日志和状态文件未写入密码、token 或带凭据 URL。

### Import 与 Validation 结果

新增 39 条中：

- import 成功：`35`
- import 失败：`4`
- validation 通过：`35`
- validation 失败：`0`
- 因 clone 失败缺失分析产物：`4`

按年份统计：

| year | metadata | complete_analysis | validation_passed | missing_analysis | validation_failed |
| --- | ---: | ---: | ---: | ---: | ---: |
| 2024 | 29 | 27 | 27 | 2 | 0 |
| 2023 | 10 | 8 | 8 | 2 | 0 |

当前 `outputs/history/` 下共有 `60` 个完整且通过校验的历史项目，可用于后续相似度检索。

完整明细见 `docs/history_library_2023_2024_expansion_report.md`。

## 7. 本次补充的工程保护

- `scripts/fetch_repos.py`：将空 URL 跳过状态规范为 `skipped_no_url`，并纳入 skipped 统计。
- `scripts/import_history.py`：补充顶层统计字段，输出 `outputs/history_import_status.json`，并增加单仓库分析超时保护。
- `team_deliveries/接口a/scripts/analyze_repo.py`：修复 C 函数名识别中可能触发正则慢回溯的问题，保持输出格式不变。

## 8. 下一步

历史库已经达到可用于相似度匹配的最低门槛。下一步应准备 2026 新作品仓库，例如：

`data/sample_repos/new_2026_001/`

当前该目录尚不存在，需要先把待分析的新仓库放到这个路径，或在运行命令时把 `--repo` 指向真实的新作品路径。

准备好后执行：

```bash
python3 scripts/run_pipeline.py \
  --repo data/sample_repos/new_2026_001 \
  --repo-id new_2026_001 \
  --out outputs/new_2026_001
```