奥创王牌工具箱 (UltraAce Toolkit)

(For English documentation, please scroll down)

---

奥创王牌工具箱的设计初衷，是将各类实用但需要通过命令行运行的Python自动化脚本，封装进一个统一、美观、且极易上手的图形用户界面（GUI）中。用户无需记忆任何复杂的命令，只需通过简单的点击、拖拽和填写，即可轻松完成批量文件处理、数据转换、代码分析等各类任务。

它的核心理念是 “一次编写，处处运行，人人可用”。

✨ 核心特性

• 高度可扩展: 只需将符合规范的Python脚本放入scripts文件夹，工具箱即可自动识别并加载，无需修改任何主程序代码。
• 用户友好: 直观的界面设计，支持文件/文件夹拖放、多选、复选框批量操作、撤销/重做等现代化功能。
• 动态参数界面: 能自动解析脚本的argparse参数，并为之生成对应的复选框、下拉菜单和输入框，告别手动拼写参数。
• 双语支持: 界面和脚本输出均支持中/英双语切换，为不同语言用户提供一致的体验。
• 内置增强型终端: 不仅能实时显示脚本的输出日志，还能在脚本未运行时作为标准的系统命令行工具使用。
• 个性化主题: 支持浅色、深色及跟随系统的显示模式，关爱你的眼睛。
• 详尽的交互反馈: 无论是代码注释、界面提示还是终端输出，我们都力求详尽、清晰，让用户和开发者随时了解程序动态。

⚠️ Alpha版本警告

请注意，本工具箱目前处于早期的Alpha开发阶段。

这意味着它可能包含未知的错误（Bug），且部分功能尚不完善。我们非常欢迎并感谢您通过GitHub Issues提交错误报告、提出功能建议，或通过Pull Request直接贡献代码。您的任何反馈与贡献都对项目的成长至关重要！

🚀 快速上手指南

对于初次接触本工具的小白用户，请严格遵循以下步骤，这能保证你顺利地第一次运行本工具。

第一步：环境准备

确保你的电脑已经安装了 Python 3.8 或更高版本。你可以在命令行（终端）中输入以下命令来检查：

python --version
# 或者
python3 --version

如果未安装，请前往 Python官方网站 下载并安装。

第二步：下载核心文件

1. 从本仓库下载最重要的三个部分：

   • 主程序文件: main.py
   • 任务脚本文件夹: scripts
   • UI文本文件: ui_texts.json（界面多语言文本配置，必须和 main.py 在同一目录，本仓库已自带）

2. 将它们放在你电脑的任意位置，但必须保持以下文件夹结构：

   你的工作区/
   ├── main.py          (主程序)
   ├── ui_texts.json    (界面文本配置文件)
   └── scripts/         (存放所有任务脚本的文件夹)
       └── 任务脚本1.py
       └── 任务脚本2.py
       ...
   

警告: main.py、ui_texts.json 和 scripts 文件夹必须位于同一级目录，否则程序将无法找到界面文本或任务脚本！

第三步：运行工具箱

打开你的命令行（终端），进入 main.py 所在的目录，然后运行它：

cd /path/to/你的工作区/
python main.py

如果一切顺利，你应该能看到“奥创王牌工具箱”的主界面了。

方法二：使用IDE（如 VS Code）运行

如果你更习惯使用代码编辑器，这也是一个非常推荐的方式：

1. 在你的IDE中，选择 “打开文件夹”，然后打开包含main.py的整个工作区文件夹。
2. 在IDE的文件浏览器中，单击打开main.py文件。
3. 关键步骤: 找到并点击IDE的“运行”按钮。请务必选择 “运行Python文件” 或 “以Python文件形式调试” 选项。

警告: 不要使用“运行选定代码”(Run Code)功能，因为它可能无法正确启动GUI。在VS Code中，这通常指右上角的绿色三角形“播放”按钮。

第四步：执行你的第一个任务

