# Architecture

## 1. 问题定义

我们要解决的不是“怎样让模型记住更多”，而是：
当 agent 遇到一个任务时，怎样在有限上下文、有限工具预算和有限时间下，快速决定是否要调用 memory、skill、tool，并让这个决策过程能够被训练和修正。

## 2. 系统总览

系统采用四层架构。

### 2.1 Retrieval Layer（候选召回层）
输入：
- 当前用户任务
- 对话短摘要
- 当前环境状态
- 失败历史 / 最近修正

输出：
- top-k memory candidates
- top-k skill candidates
- top-k tool candidates

职责：
- 从不同来源召回候选对象
- 统一为标准候选格式
- 不做最终决策，只做缩小搜索空间

### 2.2 Policy Layer（直觉 / 路由层）
输入：
- 当前任务表示
- 候选对象集合
- 历史选择特征
- 成本与风险信号

输出：
- 直接回答
- 读取某条 memory
- 加载某个 skill
- 调用某个 tool
- 组合动作（如先 skill 后 tool）
- 请求澄清

职责：
- 模拟“直觉”
- 先做快速动作选择
- 后续可从规则逐步升级到分类器、reranker、bandit、RL policy

### 2.3 Execution Layer（执行层）
职责：
- 注入记忆到上下文
- 加载 skill 指令
- 调用真实工具
- 记录执行步骤、耗时、报错、产出

### 2.4 Evaluation Layer（反馈 / 归因层）
职责：
- 判断任务是否成功
- 分析步骤数、重试数、错误率、用户修正次数
- 拆解 reward
- 产生可训练轨迹

没有这一层，就没有真正的“学习”，只有玄学调参。

## 3. 统一对象模型

虽然 memory、skill、tool 性质不同，但在召回和路由阶段可以统一成候选对象：

```json
{
  "id": "string",
  "type": "memory|skill|tool",
  "title": "string",
  "summary": "string",
  "triggers": ["string"],
  "cost": 0.0,
  "confidence": 0.0,
  "success_rate": 0.0,
  "freshness": 0.0,
  "risk": 0.0,
  "embedding": "vector-ref",
  "tags": ["string"],
  "source": "user|system|generated|external"
}
```

注意：统一的是候选接口，不是语义本体。
三类对象必须保持边界：
- memory 存事实
- skill 存程序
- tool 存动作能力

## 4. 记忆系统分层

### 4.1 Semantic Memory（事实记忆）
例如：
- 用户偏好
- 机器环境
- 项目约定
- API 限制

### 4.2 Procedural Memory（程序性记忆）
即 skill：
- 某类任务的处理流程
- 踩坑经验
- 验证步骤

### 4.3 Episodic Memory（情景记忆）
- 某次任务的具体轨迹
- 当时用了什么资源
- 为什么成功或失败

### 4.4 Working Memory（工作记忆）
- 当前任务临时状态
- 本轮推理中间产物
- 不应直接沉淀为长期记忆

## 5. 训练策略：先外部策略，后端到端

### 5.1 Phase A：不改基础模型权重
先训练一个小型策略器，决定：
- 要不要查记忆
- 查哪类记忆
- 要不要 skill
- 先用哪个工具

可选实现：
- 规则 + 分数融合
- 轻量分类器
- reranker
- contextual bandit

### 5.2 Phase B：从轨迹中学 reranking / routing
训练输入：
- 任务上下文
- 候选对象集合
- 实际动作
- 结果 reward

训练目标：
- 最大化任务完成率
- 最小化无效调用
- 减少用户重复提供信息
- 减少不必要的上下文膨胀

### 5.3 Phase C：端到端实验
只有当以下条件成立，才值得考虑：
- 已有高质量轨迹数据
- 能做 credit assignment
- 有稳定的离线评估环境
- 能控制灾难性遗忘

## 6. Feedback & Reward 设计

reward 不能只看任务是否成功。要拆成多项：
- task_success：最终是否完成
- efficiency：用了多少步
- retrieval_hit：是否命中关键 memory/skill/tool
- user_correction_penalty：用户是否纠正
- tool_error_penalty：是否触发无效工具调用
- context_cost_penalty：上下文是否膨胀过度
- latency_penalty：是否过慢

可组合为：

```text
R = a*task_success + b*retrieval_hit - c*tool_error - d*user_correction - e*latency - f*context_cost
```

## 7. 关键难点

### 7.1 Credit Assignment
成功了，到底是谁的功劳？
要记录候选集、最终选择、未选备选项，才能做反事实分析。

### 7.2 False Reinforcement
错误记忆被反复命中，会自我强化。
需要：
- 置信度
- 可撤销
- 最近验证时间
- 来源追踪

### 7.3 Exploitation vs Exploration
老选最稳的对象会变保守，永远学不到新模式。
需要安全探索机制。

### 7.4 Type Boundary Collapse
如果把 memory、skill、tool 混成一个大向量池，系统会越来越糊。

## 8. 推荐 MVP

### MVP-1：可观测系统
- 定义对象 schema
- 定义事件 schema
- 统一记录轨迹
- 做基础检索
- 用规则路由

### MVP-2：轻量学习型路由
- 加入候选打分器
- 从优秀轨迹训练动作选择器
- 做离线回放评估

### MVP-3：在线自适应
- 使用 bandit / preference updates
- 根据任务结果微调路由策略

### MVP-4：端到端试验场
- 小规模实验性训练
- 与分层方案对比
- 验证是否真有收益

## 9. 核心原则

1. 先可观测，再可学习
2. 先学路由，再学大脑
3. 先做分层归因，再做端到端优化
4. 优化“何时依赖什么”，而不是盲目优化“模型看起来更聪明”