WORKSPACE_STATUS.md

# WORKSPACE STATUS — CS3319 Project 2 Final Deliverable

> 本文件由代码仓库快速勘察生成,用于帮助后续开发者快速熟悉本目录。
> **最后更新**:2026-06-17

---

## 一、项目简介

### 1.1 项目定位
本项目是 **CS3319 推荐系统课程(Project 2)的最终交付物**。

- **业务目标**:构建**学术论文阅读推荐系统**——在学术平台上为学者推荐其可能感兴趣/应阅读的论文。
- **建模方式**:形式化为**异构学术网络中的链路预测(Link Prediction)**问题。
- **网络结构**:
  - 节点:作者(author,0–6610)、论文(paper,0–79936)
  - 边:作者-论文阅读/引用关系(二部图)、作者-作者合著关系(无向)、论文-论文引用关系(有向)
- **预测任务**:对测试集中的每个 `(author, paper)` 对,输出 `1`(推荐)/`0`(不推荐)。
- **评估指标**:Public Leaderboard **F1**。
- **最佳确认成绩**:**Public F1 = 0.96626**
  - 方法:rich content + 7 个随机游走块 + 有向高阶引用传播 + LightGBM,rank top 50% 决策。

### 1.2 核心技术栈
- **语言**:Python 3.10
- **数据处理**:`numpy`、`pandas`、`scipy`
- **传统机器学习**:`scikit-learn`、`lightgbm`、`xgboost`
- **深度学习 / GNN**:`torch`、`torch-geometric`
- **图嵌入 / 随机游走**:`gensim`、`node2vec`、`networkx`
- **核心模型族**:LightGCN 风格异构图卷积推荐器(BPR loss + hard negatives),最终方案为多源特征 + LightGBM 二阶段堆叠。

### 1.3 数据来源
数据由 Acemap group 提供,采集自 GeoScience 领域顶刊:
- **6,611 位作者**、**79,937 篇论文**及其引用信息。
- 论文节点附带预训练特征 `feature.pkl`。

---

## 二、目录结构解析

```
26H1_cs3319_final_deliverable/
├── README.md                         项目总览、最佳成绩、复现命令
├── WORKSPACE_STATUS.md               本文件(项目现状日志)
│
├── code/                             核心:全部训练与提交生成脚本(详见第五节)
│
├── data_and_docs/                    官方数据 + 课程文档
│   ├── bipartite_train_ann.txt       训练集二部网络(author-paper)
│   ├── bipartite_test_ann.txt        测试集待预测对
│   ├── author_file_ann.txt           作者合著网络(无向)
│   ├── paper_file_ann.txt            论文引用网络(有向)
│   ├── feature.pkl                   论文预训练特征(约 156 MB)
│   ├── dataset.md / project_description.md / advice.md  数据/项目说明
│   ├── proposal.md                   开题提案
│   ├── references.md                 参考文献
│   ├── project_evaluation.md         评估说明
│   ├── project-example-2026-pygver.ipynb  官方示例 Notebook(PyG 版)
│   └── project2_ recmendation systems.pdf  课程项目书
│
├── checkpoints/                      LightGCN 模型权重(⚠️ 当前为空,见第四节)
│   ├── extra_models/
│   └── final_ens6/
│
├── cached_scores/                    早期缓存的分数/模型
│   ├── lgb_model.pkl / lgb_v2_model.pkl
│   ├── test_bpr_cos.npy / test_bpr_dot.npy
│   ├── test_lgb_scores.npy / test_lgb_v2_scores.npy
│   ├── test_known_mask.npy
│   ├── dot_full/
│   └── large_ensemble/
│
├── validation_runs/                  验证运行结果
│   ├── dynamic_summary.csv
│   ├── stack_ratio_analysis.csv
│   ├── stack_threshold_summary.csv
│   ├── dynamic_seed202/              (⚠️ 仅目录壳,内容缺失)
│   └── feature_cache/                (⚠️ 仅目录壳,内容缺失)
│
├── submissions/                      已确认的提交文件
│   ├── sub_ens6_t0.35.csv
│   ├── sub_ens6_t0.36.csv  ← 纯 LightGCN 路线最佳(公开 0.93044)
│   └── sub_ens6_t0.37.csv
│
├── reports/                          报告
│   ├── preliminary_report.md
│   ├── exploration_summary.md
│   └── final_report.md
│
├── notes/
│   └── experiment_history.md         完整实验历史(10 个阶段)
│
└── manifests/                        原始传输包的文件清单
    ├── package_manifest.txt          完整交付包文件+大小清单
    ├── final_deliverable_filelist.tsv
    ├── home_artifacts_manifest.txt
    └── key_files_sha256.txt
```

---

## 三、运行与配置