1. 选择脚本: 在程序窗口左侧的“可用脚本”列表中，点击一个你想运行的脚本（例如“文档页数统计器”）。
2. 添加文件: 直接从你的电脑桌面或文件夹中，将一个或多个文件拖拽到程序窗口中。
3. 执行: 点击窗口右下角的“执行脚本”按钮。如果任务耗时过长，旁边会出现一个红色的“停止脚本”按钮，可以随时中止任务。
4. 查看结果: 程序会自动切换到“增强型终端”选项卡，你可以在这里看到脚本运行的全部过程和最终结果。

恭喜你！你已经成功地使用了奥创王牌工具箱。

🔧 GUI 详细使用与配置

工具箱的每一个功能都为提升你的效率而设计。了解它们，能让你事半功倍。

主界面布局

• 左侧面板: 用于选择和了解脚本。
  • 可用脚本列表: 显示scripts文件夹中所有可用的任务。右键点击脚本项，可以选择“在文件夹中显示”，快速定位到脚本源文件。
  • 脚本介绍: 显示当前选中脚本的详细说明文档。
• 右侧面板: 核心操作区域，用于配置任务和查看结果。

交互功能详解

文件/文件夹列表

• 添加: 支持 拖放 或点击 “添加文件/文件夹” 按钮。
• 编辑: 双击 列表中的任意一项，可以直接修改其路径。
• 标记: 每一项前面都有一个 复选框(Checkbox)。这是本工具箱最关键的批量处理机制：
  • 当有任意项被勾选时: 点击“执行脚本”，将只处理被勾选的项。
  • 当没有任何项被勾选时: 点击“执行脚本”，将处理列表中的所有项。
• 移除:
  • 选中（高亮）或勾选任意项后，点击“移除选中项”按钮可删除它们。
  • 在没有任何项被选中或勾选时，该按钮会变为“清空所有”，点击可清空整个列表。
  • 选中列表后，按 Delete 或 Backspace 键也能快速移除。
• 全选/取消全选:
  • 点击“勾选全部”按钮可以一键勾选列表中的所有项。
  • 此时按钮会变为“取消选择”，再次点击可取消所有勾选。
  • 按 Esc 键可以快速取消所有勾选。

参数配置

• 可视化参数: 当你选择一个脚本后，这里会自动出现为该脚本定制的配置选项。你无需知道它们背后对应的命令行参数是什么，只需像填写问卷一样操作即可。
• 手动参数: 如果你需要输入一些临时的、或者脚本并未提供可视化界面的高级参数，可以在这里手动填写。格式与标准命令行完全一致（例如 -v --output "my file.txt"）。

执行与停止按钮

• 执行脚本: 配置好参数和文件列表后，点击此按钮开始执行任务。在脚本运行时，此按钮会被禁用。
• 停止脚本: 当脚本开始运行后，此按钮会变为可用状态，并以红色高亮显示。点击它可以立即强制终止当前正在运行的脚本，适用于任务卡死或需要提前结束的场景。

过程与结果

• 进度条: 当执行一个支持进度报告的脚本时，一个可视化的进度条会自动出现在“执行”按钮下方。它会实时显示任务的完成度、百分比和当前正在进行的操作，让你对耗时任务的状况了如指掌。
• 标准输出: 一个简洁的、只显示脚本最终输出的文本框。
• 增强型终端:
  • 实时日志: 完整显示脚本执行的每一步，包括依赖安装、调试信息等。所有非进度的输出都会在这里清晰记录，便于追溯。
  • 交互式输入: 如果脚本在运行过程中需要你输入任何信息（如确认“yes/no”、输入密码等），你都可以在终端下方的输入行中输入并按回车。即使是直接按回车（空输入），也会被正确传递给脚本。
  • 系统命令: 当没有脚本在执行时，这里就是一个标准的系统终端。你可以使用cd, ls, dir, pip等常用命令。输入exit可关闭程序。

菜单栏配置

• 偏好设置 -> 主题: 在这里可以切换“浅色模式”、“深色模式”或“跟随系统”。你的选择会被自动保存，下次启动时无需重新设置。

