mcpField
C
Convex Agents Files

Convex Agents Files

github.com/sstoboAgent 工作流24197 次安装40 周前更新
代码仓库

关于 Convex Agents Files

Convex Agents Files 是面向 Convex Agent 开发者的技能，介绍文件存储、消息附件、图像处理和清理流程，也涵盖图像生成及文件引用跟踪。

主要功能

  1. 01存储上传的文件
  2. 02将文件附加到消息
  3. 03以内联方式处理文件
  4. 04生成并保存图像
  5. 05跟踪元数据并清理文件

适用场景

  1. 01分析用户上传的图像
  2. 02在 Agent 工作流中处理文档
  3. 03将文件附加到对话消息
  4. 04清理不再引用的文件

安装

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

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

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

详细介绍

用途

文件和图片让 Agent 能够理解并生成视觉内容。涵盖上传、存储、附加到消息以及管理文件生命周期。

何时使用此技能

  • 用户上传图片供 Agent 分析
  • Agent 需要处理文档或文件
  • Agent 使用 DALL-E 生成图片
  • 构建基于文件的工作流
  • 实现文件清理和跟踪

上传并存储文件

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

export const uploadFile = action({
  args: { fileData: v.string(), filename: v.string(), mimeType: v.string() },
  handler: async (ctx, { fileData, filename, mimeType }) => {
    const bytes = Buffer.from(fileData, "base64");

    const { file } = await storeFile(
      ctx,
      components.agent,
      new Blob([bytes], { type: mimeType }),
      { filename, sha256: "hash" }
    );

    return {
      fileId: file.fileId,
      url: file.url,
      storageId: file.storageId,
    };
  },
});

随消息发送文件（2 步）

先上传，再发送带附件的消息：

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

// Step 1: Save message with file
export const submitFileQuestion = mutation({
  args: { threadId: v.string(), fileId: v.string(), question: v.string() },
  handler: async (ctx, { threadId, fileId, question }) => {
    const { imagePart, filePart } = await getFile(ctx, components.agent, fileId);

    const { messageId } = await saveMessage(ctx, components.agent, {
      threadId,
      message: {
        role: "user",
        content: [
          imagePart ?? filePart,
          { type: "text", text: question },
        ],
      },
      metadata: { fileIds: [fileId] },
    });

    return { messageId };
  },
});

// Step 2: Generate response
export const generateFileResponse = action({
  args: { threadId: v.string(), promptMessageId: v.string() },
  handler: async (ctx, { threadId, promptMessageId }) => {
    const { thread } = await myAgent.continueThread(ctx, { threadId });
    await thread.generateText({ promptMessageId });
  },
});

内联文件保存（仅限 Action）

在生成时直接传入文件：

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

    await thread.generateText({
      message: {
        role: "user",
        content: [
          {
            type: "image",
            image: Buffer.from(imageData, "base64"),
            mimeType: "image/png",
          },
          { type: "text", text: question },
        ],
      },
    });
  },
});

生成并保存图片

export const generateAndSaveImage = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { image } = await generateImage({
      model: openai.image("dall-e-2"),
      prompt,
    });

    const { file } = await storeFile(ctx, components.agent, image, {
      filename: `generated-${Date.now()}.png`,
    });

    return { fileId: file.fileId };
  },
});

关键原则

  • 自动存储：大于 64KB 的文件会自动存储
  • 文件跟踪：元数据跟踪哪些消息引用了文件
  • URL 生成：签名 URL 防止未经授权的访问
  • MIME 类型推断：未提供时自动检测
  • 清理：跟踪文件以进行垃圾回收

后续步骤

  • 查看 messages 了解消息管理
  • 查看 streaming 了解流式文件处理
  • 查看 fundamentals 了解 Agent 设置

评论

支持 Markdown