SuncodeSoftware.SuperSDK.Talk 5.0.0

SuperSDK.Talk

SuperSDK AI 对话 UI 组件库，适用于 Avalonia 桌面应用。提供开箱即用的聊天界面、会话列表、通讯录、资料卡片和数据服务，以及与 SuperSDK MessageBus 的原生集成。

安装

dotnet add package SuncodeSoftware.SuperSDK.Talk

控件概览

所有控件的命名空间：

xmlns:talk="clr-namespace:SuperSDK.Talk.Controls;assembly=SuperSDK.Talk"

快速上手

典型三列布局（仿微信）

<Grid RowDefinitions="*,Auto">

    
    <Grid Grid.Row="0" ColumnDefinitions="240,8,*,8,260" Height="600">

        
        <talk:GzConversationBox Grid.Column="0"
                                BoxPadding="0"
                                BoxCornerRadius="6"
                                BoxBorderThickness="1"/>

        
        <DockPanel Grid.Column="2">
            <talk:GzInputBox DockPanel.Dock="Bottom"
                             SenderId="me"
                             SenderName="我"
                             Placeholder="输入消息…"
                             MinHeight="90"
                             BoxPadding="0"
                             BoxCornerRadius="6"
                             BoxBorderThickness="1"/>
            <talk:GzChatBox BoxPadding="0"
                            BoxCornerRadius="6"
                            BoxBorderThickness="1"/>
        </DockPanel>

        
        <DockPanel Grid.Column="4">
            
            <talk:GzProfileLiteBox DockPanel.Dock="Top"
                                   BoxPadding="0"
                                   BoxCornerRadius="0"
                                   BoxBorderThickness="0"/>
            <talk:GzContactBox BoxPadding="0"
                               BoxCornerRadius="6"
                               BoxBorderThickness="1"/>
        </DockPanel>
    </Grid>

    
    <talk:GzDataBox Grid.Row="1"
                    Height="120"
                    IsVisible="True"
                    BoxPadding="6"
                    BoxCornerRadius="6"
                    BoxBorderThickness="1"/>
</Grid>

登录 / 初始化

所有控件只需发布一条 TalkOwnerChanged 即可完成初始化 — 无需逐个调用控件方法：

using SuperSDK.Core.Messaging;
using SuperSDK.Talk.Messages;

// 登录后广播一次，GzConversationBox / GzContactBox / GzInputBox /
// GzProfileLiteBox / GzDataBox 全部自动响应
MessageBus.Pub(new TalkOwnerChanged
{
    UserId      = "user_42",
    DisplayName = "李四",
});

发送消息

// 文本消息（本人发）
MessageBus.Pub(new ChatMessageReceived
{
    Message = TextChatMessage.Outbound("me", "我", "你好！")
});

// 文本消息（对方发）
MessageBus.Pub(new ChatMessageReceived
{
    Message = TextChatMessage.Inbound("ai", "AI 助手", "你好，有什么可以帮你？")
});

// 图片消息
MessageBus.Pub(new ChatMessageReceived
{
    Message = new ImageChatMessage
    {
        SenderId   = "me",
        SenderName = "我",
        Direction  = ChatDirection.Outbound,
        FilePath   = "/path/to/image.jpg",
        Format     = "jpg",
        Caption    = "附带说明",          // 可选
        Status     = ChatMessageStatus.Sent,
    }
});

// PDF 消息
MessageBus.Pub(new ChatMessageReceived
{
    Message = new PdfChatMessage
    {
        SenderId   = "me",
        SenderName = "我",
        Direction  = ChatDirection.Outbound,
        FilePath   = "/path/to/doc.pdf",
        PageCount  = 5,
        Caption    = "请查阅此报告",       // 可选
        Status     = ChatMessageStatus.Sent,
    }
});

// 系统通知（居中气泡，无头像）
MessageBus.Pub(new ChatMessageReceived
{
    Message = new SystemChatMessage("对话已开始")
});

清空消息

// 方式 A：直接调用控件方法
MyChatBox.Clear();

// 方式 B：通过 MessageBus（无需持有控件引用）
MessageBus.Pub(new ChatClearRequested());

加载通讯录

// 通讯录会在 TalkOwnerChanged 后自动从 DB 加载；
// 也可手动指定要显示的联系人 ID 列表：
MessageBus.Pub(new ContactBookLoadRequested
{
    UserIds = new List<string> { "ai_alice", "ai_bob", "ai_charlie" }
});

手动展示联系人资料

// 弹出完整资料面板（通常由 GzProfileLiteBox 右键自动完成，也可手动触发）
var profileBox = new GzProfileBox { BoxPadding = new Thickness(20) };
profileBox.ShowContact(myAIContact);    // AI 联系人模式
// 或
profileBox.ShowOwn(myUserEntity);       // 我的资料模式

new Window { Content = profileBox, Width = 380, Height = 540 }.Show();

GzChatBox

公开 API

订阅的 MessageBus 消息

GzInputBox

公开 API

订阅的 MessageBus 消息

• 内含附件按钮，支持 jpg / jpeg / png / gif / webp / bmp / pdf
• 选择文件后显示预览徽章，可点 ✕ 取消；若同时填写文字，将作为 Caption 附带发送
• 按 Enter 发送，Shift+Enter 换行
• 不依赖 ChatBox，可独立使用

