cloche

<p align="center"> <img src="docs/assets/cloche-social-preview.jpg" alt="Cloche banner" width="900"> </p> <h1 align="center">Cloche</h1> <p align="center"> <strong>一款开源的桌面截图命令行工具，可以将任意窗口转换为精致、易于分享的卡片，输出稳定的 JSON 数据，并支持从 shell、热键或 AI 代理使用。</strong> </p> <p align="center"> <a href="https://github.com/escoffier-labs/cloche/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/escoffier-labs/cloche/ci.yml?branch=master&style=for-the-badge&label=CI&logo=githubactions&logoColor=white" alt="CI status"></a> <a href="https://crates.io/crates/cloche"><img src="https://img.shields.io/crates/v/cloche?style=for-the-badge&label=crates.io&logo=rust&logoColor=white" alt="crates.io version"></a> <img src="https://img.shields.io/badge/Rust-2024-b7410e?style=for-the-badge&logo=rust&logoColor=white" alt="Rust 2024"> <img src="https://img.shields.io/badge/platform-Linux_first-2563eb?style=for-the-badge&logo=linux&logoColor=white" alt="Linux first"> <img src="https://img.shields.io/badge/Windows-supported-0078d4?style=for-the-badge&logo=windows&logoColor=white" alt="Windows supported"> <img src="https://img.shields.io/badge/MCP-optional-7c3aed?style=for-the-badge" alt="Optional MCP server"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-2ea043?style=for-the-badge" alt="Apache-2.0 license"></a> </p> <p align="center"> <strong>官方网站：</strong> <a href="https://cloche.escoffierlabs.dev">cloche.escoffierlabs.dev</a> </p> <p align="center"> <img src="docs/cloche-settings-card-2026-06-07.png" alt="Cloche shot of Linux Settings, framed as a polished presentation card" width="720"> </p> <p align="center"> <img src="docs/cloche-calculator-card-2026-06-07.png" alt="Cloche shot of Linux Calculator, framed as a polished presentation card" width="420"> </p> Cloche 是一款开源的桌面截图命令行工具，适用于人和 AI 代理。它捕获活动应用程序或窗口，将结果框架为精致的演示卡，写入原始图像和元数据，并输出稳定的 JSON 数据，以便脚本、本地工具和编码代理可以驱动相同的命令。上面的截图是真正的 Cloche 输出，而不是模拟的：原始捕获直接放到渐变背景上，带有圆角窗口和柔和阴影。 Cloche 的不同之处在于，捕获、润色和机器可读输出是一个工具。大多数截图应用程序仅限于 GUI，止步于 PNG 文件；而 Cloche 可以在 shell 中无头运行，绑定到单个热键，或作为 MCP 服务器运行，并且每种路径都输出相同的 JSON 契约。名称来源于用于干净地展示菜肴的玻璃罩：Cloche 提升屏幕上的内容，框架它，并使其准备好分享。 第一个生产模式是 **Shots**：带有原始文件、元数据、文本提取和画廊帮助的精致截图。路线图增加了 **Reels** 以进行短屏幕录制，然后是 **GIF 导出** 以进行轻量级循环。 此仓库最初是 `appshots`。`appshots` 二进制文件作为兼容别名保留，而 `cloche` 成为主要命令。 ## Cloche 的功能 Cloche 是一款命令行截图和屏幕捕获工具，生成可分享的演示卡和稳定的 JSON 数据，适用于 Linux 和 Windows。它在一个二进制文件中完成整个捕获管道：获取像素，将它们润色到渐变背景上，写入元数据，并将干净的 JSON 结果交给调用者。 - 捕获活动窗口、选定窗口、整个屏幕或交互选择的区域。 - 写入 `shot.png`、`metadata.json`、可选的 `text.txt` 和精致的 `shot-card.png`。 - 使用 `cloche polish` 将现有图像样式转换为相同的演示卡。 - 为代理和自动化输出稳定的 JSON 数据。 - 在操作系统公开时，通过 OS 可访问性层提取尽力而为的可见或可访问应用程序文本。 - 为捕获历史提供 `gallery`、`latest` 和 `preview` 帮助程序。 - 直接作为 CLI 运行，或通过 `cloche mcp` 作为小型_stdio MCP 服务器运行。 - 在重命名期间保留 `appshots` 作为兼容命令。 ## 模式 **Shots** 现已可用。Shot 是带有原始和演示图像、元数据和可选提取文本的静态捕获。 **Reels** 计划在 Shots 之后推出。Reel 将是一个短桌面录制，具有相同的 Cloche 演示系统、光标强调、字幕和稳定的元数据。现有的 Appreels 原型是此模式的起点。 **GIF 导出** 计划在 Reels 之后推出。GIF 将从完成的 Reels 中生成作为交付格式，而不是作为主要源格式记录。 ## 为什么 Cloche 存在 OpenAI 文档将 Appshots 描述为 Codex 的 macOS 应用程序功能。Codex 仓库已经可以通过 app-server v2 `turn/start` 输入恢复包含本地图像的线程： ```json { "type": "localImage", "path": "/absolute/path/to/shot.png", "detail": "high" } ``` Linux 和 Windows 用户仍然需要一种可靠的方式从普通 CLI 创建这些捕获。Cloche 填补了捕获侧，同时保持独立于任何代理堆栈。可以与 Codex、OpenClaw、Claude Code、Hermes、本地 MCP 客户端或普通 shell 脚本一起使用。 参考：<https://developers.openai.com/codex/appshots> ## 为什么不使用其他截图工具？ - **Flameshot、Spectacle、GNOME Screenshot、Greenshot、ShareX** 是优秀的交互式 GUI 工具，适用于人类单击和注释。它们不为脚本提供稳定的命令接口，不输出机器可读的 JSON 数据，也不能从代理进程无头运行。Cloche 优先使用 CLI 和 JSON；它使用诸如 Flameshot 之类的工具进行区域选择步骤，但拥有润色、元数据和契约。 - **`grim` / `scrot` / ImageMagick `import` / `maim`** 捕获像素并停止。您仍然需要手动组装框架、渐变、元数据和 JSON。Cloche 包装相同的底层捕获并在单个命令中完成其余操作。 - **`carbon-now`、`silicon`、`ray.so`** 从源代码或任意图像中创建漂亮的卡片，而不是实时窗口。Cloche 捕获实际应用程序，然后将其框架，并且 `cloche polish <image>` 涵盖了“我已经有截图”的情况。 - **macOS Appshots 应用程序适用于 Codex** 是灵感来源，但仅限于 macOS，并绑定到一个代理堆栈。Cloche 在 Linux 和 Windows 上填补了相同的捕获角色，同时保持代理中立：可以与 Codex、OpenClaw、Claude Code、Hermes、任何 MCP 客户端或普通 shell 脚本一起使用。 ## Cloche 不是什么 Cloche 是一个本地捕获工具，而不是服务或注释套件。 它不： - 运行后台守护进程、托盘应用程序或调度程序 - 上传、同步或电话回家您的捕获 - 注释、模糊或编辑（它框架屏幕上的内容；请在分享前查看） - 记录音频或执行 OCR（文本提取通过 OS 可访问性层尽力而为） - 替换您的编辑器或分享主机；它写入本地文件和 JSON 接收，然后由您处理 ## 安装 Cloche 需要 Rust 1.88 或更新版本。发行版软件包可能滞后（Ubuntu 24.04 的 `apt install cargo` 提供了 1.75，这太旧了）；如果 `cargo install cloche` 因 MSRV 错误而失败，请先使用 [rustup](https://rustup.rs) 安装当前工具链。 从 crates.io 安装最新版本： ```bash cargo install cloche ``` 从本地检出构建和安装： ```bash cargo install --path . --bins ``` 或使用安装脚本： ```bash bash scripts/install.sh ``` 在 Windows 上： ```powershell powershell -ExecutionPolicy Bypass -File scripts/install.ps1 ``` ## 快速入门 将活动应用程序或窗口捕获为 Shot： ```bash cloche capture --target active --out-dir /tmp/cloche-shot-$(date +%s) --format json ``` 将现有截图样式转换为演示卡，无需重新捕获： ```bash cloche polish /tmp/diff.png --palette violet-haze --format json ``` 通过实验性 Remotion 卷轴引擎渲染现有短录制： ```bash cd remotion && npm install && cd .. cloche reels render \ --input raw.mp4 \ --out demo.mp4 \ --cues cues.json \ --title "Create a project" ``` 提示文件遵循 AppReels 时间轴形状： ```json { "titleCard": { "text": "Create a project", "ms": 900 }, "captions": [{ "startMs": 1000, "endMs": 2600, "text": "Open the project menu" }], "zooms": [{ "startMs": 1200, "endMs": 2400, "scale": 1.08 }], "outroCard": { "text": "Done", "ms": 700 } } ``` 预览最新捕获： ```bash cloche preview ``` 创建最近 Shots 的自包含 HTML 画廊： ```bash cloche gallery --root /tmp --html /tmp/cloche.html --title "My Shots" --open ``` 从 Shot 生成 Codex `turn/start` 有效载荷： ```bash cloche codex-payload --thread-id "$THREAD_ID" /tmp/cloche-shot-123 ``` ## 命令参考 ```bash cloche doctor --format json cloche list-windows --format json cloche capture --target active --presentation both --out-dir /tmp/cloche-shot --format json cloche capture --target active --style-seed 12345 --out-dir /tmp/cloche-shot --format json cloche capture --target screen --out-dir /tmp/cloche-shot --format json cloche capture --target window --title Firefox --out-dir /tmp/cloche-shot --format json cloche capture --target region --presentation both --clipboard --out-dir /tmp/cloche-shot --format json cloche polish /tmp/diff.png --format json cloche polish /tmp/diff.png --out /tmp/diff-card.png --palette ember-glow --style-seed 12345 cloche gallery --limit 10 cloche gallery --root /tmp --html /tmp/cloche.html --title "My Shots" --open cloche latest cloche preview cloche open /tmp/cloche-shot cloche schema cloche schema --for polish cloche codex-payload --thread-id THREAD_ID /tmp/cloche-shot cloche mcp cloche setup cloche setup --print cloche setup hotkey cloche setup agent --client claude-code cloche setup verify --format json ``` 旧的 `appshots` 命令作为同一代码路径的别名保留。 ## 输出文件 每个成功的 Shot 目录包含： - `shot.png`，原始捕获图像。 - `shot-card.png`，演示图像：带有圆角和柔和阴影的截图，置于全出血渐变背景上，完全不透明，以便在 JPEG 和任何地方粘贴时保持不变。 - `metadata.json`，与 stdout 打印的相同 JSON 对象。 - `text.txt`，可选的尽力而为的可访问文本，来自聚焦应用程序。 捕获仅在写入原始图像时退出，状态为 `0`。文本提取和演示图像失败是警告，因为可访问性支持和桌面合成因工具包、应用程序、桌面环境和操作系统而异。`--target screen` 作为回退和调试模式存在。`--target active` 是默认目标。 使用 `--presentation raw`、`--presentation card` 或 `--presentation both` 控制输出图像生成。使用 `--style-seed <number>` 准确重现随机样式的演示卡。 `--target region` 打开交互式选择器（如果可用，则为 Flameshot；否则为 ImageMagick `import` 拖动选择）：拖动矩形，选择完成后立即拍摄快照。添加 `--clipboard` 将完成的卡片直接复制到剪贴板（Wayland 上为 wl-copy，X11 上为 xclip）。区域捕获需要有人坐在桌前；它不适用于无头代理。Windows 上尚不支持：使用 Win+Shift+S，保存文件，然后运行 `cloche polish <file>`。 ## 热键工作流 将一个键绑定到剪贴板上的可分享卡：按下它，拖动一个区域，粘贴精致的卡片到任何地方。捕获、润色和复制到剪贴板都发生在 cloche 中；只需设置按键绑定即可。 最快的路径是一条命令： ```bash cloche setup ``` 它安装 `cloche-grab`，将其绑定到 GNOME 的 Print 键（并在 KDE/sway/i3 上打印确切的步骤），用它检测到的任何代理注册 MCP 服务器，然后验证捕获、热键和 MCP 服务器实际上是否正常工作。运行 `cloche setup --print` 预览每项更改，或随时运行 `cloche setup verify` 重新检查。下面的手动步骤是 `cloche setup` 自动化的内容，是不支持的桌面的备用方案。 仓库附带 `scripts/cloche-grab.sh`，它封装了捕获并添加了桌面通知。安装它并绑定： ```bash # 1. 将脚本放在您的 PATH 中（或在原地绑定到它）。 install -Dm755 scripts/cloche-grab.sh ~/.local/bin/cloche-grab # 2. 确认它有效（它会打开区域选择器）： cloche-grab ``` 然后将 `cloche-grab` 绑定到一个键： - **GNOME：** 设置 -> 键盘 -> 查看和自定义快捷键 -> 自定义快捷键 -> +。命名为“Cloche Grab”，命令为 `cloche-grab`，并设置快捷键（例如 Print）。要先将原生截图界面从 Print 键移开：`gsettings set org.gnome.shell.keybindings show-screenshot-ui "['<Shift>Print']"`。 - **KDE：** 系统设置 -> 快捷键 -> 自定义快捷键 -> 编辑 -> 新建 -> 全局快捷键 -> 命令/网址，命令为 `cloche-grab`，然后分配一个键。 - **其他（sway、i3 等）：** 在您的 WM 配置中将一个键绑定到 `cloche-grab`。 如果您不喜欢脚本，可以直接绑定以下一行命令： ```bash cloche capture --target region --presentation both --clipboard --out-dir ~/Pictures/ClocheShots/$(date +%s) ``` `cloche polish` 写入单个卡片 PNG 文件，而不是 Shot 目录：默认情况下，在输入旁边生成 `<input>-card.png`，或使用您传递的 `--out <path>`（它必须以 `.png` 结尾）。其 stdout JSON 报告 `input`、`card` 和 `presentationStyle`。 ## 代理使用 任何具有 shell 能力的代理都可以调用： ```bash cloche capture --target active --out-dir /tmp/cloche-shot-$(date +%s) --format json ``` 然后从 stdout 解析 `image.path` 或读取生成的 `metadata.json`。 Codex 应用程序服务器客户端可以将捕获转换为准备好的 `turn/start` 有效载荷： ```bash cloche codex-payload --thread-id "$THREAD_ID" /tmp/cloche-shot-123 ``` 其他代理应将 Cloche 视为普通的子进程工具。核心命令没有 MCP 依赖、桌面应用程序依赖或特定于代理的运行时依赖。 ## MCP 服务器 `cloche mcp` 为更喜欢 Model Context Protocol 而非直接子进程调用的客户端运行一个最小的 stdio MCP 服务器。它在 stdin/stdout 上使用换行分隔的 JSON-RPC 2.0 进行通信，并将 `capture`、`polish`、`list_windows`、`doctor`、`latest` 和 `gallery` 公开为工具。每个工具调用都分发到相同的二进制文件，因此 JSON 契约与 CLI 相同。 `cloche setup agent` 将此服务器自动注册到 Claude Code、OpenClaw 和 Codex CLI（备份它编辑的任何配置，并跳过已配置的客户端）。下面的手动配置适用于其他客户端或您希望自己连接的情况。 像任何 stdio MCP 服务器一样注册： ```json { "mcpServers": { "cloche": { "command": "cloche", "args": ["mcp"] } } } ``` 兼容性配置： ```json { "mcpServers": { "appshots": { "command": "appshots", "args": ["mcp"] } } } ``` ## Linux 后端说明 - X11 活动/窗口捕获使用 `xdotool`/`wmctrl``获取窗口元数据，ImageMagick `import`获取 PNG 捕获。 - Wayland wlroots 屏幕捕获使用 `grim`。 - GNOME/KDE Wayland 可能会因设计而阻止静默活动窗口捕获。使用 `--target screen` 或运行 `cloche doctor --format json` 进行诊断。 - 文本提取通过 Python GI 使用 AT-SPI 尽力而为。 ## Windows 后端说明 - 活动/窗口捕获使用 Win32 前台窗口和顶级窗口元数据，然后使用 `PrintWindow` 捕获目标窗口，以便不会被顶部覆盖的任何内容污染。如果 `PrintWindow` 对该窗口不可用，则它会回退到 .NET `CopyFromScreen`。 - 屏幕捕获使用 Windows 虚拟屏幕。 - 文本提取通过 UI 自动化尽力而为。 - 捕获必须在登录的交互式桌面会话中运行。纯 OpenSSH 会话可以构建和运行 `doctor`，但 Windows 阻止非交互式 SSH 服务会话的屏幕捕获。 ## 画廊 HTML 导出 `cloche gallery --html <path>` 写入一个自包含的 HTML 文件，其中每个捕获的图像都嵌入其中，以便结果可以共享而无需任何配套文件。将其与 `--root`、`--limit`、`--title` 和 `--open` 结合使用。JSON 输出增加了一个 `htmlPath` 字段，指向已写入的文件。 ## 发布打包 构建本地发布存档： ```bash bash scripts/package-release.sh ``` 在 Windows 上： ```powershell powershell -ExecutionPolicy Bypass -File scripts/package-release.ps1 ``` 存档文件写入 `dist/` 下。标记的 GitHub 版本由 `.github/workflows/release.yml` 为 Linux 和 Windows 打包。 ## 路线图 参见 [ROADMAP.md](ROADMAP.md)。