Initial standalone memabra release

docs/PROTOTYPE_LAYOUT.md

@@ -0,0 +1,90 @@
+# Prototype Layout
+
+## 目标
+
+为 memabra 建立一个最小可运行的原型目录结构，让后续 rule-based router、replay harness、sample trajectories 和训练样本生成都能有明确落点。
+
+## 目录结构
+
+```text
+src/memabra/
+├── __init__.py
+├── candidate_types.py      # 统一候选对象与决策类型
+├── router.py               # Rule-based router baseline
+├── telemetry.py            # 事件、reward、轨迹的运行时结构
+├── reward.py               # reward 聚合逻辑
+├── retrieval.py            # 后续：候选召回接口
+├── memory_store.py         # 后续：长期记忆存取
+├── replay.py               # 后续：trajectory 回放与评估
+└── schemas.py              # 后续：schema 装载/校验
+
+tests/memabra/
+└── test_router_smoke.py    # baseline 冒烟测试
+```
+
+## 当前已落地
+
+已创建：
+- `src/memabra/__init__.py`
+- `src/memabra/candidate_types.py`
+- `src/memabra/router.py`
+- `src/memabra/telemetry.py`
+- `src/memabra/reward.py`
+- `tests/memabra/test_router_smoke.py`
+
+## 模块边界
+
+### candidate_types.py
+负责：
+- `CandidateObject`
+- `DecisionType`
+- 后续可扩展 memory/skill/tool type-specific adapter
+
+### router.py
+负责：
+- `TaskContext`
+- `RouteDecision`
+- `RuleBasedRouter`
+
+当前只实现 baseline 启发式，后续升级为：
+- 特征打分器
+- reranker
+- learned policy
+
+### telemetry.py
+负责：
+- 原子事件结构
+- reward breakdown
+- 后续 trajectory runtime objects
+
+### reward.py
+负责：
+- reward 组合与计算
+- 后续权重版本化
+
+## 设计原则
+
+1. 先有可运行 baseline，再抽象复杂接口
+2. 数据结构先简单，但字段命名与 Phase 0 schema 保持一致
+3. 先保证 replayable，再考虑高性能
+4. 不提前引入数据库或向量库耦合
+
+## 下一步落点
+
+- `retrieval.py`：定义候选召回接口
+- `replay.py`：实现 trajectory 读取、回放和指标计算
+- `schemas.py`：把 JSON schema 转成运行时校验入口
+- `sample_data/`：放示例 candidates 和 trajectories
+
+## 验证建议
+
+在项目根目录运行：
+
+```bash
+source venv/bin/activate
+python -m pytest tests/memabra/test_router_smoke.py -q
+```
+
+期望：
+- baseline router 冒烟测试通过
+- 说明最小原型骨架已可被导入和调用