GzConversationBox

会话列表控件，展示当前登录用户的所有历史对话（仿微信左侧栏）。

公开 API

订阅的 MessageBus 消息

GzContactBox

通讯录控件，展示所有 AI 联系人。右键菜单提供「查看」（弹出 GzProfileBox 窗口）和「删除」。

公开 API

订阅的 MessageBus 消息

发布的 MessageBus 消息

GzProfileLiteBox

用户/联系人资料的轻量卡片，仅展示头像圆圈 + 底部 1/3 叠层（名称 + ID），保持正方形外观。
右键 → 「查看详情」→ 弹出完整 GzProfileBox 窗口。
自动响应 TalkOwnerChanged，无需手动调用 ShowOwn。

公开 API

订阅的 MessageBus 消息

GzProfileBox

用户/联系人信息面板，支持两种模式。通常由 GzProfileLiteBox 的右键菜单弹出，也可独立使用。

• OwnProfile 模式（ShowOwn(UserEntity)）：展示登录用户信息，头像可点击更换，用户名可编辑
• ContactProfile 模式（ShowContact(AIContactEntity)）：展示 AI 联系人只读信息，支持修改别称

公开 API

注：GzProfileBox 不订阅任何 MessageBus 消息。别称同步由 GzProfileLiteBox 负责；直接弹出使用时需手动调用 ShowOwn / ShowContact。

GzDataBox

数据库写入监控护栏，展示消息写入日志。通常直接放于聊天区域底部。

公开 API

订阅的 MessageBus 消息

命名空间统一为 SuperSDK.Talk.Messages，消息文件按用途分两个子目录。

💬 Display — 显示类消息

展示在 ChatBox 聊天列表中的实体消息类型。

公共属性（所有消息类型）：

🔔 ChatSubMessage — AI 任务子消息节点

在消息气泡底部以时间轴形式展示的 AI 步骤节点。

var step = new ChatSubMessage
{
    ParentMessageId = parentMsg.Id,
    Title           = "步骤 1：分析数据",
    Content         = "详细结果（可选，可展开查看）",
    Status          = ChatSubMessageStatus.InProgress,
    NodeType        = ChatSubMessageNodeType.Network,
};
MessageBus.Pub(new ChatSubMessageReceived { SubMessage = step });

⚙️ Actions — 操作类消息

通过 MessageBus 触发控件行为的指令，全部通过消息唯一 ID 定位目标。

基础消息操作

AI 子消息操作

示例：AI 任务完整流程

// 1. 显示 AI 回复消息，开启花瓣动画
var aiMsg = TextChatMessage.Inbound("ai", "AI 助手", "好的，开始处理…");
MessageBus.Pub(new ChatMessageReceived { Message = aiMsg });
MessageBus.Pub(new ChatSubTaskStarted { MessageId = aiMsg.Id });

// 2. 追加进行中子节点
var step = new ChatSubMessage
{
    ParentMessageId = aiMsg.Id,
    Title           = "步骤 1：读取文件",
    Status          = ChatSubMessageStatus.InProgress,
    NodeType        = ChatSubMessageNodeType.Read,
};
MessageBus.Pub(new ChatSubMessageReceived { SubMessage = step });

// 3. 流式向该节点追加内容（可多次调用）
MessageBus.Pub(new ChatSubContentAppended
{
    ParentMessageId = aiMsg.Id,
    SubMessageId    = step.Id,
    ContentChunk    = "读取成功，共 1024 行。",
});

// 4. 将该节点切换为完成状态
MessageBus.Pub(new ChatSubNodeStatusChanged
{
    ParentMessageId = aiMsg.Id,
    SubMessageId    = step.Id,
    NewStatus       = ChatSubMessageStatus.Completed,
});

// 5. 任务结束，关闭父消息花瓣动画
MessageBus.Pub(new ChatSubTaskCompleted { MessageId = aiMsg.Id });

主题

using SuperSDK.UI;
ThemeManager.ToggleTheme(); // 切换明/暗主题，所有控件自动响应

所有颜色均基于 Semi Avalonia 标准动态键（SemiColorBackground0-4、SemiColorText0-3、SemiColorBorder 等），无硬编码颜色。

MessageBus 消息完整清单

命名空间 SuperSDK.Talk.Messages，分 Actions（操作指令）和 Display（展示数据）两类。
所有消息均通过 MessageBus.Pub(msg) 发送、MessageBus.Subscribe<T>(this, handler) 订阅。
控件从视觉树卸载时调用 MessageBus.UnsubscribeAll(this) 一次性取消所有订阅。

📦 Display — 消息内容对象（不直接发布，包装在 ChatMessageReceived 里发布）

⚡ Actions — 操作指令消息（通过 MessageBus 发布以驱动控件行为）

聊天基础操作

AI 子消息操作

通讯录（GzContactBox / GzProfileBox 弹窗）

用户 / 登录 / 会话列表（GzProfileBox / GzConversationBox）

🗃️ 数据库实体（SuperSDK.Data / SQLite，数据库文件 Talk.db）

实体注册（App.axaml.cs 中 SApp.Initialize 内）：

config.RegisterEntity<AIContactEntity>();
config.RegisterEntity<UserEntity>();
config.RegisterEntity<ChatMessageEntity>();
config.RegisterEntity<ChatSubMessageEntity>();

🔌 控件快速对照