1.终端与虚拟环境
-
base 和 venv 的区别（你经常看到 (venv) (base)）
-
为什么"装了包但 import 不到"
-
VS Code / PyCharm 运行时用的是哪个 Python
关键概念
-
解释器路径：which python / which pip
-
环境隔离：venv 里装的包只给这个工程用
-
正确运行方式：
-
命令行：python -m src.xxx
-
VS Code：选择解释器为 venv/bin/python
-
现在的状态
✅ 已经能创建 venv、安装 pandas、MeCab，并能在终端跑通
⬆️ 还需要强化：解释器选择 和环境一致性
2.Python 包与导入机制
-
为什么 python src/metrics/xxx.py 会找不到 src
-
为什么 python -m src.metrics.xxx 可以
-
init.py 的作用
关键概念
-
模块搜索路径：sys.path
-
包：目录 + init.py
-
-m 的意义：把工程根目录当作包入口运行（更稳定）
现在的状态
✅ 已经知道要把 src 变成包
⬆️ 还需要：理解"相对导入/绝对导入"的规则与最佳实践
3. 路径与文件组织（工程化最核心）
需要搞清楚
-
为什么要把 input/output/resources 分开
-
为什么要用 Path() 而不是字符串
-
为什么 Streamlit 上传文件要写进临时目录
关键概念
-
pathlib.Path：跨平台、可读性强
-
相对路径 vs 绝对路径
-
BASE_DIR = Path(file).resolve().parents[1] 这种写法的意义（项目根目录定位）
现在的状态
✅ 已经按"工程结构"拆分好了文件夹
⬆️ 还需要：熟练处理"当前工作目录 (cwd)"导致的路径错误
4. 编码与文本预处理
需要搞清楚
-
什么是 UTF-8 / UTF-8-sig / cp932 / shift-jis
-
为什么 len(text) 很大但 MeCab token 只有 2（BOS/EOS）
-
为什么 \x00（NUL）会让 MeCab "吃不到内容"
关键概念
-
bytes vs str
-
解码策略：尝试多种编码，最后 replace 兜底
-
normalize_text：去 BOM、去 NUL、统一换行（放在 IO 层最合理）
现在的状态
✅ 已经有 io_utils.py 并把 normalize 做进 read_text_auto
⬆️ 还需要：知道"什么时候应该在 IO 层处理、什么时候在 NLP 层处理"
5. 数据结构：Token 设计
需要搞清楚
-
Token 里哪些字段是必须的：surface, lemma, pos, pos1, reading...
-
为什么很多指标都依赖 lemma（类符）而不是 surface（形符）
-
pos（細分類）与 pos1（大分類）的区别
关键概念
-
用 dataclass 表达 Token（类型清晰）
-
统一 Token 字段命名，避免每个模块各写各的
现在的状态
✅ 已经能围绕 Token 写密度/多样性/难度/组合性
⬆️ 还需要：系统理解"字段一致性"对项目可维护性的影响
6. 指标计算的"可复用设计"
需要搞清楚
-
为什么 4 个 metrics 文件要分开
-
为什么要写成 compute_xxx(tokens, ...) -> dict
-
为什么要把可变参数（阈值、OOV）作为函数参数，而不是写死路径
关键概念
-
纯函数思维：输入 tokens，输出 dict（无副作用）
-
参数化：threshold / treat_oov_as_low / shugo_map / freq_rank_map
-
小工具函数：_is_punct, _filter_verbs 等
现在的状态
✅ 架构思路已经是"研究可复现"的写法
⬆️ 还需要：学会写更稳的异常处理（空文本、短文本、缺字段）
7.批处理与 DataFrame 合并输出（run_batch）
你需要搞清楚
-
为什么要 row.update(...) 拼接 4 个 dict
-
为什么把 file_name 放首列要做 cols = [...]
-
为什么输出用 utf-8-sig（Excel 兼容）
关键概念
-
list[dict] → DataFrame
-
列顺序控制
-
输出目录创建：mkdir(parents=True, exist_ok=True)
现在的状态
✅ 已经能把整套指标输出成一个 CSV
⬆️ 还需要：学习"日志/进度条"和"异常文件跳过策略"
8. Streamlit：把脚本变成小应用
需要搞清楚
-
为什么要用 streamlit run xxx.py
-
Local URL vs Network URL 的区别
-
上传文件是 bytes，需要你自己保存/解码/清洗
关键概念
-
UI 与计算分离：Streamlit 只负责交互，计算调用 run_batch.main
-
临时目录：tempfile.TemporaryDirectory()
-
研究者版 vs 学生版：显示层不同，计算层相同
现在的状态
✅ 已经把工程跑到可用 app 的阶段
⬆️ 还需要：会做基本的 UI 组织（expander、tabs、下载按钮、参数面板）