feat: 实现协议双向映射，支持 Live 模式调用 OpenAI API

核心改动：
- 新增 src/utils/import.ts：OpenAI 响应 → Protocol Message 反向映射 + StreamingImporter 流式增量累加器
- 新增 src/services/api.ts：薄封装层，exportToOpenAIFormat → fetch → importFromOpenAIResponse
- 新增 src/services/api-config.ts：API 配置 localStorage 持久化
- 新增 src/components/ApiSettings.tsx：API 设置模态框
- 改造 ChatContext：新增 isLive / sendMessage / 流式状态管理
- 改造 ChatView/ChatInput：Live 模式下启用输入，支持回车发送和 loading 动画
- 改造 App.tsx：Demo/Live 模式切换 + 设置入口
- 新增 19 个 import.test.ts 测试用例，全部 48 测试通过

src/App.tsx

@@ -1,7 +1,10 @@
+import { useState } from 'react'
 import { ChatProvider, useChat } from './context/ChatContext'
 import ChatView from './components/ChatView'
 import ProtocolPanel from './components/ProtocolPanel'
-import { Layers } from 'lucide-react'
+import ApiSettings from './components/ApiSettings'
+import { Layers, Settings, FlaskConical, Zap } from 'lucide-react'
+import { hasApiKey } from './services/api-config'
 
 function DemoSelector() {
   const { demos, activeDemo, setActiveDemo } = useChat()
@@ -26,7 +29,16 @@ function DemoSelector() {
 }
 
 function AppContent() {
-  const { envelope, demos, activeDemo } = useChat()
+  const { envelope, demos, activeDemo, isLive, setIsLive } = useChat()
+  const [settingsOpen, setSettingsOpen] = useState(false)
+
+  const handleToggleLive = () => {
+    if (!isLive && !hasApiKey()) {
+      // 首次切换到 Live 模式，自动弹出设置
+      setSettingsOpen(true)
+    }
+    setIsLive(!isLive)
+  }
 
   return (
     <div className="h-screen flex flex-col">
@@ -37,12 +49,61 @@ function AppContent() {
           <h1 className="text-sm font-bold text-gray-800">
             Prompt Envelope Protocol
           </h1>
-          <span className="text-[10px] text-gray-400 bg-gray-100 px-1.5 py-0.5 rounded">
+          {isLive ? (
-            MVP
+            <span className="text-[10px] text-green-600 bg-green-50 px-1.5 py-0.5 rounded flex items-center gap-1">
-          </span>
+              <Zap size={10} /> Live
+            </span>
+          ) : (
+            <span className="text-[10px] text-gray-400 bg-gray-100 px-1.5 py-0.5 rounded">
+              MVP
+            </span>
+          )}
         </div>
+
         <div className="flex-1" />
+
+        {/* 模式切换 */}
+        <div className="flex items-center gap-1 bg-gray-100 rounded-lg p-0.5">
+          <button
+            onClick={() => !isLive && handleToggleLive()}
+            disabled={isLive}
+            className={`px-3 py-1 rounded-md text-xs font-medium transition-all ${
+              isLive
+                ? 'bg-white text-blue-600 shadow-sm'
+                : 'text-gray-400 cursor-pointer hover:text-gray-600'
+            }`}
+          >
+            Live
+          </button>
+          <button
+            onClick={() => isLive && setIsLive(false)}
+            disabled={!isLive}
+            className={`px-3 py-1 rounded-md text-xs font-medium transition-all ${
+              !isLive
+                ? 'bg-white text-gray-600 shadow-sm'
+                : 'text-gray-400 cursor-pointer hover:text-gray-600'
+            }`}
+          >
+            Demo
+          </button>
+        </div>
+
         <DemoSelector />
+
+        {/* 设置齿轮（仅 Live 模式） */}
+        <button
+          onClick={() => setSettingsOpen(true)}
+          className={`p-1.5 rounded-lg transition-colors ${
+            isLive
+              ? 'text-gray-500 hover:bg-gray-100 hover:text-gray-700'
+              : 'text-gray-300 cursor-default'
+          }`}
+          title="API 设置"
+          disabled={!isLive}
+        >
+          <Settings size={16} />
+        </button>
+
         <span className="text-[10px] text-gray-400 bg-blue-50 px-2 py-1 rounded max-w-xs truncate">
           {demos[activeDemo].description}
         </span>
@@ -53,6 +114,9 @@ function AppContent() {
         <ChatView />
         <ProtocolPanel envelope={envelope} />
       </div>
+
+      {/* API 设置模态框 */}
+      <ApiSettings open={settingsOpen} onClose={() => setSettingsOpen(false)} />
     </div>
   )
 }

src/__tests__/import.test.ts

@@ -0,0 +1,436 @@
+import { describe, it, expect } from 'vitest'
+import {
+  importFromOpenAIResponse,
+  importToolResult,
+  StreamingImporter,
+} from '../utils/import'
+import type { OpenAIMessage } from '../utils/export'
+
+// ============================================================
+// importFromOpenAIResponse
+// ============================================================
+
+describe('importFromOpenAIResponse', () => {
+  it('纯文本响应 → 单 text segment', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: '你好，我是 AI 助手。',
+    }
+
+    const result = importFromOpenAIResponse(msg, 'stop')
+
+    expect(result.role).toBe('assistant')
+    expect(result.segments).toHaveLength(1)
+    expect(result.segments[0]).toEqual({
+      kind: 'text',
+      content: '你好，我是 AI 助手。',
+    })
+    expect(result.id).toMatch(/^msg_\d+_\d+$/)
+    expect(result.timestamp).toBeGreaterThan(0)
+  })
+
+  it('带 tool_calls 的响应 → text + tool_call_request segments', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: '我来帮你搜索一下。',
+      tool_calls: [
+        {
+          id: 'call_001',
+          type: 'function',
+          function: {
+            name: 'search',
+            arguments: '{"query":"HCI 设计","limit":5}',
+          },
+        },
+      ],
+    }
+
+    const result = importFromOpenAIResponse(msg, 'tool_calls')
+
+    expect(result.role).toBe('assistant')
+    expect(result.segments).toHaveLength(2)
+
+    // 第一个 segment: text
+    expect(result.segments[0]).toEqual({
+      kind: 'text',
+      content: '我来帮你搜索一下。',
+    })
+
+    // 第二个 segment: tool_call_request
+    expect(result.segments[1]).toEqual({
+      kind: 'tool_call_request',
+      toolName: 'search',
+      arguments: { query: 'HCI 设计', limit: 5 },
+      collapsed: false,
+    })
+  })
+
+  it('纯 tool_calls（content=null）→ 仅 tool_call_request segments', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: null,
+      tool_calls: [
+        {
+          id: 'call_a',
+          type: 'function',
+          function: {
+            name: 'get_weather',
+            arguments: '{"city":"北京"}',
+          },
+        },
+        {
+          id: 'call_b',
+          type: 'function',
+          function: {
+            name: 'get_time',
+            arguments: '{"timezone":"Asia/Shanghai"}',
+          },
+        },
+      ],
+    }
+
+    const result = importFromOpenAIResponse(msg, 'tool_calls')
+
+    expect(result.role).toBe('assistant')
+    expect(result.segments).toHaveLength(2)
+
+    expect(result.segments[0]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'get_weather',
+      arguments: { city: '北京' },
+    })
+    expect(result.segments[1]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'get_time',
+      arguments: { timezone: 'Asia/Shanghai' },
+    })
+  })
+
+  it('多 tool_calls → 对应多个 tool_call_request segments', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: '并行查询：',
+      tool_calls: [
+        {
+          id: 'c1',
+          type: 'function',
+          function: { name: 'search', arguments: '{"q":"A"}' },
+        },
+        {
+          id: 'c2',
+          type: 'function',
+          function: { name: 'search', arguments: '{"q":"B"}' },
+        },
+        {
+          id: 'c3',
+          type: 'function',
+          function: { name: 'fetch', arguments: '{"url":"x"}' },
+        },
+      ],
+    }
+
+    const result = importFromOpenAIResponse(msg, 'tool_calls')
+
+    expect(result.segments).toHaveLength(4) // 1 text + 3 tool_calls
+    expect(result.segments[0]).toMatchObject({ kind: 'text' })
+    expect(result.segments[1]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'search',
+      arguments: { q: 'A' },
+    })
+    expect(result.segments[2]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'search',
+      arguments: { q: 'B' },
+    })
+    expect(result.segments[3]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'fetch',
+      arguments: { url: 'x' },
+    })
+  })
+
+  it('finish_reason="length" → 追加截断标记', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: '这是一段很长的回复被截断了...',
+    }
+
+    const result = importFromOpenAIResponse(msg, 'length')
+
+    expect(result.segments).toHaveLength(2)
+    expect(result.segments[0]).toEqual({
+      kind: 'text',
+      content: '这是一段很长的回复被截断了...',
+    })
+    expect(result.segments[1]).toEqual({
+      kind: 'text',
+      content: '[因长度限制被截断]',
+    })
+  })
+
+  it('finish_reason="stop" → 无额外处理', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: '正常结束。',
+    }
+
+    const result = importFromOpenAIResponse(msg, 'stop')
+
+    expect(result.segments).toHaveLength(1)
+    expect(result.segments[0]).toEqual({
+      kind: 'text',
+      content: '正常结束。',
+    })
+  })
+
+  it('空 content + 无 tool_calls → 防御占位 segment', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: '',
+    }
+
+    const result = importFromOpenAIResponse(msg, 'stop')
+
+    expect(result.segments).toHaveLength(1)
+    expect(result.segments[0]).toEqual({
+      kind: 'text',
+      content: '[空响应]',
+    })
+  })
+
+  it('非法 JSON arguments → _raw 字段保留原始字符串', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: null,
+      tool_calls: [
+        {
+          id: 'bad',
+          type: 'function',
+          function: { name: 'parse', arguments: 'not-valid-json' },
+        },
+      ],
+    }
+
+    const result = importFromOpenAIResponse(msg, 'tool_calls')
+
+    expect(result.segments).toHaveLength(1)
+    expect(result.segments[0]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'parse',
+      arguments: { _raw: 'not-valid-json' },
+    })
+  })
+
+  it('支持自定义 id 和 timestamp', () => {
+    const msg: OpenAIMessage = {
+      role: 'assistant',
+      content: 'test',
+    }
+
+    const result = importFromOpenAIResponse(msg, 'stop', {
+      id: 'custom-id',
+      timestamp: 1234567890000,
+    })
+
+    expect(result.id).toBe('custom-id')
+    expect(result.timestamp).toBe(1234567890000)
+  })
+})
+
+// ============================================================
+// importToolResult
+// ============================================================
+
+describe('importToolResult', () => {
+  it('成功的 tool 结果 → success=true, collapsed=true', () => {
+    const result = importToolResult('search', '找到 3 条结果', true)
+
+    expect(result.role).toBe('tool')
+    expect(result.segments).toHaveLength(1)
+    expect(result.segments[0]).toEqual({
+      kind: 'tool_call_result',
+      toolName: 'search',
+      result: '找到 3 条结果',
+      success: true,
+      collapsed: true,
+    })
+    expect(result.id).toMatch(/^msg_\d+_\d+$/)
+  })
+
+  it('失败的 tool 结果 → success=false, collapsed=false（默认展开以便查看错误）', () => {
+    const result = importToolResult('fetch', 'Connection refused', false, false)
+
+    expect(result.role).toBe('tool')
+    expect(result.segments).toHaveLength(1)
+    expect(result.segments[0]).toMatchObject({
+      kind: 'tool_call_result',
+      toolName: 'fetch',
+      result: 'Connection refused',
+      success: false,
+      collapsed: false,
+    })
+  })
+})
+
+// ============================================================
+// StreamingImporter
+// ============================================================
+
+describe('StreamingImporter', () => {
+  it('纯文本流式 delta → 逐字拼接', () => {
+    const importer = new StreamingImporter()
+
+    importer.ingestDelta({ role: 'assistant' })
+    importer.ingestDelta({ content: '你好' })
+    importer.ingestDelta({ content: '，世界' })
+    importer.ingestDelta({ content: '！' })
+
+    const msg = importer.toMessage()
+
+    expect(msg.role).toBe('assistant')
+    expect(msg.segments).toHaveLength(1)
+    expect(msg.segments[0]).toEqual({
+      kind: 'text',
+      content: '你好，世界！',
+    })
+  })
+
+  it('toPartialMessage 返回当前部分内容（用于流式渲染）', () => {
+    const importer = new StreamingImporter()
+
+    importer.ingestDelta({ content: 'Hello' })
+    const partial1 = importer.toPartialMessage()
+    expect(partial1.segments[0]).toEqual({ kind: 'text', content: 'Hello' })
+
+    importer.ingestDelta({ content: ' World' })
+    const partial2 = importer.toPartialMessage()
+    expect(partial2.segments[0]).toEqual({ kind: 'text', content: 'Hello World' })
+  })
+
+  it('tool_call 流式 delta → 按 index 累积 arguments', () => {
+    const importer = new StreamingImporter()
+
+    // 模拟真实的 tool_call 流式片段
+    importer.ingestDelta({
+      tool_calls: [
+        { index: 0, id: 'call_001', type: 'function', function: { name: 'search', arguments: '' } },
+      ],
+    })
+    importer.ingestDelta({
+      tool_calls: [{ index: 0, function: { arguments: '{"query"' } }],
+    })
+    importer.ingestDelta({
+      tool_calls: [{ index: 0, function: { arguments: ':"HCI"' } }],
+    })
+
+    // 此时 arguments = '{"query":"HCI"' —— 缺少结尾 }，无法 parse
+    // 部分模式下不应出现 tool_call segment
+    const partial = importer.toPartialMessage()
+    const toolSegments = partial.segments.filter((s) => s.kind === 'tool_call_request')
+    expect(toolSegments).toHaveLength(0)
+
+    // 补充最后一片 —— arguments 完整
+    importer.ingestDelta({
+      tool_calls: [{ index: 0, function: { arguments: '}' } }],
+    })
+
+    // 最终模式下，arguments 完整，应正确解析
+    const final = importer.toMessage()
+    expect(final.segments).toHaveLength(1)
+    expect(final.segments[0]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'search',
+      arguments: { query: 'HCI' },
+    })
+  })
+
+  it('多个 tool_call 并行流式 → 正确分离', () => {
+    const importer = new StreamingImporter()
+
+    // tool 0
+    importer.ingestDelta({
+      tool_calls: [
+        { index: 0, id: 'c0', function: { name: 'search', arguments: '{"q":"A"}' } },
+      ],
+    })
+    // tool 1
+    importer.ingestDelta({
+      tool_calls: [
+        { index: 1, id: 'c1', function: { name: 'fetch', arguments: '{"url":"x"}' } },
+      ],
+    })
+
+    const msg = importer.toMessage()
+
+    expect(msg.segments).toHaveLength(2)
+    expect(msg.segments[0]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'search',
+      arguments: { q: 'A' },
+    })
+    expect(msg.segments[1]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'fetch',
+      arguments: { url: 'x' },
+    })
+  })
+
+  it('混合流式：文本 + tool_call 交替出现', () => {
+    const importer = new StreamingImporter()
+
+    importer.ingestDelta({ content: '让我' })
+    importer.ingestDelta({ content: '查一下。' })
+    importer.ingestDelta({
+      tool_calls: [
+        { index: 0, id: 'c0', function: { name: 'search', arguments: '{"q":"天气"}' } },
+      ],
+    })
+
+    const msg = importer.toMessage()
+
+    expect(msg.segments).toHaveLength(2)
+    expect(msg.segments[0]).toEqual({
+      kind: 'text',
+      content: '让我查一下。',
+    })
+    expect(msg.segments[1]).toMatchObject({
+      kind: 'tool_call_request',
+      toolName: 'search',
+    })
+  })
+
+  it('reset() 清空所有累积状态', () => {
+    const importer = new StreamingImporter()
+
+    importer.ingestDelta({ content: 'Hello' })
+    importer.ingestDelta({
+      tool_calls: [{ index: 0, function: { name: 't1', arguments: '{}' } }],
+    })
+
+    importer.reset()
+
+    expect(importer.content).toBe('')
+    expect(importer.hasPendingToolCalls).toBe(false)
+
+    const msg = importer.toMessage()
+    expect(msg.segments[0]).toEqual({ kind: 'text', content: '[空响应]' })
+  })
+
+  it('空 delta 累积 → toMessage 返回防御占位', () => {
+    const importer = new StreamingImporter()
+
+    const msg = importer.toMessage()
+
+    expect(msg.segments).toHaveLength(1)
+    expect(msg.segments[0]).toEqual({ kind: 'text', content: '[空响应]' })
+  })
+
+  it('toPartialMessage 空内容时返回省略号占位', () => {
+    const importer = new StreamingImporter()
+
+    const partial = importer.toPartialMessage()
+
+    expect(partial.segments[0]).toEqual({ kind: 'text', content: '…' })
+  })
+})

