# Agent 内核设计(PRD §4 落地稿)

> 状态:演进中 · 配合 `docs/PRD.md §4` 阅读。本文记录"一个 agent 怎么想、怎么动"的具体设计,按"分层自底向上"逐层实现并标注完成度。

## 分层与进度

| 层 | 模块 | 状态 |
|---|---|---|
| L0 人设 | `persona/mbti.py`、`persona/persona.py` | ✅ 已实现 + 测试(22 cases) |
| L1 记忆 | 记忆流 + 检索(相关性×新近度×重要度)+ 可插拔存储 | ✅ 已实现 + 测试(34 单测 + 1 mem0 集成);反思留到 L2(需 LLM) |
| L2 一拍循环 | 感知→检索→决策(LLM)→行动→写记忆 + 反思触发 | ✅ 已实现 + 测试;DeepSeek 联调通过 |
| L2.5 工具/具身 | 工具=动作手段;技能→世界effect + 自身状态变化 + 结果回灌 | ✅ 已实现 + 测试(64 单测;DeepSeek demo 通过) |
| World 层 | 时钟 + 地点 + 状态机(目击者广播+级联)+ 从世界生成感知 | ✅ 已实现 + 测试(75 单测;多agent DeepSeek demo 涌现社交) |
| L3 规划 | 晨间日程 + 当前目标分解 | ⬜ |
| 造物主层 | 上帝视角观察 + 事件注入 + 时间加速 + agent工厂配置化入世 | ⬜ 下一步候选 |

### L2 落地说明
- `agent/perception.py`:`Perceived`(感知切片,World 层接入前用桩填)+ `Action`/`ActionType`(开放动作空间)。
- `agent/decision.py`:`traits_from_behavior`(旋钮→自然语言性格)、`build_messages`(拼 prompt)、`parse_action`(鲁棒解析,脏输入降级 WAIT)。纯函数。
- `agent/mind.py`:`AgentMind.tick`(一拍)+ `reflect`(重要度累积过阈值触发,洞察严格基于真实记忆防幻觉)。
- `llm/client.py`:`LLM` 协议 + `LiteLLMClient`(DeepSeek)+ `ScriptedLLM`(测试桩,可断言 prompt)。
- `obs/logging_setup.py`:关键路径结构化日志落盘 `logs/genesis.log`(轮转)。
- 集成测试 `tests/test_agent_llm.py`:真实 DeepSeek 跑通一次 tick,默认不跑,待与用户联调。

## L0:人设 → 行为旋钮(已实现)

MBTI 不逐型硬编码,拆成 4 轴 → [0,1] 行为旋钮,注入决策 prompt 作"性格参数"。

| MBTI 轴 | 旋钮 | 高值含义 |
|---|---|---|
| E/I | `social_initiative` | 主动社交 |
| N/S | `novelty_seeking` | 探索新事物 |
| F/T | `agreeableness` | 顾及他人(低=坚持己见) |
| J/P | `routine_strictness` | 作息/计划规律 |
| 派生 | `assertiveness` | 冲突中坚持己见(**制造摩擦**,对冲 LLM 过度礼貌) |
| 派生 | `risk_tolerance` | 冒险/尝鲜(随性+尝鲜+年轻) |
| 派生 | `night_owl` | 夜猫子(随性+年轻;J 偏早睡) |

派生公式为 v0 启发式,待仿真后校准。

## L2:一拍(tick)循环(已实现)

```
Perceive(Perceived 切片)
  → Retrieve(按 相关性×新近度×重要度 检索 top-k 记忆)
  → Decide(LLM:注入 persona + 行为旋钮 + 自身状态 + 检索记忆 + 感知 + 工具集 → 选工具)
  → Execute(工具在世界执行 → 三路后果,见 L2.5)
  → Write(把 observation 写回记忆流;应用 actor_delta 到自身状态)
触发器:重要记忆累积过阈值触发 Reflection(晨间 Planning 留 L3)
```

**契约**:`AgentMind.tick(perception, now) -> (ToolCall, ToolResult)`,纯文本驱动、不依赖地图渲染,可单测。
动作空间 = agent 挂载的工具集(放权偏好:动作空间不能太小,职业工具可热扩展)。

## 待对齐 TODO(同步到 PRD §12)
- [ ] 行为旋钮派生公式校准
- [ ] 记忆重要度打分 + 检索权重函数
- [ ] 情绪模型选型(离散标签 / PAD / 数值)及其对决策的影响
- [ ] 规划是否引入 Voyager 自动课程
- [ ] 动作/工具的安全黑名单