blog-studio 팀원 설치 안내

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

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

0. 준비 확인

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. 확인

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)를 사용자에게 묻는다.

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 없는 파일)는 보여 주거나 보내지 않는다.

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. 받기

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. 설치

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

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

5. 토큰 [사용자 확인]

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

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 "제목" 으로 수정 요청 문서를 만들어 개발자에게 전달한다. 코드는 직접 고치지 않는다.

에이전트용 원문: /setup.md · MCP: /mcp