令牌成本预测

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`)