BraveCowNoFear/desktop-control-for-windows

Windows용 데스크탑 제어

개요

이 스킬을 사용하면 마치 빠른 인간처럼 보이는 Windows UI를 조작할 수 있습니다: 스크린샷 촬영, 픽셀 분석, 대상 창 활성화, 번들 스크립트를 통한 키보드/마우스 작업 실행. 활성 워크플로우는 로컬 Python 자동화만을 사용합니다.

이 스킬에는 두 가지 역할이 있습니다:

• Coordinator(조정자): UI 워커가 아닌 모든 깊이의 에이전트. 가시적인 UI 제어가 필요한지 판단하고, 위임이 가능할 때 하나의 UI 작업을 워커에게 위임하며, 위임이 진정으로 불가능할 때만 도구/정책 차단을 보고합니다.
• UI Worker(UI 워커): 이미 위임받은 에이전트로, 스크린샷을 촬영하고, 픽셀을 검사하며, scripts/ui_control.py를 직접 실행합니다.

필수 위임 게이트: 실시간 Windows UI 제어 작업에 대해, 먼저 주어진 프롬프트에서 자신의 역할을 결정하십시오. 이 UI 작업을 위해 명시적으로 UI 워커/스크린 제어 워커로 생성되지 않았다면, 더 큰 작업의 하위 에이전트라 할지라도 Coordinator입니다. 스크린샷을 촬영하거나, 스크린샷을 보거나, scripts/ui_control.py를 호출하거나, 실시간 화면 이미지를 직접 검사하지 마십시오. 정확히 하나의 전담 UI Worker에게 위임하십시오. spawn_agent 또는 이에 상응하는 위임 도구를 사용할 수 있을 때, 이 스킬의 활성 사용은 워커를 생성할 수 있는 권한입니다. 사용자에게 매직 워드, 암호 또는 추가 확인을 요청하지 마십시오. 이미 UI Worker이거나 이 스킬 자체를 디버깅/편집하는 경우에만 위임을 건너뛰십시오.

재귀적 UI Worker 위임 금지: 일반 작업 에이전트는 2~3단계 깊이로 중첩될 수 있으며, 여전히 자신의 가시적 UI 단계를 위해 하나의 전담 UI Worker를 생성할 수 있습니다. 하지만 리프(leaf) UI Worker 자체는 추가 에이전트를 생성하거나, 위임하거나, 메시지를 보내거나, 대기해서는 안 됩니다. 번들 스크립트를 사용하여 로컬에서 UI 작업을 수행하고 간결한 텍스트 보고서를 반환하십시오.

전역 UI 잠금: 모든 활성 UI Worker는 scripts/ui_control.py를 통해 하나의 잠금 파일을 공유합니다. UI Worker는 UI 단계 시작 시 잠금을 획득하고, 반환된 --lock-token을 모든 스크린샷/창/마우스/키보드/클립보드 명령에 전달하며, 반환하기 전에 잠금을 해제해야 합니다. 다른 Worker가 이미 잠금을 보유하고 있으면 대기하거나, partial 상태와 함께 사용 중인 잠금 세부 정보를 반환합니다. 이는 병렬 에이전트가 마우스, 키보드, 포그라운드 창 또는 클립보드를 놓고 경쟁하는 것을 방지합니다.

로케일 인식 텍스트 입력: WeChat 파일 전송 도우미와 같은 명명된 UI 대상을 검색하기 전에, UI 잠금을 보유한 상태에서 앱 언어/표시 레이블을 먼저 검사하십시오. UI가 중국어인 경우, type ... --decode-unicode-escapes --method paste 또는 clipboard set ... --decode-unicode-escapes 명령에 중국어 레이블을 ASCII 유니코드 이스케이프(예: \u6587\u4ef6\u4f20\u8f93\u52a9\u624b)로 전달하십시오. 중첩된 프롬프트, 셸 인수 또는 명령 파일을 통해 원시 중국어를 입력하지 마십시오. UI가 영어인 경우, 영어 레이블 또는 filehelper와 같은 ASCII 안전 별칭을 사용하십시오. 언어를 확인할 수 없는 경우, 스크립트를 통한 유니코드 이스케이프 입력을 원시 비ASCII 텍스트보다 선호하고, 결과 대상을 확인한 후에 작업을 수행하십시오.

소스: 로컬 데스크탑 제어 패턴을 위해 ClawHub breckengan/control v1.0.0에서 마이그레이션되었습니다.

마이그레이션 범위

