Cutter 是一个原生 macOS 静态截图工具，专注于快速完成区域选择、精确尺寸调整、标注、复制和存储。截图与标注数据默认只在本机处理，不上传到网络。
- macOS 14 或更高版本。
- 首次截图前，需要在“系统设置 → 隐私与安全性 → 屏幕录制”中允许 Cutter 读取屏幕内容。
- 全局快捷键为
⌥⌘2。
- 启动 Cutter。应用会驻留在菜单栏，不显示常规主窗口。
- 按
⌥⌘2，Cutter 会冻结主显示器画面。 - 悬停并单击窗口，或拖动鼠标建立自由区域选区。
- 使用选区手柄、尺寸输入、预设或标注工具调整截图。
- 选择“复制”“存储”“复制并存储”或“临时贴图”。
焦点不在尺寸输入框时，按 Return 会执行上次使用并记住的输出动作。
菜单栏“截图延时”提供立即、3 秒、5 秒和 10 秒，并记住上次选择。延时截图启动后，主显示器中央会显示一个不会进入最终截图的倒计时 HUD；再次按 ⌥⌘2 可以取消本次倒计时。HUD 会在真正读取屏幕前隐藏。
截图启动后默认进入智能窗口识别：
- 鼠标悬停时突出最前面的可捕获窗口，并显示应用名称和窗口标题。
- 单击锁定整个窗口，随后仍可使用尺寸、标注和输出工具。
- 在窗口上直接拖动会自动改为自由区域选择。
- 选区建立前按 Space 可以开关窗口识别。
- 窗口内容通过 ScreenCaptureKit 的独立窗口过滤器捕获，不使用冻结屏幕的矩形裁剪。
当前窗口识别范围是完整位于主显示器内、处于普通窗口层级的应用窗口；不包含 Cutter 自身窗口，也暂不包含窗口阴影和跨显示器窗口。
滚动截图使用“手动滚动、自动拼接”的方式，适合网页、文档、聊天记录和应用列表。全部图像在本机内存中处理，只有选择输出动作才会复制或存储。
- 按
⌥⌘2选中要截取的内容区域，保持矩形且暂不添加标注。 - 点击操作条上的“滚动截图”。选区至少为
120 × 120 pt；应避开固定页头、页脚和侧边栏。 - 在框内向下滚动一小段，稍停后继续，保留一部分上一屏内容供拼接。
- 浮动面板显示已拼接尺寸和状态，可暂停、继续或撤销末段。
- 点击“完成”打开长图预览，检查接缝后选择复制、存储、复制并存储或临时贴图。
长图预览提供“适合宽度”和“100%”，可滚动查看完整内容。取消捕获或关闭预览会丢弃本次未输出结果。
匹配不确定时不会追加新内容，请按提示往回滚一点，再缓慢继续。画面静止只表示没有新内容，不代表已到页面底部。首版仅支持主显示器固定区域的竖向向下拼接；尚不支持横向拼接、自动滚动、自动去除所有吸顶元素和长图标注。
长图最大高度为 32,768 像素，总像素和内存也有限制；达到上限后保留已完成部分供输出。详细设计与验收要求见 docs/SCROLLING_CAPTURE.md。
操作条始终显示全部工具，不需要展开二级工具面板。
形状和标注采用图标按钮，悬停可查看名称与快捷键。虚线矩形、正方形和圆形表示选区形状，实线矩形表示矩形标注；邮票使用打孔边框图标。绘图、文字标签、隐私处理、颜色和撤销通过间距与分隔线分组，复制、存储等输出动作保留文字。较窄屏幕会增加一行排列工具，不会折叠隐藏。
- 矩形
- 正方形
- 圆形
- 邮票：支持任意宽高，四边显示连续打孔预览，最终 PNG 输出透明半圆孔边缘。
选区建立后可以拖动八个手柄缩放，也可以在“选择”模式下拖动选区。移动选区时，文字标签、画笔、直线和箭头会保持相对位置并随选区一起移动。圆形和邮票模式会保留透明背景信息，因此适合输出带异形边缘的 PNG。
- 选择：选择和移动已有标注。
- 画笔：绘制自由路径。
- 直线：绘制直线。
- 箭头：绘制带箭头的直线。
- 数字：按顺序添加数字标签。
- 字母：按顺序添加字母标签；超过 Z 后继续使用 AA、AB 等编号。
- 矩形框：绘制矩形边界。
- 文本：在选区内输入说明文字。
- 高亮：使用半透明颜色标记一段内容。
- 马赛克：使用随机色块遮盖矩形区域。
- 模糊：使用随机低频纹理遮盖矩形区域。
标注提供红、橙、蓝、绿、黑五个快捷色块，旁边的原生颜色按钮可以打开 macOS 系统调色板，选择任意自定义颜色并使用系统保存的常用色块。快捷色和自定义色都会一致用于实时预览与最终导出。所有标注都可以选择、移动、删除、撤销和重做。
选中一个或多个标注后，操作条会显示上下文编辑区：
- 线宽：1、2、4、6、8 px。
- 字号：12、14、16、18、22、28、36 pt。
- 复制：以小偏移复制选中的标注。
- 前移 / 后移：调整标注绘制层级。
- 对齐：左、水平居中、右、顶部、垂直居中、底部。
按住 Shift 点击可以多选标注；线宽只作用于线条类标注，字号只作用于文本、数字和字母标注。
马赛克和模糊会使用与原始画面无关的随机内容覆盖区域，适合遮挡隐私信息；它们不会把原始像素送入模糊或像素化滤镜。矩形框、文本和高亮保留为当前会话内的可撤销标注。
宽度和高度使用截图像素，而不是界面点数。
- 修改输入框后，“应用”按钮会高亮。
- 应用成功后短暂显示“已应用”。
- 非法数值只标红对应输入框，并保留原输入供修改。
- 可以点击“应用”，也可以按 Return 提交尺寸。
- 正方形和圆形模式由宽度决定边长，高度输入会禁用。
如果要求的尺寸超出当前显示器，Cutter 会在显示器范围内保留尽可能大的选区，并更新输入框显示实际像素尺寸。
点击尺寸区域旁的“预设…”可以使用或管理常用截图大小。
内置预设：
200×200400×400800×6001280×720
自定义预设：
- 在宽高输入框中填写尺寸。
- 打开“预设…”。
- 选择“保存当前尺寸为预设”。
自定义预设会持久保存在本机。再次打开菜单即可直接应用；可通过“删除自定义预设”移除，删除前会确认。内置尺寸和已有自定义尺寸不会被重复保存。
非正方形预设会自动切换到矩形选区。应用预设后，预设按钮会显示当前尺寸。
| 快捷键 | 动作 |
|---|---|
⌥⌘2 |
从任意应用开始区域截图；倒计时期间再次按下可取消 |
| Return / 小键盘 Enter | 焦点不在尺寸输入框时，使用记住的输出动作完成截图 |
| Esc | 先退出当前标注工具；再次按下取消截图 |
| Space | 建立选区前切换智能窗口识别与自由区域模式 |
V |
选择工具 |
P |
画笔 |
L |
直线 |
A |
箭头 |
N |
数字标签 |
T |
字母标签 |
R |
矩形框 |
X |
文本 |
H |
高亮 |
M |
马赛克 |
B |
模糊 |
⌘Z |
撤销标注操作 |
⇧⌘Z |
重做标注操作 |
| Delete / Backspace | 删除选中的标注；未选择时删除最后一个标注 |
- 复制：将截图写入系统剪贴板。
- 存储：将 PNG 写入
~/Pictures/Cutter。 - 复制并存储：同时执行以上两个动作。
- 临时贴图：打开一个不写入文件的浮动图片窗口，可拖动、缩放和关闭。
上次使用的输出动作会保存在本机，并成为下次截图的默认动作。选择临时贴图时，截图只保留在当前浮动窗口中；关闭窗口后移除，不进入截图历史。完成后，菜单栏图标和提示文本会明确区分复制、存储、复制并存储和临时贴图。
- 开始截图。
- 查看截图方式；当前统一支持智能窗口和自由区域，全屏截图仍在计划中。
- 设置是否包含鼠标指针。
- 设置立即、3 秒、5 秒或 10 秒截图延时。
- 关闭所有临时贴图。
- 检查屏幕录制权限。
- 退出 Cutter。
使用 SwiftPM 构建开发可执行文件：
swift build如果当前 Command Line Tools 存在 SwiftPM PackageDescription ABI 不匹配，可使用直接编译脚本：
./scripts/build-dev.sh该脚本输出 .build/manual/CutterMac。新增 Swift 源文件时，也要把它加入 scripts/build-dev.sh 的显式文件列表。
构建并签名本地 .app：
./scripts/build-app.sh
open .build/Cutter.app首次构建本地应用前需要创建开发签名身份：
./scripts/create-local-signing-identity.sh该身份只保存在登录钥匙串中，不会写入仓库，也不是用于分发的 Apple Developer ID。
生命周期脚本：
./scripts/start.sh
./scripts/status.sh
./scripts/restart.sh
./scripts/stop.shCutter 使用 UserDefaults 保存：
- 是否包含鼠标指针。
- 上次使用的输出动作。
- PNG 存储目录。
- 自定义尺寸预设。
- 截图延时。
截图图像仅在当前捕获流程、剪贴板或用户选择的本机输出目录中使用。
.impeccable 同时可能包含共享设计决策和本机生成状态，因此不整体忽略：
- 可版本化：
config.json、design.json、surfaces/、经确认的mocks/，以及团队共享的critique/ignore.md。 - 不版本化：时间戳 critique 报告、
config.local.json、hook 缓存和live/运行状态。
后续 $impeccable polish 会读取本机最新的 critique 报告作为输入，因此完成或推翻报告中的建议后，应重新评审或删除过时报告，避免旧结论继续影响后续修改。
当前版本尚未实现：
- 全屏截图。
- 多显示器同时选择。
- 屏幕录制和视频处理。
架构与模块边界见 docs/ARCHITECTURE.md。
滚动截图的产品流程、拼接规则与验证记录见 docs/SCROLLING_CAPTURE.md。