crimeacs/auto-improve

auto-improve 是做什麼的？

自主、由評審把關的文字工件自我改進工具。完整指南請參閱 README.md；此處為面向代理的快速參考。

使用時機

使用者希望某個文件能可衡量地變得更好，而不只是被改寫——並且願意將「更好」表達為一組評分標準。適用範圍：冷郵件、登陸文案、提示、技能定義、部落格文章、求職信、技術文件、合約、選單等。

執行方式

export GEMINI_API_KEY=...        # https://aistudio.google.com/apikey
python3 improve.py \
  --artifact path/to/file.md \   # 必須位於 git 倉庫內
  --tag v1 \                     # → 分支 improve/v1，結果 results/v1.tsv
  --max-iterations 8 \
  --criteria path/to/rubric.md   # 可選 — 省略則自動推斷評分標準；或加上
                                 # --goal "什麼是好的樣貌" 來引導推斷的標準

若未傳遞 --criteria，auto-improve 會先根據工件寫出評分標準並儲存至 results/<tag>.rubric.md——閱讀它可了解最佳化目標。 檢查已完成執行：python3 improve.py --status --tag v1。 結果位於 improve/<tag> git 分支上——使用 git diff main improve/v1 -- <file> 檢視差異。

決策方式（反垃圾的部分）

1. 變異 — 從 N 個候選編輯中選出最佳者，以手術刀式差異套用（防當機）。
2. 評分 — 每個候選由一個獨立模型呼叫根據評分標準評分。
3. 決定 — 最佳候選與當前冠軍進行成對比較（雙向排序，消除偏差）；僅在確實勝出時保留，否則還原。

變異器永遠不評分自己的作品，自信但更差的改寫會被丟棄——因此品質提升是真實的，每次提交都是驗證過的進展。

撰寫評分標準

一個包含加權維度的 Markdown 檔案，總分為 100——設有基準（50/70/90）、獎勵框架、具體說明。請參閱 criteria/README.md 及 criteria/ 目錄中的範例。

關鍵規則

• 變異器與評估器永不共享上下文。
• 每次執行一個工件、一個評分標準、一個 --tag。
• Git 分支是真相來源；results/<tag>.tsv 是進展記錄（不受版本控制）。
• 絕不編輯工件以外的檔案；使用小型手術刀式差異，而非全面改寫。