본문으로 건너뛰기

시스템 · 명령 참조

qzx explainFileWithGemini

기능

미리 본 뒤 명시적인 승인을 받으면 파일의 제한된 샘플을 Google Gemini로 보내 설명을 받습니다.

명령 성숙도: Alpha

실제 사용과 피드백에 사용할 수 있지만 인터페이스와 동작은 아직 바뀔 수 있습니다. 현재 개발 체크아웃에 대한 평가입니다. 이후의 각 불변 릴리스 태그는 해당 버전에 포함된 정확한 평가를 보존합니다. PyPI 0.2.2.0.9에서 사용할 수 있습니다. 문서는 alpha 체크아웃 0.2.2.0.9에 해당합니다.

동작 및 내장 보호

실제 모드는 요청한 변경 사항을 적용합니다

미리보기 제공

네이티브 프로그램을 호출하지 않고 작동합니다

문서화된 작업을 위해 네트워크를 사용합니다

권한 상승 없이 작동하도록 설계되었습니다

기본 동작은 해석된 파일, 공급자, 지시 출처 및 제한만 미리 봅니다. 자격 증명을 읽지 않고 네트워크를 사용하지 않으며 내용을 공유하지 않습니다. 실제 요청은 dry_run=false와 apply=true를 요구하고 파일, 지시 및 각 샘플 구간을 제한하며 바이너리를 거부하고 키를 헤더로 전송합니다. 결과는 Google Gemini에 공유된 원본 문자 수와 모델을 정확히 보고하며 비밀 정보나 공급자의 오류 본문을 반환하지 않습니다.

문서화된 외부 서비스를 사용하며 아래에 설명된 데이터만 공유합니다.

이 안전 분류는 2026-08-25에 OpenAI GPT-5.6 Pro가 구현 다이제스트 sha256:ddc5d31a339e89383a9157b28bf5aae6e5d38a23b501f9728c1df1bab5d2e571를 기준으로 검토했습니다.

정확한 구문

qzx explainFileWithGemini <file_path> [sample_size] [model] [custom_prompt] [max_file_size_mb] [dry_run] [apply] --json

매개변수

밀거나 가로 스크롤 막대를 사용해 모든 열을 확인하세요.

이름유형필수기본값설명
file_pathstr예선언되지 않음설명할 텍스트 파일 경로
sample_sizeint아니요500시작, 중간, 끝에서 샘플로 가져올 문자 수(10-100000, 기본값: 500)
modelstr아니요""사용할 Gemini 모델. 비워 두면 사용 가능한 호환 모델을 선택
custom_promptstr아니요""제한된 샘플보다 먼저 Gemini에 전송할 사용자 지정 지시
max_file_size_mbint아니요10허용할 로컬 파일 최대 크기(MiB, 1-100, 기본값: 10)
dry_runbool아니요trueGemini에 연결하지 않고 어떤 종류의 데이터가 공유될지 정확히 미리보기
applybool아니요false외부 요청을 승인하며 dry_run=false가 필요

입력 예제

qzx explainFileWithGemini "path/to/file.txt"

파일 내용을 보내지 않고 제한된 샘플과 외부 서비스 미리보기

qzx explainFileWithGemini "path/to/file.txt" 1000 "" "" 10 --dry-run false --apply

각 샘플 구간에서 최대 1000자를 Google Gemini로 전송

qzx explainFileWithGemini "path/to/file.txt" 500 "gemini-2.5-flash" "" 10 --dry-run false --apply

명시적 승인 후 사용 가능한 특정 Gemini 모델 사용

전체 구조화 페이로드를 받으려면 --json을 추가하세요: qzx explainFileWithGemini <file_path> [sample_size] [model] [custom_prompt] [max_file_size_mb] [dry_run] [apply] --json

대표 출력 예제

이 예시 JSON은 현재 구현이 뒷받침하는 결과 계약에서 파생됩니다. 기록된 실행이라고 주장하지 않고 명령이 반환할 수 있는 내용을 보여 주며, 값은 입력, 장비, 권한 및 선택 도구에 따라 달라집니다.

예제 명령: qzx explainFileWithGemini "path/to/file.txt" --json

