open-computer-use 딥다이브
— AI의 클릭 뒤에 있는 운영체제와 안전장치

1프로젝트 한줄 요약

open-computer-use는 AI 에이전트가 데스크톱 앱을 관찰하고 조작할 수 있게 해주는 오픈소스 MCP 서비스입니다. 앱 목록을 읽고, 창의 상태를 가져오고, 버튼을 누르고, 글자를 입력합니다. 스스로 모델을 학습하거나 다음 행동을 결정하는 부분은 이 서비스의 역할이 아닙니다.

이 저장소에서 배울 핵심은 “클릭 명령” 자체보다, 지금 보고 있는 앱과 실제로 조작할 앱이 같은지 확인하는 방법입니다.

1-1. 한 번의 작업은 세 단계로 읽는다

1. 관찰: 앱의 접근성 정보와 필요에 따른 스크린샷을 가져옵니다.
2. 실행: 현재 요소 번호나 스크린샷 기준 좌표를 이용해 도구를 호출합니다.
3. 확인: 결과 상태를 다시 읽고, 원했던 변화가 생겼는지 판단합니다.

macOS 구현에서는 packages/OpenComputerUseKit/Sources/OpenComputerUseKit/ComputerUseService.swift가 이 흐름의 중심입니다. getAppState()가 상태를 만들고, click() 등이 동작을 수행하며, actionResult()가 설정에 따라 후속 상태를 반환합니다.

// native MCP 클라이언트가 보내는 요청의 개념 예시
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_app_state","arguments":{"app":"TextEdit"}}}

// 결과에서 확인한 현재 요소 번호를 같은 세션에서 사용한다.
// 12는 설명용 번호이며, 실제 화면에서 얻은 값으로 바꿔야 한다.
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"click",
 "arguments":{"app":"TextEdit","element_index":"12"}}}

위 JSON은 구조를 읽기 쉽게 펼친 표현입니다. 이 서버의 stdio 통신에서는 요청마다 JSON을 한 줄로 직렬화하고 끝에 줄바꿈을 붙입니다. 여러 줄로 펼친 JSON을 그대로 보내면 readLine()이 메시지를 나누어 읽습니다.

같은 서비스를 두 가지 방식으로 호출할 수 있습니다. 일반 MCP 클라이언트는 네이티브 도구를 직접 호출합니다. Codex 플러그인 경로에서는 지속적인 JavaScript 실행 환경이 그 도구들을 감싸고, 모델에 js와 js_reset을 노출합니다. “도구가 2개”라는 설명과 “도구가 여러 개”라는 설명은 서로 다른 계층을 가리킬 수 있습니다.

2왜 주목받는가

2-1. 화면을 “사진”과 “구조”로 함께 다룬다

GitHub Trending Swift Weekly #4에 선정된 프로젝트로, 2026-10-23 기준 스타 2,645개와 포크 245개를 기록했습니다. README는 Codex Computer Use에서 영감을 받아 접근성 기반의 비침해적 자동화를 공개 구현했다고 설명합니다. 아래는 기능과 소스에 근거해 관심을 끌 만한 요인을 정리한 분석입니다.

첫째, 그림만 보고 좌표를 맞추는 방식에 구조화된 UI 정보를 더합니다. AccessibilitySnapshot.swift의 ElementRecord에는 역할, 제목, 값, 액션, 창 내부 위치가 담깁니다. “오른쪽 위의 파란 점”보다 “제목이 저장인 버튼”을 대상으로 삼을 근거가 생기는 셈입니다.

둘째, 사용 중인 데스크톱을 덜 방해하려는 설계가 구체적입니다. 앱을 대상으로 한 입력, 실제 포인터와 구분되는 소프트웨어 커서, 창을 별도 가상 디스플레이로 옮기는 경로가 있습니다. 다만 앱마다 접근성 지원이 다르고, 일반 복구 경로에는 활성화가 허용되는 경우도 있습니다.

셋째, 모델과 실행 엔진의 결합이 느슨합니다. 네이티브 MCP 서버와 여러 클라이언트용 설치 진입점이 있어, 하나의 AI 앱 전용 기능을 넘어 실행 도구를 재사용하는 구조를 볼 수 있습니다. 이것이 모든 클라이언트·모든 앱에서 같은 결과를 보장한다는 뜻은 아닙니다.

2-2. 무엇과 비교하면 장점이 분명해지는가

