• 如何使用本插件
• 安装说明
  • 第零步：安装Python和Zotero
  • 第一步：安装uv/conda
  • 第二步：下载项目文件
  • 第三步：启动服务
  • 第四步：下载并安装插件
  • 第五步：Zotero端插件设置
  • 第六步：关于翻译选项
  • 第七步：关于包更新
  • 其他安装方法
• 常见问题（FAQ）
  • 关于网络
  • 关于环境
  • 关于翻译服务
  • 关于OCR/扫描件
  • 关于翻译效果
  • 关于插件功能
  • 关于提问
  • 关于支持本插件
• 致谢
• 贡献者
• 如何支持我
• 开源协议与使用声明

本指南将引导您完成 Zotero PDF2zh 插件的安装和配置。

❓ 遇到问题

• 跳转至本项目总结的常见问题：常见问题(FAQ)
• 基础问题（例如如何安装python，如何安装conda等问题）请向AI提问
• 在github issue区提问
• QQ群提问:
  • 提问时需要遵循规则: 确保已经阅读过issue区和常见问题文档，重复问题不会得到回复。确定问题为新问题后, 将终端报错复制到txt文件, 并截图zotero插件设置端配置
  • 1群: 971960014(已满)
  • 2群: 897867369(已满)
  • 3群: 1064375380(已满)
  • 4群: 443031486(已满)
  • 5群: 1064435415(已满)
  • 6群: 1083772600
  • 7群: 930368730
  • 入群问题答案: github

• Python：下载链接，建议安装 3.12 版本

• Zotero：支持 Zotero 7 和 Zotero 8（适配 by @Aphcity）

• 打开命令行工具（后续步骤都在命令行中执行）：

  • Windows：按 Win + R → 输入 cmd → 回车（建议以管理员身份运行）
  • macOS：按 Cmd + 空格 → 输入"终端" → 回车
  • Linux：Ctrl + Alt + T

选择一个环境管理工具。如果不确定选哪个，推荐 uv。

uv安装(推荐)

# macOS/Linux
wget -qO- https://astral.sh/uv/install.sh | sh
# Windows（在PowerShell中执行）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后执行 uv --version，能看到版本号即成功。

如果提示找不到命令，需将 uv 路径添加到环境变量并重启终端：

# MacOS/Linux
export PATH="$HOME/.local/bin:$PATH"
# Windows PowerShell
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

conda安装

参考 Miniconda 安装指南进行安装，安装后执行 conda --version 验证。

⚠️ Windows用户注意：请勿在C盘（系统盘）下创建项目文件夹，建议在D盘或其他非系统盘操作。例如：先执行 D: 切换到D盘，再执行后续命令。

# 1. 创建并进入zotero-pdf2zh文件夹
mkdir zotero-pdf2zh && cd zotero-pdf2zh

# 2. 下载并解压server文件夹
# 如果server.zip下载失败, 可以直接访问: https://github.com/guaguastandup/zotero-pdf2zh/blob/main/server.zip 手动下载
wget https://raw.githubusercontent.com/guaguastandup/zotero-pdf2zh/refs/heads/main/server.zip
unzip server.zip

# 3. 进入server文件夹
cd server

💡 提示：确认目录结构

解压后，请确认您的目录结构应该是：

zotero-pdf2zh/
└── server/
    ├── server.py
    ├── ...
    └── requirements.txt

如果您看到的是 server/server/ 这样的嵌套结构（两层 server），说明解压出现了嵌套问题，请执行：

