ZIAForge 사용자 가이드

시작하기

ZIAForge는 논의, 계획, 실행 및 검증을 하나의 작업으로 유지합니다. Git 프로젝트에는 Code를 선택하고, 일반 폴더의 문서, 연구 및 기타 결과물에는 Work를 선택하십시오.

별도의 프로젝트에서 작은 작업부터 시작하십시오. 네이티브 CLI를 선택하는 경우 먼저 터미널에서 설치하고 자체 계정으로 로그인하십시오. 또는 API 연결을 구성하십시오. CLI 구독과 유료 API는 별개의 연결 방법입니다. ZIAForge는 자동으로 로그인해주거나 둘 사이에 크레딧을 이전하지 않습니다.

1. 설정을 열고 작업 영역 폴더와 언어를 확인하십시오. 정보에서는 현재 실행 중인 빌드의 정확한 정보를 보여줍니다.
2. Code의 경우 사이드바에서 Git 저장소를 추가하십시오. Work의 경우 작업을 생성할 때 별도의 폴더를 선택하십시오.
3. CLI, 모델, 추론 노력 및 액세스 수준으로 프리셋을 저장하십시오. 저장된 프리셋 없이 사용자 지정을 직접 선택할 수도 있습니다.
4. 작업을 생성하고 경로, 역할, 수동 또는 자동 진행 여부를 선택하십시오. 시작 전에 선택 사항을 검토하십시오.

관련 지침: 프로젝트 개요 · 제공업체 호환성.

올바른 데스크톱 패키지 설치

사용 중인 운영 체제와 CPU 아키텍처(x64 또는 arm64)에 맞는 패키지를 선택하십시오. 빌드 파이프라인은 macOS DMG/ZIP, Windows NSIS 설치 프로그램/ZIP, Linux DEB/RPM/AppImage/tar.gz/ZIP 형식을 생성할 수 있습니다. 생성된 파일이나 크로스 빌드가 해당 컴퓨터에서 설치 프로그램 및 네이티브 UI 테스트를 통과했음을 증명하지는 않으므로 해당 릴리스의 검증 기록을 참조하십시오.

Electron 44를 사용하는 macOS 빌드는 macOS 13 이상이 필요합니다. Apple Silicon에서는 arm64 패키지를, Intel에서는 x64 패키지를 사용하십시오. 교체하기 전에 이전 앱을 완전히 종료하십시오. 프리뷰 패키지는 서명되지 않았거나 공증되지 않았을 수 있으므로 개발용 아티팩트를 서명된 공식 릴리스로 오인하지 마십시오.

Windows는 번들된 Electron 버전에서 지원하는 운영 체제와 PATH에서 사용할 수 있는 Git이 필요합니다. 일치하는 아키텍처를 선택하십시오. 서명되지 않은 프리뷰에는 Authenticode 인증이 없습니다. 포터블 ZIP은 실행 파일뿐만 아니라 전체 애플리케이션 디렉터리와 런타임 파일을 보존해야 합니다.

Linux는 호환되는 그래픽 데스크톱, Electron에 필요한 시스템 라이브러리 및 Git이 필요합니다. 암호화된 제어 자격 증명을 위해 gnome-libsecret 또는 KWallet과 같이 정상 작동하는 Secret Service를 제공해야 하며, 안전하지 않은 basic_text 백엔드는 허용되지 않습니다. 헤드리스/컨테이너 스모크 테스트 결과가 모든 데스크톱이나 배포판을 보증하지는 않습니다.

DEB는 apt install ./file.deb 명령으로 설치하거나, 배포판의 패키지 관리자를 통해 RPM을 설치하십시오. AppImage는 실행 권한과 적절한 FUSE 지원이 필요하며, 지원되는 환경에서는 --appimage-extract-and-run을 대안으로 사용할 수 있습니다. tar.gz 및 ZIP 패키지는 모든 런타임 파일과 함께 압축을 해제하십시오. 패키지를 교체할 때는 사용자 데이터와 애플리케이션 파일을 분리하여 유지하십시오.

소스에서 빌드하려면 표준 Electron 설치 프로그램을 포함하여 Node 24, Git 및 npm ci를 사용하십시오. 네이티브 재빌드에는 플랫폼 도구가 필요합니다. macOS에서는 Xcode 명령줄 도구, Windows에서는 MSVC C++, Windows SDK 및 Python, Linux에서는 컴파일러, make, Python, pkg-config 및 필요한 패키징 도구가 필요합니다. 정확한 명령과 현재 플랫폼 제한 사항은 PLATFORM_BUILDS.md를 따르십시오.

릴리스 버전은 중앙에서 예약되며 결과물은 불변입니다. CI 검증 빌드는 공개된 설치 프로그램이 아닙니다. 소스 아카이브에는 소스 코드, 록파일, 문서 및 스크립트가 포함되며 종속성, 자격 증명, 사용자 프로필 및 비공개 연구 내용은 제외됩니다. 성공적인 x64 빌드로부터 네이티브 ARM 또는 Windows 검증을 추론하지 마십시오.

관련 지침: 플랫폼 패키지, 필수 조건 및 검증 한계 · 빌드 식별 및 릴리스 점검.

Code: 다섯 가지 경로

Auto는 범위를 평가합니다. 단순한 질문은 답변으로 끝날 수 있지만, 규모가 큰 작업은 준비 단계가 필요합니다. 버그 수정은 원인을 조사하고 수정 사항을 준비합니다. 사양 우선은 기술적 솔루션부터 시작하며, 요구사항 우선은 요구사항 및 승인 기준부터 시작합니다.

멀티 모델은 탐색, 설계, 구현 및 검토에 별도의 컨텍스트를 사용합니다. 경로 이름이 서로 다른 제공업체를 요구하는 것은 아닙니다. 각 역할은 사용자가 선택한 프리셋 또는 사용자 지정 구성을 사용합니다.

워크트리는 작업의 Git 변경 사항을 격리합니다. 브랜치는 선택한 체크아웃 환경에서 작동합니다. 시작하기 전에 프로젝트, 브랜치 및 모델을 확인하십시오. 작업 설명은 일반 대화로 중복 전송되지 않습니다.

해결되지 않은 제품 또는 기술적 결정이 남아 있는 아이디어의 경우 요구사항 우선을 사용하고 논의를 통해 토대를 구축하십시오. Auto는 요청을 분류할 뿐 모든 짧은 문구를 즉시 구현하라는 명령이 아닙니다. 임시 저장은 모델에 연결하지 않고 요청을 유지하며, 시작은 관리형 워크플로를 한 번 저장하고 실행합니다. 1개에서 4개까지의 작업 복사본은 독립적인 생성 ID와 역할 설정을 가집니다.

관련 지침: Code 워크플로 계약 · Code 프롬프트 프로필.

Forge 논의

시작을 누르면 중앙 논의 창이 열립니다. 자연스럽게 답변하고, 반문하며, 제약 조건을 추가하고 기술적 선택 사항을 논의하십시오. 대화 및 질문은 작업과 함께 유지됩니다.

텍스트를 전송한다고 해서 문서가 승인되거나 새 구현 계획이 승인되는 것은 아닙니다. 실행 중 명확화 요청이 발생하면 먼저 관리형 턴을 일시 중지하고 영향을 받는 범위를 다시 검토합니다. 이미 승인된 단계 내의 질문에 대한 답변은 해당 단계를 계속 진행할 수 있습니다.