Codex와의 비교 범위는 README, docs/ARCHITECTURE.md, scripts/computer-use-cli/README.md의 설명 기준입니다. 이 자료는 경쟁 제품의 성능 순위나 성공률을 측정한 벤치마크가 아닙니다.

공개 구현의 교육적 가치는 “AI가 앱을 쓴다”는 결과를 관찰·검증·실행이라는 읽을 수 있는 코드로 나눠 보여준다는 데 있습니다.

2-3. README의 도구 수와 실제 목록은 다르다

최신 릴리스 문서 docs/releases/github/v1.1.2.md에는 움직이는 창에 대한 커서 정렬, Linux 동작 후 상태 읽기 설정 수정, 저장소 이름 변경에 따른 링크 정리가 기록되어 있습니다. 시각적 데모 뒤에서 상태 수명과 플랫폼 차이를 계속 다듬는 프로젝트라는 점도 읽을 거리입니다.

3기술 스택 전체 지도

3-1. 백엔드: 로컬 네이티브 실행 엔진

여기서 백엔드는 HTTP 서버와 데이터베이스가 중심인 웹 백엔드가 아닙니다. macOS의 핵심은 OpenComputerUseKit 라이브러리와 OpenComputerUse 실행 파일입니다. 기본 MCP 전송은 표준 입력·출력이며, 앱 호스트 경로에는 로컬 소켓 통신도 사용됩니다.

Package.resolved의 libwebp 고정 리비전은 2b5256c29ff4e20f2a0d5ee863b62b1a22144434입니다. WebPEncoding.swift의 losslessWebPData(for:)는 C 함수 WebPEncodeLosslessRGBA를 호출하고, defer로 WebPFree를 보장합니다. 의존성 목록과 실제 사용처를 연결해 읽기 좋은 사례입니다.

3-2. 프론트엔드: AppKit 권한 창과 커서, 그리고 코드 인터페이스

루트 package.json에는 React·Vue 같은 웹 UI 의존성이 없습니다. 이 저장소의 사용자 인터페이스는 네이티브 앱과 CLI에 가깝습니다. apps/OpenComputerUse/Sources/OpenComputerUse/PermissionOnboardingApp.swift는 AppKit 기반 권한 안내 창을 만듭니다.

• 권한 안내: PermissionOnboardingApp.launch()는 권한이 이미 충족되면 창을 열지 않습니다.
• 시각 피드백: SoftwareCursorOverlay.swift는 자동화의 커서를 표시합니다. 표시용 커서와 실제 시스템 포인터는 구분해서 읽어야 합니다.
• JavaScript 인터페이스: scripts/node-repl/open-computer-use-repl.mjs의 createCuaApi()가 cua.getApp(), app.click() 등을 제공합니다.
• CLI: npm 런처가 open-computer-use와 짧은 별칭 ocu를 제공합니다. js는 단발 평가, repl은 상태를 유지하는 터미널 세션입니다.

3-3. 인프라·빌드: npm은 네이티브 앱을 싣는 포장 상자

npm으로 설치된다는 사실과 실행 엔진이 JavaScript라는 사실은 같지 않습니다. 루트 package.json은 npm 게시를 막은 저장소 관리용 패키지이며, scripts/npm/build-packages.mjs가 배포용 패키지 메타데이터를 생성합니다.

Go SDK v1.4.1을 macOS MCP 서버의 의존성으로 오해하면 안 됩니다. macOS의 StdioMCPServer는 Foundation으로 JSON을 직접 처리하고, 해당 SDK는 별도 프로빙 CLI에 쓰입니다. Windows·Linux의 제품 go.mod에는 외부 require가 없습니다.

제품 빌드의 중심은 Swift Package Manager, Go, npm 패키징과 운영체제별 스크립트입니다. 별도 웹 프론트 빌드나 컨테이너를 필수 실행 경로로 가정할 근거는 없습니다. CI 파일의 존재는 설정된 절차의 증거이며, 특정 실행이 성공했다는 증거는 아닙니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

아래 그림에서 AI의 판단은 클라이언트 쪽에 있습니다. 로컬 실행 엔진은 관찰 결과를 돌려주고, 지정된 액션을 처리합니다. JavaScript 어댑터는 선택 가능한 상위 계층이며, 일반 MCP 클라이언트는 네이티브 서버로 바로 연결할 수 있습니다.

