拓冰网站定制 
桌面应用【免费下载链接】czkawkaMulti functional app to find duplicates, empty folders, similar images etc.项目地址https://gitcode.com/GitHub_Trending/cz/czkawka点击查看免费下载本篇技术指南以czkawka_cli的架构文档czkawka_cli/CLAUDE.md为主体结合仓库源码逐层剖析这个薄 CLI 包装层的设计它如何用 4 个源文件承载 14 个扫描子命令如何在主线程与计算线程之间通过 crossbeam 通道协作以及如何将czkawka_core的扫描能力以可脚本化的方式暴露给终端。读完本文你将掌握 czkawka_cli 的完整调用链、全部共享参数与删除策略的语义、进度渲染与取消机制以及每种工具的典型命令行用法。一、定位与设计哲学薄壳与核心的边界czkawka_cli在 Czkawka 项目中扮演的角色非常明确它是一个围绕czkawka_core的薄 CLI 包装层thin CLI wrapper。它只负责四件事——参数解析argument parsing、线程编排thread orchestration、进度渲染progress rendering与结果输出result output所有扫描逻辑都驻留在czkawka_core中本 crate 只负责把核心能力接到终端上。这个边界体现在Cargo.toml的依赖声明中[dependencies] clap { version 4.5, features [derive, color] } log 0.4.22 czkawka_core { path ../czkawka_core, version 12.0.1, features [] } indicatif 0.18 crossbeam-channel { version 0.5, features [] } ctrlc { version 3.4, features [termination] } humansize 2.1依赖清单czkawka_cli/Cargo.toml中没有任何扫描算法相关的依赖——哈希、感知哈希、音频指纹等能力全部经由czkawka_core提供。从源码结构看main.rs中 14 个 dispatch 函数无一例外地遵循构造工具 → 设置公共参数 → 设置工具参数 → 调用search→ 收集输出的固定模式这正是薄壳设计的直接体现。源码布局czkawka_cli/src/ ├── main.rs # Entry point, thread spawning, tool dispatchers ├── commands.rs # All clap CLI argument definitions ├── parsers.rs # parse_* clap value-parser functions used by commands.rs └── progress.rs # indicatif progress bar rendering四个文件职责高度单一见 czkawka_cli/src/main.rs、czkawka_cli/src/commands.rs、czkawka_cli/src/parsers.rs、czkawka_cli/src/progress.rscommands.rs只做 clap 声明parsers.rs只做值校验progress.rs只做渲染main.rs负责串联。二、执行模型双线程 通道 原子取消标志main()的执行流程可以精确还原为如下调用链源码位于 czkawka_cli/src/main.rs#L53-L117main() ├─ 注册图像解码钩子 register_image_decoding_hooks() ├─ 解析参数 (clap) → Args::parse().command ├─ 设置缓存路径 set_config_cache_path(Czkawka, Czkawka) ├─ 初始化日志 setup_logger(...)打印版本信息 print_version_mode(Czkawka cli) ├─ 创建 crossbeam 无界通道 (SenderProgressData, ReceiverProgressData) ├─ 创建 ArcAtomicBool stop_flag初值 false ├─ spawn calculation_thread指定 DEFAULT_THREAD_SIZE 栈大小 │ └─ match command → 分发到 14 个工具函数之一 ├─ 注册 CtrlC 处理器 → stop_flag.store(true, SeqCst) ├─ connect_progress(progress_receiver) [阻塞渲染进度条] └─ join calculation_thread → 打印输出 → 找到条目则 exit(11)否则 exit(0)这里有两个值得注意的并发设计点职责分置主线程main thread专职渲染进度计算线程calculation thread专职跑扫描。progress_receiver.recv()在发送端sender被 drop——即扫描结束时——自然返回因此进度渲染循环不需要额外的终止信号。无界通道避免死锁通道使用crossbeam_channel::unbounded()czkawka_cli/src/main.rs#L70进度消息的发送不会因接收端阻塞而卡住扫描线程。另外main()入口处调用了Args::command().debug_assert()仅 debug 构建这是 clap derive 的静态自检确保所有参数定义在开发阶段就符合 clap 的约束。三、14 个 CLI 子命令别名与用途总览顶层枚举Commands定义在 czkawka_cli/src/commands.rs#L61-L139共有 14 个变体覆盖 Czkawka 全部扫描能力子命令别名用途Duplicatesdup查找重复文件按哈希/名称/大小EmptyFoldersempty-folders查找空目录BiggestFilesbig查找最大或最小文件EmptyFilesempty-files查找零字节文件Temporarytemp查找临时文件SimilarImagesimage查找相似图片感知哈希SameMusicmusic查找重复音乐标签/指纹InvalidSymlinkssymlinks查找损坏的符号链接BrokenFilesbroken查找损坏的 PDF/音频/图片/压缩包SimilarVideosvideo查找相似视频帧哈希BadExtensionsext查找扩展名错误的文件BadNamesbad-names查找有问题的文件名VideoOptimizervideo-optimizer转码或裁剪视频ExifRemoverexif-remover移除图片 EXIF 元数据每个子命令的after_help中都内置了一个可直接运行的示例czkawka_cli/src/commands.rs#L61-L139例如czkawka dup -d /home/rafal -e /home/rafal/Obrazy -m 25 -x 7z rar IMAGE -s hash -f results.txt -D aeo要查看任意工具的全部参数运行czkawka_cli --help获取总览或czkawka_cli dup --help查看单个工具的详细帮助。四、CommonCliItems所有子命令共享的公共参数CommonCliItems通过#[clap(flatten)]注入每个子命令czkawka_cli/src/commands.rs#L918-L1003是使用 CLI 必须掌握的第一组参数参数说明-d待扫描目录必填可多个-e排除的目录绝对路径文件将被完全忽略-E排除的条目glob 模式如*/.*支持宏DEFAULT和$TRASH-x允许的扩展名支持宏IMAGEjpg,kra,gif,png,bmp,tiff,hdr,svg、TEXTtxt,doc,docx,odt,rtf、VIDEOmp4,flv,mkv,webm,vob,ogv,gifv,avi,mov,wmv,mpg,m4v,m4p,mpeg,3gp,m2ts、MUSICmp3,flac,ogg,opus,tta,wma,webm-P排除的扩展名-R禁止递归搜索只扫描顶层目录-X仅 Unix排除其他文件系统避免扫到挂载盘、网络共享-f将结果保存为格式化文本文件-C将结果保存为紧凑 JSON 文件-p--pretty-file-to-save将结果保存为美化 JSON 文件-N/-M分别抑制结果/消息输出到控制台-W找到条目时不返回非零退出码-T线程数0 全部 CPU-H禁用缓存几个值得展开的细节-E与-e的性能差异-E使用通配符匹配可能较慢官方注释明确建议能用-e排除目录就用-e。-x宏展开宏在 czkawka_core/src/common/extensions.rs 中定义并校验set_common_settings通过set_allowed_extensions把它们交给核心层。-T的线程控制set_common_settings第一行调用set_number_of_threads(common_cli_items.thread_number)czkawka_cli/src/main.rs#L6870 值表示使用全部可用 CPU 线程。-H禁用缓存对应set_use_cache(!common_cli_items.disable_cache)关闭后扫描变慢但保证结果完全新鲜。参考目录Reference Directories-r--reference-directories是一个容易被忽略但非常实用的参数czkawka_cli/src/commands.rs#L1083-L1092目录中的文件作为结果中的参考条目只报告与参考文件匹配的非参考文件参考目录内独有的文件不会列出。它适用于以 A 库为准找出 B 库中与之重复的文件这类场景且只有部分工具如dup、image、music、video支持底层通过set_reference_paths注入。五、删除方法DMethod 与 SDMethod 两套策略CLI 按工具类型提供两套删除语义定义在 czkawka_cli/src/commands.rs#L1023-L1069DMethod面向相似分组类工具用于dup、image、music、video这类把结果分成组的工具-D接受如下取值取值语义NONE不删除默认AEN保留最新All Except NewestAEO保留最旧All Except OldestON只删除最新Only NewestOO只删除最旧Only OldestAEB保留最大All Except BiggestAES保留最小All Except SmallestOB只删除最大Only BiggestOS只删除最小Only SmallestHARD不删除改为创建硬链接以节省空间配套参数-Q--dry-run只预览将执行的操作而不真正执行-y--move-to-trash删除到系统回收站而非永久删除。set_advanced_deleteczkawka_cli/src/main.rs#L674-L681把这三个参数落到DeleteMethod枚举与dry_run/move_to_trash标志上。SDMethod面向简单清单类工具用于empty-folders、big、empty-files、temp、symlinks、broken、bad-names这类结果不分组、要么全删要么不删的工具-D删除所有找到的条目-Q干跑预览-y移动到回收站其实现set_simple_deleteczkawka_cli/src/main.rs#L663-L672在-D时把删除方法置为DeleteMethod::Delete定义于 czkawka_core/src/common/tool_data.rs#L38-L52。安全提示-Q干跑模式在两类删除策略中都可与-D组合使用是批量清理前验证行为的标准做法。六、工具分发模式14 个函数的统一骨架main.rs中 14 个 dispatch 函数duplicates、empty_folders、biggest_files、empty_files、temporary、similar_images、same_music、invalid_symlinks、broken_files、similar_videos、bad_extensions、bad_names、video_optimizer、exif_remover遵循完全相同的结构fn tool_name(args: ToolArgs, stop_flag: ArcAtomicBool, progress_sender: SenderProgressData) - CliOutput { // 1. 解构参数 // 2. 构建工具专属参数结构体 let mut tool ToolType::new(params); // 3. 应用公共设置路径、扩展名、缓存、线程数 set_common_settings(mut tool, common_cli_items, reference_directories); // 4. 应用工具专属设置文件大小范围、删除方法等 // 5. 运行扫描 tool.search(stop_flag, Some(progress_sender)); // 6. 可选地执行修复操作重命名/删除/转码等 // 7. 收集并返回输出 save_and_write_results_to_writer(tool, common_cli_items) }set_common_settingsczkawka_cli/src/main.rs#L683-L704通过AllTraits约束定义于 czkawka_core/src/common/traits.rs#L139统一应用线程数、包含/排除路径、排除条目、递归开关、-X跨文件系统排除、允许/排除扩展名、缓存开关。tool.search(stop_flag, Some(progress_sender))调用的是Searchtrait 的search方法czkawka_core/src/common/traits.rs#L135-L137核心层在扫描中主动轮询stop_flag并经由 sender 推送ProgressData。三类工具的差异化细节纯扫描型如empty_folders、invalid_symlinks只执行search后直接输出。扫描 修复型bad_extensions-F修正扩展名、bad_names-F自动改名、exif_remover-F移除 EXIF、video_optimizer-F执行转码/裁剪在search之后调用FixingItems::fix_itemsczkawka_core/src/common/traits.rs#L123-L127。以exif_remover为例其修复参数ExifTagsFixerParams { override_file }决定是覆盖原文件还是生成photo.czkawka_cleaned_exif.jpg式副本。嵌套子命令型video_optimizer内部再分transcode与crop两个子命令czkawka_cli/src/commands.rs#L704-L710main.rs中video_optimizer函数按mode分别构建VideoTranscode或VideoCrop参数。七、工具专属参数精选默认值与取值范围结合 czkawka_cli/src/commands.rs 与 czkawka_cli/src/parsers.rs 的校验逻辑以下是最常用工具的关键参数dup重复文件-m--minimal-file-size最小字节数默认8192-i--maximal-file-size默认u64::MAX。validate_file_sizes会在最大值小于最小值时打印警告czkawka_cli/src/commands.rs#L1190-L1194。-s--search-methodNAME最快但很少用、SIZE按大小、SIZE_NAME大小名称、HASH最慢但最准确默认。-t--hash-typeBLAKE3默认推荐、CRC32更快但不可靠、XXH3非常快但非加密安全。-c--minimal-cached-file-size哈希缓存的最小文件字节数默认257144-Z--minimal-prehash-cache-file-size与-u--use-prehash-cache控制预哈希缓存。-l--case-sensitive-name-comparison区分大小写比较名称默认不区分。-L--allow-hard-links把硬链接当作独立文件默认隐藏硬链接。image相似图片-s--max-difference0–40默认5哈希尺寸 8 时建议 ≤1016 时建议 ≤20。-g--hash-algMean、Gradient默认、Blockhash、VertGradient、DoubleGradient、Median。-z--image-filter缩放滤镜Lanczos3、Nearest默认、Triangle、Gaussian、CatmullRom。-c--hash-size仅允许 8/16/32/64默认 16校验见 czkawka_cli/src/parsers.rs#L285-L294。--geometric-invarianceoff默认、mirror-flip、mirror-flip-rotate90。-J/-Z忽略同尺寸 / 同分辨率的条目。music重复音乐-s--search-methodTAGS默认按标签或CONTENT按音频内容指纹。-z--music-similarity逗号分隔的标签组合默认track_title,track_artist可含year,bitrate,genre,length。-a--approximate-comparison标签近似比较-l--minimum-segment-duration默认10.0秒-Y--maximum-difference范围 (0, 10.0]默认2.0。--compare-fingerprints-only-with-similar-titles内容比较时仅对比标题相似的文件以减少误报。broken损坏文件-t--checking-types默认全部检查视频除外可组合PDF、AUDIO、IMAGE、ARCHIVEzip,7z,gz,tar,zst,bz2,xz、FONTttf,otf,ttc、MARKUPJSON/XML/TOML/YAML/SVG、VIDEO_FFPROBE快速头部校验、VIDEO_FFMPEG完整解码需 ffmpeg。video相似视频-t--tolerance0–20默认 10-U--skip-forward-amount默认 15 秒。--window-count1–20、--duration-tolerance-pct、--min-matching-windows、--subclip-min-match控制时序窗口匹配精度。-A--scan-duration秒默认 10仅允许预定义集合中的值。--check-audio-content等一组--audio-*参数启用音频指纹比较官方注释明确警告非常耗费资源会显著拖慢扫描。--generate-thumbnails系列CLI 生成的缩略图可预填充缓存供 krokiet/cedinia GUI 后续使用。bad-names问题文件名-u大写扩展名、-jemoji、-w首尾空格、-n非 ASCII 图形字符、-r受限字符集白名单如_- .、-a重复的非字母数字字符如file__name、-F自动改名。注意restricted_charset会被去重排序后作为允许字符集。video-optimizer视频优化transcode子命令-c排除的编码器默认排除 hevc/h265/av1/vp9、--target-codech264/h265/av1/vp9默认 h265、--quality0–51默认 23av1/vp9 建议 30、--fail-if-not-s smaller、--overwrite-original、--noise-reductionnone/hqdn3d、--custom-ffmpeg-command。crop子命令-mblackbars或staticcontent默认 blackbars、-k黑像素阈值 0–128默认 32、-b黑条最小占比 50–100%默认 90、-s采样帧数 5–1000默认 20、-z最小裁剪尺寸 1–1000默认 10。exif-removerEXIF 移除-i--ignored-tags逗号分隔的保留标签如Orientation,DateTime,Software-F实际移除-o--override-file覆盖原文件否则生成带czkawka_cleaned_exif标记的副本。八、进度渲染indicatif 的双模式渲染connect_progressczkawka_cli/src/progress.rs#L7-L34在主线程中循环调用progress_receiver.recv()对每条ProgressData消息按阶段切换渲染方式Spinner不确定模式文件收集、缓存加载/保存等阶段stage.is_indeterminate()为 true 时显示旋转动画czkawka_cli/src/progress.rs#L36-L46。线性进度条[ ]一旦总条目数或总字节数已知如PreHashing、FullHashing显示{msg} [{bar}]模板的确定进度条czkawka_cli/src/progress.rs#L48-L56。阶段标签如 Calculating hashes、Reading tags来自每条ProgressData消息上的ToolStage枚举。ToolStage在 czkawka_core/src/common/progress_data.rs#L80-L103 中定义涵盖收集文件、收集目录、删除、重命名、移动、硬链接、符号链接、优化视频、清理 EXIF 等通用阶段以及各工具专属阶段如Duplicate的 HidingHardLinks → LoadingPreHashCache → PreHashing → SavingPreHashCache → LoadingHashCache → FullHashing → SavingHashCache 七步流水线。ProgressData的to_display()方法czkawka_core/src/common/progress_data.rs#L333-L347把阶段序号换算成 0–99 的整体进度百分比标签文本通过 Fluent 本地化flc!宏生成并内嵌实时计数例如 Analyzed partial hash of 50/100 files (1 MiB / 4 MiB)——这正是 CLI 进度条消息的直接来源。九、结果输出与退出码约定save_and_write_results_to_writerczkawka_cli/src/main.rs#L618-L661统一处理三种可选文件输出与 stdout 缓冲文本格式-f调用print_results_to_file生成人类可读的格式化文本。紧凑 JSON-Csave_results_to_file_as_json(file, false)无多余空白。美化 JSON-psave_results_to_file_as_json(file, true)缩进排版适合程序后续解析。底层的PrintResultstrait 实现位于 czkawka_core/src/common/traits.rs#L19-L116write_base_search_paths会在结果头部写出扫描的包含/排除/参考路径及排除条目JSON 输出由serde_json::to_writer/to_writer_pretty完成。stdout 输出结果 消息先写入BufWriterVecu8缓冲在计算线程 join 之后统一打印避免与进度条渲染竞争终端。退出码约定是 CLI 脚本化的关键找到条目且未设置-W→exit(11)其他情况 →exit(0)。CliOutput结构体czkawka_cli/src/main.rs#L46-L51携带found_any_files、ignored_error_code_on_found与output三个字段-W--ignore-error-code-on-found即脚本需要无论是否找到都继续执行时的开关。十、取消机制ArcAtomicBool 的协作式停止取消通过ArcAtomicBoolSeqCst内存序在 CtrlC 信号处理器与计算线程之间共享czkawka_cli/src/main.rs#L94-L101ctrlc::set_handler(move || { if store_flag_cloned.load(std::sync::atomic::Ordering::SeqCst) { return; // 已在停止中忽略重复信号 } info!(Got CtrlC signal, stopping...); store_flag_cloned.store(true, std::sync::atomic::Ordering::SeqCst); })czkawka_core中的各工具在扫描期间轮询该标志检测为true后优雅停止在下一批条目边界处退出而非中断正在进行的哈希计算。这一机制对所有 14 个子命令统一生效因为 dispatch 函数都通过Search::search(stop_flag, ...)把同一标志传入核心层。十一、关键依赖与可选特性依赖一览Crate用途clap4.5CLI 解析derive APIcolor特性启用彩色帮助文本indicatif0.18进度条渲染crossbeam-channel进度消息的无界通道ctrlc3.4SIGINT / CtrlC 处理humansize2.1人类可读字节大小格式化进度标签中显示 MiB 等czkawka_core全部扫描逻辑可选特性转发给 czkawka_core特性说明依赖heifHEIF/HEIC 图片支持libheiflibrawRAW 图片支持librawlibavifAVIF 图片支持libavifxdg_portal_trashFlatPak 兼容的回收站XDG portal—no_colors禁用 clap 彩色帮助输出—编译时启用cargo run --release --bin czkawka_cli --features heif,libraw,libavif示例见 czkawka_cli/README.md。按运行时依赖区分similar_videos工具需要安装 ffmpegheif/libraw/libavif同时是构建依赖与运行时依赖且官方 README 注明在 Windows 上难以配置、预编译二进制默认不包含。十二、构建、帮助与综合示例# 基础编译 cargo run --release --bin czkawka_cli # 启用图像格式扩展 cargo run --release --bin czkawka_cli --features heif,libraw,libavif--help与各子命令的--help均来自 clap 派生声明帮助模板HELP_TEMPLATE内置了全部 14 个工具的执行示例czkawka_cli/src/commands.rs#L1196-L1224以下为从源码整理的可直接运行的完整用法czkawka dup -d /home/rafal -e /home/rafal/Obrazy -m 25 -x 7z rar IMAGE -s hash -f results.txt -D aeo czkawka empty-folders -d /home/rafal/rr /home/gateway -f results.txt czkawka big -d /home/rafal/ /home/piszczal -e /home/rafal/Roman -n 25 -x VIDEO -f results.txt czkawka empty-files -d /home/rafal /home/szczekacz -e /home/rafal/Pulpit -R -f results.txt czkawka temp -d /home/rafal/ -E */.git */tmp* *Pulpit -f results.txt -D czkawka image -d /home/rafal -e /home/rafal/Pulpit -f results.txt czkawka music -d /home/rafal -e /home/rafal/Pulpit -z track_artist,year,track_title -f results.txt czkawka symlinks -d /home/kicikici/ /home/szczek -e /home/kicikici/jestempsem -x jpg -f results.txt czkawka broken -d /home/mikrut/ -e /home/mikrut/trakt -f results.txt czkawka ext -d /home/mikrut/ -e /home/mikrut/trakt -f results.txt czkawka bad-names -d /home/rafal -u -j -w -n -f results.txt czkawka video-optimizer -d /home/rafal transcode -c h264 -f results.txt czkawka video-optimizer -d /home/rafal crop -m blackbars -f results.txt czkawka exif-remover -d /home/rafal -x IMAGE -f results.txt十三、注释规范与代码维护约定架构文档最后给出注释约定注释应短小精炼遵循仓库根目录 AGENTS.md 的规范只在代码行为无法从阅读本身推断时添加如非显而易见的约束、workaround、跨模块耦合绝不重复代码已表达的内容。这一点在main.rs中体现得很明显——例如HardwareEncoder::None处的TODO - missing hardware encoder注释只标记了一个真实的未实现约束而不是解释显而易见的逻辑。结语从架构图到实战回顾全文czkawka_cli 的设计精髓可以概括为三点薄壳分层扫描逻辑全在核心CLI 只做接线、固定分发骨架14 个工具共享同一套构造 → 配置 → 搜索 → 输出流水线、脚本友好exit(11)退出码 -W开关 三种结果格式。结合 czkawka_cli/src/main.rs 与 czkawka_cli/src/commands.rs 阅读本文你既可以把每个参数精确映射到实现也可以把整套执行模型迁移到自己的工具链中——例如模仿双线程 通道 原子标志的模式为自己的 CLI 增加可取消扫描与进度上报能力。赞分享桌面应用【免费下载链接】czkawkaMulti functional app to find duplicates, empty folders, similar images etc.项目地址https://gitcode.com/GitHub_Trending/cz/czkawka点击查看免费下载相关推荐stitch-skills UI/UX关键词速查表Stitch优化词汇库完整指南stitch skills UI/UX关键词速查表Stitch优化词汇库完整指南 stitch skills 是配合 Google Stitch MCP 服务AI 技能AI 插件OpenTofu架构深度解析从命令行到资源编排OpenTofu架构深度解析从命令行到资源编排 本文深入解析了OpenTofu的完整架构体系从CLI命令处理、配置加载与模块管理、状态管理与数据持久化到图云原生DevOps基础设施Open3D 3D Gaussian Splatting 渲染深度解析Vulkan/Metal 计算管线、深度合成与架构设计Open3D 3D Gaussian Splatting 渲染深度解析Vulkan/Metal 计算管线、深度合成与架构设计 Open3D 通过一条与 Fil计算机视觉图形学3D渲染科学计算上一篇最全面的TDengine跨版本升级指南从数据迁移到兼容性处理的实战策略下一篇解决javascript-obfuscator使用难题从入门到精通的实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 czkawka_cli 架构深度解析：Czkawka 命令行前端的参数解析、线程编排与进度渲染设计
桌面应用【免费下载链接】czkawkaMulti functional app to find duplicates, empty folders, similar images etc.项目地址https://gitcode.com/GitHub_Trending/cz/czkawka点击查看免费下载本篇技术指南以czkawka_cli的架构文档czkawka_cli/CLAUDE.md为主体结合仓库源码逐层剖析这个薄 CLI 包装层的设计它如何用 4 个源文件承载 14 个扫描子命令如何在主线程与计算线程之间通过 crossbeam 通道协作以及如何将czkawka_core的扫描能力以可脚本化的方式暴露给终端。读完本文你将掌握 czkawka_cli 的完整调用链、全部共享参数与删除策略的语义、进度渲染与取消机制以及每种工具的典型命令行用法。一、定位与设计哲学薄壳与核心的边界czkawka_cli在 Czkawka 项目中扮演的角色非常明确它是一个围绕czkawka_core的薄 CLI 包装层thin CLI wrapper。它只负责四件事——参数解析argument parsing、线程编排thread orchestration、进度渲染progress rendering与结果输出result output所有扫描逻辑都驻留在czkawka_core中本 crate 只负责把核心能力接到终端上。这个边界体现在Cargo.toml的依赖声明中[dependencies] clap { version 4.5, features [derive, color] } log 0.4.22 czkawka_core { path ../czkawka_core, version 12.0.1, features [] } indicatif 0.18 crossbeam-channel { version 0.5, features [] } ctrlc { version 3.4, features [termination] } humansize 2.1依赖清单czkawka_cli/Cargo.toml中没有任何扫描算法相关的依赖——哈希、感知哈希、音频指纹等能力全部经由czkawka_core提供。从源码结构看main.rs中 14 个 dispatch 函数无一例外地遵循构造工具 → 设置公共参数 → 设置工具参数 → 调用search→ 收集输出的固定模式这正是薄壳设计的直接体现。源码布局czkawka_cli/src/ ├── main.rs # Entry point, thread spawning, tool dispatchers ├── commands.rs # All clap CLI argument definitions ├── parsers.rs # parse_* clap value-parser functions used by commands.rs └── progress.rs # indicatif progress bar rendering四个文件职责高度单一见 czkawka_cli/src/main.rs、czkawka_cli/src/commands.rs、czkawka_cli/src/parsers.rs、czkawka_cli/src/progress.rscommands.rs只做 clap 声明parsers.rs只做值校验progress.rs只做渲染main.rs负责串联。二、执行模型双线程 通道 原子取消标志main()的执行流程可以精确还原为如下调用链源码位于 czkawka_cli/src/main.rs#L53-L117main() ├─ 注册图像解码钩子 register_image_decoding_hooks() ├─ 解析参数 (clap) → Args::parse().command ├─ 设置缓存路径 set_config_cache_path(Czkawka, Czkawka) ├─ 初始化日志 setup_logger(...)打印版本信息 print_version_mode(Czkawka cli) ├─ 创建 crossbeam 无界通道 (SenderProgressData, ReceiverProgressData) ├─ 创建 ArcAtomicBool stop_flag初值 false ├─ spawn calculation_thread指定 DEFAULT_THREAD_SIZE 栈大小 │ └─ match command → 分发到 14 个工具函数之一 ├─ 注册 CtrlC 处理器 → stop_flag.store(true, SeqCst) ├─ connect_progress(progress_receiver) [阻塞渲染进度条] └─ join calculation_thread → 打印输出 → 找到条目则 exit(11)否则 exit(0)这里有两个值得注意的并发设计点职责分置主线程main thread专职渲染进度计算线程calculation thread专职跑扫描。progress_receiver.recv()在发送端sender被 drop——即扫描结束时——自然返回因此进度渲染循环不需要额外的终止信号。无界通道避免死锁通道使用crossbeam_channel::unbounded()czkawka_cli/src/main.rs#L70进度消息的发送不会因接收端阻塞而卡住扫描线程。另外main()入口处调用了Args::command().debug_assert()仅 debug 构建这是 clap derive 的静态自检确保所有参数定义在开发阶段就符合 clap 的约束。三、14 个 CLI 子命令别名与用途总览顶层枚举Commands定义在 czkawka_cli/src/commands.rs#L61-L139共有 14 个变体覆盖 Czkawka 全部扫描能力子命令别名用途Duplicatesdup查找重复文件按哈希/名称/大小EmptyFoldersempty-folders查找空目录BiggestFilesbig查找最大或最小文件EmptyFilesempty-files查找零字节文件Temporarytemp查找临时文件SimilarImagesimage查找相似图片感知哈希SameMusicmusic查找重复音乐标签/指纹InvalidSymlinkssymlinks查找损坏的符号链接BrokenFilesbroken查找损坏的 PDF/音频/图片/压缩包SimilarVideosvideo查找相似视频帧哈希BadExtensionsext查找扩展名错误的文件BadNamesbad-names查找有问题的文件名VideoOptimizervideo-optimizer转码或裁剪视频ExifRemoverexif-remover移除图片 EXIF 元数据每个子命令的after_help中都内置了一个可直接运行的示例czkawka_cli/src/commands.rs#L61-L139例如czkawka dup -d /home/rafal -e /home/rafal/Obrazy -m 25 -x 7z rar IMAGE -s hash -f results.txt -D aeo要查看任意工具的全部参数运行czkawka_cli --help获取总览或czkawka_cli dup --help查看单个工具的详细帮助。四、CommonCliItems所有子命令共享的公共参数CommonCliItems通过#[clap(flatten)]注入每个子命令czkawka_cli/src/commands.rs#L918-L1003是使用 CLI 必须掌握的第一组参数参数说明-d待扫描目录必填可多个-e排除的目录绝对路径文件将被完全忽略-E排除的条目glob 模式如*/.*支持宏DEFAULT和$TRASH-x允许的扩展名支持宏IMAGEjpg,kra,gif,png,bmp,tiff,hdr,svg、TEXTtxt,doc,docx,odt,rtf、VIDEOmp4,flv,mkv,webm,vob,ogv,gifv,avi,mov,wmv,mpg,m4v,m4p,mpeg,3gp,m2ts、MUSICmp3,flac,ogg,opus,tta,wma,webm-P排除的扩展名-R禁止递归搜索只扫描顶层目录-X仅 Unix排除其他文件系统避免扫到挂载盘、网络共享-f将结果保存为格式化文本文件-C将结果保存为紧凑 JSON 文件-p--pretty-file-to-save将结果保存为美化 JSON 文件-N/-M分别抑制结果/消息输出到控制台-W找到条目时不返回非零退出码-T线程数0 全部 CPU-H禁用缓存几个值得展开的细节-E与-e的性能差异-E使用通配符匹配可能较慢官方注释明确建议能用-e排除目录就用-e。-x宏展开宏在 czkawka_core/src/common/extensions.rs 中定义并校验set_common_settings通过set_allowed_extensions把它们交给核心层。-T的线程控制set_common_settings第一行调用set_number_of_threads(common_cli_items.thread_number)czkawka_cli/src/main.rs#L6870 值表示使用全部可用 CPU 线程。-H禁用缓存对应set_use_cache(!common_cli_items.disable_cache)关闭后扫描变慢但保证结果完全新鲜。参考目录Reference Directories-r--reference-directories是一个容易被忽略但非常实用的参数czkawka_cli/src/commands.rs#L1083-L1092目录中的文件作为结果中的参考条目只报告与参考文件匹配的非参考文件参考目录内独有的文件不会列出。它适用于以 A 库为准找出 B 库中与之重复的文件这类场景且只有部分工具如dup、image、music、video支持底层通过set_reference_paths注入。五、删除方法DMethod 与 SDMethod 两套策略CLI 按工具类型提供两套删除语义定义在 czkawka_cli/src/commands.rs#L1023-L1069DMethod面向相似分组类工具用于dup、image、music、video这类把结果分成组的工具-D接受如下取值取值语义NONE不删除默认AEN保留最新All Except NewestAEO保留最旧All Except OldestON只删除最新Only NewestOO只删除最旧Only OldestAEB保留最大All Except BiggestAES保留最小All Except SmallestOB只删除最大Only BiggestOS只删除最小Only SmallestHARD不删除改为创建硬链接以节省空间配套参数-Q--dry-run只预览将执行的操作而不真正执行-y--move-to-trash删除到系统回收站而非永久删除。set_advanced_deleteczkawka_cli/src/main.rs#L674-L681把这三个参数落到DeleteMethod枚举与dry_run/move_to_trash标志上。SDMethod面向简单清单类工具用于empty-folders、big、empty-files、temp、symlinks、broken、bad-names这类结果不分组、要么全删要么不删的工具-D删除所有找到的条目-Q干跑预览-y移动到回收站其实现set_simple_deleteczkawka_cli/src/main.rs#L663-L672在-D时把删除方法置为DeleteMethod::Delete定义于 czkawka_core/src/common/tool_data.rs#L38-L52。安全提示-Q干跑模式在两类删除策略中都可与-D组合使用是批量清理前验证行为的标准做法。六、工具分发模式14 个函数的统一骨架main.rs中 14 个 dispatch 函数duplicates、empty_folders、biggest_files、empty_files、temporary、similar_images、same_music、invalid_symlinks、broken_files、similar_videos、bad_extensions、bad_names、video_optimizer、exif_remover遵循完全相同的结构fn tool_name(args: ToolArgs, stop_flag: ArcAtomicBool, progress_sender: SenderProgressData) - CliOutput { // 1. 解构参数 // 2. 构建工具专属参数结构体 let mut tool ToolType::new(params); // 3. 应用公共设置路径、扩展名、缓存、线程数 set_common_settings(mut tool, common_cli_items, reference_directories); // 4. 应用工具专属设置文件大小范围、删除方法等 // 5. 运行扫描 tool.search(stop_flag, Some(progress_sender)); // 6. 可选地执行修复操作重命名/删除/转码等 // 7. 收集并返回输出 save_and_write_results_to_writer(tool, common_cli_items) }set_common_settingsczkawka_cli/src/main.rs#L683-L704通过AllTraits约束定义于 czkawka_core/src/common/traits.rs#L139统一应用线程数、包含/排除路径、排除条目、递归开关、-X跨文件系统排除、允许/排除扩展名、缓存开关。tool.search(stop_flag, Some(progress_sender))调用的是Searchtrait 的search方法czkawka_core/src/common/traits.rs#L135-L137核心层在扫描中主动轮询stop_flag并经由 sender 推送ProgressData。三类工具的差异化细节纯扫描型如empty_folders、invalid_symlinks只执行search后直接输出。扫描 修复型bad_extensions-F修正扩展名、bad_names-F自动改名、exif_remover-F移除 EXIF、video_optimizer-F执行转码/裁剪在search之后调用FixingItems::fix_itemsczkawka_core/src/common/traits.rs#L123-L127。以exif_remover为例其修复参数ExifTagsFixerParams { override_file }决定是覆盖原文件还是生成photo.czkawka_cleaned_exif.jpg式副本。嵌套子命令型video_optimizer内部再分transcode与crop两个子命令czkawka_cli/src/commands.rs#L704-L710main.rs中video_optimizer函数按mode分别构建VideoTranscode或VideoCrop参数。七、工具专属参数精选默认值与取值范围结合 czkawka_cli/src/commands.rs 与 czkawka_cli/src/parsers.rs 的校验逻辑以下是最常用工具的关键参数dup重复文件-m--minimal-file-size最小字节数默认8192-i--maximal-file-size默认u64::MAX。validate_file_sizes会在最大值小于最小值时打印警告czkawka_cli/src/commands.rs#L1190-L1194。-s--search-methodNAME最快但很少用、SIZE按大小、SIZE_NAME大小名称、HASH最慢但最准确默认。-t--hash-typeBLAKE3默认推荐、CRC32更快但不可靠、XXH3非常快但非加密安全。-c--minimal-cached-file-size哈希缓存的最小文件字节数默认257144-Z--minimal-prehash-cache-file-size与-u--use-prehash-cache控制预哈希缓存。-l--case-sensitive-name-comparison区分大小写比较名称默认不区分。-L--allow-hard-links把硬链接当作独立文件默认隐藏硬链接。image相似图片-s--max-difference0–40默认5哈希尺寸 8 时建议 ≤1016 时建议 ≤20。-g--hash-algMean、Gradient默认、Blockhash、VertGradient、DoubleGradient、Median。-z--image-filter缩放滤镜Lanczos3、Nearest默认、Triangle、Gaussian、CatmullRom。-c--hash-size仅允许 8/16/32/64默认 16校验见 czkawka_cli/src/parsers.rs#L285-L294。--geometric-invarianceoff默认、mirror-flip、mirror-flip-rotate90。-J/-Z忽略同尺寸 / 同分辨率的条目。music重复音乐-s--search-methodTAGS默认按标签或CONTENT按音频内容指纹。-z--music-similarity逗号分隔的标签组合默认track_title,track_artist可含year,bitrate,genre,length。-a--approximate-comparison标签近似比较-l--minimum-segment-duration默认10.0秒-Y--maximum-difference范围 (0, 10.0]默认2.0。--compare-fingerprints-only-with-similar-titles内容比较时仅对比标题相似的文件以减少误报。broken损坏文件-t--checking-types默认全部检查视频除外可组合PDF、AUDIO、IMAGE、ARCHIVEzip,7z,gz,tar,zst,bz2,xz、FONTttf,otf,ttc、MARKUPJSON/XML/TOML/YAML/SVG、VIDEO_FFPROBE快速头部校验、VIDEO_FFMPEG完整解码需 ffmpeg。video相似视频-t--tolerance0–20默认 10-U--skip-forward-amount默认 15 秒。--window-count1–20、--duration-tolerance-pct、--min-matching-windows、--subclip-min-match控制时序窗口匹配精度。-A--scan-duration秒默认 10仅允许预定义集合中的值。--check-audio-content等一组--audio-*参数启用音频指纹比较官方注释明确警告非常耗费资源会显著拖慢扫描。--generate-thumbnails系列CLI 生成的缩略图可预填充缓存供 krokiet/cedinia GUI 后续使用。bad-names问题文件名-u大写扩展名、-jemoji、-w首尾空格、-n非 ASCII 图形字符、-r受限字符集白名单如_- .、-a重复的非字母数字字符如file__name、-F自动改名。注意restricted_charset会被去重排序后作为允许字符集。video-optimizer视频优化transcode子命令-c排除的编码器默认排除 hevc/h265/av1/vp9、--target-codech264/h265/av1/vp9默认 h265、--quality0–51默认 23av1/vp9 建议 30、--fail-if-not-s smaller、--overwrite-original、--noise-reductionnone/hqdn3d、--custom-ffmpeg-command。crop子命令-mblackbars或staticcontent默认 blackbars、-k黑像素阈值 0–128默认 32、-b黑条最小占比 50–100%默认 90、-s采样帧数 5–1000默认 20、-z最小裁剪尺寸 1–1000默认 10。exif-removerEXIF 移除-i--ignored-tags逗号分隔的保留标签如Orientation,DateTime,Software-F实际移除-o--override-file覆盖原文件否则生成带czkawka_cleaned_exif标记的副本。八、进度渲染indicatif 的双模式渲染connect_progressczkawka_cli/src/progress.rs#L7-L34在主线程中循环调用progress_receiver.recv()对每条ProgressData消息按阶段切换渲染方式Spinner不确定模式文件收集、缓存加载/保存等阶段stage.is_indeterminate()为 true 时显示旋转动画czkawka_cli/src/progress.rs#L36-L46。线性进度条[ ]一旦总条目数或总字节数已知如PreHashing、FullHashing显示{msg} [{bar}]模板的确定进度条czkawka_cli/src/progress.rs#L48-L56。阶段标签如 Calculating hashes、Reading tags来自每条ProgressData消息上的ToolStage枚举。ToolStage在 czkawka_core/src/common/progress_data.rs#L80-L103 中定义涵盖收集文件、收集目录、删除、重命名、移动、硬链接、符号链接、优化视频、清理 EXIF 等通用阶段以及各工具专属阶段如Duplicate的 HidingHardLinks → LoadingPreHashCache → PreHashing → SavingPreHashCache → LoadingHashCache → FullHashing → SavingHashCache 七步流水线。ProgressData的to_display()方法czkawka_core/src/common/progress_data.rs#L333-L347把阶段序号换算成 0–99 的整体进度百分比标签文本通过 Fluent 本地化flc!宏生成并内嵌实时计数例如 Analyzed partial hash of 50/100 files (1 MiB / 4 MiB)——这正是 CLI 进度条消息的直接来源。九、结果输出与退出码约定save_and_write_results_to_writerczkawka_cli/src/main.rs#L618-L661统一处理三种可选文件输出与 stdout 缓冲文本格式-f调用print_results_to_file生成人类可读的格式化文本。紧凑 JSON-Csave_results_to_file_as_json(file, false)无多余空白。美化 JSON-psave_results_to_file_as_json(file, true)缩进排版适合程序后续解析。底层的PrintResultstrait 实现位于 czkawka_core/src/common/traits.rs#L19-L116write_base_search_paths会在结果头部写出扫描的包含/排除/参考路径及排除条目JSON 输出由serde_json::to_writer/to_writer_pretty完成。stdout 输出结果 消息先写入BufWriterVecu8缓冲在计算线程 join 之后统一打印避免与进度条渲染竞争终端。退出码约定是 CLI 脚本化的关键找到条目且未设置-W→exit(11)其他情况 →exit(0)。CliOutput结构体czkawka_cli/src/main.rs#L46-L51携带found_any_files、ignored_error_code_on_found与output三个字段-W--ignore-error-code-on-found即脚本需要无论是否找到都继续执行时的开关。十、取消机制ArcAtomicBool 的协作式停止取消通过ArcAtomicBoolSeqCst内存序在 CtrlC 信号处理器与计算线程之间共享czkawka_cli/src/main.rs#L94-L101ctrlc::set_handler(move || { if store_flag_cloned.load(std::sync::atomic::Ordering::SeqCst) { return; // 已在停止中忽略重复信号 } info!(Got CtrlC signal, stopping...); store_flag_cloned.store(true, std::sync::atomic::Ordering::SeqCst); })czkawka_core中的各工具在扫描期间轮询该标志检测为true后优雅停止在下一批条目边界处退出而非中断正在进行的哈希计算。这一机制对所有 14 个子命令统一生效因为 dispatch 函数都通过Search::search(stop_flag, ...)把同一标志传入核心层。十一、关键依赖与可选特性依赖一览Crate用途clap4.5CLI 解析derive APIcolor特性启用彩色帮助文本indicatif0.18进度条渲染crossbeam-channel进度消息的无界通道ctrlc3.4SIGINT / CtrlC 处理humansize2.1人类可读字节大小格式化进度标签中显示 MiB 等czkawka_core全部扫描逻辑可选特性转发给 czkawka_core特性说明依赖heifHEIF/HEIC 图片支持libheiflibrawRAW 图片支持librawlibavifAVIF 图片支持libavifxdg_portal_trashFlatPak 兼容的回收站XDG portal—no_colors禁用 clap 彩色帮助输出—编译时启用cargo run --release --bin czkawka_cli --features heif,libraw,libavif示例见 czkawka_cli/README.md。按运行时依赖区分similar_videos工具需要安装 ffmpegheif/libraw/libavif同时是构建依赖与运行时依赖且官方 README 注明在 Windows 上难以配置、预编译二进制默认不包含。十二、构建、帮助与综合示例# 基础编译 cargo run --release --bin czkawka_cli # 启用图像格式扩展 cargo run --release --bin czkawka_cli --features heif,libraw,libavif--help与各子命令的--help均来自 clap 派生声明帮助模板HELP_TEMPLATE内置了全部 14 个工具的执行示例czkawka_cli/src/commands.rs#L1196-L1224以下为从源码整理的可直接运行的完整用法czkawka dup -d /home/rafal -e /home/rafal/Obrazy -m 25 -x 7z rar IMAGE -s hash -f results.txt -D aeo czkawka empty-folders -d /home/rafal/rr /home/gateway -f results.txt czkawka big -d /home/rafal/ /home/piszczal -e /home/rafal/Roman -n 25 -x VIDEO -f results.txt czkawka empty-files -d /home/rafal /home/szczekacz -e /home/rafal/Pulpit -R -f results.txt czkawka temp -d /home/rafal/ -E */.git */tmp* *Pulpit -f results.txt -D czkawka image -d /home/rafal -e /home/rafal/Pulpit -f results.txt czkawka music -d /home/rafal -e /home/rafal/Pulpit -z track_artist,year,track_title -f results.txt czkawka symlinks -d /home/kicikici/ /home/szczek -e /home/kicikici/jestempsem -x jpg -f results.txt czkawka broken -d /home/mikrut/ -e /home/mikrut/trakt -f results.txt czkawka ext -d /home/mikrut/ -e /home/mikrut/trakt -f results.txt czkawka bad-names -d /home/rafal -u -j -w -n -f results.txt czkawka video-optimizer -d /home/rafal transcode -c h264 -f results.txt czkawka video-optimizer -d /home/rafal crop -m blackbars -f results.txt czkawka exif-remover -d /home/rafal -x IMAGE -f results.txt十三、注释规范与代码维护约定架构文档最后给出注释约定注释应短小精炼遵循仓库根目录 AGENTS.md 的规范只在代码行为无法从阅读本身推断时添加如非显而易见的约束、workaround、跨模块耦合绝不重复代码已表达的内容。这一点在main.rs中体现得很明显——例如HardwareEncoder::None处的TODO - missing hardware encoder注释只标记了一个真实的未实现约束而不是解释显而易见的逻辑。结语从架构图到实战回顾全文czkawka_cli 的设计精髓可以概括为三点薄壳分层扫描逻辑全在核心CLI 只做接线、固定分发骨架14 个工具共享同一套构造 → 配置 → 搜索 → 输出流水线、脚本友好exit(11)退出码 -W开关 三种结果格式。结合 czkawka_cli/src/main.rs 与 czkawka_cli/src/commands.rs 阅读本文你既可以把每个参数精确映射到实现也可以把整套执行模型迁移到自己的工具链中——例如模仿双线程 通道 原子标志的模式为自己的 CLI 增加可取消扫描与进度上报能力。赞分享桌面应用【免费下载链接】czkawkaMulti functional app to find duplicates, empty folders, similar images etc.项目地址https://gitcode.com/GitHub_Trending/cz/czkawka点击查看免费下载相关推荐stitch-skills UI/UX关键词速查表Stitch优化词汇库完整指南stitch skills UI/UX关键词速查表Stitch优化词汇库完整指南 stitch skills 是配合 Google Stitch MCP 服务AI 技能AI 插件OpenTofu架构深度解析从命令行到资源编排OpenTofu架构深度解析从命令行到资源编排 本文深入解析了OpenTofu的完整架构体系从CLI命令处理、配置加载与模块管理、状态管理与数据持久化到图云原生DevOps基础设施Open3D 3D Gaussian Splatting 渲染深度解析Vulkan/Metal 计算管线、深度合成与架构设计Open3D 3D Gaussian Splatting 渲染深度解析Vulkan/Metal 计算管线、深度合成与架构设计 Open3D 通过一条与 Fil计算机视觉图形学3D渲染科学计算上一篇最全面的TDengine跨版本升级指南从数据迁移到兼容性处理的实战策略下一篇解决javascript-obfuscator使用难题从入门到精通的实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考