NexusFlux v0.4.9.4

一款强大且模块化的 PySide6 桌面应用程序，旨在通过集成先进的视觉语言模型（如 GPT-4o, Gemini）来自动化和加速图像数据集的批量化标签工作。其核心亮点在于集成了可视化节点式文件名解析器与全局占位符系统，能够从复杂的文件名和文件夹结构中动态生成高度定制化的提示词，特别适用于为扩散模型（Diffusion Models）训练准备数据集，或其他需要大量、精确图像描述的机器学习流程。

核心功能

项目与文件夹管理 (递归扫描)

• 智能递归扫描: 程序会自动递归扫描项目根目录下的所有子文件夹。任何直接包含图片的文件夹（包括根目录本身）都会被识别并添加到管理列表中。
• 清晰的层级视图:
  • Folder Path: 新增“Folder Path”列，清晰显示每个文件夹相对于项目根目录的路径，一目了然其层级结构。
  • Dataset Name: 现在专指从文件夹物理名称中解析出的核心名称部分（如 12_my-style 中的 my-style），可直接编辑并实时重命名磁盘上的文件夹。
• 交互式表格: 集中管理所有文件夹，支持多选、排序以及通过右键菜单进行强大的批量操作。
• 状态速览: 直观地查看每个文件夹中未打标的图片数量，并通过“Prompt Mode”列了解其提示词生成方式（全局、静态覆盖或动态解析）。
• 安全磁盘操作: 通过右键菜单可安全地删除文件夹（及其所有内容）或一键清除所选文件夹中的所有已有标签（.txt, .prompt.txt 文件）。

高级打标工作流

• 多供应商支持: 内置支持 OpenAI (GPT-4o 等)、Google (Gemini) 以及任何与 OpenAI API 兼容的本地模型（如通过 LM Studio, Ollama 运行的模型）。
• 灵活的API密钥管理:
  • 可在设置中添加多个API Key，并为每个Key单独设置启用/禁用状态。
  • 打标任务会自动轮流使用所有已启用的密钥，当某个Key的额度用尽时，可方便地禁用它而无需删除。
  • 支持对API密钥列表进行批量勾选/取消勾选操作。
• 精细化模型控制: 可在设置中调节模型的温度 (Temperature) 和种子 (Seed) 值，以微调生成结果的创造性和一致性。
• Token优化图像缩放: 可选择不同的图像质量等级（低/中/高/原始）。应用在将图像发送给API前，会在内存中进行智能缩放（保持长宽比），在不修改原始文件的前提下，大幅节省API Token成本。
• 多层级覆盖打标:
  • 默认: 自动跳过已有标签的图片。
  • 会话级覆盖: 在文件夹表格中勾选“Overwrite?”列，可对选定文件夹进行强制重新打标，该设置仅在当前会话有效，重启后重置。
  • 全局覆盖: 通过右键菜单的“Re-label Selected (Overwrite)”选项，可快速对选中文件夹执行一次性覆盖打标。
• 多线程无阻塞UI: 所有的API请求和图像处理都在后台线程中执行，确保了即使在处理大量数据时，用户界面也保持流畅和响应。

灵活的提示词系统 (全局占位符 + 动态解析)

应用程序提供两套强大的提示词生成系统，可以为不同文件夹灵活选用。

1. 全局占位符系统 (Folder-level Placeholders)

这是一个强大的新功能，适用于所有提示词模式（全局、静态、动态）。

• 可用占位符: 您可以在任何提示词输入区域（全局主提示词、静态覆盖、动态模板）使用以下占位符：
  • {Dataset Name}: 会被替换为该行文件夹表格中的“Dataset Name”列的内容。
  • {Category}: 会被替换为该行文件夹表格中的“Category”列的内容。
• 示例:
  • 全局主提示词: A photo of a {Category}, in the style of {Dataset Name}
  • 打标 img/20_cat-style style 文件夹时: 会自动变为 A photo of a style, in the style of cat-style

2. 静态提示词系统 (Presets)

• 全局主提示词: 在主界面设置一个全局的“Master Prompt”，可内嵌 {Dataset Name} 和 {Category}。
• 全局预设: 通过“显示名/实际值”的形式创建可复用的提示词片段（如 best quality, masterpiece），并可勾选启用。
• 高效的列表管理: 所有预设列表（包括全局和文件夹特定设置）现在都支持通过Ctrl/Shift进行多项选择、通过右键菜单进行批量勾选/反选，以及更智能的拖放排序（仅在拖动已选中项时触发），有效防止误操作并提升效率。
• 触发词 (Trigger Word): 勾选“Trigger?”会将文件夹的“Dataset Name”作为触发词，自动前置于最终生成的标签，并以 . 分隔。
• 文件夹级静态覆盖 (_preset.json):
  • 通过右键菜单的“Set Static Prompt (Preset Override)...”为文件夹单独设置主提示词和预设组合。
  • 此设置会覆盖全局配置，适用于需要固定、特殊提示词的文件夹。

