memabra/docs/ROUTER_BASELINE.md

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

memory_score = confidence + freshness + success_rate - cost - risk

skill score

skill_score = confidence + success_rate - cost - risk

tool score

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 使用以下优先级：

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 保持了可解释性，同时为后续学习型策略提供了结构化特征输出。