Nextra Dify Plugin

一个用于将 Nextra 文档项目与 Dify 知识库集成的 Next.js Webpack 插件。

✨ 特性

• 🔄 自动同步: 自动将 Nextra 文档同步到 Dify 知识库
• 📝 MDX 支持: 智能解析 MDX 文件内容和 frontmatter
• ✂️ 智能分割: 支持自定义分割规则，将长文档分割为多个知识块
• 🎯 灵活配置: 支持包含/排除规则，精确控制同步范围
• 🏗️ 构建集成: 无缝集成到 Next.js 构建流程
• 🔍 智能命名: 基于文件路径和菜单结构的智能文档命名
• 🎛️ 高级处理: 支持 Dify 完整的文档处理规则配置
• 📦 ESM 支持: 支持 ES 模块和 CommonJS 双重导入方式

📦 安装

# Using npm
npm install nextra-dify-plugin

# Using yarn
yarn add nextra-dify-plugin

# Using pnpm
pnpm add nextra-dify-plugin

🚀 快速开始

1. 环境变量配置

在项目根目录创建 .env.local 文件：

# Dify API 配置
DIFY_KNOWLEDGE_BASE_ID=your-knowledge-base-id
DIFY_API_TOKEN=your-api-token

# 可选：自定义 API 地址
DIFY_API_BASE_URL=https://api.dify.ai/v1

2. Next.js 配置

ESM 方式 (推荐)

// next.config.mjs
import { NextraDifyPlugin } from 'nextra-dify-plugin'

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { dev, isServer }) => {
    // 只在生产构建的客户端侧启用
    if (!dev && !isServer) {
      config.plugins.push(
        new NextraDifyPlugin({
          knowledgeBaseId: process.env.DIFY_KNOWLEDGE_BASE_ID,
          apiToken: process.env.DIFY_API_TOKEN,
          projectName: 'my-docs',
          enableUpload: true,
          enableSplit: true,
          splitMarker: '<!-- split -->',
          include: ['pages/**/*.mdx', 'docs/**/*.mdx'],
          exclude: ['node_modules/**', '.next/**'],
          maxChunkSize: 4000,
          maxChunkSplitBeforeMarker: '^##\\s', // 正则：只匹配行首的二级标题
        })
      )
    }
    return config
  },
}

export default nextConfig

CommonJS 方式

// next.config.js
const { NextraDifyPlugin } = require('nextra-dify-plugin')

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { dev, isServer }) => {
    if (!dev && !isServer) {
      config.plugins.push(
        new NextraDifyPlugin({
          knowledgeBaseId: process.env.DIFY_KNOWLEDGE_BASE_ID,
          apiToken: process.env.DIFY_API_TOKEN,
          projectName: 'my-docs',
          enableUpload: true,
          enableSplit: true,
          splitMarker: '<!-- split -->',
          include: ['pages/**/*.mdx', 'docs/**/*.mdx'],
          exclude: ['node_modules/**', '.next/**'],
        })
      )
    }
    return config
  },
}

module.exports = nextConfig

⚙️ 配置选项

基础配置

| 选项 | 类型 | 必需 | 默认值 | 说明 | |------|------|------|--------|------| | knowledgeBaseId | string | ✅ | - | Dify 知识库 ID | | apiToken | string | ✅ | - | Dify API Token | | projectName | string | ✅ | - | 项目名称，用作文档命名前缀 | | enableUpload | boolean | ❌ | false | 是否启用上传功能 | | enableSplit | boolean | ❌ | false | 是否启用内容分割 | | splitMarker | string | ❌ | '---' | 分割标记 | | include | string[] | ❌ | ['**/*.mdx'] | 包含规则 (glob 模式) | | exclude | string[] | ❌ | ['node_modules/**', '.next/**'] | 排除规则 (glob 模式) | | apiBaseUrl | string | ❌ | 'https://api.dify.ai/v1' | Dify API 基础 URL | | maxChunkSize | number | ❌ | 5000 | 分割时每个 chunk 的最大字符数 | | maxChunkSplitBeforeMarker | string | ❌ | - | 超出最大字符数时，尝试在此标志前截断，支持正则表达式 |

高级处理规则配置

插件支持 Dify 的完整文档处理规则配置：

