📸 mac screenshot — macOS截图

使用内置工具在 macOS 上捕获截图。

默认工作流程

• 对于全屏捕获，使用 screencapture -x 。
• 对于特定应用窗口，首先尝试使用内联 Swift + CoreGraphics 枚举窗口。
• 按 owner 和 name 过滤返回的窗口，匹配用户给出的关键词如 weixin、wechat 或应用名称。
• 优先选择 sharing 为 1 的窗口。
• 使用 screencapture -x -l 捕获精确窗口。
• 保存在工作区下。
• 默认返回本地路径。
• 只有在用户明确要求时才将截图发送到当前聊天或附加到当前聊天。
• 将截图视为潜在敏感数据，因为它们可能包含机密屏幕信息。

脚本路径

优先使用捆绑的脚本：

scripts/capture-window-by-keyword.sh  [output_path]
scripts/capture-window-by-keyword.sh --list 
scripts/capture-window-by-keyword.sh --index   [output_path]

示例：

scripts/capture-window-by-keyword.sh wechat
scripts/capture-window-by-keyword.sh --list wechat
scripts/capture-window-by-keyword.sh --index 2 wechat

该脚本：

• 使用内联 Swift + CoreGraphics 枚举屏幕上的窗口
• 按关键词针对 owner 和 name 过滤
• 支持别名匹配，例如 weixin -> wechat, wx
• 可以在不捕获的情况下列出多个匹配项
• 可以通过 1-based 索引捕获特定匹配项
• 否则优先选择 sharing = 1 的窗口
• 使用 screencapture -x -l 捕获精确窗口
• 输出 PNG 路径
• 默认返回本地工件
• 只有在用户明确要求发送到聊天时才附加或发送 PNG

按关键词定位窗口的可靠方法

使用此精确模式来定位候选窗口：

swift - <<'SWIFT'
import CoreGraphics
import Foundation
let options = CGWindowListOption(arrayLiteral: .optionOnScreenOnly, .excludeDesktopElements)
let windows = (CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]]) ?? []
let matches = windows.compactMap { w -> [String: Any]? in
    let owner = (w[kCGWindowOwnerName as String] as? String) ?? ""
    let name = (w[kCGWindowName as String] as? String) ?? ""
    let low = (owner + " " + name).lowercased()
    guard low.contains("weixin") || low.contains("wechat") else { return nil }
    return [
        "id": w[kCGWindowNumber as String] ?? "",
        "owner": owner,
        "name": name,
        "sharing": w[kCGWindowSharingState as String] ?? "",
        "bounds": w[kCGWindowBounds as String] ?? ""
    ]
}
let data = try! JSONSerialization.data(withJSONObject: matches, options: [.prettyPrinted])
print(String(data: data, encoding: .utf8)!)
SWIFT

典型成功指标：

• owner 或 name 匹配请求的应用/窗口
• id 存在
• sharing = 1

然后捕获窗口：

screencapture -x -l  

经验教训/成功标准

• 不要依赖 Python Quartz；它可能未安装。
• 不要依赖 System Events 窗口属性来获取窗口 ID；某些应用不能可靠地暴露 AXWindowNumber。
• 内联 Swift 调用 CGWindowListCopyWindowInfo 是 macOS 上最可靠的内置方法。
• screencapture -l 是真正的系统窗口捕获，而不是裁剪的全屏图像。
• 如果枚举成功但捕获失败，请检查目标窗口是否可共享且在屏幕上。

故障排除

如果 screencapture 全屏有效但窗口无效

检查枚举的目标是否具有 sharing = 1。如果没有，告诉用户该应用/窗口当前不可用于窗口捕获，并要求他们将其置于前台后重试。

如果 System Events 说辅助访问不允许

不要依赖该路径。优先使用 Swift + CoreGraphics 方法。如果用户仍想要 UI 结构检查，告诉他们启用：

• 系统设置 → 隐私与安全 → 辅助功能
• 为运行代理的实际主机进程打开访问权限，通常是 openclaw-gateway、Terminal 或活动终端主机

如果屏幕捕获被阻止

告诉用户启用：

• 系统设置 → 隐私与安全 → 屏幕与系统音频录制（或旧版 macOS 上的屏幕录制）
• 为运行命令的实际主机进程授予权限

如果找不到 swift

告诉用户手动安装 Xcode Command Line Tools：

xcode-select --install

输出位置

优先将截图保存到工作区子目录，例如：

• screenshots/
• captures/

当用户可能请求多次捕获时，使用带时间戳的描述性文件名。

隐私和聊天传递规则

将截图视为潜在的敏感本地工件。当截图请求来自聊天界面时：

• 首先捕获截图
• 默认保存在本地
• 只有在用户明确要求传递或附加时才将 PNG 发送到当前聊天
• 如果明确要求传递且有明确的消息工具可用，优先使用它将文件发送到当前对话