OpenComputerUseMain.run()은 명령을 파싱한 뒤 프록시 사용 여부를 먼저 판단합니다. 직접 mcp를 처리하는 분기에서는 ComputerUseService와 StdioMCPServer를 만들고, 커서 UI가 활성화되어 있으면 MCPAppRuntime.run(server:)으로 앱 이벤트 루프를 함께 유지합니다.

이것은 네트워크로 연결된 마이크로서비스 그림이 아닙니다. 라이브러리 내부 호출, 자식 프로세스의 파이프, 로컬 앱 호스트 통신을 한눈에 표시한 것입니다. 화살표마다 같은 종류의 통신이 일어난다고 생각하면 안 됩니다.

4-2. 패턴 ① 전송·분배·업무 로직을 나눈 계층 구조

packages/OpenComputerUseKit/Sources/OpenComputerUseKit/MCPServer.swift의 run()은 줄 단위 입력을 읽습니다. handle(line:)이 initialize, tools/list, tools/call 등을 구분하고, 도구 호출을 ComputerUseToolDispatcher.callTool(name:arguments:)에 넘깁니다.

// MCPServer.swift에서 도구 호출 분기만 발췌
case "tools/call":
    let name = params["name"] as? String ?? ""
    let arguments = params["arguments"] as? [String: Any] ?? [:]
    let result = try dispatcher.callTool(name: name, arguments: arguments)
    return try encodeJSONRPCResult(
        id: id,
        result: result.asDictionary
    )

분배기는 필수 문자열, 요소 번호, 옵션을 해석합니다. 예를 들어 strictObservationBool()은 include_ax를 문자열이나 숫자에서 느슨하게 변환하지 않고 진짜 JSON 불리언인지 확인합니다. 서비스는 이 값들을 받아 앱 관찰과 조작을 수행합니다.

실패도 두 층으로 구분해 읽어야 합니다. 알 수 없는 메서드는 JSON-RPC 오류 -32601로 응답하지만, 도구 실행 실패는 content와 isError가 담긴 결과로 돌아올 수 있습니다. 응답이 JSON으로 정상 도착했다는 사실만으로 클릭 성공을 판단해서는 안 됩니다.

4-3. 패턴 ② 클릭 전략 선택과 조건부 대체 경로

ComputerUseService.swift의 ClickMethod 열거형은 auto, accessibility, app_post, sky_click, global을 구분합니다. 인터페이스를 여러 클래스로 쪼갠 형태는 아니지만, 호출자가 선택한 전략에 따라 실행 경로가 달라지는 설계입니다.

요소를 지정한 auto 경로는 접근성 액션을 먼저 시도합니다. 처리되지 않으면 다른 입력 경로를 사용합니다. validateClickMethod()는 accessibility 방식에 요소 번호가 필요함을 검사하고, global에는 환경변수로 명시적 허용을 요구합니다.

여기서 중요한 조건은 OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1입니다. 기본 비접근성 대체 경로는 InputSimulation.clickTargeted(..., pid:)를 시도하지만, 전역 입력을 허용하면 prepareAppForGlobalPointerInput()과 clickGlobally() 경로를 사용할 수 있습니다.

자동화의 대체 경로는 성공률을 높이지만, 사용자에게 미치는 영향까지 바꿀 수 있으므로 조건과 부작용을 함께 읽어야 합니다.

또한 clickActionSnapshotRecoveryPolicy()는 sky_click에 읽기 전용 정책을 주고, 다른 방식에는 활성화를 허용하는 정책을 줍니다. “실제 포인터를 기본으로 움직이지 않는다”와 “어떤 경우에도 포커스를 바꾸지 않는다”는 다른 약속입니다.

4-4. 패턴 ③ 수명이 제한된 핸들과 유한한 탐색

packages/OpenComputerUseKit/Sources/OpenComputerUseKit/TargetedQuery.swift의 TargetedElementRegistry<Value>는 query 결과를 현재 네이티브 세션의 번호로 저장합니다. 첫 발급 번호는 1,000,001이고, 최대 5,000개를 보관하며, 기본 수명은 120초입니다.

// TargetedQuery.swift의 기본 설정을 발췌
static var indexBase: Int { 1_000_000 }

init(capacity: Int = 5000,
     lifetime: TimeInterval = 120,
     now: @escaping () -> Date = Date.init) {
    self.capacity = max(1, capacity)
    self.lifetime = lifetime
    self.now = now
}

