Integration Helper·SDK 개발자 가이드

01 · 여기서 시작: 검토할 연동 준비

VibePackr는 AI 실행을 관리합니다. 작업에 API가 반환하는 정보 같은 외부 기능이 필요하면, 제품이 이해할 수 있는 형식으로 그 기능을 기술해야 합니다. 첫 번째 할 일은 그 설명을 준비하고 아직 해결해야 할 항목을 확인하는 것입니다.

개발자는 사용할 작업, 입출력 설명, 지원되는 비밀정보 없는 참조를 준비합니다. 공급자는 버전이 맞는 Helper·SDK 제공물, 공개 입력 형식, 지원 대상 Contract를 제공해야 합니다. Integration Helper는 입력을 확인하고 정리한 뒤 연동 제안인 후보 또는 누락 항목이 담긴 계획을 준비합니다. 이것이 먼저 검토할 유용한 결과이며, 실제 외부 서비스 연결 완료를 뜻하지는 않습니다.

처음 읽을 때: 도구 역할 확인 → 선언 이해 → 작은 예시 따라가기 → 단계 해설 읽기 → 필요한 제공 항목 요청. 버전이 맞는 제공물을 받으면 상세 참고 자료 를 이용하세요.

02 · 역할 및 범위

구성 요소의 역할과 지원 범위

하려는 일에 맞춰 도구를 고르세요. Helper는 연동 설명을 준비하고, SDK는 지원 라이브러리를 사용하는 프로그램의 인터페이스입니다. 어느 쪽도 고객 제품 배포를 대신하지 않습니다.

공급자에게 무엇을 요청하고 어떤 결과를 기대할지 판단하는 데 이 역할 구분을 활용하세요.

제품 설정은 고객 가이드를 따르세요.

GAPE R1은 AI 제공자 호출 없이 커밋 소스 구조를 관찰합니다. 외부 에이전트 보조와 제품 Vertex 런타임은 별도 경로입니다. 에이전트 및 AI에서 확인하세요.

03 · Contract/Document 선언: 무엇을 작성하는가

입력 예제와 제공 경계 확인

선언은 연결하려는 내용을 확인 가능한 형태로 구체화합니다. 신청서처럼 생각하면 됩니다. 연결할 작업과 정보를 기술하면 제품이 기존 지원 인터페이스에 맞는지 확인합니다.

목적: 연동이 어떤 입력·출력·기능을 제공하는지 버전이 정해진 문서로 표현하고, 제품이 지원하는 계약과 맞는지 확인하기 위한 것입니다. 일반 문서나 임의 JSON을 업로드하면 새 제품 계약이 생성되는 방식이 아닙니다.

작성 순서

1. 제공 버전과 승인된 공개 schema·샘플을 공급자에게 요청합니다. 완전한 고객 패키지가 대기인 동안 소스 문서 예제로 작성 준비를 진행합니다.
2. 지원되는 document 종류와 operation을 선택하고 필수 항목을 채웁니다. 내부 정책·권한 기록이나 원시 credential을 작성하지 않습니다.
3. R0/R2에 맞는 검증을 수행하고 반환된 상태·reason을 확인합니다. 양식이 다르면 실패를 보존하고 수정합니다.
4. 준비 결과와 미해결 항목을 검토한 뒤 지원되는 등록 검토 경로에 전달합니다.

제한된 R2 입력은 CUSTOM_API 문서와 지정된 MCP initialize/tools-list 관측입니다. 실전 소스 문서 에서 완전한 소스 형태·필드 설명·로컬 발견 결과를 확인할 수 있습니다. 완전한 고객 요청 봉투·대상 참조·제공 패키지는 여전히 확인이 필요합니다. 범용 OpenAPI 가져오기·모든 MCP 리비전·자동 제공자 연결은 입증되지 않았습니다.

04 · 설명용 흐름: 읽기 작업 하나 기술하기

