assistant.starium.site 고도화 스프린트 (2026-07-18)

hospital /opt/assistant — 대형 고도화 5종 + 후속 8종을 라이브 배포·검증. 임시 CEO /sprint 방식, 전부 근본 해결.

개요

hospital 서버의 assistant.starium.site(AI 통합 일정관리 플랫폼: web Next15 44p + api-gateway NestJS + ai-service FastAPI + mcp-server)에 대해 하루 동안 4대 대형 고도화와 그 후속 작업을 근본 해결 방식으로 라이브 배포했다. 각 작업은 헤드리스 E2E 또는 라이브 검증을 거쳤으며, 무회귀를 확인했다.

작업 요약 (Wave4 ~ Wave9f)

Wave	작업	커밋	상태
4	`<html lang>` 하드코딩 근본수정	27ee6af	✅ 라이브
5	커머스 시드 + `@IsUUID` cuid버그 근본수정	f7bd255	✅ 라이브
6	커스텀 i18n → next-intl 이관 (+react 이중본)	cfaea3c	✅ 라이브
7	Pipecat 실시간 음성 파이프라인	9f66bf5	✅ 라이브
8	실제 MCP 2.0 서버 (fastmcp)	d4031bc	✅
8b	MCP 서버 공개 노출	163494d	✅ 공개
8c	MCP 미등록 6 atom 배선 → 19툴	44b883a	✅
9	Agent Skills(SKILL.md) MCP 프롬프트	ab41572	✅
9b	웹 SkillBuilder SKILL.md import/export	6cfc926	✅
9c	react_agent SKILL.md 발동	bbfbf3e	✅
9d	UserSkill.settings 원본 SKILL.md 보존	ec180c0	✅
9e	react_agent DB 사용자스킬 발동	d7e5e7c	✅
9f	스킬 hot-reload	fe313bd	✅

Wave4 — `<html lang>` 하드코딩 근본수정

루트 app/layout.tsx가 전 로케일에 lang="ko"를 고정 발급 → en/ja/zh/vi/th 사용자의 스크린리더·검색엔진에 잘못된 언어 신호. Next 15 루트 layout은 [lang] param 접근 불가하므로 middleware가 활성 로케일을 x-lang 요청헤더로 전파 → 루트 layout이 headers()로 읽어 <html lang={lang}> 동적화.

검증: 6로케일 /login 200 + 정확한 lang (ko/en/ja/zh/vi/th 라이브 curl E2E).

Wave5 — 커머스 시드 + `@IsUUID` cuid 버그

shops 카탈로그 0건으로 장바구니→주문 E2E가 불가했다. 시드(멱등 upsert: 상점3·카테고리9·상품16)를 넣자 진짜 원인이 드러났다.

🔴 근본버그: shops/partners/lifecycle DTO의 @IsUUID() 17곳이 실제 cuid id를 거부. 스키마 전체 @default(uuid())=0 · @default(cuid())=184 → 모든 id가 cuid인데 검증기가 UUID를 강제 → cart/order/review/follow/파트너승인 전 write가 400. @IsUUID()→@IsString().
교훈: Prisma 기본 id는 cuid. class-validator @IsUUID()를 id에 붙이면 조용히 전 write API가 깨진다.

검증(E2E): login→cart(₩147,000·무료배송)→주문 ORDMRPY6IWD10·pointsEarned 3830(정확)→재고감소·서브임계 배송비 ₩3,000.

Wave6 — 커스텀 i18n → next-intl 이관

438KB 커스텀 React-context i18n(74파일이 useTranslation() 사용)을 스트랭글러-피그 shim으로 이관: 엔진만 next-intl로 교체하고 useTranslation() API 시그니처를 유지해 74개 호출부를 무수정. t()는 .raw()로 원문 반환(보간 없어 ICU 특수문자 안전).