---

✍️ 任务脚本开发指南

想为你自己开发一个专属的任务脚本吗？非常简单！遵循以下“黄金法则”，你就能创造出与本工具箱完美集成的强大工具。

第一步：文件命名与存放

• 将你的Python脚本文件（.py）直接放入scripts文件夹内。
• 文件名可以任意取，但推荐使用能清晰描述其功能的名称，例如 视频格式转换器.py。

第二步：撰写“GUI友好”的文档字符串（核心）

这是你的脚本与GUI沟通的 唯一方式。一个格式正确的文档字符串能让GUI完全理解你的脚本。请将它放在脚本文件的最顶端。

标准模板:

"""
[display-name-zh] 你的脚本中文名
[display-name-en] Your English Script Name

这里是脚本的中文介绍，用几句话描述它的核心功能、使用场景和注意事项。
你可以使用Markdown的换行、列表等来排版，让它更易读。

---
兼容性:
- 文件格式: .mp4, .mkv
- 平台: 跨平台
---
更新日志:
  - v1.0 (2025-08-06): 初始版本。
~~~
This is the English description of the script. Explain its core features,
use cases, and any important notes for English-speaking users.

---
Compatibility:
- File Formats: .mp4, .mkv
- Platform: Cross-platform
---
Changelog:
  - v1.0 (2025-08-06): Initial release.
"""

• [display-name-zh]: 必需。GUI在中文模式下显示的脚本名称。
• [display-name-en]: 必需。GUI在英文模式下显示的脚本名称。
• ~~~: 必需。中/英文介绍的分隔符。分隔符以上为中文区，以下为英文区。

第三步：使用argparse搭建沟通的桥梁

GUI通过在后台执行python your_script.py --help来解析你的参数。因此，你必须使用argparse模块来定义所有用户可配置的选项。

标准模板:

import argparse

parser = argparse.ArgumentParser(description="你的脚本描述.")

# --- GUI交互参数 (必需，请直接复制) ---
parser.add_argument('--lang', type=str, default='en', choices=['zh', 'en'], help=argparse.SUPPRESS)
parser.add_argument('--gui-mode', action='store_true', help=argparse.SUPPRESS)

# --- 文件/文件夹输入 (必需，请直接复制) ---
parser.add_argument('files', nargs='*', help="由GUI传入的文件/文件夹路径列表.")

# --- 自定义可视化参数 (示例) ---
# 示例1: 生成一个复选框 (Checkbox)
# 对于开关类型的选项，使用 action='store_true'
parser.add_argument('--recursive', action='store_true', help="勾选后将搜索所有子文件夹。\nSearch all subfolders if checked.")

# 示例2: 生成一个下拉选择菜单 (ComboBox)
# 定义 choices 列表即可生成下拉菜单
parser.add_argument('--mode', type=str, choices=['fast', 'quality', 'balance'], default='balance', help="选择处理模式。\nSelect processing mode.")

# 示例3: 生成一个文本输入框 (LineEdit)
# 定义类型 (如 str, int) 但不提供 choices，即可生成输入框
parser.add_argument('--group-size', type=int, default=3, help="每组包含的文件数量 (0 = 合并全部)\nNumber of files per group (0 = merge all).")

# --- 解析参数 ---
args = parser.parse_args()

# --- 在代码中使用 ---
if args.verbose:
    print("详细模式已开启。")

print(f"当前选择的语言是: {args.lang}")
print(f"要处理的文件列表是: {args.files}")

第四步：编写对用户友好的脚本逻辑