config.plugins.push(
  new NextraDifyPlugin({
    // ... 基础配置
    process_rule: {
      mode: 'custom', // 'automatic' | 'custom'
      pre_processing_rules: [
        { id: 'remove_extra_spaces', enabled: true },
        { id: 'remove_urls_emails', enabled: false }
      ],
      segmentation: {
        separator: '\n\n\n\n',
        max_tokens: 2000,
        parent_mode: 'full-doc' // 'full-doc' | 'paragraph'
      },
      subchunk_segmentation: {
        separator: '\n\n',
        max_tokens: 400,
        chunk_overlap: 50
      },
      doc_type: 'business_document', // 文档类型
      doc_metadata: {
        title: 'API Documentation',
        language: 'Chinese',
        author: 'Development Team',
        description: 'Complete API reference'
      }
    }
  })
)

文档类型 (doc_type)

支持的文档类型：

• 'book' - 图书
• 'web_page' - 网页
• 'paper' - 学术论文/文章
• 'social_media_post' - 社交媒体帖子
• 'wikipedia_entry' - 维基百科条目
• 'personal_document' - 个人文档
• 'business_document' - 商业文档
• 'im_chat_log' - 即时通讯记录
• 'synced_from_notion' - Notion 同步文档
• 'synced_from_github' - GitHub 同步文档
• 'others' - 其他文档类型

📝 使用方法

基础使用

1. 配置环境变量和 Next.js 配置
2. 运行生产构建：npm run build
3. 插件会自动处理所有匹配的 MDX 文件并上传到 Dify 知识库

内容分割

插件支持两种内容分割方式：

1. 使用分割标记

在 MDX 文件中使用分割标记来控制内容分割：

---
title: API 使用指南
description: 详细的 API 使用说明
---

# API 使用指南

这是 API 的基础介绍内容。

<!-- split -->

## 认证

API 使用 Bearer Token 进行认证。

<!-- split -->

## 基础用法

这里是具体的使用示例...

2. 智能字符数分割

当内容长度超过 maxChunkSize 时，插件会自动分割内容。如果配置了 maxChunkSplitBeforeMarker，插件会尝试在指定标志前进行截断，避免破坏上下文连贯性。

该选项支持正则表达式，提供更精确的匹配控制：

plugin.push(new NextraDifyPlugin({
  // ... 其他配置
  maxChunkSize: 4000,
  // 常用正则表达式示例：
  maxChunkSplitBeforeMarker: '^##\\s', // 只匹配行首的二级标题
  // maxChunkSplitBeforeMarker: '^###\\s',   // 只匹配行首的三级标题
  // maxChunkSplitBeforeMarker: '^##[^#]',   // 匹配二级标题，但不匹配三级标题
  // maxChunkSplitBeforeMarker: '^#{1,3}\\s', // 匹配一到三级标题
}))

这样可以确保内容不会在段落中间被截断，而是在语义边界（如标题）处分割。正则表达式的使用让您可以精确控制分割点，避免 ## 误匹配 ### 等问题。

文档命名规则

文档名称按以下规则生成：

• 基础格式：{projectName}_{菜单路径}
• 分割文档：{projectName}_{菜单路径}_{序号}

示例：

• 文件：pages/api/authentication.mdx
• 生成名称：my-docs_pages_api_authentication
• 分割后：my-docs_pages_api_authentication_1, my-docs_pages_api_authentication_2

🔧 API 参考

NextraDifyPlugin

主插件类，实现 Webpack 插件接口。

import { type DifyPluginOptions, NextraDifyPlugin } from 'nextra-dify-plugin'

const plugin = new NextraDifyPlugin(options)

DifyClient

Dify API 客户端，用于与 Dify 知识库交互。

import { DifyClient } from 'nextra-dify-plugin'

const client = new DifyClient(apiToken, knowledgeBaseId, baseURL, processRule)

MDXParser

MDX 文件解析器，用于解析和处理 MDX 内容。

import { MDXParser } from 'nextra-dify-plugin'

const parser = new MDXParser(options)

类型定义

import type {
  DifyApiResponse,
  DifyDocument,
  DifyPluginOptions,
  DocumentChunk,
  DocumentMetadata,
  DocumentType,
  MDXFile,
  PreProcessingRule,
  ProcessRule,
  SegmentationRule,
  SubchunkSegmentationRule,
  UploadResponse
} from 'nextra-dify-plugin'

🛠️ 开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 测试文档项目
pnpm test-docs
pnpm test-docs:build
pnpm test-docs:start

📜 License

MIT License - 查看 LICENSE 文件了解详细信息。