이 번호는 영구 ID가 아닙니다. resolve()는 만료 여부와 앱 신원을 검사합니다. 신원에는 PID뿐 아니라 bundle identifier와 실행 시각도 들어갑니다. 프로세스가 재시작되어 같은 PID를 받더라도 이전 요소를 그대로 신뢰하지 않도록 하는 장치입니다.

ComputerUseService.snapshotForAction()은 조회 번호를 해석한 뒤, SnapshotBuilder.currentGeometry(of:in:criteria:)로 창 소속·역할·식별자·검색 조건·현재 프레임을 다시 확인합니다. 현재 요소를 다시 검증하는 단계에서 실패하면 해당 조회 번호를 삭제하고 오류를 반환합니다. 이 경로는 오래된 좌표로 조작을 계속하지 않습니다.

탐색 자체도 무한정 이어지지 않습니다. boundedTargetedWalk()는 큐와 방문 집합을 쓰는 너비 우선 탐색이며, 노드 수·결과 수·시간 제한·접근성 오류로 중단합니다. targetedSearch()는 2초의 협력적 마감 시간을 둡니다. 진행 중인 운영체제 호출을 정확히 2초에 강제 중단하는 보장은 아닙니다.

matches: []인데 truncated: true라면 “그 버튼이 없다”고 결론 내릴 수 없습니다. 찾지 못한 이유를 결과에 실어 보내는 설계는 검색 API와 데이터 수집기에도 유용합니다.

4-5. 패턴 ④ 정책과 부작용을 나눈 상태 머신

packages/OpenComputerUseKit/Sources/OpenComputerUseKit/LockedUseStateMachine.swift는 macOS 잠금 상태 작업 실험의 정책을 값 타입 struct로 표현합니다. Phase에는 idle, preparing, authorizing, unlocking, active, relocking, awaitingManualUnlock가 있습니다.

begin(), guardsPrepared(), consumePermit(), tick()은 전제 조건을 검사하고 상태를 바꾸거나 실행할 효과를 반환합니다. Effect의 prepareGuards·requestUnlock·requestRelock 같은 값은 실제 시스템 동작과 정책 판단을 구분합니다.

이 상태 머신의 시간 기준은 호출자가 전달하는 단조 증가 시간입니다. 허가 수명 5초, heartbeat 제한 3초, 유휴 제한 30초, 최대 임대 300초가 선언되어 있습니다. 이는 Locked Use 실험의 정책값이며 일반 MCP 호출의 공통 타임아웃이 아닙니다. docs/ARCHITECTURE.md는 전체 장애 행렬의 실증 검증이 아직 필요하다고 명시합니다.

4-6. 좌표 변환: 사진의 픽셀과 창의 포인트는 다르다

screenshotPixelScale()은 반환된 이미지의 픽셀 크기를 창 크기로 나누고, screenshotPixelToWindowPoint()는 클릭 픽셀을 그 비율로 나눕니다. 이미지 축소 설정이 있으므로 배율을 무조건 2로 고정하면 안 됩니다.

# ComputerUseService.swift의 좌표 계산을 숫자로 풀어쓴 예시
창 크기        = 1000 × 600 포인트
반환 이미지    = 1280 × 768 픽셀
x 배율, y 배율 = 1.28, 1.28
이미지 클릭점  = (640, 384)
창 내부 좌표   = (640 / 1.28, 384 / 1.28) = (500, 300)
# 이후 창의 전역 위치를 반영한다.
# AppKit 표시 좌표는 화면별 원점과 y축 방향도 구분한다.

screenStatePointToAppKitGlobalPoint()는 화면별 프레임을 사용해 커서 표시 좌표를 바꿉니다. “좌표 두 개를 넘긴다”는 API 뒤에도 이미지 크기, 창 위치, 화면 배치라는 서로 다른 기준이 있다는 점이 핵심입니다.

4-7. 세션 종료와 상태 읽기의 비용도 아키텍처다

일반 네이티브 경로는 기본적으로 액션 후 상태를 다시 읽습니다. 반면 REPL 어댑터는 OPEN_COMPUTER_USE_ACTION_READ_BACK=0을 사용해 액션의 자동 관찰을 줄이고, 코드가 필요한 지점에서 getAXState()를 호출하도록 합니다. 같은 클릭이라도 호출 계층에 따라 결과 사용법이 달라집니다.