개념 설명용 예시입니다. 개발 팀이 자체 서비스의 읽기 전용 상태 조회 작업 하나를 연동 대상으로 검토받고 싶다고 가정합니다. 팀은 먼저 작업, 받는 정보, 반환하는 정보, 필요한 비밀정보 없는 인증 참조를 설명합니다. 이 이야기는 특정 서비스 지원을 입증하거나 실행 가능한 스키마를 정의하지 않습니다.

공급자가 지원되는 공개 형식과 대상 Contract를 제공하면 이 설명을 선언으로 작성합니다. Helper는 선언을 읽고 일관된 descriptor(구조화된 설명)로 정리한 뒤 필드와 매핑을 확인하여 후보를 준비하거나 누락 사항을 알려줍니다. 매핑은 원본 필드가 어느 대상 필드에 대응하는지를 나타냅니다.

유용한 결과는 후보 또는 다음 필수 조치에 대한 설명입니다. 예를 들어 REQUIRES_AUTHORITY 가 r2-submit 에서 반환되면 현재 CLI가 연동을 등록하지 않았다는 뜻입니다. 유효한 후보도 지원되는 승인·등록 경로가 필요합니다. 후보를 로컬에 보관하고 버전·작업명·민감정보를 제거한 이유와 함께 지원에 해당 경로를 문의하세요. 이 응답으로 서비스가 연결되거나 실행됐다고 표시하지 않습니다. 이는 문서화된 동작을 해석한 예이며, 성공 실행을 캡처한 결과가 아닙니다.

같은 사례를 실습 예제에서 이어가세요. 완전한 소스 JSON·Contract 참조 조각·기록된 로컬 결과·오류 사례·다운로드를 제공합니다.

05 · 선언부터 실행 연결까지

현재 지원되는 준비 단계

각 단계는 서로 다른 질문에 답합니다. 입력을 이해할 수 있는지, 형식에 맞는지, 어떤 후보를 준비할 수 있는지, 어떤 승인이 남아 있는지를 확인합니다. 다음 행동을 정하기 전에 어디까지 도달했는지 읽으세요.

오류·미확인·권한 대기 상태에서 다음 단계로 자동 승격하지 않습니다. 이 흐름은 단계 구분이며, 현재 완결된 고객 실행 절차를 의미하지 않습니다.

06 · 지금 준비할 내용과 다음 요청

짧은 연동 요구사항을 준비하세요. 목표, 사용할 작업, 비밀정보 없는 입출력 설명, 이미 제공받은 대상, 필요한 매핑에 관한 질문을 담습니다. 필수·선택 필드는 이 요구사항 메모가 아니라 정확한 공개 형식에 따라 정해집니다.

support@vibepackr.com 에 버전이 맞는 바이너리·crate, 지원 플랫폼과 설치 안내, 승인된 공개 스키마와 성공 샘플, 지원되는 등록 경로를 요청하세요. 아키텍처 계획이 필요하면 그 용도를 알리고 공개 입력 패키지도 요청합니다.

준비 시도가 실패했다면 도구·제품 버전, 작업명, 아는 경우 입력 스키마 revision, 민감정보를 제거한 status/reason을 전달하세요. 형식 불일치, 누락 입력, 사용할 수 없는 인증 참조, 등록 경로 등 구체적인 항목을 문의합니다. 전체 문서·bundle·로그·비밀값은 첨부하지 않습니다. 공급 항목을 기다리는 동안에도 잘 정리된 연동 요구사항을 현재 결과물로 만들 수 있습니다.

07 · 상세 참조: 버전이 맞는 제공물과 함께 사용

처음 읽기는 여기서 마쳐도 됩니다. 구현 작업에는 버전·제공물을 먼저 확인하고 해당하는 R0 또는 R2 명령 참고 자료를 이용하세요. 아키텍처 계획 은 별도 입력·결과 형식을 사용합니다. 응답·오류 필드 로 결과를 해석하고, 진단 예제 는 설명된 용도로만 사용하세요.

08 · 버전·제공 상태

