HolodoriCalc/docs/holodori-web-assistant.md

# 웹 계산기 AI 연결

ChatGPT 데스크톱 앱 또는 Codex가 연결된 브라우저의 기존 계산 화면을 조작하고 결과를 읽는다. 사이트 도구(WebMCP)가 제공되는 환경에서는 직접 호출도 사용할 수 있다. 계산은 기존 엔진을 사용하는 브라우저 Worker에서 수행한다. AI 대화는 ChatGPT에서 진행하므로 운영자가 추론 API 비용이나 계산 서버를 제공할 필요가 없다. TrueNAS, API 키, Sign in with ChatGPT 파트너 접근 신청도 이 구조에 필요하지 않다.

## 사용자 흐름

1. [공식 Windows 설치 파일](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi)로 ChatGPT 앱을 설치한 뒤 앱을 열어 계정으로 로그인한다. 주소는 OpenAI Windows 안내에서 연결하는 설치 경로다.
2. 평소 계산기를 사용하던 브라우저 프로필에 [공식 ChatGPT 확장](https://chromewebstore.google.com/detail/chatgpt/hehggadaopoacecdllhhajmbjkdcmajg?hl=ko)을 설치한다.
3. 앱의 설정 → Computer Use에서 해당 브라우저 연결 상태를 확인하고 필요한 연결 설정을 마친다.
4. 계산기 탭에서 확장 아이콘으로 대화창을 연다. 해당 브라우저의 기존 보유·성장 정보를 그대로 사용하므로 데이터 이전은 필요하지 않다. 데이터가 실제로 없을 때만 사용자 데이터 입력이나 백업 가져오기를 안내한다.
5. 도구 → AI 연결의 SKILL.md 링크를 GPT에게 먼저 읽게 한 뒤 현재 편성 분석이나 성장 가정 비교를 요청한다. AI가 배치 분석 등의 화면을 조작하고 읽으며 결과는 해당 계산 화면에 표시된다. 가정 비교 후 변경한 분석 조건을 복원하고 재계산으로 확인한다. 문서는 설치 없이 조작·해석 지침을 전달하며, 브라우저 연결 기능 자체를 제공하지는 않는다.

AI 연결 페이지는 브라우저 연결 방법, SKILL.md 사용 안내 링크와 요청 예시를 담은 AI 연결 안내만 표시한다. 별도 스킬 소개·플러그인 다운로드 영역, 직접 도구 연결 스위치·계산 확인 버튼, 최근 도구 분석 영역은 제거했다. 화면 조작에서는 연결 스위치가 필요하지 않다. 안내는 기본 조작이나 도구 호출 능력을 추가하지 않는다. 일반 웹·모바일 ChatGPT 채팅의 지원은 보장하지 않는다. 앱·모델·계정 정책과 기능 배포 상태에 따라 지원이 달라진다. [OpenAI 공식 브라우저 확장 안내](https://learn.chatgpt.com/docs/chrome-extension), [사이트 도구 안내](https://learn.chatgpt.com/docs/webmcp)

## 구현 범위

- `holodori_context`: 현재 브라우저의 보유·성장 요약, 활성 보드·연결 배치, 저장 편성 조회.
- `holodori_catalog`: 카드 이름·멤버·ID·보유·개화 또는 공개 악곡·난이도 검색. 최대 50개씩 조회.
- `holodori_analyze`: 편성 분석, 첫 편성 기준 비교, 제한된 조합 탐색. 최대 채보 3개·편성 8개·beamWidth 64·확률 표본 5000. 한 번에 하나의 작업만 허용하고 30초 제한 및 취소를 지원한다.

사이트 도구 구현은 남아 있으나 현재 안내 페이지는 도구 연결을 켜는 UI를 제공하지 않는다. 스킬은 이미 노출된 도구가 있을 때만 직접 호출하고 나머지는 화면 조작으로 진행한다. 호스트가 도구 이름에 고유 접미사를 붙일 수 있으므로 실제 발견한 이름으로 호출한다. 현재 Document API와 이전 Navigator API를 기능 확인 후 사용한다. 등록 시 AbortSignal을 전달하고 이전 unregisterTool도 지원한다. 연결 종료·페이지 종료 시 등록을 정리하고 오래된 호출도 차단한다. 새로고침 후에는 연결이 꺼진다. 지원하지 않는 브라우저에서도 기존 계산기 화면은 유지된다.

계산 시작 시 저장 데이터를 복사하며 분석과 가정 비교는 저장 데이터를 변경하지 않는다. 잘못된 ID와 지원하지 않는 쿨타임 값을 거부한다. 쿨타임 감소는 기존 계산기와 동일하게 보드 활성 상태와 무관한 최적화 변수이며 0/4/8/12를 탐색한다. 조합 탐색은 휴리스틱 후보군의 점수를 계산하는 방식이며 전역 최적을 보장하지 않는다. 여러 채보의 순위는 채보별 최적 점수의 합계다. 실시간 이벤트 보너스는 포함하지 않는다.

엔진은 `src/lib/engine/assistant-analysis.ts`로 공유한다. SvelteKit 레이아웃과 온라인 Pages 공용 진입점 모두 사이트 도구를 초기화한다. 별도 오프라인 산출물은 생성하지 않는다.

## 스킬 배포 파일

`plugins/holodori-web-assistant/skills/holodori-web-assistant`는 독립 스킬 폴더다. SKILL.md, UI 메타데이터, 화면 조작 지침과 직접 도구 요청 예시만 포함한다. 플러그인 형식은 상위 `plugins/holodori-web-assistant`를 사용한다. 엔진·카드·채보·Node 실행 파일은 포함하지 않는다. 화면 안내에는 평균/최고점 구분, 최고점 기준으로 정렬된 빈도 순위, 미사용/0% 차이, 보드 가정과 빈칸/0 덮어쓰기 차이, 새 계산 완료 확인과 조건 복원을 명시한다.

`npm run package:web-skill`은 ignored `plugin-dist`에 독립 스킬 ZIP과 설치용 플러그인 ZIP을 생성하고 파일 목록과 SHA-256을 검증한다. 검증한 파일을 `static/downloads`에도 복사한다. 현재 패키지는 독립 스킬 4파일/플러그인 6파일이다. 이 두 파일의 고정 다운로드 주소는 유지하며 AI 연결 화면은 설치 대신 사용 안내 문서 읽기를 안내한다. 안내 내용이 바뀔 때만 패키지를 다시 생성한다. 카드·채보 업데이트는 ZIP 변경이 필요하지 않다. 기존 Doricalc 등록을 재사용하거나 계정에 자동 업로드하지 않는다. 스킬 자체는 사이트 도구 미지원 환경을 지원 환경으로 바꾸지 않으며, 연결된 브라우저의 화면 조작을 대체 경로로 안내한다.

같은 명령은 SKILL.md와 두 참고 문서를 한 파일로 합친 `static/ai/SKILL.md`와 브라우저용 `static/ai/SKILL.html`도 생성한다. AI 연결의 링크는 다운로드가 아닌 HTML 문서 뷰어를 새 탭에서 열며, 뷰어에 전체 Markdown 원문과 파일 다운로드 링크가 들어 있다. 참고 문서 링크는 문서 내부 앵커로 바꿔 단독 읽기를 지원한다. 문서는 공개 자료이며 AI 전용 접근 제한은 없다. 온라인 Pages는 새 탭 링크를 해시 라우트로 바꾸지 않으므로 동일 문서를 열 수 있다.

## 검증 기록 — 2026-10-03

검증용 백업은 서로 다른 멤버 6장의 5성 카드, 모두 0개화, 메모리 10, 멤버 강화 3.2%, 보드 없음이다. 실제 데이터 가져오기 화면으로 격리된 로컬 브라우저 원점에 가져온 뒤 실제 WebMCP 도구를 발견하고 호출했다. API 모의 주입이나 클라우드 코드 변환은 사용하지 않았다.

| 검증 | 결과 |
| --- | --- |
| 도구 발견 | 데이터 요약·카탈로그·분석 3개 등록 |
| 소라·아키 고정, 소라 리더, SSS 2022 Easy 후보 4개 | complete, Worker 시간 2.414초 |
| 최고 후보 | 소라·아키·미코·AZKi·스이세이, 평균 1,024,124 / 이론 최고 1,155,842 / 종합력 205,159 |
| 소라만 4개화 가정과 현재 상태 비교 | complete, 1.234초, 평균 1,077,758 / 최고 1,217,186 / 종합력 211,854 |
| 평균 점수 증가 | +53,634 (+5.237%) |
| 가정 비교 후 원본 | 저장 시각 동일, 소라 보유 0개화 유지 |
| 존재하지 않는 카드 | error, 빈 results, 점수·순위 없음 |
| 온라인 Pages 빌드에서 같은 후보 탐색 | complete, 2.695초, 개발 환경의 4개 점수·순위와 동일 |
| 연결 해제 | 실제 등록 도구 3개가 모두 제거됨 |

위 시간은 반환된 준비·Worker 실행 시간이며 AI가 답변을 작성하는 전체 시간은 아니다. 도구 발견과 실행은 실제 내장 브라우저에서 검증했으나 새 스킬 플러그인을 계정에 설치한 뒤 자연어 한 문장으로 자동 호출하는 별도 대화는 아직 검증하지 않았다. 사이트 도구 API를 사용할 수 있기 전에 초기 HTML을 관찰하면 지원 상태 판단이 잘못될 수 있어 초기 로딩 안내를 구분했다.

자동 검증은 기존 엔진 수치 비교, 가정 적용 및 입력 불변성, 요청 검증과 쿨타임 조건, Worker 완료·오류·취소·시간 제한, 등록 실패 복구와 등록 중 연결 해제를 포함한다. 일반 웹 빌드와 온라인 Pages 빌드를 확인하며 커밋·푸시·공개 배포는 별도 승인 후 Gitea Actions를 통해 진행한다.

`npm run check`는 오류·경고 0개, 엔진 테스트 255개와 기존 분석 테스트 8개는 모두 통과했다. `npm run build`와 `npm run build:pages` 및 공개 데이터 검사를 통과했다. 패키지 생성 시 5파일 플러그인 ZIP 약 4.5KB와 3파일 스킬 ZIP 약 3.2KB의 목록·해시를 확인했다. 표준 스킬 Python 검증기는 해당 런타임의 PyYAML 누락으로 실행할 수 없었으며 패키지 검증에서 단순 스칼라 frontmatter와 필수 경로를 검사했다. 초기화·등록·조회·계산은 실제 브라우저 호출로 별도 확인했다.

## 화면 조작 스킬 독립 검증 — 2026-10-03

이전 대화·프로젝트 코드를 전달받지 않은 별도 AI에 스킬과 연결된 참고 문서만 제공하고, 사용자 Edge의 localhost 계산기에서 다음 요청을 수행하게 했다. 설치한 새 ChatGPT 대화의 자동 스킬 선택 검증과는 구분한다.

> 현재 편성으로 Play Dice! Expert 점수를 계산하고, 코보 카나에루를 명함으로 가정했을 때와 비교해줘. 비교 후 원래 분석 조건으로 되돌려줘.

| 조건 | 종합력 | 예상 점수 | 최고점·밀어치기 적용 | 최고점·미적용 |
| --- | ---: | ---: | ---: | ---: |
| 기준·코보 4개화 | 403,756 | 3,935,062 | 4,224,816 | 4,217,763 |
| 코보 명함 가정 | 396,242 | 3,808,400 | 4,098,013 | 4,091,245 |
| 원래 조건 복원 | 403,756 | 3,935,062 | 4,224,816 | 4,217,763 |

보탄 5/코보 4/마츠리 4/후부키 4/수영복 아냐 5개화, 하코스 벨즈 리더·레디언트 치즈, 빈도 고정 미사용, 파란 노드 전체 해제, 보너스 덮어쓰기 빈칸, 메모리 35개·멤버 강화 6.01% 조건이다. 명함 가정의 예상 점수는 -126,662점(-3.22%)이다. 매 조건에서 최고점 기준으로 배치를 다시 최적화했으며, 최고점 1위 조합의 평균 비교를 평균 전역 최적화로 설명하지 않았다. 실제 기준 3위 행의 예상 점수 3,935,616점이 1위보다 높다는 점도 구분했다.

복원 시 코보 인접 개화 표시 4, 나머지 입력, 계산 완료, 이전 조건 결과 경고 소멸, 기준/복원 결과 일치를 확인했다. 보유·성장 데이터, 보드, 프리셋, 저장 분석 기록은 조작하지 않았다. 사용자 Edge에는 WebMCP 직접 호출 기능이 노출되지 않아 화면 조작으로 수행했다. 안내는 이전 결과 경고와 조건별 재최적화 설명을 추가해 보완했다.

갱신 후 `npm run check` 오류·경고 0개, `npm run build`, `npm run build:pages` 통과. 패키지 생성에서 독립 스킬 4파일/플러그인 6파일의 허용 목록, 소스·ZIP·다운로드 복사본의 해시를 검증한다. 표준 Python 스킬 검증기는 여전히 PyYAML 누락으로 실행 불가하여 기존 패키지 frontmatter 검사와 실제 독립 동작 검증을 사용했다. 이 변경은 로컬 소스와 배포용 ZIP에 반영했으며 공개 배포는 Gitea Actions를 통한 후속 릴리스가 필요하다.

## 설치 없는 문서 읽기 검증 — 2026-10-03

또 다른 독립 AI에 로컬 스킬 파일이나 프로젝트 소스를 제공하지 않고, Edge에 열린 계산기의 AI 연결 페이지에서 SKILL.md 사용 안내를 먼저 읽고 현재 편성을 계산하도록 요청했다. 실제 `/tools/ai`의 링크를 따라 `/ai/SKILL.html` 전체 안내를 읽고 배치 분석에서 계산을 완료했다. 설치와 연결 스위치 없이 예상 점수 3,935,062점, 최고점 4,224,816점(밀어치기 적용)을 확인했으며 입력과 저장 데이터를 변경하지 않았다. 표시된 최고점 3위의 평균이 1위보다 554점 높다는 해석도 안내만으로 수행했다. 새 ChatGPT 대화의 계정별 기능 제공 여부까지 검증한 것은 아니다.

`npm run check` 오류·경고 0개와 온라인 Pages 빌드를 통과했다. Pages 해시 라우트에서 실제 링크 클릭으로 문서를 새 탭에 열고 전체 내용이 읽히는 것을 확인했다. Markdown/HTML 문서의 소스와 Pages 복사본 SHA-256도 일치했다. 검증용 미리보기 서버는 종료하고 사용자 계산기 탭을 유지했다. 공개 배포는 아직 수행하지 않았다.

## 최종 소스 검증 — 2026-10-03

AI 연결 변경만 포함한 격리 소스에서 기존 엔진·연동 수명주기 테스트 253개와 새 분석 연동 테스트 5개를 통과했다. 분석 연동 테스트는 기존 웹 엔진과 점수·종합력 일치, 성장 가정 및 원본 불변성, 실제 보드 효과, 잘못된 입력 거부와 고정 카드 탐색 조건을 검증한다. `npm run check` 오류·경고 0개, `npm run build`, `npm run build:pages` 통과. Pages 빌드의 기존 큰 번들 경고는 남아 있다. 공개 안내 문서와 ZIP 파일이 Pages 산출물에 포함되며 별도 스킬·플러그인 등록 없이 문서를 읽는 사용자 흐름으로 배포한다.