WorkerJavaScriptSession.run()은 평가를 큐에 직렬로 넣습니다. 제한 시간을 넘으면 워커를 종료하고 새 워커를 시작하며 네이티브 세션도 끝냅니다. 이는 무한 반복문이 평가 워커를 붙잡는 문제에 대응하는 구조이지, 이미 대상 앱에 전달한 액션을 되돌리는 트랜잭션은 아닙니다.

StdioMCPServer.endSession()은 조회 인덱스를 비우고 커서·백그라운드 창 상태를 정리합니다. 각 ocu call 프로세스 사이에 요소 번호가 공유된다고 가정하면 안 됩니다. 여러 단계를 연결하려면 같은 네이티브 세션이 필요합니다.

5디렉토리 구조 해부

apps/는 “어떻게 시작하고 어떤 프로세스로 실행하는가”, packages/는 “실제로 무엇을 하는가”에 가깝습니다. experiments/는 이름만 보고 전부 제품 경로와 분리되어 있다고 단정하면 안 됩니다. 실제로 Package.swift는 그 안의 Locked Use 실행 파일도 타깃으로 선언합니다.

5-1. 첫 독해에 추천하는 파일 순서

1. Package.swift: 제품·라이브러리·실험·테스트 타깃의 연결부터 그립니다.
2. apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swift: 명령과 실행 경로를 찾습니다.
3. packages/OpenComputerUseKit/Sources/OpenComputerUseKit/ToolDefinitions.swift: 외부에 약속한 입력 스키마를 읽습니다.
4. 같은 디렉토리의 MCPServer.swift → ComputerUseToolDispatcher.swift → ComputerUseService.swift: 도구 하나만 추적합니다.
5. TargetedQuery.swift와 대응 테스트: 시스템 API와 독립적으로 이해할 수 있는 작은 알고리즘을 읽습니다.

AccessibilitySnapshot.swift는 2,616줄, ComputerUseService.swift는 2,346줄입니다. 처음부터 끝까지 읽기보다 query나 click 한 갈래를 검색해 따라가면 책임의 경계를 파악하기 쉽습니다.

5-2. 언어별 코드 규모

커밋 43eb4b5의 apps/, packages/, experiments/, scripts/에서 아래 확장자의 파일을 세었습니다. 빈 줄·주석·테스트를 포함한 줄바꿈 문자 수이며, 문서·외부 참고 번들·이미지·빌드 산출물은 집계 범위 밖입니다.

이 수치는 GitHub의 언어 비율과 다른 기준입니다. 예를 들어 Go 프로빙 CLI와 테스트용 Python 스크립트도 포함됩니다. “주 언어 Swift”라는 분류 아래 운영체제 연결과 배포를 위한 여러 언어가 있다는 점을 보여주는 지도입니다.

6학습 포인트 (기술별)

6-1. Swift: 값 타입과 참조 타입의 선택

SnapshotObservationOptions는 불리언 두 개를 가진 struct이고, ComputerUseService는 앱별 스냅샷을 유지하는 final class입니다. 작은 설정값과 공유 상태를 가진 서비스가 서로 다른 타입으로 표현되는 이유를 비교해 보세요.

// SnapshotObservationOptions.swift의 검증 메서드
public func validate() throws {
    guard includeAX || includeScreenshot else {
        throw ComputerUseError.invalidArguments(
            "At least one of include_ax or include_screenshot must be true"
        )
    }
}

오류 문구는 “접근성 정보와 스크린샷 중 적어도 하나를 포함해야 한다”는 뜻입니다. 두 옵션을 모두 끄는 조합을 입력 경계에서 거부합니다. 실습 아이디어: 가능한 네 조합을 적고 어떤 조합이 왜 실패해야 하는지 설명해 보세요.

이는 응답에서 필드만 숨기는 옵션이 아닙니다. rememberSnapshot()은 AX를 생략한 앱의 이전 스냅샷 별칭과 조회 번호를 정리합니다. 비용을 줄이는 설정이 후속 액션의 유효성에도 영향을 준다는 점을 함께 배울 수 있습니다.

6-2. Swift와 AppKit: 이벤트 루프와 스레드 경계

MCPAppRuntime.swift는 NSApplication.run()으로 UI 이벤트 루프를 유지하면서, processStandardIO()를 별도 스레드에서 처리합니다. 입력 스트림을 기다리는 일이 UI 이벤트 처리를 막지 않게 하는 구조입니다.