### 3.1 环境配置(⚠️ 配置文件当前缺失)
README 引用的环境文件位于 `env/` 目录:
```
env/environment-cs3319.yml
env/requirements-minimal.txt
```
**注意**:本目录下 **`env/` 文件夹不存在**(本副本为精简包,详见第四节)。如需重建环境,可参照 `manifests/package_manifest.txt` 与 `manifests/home_artifacts_manifest.txt` 中的 `conda-list-cs3319.txt` 记录,或按以下核心依赖手动安装:

```bash
# Python 3.10
pip install numpy pandas scipy scikit-learn lightgbm xgboost \
            torch torch-geometric gensim node2vec networkx
```

### 3.2 快速验证最终结果(只读)
```bash
cd cs3319_final_deliverable

# 查看最终验证指标(注:依赖 validation_runs/dynamic_seed202/,当前缺失)
cat validation_runs/dynamic_seed202/high_order_graph_stack/validation_summary.csv

# 查看最终提交生成摘要(注:同上,当前缺失)
cat validation_runs/dynamic_seed202/high_order_graph_stack/submission_summary.csv
```
预期关键验证行(README 记录):
```
rich_rw7_highorder_directed validation F1 = 0.966873736337297
```

### 3.3 复现最终高阶堆叠方法(⚠️ 依赖缺失,当前可能不可运行)
```bash
python code/high_order_graph_stack.py \
  --package-root . \
  --split-seed 202 \
  --seed 202 \
  --n-splits 5 \
  --make-submission
```
**依赖前提**:需要 `validation_runs/dynamic_seed202/`(OOF/test 分数、随机游走权重)与 `validation_runs/feature_cache/`(高阶/富内容特征)。当前两者内容均缺失,直接运行大概率会因找不到输入文件而失败。

### 3.4 复现早期 6 模型 LightGCN 集成(⚠️ 权重缺失)
```bash
python code/generate_ens6_submission.py \
  --package-root . \
  --device cuda:0   # 或 cpu
```
**依赖前提**:需要 `checkpoints/final_ens6/model_lgcn_*.pt`。当前该目录为空,无法直接运行。

---

## 四、当前状态与进度

### 4.1 开发阶段(已完成,据 `notes/experiment_history.md`)
项目经历了 10 个实验阶段,可归为四条主线:

| 阶段 | 方法 | 代表脚本 | 结果 |
|---|---|---|---:|
| A. GNN 基线 | 异构 GNN(SAGEConv/HeteroMeanConv + BCE/BPR) | `run_baseline.py`、`run_improved.py`、`run_v2.py` | 验证 F1 ≈ 0.885–0.92 |
| B. LightGCN 主线 | 原生 LightGCN + BPR + hard negatives + 多 seed 集成 | `run_final.py`、`run_lgcn_final.py`、`generate_ens6_submission.py` | 公开 0.93044 |
| C. 特征模型 | LightGBM 结构特征 / BPR-MF / 随机游走 | `run_graph_features.py`、`extra_score_sources_ablation.py` | 公开 0.95760–0.96252 |
| D. 高阶堆叠(最终) | rich content + 7 RW 块 + 高阶引用传播 + LightGBM | `high_order_graph_stack.py` | **公开 0.96626** |

**最终方法**:LightGBM 二阶段堆叠,特征包括 LightGCN 分数/排名、图与元路径特征、内容余弦相似度、BPR-MF、富作者内容画像、7 个 DeepWalk/Node2Vec 块、随机游走一致性、高阶引用传播(`A-P-P^k`、`A-A-P-P^k` 等)。决策规则为 **rank top 50%**(而非概率阈值,更鲁棒地应对验证-测试分布偏移)。

### 4.2 ⚠️ 仓库当前状态(重要)

**1) 非 Git 仓库**
- 本目录 **`.git` 不存在**,**无法**查看分支、未提交改动或提交历史。
- 所有版本管理信息不可用,无法通过 git 追溯变更。

**2) 精简/部分副本**
与 README 及 `manifests/package_manifest.txt` 描述的完整交付包相比,本目录缺失多项关键产物:

| 缺失项 | 影响 |
|---|---|
| `env/`(环境配置目录) | 无法直接还原 conda/pip 环境 |
| `checkpoints/extra_models/`、`checkpoints/final_ens6/`(权重 `.pt`) | 无法复现任何 LightGCN 推理/集成 |
| `validation_runs/dynamic_seed202/`(OOF/test 分数、RW 权重、最终提交) | 无法复现/验证最终高阶堆叠方法 |
| `validation_runs/feature_cache/`(高阶/富内容特征) | 同上 |
| `submissions/` 中 `sub_final3_*`、`sub_noforce_*`、`sub_forced_*` | 早期对比提交缺失 |

**结论**:当前目录本质是**代码 + 数据 + 文档 + 部分早期缓存**的快照,**不包含最终方法所需的权重与缓存特征**,因此**无法直接复现最终成绩 0.96626**。如需完整复现,需从原始传输包(参见 `manifests/`)重新获取缺失的大体积产物。