마이그레이션된 로컬 제어 기능: 절대/상대 마우스 이동, PyAutoGUI를 통한 부드러운 지속 시간 이동, 왼쪽/오른쪽/가운데/더블 클릭, 마우스 누름/떼기, 길게 마우스 누르기, 드래그, 세로/가로 스크롤, 마우스 위치, 키 입력 또는 클립보드 붙여넣기를 통한 텍스트 입력, 단축키, 키 누름/떼기, 키 누르기, 스크린샷, 영역 스크린샷, 픽셀 색상, 이미지 매칭, 화면 크기, 창 목록/활성화/정보/최소화/최대화/복원/닫기, 클립보드 설정/가져오기, failsafe, 선택적 승인, 엄격한 경계 검사, JSONL 작업 로깅 및 배치 플랜.

의도적으로 복사하지 않음: 업스트림 데모 스크립트와 규칙 기반 ai_agent.py 앱 데모. Codex에서는 고수준 추론이 활성 에이전트 루프에 남아 있어야 하며, plan은 결정적 배치 처리를 위해 사용합니다.

Coordinator 프로토콜 (UI Worker가 아닌 에이전트)

모든 실제 UI 제어 작업에 대해, Coordinator는 현재 런타임 정책이 에이전트 위임을 허용할 때마다 하나의 UI Worker에게 위임해야 합니다. Worker는 스크린샷, 시각적 검사 및 UI 실행을 수행합니다. Coordinator는 스킬 구현을 디버깅하지 않는 한, 스크린샷을 촬영하거나, 스크린샷을 보거나, scripts/ui_control.py를 실행하거나, 화면 이미지를 직접 검사해서는 안 됩니다. 이렇게 하면 화면 픽셀, 개인 창 콘텐츠 및 시각적 추론이 기본 대화 컨텍스트에서 유지됩니다.

직접 제어 불가 폴백: Coordinator가 UI Worker를 생성하거나 메시지를 보낼 수 없는 경우(런타임 정책이나 도구 가용성으로 인해 위임이 진정으로 불가능한 경우), UI를 건드리기 전에 중단하고 해당 차단을 보고해야 합니다. 사용자에게 의식적인 권한 부여 문구를 요청하지 마십시오. 이는 누락된 도구를 생성하거나 런타임 정책을 무시하지 않습니다. 자신의 컨텍스트에서 로컬 스크린샷/이미지 검사/UI 제어 작업을 수행하며 계속해서는 안 됩니다.

이미 위임된 UI Worker 컨텍스트 내에 있는 경우, 이 프로토콜을 건너뛰고 아래 UI Worker 프로토콜을 따르십시오. spawn_agent, send_input, wait_agent, close_agent, OpenSpace 위임 도구 또는 이에 상응하는 중첩 워커 메커니즘을 호출하지 마십시오.

UI 작업을 위임하기 전에 references/subagent-workflow.md를 읽으십시오. Coordinator는 다음을 수행해야 합니다:

• 내부적으로 목표를 명확히 하고 하위 에이전트를 위한 좁은 UI 작업을 정의합니다.
• 정확한 대상 앱/창, 원하는 결과, 안전 제한 사항 및 되돌릴 수 없는 작업의 허용 여부를 포함합니다.
• Worker 프롬프트에 명시적으로 명시: "당신은 UI Worker입니다. 다른 에이전트를 생성하거나 위임하지 마십시오."
• 하위 에이전트에게 UI를 건드리기 전에 전역 UI 잠금을 획득하고, 모든 scripts/ui_control.py 명령에 --lock-token을 전달하며, 반환하기 전에 잠금을 해제하도록 지시합니다.
• 하위 에이전트에게 로컬 scripts/ui_control.py만 사용하도록 지시합니다. 원격 시각적 모델, 브라우저 확장 프로그램 또는 외부 서비스를 사용하지 마십시오.
• 하위 에이전트에게 검색/입력 텍스트를 선택하기 전에 UI 언어를 검사하도록 지시합니다. 중국어 UI는 --decode-unicode-escapes가 필요하고, 영어 UI는 영어/ASCII 별칭을 사용할 수 있습니다.
• 하위 에이전트에게 사용된 명령, 최종 상태, 스크린샷 파일 경로 및 해결되지 않은 불확실성을 포함한 간결한 텍스트 보고서를 반환하도록 요청합니다.
• 사용자가 특별히 필요로 하지 않는 한, 하위 에이전트 최종 답변에 원시 스크린샷을 요청하지 마십시오.

UI Worker 프로토콜