1. 自给自足: 如果你的脚本依赖第三方库（如requests, numpy），请在脚本内部实现自动检查和安装。这能极大地方便用户。
2. 提供国际化输出: 对于所有print()到控制台的信息，请根据args.lang参数的值来决定显示中文还是英文。
3. 拥抱标准输入输出: 使用print()来输出信息，使用input()来接收用户的交互式输入。GUI会为你处理好这一切。
4. 提供可视化进度（新！）: 对于耗时较长的任务，你可以通过打印一种特殊格式的字符串来驱动GUI的进度条，这能极大地提升用户体验，同时保持你的控制台日志干净整洁。
   • 协议格式: [PROGRESS] <current_value> / <max_value> | <description_text>
   • 数据类型: <current_value> 和 <max_value> 均可以是 整数或浮点数。GUI会自动处理数值转换和映射。
   • 示例:

     total_files = 50
     for i, file in enumerate(files_to_process):
         # ... 这里是你的文件处理逻辑 ...
         
         # 发送进度指令
         # GUI会看到这行输出，并更新进度条，但不会在终端中打印它
         print(f"[PROGRESS] {i + 1} / {total_files} | 正在处理 {file.name}...", flush=True)
     
     # 任务结束时，可以发送一个100%的指令
     print(f"[PROGRESS] {total_files} / {total_files} | 全部处理完成！", flush=True)

   • 重要提示: 任何以[PROGRESS]开头的打印输出都将被GUI拦截并用于更新进度条，不会显示在终端日志中。所有其他print输出则会照常显示。请务必在进度print语句中加入flush=True，以保证进度信息被立即发送。

第五步：遵循标准的输出规范 (新)

为了给用户提供统一、可预测的体验，所有会生成新文件的脚本都应遵循“上下文感知输出”(Context-Aware Output)逻辑。这能确保无论用户如何操作，文件系统都能保持整洁。

• 场景一：处理单个文件

  • 规则：生成的新文件应直接保存在原文件的旁边。
  • 命名：建议在原文件名的基础上添加一个描述性后缀，例如 原始文件名_formatted.txt 或 原始文件名_extracted.txt。

• 场景二：处理来自同一文件夹的多个文件

  • 规则：应在这些文件共同的源文件夹内，创建一个统一的输出子文件夹。
  • 命名：子文件夹建议命名为 功能名_OutputType，例如 格式化文本_Formatted_Text。所有生成的文件将以其原始文件名保存在此子文件夹内。

• 场景三：处理来自不同文件夹的多个文件

  • 规则：应在工具箱主程序所在的目录（即当前工作目录）下，创建一个统一的输出文件夹。
  • 命名：文件夹命名规则同上（如 提取的文本_Extracted_Text）。所有生成的文件同样以其原始文件名保存在这里。

🗺️ 蓝图与未来计划

• 功能完善: 修复所有已知问题，包括动态主题切换。
• 参数国际化: 实现下拉菜单等可视化参数的选项根据GUI语言动态显示中文或英文。
• 应用打包: 在项目进入Beta或稳定版后，我们会将其打包为Windows (.exe)、macOS (.app) 等平台的可执行文件，实现真正的开箱即用，无需手动安装Python环境。

❓ 常见问题与故障排查 (FAQ)

Q: 暗色/亮色模式切换似乎不工作？

A: 这是一个已知问题。目前，主题功能的工作方式如下：“跟随系统”选项可以在程序启动时正确应用您当前的系统主题（亮色或暗色）。但是，如果您在程序运行时切换系统主题，本工具需要重启才能应用新主题。直接点击“浅色模式”或“深色模式”按钮可能无法立即生效。我们正在努力在未来的版本中修复此问题。

Q: 手动参数的格式是什么？--name value 还是 --name=value？

A: 两种都支持，但我们推荐使用--name value（空格分隔）。这是最通用、最标准的命令行格式。

Q: 我启动main.py时，程序闪退，并提示DLL加载失败，该怎么办？

A: 这是PyQt6库在某些环境下可能出现的问题。请在命令行（终端）中执行以下命令，它会强制重新安装一个干净的PyQt6，通常能解决此问题：

python -m pip install --no-cache-dir --force-reinstall PyQt6 PyQt6-Qt6

Q: 为什么我启动了程序，但是左边的“可用脚本”列表是空的？

A: 请检查并确保：

