Maskbolt Segment Anything on CPU

Maskbolt

在 CPU 上运行 Segment Anything（SAM），供 AI Agent 和脚本使用。Maskbolt 是一个 Rust 二进制程序：它既是 MCP 服务，让 Agent 打开图像、查找所有对象或点击选择某个对象、查看带编号的预览、修正错误，并导出抠图、轮廓和掩码；也是一个可通过单条命令完成相同任务的命令行工具。无需 Python，也无需 GPU。

• 单击即可将对象抠出为透明 PNG；只需一个参数，即可获取 SAM 的三个嵌套掩码（部件、对象、组）。
• “查找所有内容”会在整张图像或重叠切片上运行网格提示词（每个切片都会重新编码到完整模型分辨率，因此小对象也能显现），排除被切片边缘截断的掩码、背景块、重复项和被其他掩码包含的掩码，并说明排除原因。
• 每条会更改掩码的回复都会说明掩码数量、候选项被排除的原因，以及仍显得未覆盖的区域（“查找更多类似区域”），让 Agent 知道还剩下什么。
• 导出格式：叠加 PNG（带编号的掩码，可缩放查看）、抠图 PNG、SVG（外轮廓和内孔，偶奇填充，可选毫米单位）、JSON（含内孔的轮廓、面积、边界框、分数）、标签 PNG（每个掩码一种颜色）。
• 掩码以裁剪到其边界框的形式存储，因此即使包含数千个候选项的密集图像也能保持较小体积。

安装

从最新版本下载适用于你的计算机的压缩包：maskbolt-v0.1.0-x86_64-pc-windows-msvc.zip、maskbolt-v0.1.0-x86_64-unknown-linux-gnu.tar.gz（glibc 2.35 或更新版本）、maskbolt-v0.1.0-aarch64-apple-darwin.tar.gz 或 maskbolt-v0.1.0-x86_64-apple-darwin.tar.gz。使用该版本附带的 SHA256SUMS 校验文件，解压后将 maskbolt（Windows 上为 maskbolt.exe）放入 PATH；运行 maskbolt version 会显示 maskbolt 0.1.0。每个压缩包还包含许可证、THIRD_PARTY.txt 和 THIRD_PARTY_NOTICES.md（该构建所用 Rust 依赖项的许可证文本）。或者，使用 Rust 1.89 或更新版本进行构建：

cargo install --git https://github.com/skulitom/Maskbolt --tag v0.1.0 --locked

Maskbolt 未发布到 crates.io。

首次运行时会将模型下载到用户缓存文件夹，并校验其 SHA-256：

模型	标志	下载大小	许可证
SAM ViT-B（Meta）	默认，--model vit-b	375 MB	Apache-2.0
MobileSAM（TinyViT）	--model tiny	41 MB	Apache-2.0

缓存文件夹：Windows 上为 %LOCALAPPDATA%\maskbolt\models；其他系统上为 $XDG_CACHE_HOME/maskbolt/models 或 ~/.cache/maskbolt/models；设置 MASKBOLT_MODEL_DIR 可使用其他位置。运行 maskbolt fetch 可立即下载。Maskbolt 会将已校验的 .pth 文件保存在转换后的 safetensors 文件旁边，并在 <name>.safetensors.sha256 中记录转换后文件的 SHA-256；每次加载时都会重新校验，如果校验不匹配，就从 .pth 文件重新构建该文件。多个 Maskbolt 进程可以共用该文件夹（使用唯一的临时文件名和原子重命名）。每个模型的磁盘占用量为检查点文件加转换后的文件（ViT-B 约 750 MB，MobileSAM 约 81 MB）。Rust 最低版本：1.89。

CLI

maskbolt cutout examples/chelsea.png --point 200,150 --out cat.png
maskbolt cutout examples/coffee.png --point 300,225 --level largest --fill-holes --out cup-set.png
maskbolt cutout photo.jpg --point 410,220 --exclude 380,300 --box 300,120,520,340 --out thing.png
maskbolt find examples/corn.png --out kernels.json --overlay kernels.png
maskbolt find examples/corn.png --tiles 400 --fill-gaps --out kernels.json --overlay kernels.png
maskbolt find examples/bed.png --grid 12 --min-area 0.01 --max-area 0.3 --drop-hole-views \
    --out offcuts.json --svg offcuts.svg --mm-per-px 0.5
maskbolt mcp --root C:\work\images
maskbolt version

除非传入 --force，否则不会覆盖已存在的输出文件；输入图像绝不会被覆盖。 单次 find 最多使用 64 个图块和 48x48 网格；超过限制时，它会说明你的设置会生成多少个图块、大约需要多长时间，以及适用的图块尺寸。分块 find 不会对整张图像进行整体处理：尺寸大于图块约三分之一的对象会被舍弃，因此处理较大对象时，请先运行普通 find。图像根据内容识别，而非扩展名；会应用 EXIF 方向，且上限为 1 亿像素。

--level：best（默认值，预测 IoU 最高）、smallest（一个部件）、middle（对象）、largest（对象及其所容纳的内容）。find 会输出 JSON 报告（数量、舍弃原因、耗时、仍未覆盖的区域）。

MCP

{"mcpServers": {"maskbolt": {"command": "maskbolt", "args": ["mcp", "--root", "C:\\work\\images"]}}}

