@agentunion/kite 1.4.0 → 1.6.0

package/docs/llm-test-enhancement-plan.md

@@ -0,0 +1,970 @@
+# LLM 测试增强功能实现方案（RPC 架构 + 两级缓存）
+
+## 架构原则
+
+**所有功能通过 RPC 调用实现，不使用 HTTP API**
+
+- 前端通过 `kernelClient.call(method, params)` 调用
+- Evol 模块注册 RPC 方法处理请求
+- 工具调用也通过 RPC 路由到对应模块
+
+**两级缓存架构（前端 + 后端）**
+
+- 前端：localStorage 缓存（快速加载）
+- 后端：文件系统缓存（按账户分隔，持久化）
+- 同步：比较 `updated_at` 时间戳，自动合并
+
+---
+
+## 已完成功能 ✅
+
+### 1. 对话缓存（前端 localStorage）
+- 会话数据持久化到 `localStorage.llmTestConfig`
+- 刷新页面后会话列表和消息历史完整恢复
+- 配置项自动缓存
+
+### 2. 基础会话列表（前端）
+- 支持多会话管理（新建、切换）
+- 每个会话独立的消息历史
+- 会话列表显示名称和消息数量
+
+---
+
+## 待实现功能
+
+### 1. 两级缓存架构（前端 + 后端同步）
+
+#### 需求
+- 前端缓存：localStorage（快速加载，离线可用）
+- 后端缓存：文件系统（按手机号分隔，跨设备同步）
+- 同步机制：比较时间戳，自动合并
+
+#### 后端存储结构
+
+```
+data/llm_sessions/
+  {phone}/
+    sessions.json      # 会话元数据列表
+    {session_id}.json  # 单个会话的完整消息
+```
+
+**sessions.json 格式：**
+```json
+[
+  {
+    "id": "1234567890",
+    "name": "新对话",
+    "created_at": "2026-03-13T06:00:00Z",
+    "updated_at": "2026-03-13T06:30:00Z",
+    "message_count": 10
+  }
+]
+```
+
+**{session_id}.json 格式：**
+```json
+{
+  "id": "1234567890",
+  "name": "新对话",
+  "messages": [
+    {"role": "user", "content": "Hello"},
+    {"role": "assistant", "content": "Hi!"}
+  ],
+  "created_at": "2026-03-13T06:00:00Z",
+  "updated_at": "2026-03-13T06:30:00Z"
+}
+```
+
+#### 后端 RPC 方法
+
+**1. `evol.llm_sessions.list` - 列出会话**
+
+```python
+async def _rpc_llm_sessions_list(self, params: dict):
+    """列出用户的所有会话（仅元数据）"""
+    phone = params.get("phone")  # 从 kiteToken 解析
+
+    sessions_file = Path(f"data/llm_sessions/{phone}/sessions.json")
+    if not sessions_file.exists():
+        return {"success": True, "data": []}
+
+    sessions = json.loads(sessions_file.read_text())
+    return {"success": True, "data": sessions}
+```
+
+**2. `evol.llm_sessions.get` - 获取会话详情**
+
+```python
+async def _rpc_llm_sessions_get(self, params: dict):
+    """获取单个会话的完整消息"""
+    phone = params.get("phone")
+    session_id = params.get("session_id")
+
+    session_file = Path(f"data/llm_sessions/{phone}/{session_id}.json")
+    if not session_file.exists():
+        return {"success": False, "error": "Session not found"}
+
+    session = json.loads(session_file.read_text())
+    return {"success": True, "data": session}
+```
+
+**3. `evol.llm_sessions.save` - 保存会话**
+
+```python
+async def _rpc_llm_sessions_save(self, params: dict):
+    """保存会话（创建或更新）"""
+    phone = params.get("phone")
+    session = params.get("session")  # {id, name, messages, created_at, updated_at}
+
+    # 更新时间戳
+    session["updated_at"] = datetime.utcnow().isoformat() + "Z"
+
+    # 保存会话详情
+    session_dir = Path(f"data/llm_sessions/{phone}")
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    session_file = session_dir / f"{session['id']}.json"
+    session_file.write_text(json.dumps(session, ensure_ascii=False, indent=2))
+
+    # 更新会话列表
+    sessions_file = session_dir / "sessions.json"
+    if sessions_file.exists():
+        sessions = json.loads(sessions_file.read_text())
+    else:
+        sessions = []
+
+    # 更新或添加会话元数据
+    meta = {
+        "id": session["id"],
+        "name": session["name"],
+        "created_at": session["created_at"],
+        "updated_at": session["updated_at"],
+        "message_count": len(session["messages"])
+    }
+
+    existing = next((s for s in sessions if s["id"] == session["id"]), None)
+    if existing:
+        sessions[sessions.index(existing)] = meta
+    else:
+        sessions.insert(0, meta)
+
+    sessions_file.write_text(json.dumps(sessions, ensure_ascii=False, indent=2))
+
+    return {"success": True, "data": session}
+```
+
+**4. `evol.llm_sessions.delete` - 删除会话**
+
+```python
+async def _rpc_llm_sessions_delete(self, params: dict):
+    """删除会话"""
+    phone = params.get("phone")
+    session_id = params.get("session_id")
+
+    session_dir = Path(f"data/llm_sessions/{phone}")
+    session_file = session_dir / f"{session_id}.json"
+
+    if session_file.exists():
+        session_file.unlink()
+
+    # 从列表中移除
+    sessions_file = session_dir / "sessions.json"
+    if sessions_file.exists():
+        sessions = json.loads(sessions_file.read_text())
+        sessions = [s for s in sessions if s["id"] != session_id]
+        sessions_file.write_text(json.dumps(sessions, ensure_ascii=False, indent=2))
+
+    return {"success": True}
+```
+
+**5. `evol.llm_sessions.sync` - 同步会话**
+
+```python
+async def _rpc_llm_sessions_sync(self, params: dict):
+    """同步会话（批量上传/下载）"""
+    phone = params.get("phone")
+    local_sessions = params.get("sessions", [])  # 前端的会话列表（仅元数据）
+
+    # 获取服务端会话列表
+    server_sessions_result = await self._rpc_llm_sessions_list({"phone": phone})
+    server_sessions = server_sessions_result["data"]
+
+    # 比较时间戳，确定需要同步的会话
+    to_upload = []  # 前端更新 > 服务端
+    to_download = []  # 服务端更新 > 前端
+
+    server_map = {s["id"]: s for s in server_sessions}
+    local_map = {s["id"]: s for s in local_sessions}
+
+    # 检查前端会话
+    for local in local_sessions:
+        server = server_map.get(local["id"])
+        if not server:
+            to_upload.append(local["id"])  # 服务端没有，需要上传
+        elif local["updated_at"] > server["updated_at"]:
+            to_upload.append(local["id"])  # 前端更新，需要上传
+
+    # 检查服务端会话
+    for server in server_sessions:
+        local = local_map.get(server["id"])
+        if not local:
+            to_download.append(server["id"])  # 前端没有，需要下载
+        elif server["updated_at"] > local["updated_at"]:
+            to_download.append(server["id"])  # 服务端更新，需要下载
+
+    return {
+        "success": True,
+        "data": {
+            "to_upload": to_upload,
+            "to_download": to_download,
+            "server_sessions": server_sessions
+        }
+    }
+```
+
+#### 前端同步逻辑
+
+**初始化时同步：**
+
+```javascript
+// evol-app.js
+
+async _syncLLMSessions() {
+  // 1. 从 localStorage 加载本地会话
+  const cached = this._loadLLMTestCache();
+  llmTestSessions = cached.sessions || [];
+
+  // 2. 获取用户手机号
+  const phone = this.userInfo?.userInfo?.phone;
+  if (!phone) return;
+
+  // 3. 调用同步 RPC
+  try {
+    const result = await this.kernelClient.call('evol.llm_sessions.sync', {
+      phone: phone,
+      sessions: llmTestSessions.map(s => ({
+        id: s.id,
+        name: s.name,
+        created_at: s.createdAt,
+        updated_at: s.updatedAt,
+        message_count: s.messages.length
+      }))
+    });
+
+    if (!result.success) return;
+
+    const { to_upload, to_download, server_sessions } = result.data;
+
+    // 4. 上传需要同步的会话
+    for (const sessionId of to_upload) {
+      const session = llmTestSessions.find(s => s.id === sessionId);
+      if (session) {
+        await this.kernelClient.call('evol.llm_sessions.save', {
+          phone: phone,
+          session: {
+            id: session.id,
+            name: session.name,
+            messages: session.messages,
+            created_at: session.createdAt,
+            updated_at: session.updatedAt
+          }
+        });
+      }
+    }
+
+    // 5. 下载需要同步的会话
+    for (const sessionId of to_download) {
+      const result = await this.kernelClient.call('evol.llm_sessions.get', {
+        phone: phone,
+        session_id: sessionId
+      });
+
+      if (result.success) {
+        const serverSession = result.data;
+        const localSession = llmTestSessions.find(s => s.id === sessionId);
+
+        if (localSession) {
+          // 更新本地会话
+          localSession.name = serverSession.name;
+          localSession.messages = serverSession.messages;
+          localSession.updatedAt = serverSession.updated_at;
+        } else {
+          // 添加新会话
+          llmTestSessions.push({
+            id: serverSession.id,
+            name: serverSession.name,
+            messages: serverSession.messages,
+            createdAt: serverSession.created_at,
+            updatedAt: serverSession.updated_at
+          });
+        }
+      }
+    }
+
+    // 6. 保存到 localStorage
+    this._saveLLMTestCache();
+    this._renderLLMTestSessions();
+
+  } catch (err) {
+    console.error('Failed to sync sessions:', err);
+  }
+}
+
+// 在 initLLMTestPage 中调用
+initLLMTestPage() {
+  // ... 现有代码
+
+  // 异步同步会话
+  this._syncLLMSessions();
+}
+```
+
+**发送消息后自动保存到服务端：**
+
+```javascript
+async function sendLLMTestMessage() {
+  // ... 发送消息逻辑
+
+  // 消息发送成功后，保存到服务端
+  const session = getLLMTestCurrentSession();
+  if (session && window.app) {
+    const phone = window.app.userInfo?.userInfo?.phone;
+    if (phone) {
+      session.updatedAt = new Date().toISOString();
+
+      // 异步保存，不阻塞 UI
+      window.app.kernelClient.call('evol.llm_sessions.save', {
+        phone: phone,
+        session: {
+          id: session.id,
+          name: session.name,
+          messages: session.messages,
+          created_at: session.createdAt,
+          updated_at: session.updatedAt
+        }
+      }).catch(err => console.error('Failed to save session:', err));
+    }
+  }
+}
+```
+
+**新建会话时保存到服务端：**
+
+```javascript
+_createNewSession() {
+  const newSession = {
+    id: Date.now().toString(),
+    name: `对话 ${llmTestSessions.length + 1}`,
+    messages: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  };
+
+  llmTestSessions.unshift(newSession);
+  llmTestCurrentSessionId = newSession.id;
+
+  this._renderLLMTestSessions();
+  this._renderLLMTestMessages();
+  this._saveLLMTestCache();
+
+  // 保存到服务端
+  const phone = this.userInfo?.userInfo?.phone;
+  if (phone) {
+    this.kernelClient.call('evol.llm_sessions.save', {
+      phone: phone,
+      session: {
+        id: newSession.id,
+        name: newSession.name,
+        messages: newSession.messages,
+        created_at: newSession.createdAt,
+        updated_at: newSession.updatedAt
+      }
+    }).catch(err => console.error('Failed to save new session:', err));
+  }
+}
+```
+
+#### 同步时机
+
+1. **页面加载时** - 自动同步（后台异步）
+2. **发送消息后** - 自动保存到服务端
+3. **新建会话时** - 立即保存到服务端
+4. **切换设备时** - 自动下载其他设备的会话
+
+---
+
+### 2. 系统提示词加载
+
+#### 需求
+加载 3 类系统提示词作为对话上下文：
+1. Kite 根目录的 `CLAUDE.md`
+2. 所有已扫描模块的 `module.md`
+3. 注册中心的完整信息（模块列表、RPC 工具、事件定义）
+
+#### 实现方案（RPC）
+
+**后端新增 RPC 方法：`evol.get_system_context`**
+
+```python
+# extensions/services/evol/server.py
+
+async def _rpc_get_system_context(self, params: dict):
+    """获取系统提示词上下文"""
+    context = {
+        "claude_md": "",
+        "module_mds": [],
+        "registry_info": {}
+    }
+
+    # 1. 读取 CLAUDE.md
+    kite_root = Path(os.getenv("KITE_ROOT", "."))
+    claude_md_path = kite_root / "CLAUDE.md"
+    if claude_md_path.exists():
+        context["claude_md"] = claude_md_path.read_text(encoding="utf-8")
+
+    # 2. 收集所有模块的 module.md
+    modules_dir = kite_root / "extensions" / "services"
+    if modules_dir.exists():
+        for module_dir in modules_dir.iterdir():
+            if module_dir.is_dir():
+                module_md = module_dir / "module.md"
+                if module_md.exists():
+                    context["module_mds"].append({
+                        "module": module_dir.name,
+                        "content": module_md.read_text(encoding="utf-8")
+                    })
+
+    # 3. 从注册中心获取信息
+    try:
+        registry_data = await self.kernel_client.call("registry.list_modules", {})
+        context["registry_info"] = registry_data
+    except Exception as e:
+        logger.error(f"Failed to get registry info: {e}")
+        context["registry_info"] = {"error": str(e)}
+
+    return {"success": True, "data": context}
+
+# 在注册时添加到 tools.rpc
+"tools": {
+    "rpc": {
+        "evol": {
+            # ... 现有方法
+            "get_system_context": {
+                "method": "get_system_context",
+                "description": "获取系统提示词上下文"
+            }
+        }
+    }
+}
+```
+
+**前端调用（RPC）：**
+
+```javascript
+// evol-app.js
+
+async _loadSystemContext() {
+  try {
+    const result = await this.kernelClient.call('evol.get_system_context', {});
+    if (result.success) {
+      return result.data;
+    }
+    return null;
+  } catch (err) {
+    console.error('Failed to load system context:', err);
+    return null;
+  }
+}
+
+function buildSystemPrompt(context) {
+  let prompt = '';
+
+  if (context.claude_md) {
+    prompt += `# Kite 项目说明\n\n${context.claude_md}\n\n`;
+  }
+
+  if (context.module_mds.length > 0) {
+    prompt += `# 模块配置\n\n`;
+    context.module_mds.forEach(m => {
+      prompt += `## ${m.module}\n\n${m.content}\n\n`;
+    });
+  }
+
+  if (context.registry_info) {
+    prompt += `# 注册中心信息\n\n${JSON.stringify(context.registry_info, null, 2)}\n`;
+  }
+
+  return prompt;
+}
+```
+
+---
+
+### 4. 统计信息展示
+
+#### 需求
+在模型选择器右侧显示统计信息：
+- 对话消息数量
+- 工具调用次数
+- 各部分上下文占用（字节数、token 估算）
+
+#### 实现方案（纯前端）
+
+**HTML 结构：**
+
+```html
+<div class="llm-test-footer-bar">
+  <select id="llm-test-model" class="llm-test-model-select">...</select>
+
+  <div class="llm-test-stats">
+    <span class="stat-item">消息: <strong id="stat-msg-count">0</strong></span>
+    <span class="stat-item">工具: <strong id="stat-tool-count">0</strong></span>
+    <span class="stat-item" title="上下文占用">
+      <strong id="stat-context-size">0</strong> tokens
+    </span>
+  </div>
+
+  <button id="llm-test-send" class="btn btn-primary">发送</button>
+</div>
+```
+
+**JS 计算逻辑：**
+
+```javascript
+function updateLLMTestStats() {
+  const session = getLLMTestCurrentSession();
+  if (!session) return;
+
+  document.getElementById('stat-msg-count').textContent = session.messages.length;
+
+  const toolCount = session.messages.filter(m => m.tool_calls).length;
+  document.getElementById('stat-tool-count').textContent = toolCount;
+
+  let totalChars = 0;
+  session.messages.forEach(m => {
+    totalChars += (m.content || '').length;
+  });
+
+  if (window.systemContext) {
+    totalChars += (window.systemContext.claude_md || '').length;
+    window.systemContext.module_mds?.forEach(m => {
+      totalChars += (m.content || '').length;
+    });
+  }
+
+  const estimatedTokens = Math.ceil(totalChars / 4);
+  document.getElementById('stat-context-size').textContent = estimatedTokens.toLocaleString();
+}
+```
+
+---
+
+### 5. LLM 对话（RPC 方式）
+
+#### 当前问题
+现在前端通过 HTTP `/api/chat` 调用 LLM，需要改为 RPC 调用。
+
+#### 实现方案（RPC）
+
+**后端新增 RPC 方法：`evol.chat`**
+
+```python
+# extensions/services/evol/server.py
+
+async def _rpc_chat(self, params: dict):
+    """LLM 对话（支持 function calling）"""
+    provider = params.get("provider", "openai")
+    model = params.get("model")
+    messages = params.get("messages", [])
+    temperature = params.get("temperature", 0.7)
+    max_tokens = params.get("max_tokens", 1024)
+    base_url = params.get("base_url")
+    api_key = params.get("api_key")
+    enable_tools = params.get("enable_tools", False)
+
+    # 1. 如果启用工具，从注册中心获取工具定义
+    tools = None
+    if enable_tools:
+        tools = await self._get_available_tools()
+
+    # 2. 调用 LLM
+    try:
+        response = await self._call_llm(
+            provider=provider,
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            base_url=base_url,
+            api_key=api_key,
+            tools=tools
+        )
+
+        # 3. 如果有工具调用，执行 RPC
+        if response.get("tool_calls"):
+            tool_results = await self._execute_tool_calls(response["tool_calls"])
+
+            # 4. 将工具结果返回给 LLM 继续对话
+            messages_with_tools = messages + [
+                {"role": "assistant", "tool_calls": response["tool_calls"]},
+                *[{"role": "tool", "tool_call_id": r["id"], "content": r["result"]}
+                  for r in tool_results]
+            ]
+
+            # 5. 再次调用 LLM
+            final_response = await self._call_llm(
+                provider=provider,
+                model=model,
+                messages=messages_with_tools,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                base_url=base_url,
+                api_key=api_key,
+                tools=tools
+            )
+
+            return {"success": True, "data": final_response}
+
+        return {"success": True, "data": response}
+
+    except Exception as e:
+        logger.error(f"Chat error: {e}")
+        return {"success": False, "error": str(e)}
+
+async def _get_available_tools(self):
+    """从注册中心获取所有可用工具"""
+    try:
+        registry_data = await self.kernel_client.call("registry.list_modules", {})
+        tools = []
+
+        for module_id, module_info in registry_data.get("modules", {}).items():
+            rpc_tools = module_info.get("tools", {}).get("rpc", {})
+            for category, methods in rpc_tools.items():
+                for method_name, method_def in methods.items():
+                    tools.append({
+                        "type": "function",
+                        "function": {
+                            "name": f"{module_id}.{method_name}",
+                            "description": method_def.get("description", ""),
+                            "parameters": method_def.get("parameters", {
+                                "type": "object",
+                                "properties": {}
+                            })
+                        }
+                    })
+
+        return tools
+    except Exception as e:
+        logger.error(f"Failed to get tools: {e}")
+        return []
+
+async def _execute_tool_calls(self, tool_calls):
+    """执行工具调用（通过 RPC）"""
+    results = []
+    for tool_call in tool_calls:
+        function_name = tool_call["function"]["name"]
+        arguments = json.loads(tool_call["function"]["arguments"])
+
+        try:
+            result = await self.kernel_client.call(function_name, arguments)
+            results.append({
+                "id": tool_call["id"],
+                "result": json.dumps(result)
+            })
+        except Exception as e:
+            results.append({
+                "id": tool_call["id"],
+                "result": json.dumps({"error": str(e)})
+            })
+
+    return results
+
+# 在注册时添加
+"tools": {
+    "rpc": {
+        "evol": {
+            "chat": {
+                "method": "chat",
+                "description": "LLM 对话（支持工具调用）"
+            }
+        }
+    }
+}
+```
+
+**前端调用（RPC）：**
+
+```javascript
+// evol-app.js
+
+async function sendLLMTestMessage() {
+  if (llmTestBusy) return;
+
+  const input = document.getElementById('llm-test-input');
+  if (!input) return;
+
+  const text = input.value.trim();
+  if (!text) return;
+
+  const cfg = getLLMTestConfig();
+  const session = getLLMTestCurrentSession();
+  if (!session) return;
+
+  input.value = '';
+  input.style.height = 'auto';
+  appendLLMTestBubble('user', text);
+
+  session.messages.push({ role: 'user', content: text });
+
+  const thinking = appendLLMTestBubble('thinking', '思考中...');
+  llmTestBusy = true;
+
+  const sendBtn = document.getElementById('llm-test-send');
+  if (sendBtn) sendBtn.disabled = true;
+
+  try {
+    // 通过 RPC 调用
+    const result = await window.app.kernelClient.call('evol.chat', {
+      provider: cfg.provider,
+      base_url: cfg.base_url,
+      api_key: cfg.api_key,
+      model: cfg.model,
+      temperature: cfg.temperature,
+      max_tokens: cfg.max_tokens,
+      messages: session.messages,
+      enable_tools: true  // 启用工具调用
+    });
+
+    if (thinking) thinking.parentElement.remove();
+
+    if (result.success) {
+      const content = result.data.content || '(空回复)';
+      session.messages.push({ role: 'assistant', content });
+      appendLLMTestBubble('assistant', content);
+
+      if (window.app) {
+        window.app._saveLLMTestCache();
+        window.app._renderLLMTestSessions();
+      }
+    } else {
+      throw new Error(result.error || '未知错误');
+    }
+  } catch (err) {
+    console.error('LLM test error:', err);
+    if (thinking) thinking.parentElement.remove();
+    appendLLMTestBubble('error', '错误: ' + err.message);
+  } finally {
+    llmTestBusy = false;
+    if (sendBtn) sendBtn.disabled = false;
+    input.focus();
+  }
+}
+```
+
+---
+
+## RPC 方法总览
+
+### Evol 模块需要新增的 RPC 方法
+
+#### 会话管理
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `evol.llm_sessions.list` | `{phone}` | `{success, data: [sessions]}` | 列出用户的所有会话（仅元数据） |
+| `evol.llm_sessions.get` | `{phone, session_id}` | `{success, data: session}` | 获取单个会话的完整消息 |
+| `evol.llm_sessions.save` | `{phone, session}` | `{success, data: session}` | 保存会话（创建或更新） |
+| `evol.llm_sessions.delete` | `{phone, session_id}` | `{success}` | 删除会话 |
+| `evol.llm_sessions.sync` | `{phone, sessions}` | `{success, data: {to_upload, to_download, server_sessions}}` | 同步会话（比较时间戳） |
+
+#### 系统上下文
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `evol.get_system_context` | `{}` | `{success, data: {claude_md, module_mds, registry_info}}` | 获取系统提示词 |
+
+#### LLM 对话
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `evol.chat` | `{provider, model, messages, temperature, max_tokens, base_url, api_key, enable_tools}` | `{success, data: {content, tool_calls}}` | LLM 对话（支持工具调用） |
+| `evol.list_available_tools` | `{}` | `{success, data: [tools]}` | 列出所有可用工具 |
+
+### 前端调用示例
+
+```javascript
+// 1. 同步会话
+const syncResult = await kernelClient.call('evol.llm_sessions.sync', {
+  phone: '13800138000',
+  sessions: [{id: '123', name: '对话1', updated_at: '2026-03-13T06:00:00Z'}]
+});
+
+// 2. 保存会话
+await kernelClient.call('evol.llm_sessions.save', {
+  phone: '13800138000',
+  session: {
+    id: '123',
+    name: '对话1',
+    messages: [{role: 'user', content: 'Hello'}],
+    created_at: '2026-03-13T06:00:00Z',
+    updated_at: '2026-03-13T06:30:00Z'
+  }
+});
+
+// 3. 获取系统提示词
+const context = await kernelClient.call('evol.get_system_context', {});
+
+// 4. LLM 对话
+const response = await kernelClient.call('evol.chat', {
+  provider: 'openai',
+  model: 'gpt-4',
+  base_url: 'https://api.openai.com/v1',
+  api_key: 'sk-...',
+  messages: [{role: 'user', content: 'Hello'}],
+  temperature: 0.7,
+  max_tokens: 1024,
+  enable_tools: true
+});
+```
+
+---
+
+## 工具调用流程（RPC 架构）
+
+```
+用户输入消息
+  ↓
+前端调用 evol.chat (enable_tools=true)
+  ↓
+Evol 模块处理：
+  1. 调用 registry.list_modules 获取工具定义
+  2. 转换为 OpenAI function calling 格式
+  3. 调用 LLM API（带工具定义）
+  ↓
+LLM 返回 tool_calls
+  ↓
+Evol 模块执行工具调用：
+  - 解析 tool_calls
+  - 通过 kernel_client.call() 调用对应 RPC
+  - 收集结果
+  ↓
+将工具结果返回给 LLM
+  ↓
+LLM 生成最终回复
+  ↓
+返回给前端
+```
+
+---
+
+## 工具定义去重策略
+
+### 问题
+系统提示词中包含注册中心信息，而工具调用也需要工具定义，会导致重复。
+
+### 解决方案
+
+1. **系统提示词简化**
+   ```javascript
+   // 只包含模块列表和基本描述
+   const registryInfo = {
+     modules: {
+       kernel: {name: 'Kernel', description: '核心模块'},
+       launcher: {name: 'Launcher', description: '启动器'},
+       // ... 不包含详细的 RPC 方法定义
+     }
+   };
+   ```
+
+2. **工具定义单独传递**
+   - 通过 LLM API 的 `tools` 参数传递
+   - 不混入 system message
+
+3. **按需加载**
+   - 用户可以选择是否启用工具调用
+   - 不启用时不加载工具定义，减少 token 占用
+
+---
+
+## 实现优先级
+
+### P0（已完成）✅
+- 对话缓存（前端 localStorage）
+- 基础会话列表（前端）
+
+### P1（高优先级，需要后端 RPC）
+- **两级缓存架构** - 实现会话管理的 5 个 RPC 方法
+  - `evol.llm_sessions.list`
+  - `evol.llm_sessions.get`
+  - `evol.llm_sessions.save`
+  - `evol.llm_sessions.delete`
+  - `evol.llm_sessions.sync`
+- **前端同步逻辑** - 页面加载时自动同步，发送消息后自动保存
+
+### P2（中优先级，前端实现）
+- 统计信息展示（消息数、工具调用次数、token 占用）
+
+### P3（中优先级，需要后端 RPC）
+- 系统提示词加载（`evol.get_system_context`）
+- LLM 对话改为 RPC（`evol.chat`，不带工具调用）
+
+### P4（低优先级，复杂度高）
+- 工具调用能力（需要完整的 function calling 实现）
+
+---
+
+## 技术难点
+
+### 1. 会话同步冲突处理
+- 同一会话在多设备同时编辑
+- 解决方案：服务端时间戳优先（last-write-wins）
+- 未来可升级为 CRDT 或操作日志
+
+### 2. 大量会话的性能
+- 用户可能有几百个会话
+- 解决方案：分页加载，只同步最近 N 个会话
+- 懒加载会话详情（点击时才下载消息）
+
+### 3. 离线编辑
+- 用户离线时新建会话、发送消息
+- 解决方案：本地队列，联网后批量上传
+- 冲突检测：比较 `updated_at` 时间戳
+
+### 4. 手机号获取
+- 需要从 `userInfo` 中获取手机号
+- 如果用户未登录或未绑定手机号，降级为仅本地缓存
+
+---
+
+## 下一步行动
+
+1. ✅ **已完成**：对话缓存和会话列表（前端 localStorage）
+2. **立即实施**：实现后端会话管理 RPC 方法（5 个方法）
+3. **立即实施**：实现前端同步逻辑（页面加载时同步）
+4. **后续**：统计信息展示（纯前端）
+5. **后续**：系统提示词加载 + LLM 对话改 RPC
+6. **后续**：工具调用能力
+
+---
+
+## 总结
+
+**两级缓存架构的优势：**
+- 快速加载（localStorage 缓存）
+- 跨设备同步（服务端持久化）
+- 离线可用（本地优先）
+- 数据安全（服务端备份）
+
+**实现复杂度：**
+- 中等（需要 5 个 RPC 方法 + 前端同步逻辑）
+- 同步逻辑需要仔细处理时间戳比较
+- 需要考虑冲突和性能问题
+
+**建议实施顺序：**
+1. 先实现后端 RPC 方法（会话管理）
+2. 实现前端同步逻辑（基础版本，简单的时间戳比较）
+3. 测试跨设备同步效果
+4. 优化性能（分页、懒加载）
+5. 实现其他功能（统计、系统提示词、工具调用）
+
+