xxd-strip-ai-meta 部署与使用教程

xxd-strip-ai-meta 是一个用 Python 编写的工具，用于批量清除图片中的 AI 来源标记和元数据。它依赖强大的 ExifTool 作为后端，支持清理 C2PA、OpenAI 等 AI 生成内容标记，以及 EXIF、XMP 等常规元数据，同时保持图片像素数据完全不变。本教程将指导你完成部署和基本使用。

核心概念与工作原理

了解工具的设计初衷和工作方式，有助于正确使用它。

  • 工具定位：这是一个元数据清理工具。它能清除嵌入在图片文件头部的描述性信息（如拍摄参数、编辑历史、AI 生成标记），但无法去除图片画面中可见的水印，也无法保证清除像素级的隐形水印或平台指纹。
  • 工作原理：工具本身是一个 Python 脚本，其核心功能是调用你系统中安装的 ExifTool（一个强大的元数据处理神器）来执行读取和删除操作。它本身不包含 ExifTool，因此需要你自行安装。
  • 输出特点：处理后的图片，其像素数据（即你看到的画面）不会被重新编码或压缩，因此图片质量无损。同时，文件的修改时间默认会被保留。

第一步：环境准备

在使用本工具前，必须确保你的系统满足以下两个前提条件。

  1. 安装 Python 环境：
    • 需要 Python 3.10 或更高版本。在终端输入 python3 --version 检查。
    • Windows 用户可能需要使用 python 命令，请确认版本。
  2. 安装核心依赖 ExifTool：
    • 这是必须的步骤，工具本身不含 ExifTool。
    • macOS：brew install exiftool
    • Debian / Ubuntu：sudo apt install libimage-exiftool-perl
    • Windows：从 ExifTool 官网下载安装包，并确保安装目录已添加到系统的 PATH 环境变量中。安装后，在命令行输入 exiftool -ver 应能正常显示版本号。

第二步：获取工具脚本

由于项目非常轻量，没有复杂的依赖，你只需要将脚本下载到本地即可。

1
2
3
# 克隆项目仓库
git clone https://github.com/nevertoday/xxd-strip-ai-meta.git
cd xxd-strip-ai-meta

工具的核心脚本是位于 scripts/ 目录下的 clean_image_provenance.py。你后续的所有操作都将围绕这个脚本进行。

第三步：基础使用与安全预览

重要提示：工具默认会直接修改（覆盖）原始文件。因此，强烈建议在首次使用时遵循以下步骤，先进行安全预览，并测试备份功能。

  1. 预览模式（推荐第一步执行）
    此模式会列出所有将被处理的文件和处理后的元数据变化，但不会实际修改任何文件。这是检查工具是否符合预期的最安全方式。

    1
    2
    # 注意：从项目根目录执行
    python3 scripts/clean_image_provenance.py /path/to/your/images --dry-run

    将 /path/to/your/images 替换为你存放图片的文件夹路径。

  2. 备份模式（首次实际运行强烈建议）
    使用 --backup 参数，ExifTool 会为每个被修改的原文件生成一个 *_original 的备份文件，方便你随时恢复。

    1
    python3 scripts/clean_image_provenance.py /path/to/your/images --backup

第四步：常用操作与高级参数

熟悉了基本流程后，你可以根据需要组合使用以下参数，应对更复杂的任务。

  • 处理多个路径：脚本可以同时接受多个文件或文件夹作为输入。

    1
    python3 scripts/clean_image_provenance.py /path/to/image1.png /path/to/folder_a /path/to/folder_b

  • 后台运行大批量任务：对于大量图片（如数千张），可以使用 --background 参数让任务在后台运行，并输出日志文件路径，方便监控。

    1
    python3 scripts/clean_image_provenance.py /path/to/large_folder --background

  • 调整性能：--jobs 参数控制并发批次数量（默认5），--chunk-size 控制每批处理的文件数（默认100）。如果你的系统性能有限，可以将 --jobs 设为 1 以降低负载。

  • 额外选项：

    • --drop-color-profile：同时删除 ICC 色彩配置文件。慎用，这可能导致图片在不同设备上的颜色显示出现偏差。
    • --no-verify：跳过清理完成后的元数据检查步骤，可以略微提升处理速度。

进阶应用：作为 AI Agent Skill 安装

该项目设计的一个独特之处是可以作为技能（Skill）安装给 AI Agent（如 Claude Code）使用。

  1. 克隆到技能目录：

    1
    2
    # 以 Claude Code 为例，将仓库克隆到其 skills 目录下
    git clone https://github.com/nevertoday/xxd-strip-ai-meta.git ~/.claude/skills/xxd-strip-ai-meta

  2. 使用方式：完成后，在支持该技能的 Agent 对话中，你可以直接要求它”使用 xxd-strip-ai-meta 技能清理我桌面上的图片”，Agent 便会调用相应的脚本。

故障排查与注意事项

  • 权限问题：确保你对要处理的图片文件及所在目录拥有读写权限。
  • “exiftool: command not found”错误：表明 ExifTool 未正确安装或未添加到 PATH。请回顾第一步，确保在终端中能直接执行 exiftool 命令。
  • “Unsupported file type”提示：工具支持 PNG、JPEG、WebP、TIFF、HEIC、HEIF 和 AVIF 格式。请检查你的文件格式是否在支持列表内。
  • 关于验证机制：工具的验证（--verify）仅检查 ExifTool 输出中是否仍有已知的来源关键字，它不是通用水印检测器，不能保证100%清除所有元数据。

总的来说，xxd-strip-ai-meta 是一个专注于图片元数据清理的实用工具，尤其适合需要去除 AI 生成标记或进行隐私保护的场景。它的部署和使用都非常轻量级，但请务必遵守其免责声明：此工具用于隐私保护和内部元数据整理，不应被用于误导他人对图片来源的判断。