src/components/ApiSettings.tsx

@@ -0,0 +1,137 @@
+import { useState, useEffect } from 'react'
+import { X, Eye, EyeOff } from 'lucide-react'
+import { getApiConfig, setApiConfig, type ApiConfig } from '../services/api-config'
+
+interface ApiSettingsProps {
+  open: boolean
+  onClose: () => void
+}
+
+export default function ApiSettings({ open, onClose }: ApiSettingsProps) {
+  const [config, setConfig] = useState<ApiConfig>(getApiConfig)
+  const [showKey, setShowKey] = useState(false)
+  const [saved, setSaved] = useState(false)
+
+  // 每次打开时从 localStorage 同步最新配置
+  useEffect(() => {
+    if (open) {
+      setConfig(getApiConfig())
+      setSaved(false)
+    }
+  }, [open])
+
+  if (!open) return null
+
+  const handleSave = () => {
+    setApiConfig(config)
+    setSaved(true)
+    setTimeout(() => {
+      onClose()
+    }, 600)
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Escape') onClose()
+  }
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/30"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose()
+      }}
+      onKeyDown={handleKeyDown}
+    >
+      <div className="bg-white rounded-xl shadow-xl w-full max-w-md mx-4 overflow-hidden">
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-4 border-b border-gray-100">
+          <h2 className="text-sm font-semibold text-gray-800">API 设置</h2>
+          <button
+            onClick={onClose}
+            className="p-1 rounded hover:bg-gray-100 text-gray-400 hover:text-gray-600 transition-colors"
+          >
+            <X size={18} />
+          </button>
+        </div>
+
+        {/* Form */}
+        <div className="px-5 py-4 space-y-4">
+          {/* Base URL */}
+          <div>
+            <label className="block text-xs font-medium text-gray-500 mb-1">
+              Base URL
+            </label>
+            <input
+              type="text"
+              value={config.baseUrl}
+              onChange={(e) => setConfig({ ...config, baseUrl: e.target.value })}
+              placeholder="https://api.openai.com/v1"
+              className="w-full rounded-lg border border-gray-200 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-200 focus:border-blue-300"
+            />
+            <p className="text-[10px] text-gray-400 mt-1">
+              OpenAI 兼容的 API 端点地址
+            </p>
+          </div>
+
+          {/* API Key */}
+          <div>
+            <label className="block text-xs font-medium text-gray-500 mb-1">
+              API Key
+            </label>
+            <div className="relative">
+              <input
+                type={showKey ? 'text' : 'password'}
+                value={config.apiKey}
+                onChange={(e) => setConfig({ ...config, apiKey: e.target.value })}
+                placeholder="sk-..."
+                className="w-full rounded-lg border border-gray-200 pl-3 pr-9 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-200 focus:border-blue-300"
+              />
+              <button
+                onClick={() => setShowKey(!showKey)}
+                className="absolute right-2 top-1/2 -translate-y-1/2 p-1 rounded text-gray-400 hover:text-gray-600 transition-colors"
+                title={showKey ? '隐藏' : '显示'}
+              >
+                {showKey ? <EyeOff size={16} /> : <Eye size={16} />}
+              </button>
+            </div>
+            <p className="text-[10px] text-gray-400 mt-1">
+              密钥仅保存在浏览器 localStorage 中
+            </p>
+          </div>
+
+          {/* Model */}
+          <div>
+            <label className="block text-xs font-medium text-gray-500 mb-1">
+              Model
+            </label>
+            <input
+              type="text"
+              value={config.model}
+              onChange={(e) => setConfig({ ...config, model: e.target.value })}
+              placeholder="gpt-4-turbo"
+              className="w-full rounded-lg border border-gray-200 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-200 focus:border-blue-300"
+            />
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-between px-5 py-3 border-t border-gray-100 bg-gray-50">
+          <span className="text-[10px] text-gray-400">
+            配置保存在本地浏览器中
+          </span>
+          <button
+            onClick={handleSave}
+            disabled={!config.apiKey.trim() || !config.baseUrl.trim()}
+            className={`px-4 py-1.5 rounded-lg text-xs font-medium transition-all ${
+              saved
+                ? 'bg-green-500 text-white'
+                : 'bg-blue-500 text-white hover:bg-blue-600 disabled:opacity-40'
+            }`}
+          >
+            {saved ? '已保存 ✓' : '保存'}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

