# Persona Lab 스킬 설치

텍스트·이미지와 원하는 질문을 한국인 가상 인물에게 제시하고, 각 인물의 프로필·답변·이유를 확인하는 외부 에이전트용 스킬입니다. 이해·호감·신뢰·우려·구매 의향 등 조사 목적에 맞춰 사용합니다. 자료가 비공개여도 파일이나 접근을 허용한 로그인 화면에서 읽을 수 있습니다. 사용자가 가상 인물이나 모델을 직접 준비할 필요는 없습니다.

## 배포 파일

- ZIP: https://persona.spbros.com/skills/persona-lab.zip
- ZIP SHA-256: https://persona.spbros.com/skills/persona-lab.zip.sha256
- 스킬 지침: https://persona.spbros.com/skills/persona-lab/SKILL.md
- 실행기: https://persona.spbros.com/skills/persona-lab/scripts/review.py
- 에이전트 메타데이터: https://persona.spbros.com/skills/persona-lab/agents/openai.yaml
- API 사용법: https://persona.spbros.com/skills/persona-lab/references/api.md

API 키 없이 다운로드할 수 있습니다. HTTPS 주소를 사용하고 설치 전에 ZIP의 SHA-256을 제공된 값과 비교하세요. ZIP의 `persona-lab/` 폴더만 설치합니다. 키·비공개 자료·DB 비밀번호는 배포 파일에 포함되지 않습니다.

## 설치

1. ZIP과 SHA-256 확인 값을 임시 디렉터리에 내려받아 검증합니다. 압축 내용은 `persona-lab/` 아래 네 파일입니다. 절대 경로·`..` 경로·심볼릭 링크가 있는 압축 파일은 설치하지 않습니다.
2. 요청한 환경의 스킬 디렉터리에 `persona-lab/`을 복사합니다. 기존에 수정한 설치본은 먼저 보관합니다. 설치 범위를 넘는 설정이나 작업을 실행하지 않습니다.
   - Codex: `~/.agents/skills/persona-lab/`
   - Claude Code: `~/.claude/skills/persona-lab/`
   - 그 밖의 Agent Skills 지원 도구: 해당 도구의 스킬 설치 위치
3. 필요하면 에이전트 세션을 다시 열어 스킬을 발견하게 합니다. Python 3.10 이상과 표준 라이브러리만 필요합니다.
4. 설치한 `SKILL.md`와 `references/api.md`를 읽고 아래 연결 점검을 합니다. 설치·연결 점검만 요청했다면 유료 조사를 시작하지 않습니다.

## API 접근 키

서버는 `https://persona.spbros.com`입니다. 조사·조회·결과 다운로드에는 별도의 **Persona API 키**가 필요하며 모델 제공자 키가 아닙니다. 기존 `PERSONA_API_KEY` 환경변수나 비공개 키 파일을 사용하고, 없으면 키 설정만 요청하세요. 키를 생성하거나 추측하지 않습니다.

UTF-8 TXT 파일에 키 한 줄만 넣습니다. `KEY=`나 `Bearer `는 넣지 않으며 POSIX에서는 권한 0600으로 보관합니다. 키를 채팅·URL·명령 인자 값·자료·상태·보고서에 적지 않습니다. 실행기는 Authorization 헤더로만 전달합니다.

```bash
python3 /path/to/persona-lab/scripts/review.py --api-key-file /private/persona-api-key.txt --check
```

실제 경로로 바꿉니다. `PERSONA_API_KEY`가 설정되어 있으면 `--api-key-file`은 생략할 수 있습니다. 모델 호출은 하지 않으며 Worker·모델 제공자 동작까지 검사하지는 않습니다. HTTP 401은 키 누락·불일치, 503은 서버 설정·준비 상태 문제입니다. 429는 `Retry-After` 초만큼 기다린 뒤 같은 결과 폴더로 재개합니다. 새 조사나 반복 호출로 한도를 우회하지 않습니다.

## 설치 후 사용

AI에게 자료와 궁금한 질문을 전달하세요. 예: **“이 안내문과 이미지를 보고 어떤 내용으로 이해했는지, 헷갈리는 부분은 무엇인지 물어봐줘. 각 인물의 프로필도 보여줘.”**

전체 자료는 제공된 본문·파일이나 접근을 허용한 로그인 화면에서 읽습니다. 비공개 URL만으로 접근할 수 있다고 가정하지 않으며 자료를 공개하도록 요청하지 않습니다. 이미지가 있으면 실제 이미지 파일을 확보합니다.

```bash
python3 /path/to/persona-lab/scripts/review.py --api-key-file /private/persona-api-key.txt --text-file /private/material.txt --question '이 내용을 어떻게 이해했나요? 헷갈리는 부분과 그 이유를 알려주세요.' --require-images --image /private/photo.png --output-dir /private/survey-01
```

기본은 원하는 질문에 자유롭게 답하는 반응 조사(`--mode reaction`)입니다. 텍스트만 있으면 이미지 옵션을 생략하고, 이미지만 있으면 `--text-file`을 생략합니다. PNG·JPEG·WebP 최대 20장, 장당 5 MiB, 합계 30 MiB입니다. 요청한 인물 키워드는 새 조사에 `--keyword '캠핑'`으로 전달합니다.

**“이 상품을 살지 물어봐줘”**처럼 구매 의향을 명시하면 `--mode purchase`로 구매 의향 있음·없음·판단 보류를 조사합니다. 구매 의향 모드는 텍스트가 필요하며 이미지를 함께 보낼 수 있습니다.

새 조사마다 서버 설정에 따라 100만 개의 저장된 프로필 중 무작위 20명과 `gpt-6-luna` 한 모델을 사용합니다. 별도 요청이 없으면 인원·모델을 변경하지 않습니다. 실제 조사는 유료 모델 호출을 사용하며 자료·이미지가 조사 서버와 모델 API로 전달됩니다.

중단되거나 종료 코드 2가 나오면 새 조사를 만들지 말고 같은 폴더를 재개합니다. 저장된 질문·모드·인물·자료·이미지를 그대로 사용합니다.

```bash
python3 /path/to/persona-lab/scripts/review.py --api-key-file /private/persona-api-key.txt --resume /private/survey-01
```

결과는 실제 사용한 질문, 자유 답변과 이유·우려, 각 인물의 프로필, 유효·실패 응답을 함께 보여줍니다. 구매 의향 모드에서만 구매 선택을 집계합니다. 가상 인물의 합성 응답은 실제 사람의 의견·행동이나 판매 예측을 보장하지 않습니다. 사용자의 자료를 발행하거나 공개하지 않습니다.