# Reward Specification

## 目标

memabra 的 reward 不是简单判断“任务做成没”，而是评估：
- 是否选对了 memory / skill / tool
- 是否高效
- 是否稳定
- 是否减少了用户重复输入和纠正
- 是否控制了工具成本与上下文成本

reward 的作用不是直接美化分数，而是给路由策略提供可归因、可优化的训练信号。

## Reward 组成

总奖励记为：

```text
R = ws*S + wr*H - we*E - wc*C - wl*L - wx*X + wu*U
```

其中：
- `S` = task success
- `H` = retrieval hit quality
- `E` = execution/tool error penalty
- `C` = user correction penalty
- `L` = latency penalty
- `X` = context cost penalty
- `U` = useful reuse bonus

## 1. Task Success (`S`)

定义：任务最终是否完成，以及完成质量如何。

建议取值：
- `1.0`：完整达成目标
- `0.5`：部分达成
- `0.0`：未完成
- `-0.5`：明显误导或做错方向

数据来源：
- 自动任务验收器
- 用户显式反馈
- 回放对比规则

## 2. Retrieval Hit Quality (`H`)

定义：是否命中对任务真正有帮助的 memory / skill / tool。

建议拆分：
- `Hm`：memory hit
- `Hs`：skill hit
- `Ht`：tool hit

取值思路：
- 命中高价值候选并帮助减少步骤：正奖励
- 召回很多但没用：低奖励或 0
- 漏掉关键候选：负奖励

## 3. Execution / Tool Error Penalty (`E`)

定义：是否出现无效调用、错误调用、明显多余调用。

示例：
- 调了不该调的工具
- 工具参数明显错
- 重复调用同一无效动作
- 本可以直接答，却走了长链路

建议取值：
- 每次轻微错误：`0.1` 到 `0.3`
- 严重错误：`0.5` 到 `1.0`

## 4. User Correction Penalty (`C`)

定义：用户是否需要补充本应已知的信息，或纠正错误动作。

示例：
- 用户重复说明偏好
- 用户指出调用了错误工具
- 用户要求撤回错误记忆

解释：
这项对长期系统非常关键，因为它直接代表“系统到底有没有真正学会”。

## 5. Latency Penalty (`L`)

定义：系统完成任务消耗的时间和步骤是否过长。

建议包括：
- wall-clock latency
- action count
- retry count

思路：
- 少量额外推理可以接受
- 大量无效绕路必须惩罚

## 6. Context Cost Penalty (`X`)

定义：是否过度膨胀上下文。

包括：
- 注入了太多无关 memory
- 加载了不必要的 skill
- 输出了过大的中间内容

原因：
agent 很容易“为了保险多塞一点”，结果把上下文拖死。
这个成本必须显式进 reward。

## 7. Useful Reuse Bonus (`U`)

定义：是否复用了正确的长期信息，并确实提升了效率或质量。

例子：
- 成功复用用户偏好，避免再次确认
- 复用已验证的 skill，减少试错
- 复用相似 episode，加速完成任务

## 初始权重建议

可先用一个朴素版本：

```text
ws = 1.0
wr = 0.35
we = 0.30
wc = 0.40
wl = 0.15
wx = 0.20
wu = 0.25
```

解释：
- success 最高
- user correction 罚得较重，因为它直接暴露系统没学会
- retrieval hit 有明显价值，但不能盖过结果
- latency/context 重要，但初期不该过重

## 信号来源

reward 可来自三类来源：

### A. 显式信号
- 用户说“对/不对”
- 用户纠正
- 用户二次要求重做

### B. 隐式信号
- 是否减少步骤
- 是否触发错误
- 是否重复问同样的问题
- 是否超时

### C. 程序性验收
- 测试是否通过
- 目标文件是否生成
- 指定字段是否匹配
- 工具执行是否成功

## 反事实记录要求

为后续训练，必须记录：
- 候选集有哪些
- 最终选了谁
- 哪些高分候选没有被选
- 每个动作的局部 outcome

否则 reward 只能打给“整个过程”，无法学习具体路由策略。

## 初期策略

Phase 0 / Phase 1 不建议直接把 reward 用于大模型权重更新。
先用于：
- 路由规则评估
- 样本打标
- 候选排序优化
- bandit / reranker 训练

## 风险

- 只看 success，会奖励瞎猫碰死耗子
- 只看效率，会让系统不敢探索
- 只看用户反馈，会受用户表达噪声影响
- 不记录反事实，训练会非常盲

## 当前结论

reward 在 memabra 中不是附属件，而是学习闭环的核心基础设施。
如果 reward 设计不清，后面所有“根据结果更新权重”都会变成伪学习。