src/components/ChatInput.tsx

@@ -1,28 +1,68 @@
-import { Send } from 'lucide-react'
+import { useRef } from 'react'
+import { Send, Loader2 } from 'lucide-react'
 
 interface ChatInputProps {
   value: string
   onChange: (v: string) => void
   disabled?: boolean
+  loading?: boolean
+  onSend?: () => void
+  placeholder?: string
 }
 
-export default function ChatInput({ value, onChange, disabled }: ChatInputProps) {
+export default function ChatInput({
+  value,
+  onChange,
+  disabled,
+  loading,
+  onSend,
+  placeholder,
+}: ChatInputProps) {
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      if (!disabled && !loading && value.trim() && onSend) {
+        onSend()
+      }
+    }
+  }
+
+  const handleSend = () => {
+    if (!disabled && !loading && value.trim() && onSend) {
+      onSend()
+    }
+  }
+
+  const defaultPlaceholder = disabled
+    ? 'Demo 模式 — 切换到 Live 模式即可发送消息'
+    : '输入消息...'
+
   return (
     <div className="border-t border-gray-200 bg-white px-4 py-3">
       <div className="flex items-center gap-2 max-w-3xl mx-auto">
         <input
+          ref={inputRef}
           type="text"
           value={value}
           onChange={(e) => onChange(e.target.value)}
-          disabled={disabled}
+          onKeyDown={handleKeyDown}
-          placeholder="输入消息（Demo 模式 — 不会调用 LLM）"
+          disabled={disabled || loading}
-          className="flex-1 rounded-lg border border-gray-200 px-4 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-200 focus:border-blue-300 disabled:bg-gray-50 disabled:text-gray-400"
+          placeholder={placeholder ?? defaultPlaceholder}
+          className="flex-1 rounded-lg border border-gray-200 px-4 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-200 focus:border-blue-300 disabled:bg-gray-50 disabled:text-gray-400 transition-colors"
         />
         <button
-          disabled={disabled || !value.trim()}
+          onClick={handleSend}
-          className="shrink-0 rounded-lg bg-blue-500 p-2 text-white hover:bg-blue-600 disabled:opacity-40 transition-opacity"
+          disabled={disabled || loading || !value.trim()}
+          className="shrink-0 rounded-lg bg-blue-500 p-2 text-white hover:bg-blue-600 disabled:opacity-40 transition-all"
+          title="发送 (Enter)"
         >
-          <Send size={18} />
+          {loading ? (
+            <Loader2 size={18} className="animate-spin" />
+          ) : (
+            <Send size={18} />
+          )}
         </button>
       </div>
     </div>

src/components/ChatView.tsx

@@ -2,15 +2,43 @@ import { useState } from 'react'
 import { useChat } from '../context/ChatContext'
 import MessageList from './MessageList'
 import ChatInput from './ChatInput'
+import { AlertCircle, X } from 'lucide-react'
 
 export default function ChatView() {
-  const { envelope } = useChat()
+  const { envelope, isLive, isLoading, sendMessage, error, clearError } = useChat()
   const [input, setInput] = useState('')
 
+  const handleSend = () => {
+    if (!input.trim() || isLoading) return
+    sendMessage(input.trim())
+    setInput('')
+  }
+
   return (
     <div className="flex-1 flex flex-col min-w-0">
+      {/* 错误提示条 */}
+      {error && (
+        <div className="flex items-center gap-2 mx-3 mt-2 px-3 py-2 rounded-lg bg-red-50 border border-red-200 text-red-700 text-xs">
+          <AlertCircle size={14} className="shrink-0" />
+          <span className="flex-1">{error}</span>
+          <button
+            onClick={clearError}
+            className="shrink-0 p-0.5 rounded hover:bg-red-100 transition-colors"
+          >
+            <X size={14} />
+          </button>
+        </div>
+      )}
+
       <MessageList messages={envelope.messages} />
-      <ChatInput value={input} onChange={setInput} disabled />
+
+      <ChatInput
+        value={input}
+        onChange={setInput}
+        disabled={!isLive}
+        loading={isLoading}
+        onSend={handleSend}
+      />
     </div>
   )
 }

src/context/ChatContext.tsx

@@ -1,25 +1,202 @@
-import { createContext, useContext, useState, type ReactNode } from 'react'
+import { createContext, useContext, useState, useCallback, useRef, type ReactNode } from 'react'
-import type { PromptEnvelope } from '../types/protocol'
+import type { PromptEnvelope, Message } from '../types/protocol'
 import { demos } from '../data/demos'
+import { getApiConfig, hasApiKey } from '../services/api-config'
+import { sendChatRequestStream } from '../services/api'
 
 interface ChatContextValue {
+  // 现有（保持不变）
   envelope: PromptEnvelope
   setEnvelope: (e: PromptEnvelope) => void
   demos: typeof demos
   activeDemo: number
   setActiveDemo: (i: number) => void
+
+  // 新增 —— Live 模式
+  isLive: boolean
+  setIsLive: (v: boolean) => void
+  isLoading: boolean
+  sendMessage: (text: string) => Promise<void>
+  error: string | null
+  clearError: () => void
 }
 
 const ChatContext = createContext<ChatContextValue | null>(null)
 
-export function ChatProvider({ children }: { children: ReactNode }) {
+/** 生成唯一消息 ID */
-  const [activeDemo, setActiveDemo] = useState(0) // Default: Scene A
+let msgCounter = 0
-  const [envelope, setEnvelope] = useState<PromptEnvelope>(demos[0].envelope)
+function genMsgId(): string {
+  return `live_${Date.now()}_${++msgCounter}`
+}
 
-  const switchDemo = (i: number) => {
+export function ChatProvider({ children }: { children: ReactNode }) {
-    setActiveDemo(i)
+  const [activeDemo, setActiveDemo] = useState(0)
-    setEnvelope(demos[i].envelope)
+  const [envelope, setEnvelope] = useState<PromptEnvelope>(demos[0].envelope)
-  }
+  const [isLive, setIsLive] = useState(false)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  // 保存 Live 模式下的对话历史消息（用于 track 最新的消息列表）
+  const liveMessagesRef = useRef<Message[]>([])
+
+  const clearError = useCallback(() => setError(null), [])
+
+  /**
+   * 从 demo 的 envelope 中提取系统上下文消息
+   * （role: "system" 的消息，包含 system_prompt / memory / skills / tool_overview / static_var）
+   */
+  const extractSystemContext = useCallback((env: PromptEnvelope): Message[] => {
+    return env.messages.filter((m) => m.role === 'system')
+  }, [])
+
+  /**
+   * 构建 Live 模式的初始 envelope：
+   * 保留当前 demo 的系统上下文，但清空所有 user/assistant/tool 消息。
+   */
+  const buildLiveEnvelope = useCallback(
+    (demoIndex: number): PromptEnvelope => {
+      const systemMsgs = extractSystemContext(demos[demoIndex].envelope)
+      return {
+        version: '1.0' as const,
+        model: demos[demoIndex].envelope.model,
+        messages: [...systemMsgs],
+      }
+    },
+    [extractSystemContext]
+  )
+
+  /**
+   * 切换 Demo 场景。
+   * - Demo 模式：直接加载 Demo JSON（现有行为）
+   * - Live 模式：替换系统上下文，清空对话历史
+   */
+  const switchDemo = useCallback(
+    (i: number) => {
+      setActiveDemo(i)
+      if (isLive) {
+        const newEnv = buildLiveEnvelope(i)
+        liveMessagesRef.current = newEnv.messages
+        setEnvelope(newEnv)
+      } else {
+        setEnvelope(demos[i].envelope)
+      }
+      setError(null)
+    },
+    [isLive, buildLiveEnvelope]
+  )
+
+  /**
+   * 切换 Demo / Live 模式。
+   */
+  const handleSetIsLive = useCallback(
+    (v: boolean) => {
+      if (v === isLive) return
+
+      if (v) {
+        // Demo → Live：保留系统上下文，清空对话
+        const newEnv = buildLiveEnvelope(activeDemo)
+        liveMessagesRef.current = newEnv.messages
+        setEnvelope(newEnv)
+      } else {
+        // Live → Demo：恢复完整的 Demo JSON
+        setEnvelope(demos[activeDemo].envelope)
+        liveMessagesRef.current = []
+      }
+
+      setIsLive(v)
+      setError(null)
+      setIsLoading(false)
+    },
+    [isLive, activeDemo, buildLiveEnvelope]
+  )
+
+  /**
+   * 发送消息（Live 模式）。
+   *
+   * 协议映射流程：
+   *   1. 用户输入 → TextSegment → role:"user" Message
+   *   2. 追加到 envelope → exportToOpenAIFormat → API 请求
+   *   3. API 响应 → StreamingImporter → importFromOpenAIResponse → assistant Message
+   *   4. 追加到 envelope → UI 重新渲染
+   */
+  const sendMessage = useCallback(
+    async (text: string) => {
+      if (!text.trim() || isLoading) return
+
+      // 检查 API 配置
+      if (!hasApiKey()) {
+        setError('请先配置 API Key（点击右上角齿轮图标）')
+        return
+      }
+
+      const config = getApiConfig()
+      clearError()
+
+      // 1. 构造用户消息
+      const userMsg: Message = {
+        id: genMsgId(),
+        role: 'user',
+        segments: [{ kind: 'text', content: text.trim() }],
+        timestamp: Date.now(),
+      }
+
+      // 2. 构建当前 envelope（包含系统上下文 + 历史 + 新用户消息）
+      const currentMessages = [
+        ...liveMessagesRef.current,
+        userMsg,
+      ]
+      const currentEnvelope: PromptEnvelope = {
+        version: '1.0',
+        model: envelope.model,
+        messages: currentMessages,
+      }
+
+      // 立即渲染用户消息
+      liveMessagesRef.current = currentMessages
+      setEnvelope({ ...currentEnvelope })
+      setIsLoading(true)
+
+      // 3. 发送流式请求
+      let lastPartial: Message | null = null
+
+      await sendChatRequestStream(currentEnvelope, config, {
+        onToken(partial: Message) {
+          lastPartial = partial
+          // 流式渲染：将部分 assistant 消息追加到列表末尾
+          const updatedMessages = [...liveMessagesRef.current, partial]
+          setEnvelope({
+            ...currentEnvelope,
+            messages: updatedMessages,
+          })
+        },
+
+        onDone(finalMessages: Message[]) {
+          // 移除可能存在的部分消息，追加最终消息
+          const baseMessages = liveMessagesRef.current.filter(
+            (m) => m.id !== lastPartial?.id
+          )
+          const updatedMessages = [...baseMessages, ...finalMessages]
+          liveMessagesRef.current = updatedMessages
+          setEnvelope({
+            ...currentEnvelope,
+            messages: updatedMessages,
+          })
+          setIsLoading(false)
+        },
+
+        onError(err: Error) {
+          // 移除流式部分消息，保留用户消息
+          setEnvelope({
+            ...currentEnvelope,
+            messages: liveMessagesRef.current,
+          })
+          setError(err.message)
+          setIsLoading(false)
+        },
+      })
+    },
+    [isLoading, envelope.model, clearError]
+  )
 
   return (
     <ChatContext.Provider
@@ -29,6 +206,12 @@ export function ChatProvider({ children }: { children: ReactNode }) {
         demos,
         activeDemo,
         setActiveDemo: switchDemo,
+        isLive,
+        setIsLive: handleSetIsLive,
+        isLoading,
+        sendMessage,
+        error,
+        clearError,
       }}
     >
       {children}

src/services/api-config.ts

@@ -0,0 +1,73 @@
+/**
+ * API 配置管理 —— localStorage 持久化存储。
+ *
+ * 存储的字段：
+ *   - baseUrl: API 端点地址（默认 OpenAI 官方）
+ *   - apiKey:  API 密钥
+ *   - model:   模型名称（默认 envelope.model ?? 'gpt-4-turbo'）
+ */
+
+const STORAGE_KEY = 'hci-api-config'
+
+export interface ApiConfig {
+  baseUrl: string
+  apiKey: string
+  model: string
+}
+
+const DEFAULTS: ApiConfig = {
+  baseUrl: 'https://api.openai.com/v1',
+  apiKey: '',
+  model: 'gpt-4-turbo',
+}
+
+/**
+ * 从 localStorage 读取 API 配置。
+ * 若某项不存在，使用默认值填充。
+ */
+export function getApiConfig(): ApiConfig {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (raw) {
+      const parsed = JSON.parse(raw) as Partial<ApiConfig>
+      return {
+        baseUrl: parsed.baseUrl || DEFAULTS.baseUrl,
+        apiKey: parsed.apiKey || DEFAULTS.apiKey,
+        model: parsed.model || DEFAULTS.model,
+      }
+    }
+  } catch {
+    // localStorage 不可用或数据损坏，回退默认值
+  }
+  return { ...DEFAULTS }
+}
+
+/**
+ * 保存 API 配置到 localStorage。
+ */
+export function setApiConfig(config: ApiConfig): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(config))
+  } catch {
+    console.warn('[api-config] localStorage 写入失败')
+  }
+}
+
+/**
+ * 检查是否已配置 API Key。
+ */
+export function hasApiKey(): boolean {
+  const config = getApiConfig()
+  return config.apiKey.trim().length > 0
+}
+
+/**
+ * 清除已保存的 API 配置。
+ */
+export function clearApiConfig(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY)
+  } catch {
+    // 静默
+  }
+}

