cull

Cull

Cull 是一款本地 AI 艺术图片库应用：导入文件夹、浏览、评分／决策、创建合集、运行视觉／质量分析、通过嵌入向量查找相似图片，以及导出／发布。

Cull 通过四种方式提供相同的操作：cull CLI、cull:// URL scheme、GUI 和 MCP 服务——它们都是同一个 Rust 核心的轻量封装。默认使用 CLI + URL scheme。 它们无需 MCP 连接，即使应用重启也能继续使用。只有在需要交互式控制，而无头接口尚未实现相关功能时，才使用 MCP（参见“何时需要 MCP”）。

唯一的核心规则（请勿跳过）

显示或审核图片时，请使用 Cull——绝不要使用 open <image> 或 Preview。 用户不需要 Preview 窗口。请先将图片导入 Cull 的图库，然后将应用切换到该文件夹（见下文）来显示。将应用切换到前台没有问题；但不要用 open 打开图片文件。

无头驱动 Cull（默认方式）

二进制文件位于 /Applications/Cull.app/Contents/MacOS/cull。设置一次：

CULL="/Applications/Cull.app/Contents/MacOS/cull"

不带子命令时会启动 GUI；带子命令时会以无头模式运行并退出，写入正在运行的应用所读取的同一个图库数据库。添加 --json 可输出机器可读的结果。

显示／审核一批图片——这是最常见的任务。先导入（无头模式），然后通过 URL scheme 将应用切换到该文件夹：

$CULL --json import_folder --folder_path "/abs/path/to/batch"
open -a /Applications/Cull.app "cull://open?path=/abs/path/to/batch&view=grid"   # &view=loupe for single-image detail
open -a Cull                                            # ensure the window is frontmost

重复运行 import_folder 是安全的——已导入的文件会被跳过。

已实现的 CLI 子命令

这些命令已在发布的二进制文件中可用（运行 cull --help 确认）。字段名称与 MCP 工具参数一致。

命令	用途
import_folder --folder_path P / import_files --file_paths a,b	将文件夹／指定文件导入图库
list_folders / list_images [--limit N --offset N] / list_collections	列出文件夹／图片／合集
get_library_stats	统计整个图库
list_export_presets / export_images --image_ids … --output_dir … --format …	列出预设／导出到磁盘（也可使用 --collection_id 或 --folder_path）
get_embedding_model_download_info / download_embedding_model / generate_embeddings	获取嵌入模型前置条件并构建（异步）
analyze_image_quality / get_image_quality / get_quality_count	运行质量分析／读取评分／按分类统计数量
call_tool <tool> --params_json '{…}'	通用备用入口——使用 JSON 对象调用任意 MCP 工具

call_tool 接受符合 MCP 格式的参数，因此可以在无头模式下尝试任何 MCP 操作：

$CULL --json call_tool import_folder --params_json '{"folder_path":"/abs/path"}'
$CULL --json call_tool export_images --params_json '{"collection_id":"<id>","output_dir":"/tmp/out","format":"original"}'

URL scheme（GUI 操作）

open -a /Applications/Cull.app "cull://<action>?<params>"——路径需进行 URL 编码，多个路径以逗号分隔。始终传入 -a /Applications/Cull.app：Cull 的开发版也会注册 cull:// scheme，直接运行 open "cull://…" 可能会跳转到过时的副本（URL 会被静默丢弃）。GUI 操作会将窗口切换到前台；如果应用尚未运行，macOS 会启动它。

操作	示例
打开／导航	cull://open?path=/abs/folder&view=grid（view=loupe、&focus=N、&fullscreen=true）
搜索	cull://search?q=sunset
查找相似图片	cull://similar?path=/abs/ref.jpg&top=5
评分／接受	cull://rate?path=/abs/img.jpg&stars=4 · cull://accept?path=/abs/img.jpg
合集	cull://collection/add?name=picks&paths=/abs/a.jpg,/abs/b.jpg

URL scheme 调用是即发即弃的（不返回值）。需要结果时，请使用 CLI（--json）或 MCP。

配方（CLI 优先）

用 Loupe 查看一张图片。 open -a /Applications/Cull.app "cull://open?path=/abs/img.png&view=loupe"。

导出选中的图片。 list_export_presets → 使用 --collection_id / --folder_path / --image_ids、--output_dir 和 --format 调用 export_images。

质量检查。 analyze_image_quality（异步——它会返回一个任务；使用 CLI 时，通过重新读取来轮询）→ 使用 get_quality_count 查看分布 → 对每张图片调用 get_image_quality。

嵌入的前置步骤。 download_embedding_model（一次即可）→ generate_embeddings（异步）。完成后，相似度功能才可用（cull://similar?…，或通过 MCP 调用 find_similar）。

何时需要 MCP（可选）

无头 CLI 尚不支持交互式整理和实时导航——这些功能仅由 mcp__cull__* 工具（或手动 GUI 操作）提供。以下情况可使用 MCP：

• 由 Agent 精确导航 / 显示：navigate_to_folder、show_image、show_collection（URL scheme 涵盖常见情况，但这些工具可提供程序化控制和确认）。
• 来回操作以整理内容：set_rating、set_decision、create_collection、add_to_collection、create_smart_collection。
• 搜索和视觉分析并获取结果：find_similar、search_by_object、detect_objects / get_detections、analyze_images、get_vision_metadata。
• 跟踪异步任务：list_jobs / get_job / cancel_job。
• 发布：export_static_publish_package / serve_static_publish_package、剪贴板集合工具。

MCP 的使用方式。 这些工具命名为 mcp__cull__<tool>，在 Claude Code 中是延迟加载的——尚未加载 schema，因此直接调用会失败。调用前先加载，只加载配方所需的工具：

ToolSearch "select:mcp__cull__navigate_to_folder,mcp__cull__set_rating"

Cull 重启后 MCP 会断开。 退出 / 重新启动应用会终止其 MCP 服务；用户必须先通过 /mcp 重新连接，mcp__cull__* 调用才能再次生效。CLI 和 URL scheme 没有此依赖——优先使用它们，仅在需要上述交互操作时再使用 MCP。

常见错误

• 使用 open / Preview，而不是 Cull。 这是最严重的错误——始终在 Cull 中进行审阅（import_folder + cull://open，或使用 MCP 的显示 / 导航工具）。
• 优先使用 MCP。 默认使用 CLI + URL scheme；它们无需连接，重启后也能正常使用。交互式整理时再使用 MCP。
• 认为 Cull 重启后 MCP 仍然可用。 并非如此——用户必须通过 /mcp 重新连接。如果任务依赖 MCP，不要中途重启 Cull。
• 未加载延迟加载的 MCP 工具就直接调用。 先运行 ToolSearch "select:mcp__cull__…"。
• 把异步操作当作同步操作。 嵌入、分析和大型导出都是任务——应轮询状态，不要假定它们已完成。
• 猜测参数。 查看 cull <command> --help，或加载 MCP 工具并阅读其 schema。

安全与限制

• 执行破坏性操作前必须明确确认。 delete_collection 和 prune_audit_log 会删除数据；运行前请确认。
• 令牌具有管理员权限。 create_token / rotate_token / revoke_token 会更改访问凭据——除非用户明确要求，否则不要操作。