JPEG XL 图像处理插件，为 LibACG 系统提供图像扫描和格式转换功能。

确保已安装 JPEG XL 工具链：

# Debian/Ubuntu
apt install libjxl-tools

# macOS
brew install jxl

本插件提供 2 个 Stage：

Stage	名称	功能	进度模式
scan	图像扫描	扫描指定路径下的图像文件	ALWAYS
convert	JPEG XL 转换	将图像转换为 JPEG XL 格式	BATCH

---

扫描指定目录或文件，查找支持的图像格式文件。

输入 (Input)

参数	类型	必填	说明
input_paths	list[str]	是	要扫描的路径列表（文件或目录）
params.path	str	否	扫描目录路径（input_paths 为空时使用）
params.recursive	bool	否	是否递归扫描子目录，默认 true
params.input_formats	list[str]	否	限定的格式列表，如 ["jpg", "png"]
params.max_count	int	否	返回文件数量上限

支持的输入格式

.jpg, .jpeg, .png, .gif, .bmp, .tiff, .tif, .webp, .ppm, .pgm, .pbm

输出 (Output)

字段	类型	说明
output_paths	list[str]	找到的图像文件路径列表
metadata.scanned_path	str	扫描的路径
metadata.found_count	int	找到的文件数量
metadata.recursive	bool	是否递归扫描
metadata.formats	list[str]	使用的格式过滤器

---

将图像文件批量转换为 JPEG XL 格式（使用 cjxl 命令）。

输入 (Input)

参数	类型	必填	说明
input_paths	list[str]	是	要转换的图像文件或目录路径
params.input_format	list[str]	否	限定的输入格式，如 ["jpg", "png"]
params.lossless	bool	否	无损压缩模式，默认 false
params.distance	float	否	距离压缩级别 (0-15)，默认 1，与 quality 互斥
params.quality	int	否	质量参数 (0-100)，与 distance 互斥
params.effort	int	否	压缩努力程度 1-10，默认 7
params.max_width	int	否	最大输出宽度（像素）
params.max_height	int	否	最大输出高度（像素）

支持的输入格式

.jpg, .jpeg, .png, .gif, .bmp, .tiff, .tif, .webp, .ppm, .pgm, .pbm

输出 (Output)

字段	类型	说明
output_paths	list[str]	转换后的 .jxl 文件路径列表
metadata.converted	int	成功转换的文件数量
metadata.total	int	总共要处理的文件数量
metadata.effort	int	使用的压缩努力程度
metadata.lossless	bool	是否使用无损模式

---

扫描指定目录下的所有图像文件：

name: scan-images
version: "1.0"

stages:
  - name: libjxl.scan
    input_paths:
      - "/path/to/images"
    params:
      recursive: true

只扫描 JPG 和 PNG 文件，最多返回 100 个：

name: scan-jpg-png
version: "1.0"

stages:
  - name: libjxl.scan
    input_paths:
      - "/path/to/images"
    params:
      recursive: true
      input_formats:
        - jpg
        - jpeg
        - png
      max_count: 100

将目录下的所有图像转换为 JPEG XL，使用 distance=1 的压缩级别：

name: convert-to-jxl
version: "1.0"

stages:
  - name: libjxl.convert
    input_paths:
      - "/path/to/images"
    params:
      distance: 1
      effort: 7

无损压缩转换：

name: convert-to-jxl-lossless
version: "1.0"

stages:
  - name: libjxl.convert
    input_paths:
      - "/path/to/images"
    params:
      lossless: true
      effort: 7

先扫描图像，再转换为 JPEG XL，并限制最大尺寸为 1920x1080：

name: scan-and-convert
version: "1.0"

stages:
  - name: libjxl.scan
    input_paths:
      - "/path/to/images"
    params:
      recursive: true
      input_formats:
        - jpg
        - png
        - webp

  - name: libjxl.convert
    input_paths_from: libjxl.scan
    params:
      distance: 2
      effort: 5
      max_width: 1920
      max_height: 1080

使用质量参数代替 distance：

name: convert-with-quality
version: "1.0"

stages:
  - name: libjxl.convert
    input_paths:
      - "/path/to/images"
    params:
      quality: 95
      effort: 7

---

当一个 Stage 的输出需要作为下一个 Stage 的输入时，可以使用 input_paths_from 字段指定数据来源：

stages:
  - name: libjxl.scan           # Stage 1: 扫描
    id: scan_step
    input_paths:
      - "/path/to/images"

  - name: libjxl.convert        # Stage 2: 转换 scan 的输出
    input_paths_from: scan_step # 使用上一步的 output_paths
    params:
      distance: 1