1. 存在一个名为scripts的文件夹。
2. scripts文件夹与main.py在同一个目录下。
3. scripts文件夹内至少有一个.py结尾的Python脚本文件。

Q: 如果丢失或损坏了 ui_texts.json 会怎样？

A: 程序将无法正常启动或界面文本会全部丢失。请确保 main.py 和 ui_texts.json 始终在同一文件夹，并且 json 文件内容完整。

Q: 如何让我的任务脚本支持交互，比如中途需要用户输入"yes"？

A: 只需在你的脚本代码中使用标准的input()函数即可。例如：

user_confirmation = input("Are you sure you want to proceed? (yes/no): ")
if user_confirmation.lower() == 'yes':
    # ...继续执行...

当脚本运行到这里时，GUI的“增强型终端”会自动等待用户输入。

---

UltraAce Toolkit (English Documentation)

---

The UltraAce Toolkit is designed to wrap various useful command-line Python automation scripts into a unified, elegant, and extremely user-friendly Graphical User Interface (GUI). Users no longer need to memorize complex commands; instead, they can perform bulk file processing, data conversion, code analysis, and more through simple clicks, drags, and fills.

Its core philosophy is "Write once, run anywhere, for everyone."

✨ Core Features

• Highly Extensible: Simply place a compliant Python script into the scripts folder, and the toolkit will automatically recognize and load it without any changes to the main program.
• User-Friendly: Intuitive interface design supporting drag-and-drop, multi-selection, checkbox-based batch operations, undo/redo, and other modern features.
• Dynamic Parameter Interface: Automatically parses a script's argparse parameters and generates corresponding checkboxes, dropdown menus, and input fields, eliminating manual parameter typing.
• Bilingual Support: The interface and script outputs support both Chinese and English, providing a consistent experience for users of different languages.
• Built-in Enhanced Terminal: Not only displays real-time script output logs but also functions as a standard system command-line tool when no script is running.
• Personalized Themes: Supports light, dark, and system-following display modes to care for your eyes.
• Detailed Interactive Feedback: From code comments and UI tooltips to terminal output, we strive for exhaustive clarity, keeping users and developers informed at all times.

⚠️ Alpha Version Warning

Please note that this toolkit is currently in an early Alpha development stage.

This means it may contain unknown bugs, and some features might be incomplete. We warmly welcome and appreciate you submitting bug reports or suggesting features via GitHub Issues, or contributing code directly through Pull Requests. Your feedback and contributions are crucial for the project's growth!

🚀 Quick Start Guide

For new users, please strictly follow these steps to ensure you can run the tool successfully for the first time.

Step 1: Environment Setup

Ensure you have Python 3.8 or a newer version installed on your computer. You can check by typing the following command in your command line (terminal):

python --version
# or
python3 --version

If it's not installed, please download and install it from the official Python website.

Step 2: Download Core Files

1. Download the three most important parts from this repository:

   • The main program file: main.py
   • The task script folder: scripts
   • UI text file: ui_texts.json (provides all GUI multi-language text, must be in the same directory as main.py)

2. Place them anywhere on your computer, but you must maintain the following folder structure:

   Your-Workspace/
   ├── main.py          (The main program)
   ├── ui_texts.json    (UI text config file)
   └── scripts/         (Folder for all task scripts)
       └── Task-Script-1.py
       └── Task-Script-2.py
       ...
   

Warning: main.py, ui_texts.json, and the scripts folder must all be in the same directory, otherwise the program will not find the UI text or any task scripts!

Step 3: Run the Toolkit

Open your command line (terminal), navigate to the directory containing main.py, and run it:

cd /path/to/Your-Workspace/
python main.py

If everything is correct, you should see the main interface of the "UltraAce Toolkit".

Alternative: Run with an IDE (e.g., VS Code)

If you prefer using a code editor, this is also a highly recommended method:

1. In your IDE, select "Open Folder" and open the entire workspace folder containing main.py.
2. In the IDE's file explorer, click to open the main.py file.
3. Crucial Step: Find and click the "Run" button. Make sure you select the option "Run Python File" or "Debug Python File".