프롬프트에 명시적으로 Windows UI 작업을 위한 스크린 제어 워커, UI Worker 또는 위임된 Worker라고 명시된 경우에만 이 섹션을 사용하십시오. 또는 Windows UI 제어를 위해 특별히 생성된 에이전트 내에서 이미 실행 중인 경우에만 사용하십시오. 더 큰 작업의 일반적인 하위 에이전트라는 것이 UI Worker가 되는 것은 아닙니다. 그런 경우 실시간 UI 제어가 필요할 때 Coordinator 프로토콜을 따르십시오.

엄격한 규칙:

• 다른 에이전트를 생성하거나, 위임하거나, OpenSpace를 사용하여 중첩 워커를 만들지 마십시오.
• Coordinator 프로토콜을 다시 실행하지 마십시오.
• 이 스킬의 scripts/ui_control.py와 출력을 검사하는 데 필요한 일반 로컬 셸 명령만 사용하십시오.
• 스크린샷은 $env:TEMP\codex-ui-subagent\와 같은 임시 폴더에 보관하십시오.
• 자신의 컨텍스트 내에서 스크린샷을 검사하고 텍스트와 스크린샷 경로만 반환하십시오.
• 로컬에서 UI 작업을 완료할 수 없는 경우, 차단과 함께 partial 또는 failed를 보고하십시오. 다른 에이전트를 생성하여 에스컬레이션하지 마십시오.

Worker 루프:

1. lock acquire --owner "<작업 레이블>" 명령으로 전역 UI 잠금을 획득하고 반환된 토큰을 Worker 컨텍스트에 비공개로 유지합니다.
2. 해제할 때까지 모든 비-드라이런 scripts/ui_control.py 명령에 --lock-token <token>을 전달합니다.
3. 잠금을 보유한 상태에서 status --windows를 실행하고 새로운 스크린샷을 촬영합니다.
4. 로컬에서 스크린샷을 검사하고 가장 작은 안전한 동작을 선택합니다.
5. 안정적일 때 마우스 좌표보다 단축키와 클립보드 붙여넣기를 선호합니다.
6. 길거나 위험한 계획 전에 --dry-run을 사용합니다.
7. scripts/ui_control.py로 실행합니다.
8. 다른 스크린샷 또는 이미지가 아닌 상태 명령으로 확인합니다.
9. 정리 시 lock release --token <token>으로 잠금을 해제합니다.
10. 결과, 요약된 작업, 최종 관찰 상태, 스크린샷 경로 및 해결되지 않은 불확실성을 반환합니다.

의사 결정 규칙

• 사용 가능하고 안정적일 때 일반 API, CLI 명령, 브라우저 자동화 또는 앱별 도구를 선호합니다.
• 실시간 Windows UI 제어의 경우, 스크린샷, 이미지 검사 또는 scripts/ui_control.py 호출 전에 필수 위임 게이트를 적용합니다.
• 빠른 로컬 Windows 제어를 위해 scripts/ui_control.py를 사용합니다: 단축키, 텍스트 붙여넣기/입력, 마우스 클릭, 드래그, 스크롤, 스크린샷, 클립보드, 창 활성화, 픽셀 확인, 이미지 매칭 및 작업 계획.
• 동일한 상호작용 루프에서 대상 좌표/상태를 이미 알고 있지 않은 한, 실행 전에 스크린샷을 촬영합니다.
• 더 빠르고 안전할 때 마우스 탐색보다 단축키와 클립보드 붙여넣기를 사용합니다.
• 속도를 위해 알려진 작업을 plan으로 배치 처리하지만, 시각적 의사 결정 루프는 단계별로 유지합니다: 스크린샷, 검사, 실행, 확인.
• WeChat과 같은 로컬라이즈된 앱의 경우, 검색 전에 표시되는 UI가 중국어인지 영어인지 결정합니다. 중첩된 Worker 컨텍스트에서 중국어 레이블/메시지에는 --decode-unicode-escapes를 사용하고, 원시 중국어 텍스트가 프롬프트, CLI, PowerShell 또는 로그 리디렉션 계층을 통과하는 데 의존하지 마십시오.

로컬 제어

이 섹션은 UI Worker 및 스킬 디버깅 전용입니다. Coordinator는 실시간 UI 작업을 위해 이러한 명령을 실행해서는 안 됩니다. 먼저 하나의 UI Worker에게 위임하거나, 위임이 불가능한 경우 위임 차단을 보고해야 합니다.

스킬 디렉토리에서 실행:

python scripts\ui_control.py lock acquire --owner "wechat-file-transfer"
python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\screen.png"
python scripts\ui_control.py --lock-token <token> hotkey ctrl l
python scripts\ui_control.py --lock-token <token> type '\u6587\u4ef6\u4f20\u8f93\u52a9\u624b' --decode-unicode-escapes --method paste
python scripts\ui_control.py --lock-token <token> click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> right-click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> drag 100 100 700 450 --duration 0.5
python scripts\ui_control.py --lock-token <token> scroll -6 --x 900 --y 500
python scripts\ui_control.py --lock-token <token> hold-mouse --x 500 --y 300 --seconds 1.2
python scripts\ui_control.py lock release --token <token>