# 回到上级目录
cd ..
# 移动内容到正确位置
mv server/server/* server/
# 删除空的嵌套目录
rmdir server/server
# 重新进入 server 目录
cd server

快速检查方法： 执行 cd server 后，运行 ls server.py，如果能看到 server.py 文件，说明目录结构正确。如果提示找不到文件，说明存在嵌套问题。

uv 用户（推荐）

uv run --python 3.12 --with-requirements requirements.txt server.py

conda 用户

# 1. 创建环境（仅首次需要）
conda create -n zotero-pdf2zh-server python=3.12 -y
# 2. 激活环境
conda activate zotero-pdf2zh-server
# 3. 安装依赖（仅首次需要）
pip install -r requirements.txt
# 4. 启动服务
python server.py --env_tool=conda

⚠️ 重要：翻译功能依赖本脚本运行，使用翻译时不要关闭此终端窗口。

在启动命令后面追加参数即可，例如 ... server.py --port=9999：

• uv 用户：安装后请不要移动或重命名 server 文件夹（会影响环境路径）。
• conda 用户：环境存储在 conda 的 envs 目录中，可以安全移动 server 文件夹。

新版本v4.0.1下载链接

1. 安装方式：在zotero中打开“工具-插件”，将xpi文件拖入，进行安装。（若拖入后功能未生效，请重启Zotero）
2. 如何更新：您可以在zotero中检查更新，或选择自动更新，来获取最新版本插件。

zotero 插件设置页面

检查服务器连接

在插件设置页面中，点击"Python Server IP"输入框旁边的"检查连接"按钮，可测试与Python服务的连接状态。若显示连接成功，则服务正常运行；若显示连接失败，请检查：

• server.py 脚本是否正在运行
• 端口号是否正确（默认8890）
• 防火墙/杀毒软件是否阻止了连接

配置选项说明

• 切换翻译引擎pdf2zh/pdf2zh_next，界面将显示不同引擎的翻译配置

• 其他说明（初次配置可以忽略）

  • 关于qps(Query Per Second)和poolsize选项：

  • 具体数值请参考您的LLM服务商提供的参数（例如zhipu）

    • 计算公式: qps = rpm / 60 (RPM = Request Per Minute)
    • 对于上游为qps/rpm限速：pool size = qps * 10;
    • 对于上游为并发数限制: pool size = max(向下取整(0.9*官方并发数限制), 官方并发数限制-20)，qps = pool size
    • 如果您不知道怎么设置, 请直接设置qps即可, pool size设置为默认值0即可

  • 翻译引擎pdf2zh的自定义字体：

  • • 字体文件路径为本地路径。

    • 如果采用远端服务器部署，暂时无法在插件设置中指定字体路径。需要您手动修改config.json文件中的NOTO_FONT_PATH字段。

  • 额外配置参数名需要与config文件中的字段相同(例如在pdf2zh_next中, openai对应的额外配置: openai_temperature和openai_send_temperature与config.toml文件中的字段相对应), 本功能将在未来继续优化, 可参考文档

网页端查看翻译进度

服务启动后，可在浏览器中访问 http://127.0.0.1:8890 查看翻译进度和使用相关功能：

查看当前配置信息

实时查看翻译进度

查看历史翻译记录并预览下载

功能说明：

• 查看当前server端的配置信息
• 实时显示当前翻译任务状态
• 查看翻译历史记录，支持预览和下载翻译后的文件

📢: v4.0.3(3月7日) windows端暂时不支持多进度条显示(多个pdf同时翻译时只会有一个进度条会更新，是bug待修复)

翻译引擎对比

插件支持两种翻译引擎，请根据需求选择：

翻译服务配置

配置翻译服务需完成两步：

第一步：添加API配置

在"LLM API配置管理"区域点击"新增"，填写服务配置信息。同一服务可添加多个配置，但只能激活其中一个。

第二步：选择翻译服务

在页面顶部的"翻译服务"下拉菜单中，选择要使用的服务名称。

警告：仅添加API配置不会生效，必须完成第二步选择服务，翻译功能才能使用。

💡 翻译服务介绍(必读)

• 除了免费服务，您均需要配置自己的API Key和URL才可以使用翻译服务（某些服务不需要配置URL，可以忽略）

• 您可以根据实际情况自行调整并发数

• openailiked服务选项可以填写所有兼容openai格式的LLM服务, 您需要填写您的LLM服务供应商提供的URL, API Key, Model名称等信息。

  • 示例: 火山引擎url填写为https://ark.cn-beijing.volces.com/api/v3

在Zotero中对条目/PDF右键，选择PDF2zh-翻译选项，进行翻译。

对条目/附件单击右键, 可以看到四个翻译选项:

💡 翻译选项解析

翻译选项	解释	示例图片
翻译PDF (translate PDF)	点击原文PDF或论文条目, 将会生成在Zotero插件设置端所选择的默认生成文件
裁剪PDF (crop PDF)	选择dual/mono类型附件, 将会对选择的附件在宽度1/2处裁剪, 然后上下拼接, 此功能适合手机阅读 注意事项: 1. 本选项会将页面两侧空白处进行裁剪 2. 若产生截断了原文内容的情况, 可将server/utils/config.py中的config.pdf_w_offset值降低
双语对照 (compare PDF)	点击此选项, 会生成左边为原文, 右边为翻译后文本的PDF 1. 选择"Dual文件翻译页在前"可以交换生成顺序 2. 此选项等同于翻译引擎为pdf2zh_next, 且双语(Dual)文件显示模式为Left&Right时生成的文件
双语对照(裁剪) (crop-compare PDF)	此选项仅针对双栏PDF论文。它会先将PDF竖向裁剪为单栏文件，再左右拼接。

您可以多选条目，右键菜单，然后进行批量PDF翻译

zotero插件和server脚本均具有自动更新功能, 但是为了使用最新版本babeldoc和pdf2zh_next, 您需要进行下列操作:

0. 进入server文件夹

1. 进入虚拟环境: 名称为zotero-pdf2zh-next-venv

# conda
conda activate zotero-pdf2zh-next-venv

# uv
## MacOS/Linux
source ./zotero-pdf2zh-venv-next/bin/activate
## Windows
.\zotero-pdf2zh-next-venv\Scripts\activate

2. 更新

# conda
pip install --upgrade pdf2zh_next babeldoc
# uv
uv pip install --upgrade pdf2zh_next babeldoc

如果您不想配置Python虚拟环境，可以直接使用pdf2zh_next 提供的预编译exe版本。

安装步骤：

1. 下载exe包：访问 pdf2zh_next Release 页面，下载 pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64.zip（选择 with-assets 版本）

2. 解压文件：将下载的zip文件解压到 server 目录下，

• 解压后目录结构：server/pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe

3. 运行服务：

python server.py --enable_winexe=True --winexe_path='./pdf2zh-v2.x.x-BabelDOC-v0.x.x-win64/pdf2zh/pdf2zh.exe'

注意事项：

• exe版本不需要配置Python虚拟环境，- 确保exe路径正确，路径相对于 server 目录
• 如果遇到DLL相关错误，请安装 Visual C++ Redistributable
• exe模式目前可能存在一些兼容性问题，如果遇到问题建议使用虚拟环境方式

• zotero-pdf2zh docker链接 by @xucongyong
• 请参考：Docker部署方法一 by @Rosetears520
• 请参考：Docker部署方法二 by @taozhe6

• 参考：做了一个 homebrew 的 tap，便于 mac 用户直接使用 #187 by @NightWatcher314
• 仓库链接: NightWatcher314/zotero-pdf2zh-server

如果您只想使用 pdf2zh_next/pdf2zh 引擎中的一个，并且全局 Python 版本为 3.12.0，可以不使用虚拟环境管理。

⚠️ 注意：不使用虚拟环境管理时，您需要确保：

• 全局 Python 版本为 3.12 或更高
• 已手动安装所需的依赖包

# 创建固定主虚拟环境（只需执行一次）
uv venv zotero-pdf2zh-server --python 3.12

# 激活环境
# Windows
.\zotero-pdf2zh-server\Scripts\activate
# macOS/Linux
source ./zotero-pdf2zh-server/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动服务
python server.py --enable_venv=False

# 创建主虚拟环境（只需执行一次）
conda create -n zotero-pdf2zh-server python=3.12 -y

# 激活环境
conda activate zotero-pdf2zh-server

# 安装依赖
pip install -r requirements.txt

# 启动服务
python server.py --env_tool=conda --enable_venv=False

# 如果只使用 pdf2zh:
pip install pdf2zh==1.9.11 numpy==2.2.0

# 如果只使用 pdf2zh_next:
pip install pdf2zh_next

每次翻译都需要打开终端执行启动命令，为了方便日常使用，您可以配置一键启动：

方式一：使用 uv 的用户

Windows 用户 - 创建桌面快捷脚本：

1. 先在当前终端输入 cd 命令查看完整路径

cd

终端会显示类似：D:\zotero-pdf2zh\server 的路径

2. 在桌面新建一个文本文件，右键编辑，写入以下内容：

@echo off
cd /d <粘贴刚才复制的路径>
uv run --python 3.12 --with-requirements requirements.txt server.py
pause

3. 将 <粘贴刚才复制的路径> 替换为您复制的实际路径

4. 重命名为 start-pdf2zh.bat（后缀名必须是 .bat）

5. 保存后双击即可启动

macOS / Linux 用户 - 配置别名（alias）：

1. 打开终端，编辑 shell 配置文件：

# 如果使用 zsh（macOS 默认）
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc

2. 在文件末尾添加别名（请根据实际路径修改）：

alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && uv run --python 3.12 --with-requirements requirements.txt server.py'

3. 保存后执行：

source ~/.zshrc
# 或
source ~/.bashrc

4. 之后只需在终端输入 pdf2zh-start 即可一键启动

方式二：使用 conda 的用户

Windows 用户 - 创建桌面快捷脚本：

1. 先在当前终端输入 cd 命令查看完整路径

cd

终端会显示类似：D:\zotero-pdf2zh\server 的路径

2. 在桌面新建一个文本文件，右键编辑，写入以下内容：

@echo off
cd /d <粘贴刚才复制的路径>
python server.py --env_tool=conda
pause

3. 将 <粘贴刚才复制的路径> 替换为您复制的实际路径

4. 重命名为 start-pdf2zh-conda.bat（后缀名必须是 .bat）

5. 保存后双击即可启动

macOS / Linux 用户 - 配置别名（alias）：

1. 打开终端，编辑 shell 配置文件：

# 如果使用 zsh（macOS 默认）
nano ~/.zshrc
# 如果使用 bash
nano ~/.bashrc

2. 在文件末尾添加别名（请根据实际路径修改）：

alias pdf2zh-start='cd /path/to/zotero-pdf2zh/server && python server.py --env_tool=conda'

💡 注意：使用此别名前，请确保已初始化 conda（通常在安装 conda 后会自动添加到 .bashrc 或 .zshrc 中）

3. 保存后执行：

source ~/.zshrc
# 或
source ~/.bashrc

4. 之后只需在终端输入 pdf2zh-start 即可一键启动

• [🔥高频问题]Q：我遇到了网络问题（NetworkError when attempting to fetch resource），该怎么办？

• A：

  • 首先点击插件设置页面中"Python Server IP"旁边的"检查连接"按钮，查看连接状态
  • 若显示连接失败，请按以下步骤排查：
    • 确保插件是最新版：版本号4.0.x，而不是旧版本：3.0.x或2.4.3
    • 翻译过程中需要保证server.py脚本开启
    • 请检查8890端口是否被其他程序占用
    • 切换端口重试（可以多次尝试更换新的端口）
      • 切换端口需要修改两个地方（以新端口号为9999为例）
        • zotero插件配置里的python server ip里的8890修改为9999
        • 执行脚本时的指令修改为：python server.py --port=9999
    • 检查防火墙是否开启
    • 关闭杀毒软件并重启电脑
  • 另外如果您执行翻译时，终端有日志输出/正在尝试翻译，此后报网络错误，则不符合上述情况，应该优先解决终端中提示的报错。

• [🔥高频问题]Q: 翻译卡在某个地方不动了 / pdf2zh_next第一次翻译时进度条一直卡在某一处（例如10/100）/ 出现assets download failed问题

• A：

  • 这是因为pdf2zh_next在首次启动时，需要远程下载字体和模型文件，这个过程比较慢。
  • 您可以：
    • 访问pdf2zh_next的最新release: https://github.com/PDFMathTranslate-next/PDFMathTranslate-next/releases, 下载其中的exe包，例如：pdf2zh-v2.6.4-BabelDOC-xxx-with-assets-win64.zip
      • 如果由于网络问题无法下载, 请加入QQ群下载群文件
    • 解压后打开其中的pdf2zh.exe，然后打开命令行中提示的gui路径(http://127.0.0.1:7860/)，翻译一篇文章后退出。
    • 回到插件重新翻译。

  为什么这样做是有效的：

  • 资源已下载并加入缓存：通过exe包完成一次翻译后，字体和模型文件会被下载并缓存到系统中。之后再次使用插件时，就可以直接使用缓存的资源，无需重新下载。
  • 网络环境检查：如果依然出现下载失败的情况，请检查您的网络环境是否能够正常访问GitHub或相关资源服务器。您可以尝试切换网络、使用代理工具，或者加入QQ群下载群文件中的离线资源包。

• [🔥高频问题]Q：我遇到了““动态链接库(DLL)初始化例程失败”的错误，但是我尝试安装了提示中指定的vs_redist.x64.exe包，依然报错，该怎么办？

• A：

  • 您需要进入虚拟环境，将onnx包降级到1.16.1版本
    • pdf2zh 对应的虚拟环境名为zotero-pdf2zh-venv
    • pdf2zh_next对应的虚拟环境名为zotero-pdf2zh-next-venv
    • 如果您依然不会操作，可以把这段内容发送给AI，并且告诉它您正在使用uv还是conda进行虚拟环境管理。
  • 您也许缺少的是x86或其他版本的Visual C++ Redistributable，可以尝试安装以下三个文件：
    • VC_redist.x86.exe（32位版本）
    • VC_redist.x15.x64.exe（64位版本，2015-2019）
    • VC_redist.x17.x64.exe（64位版本，2015-2022）
    • 如果您在QQ群中，也可以直接在群文件中下载这三个文件
  • 也许您正在使用macOS旧版本系统（这个问题大部分发生在windows系统中），您需要在安装时python虚拟环境指定为3.11而不是3.12
  • 另有群友贡献的方法供您尝试:
    • 

• [🔥高频问题]Q: 我的命令行中提示: Failed to canonicalize script path

• A: 删除server路径下的zotero-pdf2zh-next-venv或者zotero-pdf2zh-venv文件夹, 然后重新配置。使用uv方法在安装配置后不可以修改路径名/移动文件夹。

• Q：我没配置API，可以用吗？

• A：不可以，除非您使用的是免费的服务。

  • 例如，如果您选择pdf2zh_next引擎，并且使用siliconflowfree服务，就可以获得免费的服务，但是本服务可能会漏翻译一些内容。建议您优先自己配置API。

• [🔥高频问题]Q：我正在使用bing/google，也是免费的，但是翻译到一半就报错了/卡住了/中止了

• A：因为bing/google的限流较为严重，您需要把线程数设置得非常低。建议您最好换到更加稳定的服务，以便长期使用。

• Q：我感觉这个翻译消耗的Token很多，怎么办？

• A：

  • 通常一篇10页的英文文献消耗Token量在7～10w左右，单页在5k左右，您可以先基于此数据进行检查
  • 如果您正在使用pdf2zh_next引擎，可以尝试在zotero插件配置中，把提取术语表选项关闭，这个选项会消耗较多Token

• [🔥高频问题]Q：翻译后部分段落缺失（未被翻译），该怎么办？

• A：

  • 原因说明：为了保证PDF能够正常生成，当翻译失败时，程序会使用原文替代翻译后的位置，因此会出现部分段落未翻译的情况。
  • 解决方法：
    1. 尝试更换翻译引擎（pdf2zh/pdf2zh_next）
    2. 检查您的API是否超限（查看终端报错信息或API服务商后台）
    3. 如果使用的是免费服务（如bing/google），可能是限流导致，建议切换到更稳定的服务

• [🔥高频问题]Q1：翻译界面提示 Scanned PDF detected, 翻译失败

• A：

  • pdf2zh和pdf2zh_next不直接提供文档OCR功能, 您需要用其他工具对自己的扫描版文件进行OCR处理, 再调用插件的翻译功能。
  • 推荐使用 Adobe Acrobat Pro、ABBYY FineReader 或其他OCR工具对扫描版PDF进行文字识别处理，然后再使用本插件进行翻译。

• Q2：pdf2zh_next服务中的ocr模式与兼容模式是指什么？

• A：

  • OCR选项并不是直接提供OCR服务的，它只是一个对于OCR后的文件进行兼容的临时方案，您保持自动开启OCR临时方案的选项开启即可。
  • 兼容模式生成的文件大小会更大，您在非必要的时候不需要开启。（如果您翻译功能正常，但是某一次失败了/并且确定不是远程翻译服务的问题，那您可以尝试开启）

• Q：为什么会出现段落缺失、断行或重影的情况？
• A：
  • 扫描件问题：如果文档本身是扫描件，必须先经过OCR处理后再进行翻译。若未进行OCR识别，会导致断行或段落缺失问题。
  • 重影现象：出现的重影通常是由于OCR识别不准确或PDF文件本身的问题导致的。建议使用高质量的OCR工具重新处理文档。
  • 段落缺失：如前文所述，翻译失败时程序会用原文替代，建议先排查API服务是否正常。

• Q：我不知道zotero插件里的各个功能是什么意思
• A：您可以自由尝试，请尽量不要对这些问题进行提问，翻译引擎具有缓存的设置，也就是说您重复对同一篇文献进行翻译时，可能不会消耗过多的Token（不能保证完全不消耗）

提问前请先尝试以下方法：

• 将终端报错信息发送给AI（ChatGPT、Gemini、DeepSeek等）进行分析
• 在本文档中搜索错误关键词或查阅相关章节

如需在群内提问，请提供：

• 终端完整输出（复制到txt文件）

• Zotero设置截图

• Zotero弹窗截图

• 说明您已尝试过的解决方法

• Q：我在群里问问题，怎么没人回复我？

• A：

  • 请确认您的问题不属于常见问题，或在问题描述中说明"已查阅常见问题但仍未解决"
  • 请提供终端输出、Zotero设置截图和弹窗截图，以便定位问题
  • 如果被漏看，可以稍后重新发或@群主

• Q：可是我给作者打赏了，希望能得到优先支持。

• A：非常感谢您的支持！打赏是对项目的肯定和鼓励，如果打赏后遇到问题，欢迎私聊群主，我会尽力协助您解决。

• Q：我很喜欢这个插件，想要提供支持，让这个插件更好地长期运行，我该怎么做？
• A：
  • 您可以继续下滑，找到支持本项目开发者的方式（支付码/爱发电等方式，您的昵称将出现在赞助者名单）
  • 您可以参与本项目的开发
  • 您可以为本项目点一个star
  • 您可以在issue区提出您期望的未来功能（需是合理的功能建议）
  • 您可以将本插件推荐给身边的朋友，并且在他们的安装过程中给出一些指导

• PDF2zh by @Byaidu
• PDF2zh_next by @awwaawwa
• zotero-plugin-template by @windingwind
• 沉浸式翻译为本项目的活跃贡献者赞助每月Pro会员兑换码，详情请见：CONTRIBUTOR_REWARD.md

感谢各位贡献者对项目的付出!!

贡献者名单：

💐 免费开源插件，您的支持是我继续开发的动力～祝您科研/工作/学习顺利!

• 赞助时, 请在备注中留下您希望出现在赞助者名单的姓名或昵称💗

• ☕️ Wechat微信/Alipay支付宝

• 🐳 爱发电

• 🤖 【SiliconFlow邀请链接】: https://cloud.siliconflow.cn/i/WLYnNanQ

• 🤖 【方舟Coding Plan邀请链接】: 方舟 Coding Plan 支持 Doubao、GLM、DeepSeek、Kimi 等模型，工具不限，现在订阅折上9折，低至8.9元，订阅越多越划算！立即订阅：https://volcengine.com/L/nVFMmMWNd6U/ 邀请码：8EYCPKHC

• 🤖 【GLM Coding Plan邀请链接】: 🚀 速来拼好模，智谱 GLM Coding 超值订阅，邀您一起薅羊毛！Claude Code、Cline 等 20+ 大编程工具无缝支持，“码力”全开，越拼越爽！立即开拼，享限时惊喜价！链接：https://www.bigmodel.cn/glm-coding?ic=44Y4L3RHPG

• 赞助者名单(持续更新), 按照时间先后排序:

  • 我会定期重复检查，但如果仍然有统计遗漏, 请您联系我, QQ: 546409178
  • 如果您希望在赞助者名单中补充您的昵称和您的个人主页链接，也请联系我~

赞助者名单

感谢您的支持! 您的支持是我开发的动力~

本项目采用开源协议发布，所有开发者在使用本插件代码时必须遵循以下原则：

1. 遵守开源协议：使用本项目的代码必须遵循本项目所采用的AGPL开源协议（详见 LICENSE 文件），包括但不限于保留版权声明、开源修改后的代码等。

2. 禁止商业倒卖：本插件为免费开源项目，严禁任何形式的商业倒卖行为，包括但不限于：

   • 将本插件打包后以收费形式出售
   • 以"代安装"、"技术服务"等名义收取高额费用后交付本插件
   • 将本插件作为付费产品的一部分进行销售

   ⚠️ 特别提醒：商业贩子请勿加入QQ群提问，不要消耗维护者的精力。一旦发现，将直接移出群聊并拉黑。

3. 合理使用：欢迎个人学习、研究、非商业用途的使用。如需商业使用，请联系作者获取授权。

4. 尊重开源精神：我们鼓励开发者基于本项目进行改进和贡献，但请尊重原作者的劳动成果，遵守开源社区的基本准则。

如发现违反上述原则的行为，作者保留追究法律责任的权利。