Warning: Do not use the "Run Code" feature, as it may fail to launch the GUI correctly. In VS Code, this typically refers to the green triangular "play" button in the top-right corner.

Step 4: Execute Your First Task

1. Select a Script: In the "Available Scripts" list on the left side of the program window, click on a script you want to run (e.g., "Document Page Counter").
2. Add Files: Drag one or more files from your desktop or a folder directly into the program window.
3. Execute: Click the "Run Script" button in the bottom right. If a task is running, a red "Stop Script" button will appear next to it, allowing you to terminate the task at any time.
4. View Results: The program will automatically switch to the "Enhanced Terminal" tab, where you can see the entire execution process and the final result of the script.

Congratulations! You have successfully used the UltraAce Toolkit.

---

🔧 Detailed GUI Usage and Configuration

Every feature of the toolkit is designed to enhance your efficiency. Understanding them will make you even more productive.

Main Interface Layout

• Left Panel: For selecting and understanding scripts.
  • Available Scripts List: Displays all available tasks from the scripts folder. Right-clicking a script item allows you to "Show in Folder" to quickly locate the source file.
  • Script Info: Shows the detailed documentation for the currently selected script.
• Right Panel: The core operation area for configuring tasks and viewing results.

Interactive Features Explained

File/Folder List

• Add: Supports drag-and-drop or clicking the "Add Files/Folders" buttons.
• Edit: Double-click any item in the list to directly edit its path.
• Marking: Each item has a Checkbox in front of it. This is the key mechanism for batch processing:
  • When any item is checked: Clicking "Run Script" will only process the checked items.
  • When no items are checked: Clicking "Run Script" will process all items in the list.
• Remove:
  • After selecting (highlighting) or checking any items, click "Remove Selected" to delete them.
  • When no items are selected or checked, this button becomes "Clear All," which clears the entire list.
  • You can also press Delete or Backspace to quickly remove items.
• Select/Deselect All:
  • Click "Select All" to check all items in the list with one click.
  • The button will then change to "Deselect All." Clicking it again will uncheck everything.
  • Pressing the Esc key also quickly deselects all items.

Parameter Configuration

• Visual Parameters: When you select a script, custom configuration options for that script will automatically appear here. You don't need to know the underlying command-line arguments; just fill it out like a form.
• Manual Parameters: If you need to input temporary or advanced parameters that don't have a visual interface, you can type them here. The format is identical to the standard command line (e.g., -v --output "my file.txt").

Run and Stop Buttons

• Run Script: After configuring parameters and the file list, click this button to start the task. This button will be disabled while a script is running.
• Stop Script: This button becomes enabled and highlighted in red once a script begins to run. Clicking it will immediately terminate the currently running script, which is useful if a task hangs or you need to end it prematurely.

Process and Results

• Progress Bar: When running a script that supports progress reporting, a visual progress bar will automatically appear below the "Run" button. It shows the task's completion percentage and a description of the current operation in real-time, keeping you informed about long-running tasks.
• Standard Output: A simple text box that displays only the final output of the script.
• Enhanced Terminal:
  • Real-time Logs: Shows every step of the script's execution, including dependency installation and debug info. All non-progress output is clearly logged here for traceability.
  • Interactive Input: If a script requires any input during execution (like a "yes/no" confirmation or a password), you can type it in the input line at the bottom of the terminal and press Enter. Even an empty Enter press is correctly passed to the script.
  • System Commands: When no script is running, this acts as a standard system terminal. You can use common commands like cd, ls, dir, pip, etc. Type exit to close the program.

Menu Bar Configuration

• Preferences -> Theme: Here you can switch between "Light Mode," "Dark Mode," or "Follow System." Your choice is saved automatically for the next launch.

---

✍️ Task Script Development Guide

Want to develop your own custom task script? It's very simple! Follow these "Golden Rules" to create powerful tools that integrate perfectly with the toolkit.

