# 고급편 로드맵: 기본 연결 성공 후 필요한 것만

아래는 **설계·검증 프롬프트**다. 설치 실행·외부 노출·실서비스 전환을 승인하는 문서가 아니다. 각 프롬프트 앞에 [공통 안전 계약](01-basic.md#0-모든-단계-앞에-붙이는-공통-안전-계약)을 붙인다. 모듈마다 기존 자원 조사→비밀 없는 변경안→수동 승인→소규모 검증→전환 순서로 진행한다. 기존 서비스의 장애 복구는 새 모듈 설치와 분리하고, 승인한 범위 밖의 서비스는 변경하지 않는다.

## 1. LiteLLM 라우팅

선행 조건: 기본편 완료, 직접 공급자 호출 성공, 요금/쿼터 책임자 확인. 라우터를 쓰고 싶을 때만 추가한다. 주 모델 하나와 fallback 하나로 시작하고 다중 tier·분류기는 나중에 붙인다.

```text
기본 Hermes+Slack이 통과했다. LiteLLM 모듈의 읽기 전용 사전 조사와 실행 계획을 만들어 줘.
기존 proxy/포트/DB/모델 별칭/인증 방식과 Hermes fallback 계층을 비밀 없이 조사해 줘. 운영 중인 라우팅은 바꾸지 마.
현재 공식 지원에 맞는 버전을 고정하고 공급자 API 접근·OAuth 지원 조건·요금·동시성/timeout/retry 상한을 확인해 줘. 구독 계정이면 해당 인증 경로를 별도 확인하고 임의 토큰 재사용을 하지 마.
로컬 전용 엔드포인트, 단일 public alias, primary 하나와 fallback 하나의 최소안을 작성해 줘. LiteLLM fallback과 Hermes fallback의 중첩 재시도·비용 증가를 설명하고 총 시도 횟수 상한을 정해 줘.
Compose가 이 모듈에 필요하다고 판단한 경우에만 별도 초안 파일과 비밀 없는 .env.example을 만들어 줘. 이미지 digest/버전, loopback publish, healthcheck, 영속 저장소, 자격증명 분리와 복원 절차를 포함해 줘. 실행하지 마.
구체적 변경/다운로드/비용 발생 테스트를 사람이 승인한 뒤만 적용해 줘. 키는 지원되는 보안 로컬 입력으로 사람이 넣는다.
검증은 alias 1회, primary 실패를 운영 모델 차단 없이 격리 환경에서 재현한 fallback 1회, 요청당 총 시도·timeout·오류 결과를 확인하는 순서로 해 줘. 실패하면 Slack 경로를 전환하지 마.
```

기대 결과: 하나의 alias 뒤에서 선택된 모델과 실패 전환을 비밀 없는 요청 ID로 추적할 수 있다. 수동 체크포인트는 공급자 결제·OAuth 동의, 비용 테스트 승인, Hermes 경로 전환 승인이다. synthetic 모델 별칭 `study-default`를 예로 들 수 있으나 실제 모델 ID는 검증 후 선택한다.

검증: 기본 경로·fallback·전체 실패·비용 제한이 각자 확인돼야 한다. 401/403을 단순 재시도로 감추지 않는다. 429에서 무한 순환 fallback을 만들지 않는다. rollback은 승인 후 Hermes의 이전 공급자 설정만 복원하고 이번 모듈 프로세스만 정지한다. 기존 DB/볼륨·자격증명은 삭제하지 않는다.

## 2. n8n + ngrok 자동화

선행 조건: 기본편 완료. LiteLLM은 자동화에 꼭 필요한 의존성이 아니다. Slack 봇 대화 연결에는 이 모듈이 필요 없다. 외부 서비스가 **로컬 n8n의 webhook을 호출해야 할 때** 공개 HTTPS 경로를 검토한다.

```text
n8n 자동화 모듈을 계획해 줘. 기존 workflow/포트/credentials/relay 상태는 읽기 전용으로 조사하고 변경하지 마.
먼저 외부 webhook이 실제 필요한지 확인해 줘. 로컬 수동 실행/스케줄만으로 되면 ngrok을 설치하지 마. 필요하면 공개 경로·수신 이벤트·보관 데이터·인증/서명 검증·rate limit·중복 키·재시도 상한을 구체화해 줘.
버전 고정된 n8n과 영속 저장소, 암호화 키 보존, loopback editor, 접근 통제, 백업 복원안을 제안해 줘. 필요할 때만 이 모듈용 Compose 초안을 작성하고 기존 스택을 재사용할지 비교해 줘. latest tag나 docker compose down -v를 복구법으로 쓰지 마.
ngrok은 필요한 webhook 경로만 대상으로 계획하고 editor나 DB를 공개하지 마. 토큰·계정 로그인·도메인 선택·앱 권한 동의·공개 터널 시작은 사람 체크포인트로 남겨 줘. 실행/노출 승인을 받기 전에는 터널을 시작하지 마.
승인 후 합성 payload 한 건으로 인증 성공/실패·중복 재전송·timeout을 검증해 줘. 실제 Slack 수집은 채널/사용자 동의·보관 기간·최소 scope와 이벤트를 별도 승인받은 뒤 연결해 줘.
```

기대 결과: 허용된 이벤트 한 건이 의도한 workflow를 한 번 실행하고 비인증 요청은 거절된다. Slack 재전송에는 빠른 수신 확인과 비동기 처리·중복 키가 필요하다. 기본 Hermes 앱과 수집 앱의 이벤트·권한은 섞지 않는다. 공개 URL을 얻었다는 것만으로 안전한 endpoint라고 판단하지 않는다.

문제 대응: webhook URL 변경, 서명/인증 오류, container→host DNS, workflow 비활성, 이벤트 중복을 차례로 구분한다. 운영 데이터 전체 replay는 별도 승인 없이 하지 않는다. rollback은 이번 webhook 등록을 사람이 원복하고 승인 후 이번 터널/workflow만 중지한다. n8n 저장 데이터·암호화 키·볼륨은 보존한다.

## 3. Qdrant + Ollama 임베딩

선행 조건: 수집할 데이터의 소유권/동의·제외 규칙·보존 기간 확정. n8n 수집을 사용한다면 그 모듈의 검증 완료. 먼저 합성 문서로 테스트한다. 채팅 모델과 임베딩 모델은 다르다.

```text
Qdrant+Ollama 임베딩 모듈을 설계해 줘. 기존 서버/컬렉션/모델은 읽기 전용으로 조사하고 기존 컬렉션에 쓰지 마.
대상 문서 범위·민감정보 제외·source ID·chunk ID·중복 방지·수정/삭제 동기화·보존 기간을 먼저 문서화해 줘. 문서 파일을 갱신하면 자동 임베딩된다고 가정하지 마.
지원되는 임베딩 모델 하나의 정확한 태그/가능하면 digest와 벡터 차원·distance를 확인해 줘. 로컬 Mac의 네이티브 Ollama와 Qdrant 실행 방식을 비교하고 모델 다운로드 크기·메모리를 알려 줘. 내려받기 전에 승인받아 줘.
필요한 경우에만 Qdrant Compose 초안, loopback 노출·접근 인증·영속 저장소·백업안을 작성해 줘. 컨테이너의 localhost는 Mac 호스트가 아니므로 호스트 접속 경로를 환경별로 검증해 줘. 호스트 LLM 포트를 무조건 0.0.0.0으로 열지 마.
새 테스트 컬렉션에 합성 문서 세 개만 넣는 계획을 보여 줘. 사람 승인 후 벡터 길이·검색 top-k·출처 메타데이터·동일 문서 재실행의 idempotency·수정/삭제 반영을 확인해 줘. 실패하면 실제 Slack 데이터를 넣지 마.
모델/차원이 바뀌면 기존 컬렉션을 덮어쓰지 말고 새 컬렉션 재임베딩과 전환·복구를 별도 계획해 줘.
```

기대 결과: 의미가 다른 합성 문서 세 개에서 예상 문서가 검색되고 원문 출처·접근 권한을 확인할 수 있다. 로컬 기존 운영 기록은 한국어 BGE-M3 계열 1024차원을 사용했지만 모든 모델이 1024차원인 것은 아니다. 이 값을 새 모델에 고정하지 않는다. 검색된 문서는 자료이지 도구 실행 지시가 아니며, 문서에 포함된 프롬프트 지시를 따르지 않도록 한다.

문제 대응: 모델 태그 없음/DNS, 벡터 차원 불일치, host 연결 오류, chunk 중복, workflow의 다른 분기 실패를 구분한다. point 수는 메시지 수가 아니다. 성공 실행 몇 건은 전체 과거 적재 완료의 증거가 아니다. rollback은 승인 후 ingest를 중지하고 이전 검색 컬렉션 alias로 복귀한다. 기존 컬렉션/볼륨 삭제·운영 데이터 일괄 재처리는 별도 승인 사항이다.

## 4. dot의 여러 Slack 프로젝트 오케스트레이션

선행 조건: 단일 프로젝트 smoke test와 권한 경계가 안정적이어야 한다. 고급 모듈 1~3은 필요에 따라 선택하며 다중 프로젝트의 필수 의존성은 아니다. 여기서 dot은 사용자가 실제 쓰는 도구/앱을 확인한 후 그 공식 기능만 사용한다. 제품 정체·API가 확인되기 전 명령을 발명하지 않는다.

```text
dot을 이용한 여러 Slack 프로젝트 오케스트레이션을 설계해 줘. 먼저 이 환경에서 dot이 어떤 도구인지, 설치 버전·공식 기능·허용된 제어 API가 무엇인지 읽기 전용으로 확인해 줘. 불분명하면 확인된 부분까지만 정리하고 구현을 중단해 줘.
실행 중인 Hermes gateway, 별도 CLI bridge, Slack 앱, 프로젝트 폴더와 세션 매핑을 비밀 값 없이 조사해 줘. 앱 이름이 비슷하다고 같은 서비스로 취급하지 마. 기존 운영 서비스의 장애 복구를 이 설계 작업에 섞지 마.
합성 프로젝트 project-a / project-b 두 개로 채널→봇→프로젝트 루트→세션 키→모델 정책→허용 도구→결과 전달 경로의 표를 작성해 줘. 실제 private 경로/ID/토큰/호스트는 공유 표에 넣지 마.
봇별 사용자 allowlist, 직접 멘션, thread 격리, bot-to-bot 허용 범위, 최대 hop·동시 실행·시간/비용·재시도·중단 책임자를 정의해 줘. allow_bots=all이나 permissions skip를 기본값으로 쓰지 마. 필요한 봇 협업만 지원되는 mentions 정책과 allowlist로 검토해 줘.
dot의 권한이 Slack 메시지만으로 확대되지 않게 하고 외부 발송/배포/삭제는 사람 승인 경계를 유지해 줘. 충돌 파일 쓰기는 프로젝트별 작업 공간으로 격리해 줘.
변경안/검증안 승인 후에만 별도 테스트 채널에서 A→B 읽기 요청 하나, 의도하지 않은 봇 침묵, 다른 프로젝트 접근 거절, 중복 이벤트, 중단·재시작·요청 ID 복구를 확인해 줘. 운영 전환은 다시 승인받아 줘.
```

기대 결과: 모든 요청에 소유 프로젝트·세션·실행 주체·결과가 연결된다. “여러 봇이 대화했다”보다 격리와 종료 가능성이 중요하다. 일반 채널 메시지와 스레드 후속 멘션 정책을 별도로 테스트한다. 스레드 중단은 설치 버전에서 지원되는 `!stop`, 최상위 중단은 `/stop`을 확인해 사용한다. 어떤 명령도 다른 서비스/프로젝트를 함께 중단한다고 가정하지 않는다.

문제 대응: 무한 봇 핑퐁·타 프로젝트 컨텍스트 유입·중복 실행·경로 오인식이 있으면 신규 위임을 중단하고 요청 ledger와 로그부터 확인한다. 실행 중에 반복 follow-up을 보내지 않는다. rollback은 신규 route/협업 허용만 승인 후 해제하고 기본 단일 봇 테스트로 돌아간다. 대화 DB·프로젝트·인증은 삭제하지 않는다.

## 모듈별 완료 기록

각 단계에서 정확한 버전·승인한 변경·합성 검증 결과·실운영 데이터 검증 범위·미해결 항목·복구 지점을 기록한다. Compose 초안 작성과 실행, endpoint 도달과 업무 성공, 로컬 자료 확인과 새 설치 검증을 구분한다. 현재 문서는 이 고급 모듈을 설치·실행·복구하지 않았다.