# 16. Agent 对话架构 — 两层日志 + 多轮上下文恢复

> 每个 Agent 的对话遵循 `conversationId/messageId` 两层存储架构，
> 支持持久化 + 多轮上下文 + 服务重启后自动恢复。

---

## 16.1 存储结构

```
data/agents/{agentId}/conversations/          ← Agent 实例自带对话目录
└── {conversationId}/                          ← 一个对话
    ├── meta.json                              ← 对话元数据
    ├── history.json                           ← 有序消息列表 (供前端 + 上下文恢复)
    └── {messageId}/                           ← 一轮对话 (user + agent)
        └── messages.log                       ← 时间戳日志
```



### meta.json 结构

```json
{
  "conversationId": "conv-mn3112l3",
  "agentId": "innovator-001",
  "title": "创建 Master Agent",
  "createdAt": "2026-03-23T10:12:11.993Z",
  "updatedAt": "2026-03-23T10:12:50.078Z",
  "status": "completed",     // running | completed | failed | idle
  "stats": {
    "messageCount": 4,
    "toolCallCount": 2
  }
}
```

### history.json 结构

```json
[
  { "role": "user",      "content": "你好", "messageId": "msg-xxx-aaa", "timestamp": "..." },
  { "role": "assistant", "content": "你好，我是 Innovator", "messageId": "msg-xxx-aaa", "timestamp": "..." },
  { "role": "user",      "content": "帮我创建 Master Agent", "messageId": "msg-xxx-bbb", "timestamp": "..." },
  { "role": "assistant", "content": "好的，我来创建...", "messageId": "msg-xxx-bbb", "timestamp": "..." }
]
```

### messages.log 格式 (每轮)

```
[2026-03-23T10:12:11.994Z] [USER]
你好

[2026-03-23T10:12:26.207Z] [AGENT]
你好，我是 Innovator，LemonBoss 的元 Agent。
```

---

## 16.2 多轮对话 — 三场景自动处理

```
                    ┌─────────────────────────────────────┐
                    │          sendMessage()               │
                    │   Agent.js 父类核心接口                │
                    └────────────┬────────────────────────┘
                                 │
                    ┌────────────▼────────────────────────┐
                    │  isNewSession = false?               │
                    │  (同进程 + 同 conversationId)          │
                    └───┬──────────────────────────┬──────┘
                        │ YES                      │ NO
                        ▼                          ▼
               ┌───────────────┐       ┌───────────────────────┐
               │  场景 B:       │       │  history.length === 0? │
               │  直接发 message│       └───┬───────────────┬──-┘
               │  (ACP 自带上下文)       │ YES             │ NO
               └───────────────┘       ▼                  ▼
                              ┌──────────────┐  ┌──────────────────┐
                              │ 场景 A:       │  │ 场景 C:           │
                              │ system prompt │  │ system prompt    │
                              │ + 用户消息     │  │ + 历史摘要 (≤20条) │
                              │               │  │ + 用户消息         │
                              └──────────────┘  └──────────────────┘
```

| 场景 | 触发条件 | Prompt 构成 | 说明 |
|------|---------|-------------|------|
| **A. 全新对话** | 首条消息 + 无历史 | systemPrompt + message | ClaudeCliProtocol 首次 sendPrompt |
| **B. 同进程多轮** | 同 convId + same session | message only | ACP 持久进程天然保持上下文 |
| **C. 恢复对话** | 新 session + 有历史 | systemPrompt + history + message | 服务重启后自动注入历史摘要 |

---

## 16.3 ACP Session 池

```
sessions: Map<key, entry>

key     = "{agentId}:{conversationId}"       ← 每个对话独立会话
entry   = {
  protocol: ClaudeCliProtocol,               ← 持久 CLI 进程
  messageCount: number,                       ← 消息计数 (判断首次 vs 后续)
  agentId: string,
  convId: string,
}
```

- 一个 Agent 可以同时有多个对话（不同 conversationId）
- 每个对话对应一个独立的 ClaudeCliProtocol 实例
- 进程退出 / 超时 → 自动清理 → 下次 sendMessage 时自动创建新会话 + 恢复上下文

---

## 16.4 Agent.js 父类接口

`packages/agent-core/Agent.js` 提供以下对话管理方法:

| 方法 | 说明 |
|------|------|
| `createConversation(title)` | 创建新对话，返回 `{ conversationId }` |
| `listConversations()` | 列出所有对话的 meta 信息 |
| `loadConversationHistory(convId)` | 加载对话的完整消息列表 |
| `appendMessage(convId, msg)` | 追加消息（同步写 messageId 日志 + history.json + meta.json） |
| `sendMessage(convId, message, options)` | 核心接口：自动处理三场景 prompt 构建，emit event 给 ACP 层 |

---

## 16.5 API 端点

```
GET  /api/agent/list                            → 列出所有 Agent
GET  /api/agent/:agentId/info                   → Agent 详情
GET  /api/agent/:agentId/conversations          → 对话列表
GET  /api/agent/:agentId/conversations/:convId  → 对话详情 (meta + messages)
POST /api/agent/:agentId/chat                   → 发送消息 (SSE 流式响应)
     body: { message, conversationId? }
     events: session | thinking | agent_output | tool_call | error | result
DELETE /api/agent/:agentId/conversations/:convId → 删除对话
```

---

## 16.6 与 Agent 目录结构的关系

```diff
 data/agents/{id}/
   ├── agent.md
   ├── soul.md
   ├── identity.md
   ├── user.md
   ├── tools.md
   ├── heartbeat.md
   ├── skills/
   ├── memory/
   ├── knowledge/
   ├── workspace/
+  ├── conversations/         ← 新增: 对话会话目录
+  │   └── {convId}/
+  │       ├── meta.json
+  │       ├── history.json
+  │       └── {msgId}/
+  │           └── messages.log
   ├── logs/
   └── config.json
```

对话是 Agent 的一部分，而不是全局的——每个 Agent 管理自己的对话历史。