mcpField
C
Convex Agents Streaming

Convex Agents Streaming

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

关于 Convex Agents Streaming

Convex Agents Streaming 是一项为 Convex Agent 应用添加异步渐进式文本输出的技能，涵盖流增量的保存、读取及 React 展示。

主要功能

  1. 01异步文本流式输出
  2. 02可配置分块与节流
  3. 03持久化流增量
  4. 04流状态处理
  5. 05使用 useSmoothText 在 React 中展示

适用场景

  1. 01实时更新聊天界面
  2. 02渐进展示较长回复
  3. 03向多个客户端推送同次生成
  4. 04在后台 Action 中流式输出

安装

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

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

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

详细介绍

用途

流式传输让响应能够实时逐字符显示，从而改善用户体验和感知性能。支持异步流式传输和多个客户端。

何时使用此技能

  • 构建具有实时更新的实时聊天界面
  • 生成长响应并从渐进式显示中获益
  • 从单次生成流式传输到多个客户端
  • 在后台操作中使用异步流式传输
  • 实现平滑的文本动画

基本异步流式传输

流式传输增量并将其保存到数据库：

export const streamResponse = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { thread } = await myAgent.continueThread(ctx, { threadId });

    await thread.streamText(
      { prompt },
      { saveStreamDeltas: true }
    );

    return { success: true };
  },
});

配置流分块

await thread.streamText(
  { prompt },
  {
    saveStreamDeltas: {
      chunking: "line", // "word" | "line" | regex | function
      throttleMs: 500, // Save deltas every 500ms
    },
  }
);

检索流增量

import { vStreamArgs, syncStreams } from "@convex-dev/agent";

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

    const streams = await syncStreams(ctx, components.agent, {
      threadId,
      streamArgs,
    });

    return { ...messages, streams };
  },
});

在 React 中显示流式传输

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

function ChatStreaming({ threadId }: { threadId: string }) {
  const { results } = useUIMessages(
    api.streaming.listMessages,
    { threadId },
    { initialNumItems: 20, stream: true }
  );

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

function StreamingMessage({ message }: { message: UIMessage }) {
  const [visibleText] = useSmoothText(message.text, {
    startStreaming: message.status === "streaming",
  });

  return <div>{visibleText}</div>;
}

关键原则

  • 异步流式传输：最适合后台生成
  • 增量节流：在响应性与写入量之间取得平衡
  • 流状态：检查 message.status === "streaming"
  • 平滑动画：使用 useSmoothText 进行文本更新
  • 持久化：增量在页面重新加载后仍然保留

后续步骤

  • 有关消息管理，请参阅 messages
  • 有关 Agent 设置，请参阅 fundamentals
  • 有关支持流式传输的上下文，请参阅 context

评论

支持 Markdown