PermissionOnboardingApp와 주 진입점에는 @MainActor가 보이지만, 핵심 전체가 Swift actor만으로 구성된 것은 아닙니다. 기존 Thread·DispatchQueue·잠금도 함께 쓰입니다. 실습 아이디어: 표준 입력 읽기, 앱 종료, 커서 표시 각각이 어느 실행 경계에 놓이는지 표시해 보세요.

6-3. MCP와 JSON-RPC: 성공을 여러 층으로 나누기

ToolDefinitions.swift는 도구의 이름·설명·스키마를 만들고, ToolResult.swift는 텍스트와 이미지 블록을 결과로 묶습니다. 이미지 바이트는 base64 문자열로 전달됩니다.

실습 아이디어: 동일한 요청에 대해 ① 알 수 없는 메서드, ② 알 수 없는 도구, ③ 유효한 도구지만 잘못된 앱을 지정한 경우를 각각 어떤 경로가 처리할지 그려보세요. 통신 성공, 도구 성공, UI에서 의도한 변화는 구별해서 설명해야 합니다.

버전 선언도 확인할 가치가 있습니다. JS JsonLinePeer.initialize()는 2025-06-18을 요청하고, macOS 서버는 2025-03-26을 응답합니다. 요청 문자열이 같지 않다는 사실과 실제 호환성 검증은 별개의 문제입니다.

6-4. 알고리즘과 테스트: 데스크톱 없이도 탐색을 이해하기

boundedTargetedWalk()는 노드 조사와 자식 조회를 클로저로 받습니다. 진짜 창 대신 정수로 만든 가짜 그래프를 넣을 수 있습니다. 화면 자동화 코드 안에서도 순수한 탐색 로직을 뽑아낼 수 있다는 뜻입니다.

packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/TargetedQuerySafetyTests.swift에는 순환 그래프 중복 제거, 넓은 트리의 예산 제한, 만료, 다른 앱의 번호 거부를 검증하는 XCTest 코드가 있습니다. 실습 아이디어: testTraversalDeduplicatesCyclesAndStopsAtResultLimit()을 읽고 큐·방문 집합·결과 배열을 손으로 갱신해 보세요.

6-5. 이미지 처리: 품질·비용·정확도를 함께 보기

ImageCaptureConfig.swift의 기본값은 PNG, JPEG 품질 0.8, ScreenCaptureKit 캡처 제한 5초, 최대 긴 변 1,280픽셀, 초과 시 축소, 총 픽셀 수 64 미만 이미지 생략입니다. 64픽셀은 한 변의 길이가 아니라 면적입니다. 테스트는 7×9의 생략과 8×8의 허용을 구분합니다.

설정 우선순위는 환경변수 → JSON 파일 → 기본값입니다. 기본 파일 위치는 ~/.config/ocu/config.json이며 XDG_CONFIG_HOME이나 OPEN_COMPUTER_USE_CONFIG_FILE로 바뀔 수 있습니다. 실습 아이디어: 파일의 긴 변 제한이 640이고 유효한 환경변수가 800일 때의 결과를 예측하고 ImageCaptureConfigTests.swift와 대조해 보세요.

캡처 경로도 README의 짧은 설명보다 복잡합니다. WindowCapture.captureImage()는 허용되는 경우 SkyLight 하드웨어 캡처를 먼저 시도하고, 실패하거나 해당 경로를 사용할 수 없으면 ScreenCaptureKit으로 내려갑니다. SDK 이름 하나만으로 전체 경로를 설명하지 않는 연습이 됩니다.

6-6. Go·Python·PowerShell: API는 공유하고 구현은 바꾸기

두 Go 런타임은 //go:embed로 각 플랫폼의 스크립트를 포함합니다. Linux는 gi.repository.Atspi, Windows는 UIAutomationClient·UIAutomationTypes와 Win32를 사용합니다. 실행 파일에 스크립트가 들어 있어도 Python·PowerShell 등 실행 환경이 불필요해지는 것은 아닙니다.

실습 아이디어: 세 플랫폼의 get_app_state 옵션과 click_method를 표로 비교하세요. Linux의 app_post·sky_click 거부처럼 이름만 공유하는 옵션을 찾아야 합니다. 교차 플랫폼 설계의 목표는 호출 모양의 공통화이지 운영체제 기능의 완전한 동일화가 아닙니다.

