本项目是一个面向研究实验的 Python 骨架，用于在 Hugging Face 预训练语言模型上对比 RoPE 与 PoPE 位置编码方案，并在指定层提取隐藏状态、训练 TopK SAE，输出可复用的评估产物（重构误差、稀疏度、特征级统计等）。当前版本优先保证目录结构、模块边界、配置对象 CFG、双模式 Pipeline（run / reproduce）、缓存与输出分离；PoPE 的真实替换、SAE 的进阶损失与可解释性指标等，在代码中以 TODO 明确标出，避免过早引入复杂实现。

project_root/
├── main.py
├── README.md
├── requirements.txt
├── cache/                 # 仅中间缓存（模型、数据集、分词结果、激活、SAE 权重）
│   ├── hf_models/
│   ├── hf_datasets/
│   ├── tokenized/
│   ├── activations/
│   └── checkpoints/
├── outputs/               # 仅实验产物（运行摘要、表、图、日志）
│   ├── runs/
│   ├── tables/
│   ├── figures/
│   └── logs/
└── core/                  # 核心逻辑（禁止改名为 src/ 等）
    ├── parameters.py    # CFG
    ├── dataset.py       # DatasetManager
    ├── model.py         # ModelManager
    ├── sae.py           # TopKSAE
    ├── train.py         # SAETrainer
    ├── evaluate.py      # Evaluator（注意：文件名必须是 evaluate.py）
    └── pipeline.py      # ExperimentPipeline（run / reproduce）

pip install -r requirements.txt

首次运行会从 Hugging Face 拉取模型与数据集，体积较大；做快速联调时建议在 CFG 中减小 max_samples、max_length、sae_hidden_dim、sae_epochs，并确认 sae_input_dim 与模型 hidden_size 一致（TinyLlama-1.1B 为 2048）。

python main.py

默认 positional_encoding_type="rope"。若设为 "pope" 且 monkey_patch_pope=True，当前骨架会在 ModelManager.prepare() 处抛出 NotImplementedError，提示你实现 PoPE 的具体替换逻辑（见 core/model.py 内 TODO）。

在已经成功执行过一次 run() 并生成 outputs/runs/<experiment_name>/config.json 之后：

from core.parameters import CFG
from core.pipeline import ExperimentPipeline

cfg = CFG()  # experiment_name 需与当初一致
ExperimentPipeline(cfg).reproduce()

reproduce() 会尽量复用 cache/tokenized/、cache/activations/、cache/checkpoints/ 中的中间结果，并重新跑评估以刷新 outputs/tables/ 与 outputs/figures/。

• 单一配置入口：所有模块只读 CFG（core/parameters.py）。
• Pipeline 双模式：ExperimentPipeline.run() 全流程；reproduce() 面向论文式复现。
• 一文件一主类：DatasetManager、ModelManager、TopKSAE、SAETrainer、Evaluator、ExperimentPipeline；避免大量零碎自由函数。
• 大阶段方法：如 prepare()、collect()、run()、evaluate()，减少跳转阅读成本。
• cache / outputs 严格分离：中间张量与 checkpoint 只进 cache/；表格、图、运行 JSON 只进 outputs/。

• PoPE：在 ModelManager 中实现真正的注意力/旋转位置模块替换，并与 CFG.positional_encoding_type 对齐。
• 数据：去重、验证集划分、流式数据集等。
• SAE：更贴近论文的训练目标（辅助稀疏项、死特征处理、学习率策略等）。
• 评估 / 可解释性：在 Evaluator 中扩展 probing、干预、解耦等指标，保持接口稳定、实现可插拔。