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

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

---

16.1 存储结构

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

meta.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 结构

[
  { "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 目录结构的关系

 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 管理自己的对话历史。