# 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 仓库。
- 作为后续继续做误差分析、短文本扩展、跨域对比的基座。