기본 토대를 의도적으로 다시 검토하려면 요구사항, 사양 또는 계획을 선택하십시오. 새 버전이 생성되면 종속된 결정에 대해 새로운 승인이 필요합니다. 완료된 단계와 해당 증거는 유지되며, 대체된 미완료 단계는 기록에 남습니다.

단계별 관리 세션은 자유 대화와 다릅니다. 워크플로 소유 세션에 수동 프롬프트를 직접 보내는 대신 Forge 논의를 사용하십시오.

관련 지침: Forge 논의 계약.

문서 및 결정

문서를 열어 버전을 확인하고 필요한 경우 수정하십시오. 논의를 통해 수정한 내용을 제출하면 새 버전이 생성되며, 보고서와 검증된 결과는 소급하여 재작성되지 않습니다.

제안된 계획을 승인하기 전에 순서, 지침, 승인 기준 및 검증 명령을 편집하십시오. 작업 폴더에서 실행되므로 본인이 이해한 구체적인 명령만 승인하십시오. 멀티 모델은 전체 작업에 대한 하나의 구현 단계를 제안하며, 세부 정보는 해당 문서와 지침에 포함됩니다.

승인은 별도의 신중한 결정입니다. Auto는 요구사항, 사양 및 계획에 대한 질문이나 승인을 건너뛰지 않습니다. 외부에서 변경된 문서는 이전 승인을 재사용할 수 없습니다.

준비 파일은 아티팩트로 표시됩니다. 버전, 생성 단계 및 해시가 아티팩트를 결과에 바인딩합니다. Code 문서는 워크트리 외부에 보관되며 커밋에 자동으로 포함되지 않습니다.

승인하기 전에 문서와 표시된 결정을 모두 확인하십시오. 승인은 현재 게이트 ID, 계획 리비전 및 유지된 문서 해시를 바인딩합니다. 범위나 증거가 잘못된 경우 변경을 요청하십시오. 결정이 유효하지 않게 된 경우 새로운 선택을 하기 전에 저장된 상태를 다시 로드하십시오. 변경된 파일은 이전 버전으로 승인될 수 없습니다.

관련 지침: 워크플로 게이트 및 문서 버전.

실행 및 검토

할 일 목록은 실제 단계, 현재 시도, 검증 및 검토 결과를 보여줍니다. 에이전트가 "완료"라고 말하는 것만으로는 단계가 완료되지 않으며, 계획에 필요한 증거가 존재해야 합니다.

수동 모드는 대상 단계 사이에서 일시 중지됩니다. Auto는 검증된 단계를 진행하고 제한된 재시도를 허용합니다. 다음 이후 중지는 항상 체크포인트를 생성합니다. 일시 중지는 워크플로의 활성 작업을 중단하며, 패널을 닫아도 작업이 중단되지 않습니다.

독립적인 검토자는 파일 및 검증 결과가 포함된 별도의 컨텍스트를 사용합니다. 차단된 모든 필수 지적 사항은 해결되어야 하며, 여러 검토자가 투표로 차단 오류를 무효화할 수는 없습니다.

멀티 모델에서 지적 사항을 수정하려면 명시적인 결정이 필요합니다. 수정이 다른 검토를 자동으로 시작하지는 않으며, 다시 검토를 통해 새로운 주기를 시작합니다. 검토 의견은 구현을 반복하지 않고 코디네이터에게 재검토를 요청할 수 있습니다.

완료된 단계는 임의로 수정할 수 없습니다. TDD를 사용하는 경우 Red 단계는 예상된 이유로 실제로 실패해야 하며, 이후 Green 단계는 통과해야 합니다. 제한된 시도 횟수를 통해 무한 재시도를 방지합니다.

설정 → 검토 팀에서 독립적인 CLI/API 검토자를 저장한 다음 Code 또는 Work에서 팀을 선택하십시오. 검토자가 병렬로 실행된 후 팀의 보고서 설계자가 뒤따라 실행됩니다. 저장된 팀 없이 독립적인 검토자를 구성할 수도 있습니다. 보고서 설계자는 프로젝트 파일이나 도구 없이 익명의 구조화된 보고서만 받으며, 이러한 격리 환경은 현재 Claude Code 또는 API가 필요합니다.

각 구현 단계에는 실행 가능한 점검, 필수적인 독립 검토 또는 둘 다 필요합니다. 준비 단계에서는 대신 검증된 결과와 아티팩트 영수증을 보관하며, 이것이 구현 테스트가 실행되었음을 대신 증명하지는 않습니다. 명령은 실제 종료 상태와 소유 프로세스의 정리가 확인된 경우에만 성공한 것으로 간주됩니다. TDD의 Red 검사는 구현 및 Green 검증 전에 정상적으로 실패해야 하며, 실행 파일 누락이나 타임아웃은 유효한 Red 결과가 아닙니다.

기본 회로 차단기는 한 단계에서 3회 실패하거나 총 50회 시도 후 중지됩니다. 중단은 시도 횟수를 소모하지만 그 자체가 실패한 시도로 간주되지는 않습니다. 한도 및 완료된 증거는 재시작 후에도 유지되며, 재시도가 이를 초기화하지는 않습니다. 다른 시도를 승인하기 전에 보관된 오류를 확인하십시오.

관련 지침: 검증 및 검토.

병렬 검토 팀 및 보고서 설계자

설정 → 검토 팀을 열고 팀을 저장하십시오. 자체 CLI 또는 API, 모델, 추론 노력 및 전문 분야를 가진 독립적인 검토자를 추가한 다음 보고서 설계자를 선택하십시오. 작업의 검토 구성에서 팀을 선택하십시오. 실행기 프리셋을 검토자가 사용할 수도 있으며 사용자 지정도 여전히 가능합니다. 독립적인 역할은 여전히 별도의 컨텍스트를 유지합니다.

검토자는 동일한 작업 증거를 바탕으로 병렬로 실행됩니다. 필요한 각 보고서, 오류 및 판정이 보관됩니다. 설계자는 검토자 이름, 모델 또는 제공업체 식별 정보, 원본 작업 내용, 저장소 액세스 권한 또는 도구 없이 익명의 번호가 매겨진 보고서만 받습니다. 보고서를 비교하여 하나의 구조화된 판정을 반환하며 새로운 소스 코드 검토를 직접 수행하지는 않습니다.

차단된 지적 사항이나 필수 검토자의 거부는 다수결이나 설계자의 선호로 면제될 수 없습니다. 보고서가 누락되거나 형식이 잘못된 경우 승인이 방지됩니다. 수정 사항을 수락하거나 승인하기 전에 개별 지적 사항과 집계된 결정을 검토하십시오. 저장된 팀은 실행을 위해 확정 및 고정되며, 프리셋을 편집해도 완료된 증거가 재작성되지 않습니다.

보고서 전용 설계자는 현재 지원되는 Claude 또는 API 무도구 구성을 사용합니다. Codex 및 Antigravity는 검토자로 계속 사용할 수 있지만, 검증된 도구 없는 규약이 마련될 때까지 이 격리된 설계자 역할에는 사용할 수 없습니다. 프롬프트에 "도구 없음"이라고 명시하는 것만으로는 충분하지 않습니다.

관련 지침: 형식화된 팀 구성 · 검토 집계.

에이전트 전문 분야 및 프롬프트 정책

모델은 실행 엔진이며, 전문 분야는 지침 프로필입니다. 추가 전문 분야가 없는 경우 없음, 기본 가이드의 경우 표준, 관련 기본 제공 가이드의 경우 Auto, 선택한 가이드 및 자체 제한 지침의 경우 수동을 선택하십시오. 프리셋에 선택 사항을 저장할 수 있습니다.