🔴 선재 잠복버그: react 이중본(root react@18.3.1 vs web 19.2.7)으로 next-intl 클라 컨텍스트가 useContext null 크래시. root package.json overrides에 react/react-dom=19.2.7 단일화.
함정 4종: ①react 이중본 ②--install-strategy=nested가 트리 파괴(React #31) ③plugin/config 필수(런타임 500) ④서버→클라 함수 props 금지.

검증: 6로케일 실번역 렌더·키누출 0·18페이지 sweep 200·tsc0·build0.

Wave7 — Pipecat 실시간 음성 파이프라인

프론트에 스트리밍 음성 UI(voiceSocket.ts+VoiceAgentButton)는 있었으나 백엔드가 없었다. Pipecat로 구축:

브라우저 WS → VAD(Silero onnx, torch 불필요) → Groq STT(Whisper)
  → Groq LLM(Llama) → edge-tts(무료) → 오디오 재생   [전 과정 스트리밍]

STT/LLM은 기존 Groq 키, TTS는 edge-tts(무료). 프론트 voiceSocket.ts를 socket.io→raw WS로 교체(인터페이스 유지). 인프라: systemd PrivateTmp(ffmpeg)·NLTK_DATA·--host 0.0.0.0, nginx /voice/ws WS 프록시.

함정: VAD=별도 VADProcessor(TransportParams 아님)·전사는 TranscriptTap 릴레이·ffmpeg는 PrivateTmp·docker→호스트는 0.0.0.0.

검증(합성오디오 E2E, 공개 wss): 인사말→한국어 발화 스트리밍→STT 한국어("오늘 서울 날씨 어때요?")→LLM 한국어 응답→TTS 왕복 PASS. (브라우저 마이크 E2E는 수동 확인 잔여)

Wave8 — 실제 MCP 2.0 서버 (fastmcp)

기존 mcp-server(NestJS)는 REST /tools API일 뿐 MCP 프로토콜이 아니었다. fastmcp로 진짜 MCP 서버(streamable HTTP)를 구축, 19개 도구를 노출하고 실행은 기존 :7003 /tools/execute로 프록시(NestJS 무수정).

공개 라이브: https://assistant.starium.site/mcp (x-api-key 인증). fastmcp host=0.0.0.0 + UFW 172.16/12→7009(docker만 허용·외부 차단, 사용자 승인) + nginx /mcp(SSE).
8c: 미등록 6 atom(constructor에 prisma 필요) 배선 → 19툴 전체. 부수로 nest build 실패(pre-existing TS7006)·@prisma/client 미생성(node_modules 처닝) 근본수정.
함정: fastmcp ESM-only → .mjs 별도 실행.

검증(MCP SDK 클라이언트): initialize·tools/list 19·tools/call 실데이터·키無 401.

Wave9 — Agent Skills (SKILL.md) 6각 완결

기존 skills 기능은 tool-chain 매크로일 뿐 Anthropic Agent Skills(SKILL.md) 표준 미지원. 저작→저장→발동→hot-reload 전체 흐름을 완성했다. 세 소비자(MCP·웹·에이전트)가 같은 apps/mcp-server/skills/ 디렉토리를 공유한다.

#	작업	핵심
9	MCP 프롬프트 노출	SKILL.md 4종→`addPrompt`(progressive disclosure: list=name+desc, get=본문)
9b	웹 SkillBuilder import/export	`lib/skillMd.ts` 라운드트립(frontmatter+mco:steps JSON블록)
9c	react_agent 발동	시스템프롬프트에 카탈로그+매칭스킬 절차 주입
9d	원본 SKILL.md 보존	`UserSkill.settings`에 원본 prose 저장
9e	DB 사용자스킬 발동	asyncpg로 `user_skills` 조회, 전역+사용자 병합
9f	hot-reload	MCP `fs.watch`→`addPrompt` 재호출(무재시작·list_changed), 파이썬 mtime 캐시

핵심 검증: 라이브 /api/v1/agent/run "Give me my morning briefing" → 에이전트 thought = "the morning-briefing skill is active. first step call get_current_time" → 스킬 절차대로 도구 실행·스킬 출력포맷대로 답변. = SKILL.md가 실제 에이전트 행동을 유도함을 실증. quick-note SKILL.md 추가→공개 prompts/list 즉시 5(무재시작).

한계(정직): fastmcp에 removePrompt 부재 → 스킬 파일 삭제는 hot-reload 불가(재시작 필요, 로그 표기). 추가/수정은 즉시 반영.

최종 상태

공개 엔드포인트: https://assistant.starium.site (6로케일 정확 lang), /mcp (MCP 2.0, 19툴 + 4 Agent Skills 프롬프트), /voice/ws (실시간 음성 wss)
서비스: assistant-web / assistant-api(×4) / assistant-ai(systemd, 음성+에이전트) / assistant-mcp-server(:7003) / assistant-mcp-stream(:7009) 전부 online
무회귀: 전 웨이브 후 web/api 200, docker 38컨테이너 정상, 커머스 시드 유지

HQ 전 채널 반영 현황 (12 채널)

이번 스프린트를 star365 HQ의 모든 공개 채널에 각 서비스 성격에 맞게 반영했다. 이 리포트 하나에서 전 반영 지점으로 이어진다.

#	채널	반영 형태	링크
1	docs 홈	상단 featured 카드	https://docs.star365.site/
2	docs 04-report	세션 리포트(본 문서)	https://docs.star365.site/04-report/assistant-starium-advanced-sprint-20260718.report
3	AI 직원 명부	"배포 자동화" KPI + 링크	https://docs.star365.site/ai-employees/18
4	8 본부장	"인프라 본부장" 완료 태스크	https://docs.star365.site/departments/infra-lead
5	admin 관제	대시보드 상단 배너	https://admin.star365.site/
6	status 헬스	assistant + MCP 엔드포인트 모니터링	https://status.star365.site/
7	ceo Command	타임라인 + 알림	https://ceo.star365.site/
8	team Multica	완료 이슈 (#5)	https://team.star365.site/
9	models 벤치	"실전 적용" 배너(채택 모델 스택)	https://models.star365.site/
10	api 브릿지	`latestSprint` API	https://api.star365.site/hq/latest-sprint
11	obs Langfuse	스프린트 trace(6 span + score)	https://obs.star365.site/
12	translate PWA	설치 랜딩 배너 + CHANGELOG	https://translate.star365.site/app-install.html
—	members 회원	마이페이지 서비스 업데이트(회원용)	https://members.star365.site/me

HQ 관제·문서·의사결정·협업·벤치·API·LLM관제 채널엔 상세 리포트를, 회원 페이지엔 회원용 서비스 안내를 반영(내부 로그 비노출).

교훈 (재사용)

Prisma id는 cuid — @IsUUID()를 id에 붙이면 전 write API가 조용히 깨진다.
node_modules 대량 재설치(npm install/override) 후엔 prisma generate 재실행 — 안 하면 prisma 쓰는 서비스가 다음 재시작에 죽는다.
fastmcp는 ESM-only — CJS NestJS에 통합 불가, .mjs 별도 실행.
bash heredoc + JS 템플릿리터럴(백틱/${}) — ssh "..." 안에서 명령치환으로 파일 깨짐. 전체 파일 로컬 작성 + scp가 정답.
Silero VAD는 8k/16k만 — 브라우저 캡처를 16k로 맞춰야 한다.
docker nginx→호스트는 --host 0.0.0.0 바인드 필수(loopback이면 502).

남은 것 (소규모·비긴급)

음성 브라우저 마이크 E2E 수동 검증 · SkillBuilder 다운/업로드 브라우저 E2E 수동 검증
any 타입 정리 · shim→next-intl 직접 전환(점진) · 스킬 삭제 hot-reload(fastmcp removePrompt 대기)