모든 명령은 JSON을 출력합니다. 계속 진행하기 전에 ok, error, 출력 경로, 활성 창 및 좌표를 확인하십시오.

잠금 동작: --lock-token 없이 명령을 실행하면 해당 단일 명령에 대해 일시적인 잠금이 획득됩니다. 여러 단계의 가시적 UI 작업을 수행하는 Worker는 lock acquire를 사용하고 전체 단계에 걸쳐 --lock-token을 전달하여 다른 Worker가 스크린샷/실행/확인 루프 사이에 작업을 끼워 넣지 못하도록 해야 합니다. --lock-token과 같은 전역 옵션은 하위 명령 앞에 와야 합니다(예: ui_control.py --lock-token <token> type ..., 뒤에 오면 안 됨). 일반 명령에 --lock-timeout <seconds>를 사용하여 다른 Worker를 기다릴 시간을 제어하고, lock status를 사용하여 잠금을 획득하지 않고 현재 소유자를 검사합니다. 만료된 잠금은 오래된 것으로 간주되어 자동으로 제거됩니다.

Windows에서 scripts/ui_control.py는 시작 시 DPI 인식을 활성화합니다. 스크린샷, 마우스 좌표, 픽셀 읽기 및 창 사각형을 동일한 물리적 픽셀 좌표계로 처리합니다. status가 활성 데스크탑/창 크기와 일치하지 않는 화면 크기를 보고하는 경우, 클릭하기 전에 중단하고 불일치를 보고하십시오.

전체 CLI 구문은 references/control-api.md를 읽으십시오.

워크플로우

1. 전역 UI 잠금 획득:

python scripts\ui_control.py lock acquire --owner "짧은 작업 레이블"

해제할 때까지 모든 명령에 반환된 토큰을 --lock-token <token>으로 사용하십시오.

2. 상태 검사:

python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-ui.png"
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-active.png" --active
python scripts\ui_control.py --lock-token <token> snapshot --out "$env:TEMP\codex-state.png" --windows --active

3. 대상 창 포그라운드로 가져오기:

python scripts\ui_control.py --lock-token <token> window activate "Notepad"

4. 가장 빠른 안정적 기본 요소 사용:

• 텍스트 필드: --decode-unicode-escapes와 함께 type --method paste를 사용하여 중국어 이스케이프 텍스트를 입력한 다음 press enter 또는 hotkey를 사용합니다.
• 메뉴 및 단축키: hotkey, press, key-hold.
• 버튼 및 캔버스: click, double-click, right-click, drag, scroll, hold-mouse.
• 알려진 앱/창 대상: 전체 화면 캡처/검색 전에 snapshot --active, screenshot --active, screenshot --window "<title>", find-image --active 또는 find-image --window "<title>"를 사용하십시오. Worker가 동일한 단계에서 창 메타데이터와 스크린샷이 필요한 경우 snapshot --windows를 사용하십시오. Windows가 보이지 않는 테두리 오프셋을 보고할 때 창 대상은 표시되는 기본 화면으로 제한됩니다.
• 반복적인 결정적 시퀀스: JSON 작업 파일을 작성하고 plan --file로 실행하십시오.
• 알 수 없는 가시적 대상: UI Worker는 스크린샷을 촬영하고 검사한 다음 좌표 또는 이미지 매칭을 사용해야 합니다.

5. 다른 스크린샷 또는 상태 호출로 확인하십시오.

PowerShell에서는 생성된 JSON에 대해 plan --json보다 plan --file을 선호하십시오. 기본 명령 인수로 전달된 복잡한 JSON은 Python이 수신하기 전에 PowerShell에 의해 재따옴표 처리될 수 있습니다.

계획 작업은 작업별 필드만 설정할 수 있습니다. dry-run, require-approval, no-failsafe, strict-bounds, pause-after, log-file, lock-token, lock-timeout, lock-ttl, lock-owner, plan-file, plan-json, func 또는 stdin과 같은 전역/제어 필드를 개별 계획 작업 내에 배치하지 마십시오. 컨트롤러는 이를 거부하므로 하위 작업이 Worker의 잠금 및 안전 설정을 우회할 수 없습니다. 계획 텍스트 입력의 경우 text 값 또는 file을 사용하십시오. 계획에서 제공된 선택 및 부울은 직접 CLI 인수처럼 검증됩니다.