원본 카탈로그는 일반 코딩, 아키텍처, 보안, 안정성, 성능, 테스트 및 인터페이스 사용성을 다룹니다. Auto는 사용 가능한 작업/단계 텍스트를 사용하여 가이드를 선택하며, 몰래 다른 모델을 호출하거나 전문성을 보증하지는 않습니다. 구현 계획을 승인하기 전에 계획 제안을 검토하고 변경할 수 있습니다.

검토 전문 분야는 주의를 집중시키는 데 도움이 되지만 독립적인 증거, 액세스 한도 또는 구조화된 판정을 대체하지는 않습니다. 사용자 지정 지침을 작업 범위의 일부로 취급하십시오. 이를 문서 승인, 도구 정책, 인증 또는 검토자 실패를 우회하는 데 사용해서는 안 됩니다.

관련 지침: 원본 프롬프트 카탈로그.

Work: 질문에서 문서까지

Work는 Git을 필요로 하지 않습니다. 기본값은 별도의 작업 폴더를 생성하고, 사용자 지정은 네이티브 선택기를 통해 기존 폴더를 선택합니다. 임시 저장은 추론 없이 설정을 저장하며, 시작은 첫 번째 단계를 실행합니다.

Auto는 직접 답변하거나 실제 할 일 목록이 포함된 적절한 계획을 제안합니다. 브레인스토밍은 추가 아이디어나 평가를 선택하기 전에 ideas.md를 생성합니다. 연구는 findings.md, 출처 및 한계점을 보관합니다. 작성은 의도에서 시작하여 유용한 경우 outline.md를 거쳐 서술형 문서 또는 draft.md로 진행되며, 개정 시 이전 버전이 유지됩니다.

네이티브 선택기를 통해 파일 입력을 선택하고 @로 참조하십시오. 앱은 이를 불변의 작업 입력으로 복사하고 실행 전에 유효성을 검사합니다. 기본값은 애플리케이션 소유의 작업 폴더를 생성하고, 사용자 지정 폴더 접근은 저장된 소유자 권한 부여입니다. 저장된 미시작 초안은 해당 폴더를 변경할 수 있습니다.

독립적인 실행기 설정을 가진 복사본 1–4개를 생성합니다. 폴더가 겹치는 작업은 동시에 쓸 수 없습니다. 이 조율은 임의의 외부 프로그램이 아닌 ZIAForge 작업에 적용됩니다.

심층 브레인스토밍은 기본적으로 세 명의 독립적인 워커를 사용하며 최대 8명까지 지원합니다. 별도의 컨텍스트에서 프리셋을 재사용하는 것을 포함하여 이들의 순서와 구성을 선택하십시오. 워커의 질문은 출처를 유지하며, 형식이 잘못된 보고서는 한 번의 형식 복구 시도를 거칩니다. 부분적인 실패는 만장일치의 성공으로 포장되지 않고 그대로 표시됩니다.

심층 모드는 보관된 워커 보고서를 brainstorm_report.md로 결합하고 항상 사용자의 결정을 요청합니다. 사소한 후속 조치는 코디네이터를 통해 보고서를 수정하며, 중대한 변경은 고정된 워커의 새로운 라운드를 시작합니다. 아티팩트는 해당 버전을 유지합니다.

확정된 역할은 작업 생성 또는 명시적 임시 저장 시 고정됩니다. 첫 번째 호출 후에는 자동/수동 진행 여부만 변경할 수 있으며, 다른 역할이나 모델 설정을 적용하려면 새 작업을 사용하십시오. 전역 프리셋을 편집해도 이후 단계가 자동으로 변경되지는 않습니다.

수동 모드는 상당한 분량의 작성 개요를 포함하여 대상 단계 사이에서 일시 중지됩니다. Auto는 해당 개요를 거쳐 계속 진행할 수 있습니다. 질문, 제안된 실행 계획, 브레인스토밍 방향 및 심층 보고서 검토는 Auto에서도 여전히 명시적인 결정으로 남습니다. 인용만으로 웹 브라우징이 수행되었음을 증명하지 못하며, 바이너리 파일이 보관되었다고 해서 정상적으로 렌더링되었음을 증명하지는 못합니다.

관련 지침: Work 모드 및 결정.

프리셋, 모델 및 액세스

프리셋은 CLI/API, 모델, 추론 노력 및 권한을 저장합니다. 대화 바닥글에는 프리셋, CLI, 모델 및 옵션 세그먼트가 있습니다. 사용자 지정은 프리셋 없이 작동하며, 프리셋 생성을 통해 현재 선택 항목을 저장합니다.

카탈로그는 지원되는 경우 설치된 선택 CLI 또는 API에서 가져옵니다. 새로 고침은 선택 항목을 변경하지 않고 목록을 업데이트합니다. 조회가 불가능한 경우 명시적인 모델 ID를 입력하십시오. 제공업체가 여전히 이를 지원해야 합니다. 추론 수준은 모델과 CLI에 따라 다릅니다. 제공업체 기본값은 명시적 none 토큰과 구별됩니다.

백엔드 승인이 확인된 후에만 변경 사항을 적용하십시오. 활성 턴 중이거나 대기열이 비어 있지 않은 경우에는 전환이 제한됩니다. 임시 저장 및 표시되는 대화 기록은 유지되지만 제공업체를 변경해도 비공개 내부 상태는 이전되지 않습니다.

Forge에서는 역할 라벨이 중요합니다. 준비 단계에서 별도의 플래너를 사용할 수 있습니다. 바닥글에서 표시되는 역할을 변경할 수 있으며, 검토자와 도우미는 워크플로 설정에서 선택합니다. 이미 검증된 구현에 대한 정책은 잠길 수 있습니다.

권한은 제공업체마다 다릅니다. 어댑터가 지원하는 경우 읽기 전용 및 워크스페이스 쓰기를 사용할 수 있습니다. Antigravity는 네이티브 CLI 설정 또는 명시적으로 선택한 전체 액세스를 사용합니다. 전체 액세스는 샌드박스가 아닙니다.

전문 분야는 프롬프트 지침을 추가할 뿐 다른 모델이나 권한을 추가하지 않습니다. 프리셋과 역할은 없음, 표준, Auto 및 수동을 지원합니다. Auto는 추가 모델 호출 없이 단계 텍스트에서 프로필을 선택합니다. 수동은 최대 4개의 전문 분야와 사용자 지정 지침을 허용합니다. 플래너가 제안한 할당은 계획을 승인하기 전에 편집할 수 있습니다.

수동으로 입력한 모델 ID나 추론 노력은 사용자의 선택이지만 제공업체에서 거부할 수 있습니다. 전역 프리셋을 편집해도 실행 중인 대화나 승인된 계획이 소급하여 변경되지는 않습니다. 유휴 대화를 의도적으로 변경하려면 자체 구성 컨트롤을 사용하고 승인을 기다리십시오. 비활성화된 옵션은 기능 또는 수명 주기 제한으로 해석해야 하며, 저장된 JSON을 편집하여 우회해서는 안 됩니다.

관련 지침: 제공업체 기능.

대화, 중지 및 대기열

열린 탭, 최근 항목, 임시 저장은 하나의 작업에 속합니다. 탭을 닫으면 열린 목록에서는 제거되지만 최근 항목에는 유지되며 제공업체 프로세스나 관리형 워크플로가 중단되지는 않습니다. 기록 메뉴에서 검색하고 대화를 다시 열거나 추가 탭을 모두 닫을 수 있습니다.

