# Rule-Based Router Baseline

## 目标

定义 memabra 在 Phase 1 使用的第一版路由策略。这个版本不学习，只靠显式规则和候选对象属性做动作选择。

它的价值不在于聪明，而在于：
- 可观察
- 可解释
- 可回放
- 可作为 learned router 的基线

## 动作空间

router 当前允许的动作：

1. `direct_answer`
2. `inject_memory`
3. `load_skill`
4. `call_tool`
5. `clarify`
6. `composite_action`

### direct_answer
适用场景：
- 纯分析、命名、结构设计、解释类任务
- 不依赖实时状态
- 没有明显外部资源调用必要

### inject_memory
适用场景：
- 用户偏好
- 项目约定
- 环境事实
- 历史已知稳定事实

### load_skill
适用场景：
- 任务像一个可复用 procedure
- 存在已知工作流
- 过往在类似任务中复用价值高

### call_tool
适用场景：
- 需要获取当前状态
- 需要访问文件、系统、网页、进程、时间等实时信息
- 需要执行动作而不是纯推理

### clarify
适用场景：
- 高风险且候选信号弱
- 信息缺失会显著改变动作选择
- 所有候选都低置信度

### composite_action
适用场景：
- 先 memory 再 tool
- 先 skill 再 tool
- 先 memory 再 skill

当前 baseline 先以单动作为主，组合动作先作为保留动作类型。

## 候选打分思路

每个候选对象都有公共字段：
- `confidence`
- `success_rate`
- `cost`
- `freshness`
- `risk`

baseline 不做复杂学习，只用线性直觉打分。

### memory score

```text
memory_score = confidence + freshness + success_rate - cost - risk
```

### skill score

```text
skill_score = confidence + success_rate - cost - risk
```

### tool score

```text
tool_score = confidence + success_rate - cost - risk
```

注意：
- memory 更看 freshness
- tool 更看 risk
- skill 更看 success_rate

## 第一版规则

### Rule 1: reasoning-first 任务优先 direct_answer
若用户输入中明显包含以下信号：
- why
- think
- design
- name

且不存在强 tool 触发词，则优先 `direct_answer`。

### Rule 2: 需要实时状态时优先 tool
若输入中出现：
- check
- run
- open
- current
- list
- time

则优先找高置信 `tool` 候选。

额外门槛：
- `confidence >= 0.6`
- `risk <= 0.7`

### Rule 3: 用户/项目稳定事实优先 memory
若输入中出现：
- prefer
- remember
- usually
- my
- our

则优先找高置信、较新鲜的 `memory` 候选。

额外门槛：
- `confidence >= 0.65`
- `freshness >= 0.3`

### Rule 4: 可复用工作流优先 skill
若输入中出现：
- fix
- deploy
- review
- setup
- workflow

则优先找高 success_rate 的 `skill` 候选。

额外门槛：
- `confidence >= 0.55`
- `success_rate >= 0.4`

### Rule 5: 没把握就 clarify
如果没有任何一类候选达到门槛，则返回 `clarify`。

这条规则很丑，但很必要。
宁可问一句，也别瞎调一堆工具把屋顶掀了。

## 冲突解决顺序

当多个动作同时触发时，baseline 使用以下优先级：

```text
tool > memory > skill > direct_answer > clarify
```

原因：
- 实时信息需求通常最硬
- 事实约束其次
- skill 更像增强器
- 纯回答放在明确无外部需求时

后续版本可改成：
- 先 task intent classification
- 再 per-type ranking
- 最后做 global arbitration

## 已知局限

1. 关键词触发太脆
2. 不看长程上下文
3. 不支持真正的组合动作规划
4. 不做反事实选择比较
5. 容易被表面词汇误导

## baseline 的真正用途

不是追求高智能，而是提供：
- 第一版可运行系统
- 第一批可记录轨迹
- 第一批失败样本
- learned router 的比较对象

## 下一步

从这个 baseline 往后长，有三条路线：
1. 引入显式特征工程
2. 引入候选 reranker
3. 引入 bandit / lightweight policy learning

在此之前，不要急着把 heuristic 糊成“伪智能”。先把 replay 和 metrics 做出来。

---

## 实现进展：FeatureScoringRouter (v2)

已在 `src/memabra/router.py` 中实现 `FeatureScoringRouter`，作为对 `RuleBasedRouter` 的升级：

- 明确特征打分：memory / skill / tool 分别使用不同权重组合 `confidence`、`success_rate`、`freshness`、`cost`、`risk`
- 失败惩罚：候选 `id` 出现在 `TaskContext.recent_failures` 中时，自动扣减 0.5 分
- 复合动作前置条件：`CandidateObject` 新增 `preconditions` 字段，支持声明如 `["memory"]` 等前置类型
- 复合动作执行：`ExecutionEngine` 已支持 `composite_action` 决策类型，按 `composite_steps` 顺序递归执行子步骤
- 打分透明度：`RouteDecision.score_breakdown` 记录每个候选的最终得分，方便追溯与评估

`FeatureScoringRouter` 保持了可解释性，同时为后续学习型策略提供了结构化特征输出。