zclaw_openfang/docs/features/01-core-features/00-chat-interface.md

聊天界面 (Chat Interface)

分类: 核心功能 优先级: P0 - 决定性 成熟度: L4 - 生产 最后更新: 2026-03-25 验证状态: ✅ 代码已验证

---

一、功能概述

1.1 基本信息

聊天界面是用户与 Agent 交互的主要入口，支持流式响应、Markdown 渲染、模型选择等核心功能。

属性	值
分类	核心功能
优先级	P0
成熟度	L4
依赖	chatStore, GatewayClient, TauriGateway
LLM Provider 支持	8
流式响应	✅ 已实现
Markdown 渲染	✅ 已实现
多模型切换	✅ 已实现

1.2 支持的 LLM Provider

Provider	模型示例	状态
Kimi	kimi-k2.5	✅ 可用
Qwen (通义千问)	qwen3.5-plus	✅ 可用
DeepSeek	deepseek-chat	✅ 可用
Zhipu (智谱)	glm-5	✅ 可用
OpenAI	gpt-4o	✅ 可用
Anthropic	claude-3-5-sonnet	✅ 可用
Gemini	gemini-2.0-flash	✅ 可用
Local/Ollama	llama3	✅ 可用

1.3 相关文件

文件	路径	用途
主组件	desktop/src/components/ChatArea.tsx	聊天 UI
状态管理	desktop/src/store/chatStore.ts	消息和会话状态
消息渲染	desktop/src/components/MessageItem.tsx	单条消息
Markdown	desktop/src/components/MarkdownRenderer.tsx	轻量 Markdown 渲染
Tauri 网关	desktop/src/lib/tauri-gateway.ts	Tauri 原生命令
内核客户端	desktop/src/lib/kernel-client.ts	Kernel 通信

---

二、设计初衷

2.1 问题背景

用户痛点:

1. 需要等待完整响应，无法实时看到进度
2. 代码块没有语法高亮
3. 长对话难以管理

系统缺失能力:

• 缺乏流式响应展示
• 缺乏消息的富文本渲染
• 缺乏多会话管理

为什么需要: 作为 AI Agent 的主要交互界面，聊天功能必须是核心体验的入口。

2.2 设计目标

1. 流式体验: 实时展示 AI 响应进度
2. 富文本渲染: Markdown + 代码高亮
3. 多会话管理: 创建、切换、删除会话
4. 模型选择: 用户可选择不同 LLM

2.3 竞品参考

项目	参考点
ChatGPT	流式响应、Markdown 渲染
Claude	代码块复制、消息操作
ZCLAW	历史消息管理

2.4 设计约束

• 性能约束: 流式更新不能阻塞 UI
• 存储约束: 消息历史需要持久化
• 兼容性约束: 支持多种 LLM 提供商

---

三、技术设计

3.1 核心接口

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'tool' | 'hand' | 'workflow';
  content: string;
  timestamp: number;
  agentId?: string;
  model?: string;
  metadata?: Record<string, any>;
}

interface Conversation {
  id: string;
  title: string;
  messages: Message[];
  createdAt: number;
  updatedAt: number;
  agentId?: string;
}

interface ChatState {
  messages: Message[];
  conversations: Conversation[];
  currentConversationId: string | null;
  isStreaming: boolean;
  currentModel: string;
}

3.2 数据流

用户输入
    │
    ▼
ChatArea (React)
    │
    ▼
chatStore.sendMessage()
    │
    ├──► 记忆增强 (getRelevantMemories)
    │
    ├──► 上下文压缩检查 (threshold: 15000)
    │
    ▼
GatewayClient.chatStream()
    │
    ├──► WebSocket 连接
    │       │
    │       └──► 流式事件 (assistant, tool, hand, workflow)
    │
    ▼
消息更新 (isStreaming: true → false)
    │
    ├──► 记忆提取 (extractMemories)
    │
    └──► 反思触发 (recordConversation)

3.3 状态管理

// chatStore 核心状态 (desktop/src/store/chatStore.ts)
interface ChatState {
  messages: Message[];              // 当前会话消息
  conversations: Conversation[];    // 所有会话
  currentConversationId: string | null;
  isStreaming: boolean;
  currentModel: string;             // 默认 'glm-5'
  agents: Agent[];                  // 可用 Agent 列表
  currentAgent: Agent | null;       // 当前选中的 Agent
  abortController: AbortController | null; // 流式中断控制
}

// 核心方法
{
  sendMessage: (content: string, options?) => Promise<void>,
  stopStreaming: () => void,
  switchModel: (modelId: string) => void,
  switchAgent: (agentId: string) => void,
  createConversation: () => string,
  deleteConversation: (id: string) => void,
}

3.4 流式处理

// WebSocket 事件处理
case 'assistant':
  // 追加内容到当前消息
  updateMessage(currentMessageId, { content: delta });
  break;

case 'tool':
  // 添加工具调用记录
  addMessage({ role: 'tool', content: toolResult });
  break;

case 'workflow':
  // 添加工作流状态更新
  addMessage({ role: 'workflow', content: workflowStatus });
  break;

case 'done':
  // 完成流式
  setIsStreaming(false);
  // 触发后处理
  extractMemories();
  recordConversation();
  break;

---

四、预期作用

4.1 用户价值

价值类型	描述
效率提升	流式响应无需等待
体验改善	富文本渲染，代码高亮
能力扩展	多模型选择，多会话管理

4.2 系统价值

价值类型	描述
架构收益	清晰的消息流处理
可维护性	组件职责分离
可扩展性	支持新的消息类型

4.3 成功指标

指标	基线	目标	当前
流式延迟	2s	<500ms	300ms
消息渲染	1s	<200ms	150ms
用户满意度	-	4.5/5	4.3/5

---

五、实际效果

5.1 已实现功能

• 流式响应展示 (WebSocket 实时更新)
• Markdown 渲染（轻量级）
• 代码块渲染
• 多会话管理
• 多模型选择（8 个 LLM Provider）
• 消息自动滚动
• 输入框自动调整高度
• 记忆增强注入 (getRelevantMemories)
• 上下文自动压缩 (threshold: 15000 tokens)
• 流式中断控制 (AbortController)
• Agent 切换
• 工具调用展示 (tool, hand, workflow 消息类型)

5.2 测试覆盖

• 单元测试: 30+ 项
• 集成测试: 包含在 chatStore.test.ts
• 覆盖率: ~85%

5.3 已知问题

问题	严重程度	状态	计划解决
超长消息渲染卡顿	中	待处理	Q2
代码高亮样式单一	低	待处理	Q3

5.4 用户反馈

流式体验流畅，Markdown 渲染满足需求。希望增加更多代码高亮主题。

---

六、演化路线

6.1 短期计划（1-2 周）

• 消息搜索功能
• 消息导出功能

6.2 中期计划（1-2 月）

• 多代码高亮主题
• 消息引用和回复

6.3 长期愿景

• 语音输入/输出
• 多模态消息（图片、文件）

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否需要支持消息编辑？
2. 是否需要支持消息分支（同一提示的不同响应）？

7.2 创意想法

• 消息时间线：可视化对话历史
• 智能摘要：长对话自动生成摘要
• 协作模式：多人同时对话

7.3 风险与挑战

• 技术风险: 大量消息的渲染性能
• 缓解措施: 虚拟化列表，消息分页