mcpField
C
Convex Agents Messages

Convex Agents Messages

github.com/sstobo开发24197 次安装40 周前更新
代码仓库

关于 Convex Agents Messages

面向使用 Convex Agents 处理消息的开发者，涵盖线程历史的保存与检索、消息展示和更新管理。

主要功能

  1. 01分页检索线程消息
  2. 02在 React 中展示消息
  3. 03手动保存消息
  4. 04应用乐观 UI 更新
  5. 05删除单条或指定范围的消息

适用场景

  1. 01向用户展示对话历史
  2. 02生成回复前保存用户消息
  3. 03保存期间即时显示消息
  4. 04从可见历史中筛除工具消息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sstobo/convex-skills --skill convex-agents-messages

安装后在 Claude Code 中输入/convex-agents-messages确认已加载。

详细介绍

用途

消息表示会话线程中的单次交流。本技能涵盖消息的保存、检索、显示和管理。

何时使用本技能

  • 向用户显示对话历史
  • 在生成响应前保存用户消息
  • 在 UI 中实现乐观消息更新
  • 使用 UIMessage 进行富文本格式化
  • 从显示的历史中过滤工具消息

检索消息

import { listUIMessages } from "@convex-dev/agent";

export const listThreadMessages = query({
  args: { threadId: v.string(), paginationOpts: paginationOptsValidator },
  handler: async (ctx, { threadId, paginationOpts }) => {
    return await listUIMessages(ctx, components.agent, {
      threadId,
      paginationOpts,
    });
  },
});

在 React 中显示

import { useUIMessages } from "@convex-dev/agent/react";

function ChatComponent({ threadId }: { threadId: string }) {
  const { results } = useUIMessages(
    api.messages.listThreadMessages,
    { threadId },
    { initialNumItems: 20 }
  );

  return (
    <div>
      {results?.map((message) => (
        <div key={message.key}>{message.text}</div>
      ))}
    </div>
  );
}

手动保存消息

import { saveMessage } from "@convex-dev/agent";

export const saveUserMessage = mutation({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { messageId } = await saveMessage(ctx, components.agent, {
      threadId,
      prompt,
      skipEmbeddings: true,
    });
    return { messageId };
  },
});

乐观更新

在消息保存前立即显示：

const sendMessage = useMutation(api.chat.generateResponse).withOptimisticUpdate(
  optimisticallySendMessage(api.messages.listThreadMessages)
);

删除消息

await myAgent.deleteMessage(ctx, { messageId });
await myAgent.deleteMessages(ctx, { messageIds });
await myAgent.deleteMessageRange(ctx, { threadId, startOrder, endOrder });

UIMessage 类型

带有 Agent 特定字段的扩展消息：

interface UIMessage {
  key: string;
  role: "user" | "assistant" | "system";
  text: string;
  status: "saved" | "streaming" | "finished" | "aborted";
  agentName?: string;
  _creationTime?: Date;
  parts?: MessagePart[];
}

关键原则

  • UIMessage 与 MessageDoc：UI 使用 UIMessage，后端使用 MessageDoc
  • 消息排序：由 order 和 stepOrder 自动维护
  • 乐观更新：在保存前显示消息可提供更好的用户体验
  • 在变更中跳过嵌入：在变更中保存时使用

后续步骤

  • 参见 streaming 了解实时消息更新
  • 参见 files 了解向消息附加媒体
  • 参见 threads 了解管理消息容器

评论

支持 Markdown