고객 제공 확인 대기

도구와 입력 형식의 버전이 맞아야 합니다. 제공물을 먼저 확인하면 설치·형식 불일치를 연동 문제로 오해하지 않을 수 있습니다.

문서 기준은 0.1.0-r232입니다. Helper R0/R2와 architecture planning 구현을 확인했지만, 모든 고객 image에 CLI가 설치되고 PATH에 노출된다는 뜻은 아닙니다. Rust SDK의 기존 호환성 선언은 0.1.x이며 모든 조합의 ABI 보장이 아닙니다.

• 공급자에게 정확한 binary/crate, 지원 플랫폼, 설치 방법과 해당 버전 입력 양식을 요청하세요.
• R0 schema는 packr.integration-helper.v1, R2 machine schema는 packr.integration-onboarding.r2.v1입니다.
• 현재 개발본과 향후 successor는 r232와 구분합니다. 최종 고객 제공 버전과 공개 성공 입력 패키지는 대기입니다.
• 확인되지 않은 package-manager 설치 명령이나 다운로드 URL은 제공하지 않습니다.

기술 호환성 참조: 기존 SDK 사용자는 PackrGUI와 내장 GEC subset입니다. 기존 라이브러리 사용을 나타내며 고객 패키지 제공을 뜻하지는 않습니다.

09 · Helper R0 명령

명령 참조 · 제공 조건 확인 필요

R0는 같은 원본 선언을 단계별 관점에서 확인합니다. 각 명령으로 준비 결과를 살펴보며, 한 결과를 다음 명령의 입력으로 연결하지 않습니다.

아래는 바이너리와 일치하는 입력 양식을 공급받은 환경에서 사용할 참조 문법입니다. source.json 은 실제로 준비해야 할 파일의 자리표시자입니다. 각 명령은 같은 source JSON을 입력으로 받고, 이전 stdout을 다음 입력으로 넘기지 않습니다.

R0는 선언된 HTTP/REST·CLI·실행 파일 메타데이터, 구조적 local IPC, structured manifest와 기존 runtime-provider 메타데이터를 각 지원 등급 안에서 처리합니다. 임의 shell 실행·network scan을 하지 않는 준비 경로입니다. R0의 gRPC·WebSocket·SDK 생성·repository onboarding은 deferred입니다. 성공은 stdout JSON의 decision=PASS , authority=NONE으로 구분합니다. 오류는 stderr JSON의 stage/reason/message와 종료 코드 2입니다.

packr-integration-helper discover source.json
packr-integration-helper normalize source.json
packr-integration-helper validate source.json
packr-integration-helper prepare source.json
packr-integration-helper inspect source.json

10 · Helper R2 명령과 필수 입력

명령 참조 · 제공 조건 확인 필요

R2는 프로그램이 읽을 수 있는 구조화된 응답을 반환합니다. 확인할 질문에 맞는 작업을 고르고 결과를 사용하기 전에 상태와 이유를 읽으세요.

각 명령은 해당 버전의 request.json을 다시 처리합니다. 최상위 필수 항목은 request_id, correlation_id , draft이며 draft의 정확한 공개 양식은 제공 대기입니다.

확인된 mapping은 IDENTITY(이름 변경 포함), STRING_TO_INTEGER의 제한된 변환입니다. scaffold 생성은 REQUIRES_IMPLEMENTATION준비 자산 범위이며 완성된 SDK·adapter·자동 등록이 아닙니다. 이 여섯 준비용 machine operation의 기존 검증은 로컬 합성 환경에 한정됩니다.

입력·결과 흐름 에서 소스 문서와 전체 요청을 구분하세요. R2 의미상 거부도 프로세스 종료 코드 0을 반환할 수 있으므로 status 와 reason을 확인합니다.

packr-integration-helper r2-discover request.json
packr-integration-helper r2-normalize request.json
packr-integration-helper r2-validate request.json
packr-integration-helper r2-prepare request.json
packr-integration-helper r2-status request.json
packr-integration-helper r2-submit request.json