Step 1: File Naming and Placement

• Place your Python script file (.py) directly into the scripts folder.
• You can name the file anything, but it's recommended to use a name that clearly describes its function, e.g., Video Format Converter.py.

Step 2: Write a "GUI-Friendly" Docstring (Crucial)

This is the only way your script communicates with the GUI. A correctly formatted docstring allows the GUI to fully understand your script. Place it at the very top of your script file.

Standard Template:

"""
[display-name-zh] 你的脚本中文名
[display-name-en] Your English Script Name

这里是脚本的中文介绍，用几句话描述它的核心功能、使用场景和注意事项。
你可以使用Markdown的换行、列表等来排版，让它更易读。

---
兼容性:
- 文件格式: .mp4, .mkv
- 平台: 跨平台
---
更新日志:
  - v1.0 (2025-08-06): 初始版本。
~~~
This is the English description of the script. Explain its core features,
use cases, and any important notes for English-speaking users.

---
Compatibility:
- File Formats: .mp4, .mkv
- Platform: Cross-platform
---
Changelog:
  - v1.0 (2025-08-06): Initial release.
"""

• [display-name-zh]: Required. The script name displayed by the GUI in Chinese mode.
• [display-name-en]: Required. The script name displayed by the GUI in English mode.
• ~~~: Required. The separator for Chinese/English descriptions. Above the separator is the Chinese section, below is the English section.

Step 3: Use argparse to Build the Communication Bridge

The GUI parses your parameters by running python your_script.py --help in the background. Therefore, you must use the argparse module to define all user-configurable options.

Standard Template:

import argparse

parser = argparse.ArgumentParser(description="Your script's description.")

# --- GUI Interaction Parameters (Required, copy this directly) ---
parser.add_argument('--lang', type=str, default='en', choices=['zh', 'en'], help=argparse.SUPPRESS)
parser.add_argument('--gui-mode', action='store_true', help=argparse.SUPPRESS)

# --- File/Folder Input (Required, copy this directly) ---
parser.add_argument('files', nargs='*', help="List of file/folder paths passed in by the GUI.")

# --- Custom Visual Parameters (Examples) ---
# --- Custom Visual Parameters (Examples) ---
# Example 1: Generates a Checkbox
# For on/off options, use action='store_true'.
parser.add_argument('--recursive', action='store_true', help="Search all subfolders if checked.")

# Example 2: Generates a ComboBox (dropdown menu)
# Defining a 'choices' list will generate a dropdown menu.
parser.add_argument('--mode', type=str, choices=['fast', 'quality', 'balance'], default='balance', help="Select the processing mode.")

# Example 3: Generates a LineEdit (text input box)
# Defining a type (like str or int) without 'choices' will generate an input box.
parser.add_argument('--group-size', type=int, default=3, help="Number of files per group (0 = merge all).")
  
# --- Parse Arguments ---
args = parser.parse_args()

# --- Use in your code ---
if args.verbose:
    print("Verbose mode is enabled.")

print(f"The currently selected language is: {args.lang}")
print(f"The list of files to process is: {args.files}")

Step 4: Write User-Friendly Script Logic

1. Be Self-Sufficient: If your script depends on third-party libraries (like requests, numpy), implement logic to automatically check and install them. Users will love this feature.
2. Provide Internationalized Output: For all information printed to the console (print()), decide whether to display Chinese or English based on the value of args.lang.
3. Embrace Standard I/O: Use print() to output information and input() to receive interactive user input. The GUI will handle all of this for you.
4. Provide Visual Progress (New!): For long-running tasks, you can drive the GUI's progress bar by printing a specially formatted string. This dramatically improves user experience while keeping your console logs clean.
   • Protocol Format: [PROGRESS] <current_value> / <max_value> | <description_text>
   • Data Types: Both <current_value> and <max_value> can be integers or floats. The GUI will handle the conversion and mapping automatically.
   • Example:

     total_files = 50
     for i, file in enumerate(files_to_process):
         # ... your file processing logic here ...
         
         # Send a progress command
         # The GUI will see this, update the progress bar, but not print it in the terminal
         print(f"[PROGRESS] {i + 1} / {total_files} | Processing {file.name}...", flush=True)
     
     # At the end of the task, you can send a 100% command
     print(f"[PROGRESS] {total_files} / {total_files} | All files processed!", flush=True)

   • Important: Any line printed to stdout that starts with [PROGRESS] will be intercepted by the GUI to update the progress bar and will not be displayed in the terminal log. All other print outputs will appear as usual. Be sure to include flush=True in your progress print statements to ensure the information is sent immediately.

