diff --git a/.gitignore b/.gitignore index bf42945..b04d088 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Copyrighted lyrics cache — never commit full lyrics -data/lyrics/ +data/captures/lyrics/ # Secrets .env diff --git a/CLAUDE.md b/CLAUDE.md index 1a092dc..cd6f7f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,9 +21,11 @@ ## Data rules -- `data/yearend_hot100_2016_2025.csv` is the only hand-placed - raw file; everything else in `data/` is script-derived. -- Full lyrics are copyrighted: they stay in `data/lyrics/` +- `data/source/` holds the immutable hand-placed raw files; + `data/captures/` is written only by the fetch commands and the + private import script; `data/manual/` is written only by the + user's own hand. +- Full lyrics are copyrighted: they stay in `data/captures/lyrics/` (gitignored) and must never be committed or reproduced in full anywhere in the repo. diff --git a/README.md b/README.md index e2535ae..0a841d8 100644 --- a/README.md +++ b/README.md @@ -21,17 +21,17 @@ Hot 100(2016–2025)為例的內容分析。 3. 依 `docs/research_plan.md` 的階段順序,於 `tools/` 目錄下 執行子命令,必要輸入以位置引數、選擇性輸入以選項給定(如 `pop-fem-audit-tools build-db - ../data/yearend_hot100_2016_2025.csv - --lyrics-dir ../data/lyrics - --wikidata-csv ../data/artists_wikidata.csv - --overrides-csv ../data/artists_overrides.csv`)。 + ../data/source/yearend_hot100_2016_2025.csv + --lyrics-dir ../data/captures/lyrics + --wikidata-csv ../data/captures/artists_wikidata.csv + --overrides-csv ../data/manual/artists_overrides.csv`)。 LLM 步驟使用 `claude-sonnet-4-6`、temperature=0、 thinking 關閉;每步驟獨立執行兩次後由仲裁步驟合併 (「2+1」協定)。 4. 每次執行的完整紀錄(定義檔快照、原始輸出、參數)存於 `runs/`,可逐筆稽核。論文引用的最終資料表在 `results/`。 -注意:歌詞受版權保護,`data/lyrics/` 不隨 repo 發布,須自行 +注意:歌詞受版權保護,`data/captures/lyrics/` 不隨 repo 發布,須自行 以 `tools/` 中的抓取程式重建。 ## 授權 diff --git a/data/yearend_hot100_2016_2025.csv b/data/source/yearend_hot100_2016_2025.csv similarity index 100% rename from data/yearend_hot100_2016_2025.csv rename to data/source/yearend_hot100_2016_2025.csv diff --git a/docs/decision_log.md b/docs/decision_log.md index a3aaa3c..153cf04 100644 --- a/docs/decision_log.md +++ b/docs/decision_log.md @@ -119,3 +119,8 @@ settings 的 `.env` 依 pydantic 慣例讀自 CWD(約定 `tools/`),資料路徑原以 repo 根為 CWD,兩者衝突;顯式引數 消滅隱性 CWD 契約,亦拒絕以父目錄推導兄弟檔案的隱性慣例。 +- **`data/` 依生命週期分三層**:`source/`(源頭,手放後不動)、 + `captures/`(外部捕捉,只由 fetch 命令與私人匯入腳本寫入)、 + `manual/`(人工著作,只由研究者手寫;之後的黃金標準編碼 + 亦居此)。理由:三種生命週期混住一層,目錄無法傳達「誰可以 + 寫哪裡」;顯式引數化後搬遷零程式改動。 diff --git a/docs/project_structure.md b/docs/project_structure.md index f5a6e76..efdcd4b 100644 --- a/docs/project_structure.md +++ b/docs/project_structure.md @@ -8,16 +8,20 @@ pop-fem-audit/ ├── README.md # 專案說明、重現步驟 ├── CLAUDE.md # 極簡工作規範(subagent 會讀到, │ # 絕不放理論、codebook、預期結果) -├── .gitignore # data/lyrics/、.env、scratch +├── .gitignore # captures/lyrics/、.env、scratch ├── conference_abstract.md # pilot 摘要(投稿版) -├── data/ # 源頭與捕捉層(文字格式,進 git) -│ ├── yearend_hot100_2016_2025.csv # 原始榜單(唯一手放原始檔) -│ ├── artists_wikidata.csv # 捕捉:Wikidata 快照 -│ ├── artists_overrides.csv # 人工核定 / 深度背景 -│ ├── lyrics_provenance.csv # 歌詞出處(source + method) -│ ├── lyrics_missing.csv # 歌詞缺漏報表(人工補救用) -│ └── lyrics/ # 歌詞 .txt 快取 -│ # (gitignored,版權) +├── data/ # 依生命週期分三層(文字格式) +│ ├── source/ # 源頭:手放後不動 +│ │ └── yearend_hot100_2016_2025.csv # 原始榜單 +│ ├── captures/ # 外部捕捉:只由 fetch 命令與 +│ │ │ # 私人匯入腳本寫入 +│ │ ├── artists_wikidata.csv # Wikidata 快照 +│ │ ├── lyrics_provenance.csv # 歌詞出處 +│ │ ├── lyrics_missing.csv # 歌詞缺漏報表 +│ │ └── lyrics/ # 歌詞 .txt 快取 +│ │ # (gitignored,版權) +│ └── manual/ # 人工著作:只由研究者手寫 +│ └── artists_overrides.csv # 人工核定 / 深度背景 ├── prompts/ # LLM 定義檔(逐字作為 system prompt) │ └── _v.md # 版本化:screen_v1.md、judge_v2.md… ├── tools/ # 輔助工具子專案(src-layout) @@ -36,7 +40,7 @@ pop-fem-audit/ │ │ ├── fetch_artists.py # fetch artist metadata from │ │ │ # Wikidata into the snapshot CSV │ │ ├── fetch_lyrics.py # fetch missing lyrics from the -│ │ │ # public APIs into data/lyrics/ +│ │ │ # public APIs into the lyrics dir │ │ ├── models.py # SQLAlchemy ORM 資料模型 │ │ └── run_llm.py # API runner:2+1 協定、Batch API、 │ │ # 寫入引數指定的 runs 目錄;執行 diff --git a/docs/research_plan.md b/docs/research_plan.md index 264387f..da1f856 100644 --- a/docs/research_plan.md +++ b/docs/research_plan.md @@ -61,7 +61,7 @@ 匯入歌詞快取——只取識別欄位與歌詞本文,以 (year, rank) 精確匹配 song_id。匯入工具不屬於專案交付物 (讀者拿不到其輸入),讀者的重現路徑純粹是 `fetch-lyrics`; - 沿用之**事實**記於 `data/lyrics_provenance.csv`(進 git): + 沿用之**事實**記於 `data/captures/lyrics_provenance.csv`(進 git): `source`(原始 API)與 `method` (pilot-import / api-fetch / manual)兩層,取得日期不可考者 不假造,僅記可證上界。 @@ -103,7 +103,7 @@ ## 其他已定案事項 -- 歌詞受版權保護:完整歌詞不進 git(`data/lyrics/` gitignored), +- 歌詞受版權保護:完整歌詞不進 git(`data/captures/lyrics/` gitignored), 論文與 repo 只留分類所引摘錄。 - Fable 5 不用於 pipeline:成本高、thinking 無法關閉且不可稽核、 無 temperature 控制,且會混淆「盲點是提示問題」的核心主張。