3. 动态提示词系统 (Filename Parser)

这是本应用最强大的功能之一，通过右键菜单的“Set Dynamic Prompt (from Filename)...”激活。

• 可视化节点编辑器: 通过点击和连接节点，无需编写任何代码，即可构建一个强大的文件名解析流程。
• 多种解析操作: 支持按分隔符分割、正则表达式提取等多种方式，将 cool-cat_by-artist-xyz_2024.png 这类复杂文件名轻松解析为结构化数据（如 名称: cool-cat, 作者: artist-xyz, 年份: 2024）。
• 实时预览: 在节点编辑器中，选择任意一张示例图片，所有节点的输出结果都会实时更新，方便调试规则。
• 模板化生成 (多源占位符): 在模板中，您可以同时使用文件名解析出的字段和文件夹级占位符。
  • 示例: {作者}画的一只{名称}，它属于 {Category} 类别。
• 优先级最高: 当一个文件夹启用了动态提示词后，它将完全取代该文件夹的静态主提示词（Master Prompt），但仍然会附加已勾选的全局或静态覆盖的预设(Presets)。

现代化用户体验

• 集成图像查看器: 流畅的图像查看器，支持手动导航 (上一个/下一个)和“自动跟随”模式(当前)，以追踪打标进度。
• 实时标签编辑器: 可随时手动编辑生成的标签，所有更改都会即时、自动地以 UTF-8 编码保存到对应的 .txt 文件中。还提供了“删除当前图片标签”按钮。
• 实时Prompt预览: 无论何时修改了任何与提示词相关的设置（编辑表格、修改全局提示词、更改预设等），左侧的Prompt预览区域都会立即自动更新，显示最终将发送给API的精确内容。
• 动态缩略图预览:
  • 以文件夹为单位，分组显示所有已启用图片的缩略图。
  • 支持鼠标拖动和滚轮横向滚动浏览。
  • 支持键盘上下左右箭头进行符合视觉直觉的导航。
• 状态记忆: 自动保存上次使用的文件夹路径和UI设置，提升工作效率。
• 详细控制台: 提供实时的进度、API调用和错误日志，并支持右键清空。

---

项目结构

.
├── main.py                     # 程序入口
├── requirements.txt            # Python 依赖库
├── settings.json               # API设置和UI状态 (已在.gitignore中)
├── presets.json                # 全局提示词预设 (已在.gitignore中)
└── autolabeler/
    ├── constants.py            # 全局常量
    ├── controllers/
    │   ├── folder_action_handler.py # 文件夹右键菜单逻辑
    │   ├── labeling_manager.py # 打标工作流管理器
    │   └── main_controller.py  # 主控制器 (MVC中的C)
    ├── gui/
    │   ├── main_window.py      # 主窗口 (View的一部分)
    │   ├── parser_dialog.py    # 文件名解析器对话框
    │   └── ...                 # 其他对话框
    ├── logic/
    │   ├── file_utils.py       # 文件读写、文件夹解析
    │   ├── image_utils.py      # 图像处理
    │   ├── label_worker.py     # API打标后台线程
    │   └── thumbnail_loader.py # 缩略图加载后台线程
    ├── managers/
    │   ├── image_navigator.py  # 图像导航逻辑
    │   └── ...                 # 其他管理器
    ├── models/
    │   └── project_model.py    # 项目数据模型 (MVC中的M)
    ├── parser/                 # 文件名解析器核心模块
    │   ├── core/
    │   │   ├── engine.py       # 解析引擎
    │   │   └── nodes.py        # 节点数据结构
    │   └── ...
    ├── providers/
    │   └── api.py              # 各大模型API的实现
    └── ui/
        └── ui_manager.py       # 纯UI控件的创建与布局

---

安装与运行

1. 克隆仓库:

   git clone <your-repo-url>
   cd <your-repo-name>

2. 创建并激活虚拟环境 (推荐):

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # macOS / Linux
   source venv/bin/activate

3. 安装依赖:

   pip install -r requirements.txt

4. 运行程序: 提供了多种启动脚本：

   • Start.bat: 标准启动。
   • Start-调试模式.bat: 以调试模式启动，会显示控制台窗口。
   • Start-调试模式（自动检测环境依赖）.bat: 在调试模式基础上，自动检查并安装 requirements.txt 中的依赖。

首次使用

首次运行时，请通过菜单栏 Settings 配置您的API。

---

更新日志

v0.4.9.4

• 交互优化：条件拖放排序
  • 重构了所有列表组件（全局预设、解析器预设等）的拖放逻辑。
  • 现在，只有在点击并拖动一个已被选中的项目时，才会触发排序操作。
  • 在未选中的项目上开始拖动，会如预期般启动框选功能，彻底解决了在尝试选择多项时意外改变项目顺序的问题。