Step 5: Follow Standard Output Conventions (New)

To provide a consistent and predictable user experience, all scripts that generate new files should adhere to the "Context-Aware Output" logic. This ensures the user's file system remains clean and organized, regardless of the operation.

• Scenario 1: Processing a Single File

  • Rule: The new file should be saved directly next to the original file.
  • Naming: It is recommended to add a descriptive suffix to the original filename, such as original-filename_formatted.txt or original-filename_extracted.txt.

• Scenario 2: Processing Multiple Files from the Same Folder

  • Rule: A unified output subfolder should be created within their common source folder.
  • Naming: The subfolder should be named Feature_OutputType, for example, Formatted_Text. All generated files will be saved inside this subfolder with their original filenames.

• Scenario 3: Processing Multiple Files from Different Folders

  • Rule: A unified output folder should be created in the directory where the main toolkit program is located (the current working directory).
  • Naming: The folder naming convention is the same as above (e.g., Extracted_Text). All generated files will also be saved here with their original filenames.

🗺️ Roadmap & Future Plans

• Feature Completion: Fix all known issues, including dynamic theme switching.
• Parameter Internationalization: Implement the ability for visual parameter options (like dropdowns) to dynamically display Chinese or English based on the GUI language.
• Application Packaging: Once the project reaches a Beta or stable version, we will package it into executable files for Windows (.exe), macOS (.app), etc., to provide a true out-of-the-box experience without needing a manual Python environment setup.

❓ FAQ & Troubleshooting

Q: The dark/light mode toggle doesn't seem to work?

A: This is a known issue. Currently, the theme functionality works as follows: The "Follow System" option correctly applies your current system theme (light or dark) upon application startup. However, if you change your system theme while the application is running, the toolkit needs to be restarted to apply the new theme. Directly clicking the "Light Mode" or "Dark Mode" buttons may not work as expected. We are working on fixing this in a future release.

Q: What is the format for manual parameters? --name value or --name=value?

A: Both are supported, but we recommend using --name value (space-separated). This is the most common and standard command-line format.

Q: When I run main.py, the program crashes with a DLL loading error. What should I do?

A: This is a known issue with the PyQt6 library in some environments. Run the following command in your command line (terminal). It will force a clean reinstallation of PyQt6 and usually resolves the problem:

python -m pip install --no-cache-dir --force-reinstall PyQt6 PyQt6-Qt6

Q: Why is the "Available Scripts" list empty when I start the program?

A: Please check and ensure that:

1. A folder named scripts exists.
2. The scripts folder is in the same directory as main.py.
3. There is at least one Python script file ending in .py inside the scripts folder.

Q: What if ui_texts.json is missing or corrupted?

A: The program will not start correctly or all UI text will be missing. Please make sure main.py and ui_texts.json are always in the same folder, and the JSON file is complete and valid.

Q: How can I make my task script interactive, for example, requiring the user to type "yes" midway?

A: Simply use the standard input() function in your script's code. For example:

user_confirmation = input("Are you sure you want to proceed? (yes/no): ")
if user_confirmation.lower() == 'yes':
    # ...continue execution...

When the script reaches this point, the GUI's "Enhanced Terminal" will automatically wait for the user's input.

---

Documentation last updated: 2025-09-08. Authored by @UltraAce258, written with Copilot.