### 4.3 未完成 / 受限事项
- [ ] **恢复 `env/` 环境配置文件**,或补全依赖清单以便重建运行环境。
- [ ] **恢复 `checkpoints/` 下的 LightGCN 权重**,以支持推理/集成复现。
- [ ] **恢复 `validation_runs/dynamic_seed202/` 与 `feature_cache/`**,以支持最终高阶方法的复现与验证。
- [ ] (可选)**初始化 Git 仓库**以启用版本管理:`git init`。

---

## 五、核心脚本速查表

### 训练 / 基线类
| 脚本 | 用途 |
|---|---|
| `run_baseline.py` | 官方 Notebook 基线(HeteroMeanConv + cosine + 阈值搜索) |
| `run_improved.py` | 改进异构 GNN(HeteroConv+SAGEConv + 残差/LN + MLP 解码 + hard negatives) |
| `run_v2.py` | SAGEConv + BPR 排序变体 |
| `run_final.py` | 原生 LightGCN 最终版(早期) |
| `run_lgcn_final.py` | 原生 LightGCN(主线稳定版) |
| `run_lgcn_v2.py` | L2 归一化 LightGCN 变体(效果劣于原生) |
| `run_graph_features.py` | 手工图特征 + LightGBM |
| `run_ultimate.py` | Ultimate 综合实验 |
| `compare_gnn.py` | GNN 架构搜索(可学习层权/GAT/SAGE/Deep/Wide LightGCN) |

### 动态验证 / 集成训练类(README 核心)
| 脚本 | 用途 |
|---|---|
| `train_val_lgcn_ensemble.py` | **动态验证 LightGCN 训练与分数生成**(核心) |
| `train_dynamic_feature_fusion.py` | 动态特征融合训练 |
| `train_val_mf_bpr.py` | MF + BPR 训练 |
| `train_val_sage_bpr.py` | SAGE + BPR 训练 |
| `train_val_hgt_bpr.py` | HGT + BPR 训练 |
| `evaluate_val_checkpoints.py` | 验证 checkpoint 评估 |

### 消融 / 特征构建类
| 脚本 | 用途 |
|---|---|
| `extra_score_sources_ablation.py` | Content-mean-cos / BPR-MF / ranker 分数源消融 |
| `node2vec_deepwalk_ablation.py` | DeepWalk / Node2Vec 初始消融 |
| `randomwalk_systematic_ablation.py` | **系统随机游走特征实验**(产出最终 7 块) |
| `randomwalk_ensemble_ablation.py` / `randomwalk_one_ablation.py` | RW 集成/单块消融 |
| `content_rich_ablation.py` | **Rich `feature.pkl` 内容特征构建** |
| `post95_ablation.py` | Post95 消融 |
| `high_order_model_compare.py` | 高阶模型对比 |

### 提交生成类
| 脚本 | 用途 |
|---|---|
| `high_order_graph_stack.py` | **最终:高阶引用传播实验 + 提交生成**(产出 0.96626) |
| `generate_ens6_submission.py` | 6 模型 LightGCN 集成提交 |
| `generate_post95_submission.py` | Post95 LightGCN + 图/内容特征提交 |
| `generate_extra_bprmf_submission.py` | BPR-MF 提交 |
| `generate_node2vec_deepwalk_submission.py` | DeepWalk/Node2Vec 提交 |
| `generate_randomwalk_ensemble_submission.py` | 随机游走集成提交(喂入最终阶段) |
| `generate_randomwalk_single_submission.py` | 单随机游走提交 |
| `generate_content_rich_submission.py` | Content-rich 提交 |
| `generate_dot_submission.py` | Dot 内积提交 |
| `generate_large_ensemble_submission.py` | 大型集成提交 |
| `generate_conservative_rw_blends.py` | 保守随机游走混合 |

### 堆叠 / 校准 / 搜索类
| 脚本 | 用途 |
|---|---|
| `rich_randomwalk_stack.py` | Rich 随机游走堆叠 |
| `score_level_meta_stack.py` | 分数级元堆叠 |
| `stack_rank_calibration.py` | 堆叠排序校准 |
| `error_group_calibration.py` | 错误分析/阈值扫描/分组校准/边界模型 |
| `search_dynamic_fusion.py` / `search_val_fusion.py` | 动态/验证融合搜索 |
| `make_notebook_style_split.py` | Notebook 风格数据划分 |

---

## 六、建议阅读顺序(熟悉项目)

1. `README.md` —— 全局概览与复现命令
2. `data_and_docs/dataset.md` + `project_description.md` —— 任务与数据定义
3. `notes/experiment_history.md` —— 完整方法演进史(强烈推荐)
4. `reports/final_report.md` —— 最终方案与结论
5. `reports/preliminary_report.md` + `exploration_summary.md` —— 早期探索