중지는 현재 턴을 중단합니다. 중단 승인이 프로세스 완료를 의미하지는 않으므로 다음 전송 전에 중지가 완료될 때까지 기다리십시오. 그동안 다음 초안을 작성할 수 있습니다.

일반 대화에서 대기열은 현재 초안과 별도로 이후 요청을 저장합니다. 대기열 일시 중지는 추가 전달을 보류합니다. 중지 및 종료는 대기열을 일시 중지합니다. 다시 시작한 후에는 먼저 재개한 다음 명시적으로 대기열을 계속하십시오.

불확실은 전달 여부를 알 수 없음을 의미합니다. 이러한 메시지는 자동으로 재전송되지 않습니다. 대화 기록을 검토하고 적절한 경우 텍스트를 복사한 뒤 대기 항목을 닫으십시오. 다시 보내는 것은 새로운 의도적 요청입니다.

단계별 관리 대화는 일반 대기열 대신 자체 워크플로를 사용합니다. 단계 추적은 현재 단계를 표시하며, 다른 탭을 수동으로 선택하면 추적이 중지됩니다. CLI 로그에는 응답과 별도로 진단 정보가 표시됩니다.

마크다운 응답은 제목, 목록, 표, 링크 및 코드 블록을 렌더링합니다. 도구 카드와 CLI 진단 정보는 답변과 구분되어 유지됩니다. 모델이 보고한 생각 및 토큰 지표는 제공업체가 실제로 제공할 때만 표시되며, 애니메이션 효과만으로 내부 추론이나 사용량을 짐작해서는 안 됩니다.

불확실한 전송 또는 대기열 승인 후에는 기록을 확인하고 제공되는 경우에만 보관된 동일한 요청을 다시 시도하십시오. 대기열 접수증은 스토리지에 항목이 수락되었음을 의미할 뿐 추론이 완료되었음을 의미하지는 않습니다. 불확실한 대기 항목을 제거하는 것은 명시적인 취소일 뿐이며, 이미 전달된 프롬프트를 철회할 수는 없습니다.

관련 지침: 영구 메시지 큐.

파일, Git 및 완료

파일 목록은 작업 폴더를 보여줍니다. 결과를 요구사항과 비교하고 문서를 열며 변경 사항(diff)을 점검하십시오. 바이너리 파일을 보관한다고 해서 대상 애플리케이션에서 올바르게 렌더링된다는 보장은 없습니다.

Git은 기록된 결과와 함께 상태, 변경 사항 및 작업을 제공합니다. 커밋, 머지 및 푸시는 기본적으로 수동이며, 자동 작업은 완전히 검증된 계획을 위한 별도의 선택 사항입니다.

검증과 배포 사이에 작업 파일을 변경하지 마십시오. 승인은 정확한 바이트에 연결되어 있습니다. 충돌, 푸시 실패 및 알 수 없는 작업 결과는 명시적인 결정이 있을 때까지 진행을 차단합니다. Auto는 배포를 암묵적으로 승인하지 않습니다.

Work는 Git 브랜치를 생성하지 않으며 Git 마무리 단계도 없습니다. 버전과 출처를 포함하여 선택한 폴더에서 필요한 문서를 유지하십시오.

파일 편집기는 확장자별 구문 강조, 찾기 및 바꾸기, 실행 취소 기록, 자동 줄 바꿈 및 탭별 초안을 제공합니다. 저장 시 지원되는 UTF-8/UTF-16 인코딩이 보존되고 외부 수정 충돌이 거부됩니다. 다른 인코딩 및 바이너리 콘텐츠는 외부 편집기를 사용해야 합니다. 저장되지 않은 초안이 있으면 사용자가 저장하거나 취소할 때까지 애플리케이션 종료가 방지됩니다.

전체 구문 분석은 최대 8 MiB까지 지원됩니다. 더 큰 텍스트 파일은 256 KiB 창 단위로 열리며, 8–64 MiB 파일은 구문 분석 없이 전체를 명시적으로 로드할 수 있습니다. 64 MiB를 초과하는 파일은 창 단위 편집과 범위 제한 다음 일치 검색을 사용합니다. 이는 대용량 파일을 위한 제한된 모드이며, 임의의 대용량 문서에 대해 Sublime Text 수준의 기능을 보장하는 것은 아닙니다.

폴더 열기는 원래 저장소만 자동으로 여는 대신 현재 작업 또는 브랜치/워크트리 컨텍스트를 사용합니다. 파일 행을 통해 해당 파일의 상위 디렉터리를 표시할 수 있습니다. 경로는 등록된 작업 권한에 대해 백엔드에서 유효성을 검사합니다. 바이너리 파일은 일반 텍스트로 편집할 수 없으므로 대상 뷰어를 사용하고 원본 바이트를 유지하십시오.

워크트리 제거는 별도의 보호 조치가 적용되는 작업입니다. 유휴 세션을 포함하여 연결된 구조화된 세션 및 터미널을 먼저 종료한 후 제거하십시오. 저장된 Git 결과와 복구 상태를 점검하십시오. 작업 기록을 삭제하는 것이 커밋되지 않은 작업을 안전하게 보존하는 것을 대신할 수는 없습니다.

관련 지침: 형식화된 편집기 계약 · Git 정책.

API 연결

연결에서 명시적으로 선택한 OpenAI 호환 엔드포인트를 추가합니다. 이름, 기본 URL, 모델 및 필요한 경우 키를 입력하십시오. 대다수 서버는 기본 URL이 /v1로 끝날 것을 요구하므로 엔드포인트 설명서를 참조하십시오.

루프백 HTTP를 제외하고 HTTPS가 필수입니다. URL에 자격 증명이 포함되지 않은 순수 엔드포인트를 사용하십시오. 키는 지원되는 OS 암호화를 사용하며 UI로 다시 반환되지 않습니다. 엔드포인트를 변경하면 키를 다시 입력해야 합니다. 키 필드를 비워두면 저장된 키가 유지되며, 저장된 키 제거를 선택하면 명시적으로 삭제됩니다.

API 호출은 CLI 구독을 사용하지 않습니다. 도구와 모델은 네이티브 세션과 다르며, 모델 조회가 성공했다고 해서 추론 성공이 입증되는 것은 아닙니다. 토큰 사용량은 제공업체가 실제로 반환할 때만 표시됩니다.

자격 증명은 작업 텍스트나 프리셋 지침 대신 연결에 보관하십시오. 읽기 전용 검토자는 허용된 API 파일 도구만 전달받으며, 보고서 설계자에게는 아무 도구도 제공되지 않습니다. 지원되지 않는 도구 호출은 자동으로 실행되는 대신 거부됩니다. 서버마다 추론 매개변수, 도구 지원 및 모델 목록이 다르므로 오류 발생 시 엔드포인트의 자체 규격을 확인하십시오.

관련 지침: API 연결.

설정, 언어 및 안전한 초기화

일반 설정에서는 작업 영역, 인터페이스 언어 및 기본값을 선택합니다. 연결에서는 API 엔드포인트를 관리합니다. 프리셋 및 검토 팀은 역할 구성을 보관합니다. 원격 제어는 로컬 자격 증명, 서버 범위 및 소유자 권한을 관리하며, 업데이트는 릴리스 소스/채널을 관리합니다. 정보에서는 현재 실행 중인 빌드의 정확한 정보를 보여줍니다.

