@forsion/tangu-computer-use 0.5.8

package/native/macos/agent_highlight.swift

@@ -0,0 +1,229 @@
+import AppKit
+import SwiftUI
+
+/// 被操控窗口的边缘光效(Tangu 新增,非上游)。
+///
+/// 为什么放在 helper 里:光效必须画在**别人的 App 窗口**上,只有这个常驻的辅助进程能建一个悬在目标
+/// 窗口之上的覆盖层。Forsion 自己的窗口画不到别人身上。
+///
+/// 三条纪律:
+///  1. **绝不抢焦点、绝不吃事件** —— canBecomeKey=false + ignoresMouseEvents,与 AgentCursor 同款。
+///     否则「后台操控」这个前提就没了。
+///  2. **静态绘制,不做动画** —— 上游刚修过「光标空闲期一直重绘」(c089b30/5943c16)。呼吸灯要 120fps
+///     的 TimelineView 常驻跑,代价是操控期间一直烧 GPU。这里只画一圈静态辉光,只有几何真变了才重绘。
+///  3. **跟随窗口**:可见期间自己跑一个 8Hz 的 timer 拉 CGWindowList 的矩形(同步、便宜),几何没变
+///     就什么都不做。窗口没了(拿不到矩形)直接熄灯。
+
+/// 光效在最后一次动作后继续亮多久(秒)。短了会在连续动作之间闪烁,长了显得 agent 还在动。
+/// 顶层常量而非 static:@MainActor 类型的 static 不能当非隔离上下文里的默认参数(Swift 6 会报错)。
+private let highlightLingerSeconds: TimeInterval = 2.0
+private let highlightFollowInterval: TimeInterval = 0.125
+
+/// 覆盖层几何(光效与示意光标共用)。抽成顶层纯函数是为了可单测 —— 算错了不会报错,
+/// 只会"光标/光效画在看不见的地方",而那种错误只在特定的多屏摆位下出现,人工点验抓不住。
+enum OverlayGeometry {
+    /// 所有屏幕的并集(AppKit 坐标,主屏左下为原点)。覆盖层必须按它开,否则副屏上的点画在窗口之外。
+    static func union(of screenFrames: [CGRect]) -> CGRect {
+        screenFrames.reduce(CGRect.null) { $0.union($1) }
+    }
+
+    /// 全局 CG 点(左上原点,y 向下)→ 覆盖层内的画布坐标(窗口左上原点,y 向下)。
+    ///
+    /// 单显示器时 union=(0,0,W,H)、primaryHeight=H,结果**恒等于输入** —— 与只有主屏时的老行为一致。
+    /// 多显示器时:副屏在主屏上方 → union.maxY > primaryHeight,y 要相应下移;副屏在左侧 →
+    /// union.minX < 0,x 要相应右移。
+    static func canvasPoint(_ point: CGPoint, union: CGRect, primaryHeight: CGFloat) -> CGPoint {
+        CGPoint(x: point.x - union.minX, y: point.y + union.maxY - primaryHeight)
+    }
+}
+
+@MainActor
+final class AgentHighlight {
+    static let shared = AgentHighlight()
+
+    private var overlay: HighlightOverlayWindow?
+    private var hideTask: Task<Void, Never>?
+    private var followTimer: Timer?
+    private var generation: UInt = 0
+    private(set) var currentWindowId: UInt32 = 0
+    private var currentFrame: CGRect = .zero
+
+    /// 光效外扩多少点(辉光要向外晕开,覆盖层比目标窗口大一圈)。
+    private static let pad: CGFloat = 12
+
+    /// 点亮 / 续期(每次 act 调一次)。窗口矩形现查现用,调用方不必提供。
+    func show(windowId: UInt32, linger: TimeInterval = highlightLingerSeconds) {
+        guard let cgFrame = cgWindowBounds(windowId: windowId) else {
+            // 新目标定位不到(窗口刚关、或是没有 CG 窗口的菜单根)。**不能默默返回** ——
+            // 那会把光效留在上一个窗口上直到它自己的 linger 到期,等于指着错的窗口说"正在操作这里"。
+            if currentWindowId != 0 && currentWindowId != windowId { hide() }
+            return
+        }
+        place(windowId: windowId, cgFrame: cgFrame)
+
+        generation &+= 1
+        let mine = generation
+        hideTask?.cancel()
+        hideTask = Task { @MainActor in
+            try? await Task.sleep(for: .seconds(linger))
+            guard !Task.isCancelled, mine == self.generation else { return }
+            self.hide()
+        }
+        startFollowing()
+    }
+
+    func hide() {
+        hideTask?.cancel()
+        hideTask = nil
+        followTimer?.invalidate()
+        followTimer = nil
+        generation &+= 1
+        currentWindowId = 0
+        currentFrame = .zero
+        guard let window = overlay else { return }
+        window.orderOut(nil)
+        window.contentView = nil
+        window.close()
+        overlay = nil
+    }
+
+    /// 摆位(不续期):show 与跟随 timer 共用。
+    private func place(windowId: UInt32, cgFrame: CGRect) {
+        guard cgFrame.width > 1, cgFrame.height > 1 else { return }
+        let appKitFrame = AgentHighlight.toAppKit(cgFrame).insetBy(dx: -AgentHighlight.pad, dy: -AgentHighlight.pad)
+        let window = ensureWindow()
+        // 只有几何真变了才动窗口 —— 不变时 setFrame 也会触发一次重绘。
+        if currentWindowId != windowId || !AgentHighlight.nearlyEqual(currentFrame, appKitFrame) {
+            currentWindowId = windowId
+            currentFrame = appKitFrame
+            window.setFrame(appKitFrame, display: true)
+        }
+        if !window.isVisible { window.orderFrontRegardless() }
+        // ⚠️这里曾是 window.order(.above, relativeTo: Int(windowId)) —— 对**别的进程**的 window number
+        // 是空操作(实测:窗口既不上移也不消失)。跨进程的 z-order 只能靠 window level,见 init 里的 .floating。
+    }
+
+    private func startFollowing() {
+        guard followTimer == nil else { return }
+        let timer = Timer(timeInterval: highlightFollowInterval, repeats: true) { _ in
+            Task { @MainActor in AgentHighlight.shared.followTick() }
+        }
+        // .common:拖窗口/滚动时主 runloop 进 tracking mode,default mode 的 timer 会整个停掉 ——
+        // 而"用户拖窗口"恰好是最需要跟随的时刻。
+        RunLoop.main.add(timer, forMode: .common)
+        followTimer = timer
+    }
+
+    private func followTick() {
+        let id = currentWindowId
+        guard overlay != nil, id != 0 else {
+            followTimer?.invalidate()
+            followTimer = nil
+            return
+        }
+        guard let cgFrame = cgWindowBounds(windowId: id) else {
+            hide() // 窗口关了/最小化了,别把光效留在原地
+            return
+        }
+        place(windowId: id, cgFrame: cgFrame)
+    }
+
+    var isVisible: Bool { overlay?.isVisible == true }
+
+    private func ensureWindow() -> HighlightOverlayWindow {
+        if let overlay { return overlay }
+        let window = HighlightOverlayWindow(
+            contentRect: .zero,
+            styleMask: .borderless,
+            backing: .buffered,
+            defer: false
+        )
+        window.contentView = NSHostingView(rootView: HighlightView(inset: AgentHighlight.pad))
+        overlay = window
+        return window
+    }
+
+    /// CG 全局坐标(左上原点)→ AppKit 全局坐标(主屏左下原点)。
+    /// 主屏 = NSScreen.screens.first,**不是** NSScreen.main(后者是"当前有键盘焦点的屏")。
+    /// 拆出纯函数版是为了可测:算错就是整块光效系统性偏移一个屏高,肉眼在单屏下还未必看得出来。
+    nonisolated static func toAppKit(_ rect: CGRect, primaryHeight: CGFloat) -> CGRect {
+        CGRect(x: rect.minX, y: primaryHeight - rect.maxY, width: rect.width, height: rect.height)
+    }
+
+    static func toAppKit(_ rect: CGRect) -> CGRect {
+        toAppKit(rect, primaryHeight: NSScreen.screens.first?.frame.height ?? 0)
+    }
+
+    nonisolated static func nearlyEqual(_ a: CGRect, _ b: CGRect) -> Bool {
+        abs(a.minX - b.minX) < 0.5 && abs(a.minY - b.minY) < 0.5
+            && abs(a.width - b.width) < 0.5 && abs(a.height - b.height) < 0.5
+    }
+}
+
+/// 按 CG 窗口号取窗口矩形(CG 全局坐标,左上原点)。
+/// 顶层函数而非 Bridge 方法:AgentHighlight 是 @MainActor 单例,不该为了拿个矩形去持有 Bridge。
+/// 只用 CGWindowList(同步、便宜),不碰 ScreenCaptureKit —— 8Hz 跟随经不起异步捕获那条路。
+func cgWindowBounds(windowId: UInt32) -> CGRect? {
+    // ⚠️别换回 CGWindowListCreateDescriptionFromArray:它对**别的进程**的窗口恒返回空数组
+    // (实测同一个计算器 windowId,CreateDescriptionFromArray → count=0,
+    //  CopyWindowInfo(.optionIncludingWindow) → count=1 且 bounds 正确)。
+    // 这条曾让边缘光效整个功能静默失效 —— show() 在这里 return,窗口连建都没建。
+    // ⚠️还要看 kCGWindowIsOnscreen:`.optionIncludingWindow` 连**最小化 / 已隐藏**的窗口也照给
+    // bounds,拿它去摆光效 = 在目标已经不在屏上时,把光圈留在它原来的位置上闪。
+    guard let entries = CGWindowListCopyWindowInfo([.optionIncludingWindow], CGWindowID(windowId)) as? [[String: Any]],
+        let entry = entries.first(where: { ($0[kCGWindowNumber as String] as? NSNumber)?.uint32Value == windowId }),
+        (entry[kCGWindowIsOnscreen as String] as? Bool) == true,
+        let boundsDict = entry[kCGWindowBounds as String] as? [String: Any],
+        let bounds = CGRect(dictionaryRepresentation: boundsDict as CFDictionary)
+    else { return nil }
+    return bounds
+}
+
+/// 点击穿透、永不成为 key/main 的覆盖层。
+private final class HighlightOverlayWindow: NSWindow {
+    override var canBecomeKey: Bool { false }
+    override var canBecomeMain: Bool { false }
+
+    override init(contentRect: NSRect, styleMask: NSWindow.StyleMask, backing: NSWindow.BackingStoreType, defer flag: Bool) {
+        super.init(contentRect: contentRect, styleMask: styleMask, backing: backing, defer: flag)
+        isOpaque = false
+        backgroundColor = .clear
+        hasShadow = false
+        ignoresMouseEvents = true
+        // 宿主是 .accessory,永远不激活 → 普通层(0)的叠层会被"刚被激活的目标 App"直接压在下面,
+        // 用户什么也看不见。跨进程置顶只有 window level 一条路。光效用 .floating(3):盖住普通窗口,
+        // 但目标自己弹的菜单(popUpMenu=101)仍在它之上 —— 菜单本来就该盖住窗口边框的光。
+        level = .floating
+        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        isReleasedWhenClosed = false
+        hidesOnDeactivate = false
+    }
+}
+
+/// 静态辉光边框:由外到内几道圆角描边,越外越淡 —— 一次绘制,不动画。
+/// 颜色与 AgentCursor 同源(#FF7818),视觉上是同一个"agent 正在动手"的信号。
+private struct HighlightView: View {
+    let inset: CGFloat
+
+    private static let accent = Color(red: 1, green: 0x78 / 255, blue: 0x18 / 255)
+    /// (相对边框中心线的外扩量, 线宽, 不透明度)
+    private static let rings: [(CGFloat, CGFloat, Double)] = [
+        (7, 10, 0.10),
+        (3.5, 7, 0.22),
+        (0, 3, 0.85),
+    ]
+
+    var body: some View {
+        Canvas { graphics, size in
+            let base = CGRect(x: inset, y: inset, width: max(0, size.width - inset * 2), height: max(0, size.height - inset * 2))
+            guard base.width > 2, base.height > 2 else { return }
+            for (spread, width, opacity) in HighlightView.rings {
+                let rect = base.insetBy(dx: -spread, dy: -spread)
+                let path = Path(roundedRect: rect, cornerRadius: 12 + spread)
+                graphics.stroke(path, with: .color(HighlightView.accent.opacity(opacity)), lineWidth: width)
+            }
+        }
+        .ignoresSafeArea()
+        .allowsHitTesting(false)
+    }
+}