11 · Contract 기반 계획과 결과 검증

고객 공개 지원 확인 대기

아키텍처 계획은 요청한 연동을 제품의 알려진 구성 요소·관계와 비교합니다. 실행에 앞서 빠진 연결이나 입력을 드러내는 데 도움이 됩니다.

구현 확인 · 고객 공개 지원 확인 대기

r2-plan-architecture 는 검증된 구조 정보와 정확한 제품 계약·대상·필수 입력의 연결을 받아 binding plan, validation plan, gap report 및 안내용 projection을 생성하는 경로입니다. r2-validate-architecture-bundle 은 생성 bundle의 형식·식별값·일관성·권한 비부여 조건을 확인합니다.

사용자는 공개된 양식이 제공되면 요청 대상과 허용 입력을 작성합니다. 제품의 계약·등록·owner·권한 사실이나 내부 구조 snapshot을 사용자가 임의로 만들어 성공을 주장하는 양식은 아닙니다. 현재 이 전체 입력의 공개 지원 계약·고객 제공 패키지는 확인되지 않았으므로 실행용 입력·명령 예제는 보류합니다.

성공 bundle이 만드는 public_guide 라는 결과 이름은 전체 bundle의 공개 허가가 아닙니다. 전체 내부 bundle·snapshot을 고객에게 보내지 않습니다. bundle validator 성공도 배포·provider 호출·권한 부여가 아닙니다.

12 · 응답·오류와 다음 조치

구현 기반 참조

명령이 정상 종료됐다는 것은 프로세스가 끝났다는 뜻입니다. 요청한 준비 단계의 성공 여부와 남은 조치는 응답에서 확인합니다.

R2에서는 거부도 stdout JSON envelope로 반환되며 프로세스가 정상 종료할 수 있습니다. 종료 코드만으로 성공을 표시하지 마세요.

표는 완전한 오류 목록이 아닙니다. 알 수 없는 reason도 보존하세요. Architecture planning 응답은 이 machine envelope와 별도이며 READY/NOT_READY 또는 validation result를 해당 형식으로 확인합니다.

13 · 최소 오류 처리·Rust API 예제

정적 예제 · 제품 실행 미검증

두 작은 참조 예제는 제한된 진단에 사용합니다. 잘못된 요청 응답을 처리할 수 있는지, 제공된 Rust 라이브러리에서 스키마 상수를 읽을 수 있는지 확인하는 예제이며 성공한 연동 시연은 아닙니다.

바이너리와 crate를 승인된 방식으로 공급받은 개발 환경용 참조입니다. 이번 문서 작업에서 실행·컴파일한 결과가 아닙니다. invalid-request.json에 {}만 저장한 뒤 아래 명령으로 필수 입력 누락을 확인할 수 있습니다.

정적으로 확인한 예상 필드는 status=DENIED, reason=INVALID_REQUEST, request_id=UNAVAILABLE , result=null입니다. 성공 예제는 공개 입력 양식·샘플이 확인될 때 추가합니다.

Rust 예제는 공개 schema 상수를 출력합니다. 예상 값은 packr.integration-helper.v1이며, crate 설치·배포·ABI 호환성 검증을 뜻하지 않습니다.

packr-integration-helper r2-validate invalid-request.json

use packr_engine_core::integration_helper::INTEGRATION_HELPER_SCHEMA_VERSION;

fn main() {
    println!("{}", INTEGRATION_HELPER_SCHEMA_VERSION);
}

14 · 인증·데이터·지원

접근과 안전한 지원 요청

지원을 요청할 때는 전체 입력 파일보다 버전과 짧은 결과로 실패 단계를 알리는 편이 안전합니다. 접근 비밀정보와 고객 데이터는 요청에 넣지 마세요.

