# System Inventory

## 这份清单的用途

这个文件不再只罗列“模型目录里有什么大文件”，而是回答一个更重要的问题：当前仓库里哪些资产属于正式最终系统，哪些属于研究留档，哪些只是补充参考。

## 一类资产：正式模型资产

| 资产 | 路径 | 交付定位 | 说明 |
|---|---|---|---|
| BERT 最终权重 | `models/bert-final/` | 正式模型资产 | 微调得到的最终监督分类器 |
| RoBERTa 最终权重 | `models/roberta-final/` | 正式模型资产 | 微调得到的最终监督分类器 |
| Qwen general adapter | `models/qwen-adapters/general/` | 正式模型资产 | 通用文本 LoRA 分支 |
| Qwen short adapter | `models/qwen-adapters/short/` | 正式模型资产 | 76-180 字短文本 LoRA 分支 |
| Qwen ultra-short adapter | `models/qwen-adapters/ultra-short/` | 正式模型资产 | 0-75 字极短文本 LoRA 分支 |
| Qwen shared tokenizer | `models/qwen-adapters/shared-tokenizer/` | 正式模型资产 | 给 3 个 adapter 共用的一套 tokenizer |

边界说明：

- Qwen 基础模型权重不在仓库内。
- Qwen adapter 需要外部 `Qwen2.5-7B-Instruct` 才能运行。

## 二类资产：detector 分支资产

`FastDetectGPT` 和 `Binoculars` 也是正式最终系统的一部分，但它们的交付形式不是“一个单独的 checkpoint 目录”，而是算法脚本、配置语义和结果留档。

| 分支 | 资产位置 | 说明 |
|---|---|---|
| `FastDetectGPT` | `scripts/inference/run_zero_shot_detectors.py` + `results/` + `results/experiment-summaries/` | 基于 `Qwen2.5-3B` 与 `Qwen2.5-3B-Instruct` 的零样本打分 |
| `Binoculars` | `scripts/inference/run_zero_shot_detectors.py` + `results/` + `results/experiment-summaries/` | 与 FastDetectGPT 使用同一对 3B 模型，但打分公式不同 |

边界说明：

- detector 分支没有额外训练权重目录。
- detector 的正式存在方式是算法说明、分数文件和最终 ensemble 中的系数。

## 三类资产：正式结果资产

`results/` 是本仓库新增的正式结果区。它承接的是“最后结论”，不是训练过程快照。

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

## 四类资产：训练与实验留档

`reports/` 继续保留训练产物，用来支持溯源、复盘和核对，不直接承担“正式结果总入口”职责。

| 资产 | 路径 | 说明 |
|---|---|---|
| BERT baseline 留档 | `reports/bert-baseline/` | metrics、train/dev/test 预测、配置、日志 |
| RoBERTa baseline 留档 | `reports/roberta-baseline/` | metrics、train/dev/test 预测、配置、日志 |
| Qwen adapter 留档 | `reports/qwen-adapters/` | 各 adapter 的 metrics 和训练日志 |

## 五类资产：源码与配置

| 资产 | 路径 | 说明 |
|---|---|---|
| 共享模块 | `src/enhanced_replica/` | 数据处理、评估、模型工具、规则与 voter registry |
| 任务脚本 | `scripts/` | 训练、评估、推理、跨域实验、集成脚本 |
| 配置快照 | `configs/` | 训练参数、推理参数、正式 ensemble 配置 |
| 环境依赖 | `requirements.txt` | 当前仓库主依赖收口 |

## 六类资产：文档与归档

| 资产 | 路径 | 说明 |
|---|---|---|
| 主文档 | `docs/` | 最终系统、跨域结果、研究总结、数据说明等正式文档 |
| 旧文档归档 | `docs/archive/` | 旧版本地打包说明、审阅记录、原始 handoff 文档 |

## 如何判断“正式资产”还是“研究留档”

最简单的判断方式：

- 想看最终系统：先看 `results/`、`models/`、`configs/ensemble_config.json`、`docs/final_ensemble.md`
- 想看训练和实验过程：看 `reports/` 与 `scripts/train_eval/`
- 想看旧版本本地交接说明：看 `docs/archive/`

## 最容易被误读的一点

`src/enhanced_replica/voter_registry.py` 里的 `default_weight_champion` 和 `bucket_weights`，属于探索期硬投票研究路线，不是最终正式系统权重。正式最终权重只看：

- `results/final-system/ds13/ensemble_meta.json`
- `configs/ensemble_config.json`