• **Claude Code：**插件会注册此服务，根目录为 Claude Code 的运行目录，并提供包含以下循环的 maskbolt 技能。PATH 中需要有 maskbolt（参见安装）：

  claude plugin marketplace add skulitom/Maskbolt
  claude plugin install maskbolt@maskbolt
  

  或者，在 Claude Code 2.1.275 或更高版本中，只需一步：/plugin install maskbolt --marketplace skulitom/Maskbolt。

• **Claude Desktop（Windows x64）：**从发布页面下载 maskbolt-windows-x64.mcpb，双击该文件（或依次选择 Settings > Extensions > Advanced settings > Install Extension），然后选择图像文件夹。

• **MCP Registry：**条目为 io.github.skulitom/maskbolt，包含 Windows 捆绑包及其 SHA-256。

耗时较长的分块 find 需要几分钟：该插件为 Maskbolt 的工具设置了 10 分钟超时；其他客户端可能会更早停止等待（参见限制）。

工具：maskbolt_open、maskbolt_find、maskbolt_click、maskbolt_view、maskbolt_remove、maskbolt_gaps（add: true 会点击候选项）、maskbolt_fill_holes、maskbolt_export。find 和 view 的回复包含编号 PNG；click 的回复包含新蒙版的缩放视图。此服务只会在 --root 内读写（默认值：启动时所在的文件夹；如果该文件夹是驱动器或文件系统根目录，或是你的主文件夹，则拒绝启动）。所有路径都会在访问文件前进行检查：UNC 和设备路径（\\server\share、\\?\、\\.\、//host）、其他驱动器，以及任何通过 .. 逃出根目录的路径，都会被拒绝并显示一条消息。除非调用传入 overwrite: true，否则导出不会替换现有文件，也绝不会替换已打开的图像。View 的回复会给出 image_x = region.x + preview_x / scale；预览的长边最多为 1568 px。首次使用时，模型会在后台下载；如果 25 s 内仍未完成，maskbolt_open 会告知模型大小并提示再次调用。

有效的操作循环：打开；find（对于细小或密集的对象，添加 tile: 400）或 click；view（使用 region 缩放）；移除错误的蒙版；点击遗漏的对象；当回复列出未覆盖的区域时，使用 add: true 调用 gaps；导出。

速度（Ryzen 9 7950X3D，16 核，64 GB，仅 CPU，release 构建，2026-10-23）

步骤	SAM ViT-B	MobileSAM（--model tiny）
加载模型	0.2 s	0.05-0.2 s
编码一张图像（任意尺寸；SAM 按 1024 px 处理）	6.3-6.8 s	4.2-4.3 s
点击一次（解码 + 放大三张掩码）	0.11-0.12 s	0.13-0.14 s
对 chelsea.png 执行 cutout，完整命令	6.8 s，峰值 2.0 GB	5.1 s，峰值 0.5 GB
对 1200x1198 的 corn.png 执行 find，使用 32x32 网格	墙钟时间 30.8 s（编码后 23.5 s），228 张掩码，峰值 3.3 GB	墙钟时间 29.4 s，234 张掩码，峰值 3.0 GB
find --tiles 400（25 个图块，每个 16x16）	墙钟时间 221 s，247 张掩码，峰值 7.0 GB	未测量
find --tiles 400 --fill-gaps	墙钟时间 246 s，256 张掩码	未测量

图块每次编码 4 个（MASKBOLT_ENCODE_THREADS，默认值为 4；每个图块峰值时约占用 1.2 GB；设为 1 时峰值约为 3.3 GB，分块处理 corn 耗时 332 s）。提示词最多使用 16 个线程解码（MASKBOLT_DECODE_THREADS）。 作为对比，Node 原型（8 位 ONNX）处理 32x32 的 corn 耗时 199 s，分块处理耗时 416 s。

限制

• 仅支持 CPU。编码是较慢的步骤（使用 ViT-B 时，每张图像或每个图块约需 6.5 s）；MobileSAM 在此处编码约需 4.2 s，仅快 1.5 倍，因为 candle 的 CPU 卷积速度较慢。处理一张图像时峰值内存为 2-3.3 GB，使用 4 个并行编码处理分块查找时约为 7 GB。
• 耗时较长的分块查找可能会超过 MCP 客户端的工具超时（处理 400 px 的 corn 图像，含 25 个图块，耗时 3.5 分钟； 64 个图块的上限约需 4 到 10 分钟）。目前还没有进度通知。
• SAM 的掩码会漏掉细小部分并留下孔洞；请使用 level、额外的包含/排除点以及 fill_holes。
• 轮廓使用 Douglas-Peucker 算法简化（默认 1.2 px；MCP 导出中使用 simplify_px）；边缘移动距离最多为 此容差值。坐标是从左上角开始的图像像素（像素 x 覆盖 [x, x+1]）。
• 间隙检查是一种颜色启发式方法：它会查找与已有掩码对象相似的对象，而不是新类型的对象。

许可

MIT。模型权重：Apache-2.0（Meta 的 SAM；MobileSAM）。src/sam_decoder.rs 改编自 candle（MIT OR Apache-2.0）；candle 的许可文本位于 THIRD_PARTY.txt。发布压缩包和 MCPB 包会附带 THIRD_PARTY_NOTICES.md，其中包含该构建中每项 Rust 依赖的许可文本。发布说明：参见 mcpb/PUBLISHING.md。