abox.tools

面向 Agent 的 abox.tools

由 Abox Technologies 发布。使用现有的 abox.tools 代码压缩、调整大小和转换图像；合并、拆分、重新排序和旋转 PDF 页面；将图像转换为 PDF；查看或移除图像元数据；以及计算文件校验和。Agent 提供本地路径，并接收输出路径和简短的 JSON 结果。文件内容会保留在你的计算机上。

下载最新版本。 已列入官方 MCP 注册表，名称为 io.github.A-Box-of-Tools/abox-tools。新标记的版本通过下载验证后，会自动更新到注册表。

发布包包含 Node.js、生产依赖项、固定版本的处理代码，以及共享技能。你无需安装 Node 或 npm，也无需输入设置命令。图像处理和将图像转换为 PDF 需要安装 Edge、Chrome 或 Chromium。 PDF 编辑、元数据操作和校验和计算则不需要。

在 Codex 中安装

从版本的 Assets 中下载相应的 .zip：

版本标签	计算机
windows-x64	配备 Intel 或 AMD 64 位处理器的 Windows 计算机
macos-arm64	配备 Apple 芯片的 Mac
macos-x64	配备 Intel 处理器的 Mac
linux-x64	配备 Intel 或 AMD 64 位处理器的 Linux 计算机

1. 将整个 ZIP 解压到一个固定文件夹中。例如，0.4.0 Windows 安装包解压后会生成 abox-tools-0.4.0-windows-x64 文件夹。请勿移动此文件夹，因为本地市场会使用它来刷新插件。
2. 打开解压文件夹中的 START-HERE.html。此页面可离线使用。选择 Install in Codex，允许浏览器打开桌面应用，然后在插件详情页中选择 Install。
3. 开始新的本地聊天，并请求执行以下操作之一。

你需要安装桌面应用，并确保其 codex:// 链接处理程序可用。 该按钮会打开应用支持的本地插件详情链接；安装由应用处理。请参阅 OpenAI 官方深层链接文档。 如果浏览器阻止链接，请在 Windows 上使用 Install in Codex.cmd，或在 macOS 上使用 Install in Codex.command。Linux 提供了 Install in Codex.sh，适用于支持执行 shell 脚本的文件管理器。这些启动器会打开同一个详情页，并可能短暂显示终端；无需输入任何命令。

在 Claude Desktop 中安装工具

从同一版本下载 universal.mcpb，用 Claude Desktop 打开，然后按照安装提示操作。一个文件支持 Windows x64、Linux x64，以及 Apple 芯片和 Intel 芯片的 Mac。文件中包含运行时和处理依赖项。此外还提供更小的平台专用 MCPB。此安装方式会安装 MCP 工具；共享 Agent 技能包含在 Codex ZIP 中。

如果打开文件后没有显示安装程序，请前往 Settings → Desktop app → Manage（位于 Extensions 旁边），然后选择 Advanced settings → Install Extension… 并选择 .mcpb。请参阅 Claude 桌面扩展安装说明。 CI 会在全部四个平台上检查捆绑包格式和 MCP 执行情况。0.2.1 通用捆绑包已在 Windows 上安装并启用于 Claude Desktop，应用显示其本地 MCP 服务正在运行。尚未检查 macOS 桌面界面。更新时请下载并安装新捆绑包；自定义 MCPB 文件不会自动更新。

0.3.0 版本更正了发布者名称为 Abox Technologies。如果桌面主机中同时显示较早的发布者条目和新条目，请停用较早的条目，以避免工具重复。

在 Gemini CLI 中安装

安装 Gemini CLI 后，运行：

gemini extensions install https://github.com/A-Box-of-Tools/abox-tools-plugin

Gemini 会从最新的 GitHub Release 中选择匹配的预构建存档。 该扩展包含其运行时、依赖项和共享技能。请查看 安装提示，并允许其本地 MCP 服务。请参阅 Gemini 扩展发布指南。

在 Cursor 中安装工具

解压匹配的原生 ZIP，打开 START-HERE.html，然后选择 在 Cursor 中安装 工具。Cursor 会在添加配置前显示本地服务配置。请保留解压后的文件夹。 此操作会添加 MCP 工具；共享技能可单独安装。此仓库的 Cursor 插件安装方式需要 Node 和一次性适配器设置；请参阅 Cursor 安装说明。

通过 skills.sh 安装共享技能

适用于 skills CLI 支持的 Agent（Node 22.20+）：

npx skills add A-Box-of-Tools/abox-tools-plugin --skill abox-local-files

然后让 Agent 设置 abox.tools 本地适配器。该技能包含一个 Python 3.9+ 设置脚本，可下载匹配的打包版本、验证其校验和，并安装内置运行时。无需克隆或构建本项目。请参阅独立设置。 skills.sh 上的条目 为公开状态。Gemini 发布版安装已验证；其应用库索引尚待完成。

向 Agent 提出请求

