# blog-studio 팀원 설치 안내

이 페이지는 사람과 AI 에이전트(Claude Code·Codex)가 함께 읽는다. 사용자가 "이 주소를 보고 이 폴더에 세팅해줘"라고 하면 에이전트는 아래 순서대로 진행한다.

- **[사용자 확인]** 표시가 있는 단계에서는 멈추고 사용자에게 할 일을 알린 뒤, 끝났다는 말을 들으면 이어 간다.
- 토큰·비밀키는 묻거나 출력하거나 채팅에 남기지 않는다. 사용자가 파일에 직접 넣는다.
- 이미 있는 폴더·파일은 덮어쓰지 않는다. 막히면 그 단계에서 멈추고 무엇이 막혔는지 알린다.

## 0. 준비 확인

```bash
git --version
node --version          # v22 이상
python3 --version
ls "/Applications/Google Chrome.app"   # macOS. Google Chrome 이 있어야 한다
curl -s https://blog.ai-studio.smiledragon.co.kr/healthz          # ok 가 나와야 한다(사내망·VPN)
```

- Node 가 없거나 22 미만이면: `brew install node@22` (Homebrew), 또는 nodejs.org 의 LTS 설치 파일.
- pnpm 은 따로 설치하지 않아도 된다. 설치 스크립트가 Node 에 든 corepack 으로 정해진 버전을 쓴다.
- python3 가 없으면: `xcode-select --install`.
- `/healthz` 가 응답하지 않으면 사내망·VPN 연결을 사용자에게 확인한다.

## 1. 설치 폴더

사용자가 말한 폴더를 쓴다(말하지 않았으면 `~/blog-studio`). 폴더가 이미 있고 비어 있지 않으면 멈추고 사용자에게 묻는다.

## 2. 기기 배포 키 [사용자 확인]

배포 저장소는 기기마다 **읽기 전용 배포 키**로 받는다. 이미 세팅한 기기일 수 있으니 **먼저 확인하고, 없는 것만 만든다.** 키 파일이 이미 있으면 절대 다시 만들지 않는다(덮어쓰면 등록해 둔 키가 쓸모없어진다).

### 2-1. 확인

```bash
ls ~/.ssh/ai-studio-blog-deploy ~/.ssh/ai-studio-blog-deploy.pub
grep -A5 '^Host ai-studio-blog-client$' ~/.ssh/config
git ls-remote git@ai-studio-blog-client:nextflow-corp/ai-studio-blog-client.git HEAD
```

| 결과 | 할 일 |
|---|---|
| 세 번째 명령이 커밋 해시를 보여 준다 | 이미 된다. 3단계로 간다 |
| 키 파일·설정 블록이 있는데 `Permission denied`·`Repository not found` | 키가 아직 등록되지 않았다. 2-4(전달)로 간다 |
| 키 파일이 없다 | 2-2 부터 |
| 키 파일은 있고 설정 블록이 없다 | 2-3 부터 |

### 2-2. 키 만들기 (키 파일이 없을 때만)

키 이름표로 쓸 `<이름>-<기기>`(예: `hong-macbook`)를 사용자에게 묻는다.

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
test -f ~/.ssh/ai-studio-blog-deploy || ssh-keygen -t ed25519 -N "" -f ~/.ssh/ai-studio-blog-deploy -C "<이름>-<기기>"
```

### 2-3. SSH 설정 (블록이 없을 때만)

`~/.ssh/config` 끝에 아래 블록을 더하고 `chmod 600 ~/.ssh/config` 한다. 같은 `Host` 블록이 있으면 더하지 않는다.

```
Host ai-studio-blog-client
  HostName github.com
  User git
  IdentityFile ~/.ssh/ai-studio-blog-deploy
  IdentitiesOnly yes
  StrictHostKeyChecking accept-new
```

### 2-4. 관리자에게 전달 [사용자 확인]

공개키를 클립보드에 복사하고(macOS) 그 한 줄을 사용자에게 보여 준다. 공개키는 보여 줘도 된다. **비밀키(`.pub` 없는 파일)는 보여 주거나 보내지 않는다.**

```bash
pbcopy < ~/.ssh/ai-studio-blog-deploy.pub
cat ~/.ssh/ai-studio-blog-deploy.pub
```

사용자에게 아래 형식으로 관리자에게 보내라고 안내한다(사내 메신저 등).

```
[ai-studio-blog 배포 키 등록 요청]
이름-기기: <이름>-<기기>
공개키: <방금 복사한 한 줄>
```

관리자는 배포 저장소의 Deploy keys 에 **읽기 전용**(Allow write access 끔)으로 등록한다. 사용자가 등록됐다고 하면 2-1 의 `git ls-remote` 를 다시 돌려 커밋 해시가 나오는지 본다. 계속 `Permission denied` 면 관리자에게 등록한 공개키가 위 한 줄과 같은지 확인해 달라고 한다.

## 3. 받기

```bash
git clone git@ai-studio-blog-client:nextflow-corp/ai-studio-blog-client.git <설치 폴더>
cd <설치 폴더>
git checkout "$(git tag --list 'v*' --sort=-v:refname | head -1)"
```

## 4. 설치

```bash
node scripts/setup.mjs --server https://blog.ai-studio.smiledragon.co.kr/mcp
```

작업 공간(`workspace/`)과 설정 파일(`workspace/.env`)을 만들고 의존성을 설치(pnpm)한 뒤 점검한다. 이 단계의 점검은 토큰이 없어 한 항목이 실패하는 것이 정상이다.

## 5. 토큰 [사용자 확인]

관리자에게 받은 본인 토큰을 사용자가 `workspace/.env` 의 `BLOG_STUDIO_TOKEN=` 뒤에 **직접** 붙여넣게 한다. 에이전트는 토큰을 묻거나 대신 넣지 않는다. 넣었다고 하면 점검한다.

```bash
node scripts/doctor.mjs
```

"점검 통과"가 나오면 설치가 끝났다.

## 6. 시작

설치 폴더에서 Claude Code 나 Codex 를 새로 연다. 폴더의 `AGENTS.md` 지침이 적용된다. 서버 툴은 `node packages/media/dist/remote.js call <tool> '<json>'` 으로 부른다(토큰은 작업 공간 `.env` 에서 읽는다).

첫 요청 예: "발행할 블로그 목록 보여줘", "새 블로그 추가해줘".

## 업데이트·문제

- 업데이트: `node scripts/update.mjs` (코드 수정이 없을 때만 최신 릴리스로 바꾸고 바뀐 점을 보여 준다)
- 점검: `node scripts/doctor.mjs`
- 고칠 것·필요한 기능: `node scripts/new-request.mjs "제목"` 으로 수정 요청 문서를 만들어 개발자에게 전달한다. 코드는 직접 고치지 않는다.