인터페이스 언어는 프롬프트 언어 및 문서 검토 상태와 별개입니다. 제품 이름, 명령 ID, 파일 확장자, 제공자 모델 ID 및 사용자가 생성한 이름은 식별자로 유지됩니다. 도움말은 최신 번역이 있는 경우 선택한 인터페이스 언어를 따릅니다. 기계 번역본에는 라벨이 표시되며 영어가 표준 참조로 유지됩니다.

저장을 누르면 표시된 구성이 적용됩니다. 데이터베이스 초기화 또는 공장 초기화를 수행하면 애플리케이션 메타데이터가 제거될 수 있으므로, 초기화를 의도적으로 사용하기 전에 파일을 보존하고 테스트를 거친 백업을 준비하십시오. 이러한 작업은 로컬 소유자 전용 작업입니다. 실패한 워크플로나 손상된 레코드를 조사하기 위한 지름길로 이 작업들을 사용하지 마십시오.

관련 지침: 현지화 지침 · 데이터 복구.

도움말 어시스턴트에 질문하기

도움말을 열고 어시스턴트 패널에서 저장된 연결 프리셋을 선택한 뒤 ZIAForge에 대해 질문하십시오. 답변은 현재의 표준 영문 가이드와 선택한 인터페이스 언어를 사용합니다. 섹션 참조 버튼을 통해 관련 가이드 주제가 열리므로 설명과 원본 참조를 비교할 수 있습니다.

이 어시스턴트는 최대 100개의 저장된 항목과 3 MiB까지 별도의 비공개 대화를 유지합니다. 최대 12,000자의 질문을 입력하십시오. 전송은 질문을 전송하고, 중지는 질문 내용을 유지한 채 진행 중인 답변을 취소하며, 지우기는 이 도움말 대화를 삭제합니다. 전송하지 않은 임시 질문과 프리셋 선택은 동일한 앱 세션에서 도움말을 닫았다가 다시 열어도 유지되지만, 임시 질문이 디스크에 저장되지는 않습니다. 어시스턴트는 애플리케이션 명령을 전송하거나, 워크플로를 변경하거나, 게이트를 승인하지 않습니다. 조언은 작업, 계정 또는 외부 연결에 대한 실시간 검증이 아닙니다.

Claude Code 및 API 도움말 세션은 지원되는 도구 미사용 정책을 강제 적용합니다. 네이티브 Codex 및 Antigravity 도움말 세션에는 기존 로컬 소유자의 네이티브 컴퓨터 권한이 필요합니다. 비활성화되어 있는 경우 앱은 다른 제공자를 선택하는 대신 사전 요구 조건을 설명합니다. 소유자만이 로컬 제어 설정에서 활성화할 수 있으며, 어시스턴트가 스스로 활성화할 수는 없습니다.

Codex 도움말은 읽기 전용 샌드박스를 사용하며 도구 승인 요청을 거부합니다. Antigravity는 계획 모드와 네이티브 샌드박스 플래그를 사용합니다. 이러한 네이티브 모드가 운영체제 격리를 보편적으로 보장하는 것은 아닙니다. 소스 가이드 해시는 답변에 사용된 참조 자료를 식별합니다. 생성된 설명에는 여전히 오류가 있을 수 있으므로 조치를 취하기 전에 링크된 섹션을 검토하십시오. 이전 답변은 소스 가이드 버전이 현재 가이드와 다를 때 표시가 남습니다.

관련 지침: 표준 가이드 및 번역 유지 관리 · 애플리케이션 어시스턴트 및 권한.

어시스턴트 및 Telegram

어시스턴트는 선택한 프리셋과 동일한 애플리케이션 제어 API를 사용합니다. 상태를 검사하는 권한과 작업을 수행하는 권한은 서로 분리되어 있습니다. 명령과 결과를 직접 검사하십시오. 어시스턴트의 설명 텍스트가 작업 완료를 증명하지는 않습니다.

Telegram은 로컬 소유자만 활성화할 수 있으며, 기존 봇 토큰과 숫자 형태의 소유자 ID가 필요합니다. 제어는 해당 소유자의 비공개 채팅 전용입니다. 구성되지 않았거나 비활성 상태인 봇은 애플리케이션 메시지를 수신해서는 안 됩니다.

일반 채팅창에 봇 토큰을 붙여넣지 마십시오. 통합을 구성했다고 해서 Telegram 연결이 증명되는 것은 아니며 봇이 자동으로 생성되지도 않습니다. 스크린샷과 응답에는 비공개 워크스페이스 데이터가 포함될 수 있습니다.

어시스턴트 프리셋을 선택하고 애플리케이션 작업 권한을 검사 권한과 별도로 부여하십시오. Codex 및 Antigravity 어시스턴트 실행에는 소유자의 네이티브 권한이 필요하며, 도구를 사용하지 않는 API 또는 Claude 세션으로 묵시적 대체되지 않습니다. 스크린샷은 어시스턴트 대화창에 표시될 수 있지만 현재 모델 입력에는 이미지 분석이 포함되지 않습니다. 어시스턴트가 이미지를 단순히 표시했다고 해서 시각적으로 검사했다고 가정하지 마십시오.

어시스턴트는 형식화된 도구를 통해 요약, 작업, 채팅, 워크플로 상태, 프로세스 컨텍스트 및 애플리케이션 창을 검사할 수 있습니다. 허용된 일반 설정을 변경하고 승인된 애플리케이션 작업을 시작할 수 있습니다. 어시스턴트는 단지 편리하다는 이유로 네이티브 권한을 부여하거나, 저장된 자격 증명을 노출하거나, 루트 워크스페이스 권한을 원격으로 변경하거나, Forge 게이트를 승인할 수 없습니다.

관련 지침: 애플리케이션 제어 계약.

비공개 Telegram 봇 작동

자체 봇을 생성하거나 가져와 비공개 채팅을 시작한 후 로컬 제어 설정에 해당 토큰과 숫자 형식의 Telegram 사용자 ID를 입력하십시오. 앱을 연결하려는 의도가 있을 때만 통합을 활성화하십시오. 소유자 ID는 사용자 식별자이며 사용자 이름이나 봇 ID가 아닙니다. 동일한 비공개 채팅에서 해당 사용자가 보낸 메시지만 수락됩니다.

실행 중인 버전, 프로젝트/작업 수 및 작업 상태에 대한 개요를 확인하려면 /start, /menu 또는 /status를 사용하십시오. 버튼을 통해 프로젝트, 작업, 스크린샷, 도움말 및 언어를 열 수 있습니다. 목록은 페이지당 8개 항목을 표시하며 뒤로, 새로고침, 홈 및 이전/다음 탐색 기능을 제공합니다. 프로젝트 버튼은 작업 목록을 필터링합니다. 작업 카드에는 저장된 워크플로 진행 상황, 모델/프리셋 및 대기 중인 질문(있는 경우)이 표시됩니다.

작업의 대화창을 열어 열려 있거나 최근의 대화 및 워크플로 단계별 채팅을 미리 봅니다. 각 미리보기에는 최대 6개의 최신 사용자/어시스턴트 메시지가 각각 200자로 축약되어 표시됩니다. 비공개 추론 과정은 표시되지 않습니다. 대화 기록을 읽는다고 해서 제공자가 시작되지는 않습니다. 미리보기는 읽기 전용입니다. 일반 텍스트 및 /ask TEXT는 여전히 애플리케이션 어시스턴트를 대상으로 하며, 보고 있는 작업 채팅을 암시적으로 지정하지 않습니다.