{
    "success": true,
    "message": "Previews and optionally sends bounded file samples to Google Gemini for explanation. In this illustrative example, the command completed successfully.",
    "meta": {
        "command": "explainFileWithGemini",
        "command_maturity": {
            "stage": "alpha",
            "label": "Alpha",
            "sequence": 2,
            "public_executable": true,
            "stability": "interface_may_change",
            "summary": "Available for real use and feedback while its interface and behavior can still evolve.",
            "promotion_review_required": false,
            "assessment_scope": "development_checkout"
        },
        "duration_ms": 0,
        "schema_version": 1
    },
    "details": {
        "dry_run": true,
        "content_shared": true,
        "external_service": "Example value"
    },
    "encoding": "Example value",
    "explanation": "Example value",
    "external_service": "Example value",
    "file_path": "C:\\project\\example.txt",
    "file_sha256": "C:\\project\\example.txt",
    "file_size_bytes": 4096,
    "model_used": "Example value",
    "next_step": "Example value",
    "sample_size": "Example value",
    "usage": "Example value"
}
JSON 결과 계약 보기
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message",
        "meta"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "meta": {
            "type": "object",
            "required": [
                "command",
                "command_maturity",
                "duration_ms",
                "schema_version"
            ],
            "properties": {
                "command": {
                    "type": "string"
                },
                "command_maturity": {
                    "type": "object",
                    "required": [
                        "stage",
                        "label",
                        "sequence",
                        "public_executable",
                        "stability",
                        "summary",
                        "promotion_review_required",
                        "assessment_scope"
                    ],
                    "properties": {
                        "stage": {
                            "type": "string"
                        },
                        "label": {
                            "type": "string"
                        },
                        "sequence": {
                            "type": "integer"
                        },
                        "public_executable": {
                            "type": "boolean"
                        },
                        "stability": {
                            "type": "string"
                        },
                        "summary": {
                            "type": "string"
                        },
                        "promotion_review_required": {
                            "type": "boolean"
                        },
                        "assessment_scope": {
                            "type": "string"
                        },
                        "note": {
                            "type": "string"
                        },
                        "review": {
                            "type": "object",
                            "required": [
                                "reviewed_on",
                                "rationale",
                                "evidence"
                            ],
                            "properties": {
                                "reviewed_on": {
                                    "type": "string",
                                    "format": "date"
                                },
                                "rationale": {
                                    "type": "string"
                                },
                                "evidence": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "replacement": {
                                    "type": "string"
                                }
                            },
                            "additionalProperties": false
                        }
                    },
                    "additionalProperties": true
                },
                "duration_ms": {
                    "type": "number"
                },
                "schema_version": {
                    "type": "integer"
                }
            },
            "additionalProperties": true
        },
        "details": {
            "type": "object",
            "properties": {
                "dry_run": {
                    "type": "boolean"
                },
                "content_shared": {
                    "type": "boolean"
                },
                "external_service": []
            },
            "additionalProperties": true
        },
        "encoding": [],
        "error": [],
        "error_code": [],
        "explanation": [],
        "external_service": [],
        "file_path": [],
        "file_sha256": [],
        "file_size_bytes": [],
        "model_used": [],
        "next_step": {
            "type": "string"
        },
        "sample_size": [],
        "usage": []
    },
    "additionalProperties": true
}

오류 및 제한

공개 계약은 실패 시 success=false와 설명적인 message를 요구합니다. 이 카탈로그는 아직 명령별 오류 분류 체계를 선언하지 않으므로 결과를 확인하고 존재하지 않는 코드를 추정하지 마세요.

QZX는 alpha 단계입니다. 선택적 종속성, 권한 및 호스트 기능에 따라 결과가 달라질 수 있습니다.

근거 흐름: 승인된 엔드포인트 또는 검토된 fixture 필요.

근거 및 출처

문서 채널
개발 문서 0.2.2.0.9 · main · sha256:cfba936e39931c286ca23add0ae546693db17d8b316e7cbc3891d26642d9b7e8
제공 여부
0.2.2.0.9 또는 이전

계속 살펴보기

관련 명령

이 명령들도 시스템 범주에 속합니다. 비교하여 작업에 가장 적합한 작업을 선택하세요.

모든 QZX 명령 살펴보기