package/native/macos/agent_highlight_tests.swift

@@ -0,0 +1,99 @@
+import AppKit
+import CoreGraphics
+import Foundation
+
+/// 边缘光效里唯一「算错了肉眼未必看得出来」的部分:CG(左上原点)↔ AppKit(主屏左下原点)坐标换算。
+/// 单屏、窗口居中时偏一个屏高会直接飞出屏幕(看得见);但多屏或窗口贴边时会变成"贴在别的窗口上",
+/// 那种错误只在特定几何下出现,靠人工点验抓不住 —— 所以钉一组已知答案。
+@main
+struct AgentHighlightTests {
+    static func main() {
+        // ── 覆盖层几何(示意光标的"看不见"就出在这儿:覆盖层只开了主屏那么大)──
+        let primary = CGRect(x: 0, y: 0, width: 1600, height: 1000)
+        // 单屏:并集就是主屏,换算必须是恒等 —— 否则老的单屏行为就被改坏了
+        expect(
+            OverlayGeometry.union(of: [primary]) == primary,
+            "单屏时并集应等于主屏"
+        )
+        expect(
+            OverlayGeometry.canvasPoint(CGPoint(x: 300, y: 400), union: primary, primaryHeight: 1000)
+                == CGPoint(x: 300, y: 400),
+            "单屏时全局点到画布点必须是恒等换算"
+        )
+
+        // 副屏在主屏**右侧**:x 不变,y 也不变(并集顶边仍是主屏顶边)
+        let right = CGRect(x: 1600, y: 0, width: 1920, height: 1080)
+        let unionRight = OverlayGeometry.union(of: [primary, right])
+        expect(unionRight == CGRect(x: 0, y: 0, width: 3520, height: 1080), "并集应横向扩到两屏,高度取更高的那块")
+        // 副屏更高 → 并集顶边比主屏顶边高 80,全局 CG 的 y(从主屏顶边算)必须相应下移
+        expect(
+            OverlayGeometry.canvasPoint(CGPoint(x: 2000, y: 500), union: unionRight, primaryHeight: 1000)
+                == CGPoint(x: 2000, y: 580),
+            "右侧副屏更高时,画布 y 应比全局 y 多出并集顶边高出主屏的那 80"
+        )
+
+        // 副屏在主屏**左侧**:union.minX 为负,x 必须右移,否则画到覆盖层左边界之外(看不见)
+        let left = CGRect(x: -1920, y: 0, width: 1920, height: 1080)
+        let unionLeft = OverlayGeometry.union(of: [primary, left])
+        expect(
+            OverlayGeometry.canvasPoint(CGPoint(x: -500, y: 200), union: unionLeft, primaryHeight: 1000)
+                == CGPoint(x: 1420, y: 200 + unionLeft.maxY - 1000),
+            "副屏在左时 x 必须补上并集原点的负偏移"
+        )
+
+        // 副屏在主屏**上方**:并集顶边高过主屏顶边,y 必须下移
+        let above = CGRect(x: 0, y: 1000, width: 1600, height: 900)
+        let unionAbove = OverlayGeometry.union(of: [primary, above])
+        expect(unionAbove.maxY == 1900, "上方副屏应把并集顶边抬到 1900")
+        expect(
+            OverlayGeometry.canvasPoint(CGPoint(x: 100, y: 50), union: unionAbove, primaryHeight: 1000)
+                == CGPoint(x: 100, y: 950),
+            "副屏在上时 y 必须下移一个副屏高度"
+        )
+
+        let primaryHeight: CGFloat = 1000
+
+        // 顶到主屏顶部的窗口:CG y=0 → AppKit y = 屏高 - 窗高
+        expect(
+            AgentHighlight.toAppKit(CGRect(x: 10, y: 0, width: 300, height: 200), primaryHeight: primaryHeight)
+                == CGRect(x: 10, y: 800, width: 300, height: 200),
+            "窗口贴主屏顶部时,AppKit y 应为 屏高-窗高"
+        )
+
+        // 坐在主屏底部:CG maxY == 屏高 → AppKit y = 0
+        expect(
+            AgentHighlight.toAppKit(CGRect(x: 0, y: 800, width: 300, height: 200), primaryHeight: primaryHeight)
+                == CGRect(x: 0, y: 0, width: 300, height: 200),
+            "窗口贴主屏底部时,AppKit y 应为 0"
+        )
+
+        // 副屏在主屏上方:CG y 为负 → AppKit y 大于屏高(合法,不该被夹到 0)
+        expect(
+            AgentHighlight.toAppKit(CGRect(x: -400, y: -600, width: 300, height: 200), primaryHeight: primaryHeight)
+                == CGRect(x: -400, y: 1400, width: 300, height: 200),
+            "主屏上方的副屏窗口应换算出大于屏高的 AppKit y,不能夹紧"
+        )
+
+        // 宽高不参与换算
+        let converted = AgentHighlight.toAppKit(CGRect(x: 5, y: 5, width: 123, height: 456), primaryHeight: primaryHeight)
+        expect(converted.width == 123 && converted.height == 456, "换算不得改变尺寸")
+
+        // 抖动阈值:亚像素差算相等(否则每帧都 setFrame 重绘),半像素以上算变化
+        expect(
+            AgentHighlight.nearlyEqual(CGRect(x: 0, y: 0, width: 10, height: 10), CGRect(x: 0.2, y: 0, width: 10, height: 10)),
+            "亚像素抖动应视为未变化"
+        )
+        expect(
+            !AgentHighlight.nearlyEqual(CGRect(x: 0, y: 0, width: 10, height: 10), CGRect(x: 0, y: 0, width: 11, height: 10)),
+            "尺寸真变了必须视为变化"
+        )
+
+        print("agent highlight geometry checks passed")
+    }
+
+    private static func expect(_ condition: Bool, _ message: String) {
+        if condition { return }
+        FileHandle.standardError.write(Data("FAIL: \(message)\n".utf8))
+        exit(1)
+    }
+}