실행 / 계속은 현재 Code 또는 Work 워크플로를 다시 읽고 실행 자격이 있는 저장된 워크플로를 시작합니다. 일시 중지는 일시 중지를 요청합니다. 어느 쪽도 요구사항, 사양, 계획, 검토 결과 또는 질문을 수락하지 않으며, 결정이 보류 중이면 실행이 방지됩니다. 애플리케이션 내에서 결정을 내리거나 정확한 현재 게이트 및 리비전과 함께 명시적으로 승인된 형식화된 명령을 사용하십시오.

언어 또는 /language를 사용하여 56개의 인터페이스 언어 중 하나를 해당 고유 언어 이름으로 선택하십시오. 이는 해당 봇과 소유자에 대해서만 환경설정을 유지합니다. 앱 언어 사용은 해당 환경설정을 지웁니다. 이 설정은 애플리케이션 언어나 접근 권한을 변경하지 않으며, 기존 메시지가 자동으로 다시 전송되지 않습니다.

탐색 시 일반적으로 동일하게 게시된 메뉴 메시지가 업데이트됩니다. 버튼에는 15분 후에 만료되고 한 번만 사용할 수 있는 불투명 식별자가 포함되어 있습니다. 카드가 변경되면 이전 버튼은 무효화됩니다. 만료되었거나, 이미 사용되었거나, 메시지가 일치하지 않거나, 이전 프로세스의 버튼으로는 작업을 수행할 수 없습니다. 명확하게 편집할 수 없는 메시지는 새 카드로 교체할 수 있습니다. 알 수 없는 네트워크 오류는 새 메시지로 재시도되지 않습니다.

활성화 시 폴러는 이전 백로그를 폐기하고 디스패치 전에 업데이트 수락을 기록하므로 중단된 명령이 다시 시작할 때 자동으로 재생되지 않습니다. 이는 재생을 방지할 뿐 완료를 보장하지는 않습니다. 오류가 발생한 후 의도적으로 새 작업을 발행하기 전에 상태/컨텍스트를 확인하십시오. 자동 작업 상태 알림은 제공되지 않습니다.

명시적 명령을 계속 사용할 수 있습니다: /projects, /tasks, /task TASK_ID, /run TASK_ID, /pause TASK_ID, /screenshot 및 /ask TEXT. /new {JSON}은 형식화된 createTask를 통해 작업을 생성합니다. /command {JSON}은 명시적인 카탈로그 명령을 전송합니다. 인수 형태는 실시간 카탈로그를 확인하십시오. 애플리케이션과 동일한 백엔드 권한 부여 및 폴더 허용 범위가 적용됩니다.

앱은 저장된 봇 토큰 값을 어시스턴트에게 절대 전송하지 않습니다. 그럼에도 불구하고 스크린샷, 요약 및 대화 텍스트에는 비공개 프로젝트 정보가 포함될 수 있습니다. 봇 또는 소유자 계정을 더 이상 신뢰할 수 없는 경우 로컬에서 통합을 중지하십시오. 유출된 토큰은 봇 제공업체에서 교체(로테이션)한 다음 로컬의 암호화된 구성을 업데이트하십시오.

관련 지침: 비공개 봇 및 명령.

소유자 전용 네이티브 컴퓨터 권한

네이티브 컴퓨터 접근 권한은 기본적으로 비활성화되어 있습니다. 로컬 설정 → 원격 제어에서 소유자만 활성화할 수 있습니다. 어시스턴트 및 HTTP/MCP/Telegram 명령은 자신을 위해 이 플래그를 활성화할 수 없습니다. 작업이 거부되면 어시스턴트는 설정을 설명하고 소유자가 결정하도록 해야 합니다.

명시적으로 활성화된 경우 computer.run은 실행 파일, 인수 배열 및 선택적 절대 작업 디렉터리를 허용합니다. 셸 보간을 사용하지 않으며, 30초 제한이 있고 출력을 1 MiB로 제한합니다. 제공된 디렉터리가 없거나 유효하지 않으면 거부됩니다. cwd를 생략하면 HOME이 아니라 앱 소유의 설정 디렉터리가 사용됩니다. 종료(Quit)는 실행 중인 소유 명령을 취소하고 프로세스 정리를 기다립니다.

애플리케이션 읽기/작업 범위와 네이티브 접근은 서로 별개의 결정입니다. 작업 트리는 무제한 제공자의 파일 시스템 접근을 제한하지 않습니다. 작업 후 네이티브 접근이 더 이상 필요하지 않으면 취소하고, 어시스턴트의 설명 텍스트를 증거로 받아들이기보다 명령 영수증을 직접 검사하십시오.

관련 지침: 소유자 전용 제어 계약.

브라우저 및 원격 인스턴스

로컬 소유자가 서버를 활성화하고 주소, 포트 및 범위를 선택합니다. 검사를 위한 읽기 또는 작업을 위한 실행입니다. 기본 127.0.0.1 주소는 이 컴퓨터에서만 사용할 수 있습니다. 0.0.0.0은 네트워크 인터페이스에서 수신 대기하므로 활성화하기 전에 네트워크 접근을 검토하십시오.

브라우저는 토큰 로그인 후 동일한 인터페이스를 엽니다. 공개 링크나 스크린샷에 토큰을 포함하지 마십시오. HTTP 자체만으로는 트래픽을 암호화하지 않으므로 신뢰할 수 없는 네트워크에서는 보호된 채널을 사용하십시오.

소유자는 URL과 토큰을 통해 다른 인스턴스를 구성합니다. 백엔드가 요청을 프록시하며, 이것이 해당 프로젝트를 로컬 머신으로 복사하는 것은 아닙니다. 모든 작업을 수행하기 전에 선택한 인스턴스를 확인하십시오.

형식화된 명령과 이벤트가 애플리케이션 제어를 전달합니다. 읽기 범위는 작업 변경을 승인하지 않습니다. 네이티브 컴퓨터 제어는 별도의 로컬 소유자 선택 사항이며 기본적으로 비활성화되어 있습니다.

브라우저, Telegram 및 외부 에이전트 제어를 위해서는 앱이 계속 실행 중이어야 합니다. 각 인스턴스에는 고유한 비공개 프로필, 작업 상태, 토큰 및 서버 포트가 있습니다. 독립된 인스턴스 간에 하나의 프로필을 동시에 재사용하지 마십시오. 브라우저 이벤트 및 명령 응답은 선택한 인스턴스로 범위가 제한되며, UI를 전환해도 파일이 재배치되거나 네이티브 로그인이 복사되지 않습니다.

관련 지침: HTTP 및 인스턴스 제어.

OpenClaw, Hermes 및 기타 외부 에이전트

인증된 애플리케이션 제어 API 또는 번들로 제공되는 MCP stdio 브리지를 사용하십시오. 서버를 로컬에서 활성화하고 읽기 또는 작업을 선택한 다음, 해당 인스턴스 URL 및 토큰으로 각 클라이언트를 구성하십시오. 독립 실행형 MCP 브리지를 실행하려면 Node.js 22 이상이 필요합니다. Electron 앱은 에이전트 클라이언트를 설치하지 않습니다. 브라우저 URL은 스트리밍 가능한 HTTP MCP 엔드포인트가 아니므로 stdio 브리지에 ZIAFORGE_URL로 제공하십시오.

브리지는 ziaforge_status, ziaforge_commands, ziaforge_command 및 ziaforge_screenshot을 노출합니다. 상태 및 실시간 명령 카탈로그부터 시작한 다음 선택한 작업의 system.context를 읽으십시오. 형식화된 명령은 로컬 UI와 동일한 리비전, 게이트, 작업 폴더 및 정리 검사를 따릅니다.

