agent-desktop은(는) 무엇을 하나요?
agent-desktop은 AI 에이전트가 운영 체제 접근성 트리를 통해 데스크톱 앱을 관찰하고 조작할 수 있게 해주는 CLI입니다. 이는 에이전트가 아니라 도구입니다. 모든 명령은 하나의 JSON 봉투(ok, data 또는 error)를 출력합니다. 관찰, 행동, 검증 루프는 사용자가 직접 실행합니다.
셸 문법
예제는 POSIX 셸을 사용합니다. PowerShell에서는 모든 ref를 따옴표로 묶으세요('@s8f3k2p9:e1'). 왜냐하면 @token이 스플랫 연산자이기 때문입니다. export 대신 $env:NAME = 'value'를 사용하고, $(...) 및 jq 대신 | ConvertFrom-Json을 사용하세요. Windows 스킬에 PowerShell 형식이 있습니다.
사전 점검
태스크의 첫 번째 명령어 전에 이를 실행하세요. 도구가 설치되는 유일한 곳입니다.
-
agent-desktop version을 실행합니다. 종료 코드 0이면 CLI가 있는 것입니다: 4단계로 가세요. -
없으면 npm으로 설치하세요. npm만 지원되는 경로입니다:
npm install -g agent-desktopHomebrew, Scoop, 다운로드 아카이브 또는 이전 버전을 시도하지 마세요. 이 스킬은 npm이 확인하는 버전을 기준으로 합니다.
npm이 PATH에 없으면node -v와where npm(Windows) 또는which npm(macOS, Linux)을 실행하고 찾은 결과를 보고하세요. 다른 패키지 매니저를 추측하지 마세요. -
agent-desktop version을 다시 실행합니다. 여전히 실패하면 중단하고 사용자에게 다음을 알리세요: 설치 출력의 마지막 20줄,agent-desktop --help가 실행되는지 여부, 그리고 현재 OS. 스스로 스크린샷이나 마우스 자동화로 대체하지 마세요. -
agent-desktop status를 실행합니다. 플랫폼, 권한 및supported_surfaces를 보고합니다. macOS에서 접근성 권한이 없는 경우 여기에 표시됩니다. 사용자에게 직접 권한을 부여하려고 시도하지 말고agent-desktop permissions --guide를 실행하라고 알리세요. -
agent-desktop skills get platform을 실행합니다. 바이너리가 실행되는 OS(macOS, Windows, Linux)에 맞는 스킬을 로드하며, 이 파일과 충돌하는 경우 해당 스킬이 우선합니다. -
플래그와 구문은
agent-desktop <command> --help를 실행하세요. 이 스킬은 플래그 목록을 반복하지 않으므로--help가 항상 설치된 버전과 일치합니다.
agent-desktop skills get desktop이 이 파일과 다른 규칙을 출력하면 바이너리가 옳습니다: 이 파일은 복사본이고 바이너리가 실제로 구동하는 것입니다.
루프
역할이나 정확한 이름을 알 때 find를 사용하세요. 그렇지 않으면 먼저 앱을 매핑하고 한 영역을 드릴다운하세요.
agent-desktop snapshot --skeleton --app "Notes" -i --compact # 얕은 맵, 잘린 가지에 children_count
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 한 영역 드릴다운
agent-desktop click @s8f3k2p9:e12 # 정규화된 ref에 행동
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact # 검증: 같은 영역 다시 읽기
- 작은 앱은 스켈레톤이 필요 없습니다. 전체
snapshot -i를 찍으세요. -i는 대화형 노드만 유지하므로, 행의 정적 텍스트 레이블은 제거됩니다. 반복되는 버튼이 어떤 행에 속하는지 알려면--root로 해당 행의 컨테이너를 드릴다운하고-i를 빼세요. Windows와 Linux에서는 행을 읽지만 버튼을 실행 가능하게 만들지는 않습니다: 다른 행에서 반복되는 버튼은 창에서 쌍둥이이며 해당 ref가 거부됩니다(Refs 참조).--root드릴은 동일한 스냅샷 ID에 ref를 추가합니다. 드릴된 서브트리 외부의 ref와 드릴된 루트 자체는 유효합니다. 이미 내부에 있던 ref는 대체되므로, 그곳의 오래된 ref는STALE_REF를 반환합니다.- 서피스(
--surface menu,sheet,alert)는 스켈레톤을 절대 수행하지 마세요. 서피스는 이미 포커스되어 있습니다. - 메뉴, 시트 또는 알림을 여는 행동은
data.surfaces에 나열됩니다. 다음으로 해당 오버레이를 대상으로 하세요. - 비동기 단계 후에는
wait를 사용하세요(references/commands-system.md참조). 고정된 sleep은 레이스 조건을 유발합니다.
Refs
- 출력 ref는 정규화됩니다:
@<snapshot_id>:e<N>, 예:@s8f3k2p9:e1. 이후 명령어에 그대로 전달하세요. - Ref는 하나의 스냅샷에 유효합니다. UI가 변경된 후에는 영향을 받은 영역을 다시 드릴하거나 새 스냅샷을 찍으세요.
- 주소 지정 가능한 요소만 ref를 받습니다. 정적 텍스트와 비활성 컨테이너는 ref를 받지 않습니다.
- 명령어는 행동하기 전에 요소를 재식별합니다. macOS에서 ref는 요소 자체의 주소를 전달하므로, 동일한 쌍둥이는 각각의 ref를 유지합니다. Windows와 Linux에서 ref는 해당 스냅샷이 캡처한 창에서 역할, 네이티브 ID, 이름 및 설명과 일치하는 요소가 창에 유일할 때만 확인됩니다. 스켈레톤이나 깊이 절단 아래에서도 계산되며, 정확히 하나의 라이브 요소가 여전히 일치해야 합니다. 그곳의 동일한 쌍둥이는 ref 경로가 없습니다:
--headed mouse-click --xy X,Y만이 하나를 선택할 수 있으며, 이는 포그라운드 창을 대상으로 하고 Linux Wayland 세션에서는 거부됩니다. STALE_REF: 요소가 사라졌거나 더 이상 일치하지 않습니다.details.kind는saved_ref_absent또는 macOS에서는retained_object_stale입니다. 새 스냅샷을 찍고 새 ref를 사용하세요.AMBIGUOUS_TARGET: 동일한 요소가 나타났거나(saved_ref_ambiguous), ref가 캡처 시점에 고유함이 입증되지 않았습니다(identity_not_unique). ref를 반복하거나 동일한 쌍둥이를 다시 스냅샷 찍으면 동일한 거부가 발생합니다. 창에서 고유한 컨트롤에 행동하세요.identity_not_unique는 전체 창을 제때 읽지 못한 스냅샷 이후에도 발생합니다: 더 큰--timeout-ms로 다시 시도하세요.details.kind: resolution_identity_unknown와 함께TIMEOUT: 라이브 읽기가 응답하지 않아 정체가 입증되지 않았습니다. 아무것도 전송되지 않았습니다. 재시도하세요.SNAPSHOT_NOT_FOUND: 스냅샷 ID가 만료되었습니다. 다시 스냅샷을 찍으세요.
전달 및 재시도
행동 결과는 data.disposition을, 오류는 error.disposition을 전달하며, 각각 delivery와 retry를 포함합니다. snapshot과 같은 관찰 명령어는 성공 시 disposition이 없습니다. 해당 오류와 모든 INVALID_ARGS 거부는 not_delivered와 retry: safe를 전달합니다.
disposition.retry가safe인 경우에만 행동을 재시도하거나 대체하세요.not_delivered만 안전합니다.- 다른 전달 값은 행동이 전달되었을 수 있음을 의미합니다. 반복하면 클릭, 입력 또는 제출이 두 번 발생할 수 있으며,
toggle은 자체를 취소할 수 있습니다. - 안전하지 않은 결과가 나오면 라이브 상태(
get,is또는 새 스냅샷)를 읽고 결정하세요.details.post_state가 있을 때 도움이 됩니다. error.code와error.disposition에 따라 분기하세요. 메시지와 제안 텍스트는 변경될 수 있습니다.details.retryable: false는 기다려도 결과가 바뀌지 않음을 의미합니다. 다른 접근 방식을 시도하세요.
Headless 및 Headed
Ref 행동은 기본적으로 headless입니다. 시맨틱 접근성 호출을 사용하며 포커스를 차지하거나, 커서를 이동하거나, 키를 합성하거나, 클립보드를 사용하지 않습니다. 시맨틱 경로가 없으면 행동은 실패로 닫힙니다. 더블 클릭, 호버, 드래그 또는 포커스와 같은 물리적 입력이 사용자에 의해 명시적으로 허용된 경우에만 전역 --headed 플래그를 사용하세요. headless 실패에서 복구하기 위해 headed 모드로 전환하지 마세요. 원시 좌표(--xy)는 절대 포커스를 암시하지 않습니다. 어떤 행동이 --headed가 필요한지는 OS에 따라 다릅니다: 플랫폼 스킬을 읽으세요.
참조
필요할 때만 로드하세요: agent-desktop skills get desktop <reference>.
| 참조 | 열어야 하는 경우 |
|---|---|
commands-observation | snapshot, find, get, is, screenshot, list-surfaces 의미론, 부분 트리 또는 --root 규칙이 필요할 때 |
commands-interaction | click, type, set-value, select, toggle, scroll, press, mouse 명령어 중에서 선택하거나 행동 오류를 디버깅할 때 |
commands-system | 앱을 실행/종료하거나, 창을 관리하거나, 클립보드를 사용하거나, wait, batch, 세션, 다중 에이전트 커서, 트레이싱 또는 스킬을 로드할 때 |
workflows | 작업된 패턴(양식, 메뉴, 대화 상자, 새 창 대기, 스크롤-찾기, 드래그)과 안티패턴 목록을 원할 때 |