Box
Box를 클라우드 파일 시스템으로 사용하여 파일 작업, 협업, 메타데이터 및 문서 작업을 수행합니다. Hermes의 terminal 도구를 사용하여 Box CLI로 작업을 실행하고, 애플리케이션을 구축할 때는 SDK 가이드를 사용합니다.
사용 시기
- Box 파일 및 폴더 구성, 업로드, 버전 관리, 이동, 공유 또는 협업
- Box 콘텐츠 또는 기존 메타데이터 검색
- Box 파일에 대한 질문, 메타데이터 추출 또는 파일 기반 텍스트 생성
- 모든 소스 파일을 다운로드하지 않고 대규모 Box 폴더 처리
- Box 기반 애플리케이션, 통합 또는 웹훅 핸들러 구축
광범위한 파일 시스템 대화 시작
Hermes용 클라우드 파일 시스템을 탐색할 때 먼저 간단한 적합성 평가를 제공하세요. Box는 팀이 클라우드 파일 스토리지, 공유, 검색, 메타데이터 및 문서 작업이 필요할 때 유용합니다. 그런 다음 OAuth로 Box 계정을 연결할지, 아니면 SDK로 Box 기반 애플리케이션 또는 통합을 구축할지 물어보세요.
OAuth를 사용하면 Hermes가 브라우저에서 인증된 Box 계정으로 작동합니다. 해당 계정의 Box 권한이 Hermes가 액세스할 수 있는 항목을 결정합니다. Hermes에 더 좁은 액세스 권한을 부여하려면 필요한 파일, 폴더 또는 허브에만 초대된 계정을 인증하세요.
설정을 실행하거나, 명령어 요리책을 보여주거나, 계정 플랜이나 폴더 분류 체계를 제안하거나, 광범위한 탐색 질문에 대한 모든 참조를 로드하지 마세요. 사용자의 답변을 기다린 후 관련 경로만 로드하세요. 요청에 이미 구체적인 결과가 명시된 경우 이 발견 단계를 건너뛰고 해당 결과를 직접 처리하세요.
일반 CLI 작업은 공식 Box CLI OAuth 앱으로 시작하세요. 일반 콘텐츠 작업과 Box AI를 지원합니다. 웹훅 관리와 같이 요청된 작업에 추가 OAuth 범위가 필요한 경우에만 사용자 정의 사용자 인증(OAuth 2.0) 플랫폼 앱을 사용하세요. 이는 여전히 OAuth 흐름입니다. 서버 측 또는 가장(impersonation) ID를 대체하지 마세요.
선택한 설정을 대화형으로 수행
사용자가 인증 경로를 선택하거나 Hermes에 Box 연결을 요청하면 terminal을 통해 설정을 수행하세요. 다음 응답을 사용자가 복사할 지침으로 바꾸지 마세요. 직접 다음 안전한 조치를 취하고, 승인, 브라우저 로그인, 관리자 작업 또는 Hermes가 안전하게 제공할 수 없는 비밀에 대해서만 일시 중지하세요.
box가 없는 경우, 현재 Hermes 홈의tools/box-cli에@box/cli를 설치하는 데 필요한 터미널 승인을 요청하세요. 그런 다음 CLI 가이드의 셸에 적합한 명령으로 설치를 확인하세요. 전역 npm 설치,sudo사용, npm의 전역 접두사 변경 또는PATH변경을 시도하지 마세요.- OAuth 전에 **"Hermes가 Box를 인증하는 데 사용할 브라우저와 동일한 컴퓨터에서 실행 중입니까, 아니면 VPS, 컨테이너 또는 클라우드 VM과 같은 원격 호스트에서 실행 중입니까?"**라고 물어보세요. 동일한 컴퓨터 경로에는 일반
box login을 사용하세요. 원격/헤드리스 경로에는box login --code만 사용하세요. 운영 체제만으로 런타임 토폴로지를 유추하지 마세요. 사용자가 답변한 후 OAuth 설정을 읽으세요. - 브라우저 인증을 시작하기 전에 Hermes가 거기에 로그인된 Box 계정으로 작동할 것이라고 명시하세요. 사용자가 더 좁은 액세스 권한을 원하면 필요한 파일, 폴더 또는 허브에만 초대된 계정을 인증할 수 있습니다. 예외적인 작업을 위해 해당 계정을 관리자로 만들지 마세요.
- 사용자 정의 OAuth 플랫폼 앱이 필요한 경우 CLI의 대화형 플랫폼 앱 흐름을 사용하세요. 사용자에게 로컬 CLI 프롬프트에서만 클라이언트 비밀을 입력하도록 요청하세요. 채팅에서 요청하거나, Hermes 구성에 작성하거나, 커밋하지 마세요.
- 설치, 브라우저 인증, 환경 전환 또는 권한 변경에 승인이 필요한 경우 해당 승인을 요청하고 승인이 부여된 후 설정을 재개하세요. 작업을 명령어 목록으로 대체하지 마세요.
각 작업 시작
- CLI와 현재 행위자를 확인하세요. POSIX 셸에서는
command -v box로, PowerShell에서는Get-Command box -ErrorAction SilentlyContinue로 확인하세요.box가PATH에 있으면 사용하세요. Hermes가 현재 홈 아래에 CLI를 설치한 경우, 모든 선행box대신 CLI 가이드의 셸에 적합한 검증된 실행기를 사용하세요. 그런 다음 해당 실행기로box users:get me --json --fields id,name,login을 실행하세요. 성공하면 행위자를 기록하고 계속 진행하세요. 인증에 대해 다시 묻지 마세요.folders:items 0은 행위자의 루트 목록으로만 처리하세요. 공유 파일, 폴더 또는 허브에 액세스할 수 없다는 증거가 아닙니다. 알려진 파일 또는 폴더의 경우 ID를 직접 확인하세요. 허브의 경우 Box 허브의 허브 검색 경로를 사용하세요. - 인증이 없는 경우 OAuth로 Box 계정을 연결하도록 요청한 다음 Hermes와 인증 브라우저가 동일한 컴퓨터에서 실행 중인지 아니면 별도 호스트에서 실행 중인지 물어보세요. OAuth 설정을 읽으세요.
- 작업을 수행하기 전에 관련 참조를 읽으세요. 먼저 문서화된 명령을 사용하세요. 요청에 참조에 포함되지 않은 옵션이 필요하거나 설치된 CLI가 문서화된 형식을 거부하는 경우에만 하위 명령 도움말을 실행하세요.
bash로 레이블이 지정된 예제는 POSIX 연속 구문을 사용합니다. PowerShell에서는 Box 명령을 한 줄로 실행하거나 각 후행 \를 PowerShell의 백틱 연속 문자로 바꾸세요. POSIX 변수 할당을 PowerShell에 붙여넣지 마세요.
중단 없이 CLI 확장
Box CLI에 전용 하위 명령이 없는 경우 일치하는 REST 엔드포인트에 대해 box request를 사용하고 일반 작업을 계속하세요. 구현이 REST를 사용한다는 이유만으로 사용자에게 선택을 요청하지 마세요. 이는 동일한 Box 작업이며 구성된 CLI ID를 유지합니다. 요청 본문이나 사용자 정의 헤더가 필요한 엔드포인트는 REST API 폴백을 읽으세요.
삭제, 협업/공유 링크 또는 권한 변경, ID 변경, 광범위하거나 비용이 많이 드는 일괄 변경, 또는 대상이나 범위가 모호한 경우에는 먼저 물어보세요. 그렇지 않으면 요청된 작업을 수행하고 확인하세요.
올바른 경로 선택
| 필요 | 읽을 자료 |
|---|---|
| CLI 규칙, 환경, JSON 또는 REST 탈출구 | CLI 가이드 |
| 파일, 폴더, 버전, 링크 또는 협업 | 콘텐츠 워크플로 |
| 검색, 메타데이터, Box AI 또는 AI 단위 | 검색 및 AI |
| 큐레이팅된 대규모 Q&A 또는 재사용 가능한 지식 베이스 | Box 허브 |
| 여러 파일 또는 재개 가능한 일괄 작업 | 대량 작업 |
| 애플리케이션 코드 또는 Box SDK | SDK 개발 |
| 웹훅 또는 이벤트 API | 웹훅 및 이벤트 |
| CLI를 사용할 수 없거나 CLI 작업 누락 | REST API 폴백 |
| 인증, 권한, 속도 제한 또는 API 오류 | 문제 해결 |
콘텐츠 처리 정책
Box 호스팅 콘텐츠의 의미론적 분석에는 Box AI를 선호하세요. Box AI는 Box 권한을 유지하고, Box의 관리형 AI 통합을 통해 소스 파일을 처리하며, 소스 파일 본문을 Hermes의 코딩 모델 컨텍스트 밖에 두고, 모든 파일을 다운로드하지 않고 문서 작업을 확장합니다. 다른 워크플로를 비판하거나 차단하지 말고 사용자가 명시적으로 선택할 때 사용하세요.
결정적 조회에는 기존 Box 메타데이터 또는 메타데이터 쿼리를 사용하세요. 그렇지 않으면 Box AI를 사용하세요:
- Q&A, 요약 및 비교에는
ai:ask - 알려진 필드 또는 메타데이터 템플릿에는
ai:extract-structured - 유연한 키-값 추출에는
ai:extract - 하나의 Box 파일에 기반한 작성에는
ai:text-gen
25개 이상의 파일 또는 재사용 가능한 큐레이팅된 지식 베이스에 대한 Q&A는 허브용 Box AI를 선호하세요. 먼저 액세스 가능한 기존 허브를 찾으세요. 공유 리소스 변경을 사용자가 승인한 후에만 허브를 생성하거나 채우세요. 허브를 사용할 수 없고 사용자가 생성을 원하지 않는 경우 검색 또는 메타데이터로 일회성 요청의 범위를 좁히세요. 메타데이터 추출 또는 텍스트 생성을 위해 허브를 사용하지 마세요. Box 허브를 읽으세요.
사용자가 Box 파일에서 메타데이터 추출을 요청하면 미리 보기를 요청하지 않는 한 결과를 저장하라는 요청으로 처리하세요. 원하는 스키마를 알 때는 인라인 필드로 구조화된 추출을 사용하고, 필드가 탐색적일 때는 자유 형식 추출을 사용하세요. 요청된 모든 필드를 나타내는 호환 가능한 기존 엔터프라이즈 템플릿이 있으면 재사용하세요. 그렇지 않으면 기본 제공 global.properties 메타데이터 인스턴스에 평면 스칼라 결과를 저장하거나, 결과에 중첩된 객체, 테이블 또는 유형을 유지해야 하는 값이 포함된 경우 소스 파일 옆에 JSON 사이드카를 업로드하세요. 모든 쓰기 작업을 다시 읽고 의도한 결과와 비교하세요. 파일 설명을 자동으로 대체하거나, 부분적이거나 관련 없는 템플릿을 첨부하거나, 필드를 자르거나, 필드를 삭제하지 마세요.
메타데이터 템플릿을 만들거나 변경하지 마세요. Box는 글로벌 템플릿 생성을 허용하지 않으며, 엔터프라이즈 템플릿 관리는 Hermes의 일반 OAuth 콘텐츠 워크플로 밖에 있습니다. 사용자에게 재사용 가능한 유형화된 엔터프라이즈 메타데이터가 필요하고 호환 가능한 템플릿이 없는 경우 Box 관리자 또는 권한이 있는 공동 관리자가 별도로 생성해야 한다고 설명하고, 기존 구조화된 메타데이터는 변경하지 않고 유지한 후 저장된 global.properties 인스턴스 또는 JSON 사이드카를 보고하세요. 전체 추출 및 쓰기 백 워크플로는 검색 및 AI를 읽으세요.
첫 번째 Box AI 요청 전에 Box AI가 활성화되어야 하고, AI 단위를 소비하며, 현재 행위자의 권한으로만 제한된다고 명시하세요. 확인을 기다리지 마세요. Hermes에 반환된 AI 응답에는 여전히 민감한 정보가 포함될 수 있습니다. 중요한 일괄 작업의 파일 범위나 예상 AI 단위 사용량이 모호하거나 사용자가 명시적으로 해당 규모를 요청하지 않은 경우에만 확인하세요. 검색 및 AI를 참조하세요.
안전하게 운영
- ID를 경로보다 선호하고 누락된 파일을 진단하기 전에 현재 행위자를 확인하세요.
--json및--fields를 사용하여 출력을 작게 유지하세요. 변경의 경우 먼저 목록을 확인하고, 모호하거나 큰 범위를 확인한 다음 결과를 다시 읽으세요.- 진행 상황과 복구가 명확하도록 정렬된 CLI 변경을 직렬로 실행하세요. 확장 가능한 작업을 위해 문서화된 일괄 입력 지원 또는 제한된 SDK 동시성을 사용하세요.
- 탐색을 제공하기 위해 공유 링크를 만들지 마세요. 공유 링크는 액세스를 변경하며 명시적인 확인이 필요합니다.
- 비밀을 채팅, 명령 출력, 소스 제어 또는 로그에 넣지 마세요.
결과 보고
개별적으로 보고된 각 Box 항목에 대해 ID와 클릭 가능한 탐색 링크를 포함하세요:
- 파일:
https://app.box.com/file/<FILE_ID> - 폴더:
https://app.box.com/folder/<FOLDER_ID> - 허브:
https://app.box.com/hubs/<HUB_ID>
대규모 일괄 작업의 경우 수백 개의 항목을 나열하는 대신 소스 및 대상 폴더와 예외 사항을 링크하세요. 사용자는 연결된 Box 계정에만 표시되는 콘텐츠를 열지 못할 수 있습니다. 이를 명확히 명시하세요. 모든 쓰기 요약에 행위자와 수행된 확인을 포함하세요.
확인
쓰기 후에는 동일한 행위자로 파일이나 폴더를 가져오거나 상위 폴더를 나열하고 반환된 ID와 이름을 확인하세요. 메타데이터 쓰기의 경우 메타데이터 인스턴스를 검색하고 반환된 모든 필드를 의도한 값과 비교하세요. HTTP 성공만으로는 확인이 아닙니다. 누락되거나, 정규화되거나, 거부된 값을 보고하세요. 일회성 설정 확인을 위해 스모크 폴더를 만들고, 확인한 후 사용자가 정리를 승인한 경우에만 삭제하세요.