로컬 파일 읽기·실행 권한은 필요하지만 제품 등록·작업 권한을 대신하지 않습니다. Helper 준비 명령은 원격 인증 세션이나 등록 권한을 발급하지 않습니다. credential reference와 실제 비밀정보 가용성도 구분하세요.

• 요청에 암호·토큰·개인키·raw credential을 넣지 않습니다.
• 입력 파일은 호출자 소유이며 Helper가 보관하지 않아도 호출자의 파일이 삭제되는 것은 아닙니다.
• 실제 provider·고객 데이터 처리에는 별도의 지원 연결·권한·데이터 조건이 필요합니다.
• 지원 언어 binding, 설치 경로, 공개 성공 schema, architecture 입력 패키지와 등록 transport의 미확정 범위는 공급자에게 확인합니다.

문의: support@vibepackr.com . 버전, operation, 민감정보를 제거한 status/reason을 전달합니다. 전체 입력 문서·bundle·로그 또는 비밀정보를 보내지 않습니다.

15 · 연동 용어 안내

계약

제품이 확인 기준으로 사용하는 지원 대상 인터페이스와 조건입니다.

Document / 선언

지원 형식으로 작성한 연동 설명입니다. 확인할 정보를 제공하며 권한을 부여하지 않습니다.

Descriptor / 정규화

Descriptor는 구조화된 설명입니다. 정규화는 지원 입력을 일관된 표현으로 정리하는 과정입니다.

후보

등록 검토를 위해 준비한 연동 제안입니다.

SDK / API

소프트웨어 개발 키트는 프로그래밍 수단을 제공하고, 애플리케이션 프로그래밍 인터페이스는 소프트웨어가 이를 호출하는 방법을 정의합니다. 여기서 지원되는 Packit 범위는 앞서 설명한 공개 Rust API입니다.

GAPE

아키텍처 계획에 쓰이는 제품 구성 요소와 관계에 대한 구조 관찰 정보를 제공합니다.

자격 증명 참조

인증정보를 가리키는 지원 식별자입니다. 비밀값 자체나 인증정보를 실제로 사용할 수 있다는 증명이 아닙니다.

바인딩 / READY

Binding은 연동 revision과 대상 같은 정확한 항목들을 연결합니다. 계획 결과의 READY는 계획 점검을 충족했다는 뜻이며, 실제 작업에는 별도의 접근과 승인이 필요합니다.

16 · 연동 시 자주 묻는 질문

기존 API 설명으로 시작할 수 있나요?

연동 요구사항을 준비할 때 사용할 수 있습니다. 실행 가능한 입력은 제공된 형식으로 제한됩니다. 제한된 CUSTOM_API와 지정된 MCP 관찰 입력은 참조에 설명되어 있습니다. 일반 OpenAPI 가져오기나 모든 MCP revision 지원을 약속하지 않습니다.

prepare나 submit을 하면 연동을 사용할 수 있나요?

준비 단계는 후보를 만듭니다. 현재 R2 CLI submit에는 여전히 권한이 필요하며 신뢰된 등록 전달 경로가 없습니다. 등록과 작업 실행에는 각각 지원되는 경로가 필요합니다.

성공한 JSON 예제는 어디에 있나요?

실습 예제 에 완전한 소스 문서와 로컬에서 관측한 발견 결과가 있습니다. 완전한 CLI 요청 봉투는 아닙니다. 명령 참조의 최소 {} CLI 예제는 의도적으로 거부를 보여주며 지원 대상 참조를 포함한 완전한 고객 요청 패키지는 대기입니다.

Helper 후보를 준비하는 데도 Vertex AI가 필요한가요?

제한된 R2 준비 처리는 클라우드 AI를 요구하지 않습니다. 고객 AI 작업에는 별도의 설정·검증 조건이 적용됩니다.

지원에 요청 파일 전체를 보내야 하나요?

지원 요청 안내에 따라 최소한의 버전·작업명·민감정보를 제거한 status/reason부터 전달하세요. 비밀정보·전체 입력 문서·내부 bundle은 메시지에 넣지 않습니다.