실시간 명령 카탈로그에는 표준 영어 도움말인 documentation.guide와 해당 소스 경로 및 sourceSha256이 포함되어 있습니다. 내부 애플리케이션 설계자는 도구를 통해 동일한 참조를 수신합니다. 이를 통해 에이전트는 오래된 메모에 의존하지 않고 전체 제품 컨텍스트를 파악할 수 있습니다. 문서는 결코 접근 권한을 부여하지 않으며 현재 사용자의 결정을 대체할 수 없습니다.

에이전트는 사용자의 짧은 아이디어를 바탕으로 요구사항, 기술적 결정 및 계획을 논의해야 합니다. 명시적인 인간 게이트, 선택된 모델, 수동/Auto 정책 및 필수 검토를 유지해야 합니다. 승인을 임의로 꾸며내거나, 불확실한 명령을 새로운 ID로 재생하거나, 소유자의 의도 없이 Git 변경 사항을 게시해서는 안 됩니다.

여러 설치 환경을 위해 고유한 이름을 가진 여러 MCP 서버를 구성하십시오. 인스턴스 전환은 라우팅 결정이며 동기화가 아닙니다. OpenClaw 및 Hermes 구성 예시는 AGENT_CONTROL.md에 있습니다. 설치된 클라이언트 버전에 맞게 클라이언트별 설정 및 호환성을 확인해야 합니다.

외부 requestId 캐시는 앱이 실행되는 동안 제한된 요청 세트만 중복 제거합니다. 영속적인 작업은 자체 식별자를 사용합니다. 작업 생성에는 createRequestId, 워크플로 결정에는 commandId, 메시지에는 clientMessageId, operationId는 Git 변경에 사용됩니다. 확인 응답 상태를 알 수 없는 경우 원래 식별자와 페이로드를 보존하십시오. 새로운 작업을 의도적으로 발행하기 전에 저장된 상태를 읽으십시오.

관련 지침: MCP 클라이언트 안내.

로컬 CLI 및 자동화 한계

ziaf 디스패처는 동일한 실행 중인 앱과 저장된 워크플로를 제어합니다. 소스 환경에서는 npm run ziaf -- list, npm run ziaf -- status --task TASK_ID --json, npm run ziaf -- start --task TASK_ID, 또는 npm run ziaf -- pause --task TASK_ID를 사용하십시오. 시작 확인 응답에 성공했다고 해서 작업이 완료된 것은 아닙니다.

--until-success는 저장된 워크플로에 대해 의도적으로 Auto를 활성화하지만 질문, 검토, 승인 게이트, 제한 및 체크포인트는 여전히 적용됩니다. Ctrl+C는 관찰 중인 디스패처를 종료할 뿐 애플리케이션 워크플로를 묵시적으로 중지하지는 않습니다. 종료 코드, 로컬 엔드포인트 및 프로필 처리에 대해서는 CLI.md를 참조하십시오.

현재 자동화 인터페이스에는 디스플레이 정의와 로컬 실행 카운터가 저장됩니다. 공인된 반복 스케줄러가 아니며 백그라운드 모델 턴이 실행되었음을 증명하지 않습니다. 실제 실행을 위해서는 저장된 워크플로 컨트롤, ziaf 또는 인증된 API를 사용하고 해당 영수증을 검사하십시오. 데모 패널을 무인 스케줄링으로 오인하지 마십시오.

관련 지침: 디스패처 명령.

버전 및 업데이트

정보 창에 정확한 실행 버전이 표시됩니다. 공개 업데이트에는 신뢰할 수 있는 GitHub 릴리스 저장소와 안정 또는 미리보기 채널이 필요합니다. 확인, 다운로드 및 설치는 별도의 상태를 가집니다. 오류가 발생했다고 해서 업데이트가 설치된 것은 아닙니다.

자동 설치는 서명된 macOS 릴리스 전용입니다. 서명되지 않은 개발 빌드는 이 메커니즘을 통해 자동으로 설치되지 않습니다. 수동으로 교체하려면 현재 앱을 완전히 종료하고 검증된 아티팩트를 사용하십시오.

자동 확인은 활성화 시 즉시 실행되며, 이후 6시간마다 실행됩니다.

안정 채널은 미리보기 릴리스를 제외하며, 미리보기 채널은 개발 릴리스도 허용합니다. 확인 성공은 사용 가능한 릴리스 메타데이터만 설정할 뿐입니다. 다운로드 및 설치에는 플랫폼 패키지와 구성된 릴리스 피드가 필요합니다. Linux DEB 배포는 별도의 설치 경로입니다. DEB가 macOS 업데이트 메커니즘에 의해 자동으로 업그레이드된다고 가정하지 마십시오.

관련 지침: 릴리스 준비 상태.

다시 시작 및 복구

macOS에서는 완전한 종료를 위해 종료(Quit) / ⌘Q를 사용하십시오. 창을 닫아도 앱이 백그라운드에서 계속 실행될 수 있습니다. 애플리케이션을 교체하기 전에 이전 버전을 완전히 종료하십시오.

실행 후 동일한 작업을 선택하십시오. 기록과 임시 보관 내용이 복원됩니다. 다시 시작(Resume)은 네이티브/로컬 컨텍스트를 복원하지만 초안을 전송하거나 대기열 일시 중지를 해제하거나 알 수 없는 작업의 반복을 승인하지는 않습니다.

복구 화면이 나타나면 JSON을 직접 수동으로 편집하지 마십시오. 영향을 받는 문서 유형을 검사하고 원본 파일을 보존한 후 검증된 백업을 선택하십시오. 이전 대기열을 복원하면 해당 항목이 불확실한 상태로 표시됩니다.

전달 여부를 알 수 없는 경우 관리되는 워크플로는 새로운 컨텍스트에 대한 명시적 권한이 필요할 수 있습니다. 이전 작업과 실패한 시도는 유지되며, 조작된 성공보다 눈에 보이는 거부가 더 안전합니다.

모든 앱 인스턴스를 닫은 상태에서 작업 파일과 앱 프로필을 백업하십시오. 단순히 폴더를 복사한 것만으로는 검증된 복원이 아닙니다. 복구 시 검증된 백업을 선택하라는 메시지가 표시되면 손상된 파일 원본도 그대로 보관하십시오. 이전 워크플로나 대기열을 복원한다고 해서 불확실한 추론이나 Git 작업의 재생이 승인되는 것은 아닙니다.

관련 지침: 복구 계약.

문제 해결

CLI를 찾을 수 없음: 일반 터미널에서 설치 여부와 버전을 확인한 다음 ZIAForge를 다시 시작하십시오. 실행 파일이 있다고 해서 로그인된 것은 아닙니다. 공급자 자체의 로그인 메커니즘을 사용하십시오.

모델을 사용할 수 없거나 인증 실패: 검색을 새로 고치고 사용 가능한 ID를 선택한 다음 계정 및 한도를 확인하십시오. 기록을 검토하기 전에 불확실한 요청을 반복하지 마십시오.

워크플로 중지됨: 현재 단계, 질문, 확인 영수증 또는 CLI 로그를 여십시오. 답변되지 않은 질문, 명령, 폴더 권한 또는 시도 한도 등 구체적인 원인을 해결하십시오. 계속(Continue)을 누른다고 해서 실패한 검사가 성공으로 바뀌지는 않습니다.