6-7. Node.js: 상태 유지와 강제 종료의 경계

WorkerJavaScriptSession은 별도 워커를 사용하고, JsonLinePeer는 요청 ID와 대기 중인 응답을 관리합니다. AsyncLocalStorage는 지연된 콜백의 출력이 어느 평가에 속하는지 추적하는 데 쓰입니다.

// 준비된 macOS REPL 세션에서 수행하는 조회 예시
// TextEdit가 이미 실행 중이어야 한다. 아래 코드는 클릭하지 않는다.
var editor = await cua.getApp("TextEdit", { initialState: false });
var found = await editor.query({ role: "AXTextArea", limit: 10 });
nodeRepl.write(found);

// 실제 역할 이름은 앱이 노출하는 AX 정보에 따라 확인한다.
// found.matches뿐 아니라 truncated와 stop_reason도 함께 읽는다.

initialState: false는 바인딩 시 전체 스냅샷을 건너뛰게 합니다. 이어지는 query()는 화면 전체를 전송하는 대신 조회 결과를 반환합니다. 이 API는 macOS 전용이며, 새 세션에서는 기존 변수를 다시 바인딩해야 합니다.

세션을 재시작하면 코드의 변수는 지울 수 있지만, 이미 앱에 전달한 클릭이나 입력까지 취소되지는 않습니다. 실습 아이디어: 시간 초과 직전에 클릭이 전달된 경우를 가정하고, 재시도 전 무엇을 관찰해야 중복 실행을 피할지 적어보세요.

6-8. 배포와 검증: 설정 파일도 읽을 수 있는 설계다

release.yml은 GitHub Actions를 전체 커밋 SHA로 고정하고, 서명 인증서가 없으면 ad-hoc 서명으로 대체하는 분기를 둡니다. 이때 권한 식별자가 설치별로 달라질 수 있다는 안내도 있습니다. 공증 역시 자격 정보와 서명 조건에 따라 수행됩니다.

실습 아이디어: “태그 생성 → 릴리스 문서 검증 → 패키징 → 조건부 공증 → 아티팩트 업로드”를 그린 뒤, 인증서나 공증 자격 정보가 없을 때 어느 단계가 달라지는지 표시하세요. 워크플로 정의와 배포물의 실제 보증을 구분하는 연습입니다.

7하드웨어 / 시스템 요구사항

소스를 읽고 JSON·탐색 알고리즘을 공부하는 데는 대상 운영체제의 GUI 권한이 필요하지 않습니다. 실제 실행을 준비할 때는 플랫폼마다 다음 조건을 확인해야 합니다. 아래 조건은 저장소 선언과 구현에 근거합니다.

이 프로젝트의 실행 조건은 GPU 용량보다 운영체제의 접근성 지원, 로그인 세션, 권한, 대상 앱의 상태에 더 직접적으로 연결됩니다.

7-1. 권한 진단이 알려주는 것과 알려주지 않는 것

macOS doctor --json은 platform, accessibilityTrusted, screenCaptureGranted, allGranted, missingPermissions를 반환합니다. 이 경로는 권한 안내 창을 열지 않습니다. 권한이 없더라도 종료 코드가 0이므로 JSON의 필드를 확인해야 합니다.

PermissionDiagnostics.current()는 시스템 API와 저장된 TCC 진단 정보를 함께 사용합니다. allGranted: true는 특정 앱의 특정 버튼이 성공적으로 눌린다는 증명은 아닙니다. 권한 변경 뒤 프로세스 재시작이 필요한 경우가 있다는 점도 README에 적혀 있습니다.

7-2. 일반 사용과 Locked Use 실험은 준비물이 다르다

docs/locked-use.en.md는 서명된 앱과 Locked Use 구성요소를 요구하고, Guardian에 Accessibility·Input Monitoring 권한을 설명합니다. 일반 권한 안내를 마쳤다고 Locked Use가 자동으로 켜지는 것은 아닙니다.

Linux의 AT-SPI 입력을 모든 Wayland 환경에서 통하는 백그라운드 조작으로 이해해서도 안 됩니다. Linux 서버 안내는 의미 기반 액션을 우선하며, 좌표·키 합성은 환경에 따라 성공을 보장하지 않는 대체 경로로 설명합니다. Windows·Linux는 docs/ARCHITECTURE.md에서 실험적 런타임으로 분류합니다.

8직접 해볼 수 있는 실습 과제

