更新readme

 # 词曲 & 音眼资产导入工具
 
+本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 `hk_songs` 表，并提供：
+
+- **L1 层**：基于元数据（歌名 + 词曲作者）的六步标准化去重
+- **L2 层**：基于歌词文本 Jaccard 相似度的深度去重
+- **ETL 管道**：将词曲库数据同步至爬虫库（crawler），支持断点续传
+- **审计工具**：库内重复数据审计、L2 歌词审计、BPM 分类补全
+- **复核前端**：L2 去重测试的人工评审看板
+
+## 项目结构
+
+```
+.
+├── import_hk_songs.py              # 主脚本：聚合查询、L1/L2 去重、导入
+├── run_etl.py                      # ETL 入口：hk_songs → crawler 库同步
+├── etl_to_crawler/                 # ETL 管道模块
+│   ├── config.py                   # 多库 & OSS 配置
+│   ├── connections.py              # 数据库连接管理
+│   ├── reader.py                   # 源表分批读取
+│   ├── spider.py                   # 平台数据抓取/构造
+│   ├── writer.py                   # 目标库写入
+│   ├── runner.py                   # 编排引擎（断点续传）
+│   ├── lyric.py                    # 歌词下载与处理
+│   └── oss.py                      # OSS 上传
+├── lyric_dedup/                    # 歌词去重核心模块
+│   ├── normalization.py            # 歌词文本规范化（NFKC + OpenCC）
+│   ├── checker.py                  # 去重匹配逻辑（L1/L2 六步算法）
+│   ├── eval_dataset.py             # 评测数据集构建
+│   ├── file_import.py              # 文件导入工具
+│   └── cli.py                      # CLI 入口
+├── audit_hk_songs_duplicates.py    # L1 元数据重复审计 & 合并修复
+├── audit_hk_songs_l2.py            # L2 歌词去重库内审计（下载+比对）
+├── backfill_bpm_class.py           # BPM 分类增量补全
+├── migrate_test_to_prod.py         # 测试表 → 正式表迁移（含 COS 转存）
+├── patch_merge_authors.py          # 作者合并补处理脚本
+├── create_hk_songs_import_staging.sql  # 暂存表建表 DDL
+├── serve_l2_dashboard.py           # L2 复核前端服务
+├── l2_review_dashboard.html        # 前端页面
+├── tests/                          # 单元测试
+│   ├── test_lyric.py
+│   ├── test_oss.py
+│   ├── test_reader.py
+│   ├── test_runner.py
+│   ├── test_spider.py
+│   └── test_writer.py
+├── test_dedup.py                   # 去重单元测试 & L2 benchmark
+├── test_audit_hk_songs_duplicates.py  # 审计脚本单元测试
+├── docs/                           # 文档
+├── requirements.txt                # Python 依赖
+├── 测试流程指南.md                  # L2 测试流程说明
+├── 音眼数据库配置.md                # 数据库配置说明
+├── 音眼词曲跨库去重任务清单.md      # 跨库去重任务清单
+└── .env                            # 环境配置（不纳入版本控制）
+```
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. 配置数据库
+
+复制 `.env.example` 为 `.env` 并填写数据库连接信息：
+
+```env
+# 源库 - 音眼
+SOURCE_DB_HOST=
+SOURCE_DB_PORT=3306
+SOURCE_DB_USER=
+SOURCE_DB_PASSWORD=
+SOURCE_DB_NAME=
+
+# 目标库 - 词曲库
+TARGET_DB_HOST=
+TARGET_DB_PORT=3306
+TARGET_DB_USER=
+TARGET_DB_PASSWORD=
+TARGET_DB_NAME=
+TARGET_TABLE_NAME=hk_songs
+
+# OSS 配置
+OSS_ACCESS_KEY_ID=
+OSS_ACCESS_KEY_SECRET=
+OSS_ENDPOINT=
+OSS_BUCKET_NAME=
+OSS_FILE_BASE_NAME=
+```
+
+### 3. 运行数据导入
+
+```bash
+python import_hk_songs.py --help
+```
+
+### 4. 运行 ETL 同步至爬虫库
+
+```bash
+# 全量同步（支持断点续传）
+python run_etl.py --resume
+
+# 冒烟测试（仅前 3 批）
+python run_etl.py --max-batches 3
+
+# 指定平台
+python run_etl.py --platform qq --resume
+```
+
+### 5. 审计工具
+
+```bash
+# L1 元数据重复审计
+python audit_hk_songs_duplicates.py
+
+# L1 应用合并（软删 loser + 作者增量合并）
+python audit_hk_songs_duplicates.py --apply-merge
+
+# L2 歌词去重审计（下载 + 比对）
+python audit_hk_songs_l2.py --phase all --workers 32
+
+# BPM 分类补全
+python backfill_bpm_class.py --dry-run
+
+# 测试表迁移至正式表
+python migrate_test_to_prod.py --limit 10 --dry-run
+```
+
+### 6. 运行 L2 歌词去重测试
+
+小样本验证：
+
+```bash
+RUN_L2_BENCHMARK=1 \
+L2_BENCHMARK_LIMIT=20 \
+L2_BENCHMARK_EXISTING_LIMIT=50 \
+L2_BENCHMARK_TOPKS=20,100 \
+python -m pytest test_dedup.py::TestL2Benchmark::test_l2_recall_topk_efficiency_and_review_artifacts -q -s
+```
+
+详见 [测试流程指南.md](./测试流程指南.md)。
+
+### 7. 启动复核前端
+
+```bash
+python serve_l2_dashboard.py --host 127.0.0.1 --port 8765
+```
+
+然后访问 http://127.0.0.1:8765 查看测试报告、比对歌词、人工标注。
+
+## 单元测试
+
+```bash
+# 去重测试
+python -m pytest test_dedup.py -q
+
+# ETL 模块测试
+python -m pytest tests/ -q
+
+# 审计脚本测试
+python -m pytest test_audit_hk_songs_duplicates.py -q
+```
+
+## 注意事项
+
+- `.env` 文件包含数据库凭据，**不要**提交到仓库。
+- `output/` 目录存放测试报告和缓存文件，不纳入版本控制。
+- CSV / SQL / Excel 等数据文件不纳入版本控制。
+# 词曲 & 音眼资产导入工具
+
 本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 `hk_songs` 表，并提供 L2 歌词去重测试和人工复核前端。
 
 ## 项目结构