폴더가 없거나 교체됨: 원래 폴더에 대한 접근을 복원하거나 새 작업을 만드십시오. 앱이 HOME에서 계속 진행해서는 안 됩니다. 다른 cwd가 감지되면 해당 턴을 중지하고 진단 정보를 보존하십시오.

문제를 보고할 때는 정보 창의 버전, 라우트, CLI/모델, 예상 동작 및 실제 동작, 스크린샷, 안전한 로그 발췌본을 포함하십시오. 비밀 정보, 개인 콘텐츠 및 공개할 수 없는 경로는 제거하십시오.

원격 페이지를 사용할 수 없음: 소유자가 서버를 활성화했는지 확인하고 수신 대기 주소와 포트를 확인한 다음 올바른 인스턴스 토큰으로 인증하십시오. 401은 인증 문제를 나타냅니다. 거부된 변경 작업은 읽기 전용 범위이거나 소유자 전용 제어 때문일 수 있습니다. 토큰을 변경하면 기존 브라우저 클라이언트가 닫힙니다. 별도의 DevTools 검사 포트를 원격 애플리케이션 제어로 노출하지 마십시오.

에디터 저장 거부됨: 초안을 유지하고 디스크의 현재 파일을 검사한 후 외부 변경 충돌을 해결하십시오. 애플리케이션 메타데이터를 다시 작성하여 비교를 우회하지 마십시오. 대용량 파일 전체 로딩을 사용할 수 없는 경우 지원되는 창 편집/검색 또는 외부 에디터를 사용하십시오.

Telegram 사용 불가: 봇 토큰, 숫자 소유자, 비공개 채팅 및 상태를 로컬에서 확인하십시오. 충돌하는 웹훅이나 폴러가 폴링을 차단할 수 있습니다. ZIAForge는 웹훅을 자동으로 삭제하거나 다른 폴러를 인계받지 않습니다. 알 수 없는 경계에서 거부되거나 중단된 명령은 자동으로 재생되지 않습니다.

관련 지침: 테스트 및 진단.

문제 보고 및 증거 검사

정보 창에 표시된 정확한 실행 빌드, OS/아키텍처, 작업 모드, 선택한 제공자/모델, 문제를 재현하는 단계를 기록하십시오. 예상 결과와 관찰된 결과를 설명하십시오. 비공개 프로필 전체 대신 안전한 스크린샷과 관련하여 보관된 명령 또는 검증 영수증을 포함하십시오.

CLI 로그, 이벤트 저널, 모델 트랜스크립트, 브라우저 추적 및 스크린샷에는 소스 코드, 개인 경로 또는 토큰이 노출될 수 있습니다. 공유하기 전에 검사하고 수정(리댁트)하십시오. 로그 수정 기능의 최선 노력 처리가 스크린샷이나 아카이브를 공개 가능한 상태로 보증하는 것은 아닙니다.

기여자의 경우 qa:doctor는 환경/빌드 식별 정보를 읽고, qa:inspect는 제공자 스텁이 있는 격리된 프로필을 엽니다. 픽스처는 모델에 연결하지 않고도 테스트 대상 애플리케이션 경로를 증명합니다. 실시간 추론, Telegram 연결성, 네이티브 Linux 데스크톱, 서명 및 패키징된 아티팩트 검사는 별개의 증거입니다. 재현 가능한 명령과 정리 방법은 TESTING.md를 참조하십시오.

관련 지침: 증거 명령.

로컬 데이터 및 경계

프로젝트, 기록, 계획, 문서 및 진단 정보에는 비공개 텍스트가 포함될 수 있습니다. 소스 코드와 함께 프로필, 원시 캡처, 키 또는 전체 로그를 공개하지 마십시오.

Linux에서 API, 제어, Telegram 및 인스턴스 자격 증명을 저장하려면 잠금 해제된 GNOME Secret Service 또는 KWallet이 필요합니다. 지원되는 비밀 저장소가 없으면 ZIAForge는 Electron의 basic_text 폴백을 사용하는 대신 이러한 비밀 정보의 저장을 거부합니다.

로컬 저장소에 저장된다고 해서 요청이 컴퓨터 내에만 머문다는 뜻은 아닙니다. 선택한 CLI/API가 해당 공급자에게 요청을 전송합니다. 작업 폴더와 프로세스 감시는 OS 격리가 아닙니다. 선택한 권한을 면밀히 검사하십시오.

증거 유형을 구분하십시오. 픽스처는 모델 없이 애플리케이션을 테스트하고, 네이티브 실시간 테스트는 실제 CLI/계정을 사용하며, 패키징된 검사는 특정 아티팩트를 인증합니다. 한 가지 테스트를 통과했다고 해서 다른 테스트가 보장되는 것은 아닙니다.

애플리케이션 범위, 작업 트리 및 읽기 전용 프롬프트는 운영체제 수준의 강제 적용과 다릅니다. Antigravity 검토자/도우미 정책은 파일 시스템의 읽기 전용 접근을 강제하는 대신 수집된 워크스페이스 증거의 변경 사항을 감지합니다. 네이티브 컴퓨터 제어는 일반적인 앱 도구 경계 밖에서 소유자가 승인한 프로그램을 실행하므로, 더 이상 필요하지 않을 때는 비활성화하십시오.

관련 지침: 출처 및 공개.

오픈 소스 프로젝트 이해 및 수정

먼저 AGENTS.md 및 CONTRIBUTING.md를 읽은 다음, 현재 소스 경계를 확인하기 위해 PROJECT_MAP.md를 읽으십시오. 구현된 형식화된 계약과 현재 워크플로/제공자 문서가 동작을 규정합니다. CONCEPT.md와 ARCHITECTURE.md의 터미널 우선 부분은 역사적 의도를 보존한 것이므로 현재 릴리스 사양으로 오인해서는 안 됩니다.

영어 도움말 소스는 docs/help/en.json입니다. 생성된 USER_GUIDE.md 또는 website/guide.html을 직접 수동으로 편집하지 마십시오. 표준 섹션을 변경하고, 영향을 받는 계약을 업데이트한 다음 node scripts/help/generate.cjs를 실행하십시오. 앱 내 도움말도 동일한 소스를 읽습니다. 제한 사항, 권한 및 지원되지 않는 경로를 포함하여 실제 구현과 함께 추가 사항을 검토하십시오.

56개의 인터페이스 로캘 각각은 docs/help/locales.json에서 개별 도움말 상태를 가집니다. 누락되거나 불완전한 도움말은 영어로 대체됩니다. 완전한 기계 번역 본문에는 라벨이 부착되고 사람이 검토했다는 주장 없이 영어 소스 해시에 연결됩니다. 사람이 검토한 번역에는 검토자가 추가로 기록됩니다. 모든 번역은 섹션 ID, 작업, 파일/명령 식별자 및 기술적 제한을 유지해야 하고, 올바른 텍스트 방향을 사용해야 하며, 영어 소스가 변경될 때 갱신되어야 합니다.

배포하기 전에 node scripts/help/generate.cjs --check를 실행하여 오래된 생성 출력, 잘못된 로캘 스캐폴드 또는 깨진 로컬 계약 링크를 감지하십시오. UI 번역 검사와 애플리케이션 동작 검사는 계속 분리되어 있습니다. HELP_MAINTENANCE.md는 기여자 및 AI 업데이트 절차를 제공합니다. 문서는 실행되지 않은 테스트를 통과했다고 주장해서는 안 됩니다.

관련 지침: 현재 프로젝트 맵 · 문서 유지 관리 · 기여자 지침 · 에이전트 지침.