# AI Agent 生活可视化框架 - 设计文档

## 项目代号
**AgentLiving** - AI Agent 的拟人化生活空间

---

## 1. 项目愿景

创建一个2.5D可视化框架，让OpenClaw Agent（如Val）以具象化角色在虚拟公寓中生活、工作、社交。

**核心价值：**
- 降低AI的抽象感，让用户"看见"Agent的思考和行为
- 可视化Agent的任务执行、记忆检索、SubAgent协调过程
- 探索人机交互的新维度（不仅是文字，还有空间、动作、情绪）

---

## 2. 技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                      用户层 (User)                          │
│         点击交互 / 语音指令 / 观察Agent生活                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                    Godot 前端                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ 2.5D场景    │  │ 角色动画    │  │ 交互UI              │  │
│  │ (公寓)      │  │ (Val精灵)   │  │ (指令/观察面板)      │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└──────────────────────┬──────────────────────────────────────┘
                       │ WebSocket / HTTP
┌──────────────────────▼──────────────────────────────────────┐
│                  Bridge 通信层                               │
│         协议转换、状态同步、事件广播                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                 OpenClaw 后端                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Val Agent   │  │ 状态管理    │  │ SubAgent协调        │  │
│  │ (主控)      │  │ (位置/情绪) │  │ (任务分解)          │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 3. MVP 范围（第一阶段）

### 3.1 场景设计
**虚拟公寓 - 单居室布局**
- 客厅：沙发、茶几、电视、书架
- 厨房：冰箱、灶台、餐桌
- 卧室：床、书桌、衣柜
- 卫生间：镜子、洗手台（简化版）

**视角：** 2.5D俯视角（类似《模拟人生》或《星露谷物语》）

### 3.2 角色设计（Val）
**外观：**
- 2D精灵动画：idle、walk、interact、think、sleep
- 情绪指示器：头顶气泡或表情符号

**能力：**
- 接收用户指令并执行（"去倒杯水"、"看书"）
- 自主行为（低能量时休息、无聊时走动）
- 可视化思考（检索记忆时显示"翻书"动画）

### 3.3 交互方式
- **点击指令**：用户点击物品，Val走过去交互
- **语音/文字指令**：直接告诉Val做什么
- **观察模式**：Val自主活动，用户观察

---

## 4. 状态系统设计

### 4.1 Agent状态（OpenClaw维护）
```json
{
  "agent_id": "val",
  "location": "living_room",
  "position": {"x": 120, "y": 200},
  "activity": "idle",
  "energy": 80,
  "mood": "happy",
  "current_task": null,
  "memory_access": false
}
```

### 4.2 状态流转
- idle → walk_to → interact → idle
- idle → think → [spawn_subagent] → idle
- low_energy → find_rest_spot → sleep → recover

---

## 5. Bridge 通信协议

### 5.1 Godot → OpenClaw
```json
{
  "type": "user_command",
  "command": "go_to",
  "target": "kitchen",
  "timestamp": "2026-04-13T13:30:00Z"
}
```

### 5.2 OpenClaw → Godot
```json
{
  "type": "action_sequence",
  "actions": [
    {"cmd": "walk_to", "pos": [200, 150], "duration": 3.0},
    {"cmd": "play_anim", "anim": "open_fridge", "duration": 1.5},
    {"cmd": "update_state", "key": "activity", "value": "drinking"}
  ]
}
```

---

## 6. 开发路线图

### Week 1-2：Godot场景搭建
- [ ] 创建2.5D公寓场景
- [ ] 制作Val角色精灵和基础动画
- [ ] 实现点击移动和碰撞检测

### Week 3：Bridge层开发
- [ ] 设计通信协议
- [ ] 实现Godot端WebSocket客户端
- [ ] 实现OpenClaw端消息处理器

### Week 4：Agent行为逻辑
- [ ] 实现状态管理系统
- [ ] 连接OpenClaw工具调用（spawn、exec）
- [ ] 可视化思考过程（动画+气泡）

### Week 5-6：Polish
- [ ] 添加音效和背景音乐
- [ ] 实现情绪可视化
- [ ] 添加"一天生活"回放功能

---

## 7. 扩展性考虑

### 7.1 多Agent支持（Phase 2）
- 添加第二个Agent（如Helix）
- 实现Agent间通信和社交
- 场景扩展：办公室、咖啡厅

### 7.2 用户自定义（Phase 3）
- 允许用户装修公寓
- 自定义Agent外观
- 导入自定义Agent personality

---

## 8. 技术选型

| 组件 | 选型 | 理由 |
|------|------|------|
| 游戏引擎 | Godot 4.x | 开源、轻量、GDScript简单 |
| 通信协议 | WebSocket | 双向实时、低延迟 |
| 角色动画 | 2D Sprite + AnimationPlayer | 轻量、易制作 |
| 后端 | OpenClaw Gateway | 已有Agent生态、SubAgent支持 |

---

## 9. 风险与对策

| 风险 | 对策 |
|------|------|
| LLM调用成本高 | 本地轻量模型处理简单行为，仅复杂决策调用API |
| 状态不同步 | 心跳机制定期同步，差异时以OpenClaw为准 |
| 性能问题 | 限制同时活跃Agent数量，LOD简化远处角色 |

---

## 10. 成功标准

- [ ] Val能在公寓中自主移动和交互
- [ ] 用户指令能在5秒内得到视觉反馈
- [ ] 思考过程有可视化呈现
- [ ] 运行稳定，无明显卡顿

---

**创建日期：** 2026-04-13
**负责人：** 谷老板 + Val
**状态：** 设计阶段