Initial standalone memabra release

docs/ROUTER_BASELINE.md

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