内置工具参数手册

Nuphus 工具页 24 个内部机制命令。仅注册 invoke_handler，不注册为 agent 工具（LLM 不可经 execute_tool 调用）；用户经工具页手动使用。 本手册供 Agent 感知能力与引导用户，非用户文档。

能力总览（24）

分类	命令	输入 → 输出
PDF	pdf_merge	N 个 PDF → 1 个
PDF	pdf_compress	PDF → PDF（prune 未引用对象）
PDF	pdf_page_count	PDF → 页数
PDF	pdf_extract_text	PDF → 文本（逐页，默认上限 200 页）
PDF	pdf_images_to_pdf	N 图 → PDF（每图一页）
PDF	pdf_extract_pages	PDF+页码 → 新 PDF
PDF	pdf_rotate	PDF → PDF（90/180/270）
图像	image_compress	图→图（限宽高+质量）
图像	image_convert	图→图（按扩展名推断格式）
图像	image_resize	图→图（contain 保比例，不放大）
图像	image_info	图→宽高/大小/格式
图像	image_stitch	N 图→长图（horizontal/vertical）
图像	image_compress_batch	N 图→目录（原名-out.扩展名）
图像	image_convert_batch	N 图→目录（目标格式）
图像	image_resize_batch	N 图→目录（目标宽高 contain）
视频	video_compress	视频→视频（libx264 重编码）
视频	video_extract_frames	视频→目录（frame_%04d.jpg）
视频	video_info	视频→时长/编码/分辨率（ffprobe）
视频	video_to_gif	视频→GIF（palettegen+paletteuse）
视频	video_cut	视频→片段（-ss 快速 seek + -c copy）
音频	video_extract_audio	视频/音频→音频（wav/mp3）
音频	audio_convert	音频/视频→音频（mp3/wav/m4a/flac）
音频	voice_clone	参考音频+文本→克隆语音（走云端）
文档	doc_extract_text	docx/pptx/xls/ods/odt/odp/pdf→文本

关键参数

PDF（src-tauri/src/commands/tools/pdf.rs，lopdf）

• pdf_merge(input_paths: Vec<String>, output_path) — 多文件合并；输出扩展名必须 .pdf；单文件 ≤500MB
• pdf_compress(input_path, output_path) — 清理未引用对象后重写
• pdf_page_count(path) — 返回 pages
• pdf_extract_text(path, max_pages: Option<u32>) — 逐页 --- Page N --- 分隔
• pdf_images_to_pdf(input_paths, output_path) — 图片白名单 png/jpg/jpeg/bmp/gif/webp；单图像素 ≤5000 万
• pdf_extract_pages(input_path, pages: Vec<u32>, output_path) — 1-based，越界报错
• pdf_rotate(input_path, output_path, degrees: u32, pages: Option<Vec<u32>>) — degrees 仅 90/180/270

图像（image.rs，image crate）

• image_compress(input, output, max_width: Option<u32>, max_height: Option<u32>, quality: Option<u8>) — JPEG quality 默认 82；PNG Best+Adaptive
• image_convert(input, output) — 输出格式随扩展名（png/jpg/jpeg/bmp/gif/webp）
• image_resize(input, output, width: u32, height: u32) — contain，不放大
• image_info(path) — 宽高/大小/格式
• image_stitch(input_paths, output, direction: Option<String>) — horizontal 默认/vertical
• image_compress_batch(input_paths, output_dir, max_width?, max_height?, quality?) — 输出 原名-out.扩展名
• image_convert_batch(input_paths, output_dir, format: String) — 目标 png/jpg/jpeg/bmp/gif/webp；jpeg→jpg
• image_resize_batch(input_paths, output_dir, width: u32, height: u32) — contain 保比例，不放大；输出 原名-out.扩展名

视频（video.rs，ffmpeg）

• video_compress(input, output, quality: Option<String>) — low(1M/64k)/medium(2M/96k 默认)/high(4M/128k)
• video_extract_frames(input, output_dir, interval: Option<f64>) — 每 interval 秒一帧（0.001~3600）
• video_info(path) — ffprobe：duration_seconds(字符串)/codec/分辨率
• video_to_gif(input, output, fps: Option<f64>, scale: Option<u32>) — 输出必须 .gif；fps 默认 10(1-30)；scale 默认 480(16-2000)
• video_cut(input, output, start_sec: Option<f64>, end_sec: Option<f64>) — start 0~86400，end>start；流复制不重编码

音频（video.rs 音频部分 + voice.rs）

• video_extract_audio(input, output, format: Option<String>) — wav(pcm_s16le 44100 stereo)/默认 mp3(192k)
• audio_convert(input, output, bitrate: Option<String>) — 扩展名决定编码：mp3=libmp3lame/wav=pcm_s16le/m4a=aac/flac=flac；bitrate 如 "192k"（mp3/m4a 生效）
• voice_clone(reference_path, text, output_path) — 走云端：读 capabilities.voice（providers.toml [capabilities] voice=模型ID）→ OpenAI 兼容 POST {base_url}/audio/speech；未配置返回「模型界面 → 图像音频配置 → 语音克隆 配置」引导；参考音频格式 mp3/wav/m4a/flac/ogg/aac；克隆音色由所选模型/云端默认 voice 处理（参考音频暂作触发凭证）

文档（doc.rs）

• doc_extract_text(path) — 复用 office.rs read_office：docx/pptx/xls/ods/odt/odp/pdf

调用边界

• 命令全部 Result<serde_json::Value, String>，错误中文可读，不 panic
• 注册：src-tauri/src/main.rs invoke_handler（commands::tools::*）；模块 commands/tools.rs 声明 pub mod pdf/image/video/doc/voice
• 前端：ToolsPage.tsx（六分类：全部/图片/视频/文档/音频/PDF，20+3 信息卡=23 能力卡，映射 24 命令）+ lib/api.ts wrappers
• 语音克隆模型配置：模型界面 → 图像音频配置 → 语音克隆（capabilities.voice）
• 程序化执行：Rust 命令函数（内部代码/测试）或引擎二进制 nuphus-tools-rs/target/release/nuphus-{pdf,image,video}.exe（仅 merge/info/extract-text/compress 等子集）
• 引导用户：涉及 PDF/图像/视频/音频/文档处理 → 让用户打开工具页操作