zyw-ai-tools

基于向量检索的AI工具管理库，专为Next.js 14+项目设计，帮助您轻松存储、检索和动态加载AI工具。

特点

• 🚀 基于PostgreSQL + pgvector的向量相似性检索
• 📦 与Next.js服务器组件完美集成
• 🔍 支持自然语言搜索工具
• 🔄 动态加载匹配的工具并执行
• 🔐 支持公开/私有工具的权限控制
• 🎨 基于Mantine UI的现代客户端界面
• 🧙‍♂️ AI辅助生成工具描述、参数和代码
• 🛠️ 清晰分离的服务器API和客户端组件

安装

npm install zyw-ai-tools
# 或
yarn add zyw-ai-tools
# 或
pnpm add zyw-ai-tools

前提条件

• Node.js 18+
• Next.js 14+
• PostgreSQL 数据库（安装pgvector扩展）

架构概述

该库采用了清晰的架构分离：

• 服务器端API: 通过主模块导出 (import { ... } from 'zyw-ai-tools')
• 客户端组件: 通过客户端子模块导出 (import { ... } from 'zyw-ai-tools/client')

这种设计避免了在服务器端代码中错误地导入客户端组件，符合Next.js推荐的最佳实践。

数据库设置

1. 确保您的PostgreSQL数据库已安装pgvector扩展。可以按照pgvector官方文档进行安装。

2. 在项目根目录创建.env文件，添加数据库连接信息：

   DATABASE_LOCAL_URL="postgresql://用户名:密码@localhost:5432/数据库名?schema=public"

3. 初始化数据库：

   npx prisma db push

服务器端配置

在Next.js项目中创建一个配置文件，例如lib/aitools-config.ts：

import { config } from 'zyw-ai-tools';
import { PrismaClient } from '@prisma/client';
import { OpenAI } from '@ai-sdk/openai';

// 创建Prisma客户端实例
const prisma = new PrismaClient();

// 创建OpenAI客户端实例
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

// 配置AI工具库
config({
  // 数据库连接
  prisma,
  
  // 向量维度配置（默认1536，适配OpenAI）
  vectorDimension: 1536,
  
  // AI生成功能（可选）
  ai: {
    // 文本嵌入函数（必需）
    embed: async (text) => {
      const response = await openai.embeddings.create({
        model: 'text-embedding-3-small',
        input: text
      });
      return response.data[0].embedding;
    },
    
    // 描述生成函数（可选）
    generateDescription: async (prompt) => {
      const completion = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [
          { role: 'system', content: '你是一个帮助用户编写AI工具描述的助手。' },
          { role: 'user', content: prompt }
        ]
      });
      return completion.choices[0].message.content || '';
    },
    
    // 参数生成函数（可选）
    generateParameters: async (description) => {
      // 实现略
    },
    
    // 执行代码生成函数（可选）
    generateExecuteCode: async (description, parameters) => {
      // 实现略
    },
    
    // 代码审核函数（可选）
    reviewCode: async (code) => {
      // 实现略
    }
  }
});

客户端界面集成

要在Next.js项目中集成AI工具管理界面，您需要从 zyw-ai-tools/client 子模块导入客户端组件：

1. 工具列表页面

// app/tools/page.tsx
import { ToolList } from 'zyw-ai-tools/client';
import { getCurrentUser } from '@/lib/auth'; // 您的用户认证函数

export default async function ToolsPage() {
  const user = await getCurrentUser();
  
  if (!user) {
    return <div>请先登录</div>;
  }
  
  return (
    <div className="container mx-auto py-8">
      <ToolList userId={user.id} />
    </div>
  );
}

2. 工具创建页面

// app/tools/create/page.tsx
import { ToolCreator } from 'zyw-ai-tools/client';
import { getCurrentUser } from '@/lib/auth'; // 您的用户认证函数

export default async function CreateToolPage() {
  const user = await getCurrentUser();
  
  if (!user) {
    return <div>请先登录</div>;
  }
  
  return (
    <div className="container mx-auto py-8">
      <ToolCreator userId={user.id} />
    </div>
  );
}

3. 工具详情页面

// app/tools/[id]/page.tsx
import { ToolDetail } from 'zyw-ai-tools/client';
import { getTool } from 'zyw-ai-tools';
import { getCurrentUser } from '@/lib/auth'; // 您的用户认证函数

export default async function ToolDetailPage({ params }: { params: { id: string } }) {
  const user = await getCurrentUser();
  const tool = await getTool(params.id);
  
  if (!tool) {
    return <div>工具不存在或已删除</div>;
  }
  
  const isOwner = user?.id === tool.userId;
  
  return (
    <div className="container mx-auto py-8">
      <ToolDetail 
        tool={tool} 
        isOwner={isOwner} 
      />
    </div>
  );
}

服务器端API使用

使用服务器端API可以直接从主模块导入：

// 服务器组件或API路由
import { getToolById, searchTools, saveTool } from 'zyw-ai-tools';

// 根据ID加载工具
const tool = await getToolById('工具ID');

// 根据查询文本搜索相关工具
const tools = await searchTools('将摄氏度转换为华氏度', 5);

// 执行工具
const result = await tools[0].execute({ 
  temperature: 25 
});

客户端组件与类型

客户端组件和类型从专用的子模块导入：

// 客户端组件
import { 
  ToolList, 
  ToolCreator, 
  ToolDetail, 
  CodeEditor 
} from 'zyw-ai-tools/client';

// 客户端类型
import type { 
  ToolListProps, 
  ToolDetailProps,
  ToolSummary,
  ServerActionResponse
} from 'zyw-ai-tools/client';

工具创建流程

使用客户端界面，用户可以按照以下步骤创建AI工具：

1. 基本信息设置：填写工具名称、描述和可见性设置。也可以从文件导入或使用AI辅助生成描述。

2. 参数定义：添加工具所需的参数，包括名称、类型、是否必填和描述。可以使用AI自动根据工具描述生成参数。

3. 执行逻辑实现：编写工具的执行代码。支持JavaScript代码编辑，可以通过AI辅助生成代码。

4. 确认提交：审核工具信息，预览完整代码，并提交工具。

API参考

服务器端API (zyw-ai-tools)

• 配置

  • config(options) - 配置工具库

• 工具管理

  • saveTool(data) - 保存新工具或更新现有工具
  • getTool(id) - 根据ID获取工具
  • getToolById(id) - 根据ID获取并加载工具模块
  • searchTools(query, topK?, userId?) - 搜索相关工具
  • deleteTool(id, userId) - 删除工具

客户端组件 (zyw-ai-tools/client)

• UI组件
  • <ToolList> - 工具列表组件
  • <ToolCreator> - 工具创建组件
  • <ToolDetail> - 工具详情组件
  • <CodeEditor> - 代码编辑器组件

排查常见问题

类型错误

如果您遇到类型相关错误，请确保：

1. 从正确的模块导入：

   • 服务器API从主模块导入
   • 客户端组件从/client子模块导入

2. 如果在服务器组件中使用客户端组件，请通过动态导入：

   import dynamic from 'next/dynamic';
      
   const ToolList = dynamic(() => import('zyw-ai-tools/client').then(mod => mod.ToolList), {
     ssr: false
   });

组件渲染错误

如果客户端组件尝试在服务器上渲染：

1. 确保在客户端组件中添加 'use client' 指令
2. 使用 Next.js 的动态导入并禁用SSR

贡献指南

欢迎提交Pull Request或Issue！

许可证

MIT