• 功能增强：文件夹特定预设对话框
  • “Set Folder-Specific Static Prompt”对话框中的“Global Presets Selection”列表现已全面升级。
  • 它现在完全支持多项选择（通过Ctrl/Shift点击）和框选。
  • 新增了与主界面一致的右键上下文菜单，提供“全部勾选”、“全部取消”和“反向选择”功能，极大地提升了在为单个文件夹覆盖预设时的操作效率。
• 功能增强：灵活的API密钥管理
  • 在“设置” > “API密钥”列表中为每个密钥增加了“启用”复选框。
  • 打标任务现在将仅使用已勾选（启用）的API密钥，方便用户在某些密钥额度耗尽时临时禁用它们。
  • 实现了与主界面一致的、可靠的批量勾选功能：在API密钥列表中选中多行后，点击任意复选框可同步更新所有选中项的启用状态，且不会丢失多选选择。
• 功能增强：控制台右键菜单
  • 为底部的控制台日志区域添加了右键上下文菜单。
  • 新增“清空控制台”操作，方便用户在长时间运行后快速清理日志。

v0.4.9.3

• 交互核心修复：预设列表批量勾选
  • 彻底修复了在“全局提示词预设”列表中多选项目后，点击任一复选框会导致选择状态丢失或勾选行为异常（如“闪烁”或状态不一致）的顽固BUG。
  • 通过重构自定义列表组件 BulkCheckListWidget 的鼠标事件处理模型（在 mousePressEvent 中标记并拦截，在 mouseReleaseEvent 中执行逻辑），完全接管了批量操作，从根本上杜绝了与Qt默认行为的冲突，确保了批量勾选/取消勾选的操作100%可靠，且交互体验与文件夹表格区完全一致。
• 功能增强：批量勾选
  • 文件夹表格: 新增了批量勾选功能。当在表格中选中多行时，点击“Use”、“Trigger?”或“Overwrite?”列的任意一个复选框，所有被选中行的对应复选框都会同步更新，且选择状态保持不变。
  • 预设列表: 为“全局提示词预设”列表初步实现了批量勾选功能，提升了批量启用/禁用预设的效率。

v0.4.9.2

• 重大功能：递归文件夹扫描
  • 递归支持: 程序现在会递归扫描项目根目录下的所有子文件夹，并自动添加任何包含图片的文件夹到列表中。
  • 根目录处理: 如果项目根目录本身也直接包含图片，它也会作为一个独立的条目被处理。
  • 清晰的路径显示: 新增 "Folder Path" 列，用于显示文件夹相对于项目根的路径，取代了之前混合在 "Dataset Name" 中的方式。
  • 恢复可编辑性: "Dataset Name" 列现在恢复了可编辑状态，可以直接修改并重命名文件夹的名称部分。
• 重大功能：全局占位符系统
  • 文件夹级占位符: 您现在可以在任何提示词字段（全局、静态覆盖、动态模板）中使用 {Dataset Name} 和 {Category} 占位符。程序在生成最终提示词时会自动用对应文件夹的数据替换它们。
  • 统一的占位符处理: 重构了提示词计算逻辑，确保无论是来自文件夹表格的占位符，还是来自文件名解析器的占位符，都能被正确合并和应用。
• 重大功能：可视化文件名解析器
  • 通过右键菜单的 "Set Dynamic Prompt (from Filename)..." 激活，提供了一个强大的可视化节点编辑器，用于从复杂文件名中提取信息并生成动态提示词。
• UI与交互性修复
  • 实时Prompt更新: 彻底修复了Prompt预览区域不会在所有相关操作（如编辑表格、修改全局提示词）后立即自动更新的问题，现在可以实时预览最终提示词。
  • 修复Current按钮: 修复了在打标进行中点击“Current”按钮会导致 AttributeError 崩溃的问题。
  • 修复触发词分隔符: 修复了触发词与API标签之间使用 , 而不是 . 连接的逻辑错误。
  • 修复节点编辑器下拉菜单: 解决了在动态提示词的节点编辑器中，“按分隔符分割”节点的下拉框无法弹出的问题，确保在模态对话框中菜单能正确显示。
• 核心稳定性修复：
  • 修复跨线程信号崩溃: 彻底解决了因 Signal 类型定义不兼容（Optional[str]）导致在特定情况下（触发词为空时）打标崩溃的顽固问题。通过将信号参数类型改为 object，确保了与Qt元对象系统的兼容性和稳定性。
  • 修复GeminiProvider: 修复了 GeminiProvider 中因局部变量问题导致的 NameError，该错误是之前不相关崩溃的潜在根源。
  • 修复缩略图线程安全: 修复了在快速显示/隐藏文件夹时，因ThumbnailLoader线程未被完全等待而可能导致的 QPainter 错误。

---