• “将这张照片压缩到 500 KB 以下，并另存一份。”
• “调整这张照片的大小，使其不超过 1200 × 800 像素。”
• “将这张 PNG 转换为 WebP。”
• “按此顺序合并这些 PDF。”
• “将此 PDF 拆分为每页一个文件。”
• “将第 1–3 页和第 4–6 页分别提取为两个 PDF。”
• “创建一个 PDF，包含第 3 页、第 1–2 页，以及另一份第 3 页。”
• “将第 2–4 页顺时针旋转 90 度。”
• “按此顺序将这些照片放入一个 PDF。”
• “检查此图像是否包含 EXIF 或 XMP 元数据。”
• “移除此图像的位置和其他元数据，同时保留其方向和颜色。”
• “计算这些文件的 SHA-256 校验和。”

所有输入和输出路径都必须为绝对路径。绝不会覆盖现有输出。图像压缩支持精确的字节数目标；结果会报告是否达到目标。

MCP 工具	必需参数	有用选项
abox_capabilities	无	列出格式、限制和默认值。
abox_image_compress	input_path、output_path、target_bytes	format：keep、auto、jpeg、png、webp；allow_resize
abox_image_resize	input_path、output_path、width 和／或 height	fit：contain 或 cover；allow_upscale：false；format、quality、background
abox_image_convert	input_path、output_path、format	jpeg、png 或 webp；quality 范围为 0 到 1；JPEG 的 background
abox_pdf_split	input_path、output_dir	mode：each、every、ranges；pages_per_file；ranges；keep_bookmarks
abox_pdf_merge	input_paths、output_path	按输入顺序合并 2–32 个 PDF；keep_bookmarks
abox_pdf_select	input_path、output_path、pages	使用 3,1-2,3 等有序项；keep_bookmarks
abox_pdf_rotate	input_path、output_path、degrees	顺时针旋转 90、180 或 270 度；pages 默认为 all；保留所有页面
abox_images_to_pdf	input_paths、output_path	每页一张图像；page_size、orientation、fit、margin_mm、dpi、image_mode、quality、max_side、background
abox_exif_inspect	input_path	只读元数据清单；不返回私有标签值
abox_exif_remove	input_path、output_path	keep_orientation；keep_icc
abox_file_hash	input_path	algorithms：MD5、SHA-1、SHA-256（默认）、SHA-384、SHA-512

使用 CLI

CLI 无需 MCP 即可执行相同操作。这些命令在源码检出目录中使用 Node。 在发行包中，将 node 替换为 ./runtime/node；在 Windows 上则替换为 .\runtime\node.exe：

node bin/abox.mjs capabilities
node bin/abox.mjs doctor
node bin/abox.mjs compress-image --request-file /absolute/path/compress.json
node bin/abox.mjs resize-image --request-file /absolute/path/resize.json
node bin/abox.mjs convert-image --request-file /absolute/path/convert.json
node bin/abox.mjs split-pdf --request-file /absolute/path/split.json
node bin/abox.mjs merge-pdf --request-file /absolute/path/merge.json
node bin/abox.mjs select-pdf-pages --request-file /absolute/path/select.json
node bin/abox.mjs rotate-pdf --request-file /absolute/path/rotate.json
node bin/abox.mjs images-to-pdf --request-file /absolute/path/photos.json
node bin/abox.mjs inspect-exif --request-file /absolute/path/inspect.json
node bin/abox.mjs remove-exif --request-file /absolute/path/metadata.json
node bin/abox.mjs hash-file --request-file /absolute/path/hash.json

压缩请求文件包含：

{
  "input_path": "/absolute/path/photo.jpg",
  "output_path": "/absolute/path/photo-small.jpg",
  "target_bytes": 500000,
  "format": "keep",
  "allow_resize": true
}

页面范围请求文件包含：

{
  "input_path": "/absolute/path/document.pdf",
  "output_dir": "/absolute/path/document-parts",
  "mode": "ranges",
  "ranges": ["1-3", "4-6"],
  "keep_bookmarks": true
}

图像元数据请求文件包含：

{
  "input_path": "/absolute/path/photo.jpg",
  "output_path": "/absolute/path/photo-clean.jpg",
  "keep_orientation": true,
  "keep_icc": true
}

也支持 --request '<JSON>'，但须遵循 shell 的引号规则。请求文件可避免这些差异。CLI 会输出 JSON 摘要；不会输出文件内容。

限制和行为