아래 다섯 과제는 소스 읽기와 독립적인 작은 모형으로 수행할 수 있습니다. 실제 앱 조작과 시스템 잠금 설정은 요구하지 않습니다. 각 과제는 결과물을 남겨 이해 여부를 확인하도록 구성했습니다.

# 운영체제 API를 부르지 않는 학습용 Python 함수
def to_window(point, image_size, window_size):
    scale_x = image_size[0] / window_size[0]
    scale_y = image_size[1] / window_size[1]
    return (point[0] / scale_x, point[1] / scale_y)

# 유효한 크기를 전제로 한 예시
# point=(640,384), image_size=(1280,768), window_size=(1000,600)
# 기대 결과: (500.0, 300.0)

# 작은 가짜 그래프
0 -> [1, 2]
1 -> [0]
2 -> []

# 모든 노드가 일치하며, 자식 조회는 잘리지 않는다고 가정
maxNodes = 10
limit = 10
expired = false

좋은 실습 결과물은 “한 번 성공했다”는 화면보다, 어떤 입력과 상태에서 성공하거나 거부되어야 하는지 설명하는 표입니다.

9관련 기술 심화 학습 로드맵

주당 3~5시간을 가정한 학습 순서입니다. 처음부터 모든 언어를 익히기보다, 익숙한 언어로 작은 모형을 만든 뒤 원래 Swift 구현과 비교하면 진도를 유지하기 쉽습니다.

한 기능을 끝까지 추적하는 능력이 생기면, 익숙하지 않은 언어가 섞여 있어도 시스템의 경계부터 이해할 수 있습니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 읽기 순서

• 공식 GitHub 저장소 · 프로젝트 개요와 진입점.
• v1.1.2 릴리스 · 2026-10-17 배포 기준점.
• 분석 기준 커밋 43eb4b5 · 이후 변경과 구분하는 고정 기준.
• Package.swift · Swift 타깃·macOS 하한·고정 의존성.
• 아키텍처 문서 · 플랫폼 경계와 실험의 상태. 중국어 문서입니다.
• 이미지 설정 안내 · 기본값과 환경변수 우선순위.
• macOS query 안내 · 옵션·불완전 결과·세션 수명.
• Locked Use 안내 · 일반 자동화와 다른 구성요소·권한.

11-2. 핵심 구현으로 바로 가기

• MCPServer.swift · 표준 입출력, 초기화, 요청 분기, 세션 정리.
• ToolDefinitions.swift · macOS의 실제 11개 도구와 스키마.
• ComputerUseService.swift · 클릭 전략, 좌표 변환, 스냅샷·조회 결과 사용.
• AccessibilitySnapshot.swift · 접근성 수집, 캡처와 현재 요소 재검증.
• TargetedQuery.swift · 번호 레지스트리와 유한한 BFS.
• TargetedQuerySafetyTests.swift · 순환·만료·잘못된 신원에 대한 학습 예제.
• JavaScript REPL 어댑터 · 앱 API, JSON 줄 통신, 워커 수명.
• 릴리스 워크플로 · 빌드·서명·조건부 공증·배포물 생성 절차.

11-3. 관련 기술의 공식 문서

• Swift Package Manager 문서 · 패키지·제품·타깃의 관계를 학습할 출발점.
• Apple AXUIElement 문서 · macOS 접근성 요소 API.
• Apple ScreenCaptureKit 문서 · 창과 화면 캡처 관련 API.
• MCP 2025-03-26 전송 규격 · stdio 메시지 구분과 표준 오류 출력 규칙.
• Microsoft UI Automation 개요 · 이 프로젝트가 사용하는 관리형 접근성 API의 배경.
• GNOME AT-SPI 공식 문서 · Linux 접근성 객체·액션·텍스트 인터페이스.
• Go embed 패키지 문서 · 빌드 시 스크립트 파일을 실행 파일에 포함하는 원리.
• Node.js 24 Worker 문서 · 메시지 전달과 워커 종료 API.

공식 전송 규격에서 stdio는 줄바꿈으로 메시지를 구분하고, 로그는 표준 오류로 분리합니다. 따라서 예시 JSON을 보기 좋게 여러 줄로 표시한 것과 실제 전송 형식은 구분해야 합니다. 실제 요청은 한 줄로 직렬화합니다. MCP stdio 규격

현재 상태 (2026-10-23 확인)