docs/project_overview.md

# Project Overview

## 仓库定位

这是一个面向 Hugging Face 交付的完整研究仓，目标不是只保留模型文件，而是把模型、数据、源码、正式结果和解释文档一起收口成一个稳定的研究资产包。

## 一级结构

当前仓库由 8 个一级部分组成：

| 路径 | 作用 |
|---|---|
| `data/` | 仓库内置数据区，包含 5 个可直接实验的数据集，以及人工原料、AI 生成文本和提示词资产 |
| `models/` | 最终保留的模型资产，只保留 BERT / RoBERTa 权重与 3 个 Qwen adapter |
| `src/` | 共享 Python 模块，例如数据工具、评估工具、模型工具、voter registry |
| `scripts/` | 训练、评估、推理、集成、跨域实验入口脚本 |
| `configs/` | 训练、推理、最终 ensemble 的配置快照 |
| `reports/` | 训练产物、日志、metrics、manifest、payload 和压缩预测文件 |
| `results/` | 正式研究结果区，收纳最终系统和跨域结论 |
| `docs/` | 主说明文档与归档文档 |

## `reports/` 和 `results/` 的区别

这次重构里最重要的接口变化之一，就是明确把 `reports/` 和 `results/` 分开：

- `reports/` 只承担训练产物和训练留档角色。
- `results/` 只承担正式研究结论和预测留档角色。

如果想看“最终系统是什么”，应该先看 `results/` 和 `docs/final_ensemble.md`，而不是先去翻 `reports/`。

## `results/` 的固定分区

`results/` 当前固定为 4 类内容：

| 路径 | 作用 |
|---|---|
| `results/final-system/ds13/` | DS13 正式 7-voter ensemble 结果 |
| `results/final-system/upstream-voters/ds13/` | DS13 上游 voter 输出，用于追溯最终 ensemble |
| `results/final-system/ds01-reference/` | DS01 参考 bundle，用来解释 fallback 训练语境 |
| `results/cross-domain/` | DS06 / DS07 的跨域 bucket ensemble 正式结论 |
| `results/experiment-summaries/` | 单模、detector、最终系统的紧凑摘要 |
| `results/results_manifest.json` | 机器可读结果清单 |

## `docs/` 的组织规则

`docs/` 现在分成两层：

- 正式主文档：直接服务于交接与阅读，例如 `final_ensemble.md`、`cross_domain_results.md`、`research_summary.md`
- `docs/archive/`：旧版本地整理说明、审阅记录、原始 handoff 文档的归档区

这意味着旧文档仍然保留，但已经不再承担主说明职责。新读者应当从根 README 和主文档开始，而不是从 archive 开始。

## 模型边界

- Qwen：只保留 adapter，不保留基础模型权重。
- BERT / RoBERTa：保留最终微调权重和必要 tokenizer / config。
- FastDetectGPT / Binoculars：保留算法脚本与结果文件，不保留所谓“detector checkpoint”，因为它们本质上不是额外训练出来的分类模型。

## 数据边界

仓库当前内置了研究最终保留的数据资产，但仍然有明确边界：

- 已包含：5 个可直接实验的数据集、人工原料、AI 生成文本原料、提示词资产。
- 未包含：公网 benchmark 的原始下载包本体，以及整套外部 benchmark 镜像。

## 这份仓库适合什么用途

- 作为 Hugging Face 上的完整研究资产仓。
- 作为模型、数据、结果和说明同步交付的 handoff 仓库。
- 作为后续继续做误差分析、短文本扩展、跨域对比的基座。