• 图像压缩、调整大小和格式转换：支持 JPEG、PNG 和静态 WebP。 不处理动画图像。调整大小时可完整适配图像（contain），也可居中裁剪 （cover）；默认不放大图像。重新编码可能改变颜色并移除源元数据。若调整大小 后无需变化，则保留原始字节。
• 元数据移除：支持 JPEG、PNG 和 WebP 容器，包括其中的动画。
• PDF：输入文件不得加密，最多 5,000 页，最多生成 1,000 个输出文件。 合并操作接受 2–32 个 PDF，合计大小最多 128 MiB。页面选择会保留逗号分隔项的 顺序及重复项。范围按升序展开：3,1-2,3 会生成 3,1,2,3；如需反向顺序，请使用 明确的页面项。目前，源引擎不支持合并具有重复交互式表单字段名称的 PDF，且会在 创建输出文件前失败。工具响应最多包含 20 个输出条目。较大的拆分任务还会写入 本地 manifest.json，其中包含所有输出路径及其源页面。
• 图像转 PDF：支持静态 JPEG、PNG 或 WebP，每页一张图像，合计大小最多 128 MiB， 每张图像最多 80 百万像素。默认使用 A4、自动方向、适配模式且不留页边距。 keep 可嵌入原始 JPEG 数据流及其元数据；如需生成干净的文档，请先移除元数据。 lossless 会保留解码后的图像像素；jpeg 会按指定质量重新编码。
• 校验和：只读、流式处理，支持空文件，文件大小最多 8 GiB。
• 其他每个输入文件：最多 128 MiB。
• 压缩：每张图像最多 80 百万像素，处理时间最多两分钟。auto 可能会调整输出扩展名， 使其与所选格式一致。其他模式要求输出扩展名与实际字节内容一致，包括未更改的原始文件。
• 压缩可能会调整图像大小，除非 allow_resize 为 false。已达到目标的文件可能会 原样通过，并保留其元数据。如果任务要求移除元数据，请使用元数据移除功能。
• 元数据移除会通过编辑 PNG 和 WebP 容器保留其中的动画；压缩则会拒绝处理动画， 而不是将其压平。
• PDF 拆分会创建新的 PDF。文档标签和元数据可能会被移除；数字签名无法作为有效签名 保留。系统会验证输出页数。在支持的情况下，默认保留书签。
• 默认情况下，元数据移除会保留方向信息和 ICC 配置文件，以保持原有外观。将 keep_orientation 和 keep_icc 设为 false，也可移除这些受支持的字段；这可能会 改变显示方向或颜色。这并不能证明图像已匿名化。

下载发行包或安装浏览器时会使用网络。通过此适配器处理文件时，不会通过网络发送文件 字节。Agent 及其宿主仍会接收路径、设置、摘要和错误。此适配器无需账户或 API 密钥。

有关适配器处理的数据及 Agent 宿主各自承担的责任，请参阅插件隐私声明。

压缩器会检测常见的浏览器安装。如有需要，可将 ABOX_BROWSER_PATH 设为现有浏览器 可执行文件的路径。浏览器沙箱必须能在宿主操作系统上正常运行；在 Linux 上，检测会优先 选择已安装的稳定版 Chrome，而不是通用 Chromium 构建版本。插件不会在处理过程中下载浏览器。

此插件与网站的开发 MCP

此插件通过 MCP stdio 在本地执行文件操作。独立的网站目录 mcp-dev.abox.tools/mcp 提供 find_browser_tools：它接受公开搜索查询、区域设置和数量上限，然后 返回工具链接和交互式目录。它不接受文件或文件名，也不处理文件。其源代码来自网站的 开发目录工作器。

mcp-dev 端点用于开发。此仓库的发布工作流 不会部署网站或发布生产环境的目录端点。 有关目录提交和 MCP 注册，请参阅发布。 有关 Gemini CLI、Vercel skills.sh、Cursor 和其他分发选项，请参阅 平台支持与发布。

开发者设置与其他 MCP 宿主

无需开发工具即可使用发布包进行安装。若要从源代码检出版本进行开发，请安装 Node.js 22.15 或更高版本，然后运行：

npm ci --ignore-scripts
npm test
npm run test:browser
npm run doctor

源代码设置会下载 npm 依赖项。源代码检出版本的 mcp.json 使用宿主提供的 Node；发布打包时则会替换为随包提供的可执行文件。 开发者可以通过 codex plugin marketplace add A-Box-of-Tools/abox-tools-plugin 添加此仓库市场，然后在桌面应用中安装插件，并在已安装的副本中运行 Setup。请参阅 OpenAI 官方打包指南。

对于支持本地 MCP stdio 的其他宿主，请将其配置指向解压后软件包中的可执行文件和服务器脚本，并使用绝对路径：

{
  "mcpServers": {
    "abox": {
      "command": "/absolute/path/to/bundle/runtime/node",
      "args": ["/absolute/path/to/bundle/bin/abox-mcp.mjs"]
    }
  }
}

在 Windows 上，请使用 runtime/node.exe。在 JSON 中对反斜杠进行转义，或使用正斜杠。源代码检出版本可以使用 node，而不是随包提供的可执行文件。 请遵循宿主自身的配置格式；不要替换无关设置。

维护复用代码

若要从本地网站检出版本刷新固定的网站源代码：

npm run sync-upstream -- --source /absolute/path/to/etoolbox

检查供应商差异和来源信息，保留许可证声明，并运行上述检查。v* 标签会启动 .github/workflows/release.yml：执行测试、构建全部四个平台的软件包、构建通用 MCPB，并在所有四个平台上检查解压后的 MCP 执行情况，然后发布 GitHub Release。成功发布带标签的版本后，会使用 GitHub 的短期身份令牌，将经过验证的元数据发布到 Official MCP Registry。Claude 和 OpenAI 目录审核仍需分别提交；请参阅发布。