權杖成本預測

PRECC 內建權杖成本預測預言機,讓多步驟計畫以權杖而非掛鐘時間編列預算。在每個步驟之前記錄預測,工作完成後記錄實際值,資料集會訓練內建預測器,並隨時間持續改進。

記錄一次預測

傳入計畫步驟的一行描述。PRECC 會對其分類(feat / fix / test / refactor / measurement / doc / chore / unknown),估算權杖數,並印出一個 id,用於稍後閉環。

$ precc predict "Implement read-deltas with mtime check"
id=42 category=feat predicted=5680 tokens (confidence=0.50, model=trained-v1)
Record actual when done: precc predict --record 42 <actual_tokens>

記錄實際值

步驟完成後,從工作階段頁尾或遙測中查到實際權杖數,並透過 id 回填。

$ precc predict --record 42 6300
Recorded actual=6300 tokens for prediction id=42.

訓練 trained-v1

當至少有 10 條已關閉的預測時,在 log10(actual) 對 log10(描述長度) 加上 one-hot 類別虛擬變數上擬合 trained-v1 嶺迴歸。擬合為閉式解(在帶 ridge λ=1 的正規方程上做 Cholesky 分解),執行只需毫秒級。

$ precc predict --train
Trained trained-v1 on 22 closed predictions (λ=1).
  Model file : ~/.local/share/precc/predict_model.json
  Confidence : 0.50
  Intercept  :  +1.0016
  log_desc   :  +1.2339
  Categories :
    unknown       +0.4811
    doc           +0.4474
    measurement   +0.3422
    test          +0.1071
    refactor      +0.0326
    feat          +0.0071
    fix           -0.1096
    chore         -0.3063

訓練後,每次新的 precc predict 呼叫會自動使用 trained-v1,直到你移除或替換模型檔。舊預測保留其原始 model_version,便於你隨時間比較預測器。

檢查預測器精度

precc predict --eval 報告整體和分類別的平均絕對百分比誤差(MAPE),僅在已關閉的預測(同時具有預測值與實際值的列)上計算。

$ precc predict --eval
Predictions logged   : 30
With actuals (closed): 22
Mean predicted       :     1483 tokens
Mean actual          :    47238 tokens
MAPE (statistical)   :     76.4%

By category:
  category        n   predicted      actual    MAPE
  feat            6        4605        5250   26.2%
  unknown         4        1597       30526   52.6%
  test            4         924       38900   56.4%
  ...

列出最近的預測

precc predict --list 以倒序時間顯示最近的列。開放列(無實際值)等待關閉。

$ precc predict --list --limit 5
id    ts                   category       predicted     actual  conf description
30    2026-05-09 09:40:51  feat                5348          -  0.50 Run the synthetic-fleet pilot...
29    2026-05-09 08:56:48  test                1050          -  0.60 Train predictor: trained-v1...
28    2026-05-09 07:44:18  test                 915     150000  0.60 Implement minimal task-12...

為何用權杖而非掛鐘時間

時間估算事後無法測量,且無法跨機器或跨工作階段組合。權杖計數是確定性、可比較的,並且每個關閉的迴路都會擴充帶標籤的資料集,從而持續改進預測器。預言機的核心意義就是把估算從猜謎遊戲變成測量。

資料存放在哪裡

所有預測資料都儲存在你本地機器上,不會上傳任何內容。

~/.local/share/precc/
├── metrics.db                — predictions table (oracle DB)
└── predict_model.json        — trained-v1 coefficients (after `--train`)