src/services/api.ts

@@ -0,0 +1,231 @@
+/**
+ * API 调用服务 —— 薄封装层，负责 HTTP 通信和格式转换。
+ *
+ * 数据流：
+ *   envelope → exportToOpenAIFormat() → POST JSON → API
+ *   API → SSE/JSON response → importFromOpenAIResponse() → Message[]
+ *
+ * 依赖：
+ *   - src/utils/export.ts (Protocol → OpenAI)
+ *   - src/utils/import.ts (OpenAI → Protocol)
+ *   - src/services/api-config.ts (配置)
+ */
+
+import type { PromptEnvelope, Message } from '../types/protocol'
+import type { ApiConfig } from './api-config'
+import { exportToOpenAIFormat, type OpenAIExport, type OpenAIMessage } from '../utils/export'
+import {
+  importFromOpenAIResponse,
+  StreamingImporter,
+  type OpenAIResponse,
+  type OpenAIStreamChunk,
+} from '../utils/import'
+
+// ============================================================
+// 非流式请求
+// ============================================================
+
+/**
+ * 发送非流式 Chat Completion 请求。
+ * @returns 导入后的 Protocol Message 数组（通常只有一条 assistant 消息）
+ */
+export async function sendChatRequest(
+  envelope: PromptEnvelope,
+  config: ApiConfig
+): Promise<Message[]> {
+  const body = buildRequestBody(envelope, config)
+
+  const response = await fetch(`${config.baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${config.apiKey}`,
+    },
+    body: JSON.stringify(body),
+  })
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => '无法读取错误详情')
+    let errorMsg: string
+    try {
+      const errJson = JSON.parse(errorText)
+      errorMsg = errJson.error?.message || errorText
+    } catch {
+      errorMsg = errorText || `HTTP ${response.status}`
+    }
+    throw new Error(`API 请求失败 (${response.status}): ${errorMsg}`)
+  }
+
+  const data: OpenAIResponse = await response.json()
+  const choice = data.choices?.[0]
+  if (!choice) {
+    throw new Error('API 响应中没有有效的 choices')
+  }
+
+  const msg = importFromOpenAIResponse(choice.message, choice.finish_reason, {
+    timestamp: Date.now(),
+  })
+
+  return [msg]
+}
+
+// ============================================================
+// 流式请求
+// ============================================================
+
+export interface StreamCallbacks {
+  /** 每收到 text delta 时回调部分 Message（用于实时打字效果） */
+  onToken?: (partial: Message) => void
+  /** tool_call delta 变化时回调（用于展示即将执行的 tool） */
+  onToolCall?: (partial: Message) => void
+  /** 流式完成时回调最终 Message 数组 */
+  onDone: (final: Message[]) => void
+  /** 发生错误时回调 */
+  onError: (err: Error) => void
+}
+
+/**
+ * 发送流式 Chat Completion 请求（SSE）。
+ *
+ * 使用 StreamingImporter 逐 chunk 累积 delta，
+ * 通过 onToken/onToolCall 回调部分 Message 供 UI 实时渲染。
+ */
+export async function sendChatRequestStream(
+  envelope: PromptEnvelope,
+  config: ApiConfig,
+  callbacks: StreamCallbacks
+): Promise<void> {
+  const body = buildRequestBody(envelope, config)
+  body.stream = true
+  // 流式模式下需要 stream_options 来获取 usage（可选）
+  body.stream_options = { include_usage: true }
+
+  let response: Response
+  try {
+    response = await fetch(`${config.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify(body),
+    })
+  } catch (err) {
+    callbacks.onError(
+      new Error(`网络请求失败: ${err instanceof Error ? err.message : String(err)}`)
+    )
+    return
+  }
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => '无法读取错误详情')
+    let errorMsg: string
+    try {
+      const errJson = JSON.parse(errorText)
+      errorMsg = errJson.error?.message || errorText
+    } catch {
+      errorMsg = errorText || `HTTP ${response.status}`
+    }
+    callbacks.onError(new Error(`API 请求失败 (${response.status}): ${errorMsg}`))
+    return
+  }
+
+  const reader = response.body?.getReader()
+  if (!reader) {
+    callbacks.onError(new Error('响应体不可读（不支持流式）'))
+    return
+  }
+
+  const decoder = new TextDecoder()
+  const importer = new StreamingImporter()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+
+      buffer += decoder.decode(value, { stream: true })
+
+      // 按 SSE 协议解析：event 以 \n\n 为界
+      const lines = buffer.split('\n')
+      // 最后一个可能不完整，保留在 buffer 中
+      buffer = lines.pop() || ''
+
+      for (const line of lines) {
+        const trimmed = line.trim()
+        if (!trimmed || trimmed.startsWith(':')) {
+          // 空行、注释行 —— 跳过
+          continue
+        }
+
+        if (trimmed.startsWith('data: ')) {
+          const dataStr = trimmed.slice(6)
+
+          // 结束标记
+          if (dataStr === '[DONE]') {
+            break
+          }
+
+          try {
+            const chunk: OpenAIStreamChunk = JSON.parse(dataStr)
+            const delta = chunk.choices?.[0]?.delta
+            if (delta) {
+              const prevContent = importer.content
+              const prevToolCount = importer.hasPendingToolCalls
+
+              importer.ingestDelta(delta)
+
+              // 文本有变化 → 回调当前部分消息
+              if (importer.content !== prevContent || importer.hasPendingToolCalls !== prevToolCount) {
+                const partial = importer.toPartialMessage()
+                callbacks.onToken?.(partial)
+              }
+            }
+          } catch {
+            // JSON 解析失败 —— 跳过此 chunk（某些 API 可能返回非标准格式）
+            console.warn('[api] SSE chunk 解析失败:', dataStr.slice(0, 80))
+          }
+        }
+      }
+    }
+
+    // 构建最终消息
+    const finalMsg = importer.toMessage({ timestamp: Date.now() })
+    callbacks.onDone([finalMsg])
+  } catch (err) {
+    // 流式中断时，尝试保留已累积的内容
+    if (importer.content.trim() || importer.hasPendingToolCalls) {
+      const partial = importer.toPartialMessage({ timestamp: Date.now() })
+      // 用部分内容构建最终消息，但追加截断标记
+      const truncated = importer.toMessage({ timestamp: Date.now() })
+      if (truncated.segments.length > 0 && truncated.segments[0].kind === 'text') {
+        callbacks.onDone([truncated])
+      } else {
+        callbacks.onDone([partial])
+      }
+    }
+    callbacks.onError(
+      new Error(`流式连接中断: ${err instanceof Error ? err.message : String(err)}`)
+    )
+  }
+}
+
+// ============================================================
+// 请求构造
+// ============================================================
+
+/**
+ * 构建 OpenAI Chat Completions 请求体。
+ * 从 envelope 导出并注入 model 配置。
+ */
+function buildRequestBody(
+  envelope: PromptEnvelope,
+  config: ApiConfig
+): OpenAIExport & { stream?: boolean; stream_options?: { include_usage: boolean } } {
+  const exported = exportToOpenAIFormat(envelope)
+  return {
+    ...exported,
+    model: config.model || exported.model,
+  }
+}

src/utils/import.ts

@@ -0,0 +1,349 @@
+/**
+ * OpenAI API 响应 → Protocol Message 反向映射。
+ *
+ * 与 export.ts 的 exportToOpenAIFormat() 构成双向转换闭环：
+ *
+ *   Protocol ──export.ts──▶ OpenAI Request ──API──▶ OpenAI Response
+ *                                                      │
+ *   Protocol ◀──import.ts──────────────────────────────┘
+ *
+ * 职责：
+ *   1. importFromOpenAIResponse() — 完整响应 → Protocol Message（非流式）
+ *   2. StreamingImporter — SSE delta 增量累积 → Protocol Message（流式）
+ *   3. importToolResult() — tool 执行结果 → Protocol tool 消息
+ */
+
+import type { Message, Segment } from '../types/protocol'
+import type { OpenAIMessage, OpenAIToolCall } from './export'
+
+// ============================================================
+// OpenAI Response 类型
+// ============================================================
+
+/** API 响应的 choice 对象 */
+export interface OpenAIChoice {
+  index: number
+  message: OpenAIMessage
+  finish_reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | null
+}
+
+/** 完整的 Chat Completion 响应 */
+export interface OpenAIResponse {
+  id: string
+  object: string
+  created: number
+  model: string
+  choices: OpenAIChoice[]
+  usage?: {
+    prompt_tokens: number
+    completion_tokens: number
+    total_tokens: number
+  }
+}
+
+/** SSE 流式 chunk 中的 delta */
+export interface OpenAIDelta {
+  role?: string
+  content?: string
+  tool_calls?: Array<{
+    index: number
+    id?: string
+    type?: 'function'
+    function?: {
+      name?: string
+      arguments?: string
+    }
+  }>
+}
+
+/** SSE 流式 chunk */
+export interface OpenAIStreamChunk {
+  id: string
+  object: string
+  created: number
+  model: string
+  choices: Array<{
+    index: number
+    delta: OpenAIDelta
+    finish_reason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | null
+  }>
+}
+
+// ============================================================
+// ID 生成
+// ============================================================
+
+let idCounter = 0
+
+/** 生成唯一消息 ID */
+function genMessageId(): string {
+  return `msg_${Date.now()}_${++idCounter}`
+}
+
+// ============================================================
+// 核心导入函数
+// ============================================================
+
+/**
+ * 将 OpenAI API 响应消息转换为 Protocol Message。
+ *
+ * 映射规则：
+ *   - content（非空）→ TextSegment
+ *   - tool_calls[]      → ToolCallRequestSegment（每个 tool_call 一条）
+ *   - finish_reason      → 仅在 "length" 时追加截断标记
+ *   - content 和 tool_calls 可共存于同一消息的 segments 中
+ *
+ * @param message   choices[0].message —— API 返回的 assistant 消息
+ * @param finishReason  choices[0].finish_reason
+ * @param options   可选的 id / timestamp 覆盖
+ * @returns         单条 role: "assistant" 的 Protocol Message
+ */
+export function importFromOpenAIResponse(
+  message: OpenAIMessage,
+  finishReason: OpenAIChoice['finish_reason'] = 'stop',
+  options?: { id?: string; timestamp?: number }
+): Message {
+  const segments: Segment[] = []
+
+  // 1. 文本内容 → TextSegment
+  if (message.content && typeof message.content === 'string' && message.content.trim()) {
+    segments.push({
+      kind: 'text',
+      content: message.content,
+    })
+  }
+
+  // 2. tool_calls → ToolCallRequestSegment
+  if (message.tool_calls && message.tool_calls.length > 0) {
+    for (const tc of message.tool_calls) {
+      let args: Record<string, unknown> = {}
+      if (tc.function.arguments) {
+        try {
+          args = JSON.parse(tc.function.arguments)
+        } catch {
+          // arguments 不是合法 JSON（可能被截断），保留原始字符串
+          args = { _raw: tc.function.arguments }
+        }
+      }
+
+      segments.push({
+        kind: 'tool_call_request',
+        toolName: tc.function.name,
+        arguments: args,
+        collapsed: false,
+      })
+    }
+  }
+
+  // 3. finish_reason 处理
+  if (finishReason === 'length') {
+    segments.push({
+      kind: 'text',
+      content: '[因长度限制被截断]',
+    })
+  }
+
+  // 确保至少有一个 segment（API 不应返回空消息，但做防御）
+  if (segments.length === 0) {
+    segments.push({
+      kind: 'text',
+      content: message.content
+        ? String(message.content)
+        : '[空响应]',
+    })
+  }
+
+  return {
+    id: options?.id ?? genMessageId(),
+    role: 'assistant',
+    segments,
+    timestamp: options?.timestamp ?? Date.now(),
+  }
+}
+
+// ============================================================
+// Tool 结果导入
+// ============================================================
+
+/**
+ * 构造 tool 执行结果的 Protocol 消息。
+ *
+ * @param toolName   被调用的 tool 名称
+ * @param result     执行结果文本
+ * @param success    是否执行成功
+ * @param collapsed  是否默认折叠（默认 true）
+ */
+export function importToolResult(
+  toolName: string,
+  result: string,
+  success: boolean,
+  collapsed = true
+): Message {
+  return {
+    id: genMessageId(),
+    role: 'tool',
+    segments: [
+      {
+        kind: 'tool_call_result',
+        toolName,
+        result,
+        success,
+        collapsed,
+      },
+    ],
+    timestamp: Date.now(),
+  }
+}
+
+// ============================================================
+// 流式增量导入器
+// ============================================================
+
+/**
+ * 流式场景的增量累加器。
+ *
+ * 用法：
+ *   const importer = new StreamingImporter()
+ *   for (const chunk of sseChunks) {
+ *     importer.ingestDelta(chunk.choices[0].delta)
+ *     // 渲染部分内容：
+ *     render(importer.toPartialMessage())
+ *   }
+ *   // 完成时构建最终消息：
+ *   const finalMsg = importer.toMessage()
+ */
+export class StreamingImporter {
+  private contentBuf = ''
+  private toolCallBuf: Map<number, { id?: string; name: string; args: string }> = new Map()
+  private role: string = 'assistant'
+
+  /**
+   * 摄入一个 SSE delta 对象。
+   * @param delta choices[0].delta
+   */
+  ingestDelta(delta: OpenAIDelta): void {
+    // 记录 role（通常只在第一个 delta 出现）
+    if (delta.role) {
+      this.role = delta.role
+    }
+
+    // 文本内容：直接拼接
+    if (delta.content) {
+      this.contentBuf += delta.content
+    }
+
+    // tool_calls：按 index 分组累积
+    if (delta.tool_calls) {
+      for (const tc of delta.tool_calls) {
+        const existing = this.toolCallBuf.get(tc.index) || { name: '', args: '' }
+        if (tc.id) {
+          existing.id = tc.id
+        }
+        if (tc.function?.name) {
+          existing.name = tc.function.name
+        }
+        if (tc.function?.arguments) {
+          existing.args += tc.function.arguments
+        }
+        this.toolCallBuf.set(tc.index, { ...existing })
+      }
+    }
+  }
+
+  /**
+   * 重置所有累积状态，准备下一轮对话。
+   */
+  reset(): void {
+    this.contentBuf = ''
+    this.toolCallBuf.clear()
+    this.role = 'assistant'
+  }
+
+  /**
+   * 构建当前的完整 Protocol Message。
+   * 在流式结束时调用，得到最终的不可变消息。
+   */
+  toMessage(options?: { id?: string; timestamp?: number }): Message {
+    return this.buildMessage(false, options)
+  }
+
+  /**
+   * 构建当前部分内容的 Protocol Message（用于流式渲染的中间状态）。
+   * content 为当前已累积的文本，tool_calls 仅包含已完整接收的。
+   */
+  toPartialMessage(options?: { id?: string; timestamp?: number }): Message {
+    return this.buildMessage(true, options)
+  }
+
+  /** 当前已累积的纯文本内容 */
+  get content(): string {
+    return this.contentBuf
+  }
+
+  /** 是否有未完成的 tool_call 在累积中 */
+  get hasPendingToolCalls(): boolean {
+    return this.toolCallBuf.size > 0
+  }
+
+  // ── 私有 ──
+
+  private buildMessage(partial: boolean, options?: { id?: string; timestamp?: number }): Message {
+    const segments: Segment[] = []
+
+    // 文本内容（即使是部分模式也输出，用于实时打字效果）
+    if (this.contentBuf.trim()) {
+      segments.push({
+        kind: 'text',
+        content: this.contentBuf,
+      })
+    }
+
+    // tool_calls —— 部分模式下，只有 arguments 是合法 JSON 的才展示
+    const sortedIndices = [...this.toolCallBuf.keys()].sort()
+    for (const idx of sortedIndices) {
+      const tc = this.toolCallBuf.get(idx)!
+      if (!tc.name) continue // 还没收到 name，跳过
+
+      let args: Record<string, unknown> = {}
+      let argsValid = false
+      if (tc.args) {
+        try {
+          args = JSON.parse(tc.args)
+          argsValid = true
+        } catch {
+          // 流式传输中 arguments 可能不完整——部分模式跳过，最终模式保留原始字符串
+          if (!partial) {
+            args = { _raw: tc.args }
+          }
+        }
+      }
+
+      // 部分模式：只展示已完整解析的 tool_call
+      if (partial && (!argsValid || !tc.args)) {
+        continue
+      }
+
+      segments.push({
+        kind: 'tool_call_request',
+        toolName: tc.name,
+        arguments: args,
+        collapsed: false,
+      })
+    }
+
+    // 防御：无内容时返回占位
+    if (segments.length === 0) {
+      segments.push({
+        kind: 'text',
+        content: partial ? '…' : '[空响应]',
+      })
+    }
+
+    return {
+      id: options?.id ?? genMessageId(),
+      role: this.role as Message['role'],
+      segments,
+      timestamp: options?.timestamp ?? Date.now(),
+    }
+  }
+}