diff --git a/src/common/nats-subjects.ts b/src/common/nats-subjects.ts index 2459847..635195d 100644 --- a/src/common/nats-subjects.ts +++ b/src/common/nats-subjects.ts @@ -3,6 +3,8 @@ import type { EvalReport } from "@eval/types"; export const AGENT_REQUEST_SUBJECT = "lolympus-agent.request"; export const AGENT_ALERT_SUBJECT = "lolympus-agent.alert"; export const AGENT_EVAL_REPORT_SUBJECT = "lolympus-agent.eval.report"; +export const DISCORD_MEMBER_LOOKUP_SUBJECT = + "lolympus.discord.lookup-members"; export interface AlertPayload { kind: "latency" | "eval-score-drop" | "llm-error-rate" | "endpoint-down"; @@ -17,3 +19,36 @@ export interface AlertPayload { } export type EvalReportPayload = EvalReport; + +export type DiscordMemberMatchSource = + | "guild-nickname" + | "global-name" + | "username" + | "joined-after"; + +export interface DiscordMemberCandidate { + memberId: string; + joinedAt: string; + guildNickname?: string | undefined; + globalName?: string | undefined; + matchedBy?: DiscordMemberMatchSource | undefined; + username: string; +} + +export interface DiscordMemberLookupRequest { + chatroomId: string; + joinedAfter: string; + searchName?: string | undefined; + userId: string; +} + +export type DiscordMemberLookupResponse = + | { + status: "ok"; + joinedAfterMatches: DiscordMemberCandidate[]; + nicknameMatches: DiscordMemberCandidate[]; + } + | { + status: "error"; + reason: string; + }; diff --git a/src/common/nats.ts b/src/common/nats.ts index 5affac3..f4c9e03 100644 --- a/src/common/nats.ts +++ b/src/common/nats.ts @@ -106,6 +106,26 @@ export class NatsClient { await client.flush(); } + async request( + subject: string, + data: TRequest, + options?: { timeoutMs?: number | undefined }, + ): Promise { + const requestOptions = + options?.timeoutMs !== undefined + ? { + timeout: options.timeoutMs, + } + : undefined; + const response = await this.getConnection().request( + subject, + this.stringCodec.encode(JSON.stringify(data)), + requestOptions, + ); + + return this.decodeMessage(response); + } + respond(msg: Msg, data: unknown): Promise { if (!msg.reply) { this.logger.warn( diff --git a/src/config.ts b/src/config.ts index 3fe9da2..56c84cd 100644 --- a/src/config.ts +++ b/src/config.ts @@ -79,10 +79,21 @@ export function getRequestSubject(): string { ); } +export function getDiscordMemberLookupSubject(): string { + return ( + process.env["DISCORD_MEMBER_LOOKUP_SUBJECT"]?.trim() || + "lolympus.discord.lookup-members" + ); +} + export function getAgentRequestTimeoutMs(): number { return getPositiveNumber("AGENT_REQUEST_TIMEOUT_MS", 5_000); } +export function getDiscordVerifyTimeoutMs(): number { + return getPositiveNumber("DISCORD_VERIFY_TIMEOUT_MS", 2_500); +} + export function getOnboardingSessionKeyPrefix(): string { return process.env["ONBOARDING_SESSION_KEY_PREFIX"]?.trim() || "lolympus"; } diff --git a/src/eval/golden/onboarding.jsonl b/src/eval/golden/onboarding.jsonl index 8faa5b5..368a86c 100644 --- a/src/eval/golden/onboarding.jsonl +++ b/src/eval/golden/onboarding.jsonl @@ -1,3 +1,3 @@ {"id":"greeting-short","name":"Greeting should stay short and welcoming","input":{"request":{"requestId":"eval_greeting_1","skill":"onboarding","chatroomId":"room_eval_1","userId":"user_eval_1","nickname":"","trigger":"user-message","userMessage":"안녕하세요"},"session":null,"conversationHistory":[]},"expected":{"intent":"greeting","responseMode":"llm","mustIncludeAny":["환영","반갑"],"mustNotInclude":["디스코드"]}} -{"id":"status-photo-remaining","name":"Status question should answer only the remaining step","input":{"request":{"requestId":"eval_status_1","skill":"onboarding","chatroomId":"room_eval_2","userId":"user_eval_2","nickname":"프리리/95/여/D","trigger":"user-message","userMessage":"이제 뭐 남았지"},"session":{"chatroomId":"room_eval_2","deadlineAt":"2099-01-01T00:00:00.000Z","joinedAt":"2026-04-16T00:00:00.000Z","lastEventAt":"2026-04-16T00:10:00.000Z","nickname":"프리리/95/여/D","nicknameVerified":true,"photoVerified":false,"status":"pending","userId":"user_eval_2"},"conversationHistory":[{"role":"user","content":"안녕하세요","timestamp":"2026-04-16T00:00:00.000Z"},{"role":"assistant","content":"환영합니다! 반갑습니다.","timestamp":"2026-04-16T00:00:01.000Z"}]},"expected":{"intent":"status-question","responseMode":"llm","mustIncludeAny":["남았","하트"],"mustNotInclude":["디스코드"]}} -{"id":"nickname-invalid-tier","name":"Nickname invalid flow should focus on nickname correction","input":{"request":{"requestId":"eval_nick_1","skill":"onboarding","chatroomId":"room_eval_3","userId":"user_eval_3","nickname":"프리리/95/여/다이아","trigger":"nickname-invalid"},"session":{"chatroomId":"room_eval_3","deadlineAt":"2099-01-01T00:00:00.000Z","joinedAt":"2026-04-16T00:00:00.000Z","lastEventAt":"2026-04-16T00:10:00.000Z","nickname":"프리리/95/여/다이아","nicknameVerified":false,"photoVerified":false,"status":"pending","userId":"user_eval_3"},"conversationHistory":[]},"expected":{"intent":"nickname-question","responseMode":"llm-with-tools","mustIncludeAny":["닉네임","티어","형식"],"mustNotInclude":["디스코드"]}} +{"id":"status-photo-remaining","name":"Status question should answer only the remaining step","input":{"request":{"requestId":"eval_status_1","skill":"onboarding","chatroomId":"room_eval_2","userId":"user_eval_2","nickname":"프리리/95/여/D","trigger":"user-message","userMessage":"이제 뭐 남았지"},"session":{"chatroomId":"room_eval_2","deadlineAt":"2099-01-01T00:00:00.000Z","joinedAt":"2026-04-16T00:00:00.000Z","kakaotalkNickname":"프리리/95/여/D","kakaotalkNicknameVerified":true,"lastEventAt":"2026-04-16T00:10:00.000Z","photoVerified":false,"status":"pending","userId":"user_eval_2"},"conversationHistory":[{"role":"user","content":"안녕하세요","timestamp":"2026-04-16T00:00:00.000Z"},{"role":"assistant","content":"환영합니다! 반갑습니다.","timestamp":"2026-04-16T00:00:01.000Z"}]},"expected":{"intent":"status-question","responseMode":"llm","mustIncludeAny":["남았","하트"],"mustNotInclude":["디스코드"]}} +{"id":"nickname-invalid-tier","name":"Nickname invalid flow should focus on nickname correction","input":{"request":{"requestId":"eval_nick_1","skill":"onboarding","chatroomId":"room_eval_3","userId":"user_eval_3","nickname":"프리리/95/여/다이아","trigger":"nickname-invalid"},"session":{"chatroomId":"room_eval_3","deadlineAt":"2099-01-01T00:00:00.000Z","joinedAt":"2026-04-16T00:00:00.000Z","kakaotalkNickname":"프리리/95/여/다이아","kakaotalkNicknameVerified":false,"lastEventAt":"2026-04-16T00:10:00.000Z","photoVerified":false,"status":"pending","userId":"user_eval_3"},"conversationHistory":[]},"expected":{"intent":"nickname-question","responseMode":"llm-with-tools","mustIncludeAny":["닉네임","티어","형식"],"mustNotInclude":["디스코드"]}} diff --git a/src/main.ts b/src/main.ts index 5db691e..2db2bdb 100644 --- a/src/main.ts +++ b/src/main.ts @@ -219,7 +219,13 @@ async function bootstrap(): Promise { // Register skills const shadowEvalBus = new ShadowEvalBus(garnetClient); - const onboardingSkill = new OnboardingSkill(garnetClient, llmClient, roomContextService, shadowEvalBus); + const onboardingSkill = new OnboardingSkill( + garnetClient, + llmClient, + roomContextService, + shadowEvalBus, + natsClient, + ); agent.registerSkill(onboardingSkill); installShutdownHooks(async () => { diff --git a/src/skills/onboarding/constants.ts b/src/skills/onboarding/constants.ts index 3481eaf..67ac68e 100644 --- a/src/skills/onboarding/constants.ts +++ b/src/skills/onboarding/constants.ts @@ -31,7 +31,7 @@ export const HEART_LOCATION_TEXT = '채팅방 오른쪽 상단 메뉴 버튼을 누르면 "커버 보기"가 보여요. 거기서 프로필과 하트를 확인하실 수 있어요.'; export const DISCORD_GUIDE_TEXT = - "닉네임 변경과 하트 인증을 모두 완료하신 뒤에 디스코드 서버에서 프로필을 설정하시면 권한이 자동으로 부여돼요."; + "카카오톡 닉네임 변경과 방 하트 인증을 마치신 뒤, 디스코드 본인인증방과 구인방에 입장하고 서버 프로필 닉네임과 프로필 메시지를 설정하시면 권한이 자동으로 부여돼요."; export const DISCORD_INVITE_URL = process.env["DISCORD_INVITE_URL"]?.trim() || ""; diff --git a/src/skills/onboarding/onboarding-templates.ts b/src/skills/onboarding/onboarding-templates.ts index dece511..7cd295d 100644 --- a/src/skills/onboarding/onboarding-templates.ts +++ b/src/skills/onboarding/onboarding-templates.ts @@ -1,4 +1,12 @@ import type { NicknameIssue, OnboardingSession } from "./types.js"; +import { + formatRemainingSteps, + getRemainingSteps, + hasExtendedOnboardingTracking, + isDiscordGuidanceUnlocked, + isOnboardingCompleted, + isStep1Completed, +} from "./state/progress.js"; import { HEART_LOCATION_TEXT, HEART_RULE_TEXT, @@ -100,17 +108,20 @@ export function analyzeNicknameIssues(nickname: string): NicknameIssue[] { export function getWelcomeMessage(nickname: string): string { return pickRandom([ - `${nickname}님 환영합니다! 새내기 등록은 닉네임 변경과 하트 인증 두 가지를 진행하시면 돼요.\n\n` + + `${nickname}님 환영합니다! 새내기 등록 1단계는 카카오톡 닉네임 변경과 하트 인증이에요.\n\n` + `1. 닉네임 변경: 이름/나이/성별/티어 형식 (예: 홍길동/25/남/G)\n` + - `2. 하트 인증: 채팅방 프로필 하트를 빨간색으로 만들고 원본 스크린샷 전송\n\n` + + `2. 하트 인증: 채팅방 프로필 하트를 빨간색으로 만들고 원본 스크린샷 전송\n` + + `3. 1단계 완료 후 디스코드 단계가 이어질 수 있어요.\n\n` + `궁금한 점 있으시면 편하게 물어봐 주세요!`, - `${nickname}님 반갑습니다! 톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요.\n\n` + + `${nickname}님 반갑습니다! 톡 게시글의 공지를 참고하셔서 먼저 카카오톡 닉네임 변경과 하트 인증을 진행해 주세요.\n\n` + `닉네임: 이름/나이/성별/티어 형식으로 변경 (예: 홍길동/25/남/G)\n` + - `하트 인증: 프로필 하트 빨간색 상태 원본 스크린샷 전송\n\n` + + `하트 인증: 프로필 하트 빨간색 상태 원본 스크린샷 전송\n` + + `이후에는 디스코드 단계가 이어질 수 있어요.\n\n` + `어떤 것부터 시작하시겠어요?`, `${nickname}님 롤림푸스에 오신 걸 환영해요! 등록 절차를 안내해 드릴게요.\n\n` + `닉네임을 이름/나이/성별/티어 형식(예: 홍길동/25/남/G)으로 바꿔주시고, ` + - `채팅방 프로필 하트를 빨간색으로 만든 원본 스크린샷을 보내주시면 됩니다. 순서는 상관없어요!`, + `채팅방 프로필 하트를 빨간색으로 만든 원본 스크린샷을 보내주시면 됩니다. ` + + `카카오톡 1단계가 끝나면 디스코드 단계가 이어질 수 있어요.`, ]); } @@ -194,28 +205,22 @@ export function getProgressMessage( ): string { const nicknameIcon = session.nicknameVerified ? "v" : "x"; const photoIcon = session.photoVerified ? "v" : "x"; - - let nextStep = ""; - if (!session.nicknameVerified && !session.photoVerified) { - nextStep = pickRandom([ - "\n\n톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요!", - "\n\n아직 두 가지 모두 남아있어요. 어떤 것부터 시작하시겠어요?", - ]); - } else if (!session.nicknameVerified) { - nextStep = pickRandom([ - "\n\n닉네임 변경만 완료하시면 돼요! 이름/나이/성별/티어 형식으로 변경해 주세요.", - "\n\n하트 인증은 완료됐어요! 닉네임만 변경해 주시면 끝이에요.", - ]); - } else if (!session.photoVerified) { - nextStep = pickRandom([ - "\n\n하트 인증만 남았어요! 프로필 하트를 빨간색으로 만든 스크린샷을 보내주세요.", - "\n\n닉네임은 완료됐어요! 하트 인증 스크린샷만 보내주시면 끝이에요.", - ]); - } + const discordNicknameIcon = + session.discordProfileNicknameVerified === true ? "v" : "x"; + const discordMessageIcon = + session.discordProfileMessageVerified === true ? "v" : "x"; + const remaining = getRemainingSteps(session); + const remainingText = + remaining.length > 0 + ? `\n\n이제 ${formatRemainingSteps(remaining)}만 남아 있어요.` + : "\n\n이제 새내기 등록 절차는 모두 완료됐어요."; + const extendedStatus = hasExtendedOnboardingTracking(session) + ? ` | 디스코드 닉네임 [${discordNicknameIcon}] | 디스코드 메시지 [${discordMessageIcon}]` + : ""; return ( - `${nickname}님 현재 진행상황: 닉네임 [${nicknameIcon}] | 하트인증 [${photoIcon}]` + - nextStep + `${nickname}님 현재 진행상황: 카카오톡 닉네임 [${nicknameIcon}] | 방 하트 인증 [${photoIcon}]${extendedStatus}` + + remainingText ); } @@ -237,10 +242,10 @@ export function getGenericHelpMessage( nickname: string, session: OnboardingSession | null, ): string { - if (!session || (!session.nicknameVerified && !session.photoVerified)) { + if (!session || !isStep1Completed(session)) { return pickRandom([ - `톡 게시글의 공지를 참고하셔서 닉네임 변경과 하트 인증을 진행해 주세요!`, - `닉네임 변경과 하트 인증 두 가지를 완료하시면 돼요. 톡 게시글의 공지를 확인해 주세요!`, + `톡 게시글의 공지를 참고하셔서 먼저 카카오톡 닉네임 변경과 하트 인증을 진행해 주세요!`, + `먼저 닉네임 변경과 하트 인증 두 가지를 완료하시면 돼요. 톡 게시글의 공지를 확인해 주세요!`, ]); } @@ -258,40 +263,51 @@ export function getGenericHelpMessage( ]); } - return `${nickname}님 두 절차가 모두 확인되면 디스코드 권한이 자동으로 부여돼요!`; + if (isOnboardingCompleted(session)) { + return `${nickname}님 모든 절차가 완료됐어요! 디스코드 권한이 자동으로 부여돼요!`; + } + + return `${nickname}님 카카오톡 절차는 완료됐고, 이제 ${formatRemainingSteps( + getRemainingSteps(session), + )}만 진행하시면 돼요!`; } export function getRemainingStatusMessage( session: OnboardingSession | null, ): string { - if (!session || (!session.nicknameVerified && !session.photoVerified)) { - return "이제 닉네임 변경과 방 하트 인증 두 가지가 남아 있어요."; + const remaining = getRemainingSteps(session); + + if (remaining.length === 0) { + return "이제 새내기 등록 절차는 모두 완료됐어요."; } - if (!session.nicknameVerified) { - return "이제 닉네임 변경만 남았어요."; - } - - if (!session.photoVerified) { - return "이제 방 하트 인증만 남았어요."; - } - - return "이제 새내기 등록 절차는 모두 완료됐어요."; + return `이제 ${formatRemainingSteps(remaining)}만 남아 있어요.`; } export function getDiscordMessage( nickname: string, session: OnboardingSession | null, ): string { - if (session?.nicknameVerified && session?.photoVerified) { + if (!isDiscordGuidanceUnlocked(session)) { return pickRandom([ - `${nickname}님 두 절차 모두 완료되셨어요! 디스코드 서버에 입장해서 서버 프로필을 설정해 주시면 봇이 자동으로 권한을 부여해 드려요.`, - `${nickname}님 닉네임과 하트 인증 모두 완료됐어요! 이제 디스코드 서버에 입장하신 후 서버 프로필을 설정하시면 권한이 자동 부여돼요.`, + `${nickname}님 카카오톡 닉네임 변경과 하트 인증을 먼저 완료해 주셔야 디스코드 안내를 드릴 수 있어요!`, + `${nickname}님 디스코드 단계는 카카오톡 닉네임 변경과 하트 인증을 모두 완료하신 뒤에 안내드릴게요!`, + ]); + } + + if (session && !isOnboardingCompleted(session)) { + return pickRandom([ + `${nickname}님 카카오톡 절차는 완료됐어요! 이제 ${formatRemainingSteps( + getRemainingSteps(session), + )}만 진행하시면 돼요.`, + `${nickname}님 이제 디스코드 단계만 남았어요. ${formatRemainingSteps( + getRemainingSteps(session), + )}을 확인해 주세요.`, ]); } return pickRandom([ - `${nickname}님 닉네임 변경과 하트 인증을 먼저 완료해 주셔야 디스코드 안내를 드릴 수 있어요!`, - `${nickname}님 디스코드 권한은 닉네임 변경과 하트 인증을 모두 완료하신 후에 안내드릴게요!`, + `${nickname}님 디스코드 단계까지 모두 완료되셨어요! 권한이 자동으로 부여될 거예요.`, + `${nickname}님 모든 새내기 등록 절차가 끝났어요! 디스코드 권한 반영만 잠시 기다려 주세요.`, ]); } diff --git a/src/skills/onboarding/prompts/builder.test.ts b/src/skills/onboarding/prompts/builder.test.ts index 2d70040..66d57a9 100644 --- a/src/skills/onboarding/prompts/builder.test.ts +++ b/src/skills/onboarding/prompts/builder.test.ts @@ -26,8 +26,10 @@ function makeSession( chatroomId: "room-1", deadlineAt: "2026-04-16T12:00:00.000Z", joinedAt: "2026-04-16T10:00:00.000Z", + kakaotalkNickname: "프리리/95/여/D", + kakaotalkNicknameAliases: [], + kakaotalkNicknameVerified: true, lastEventAt: "2026-04-16T10:30:00.000Z", - nickname: "프리리/95/여/D", nicknameVerified: true, photoVerified: false, status: "pending", @@ -68,6 +70,7 @@ describe("PromptBuilder", () => { expect(messages[0]?.role).toBe("system"); expect(messages[0]?.content).toContain("하트 인증이 뭐예요?"); expect(messages[0]?.content).not.toContain("나이 제한 있나요?"); + expect(messages[0]?.content).toContain("카카오톡 닉네임"); }); it("limits prompt history to the latest five turns when summary exists", () => { diff --git a/src/skills/onboarding/prompts/examples.ts b/src/skills/onboarding/prompts/examples.ts index 2573c39..e3d33ec 100644 --- a/src/skills/onboarding/prompts/examples.ts +++ b/src/skills/onboarding/prompts/examples.ts @@ -25,7 +25,7 @@ export const EXAMPLES_BY_INTENT: Record = { "status-question": [ { user: "이제 뭐 남았지?", - assistant: "이제 방 하트 인증만 남았어요.", + assistant: "이제 디스코드 프로필 닉네임 설정과 프로필 메시지 설정만 남아 있어요.", }, { user: "진행상황 알려줘", @@ -74,7 +74,19 @@ export const EXAMPLES_BY_INTENT: Record = { { user: "디스코드는 언제 들어가요?", assistant: - "닉네임 변경과 하트 인증을 모두 완료하신 뒤에 디스코드 안내를 받으실 수 있어요.", + "카카오톡 닉네임 변경과 하트 인증을 완료하셨다면, 이제 디스코드 방 입장과 프로필 설정을 진행하시면 돼요.", + }, + ], + "discord-verify-question": [ + { + user: "디코 닉변 확인해줘", + assistant: + "아직 디스코드 닉네임 변경은 확인되지 않았어요.", + }, + { + user: "디스코드 프로필 닉네임 설정 완료했어요", + assistant: + "디스코드 닉네임을 확인해봤는데 아직 올바른 형식으로 확인되지는 않았어요.", }, ], "age-question": [ diff --git a/src/skills/onboarding/prompts/layers.ts b/src/skills/onboarding/prompts/layers.ts index 23f896a..a0b3569 100644 --- a/src/skills/onboarding/prompts/layers.ts +++ b/src/skills/onboarding/prompts/layers.ts @@ -13,6 +13,12 @@ import { NICKNAME_FORMAT_EXAMPLE, TIER_CODES_TEXT, } from "../constants.js"; +import { + formatRemainingSteps, + getRemainingSteps, + hasExtendedOnboardingTracking, + isStep1Completed, +} from "../state/progress.js"; import { EXAMPLES_BY_INTENT } from "./examples.js"; function formatKstTimestamp(value: string | undefined): string { @@ -38,8 +44,8 @@ function formatNicknameStatus(session: OnboardingSession | null): string { } return session.nicknameVerified - ? `완료 (${session.nickname})` - : `미완료 (현재: ${session.nickname})`; + ? `완료 (${session.kakaotalkNickname})` + : `미완료 (현재: ${session.kakaotalkNickname})`; } function formatPhotoStatus(session: OnboardingSession | null): string { @@ -50,6 +56,14 @@ function formatPhotoStatus(session: OnboardingSession | null): string { return session.photoVerified ? "완료" : "미완료"; } +function formatOptionalVerificationStatus(value: boolean | undefined): string { + if (value === undefined) { + return "추적 안 함"; + } + + return value ? "완료" : "미완료"; +} + function formatHistory(history: ConversationMessage[]): string { if (history.length === 0) { return "(최근 대화 없음)"; @@ -101,11 +115,13 @@ export function personaLayer(): string { [커뮤니티 규칙] - 가입 가능 연령은 ${MIN_AGE}세 이상이야. -- 새내기 등록은 닉네임 변경과 방 하트 인증 두 가지를 모두 완료하면 돼. +- 새내기 등록 1단계는 카카오톡 닉네임 변경과 방 하트 인증이야. +- 1단계 완료 후에는 디스코드 본인인증방/구인방 입장과 서버 프로필 설정이 남아 있을 수 있어. - 닉네임 형식은 이름/출생 연도 두 자리/성별/티어야. 예: ${NICKNAME_FORMAT_EXAMPLE} - 성별은 남 또는 여, 티어 코드는 ${TIER_CODES_TEXT} 중 하나야. - 방 하트 인증은 ${HEART_RULE_TEXT} -- 디스코드 안내는 닉네임 변경과 하트 인증이 모두 완료된 뒤에만 해줘.`; +- 세션에 디스코드 관련 미완료 항목이 있으면 전체 등록은 아직 완료가 아니야. +- 디스코드 안내는 카카오톡 1단계가 완료된 뒤에만 해줘.`; } export function policyLayer( @@ -144,7 +160,13 @@ export function policyLayer( lines.push("- 하트 인증에 대해서만 답하고 다른 절차는 언급하지 마."); break; case "discord-question": - lines.push("- 디스코드 질문에만 답해. 완료 전이라면 먼저 온보딩 완료가 필요하다고만 알려줘."); + lines.push("- 디스코드 질문에만 답해. 카카오톡 1단계 전이라면 먼저 닉네임 변경과 하트 인증이 필요하다고 알려줘."); + break; + case "discord-verify-question": + lines.push("- 디스코드 닉네임 확인 결과만 답해."); + lines.push("- 확인되지 않았으면 확인되지 않았다고만 답하고, 추측해서 단정하지 마."); + lines.push("- 카카오톡 닉네임 형식이 틀리면 예시를 1개만 들고 형식에 맞게 변경해 달라고 안내해."); + lines.push("- 사용자가 묻지 않은 디스코드 절차나 다음 단계는 먼저 붙이지 마."); break; case "age-question": lines.push("- 나이 제한만 간단히 답해."); @@ -165,11 +187,20 @@ export function stateLayer( session: OnboardingSession | null, derived: DerivedState, ): string { + const remaining = getRemainingSteps(session); + return [ "[현재 유저 상태]", `- phase: ${derived.phase.kind}`, - `- nickname: ${formatNicknameStatus(session)}`, - `- photo: ${formatPhotoStatus(session)}`, + `- step1(카카오톡): ${session ? (isStep1Completed(session) ? "완료" : "미완료") : "미완료"}`, + `- 카카오톡 닉네임: ${formatNicknameStatus(session)}`, + `- 방 하트 인증: ${formatPhotoStatus(session)}`, + `- 디스코드 본인인증방 입장: ${formatOptionalVerificationStatus(session?.identityRoomJoined)}`, + `- 디스코드 구인방 입장: ${formatOptionalVerificationStatus(session?.recruitingRoomJoined)}`, + `- 디스코드 프로필 닉네임: ${formatOptionalVerificationStatus(session?.discordProfileNicknameVerified)}`, + `- 디스코드 프로필 메시지: ${formatOptionalVerificationStatus(session?.discordProfileMessageVerified)}`, + `- extendedTracking: ${hasExtendedOnboardingTracking(session) ? "on" : "off"}`, + `- remaining: ${remaining.length > 0 ? formatRemainingSteps(remaining) : "없음"}`, `- deadline(KST): ${formatKstTimestamp(session?.deadlineAt)}`, ].join("\n"); } diff --git a/src/skills/onboarding/prompts/tool-policy.ts b/src/skills/onboarding/prompts/tool-policy.ts index 442289d..d784b11 100644 --- a/src/skills/onboarding/prompts/tool-policy.ts +++ b/src/skills/onboarding/prompts/tool-policy.ts @@ -13,7 +13,14 @@ export function buildToolPolicy( } if (intent === "age-question" || intent === "discord-question") { - return "- 규칙 확인이 필요하면 lookup-community-rule 도구를 사용해 정확한 규칙만 답해."; + return [ + "- 디스코드 일반 안내나 규칙 질문이면 lookup-community-rule 도구를 사용해 정확한 규칙만 답해.", + "- 사용자가 디스코드 닉네임이나 프로필 설정을 끝냈다고 말하거나 반영 여부를 묻는다면 verify-discord-nickname 도구를 먼저 사용해 직접 확인해.", + ].join("\n"); + } + + if (intent === "discord-verify-question") { + return "- 디스코드 닉네임 확인 요청은 verify-discord-nickname 도구를 먼저 사용하고, 조회 결과만 짧게 답해."; } if (intent === "help-where") { diff --git a/src/skills/onboarding/runtime/orchestrator.ts b/src/skills/onboarding/runtime/orchestrator.ts index a9e7a36..ad8227a 100644 --- a/src/skills/onboarding/runtime/orchestrator.ts +++ b/src/skills/onboarding/runtime/orchestrator.ts @@ -1,4 +1,4 @@ -import { getContext } from "@obs/context"; +import { getContext, getRequestLogger } from "@obs/context"; import type { LlmClient } from "@llm/llm-client"; import type { ChatMessage } from "@llm/types"; import type { Tool, ToolContext } from "@tools/tool"; @@ -147,11 +147,11 @@ function buildPlannerMessages( approach: "answer-direct | ask-clarification | redirect-to-step | validate-then-explain | lookup-rule-then-answer | soft-decline", targetPhase: - "fresh | nickname-pending | photo-pending | both-pending | nickname-rejected | photo-rejected | deadline-near | completed | timed-out", + "fresh | nickname-pending | photo-pending | both-pending | step1-completed | nickname-rejected | photo-rejected | deadline-near | completed | timed-out", mustInclude: ["short strings"], mustAvoid: ["short strings"], suggestedTools: [ - "validate-nickname | check-onboarding-progress | lookup-community-rule | get-room-context", + "validate-nickname | check-onboarding-progress | lookup-community-rule | get-room-context | verify-discord-nickname", ], tone: "friendly | concise | encouraging | neutral | apologetic", targetLengthChars: 150, @@ -186,8 +186,9 @@ function buildResponderAddendum(plan: PlannerOutput): string { function pickToolsForPlan( plan: PlannerOutput, tools: readonly Tool[], + forceTools: boolean, ): readonly Tool[] { - if (plan.approach === "answer-direct" || plan.approach === "soft-decline") { + if (!forceTools && (plan.approach === "answer-direct" || plan.approach === "soft-decline")) { return []; } @@ -214,8 +215,19 @@ export class OnboardingOrchestrator { maxTokens: number, modelOverride: string, ): Promise { + const logger = getRequestLogger(); const deadlineMs = getRemainingDeadlineMs(); + logger.debug( + { + intent: derived.intent.kind, + responderTools: responderTools.map((tool) => tool.name), + role: "responder", + tier: derived.tier, + }, + "[OnboardingOrchestrator] Responder execution mode decided", + ); + if (responderTools.length > 0) { return runWithTools({ deadlineMs, @@ -247,6 +259,7 @@ export class OnboardingOrchestrator { derived: DerivedState, messages: ChatMessage[], ): Promise { + const logger = getRequestLogger(); const plannerMessages = buildPlannerMessages(derived, messages); const firstAttempt = await this.llmClient.chatCompletion(plannerMessages, { deadlineMs: getRemainingDeadlineMs(), @@ -262,6 +275,14 @@ export class OnboardingOrchestrator { ? tryParsePlannerOutput(firstAttempt.content) : null; if (firstPlan) { + logger.debug( + { + intent: derived.intent.kind, + plan: firstPlan, + source: "first-attempt", + }, + "[OnboardingOrchestrator] Planner output parsed", + ); return firstPlan; } @@ -285,7 +306,28 @@ export class OnboardingOrchestrator { }); const retryPlan = retry?.content ? tryParsePlannerOutput(retry.content) : null; - return retryPlan ?? getDefaultPlan(derived); + if (retryPlan) { + logger.debug( + { + intent: derived.intent.kind, + plan: retryPlan, + source: "retry", + }, + "[OnboardingOrchestrator] Planner output parsed", + ); + return retryPlan; + } + + const fallbackPlan = getDefaultPlan(derived); + logger.debug( + { + intent: derived.intent.kind, + plan: fallbackPlan, + source: "fallback", + }, + "[OnboardingOrchestrator] Planner fell back to default plan", + ); + return fallbackPlan; } private async runTier0( @@ -317,7 +359,8 @@ export class OnboardingOrchestrator { messages, buildResponderAddendum(plan), ); - const responderTools = pickToolsForPlan(plan, options.tools ?? []); + const forceTools = derived.responseMode === "llm-with-tools"; + const responderTools = pickToolsForPlan(plan, options.tools ?? [], forceTools); return this.runDirect( derived, @@ -339,7 +382,8 @@ export class OnboardingOrchestrator { messages, buildResponderAddendum(plan), ); - const responderTools = pickToolsForPlan(plan, options.tools ?? []); + const forceTools = derived.responseMode === "llm-with-tools"; + const responderTools = pickToolsForPlan(plan, options.tools ?? [], forceTools); const draft = await this.runDirect( derived, diff --git a/src/skills/onboarding/runtime/planner-schema.ts b/src/skills/onboarding/runtime/planner-schema.ts index 8718d02..810598f 100644 --- a/src/skills/onboarding/runtime/planner-schema.ts +++ b/src/skills/onboarding/runtime/planner-schema.ts @@ -14,6 +14,7 @@ export const PlannerTargetPhaseSchema = z.enum([ "nickname-pending", "photo-pending", "both-pending", + "step1-completed", "nickname-rejected", "photo-rejected", "deadline-near", @@ -26,6 +27,7 @@ export const PlannerSuggestedToolSchema = z.enum([ "check-onboarding-progress", "lookup-community-rule", "get-room-context", + "verify-discord-nickname", ]); export const PlannerToneSchema = z.enum([ diff --git a/src/skills/onboarding/runtime/tool-loop.ts b/src/skills/onboarding/runtime/tool-loop.ts index 7e6b414..d9b274a 100644 --- a/src/skills/onboarding/runtime/tool-loop.ts +++ b/src/skills/onboarding/runtime/tool-loop.ts @@ -1,4 +1,5 @@ import { withToolSpan } from "@obs/spans"; +import { getRequestLogger } from "@obs/context"; import type { LlmClient } from "@llm/llm-client"; import type { ChatCompletionOptions, ChatMessage } from "@llm/types"; import { parseToolCalls } from "@tools/parser"; @@ -22,6 +23,7 @@ export interface ToolLoopOptions { export async function runWithTools( options: ToolLoopOptions, ): Promise { + const logger = getRequestLogger(); const maxHops = options.maxHops ?? 2; const messages = options.messages.map((message) => ({ ...message })); let allowNativeTools = true; @@ -39,14 +41,44 @@ export async function runWithTools( }); if (!response) { + logger.debug( + { + hop, + role: options.role, + tier: options.tier, + }, + "[ToolLoop] LLM returned no response", + ); return null; } const toolCalls = parseToolCalls(response.message); if (toolCalls.length === 0) { + logger.debug( + { + content: response.content, + hop, + role: options.role, + tier: options.tier, + }, + "[ToolLoop] No tool call in model response", + ); return response.content; } + logger.debug( + { + hop, + role: options.role, + tier: options.tier, + toolCalls: toolCalls.map((call) => ({ + id: call.id, + name: call.name, + })), + }, + "[ToolLoop] Parsed tool calls", + ); + if (hop === maxHops) { messages.push(response.message); messages.push({ @@ -66,6 +98,15 @@ export async function runWithTools( throw new Error(`Tool not registered for call: ${call.name}`); } + logger.debug( + { + arguments: call.arguments, + callId: call.id, + tool: tool.name, + }, + "[ToolLoop] Executing tool call", + ); + const validated = tool.argsSchema.parse(call.arguments); const result = await withToolSpan( tool.name, @@ -76,6 +117,15 @@ export async function runWithTools( () => tool.execute(validated, options.toolContext), ); + logger.debug( + { + callId: call.id, + result, + tool: tool.name, + }, + "[ToolLoop] Tool call completed", + ); + messages.push({ role: "tool", name: tool.name, diff --git a/src/skills/onboarding/runtime/validator.test.ts b/src/skills/onboarding/runtime/validator.test.ts index 4a84278..ae6d651 100644 --- a/src/skills/onboarding/runtime/validator.test.ts +++ b/src/skills/onboarding/runtime/validator.test.ts @@ -19,7 +19,7 @@ function makeDerived( } describe("validateOnboardingResponse", () => { - it("rejects discord guidance before onboarding is completed", () => { + it("rejects discord guidance before step1 is completed", () => { const result = validateOnboardingResponse( "디스코드 서버에 들어가시면 돼요.", makeDerived(), @@ -29,6 +29,21 @@ describe("validateOnboardingResponse", () => { expect(result.reasons).toContain("stateConsistency"); }); + it("allows discord guidance after step1 is completed", () => { + const result = validateOnboardingResponse( + "이제 디스코드 프로필 닉네임과 프로필 메시지를 설정하시면 돼요.", + makeDerived({ + intent: { kind: "discord-question" }, + phase: { + kind: "step1-completed", + remaining: ["discord-profile-nickname", "discord-profile-message"], + }, + }), + ); + + expect(result.status).toBe("pass"); + }); + it("rejects invalid nickname examples", () => { const result = validateOnboardingResponse( "홍길동/95/남/Z로 바꾸시면 돼요.", diff --git a/src/skills/onboarding/runtime/validator.ts b/src/skills/onboarding/runtime/validator.ts index 19f86cc..ac766a4 100644 --- a/src/skills/onboarding/runtime/validator.ts +++ b/src/skills/onboarding/runtime/validator.ts @@ -96,6 +96,22 @@ function hasRepeatedPhrase(text: string): boolean { return [...phrases.values()].some((count) => count >= 3); } +function canAdvanceDiscordStep(derived: DerivedState): boolean { + if ( + derived.phase.kind === "completed" || + derived.phase.kind === "step1-completed" + ) { + return true; + } + + if (derived.phase.kind !== "deadline-near") { + return false; + } + + return !derived.phase.remaining.includes("nickname") && + !derived.phase.remaining.includes("photo"); +} + function markValidation(result: ValidationResult): ValidationResult { const activeSpan = trace.getActiveSpan(); activeSpan?.setAttributes({ @@ -137,7 +153,7 @@ export function validateOnboardingResponse( if ( mentionsDiscord && - derived.phase.kind !== "completed" && + !canAdvanceDiscordStep(derived) && advancesDiscordStep && !defersDiscordStep ) { diff --git a/src/skills/onboarding/session.ts b/src/skills/onboarding/session.ts new file mode 100644 index 0000000..a5af6a5 --- /dev/null +++ b/src/skills/onboarding/session.ts @@ -0,0 +1,210 @@ +import type { + OnboardingSession, + OnboardingStatus, + StoredOnboardingSession, +} from "./types.js"; + +export interface ParsedKakaoNickname { + baseName: string; + gender: string; + tier: string; + year: string; +} + +interface KakaoNicknameCarrier { + kakaotalkNickname?: string | undefined; + nickname?: string | undefined; +} + +function trimString(value: string | undefined): string | undefined { + const normalized = value?.trim(); + return normalized ? normalized : undefined; +} + +function optionalStringField( + key: K, + value: string | undefined, +): Partial> { + return value === undefined ? {} : ({ [key]: value } as Partial>); +} + +function optionalBooleanField( + key: K, + value: boolean | undefined, +): Partial> { + return value === undefined ? {} : ({ [key]: value } as Partial>); +} + +function isOnboardingStatus(value: string | undefined): value is OnboardingStatus { + return value === "pending" || value === "completed" || value === "timed_out"; +} + +function escapeForRegExp(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"); +} + +export function collectNicknameAliases( + ...sources: Array +): string[] { + const aliases: string[] = []; + const seen = new Set(); + + const pushAlias = (value: string | undefined): void => { + const normalized = trimString(value); + if (!normalized || seen.has(normalized)) { + return; + } + + seen.add(normalized); + aliases.push(normalized); + }; + + for (const source of sources) { + if (Array.isArray(source)) { + for (const value of source) { + pushAlias(value); + } + continue; + } + + if (typeof source === "string") { + pushAlias(source); + } + } + + return aliases; +} + +export function getKakaotalkNickname(session: KakaoNicknameCarrier): string { + return trimString(session.kakaotalkNickname) ?? trimString(session.nickname) ?? ""; +} + +export function parseKakaoNickname( + kakaotalkNickname: string, +): ParsedKakaoNickname | null { + const [baseName, year, gender, tier, ...rest] = kakaotalkNickname + .split("/") + .map((value) => value.trim()); + + if (rest.length > 0 || !baseName || !year || !gender || !tier) { + return null; + } + + return { + baseName, + gender, + tier, + year, + }; +} + +export function matchesDiscordNicknameRule( + guildNickname: string | undefined, + kakaotalkNickname: string, +): boolean { + const normalizedGuildNickname = trimString(guildNickname); + const parsed = parseKakaoNickname(kakaotalkNickname); + if (!normalizedGuildNickname || !parsed) { + return false; + } + + const pattern = new RegExp( + `^${escapeForRegExp(parsed.baseName)}#[^/]+/${escapeForRegExp(parsed.year)}/${escapeForRegExp(parsed.tier)}$`, + "u", + ); + return pattern.test(normalizedGuildNickname); +} + +export function normalizeOnboardingSession( + session: StoredOnboardingSession | null, +): OnboardingSession | null { + if (!session) { + return null; + } + + const chatroomId = trimString(session.chatroomId); + const deadlineAt = trimString(session.deadlineAt); + const joinedAt = trimString(session.joinedAt); + const lastEventAt = trimString(session.lastEventAt); + const userId = trimString(session.userId); + + if ( + !chatroomId || + !deadlineAt || + !joinedAt || + !lastEventAt || + !userId || + !isOnboardingStatus(session.status) + ) { + return null; + } + + const kakaotalkNickname = getKakaotalkNickname(session); + const kakaotalkNicknameAliases = collectNicknameAliases( + session.kakaotalkNicknameAliases, + session.nicknameAliases, + ); + const kakaotalkNicknameVerified = + session.kakaotalkNicknameVerified ?? session.nicknameVerified ?? false; + const kakaotalkNicknameVerifiedAt = + trimString(session.kakaotalkNicknameVerifiedAt) ?? + trimString(session.nicknameVerifiedAt); + const completedAt = trimString(session.completedAt); + const discordMemberId = trimString(session.discordMemberId); + const discordProfileMessageVerifiedAt = trimString( + session.discordProfileMessageVerifiedAt, + ); + const discordProfileNicknameVerifiedAt = trimString( + session.discordProfileNicknameVerifiedAt, + ); + const identityRoomJoinedAt = trimString(session.identityRoomJoinedAt); + const nicknameVerifiedAt = kakaotalkNicknameVerifiedAt; + const photoVerifiedAt = trimString(session.photoVerifiedAt); + const recruitingRoomJoinedAt = trimString(session.recruitingRoomJoinedAt); + const step1CompletedAt = trimString(session.step1CompletedAt); + const timedOutAt = trimString(session.timedOutAt); + + return { + chatroomId, + deadlineAt, + joinedAt, + kakaotalkNickname, + kakaotalkNicknameAliases, + kakaotalkNicknameVerified, + lastEventAt, + nicknameVerified: kakaotalkNicknameVerified, + photoVerified: session.photoVerified ?? false, + status: session.status, + userId, + ...optionalStringField("completedAt", completedAt), + ...optionalStringField("discordMemberId", discordMemberId), + ...optionalBooleanField( + "discordProfileMessageVerified", + session.discordProfileMessageVerified, + ), + ...optionalStringField( + "discordProfileMessageVerifiedAt", + discordProfileMessageVerifiedAt, + ), + ...optionalBooleanField( + "discordProfileNicknameVerified", + session.discordProfileNicknameVerified, + ), + ...optionalStringField( + "discordProfileNicknameVerifiedAt", + discordProfileNicknameVerifiedAt, + ), + ...optionalBooleanField("identityRoomJoined", session.identityRoomJoined), + ...optionalStringField("identityRoomJoinedAt", identityRoomJoinedAt), + ...optionalStringField( + "kakaotalkNicknameVerifiedAt", + kakaotalkNicknameVerifiedAt, + ), + ...optionalStringField("nicknameVerifiedAt", nicknameVerifiedAt), + ...optionalStringField("photoVerifiedAt", photoVerifiedAt), + ...optionalBooleanField("recruitingRoomJoined", session.recruitingRoomJoined), + ...optionalStringField("recruitingRoomJoinedAt", recruitingRoomJoinedAt), + ...optionalStringField("step1CompletedAt", step1CompletedAt), + ...optionalStringField("timedOutAt", timedOutAt), + }; +} diff --git a/src/skills/onboarding/skill.ts b/src/skills/onboarding/skill.ts index f86d848..8ef7b44 100644 --- a/src/skills/onboarding/skill.ts +++ b/src/skills/onboarding/skill.ts @@ -1,6 +1,7 @@ import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types"; import { getConversationSummaryKey } from "@conv/conversation-store"; import type { GarnetClient } from "@common/garnet"; +import type { NatsClient } from "@common/nats"; import { getContext, getRequestLogger } from "@obs/context"; import type { LlmClient } from "@llm/llm-client"; import type { ChatMessage } from "@llm/types"; @@ -36,7 +37,12 @@ import { OnboardingIntentClassifier } from "./state/classifier.js"; import type { DerivedState, Intent } from "./state/onboarding-state.js"; import { OnboardingOrchestrator } from "./runtime/orchestrator.js"; import { validateOnboardingResponse } from "./runtime/validator.js"; -import type { OnboardingSession, PromptContext } from "./types.js"; +import { normalizeOnboardingSession } from "./session.js"; +import type { + OnboardingSession, + PromptContext, + StoredOnboardingSession, +} from "./types.js"; type LlmTextResult = | { status: "success"; text: string } @@ -56,6 +62,7 @@ export class OnboardingSkill implements Skill { private readonly llmClient: LlmClient, private readonly roomContextService?: RoomContextService, shadowEvalPublisher?: ShadowEvalPublisher, + private readonly natsClient?: Pick, ) { this.classifier = new OnboardingIntentClassifier(llmClient); this.blackboardStore = new OnboardingBlackboardStore(garnetClient); @@ -124,6 +131,16 @@ export class OnboardingSkill implements Skill { } } + if (derived.intent.kind === "discord-verify-question") { + logger.debug( + { + responseSource: response.source, + responseText: response.text, + }, + "[OnboardingSkill] Final discord verification response", + ); + } + if (response.text.trim()) { await this.rememberTurn(request, derived).catch((error) => { logger.warn({ err: error }, "[OnboardingSkill] Failed to update blackboard"); @@ -148,7 +165,8 @@ export class OnboardingSkill implements Skill { ): Promise { const prefix = getOnboardingSessionKeyPrefix(); const key = `${prefix}:onboarding:${chatroomId}:${userId}`; - return this.garnetClient.getJson(key); + const rawSession = await this.garnetClient.getJson(key); + return normalizeOnboardingSession(rawSession); } private async handleLlm( @@ -260,7 +278,8 @@ export class OnboardingSkill implements Skill { derived.intent.kind === "help-where" || derived.intent.kind === "nickname-question" || derived.intent.kind === "photo-question" || - derived.intent.kind === "discord-question" + derived.intent.kind === "discord-question" || + derived.intent.kind === "discord-verify-question" ) ? [...current.openQuestions, userMessage].slice(-3) : current.openQuestions; @@ -400,6 +419,8 @@ export class OnboardingSkill implements Skill { return getGenericHelpMessage(nickname, session); case "discord-question": return getDiscordMessage(nickname, session); + case "discord-verify-question": + return getDiscordMessage(nickname, session); case "age-question": return getAgeRequirementMessage(); case "chitchat": @@ -514,6 +535,7 @@ export class OnboardingSkill implements Skill { ): ToolContext { return { chatroomId: request.chatroomId, + natsClient: this.natsClient, userId: request.userId, session, garnetClient: this.garnetClient, @@ -524,6 +546,12 @@ export class OnboardingSkill implements Skill { private selectToolsForDerived( derived: DerivedState, ): readonly Tool[] { + if (derived.intent.kind === "discord-verify-question") { + return this.tools.filter((tool) => + tool.name === "verify-discord-nickname", + ); + } + if (derived.phase.kind === "nickname-rejected") { return this.tools.filter((tool) => tool.name === "validate-nickname" || @@ -538,6 +566,13 @@ export class OnboardingSkill implements Skill { ); } + if (derived.intent.kind === "discord-question") { + return this.tools.filter((tool) => + tool.name === "lookup-community-rule" || + tool.name === "verify-discord-nickname", + ); + } + return this.tools; } diff --git a/src/skills/onboarding/state/classifier.test.ts b/src/skills/onboarding/state/classifier.test.ts index 6e16951..ce1cb38 100644 --- a/src/skills/onboarding/state/classifier.test.ts +++ b/src/skills/onboarding/state/classifier.test.ts @@ -33,4 +33,22 @@ describe("OnboardingIntentClassifier", () => { expect(result.intent.kind).toBe("nickname-question"); expect(result.source).toBe("regex"); }); + + it("classifies discord verification via regex", async () => { + const result = await classifier.classify( + "디코 닉변 확인해줘", + "user-message", + ); + expect(result.intent.kind).toBe("discord-verify-question"); + expect(result.source).toBe("regex"); + }); + + it("classifies discord nickname completion reports as verification", async () => { + const result = await classifier.classify( + "디스코드 프로필 닉네임 설정 완료했어요", + "user-message", + ); + expect(result.intent.kind).toBe("discord-verify-question"); + expect(result.source).toBe("regex"); + }); }); diff --git a/src/skills/onboarding/state/classifier.ts b/src/skills/onboarding/state/classifier.ts index b2c825e..cac9031 100644 --- a/src/skills/onboarding/state/classifier.ts +++ b/src/skills/onboarding/state/classifier.ts @@ -76,6 +76,24 @@ function classifyByRegex(userMessage: string): ClassifiedIntent { return { intent: intent("help-how"), confidence: 0.9, source: "regex" }; } + const mentionsDiscord = /(디스코드|디코|discord)/u.test(lower); + const asksDiscordVerification = + /(확인|조회|찾아|검색|검사|바뀌|변경|닉변|맞(?:아|나요)?|됐(?:나|나요)?|완료됐(?:나|나요)?)/u.test( + trimmed, + ); + const reportsDiscordNicknameCompletion = + /(닉네임|닉변|프로필\s*닉네임|서버\s*닉네임)/u.test(trimmed) && + /(완료했(?:어|어요|습니다)?|끝냈(?:어|어요|습니다)?|설정했(?:어|어요|습니다)?|바꿨(?:어|어요|습니다)?|변경했(?:어|어요|습니다)?|다\s*했(?:어|어요|습니다)?|해놨(?:어|어요|습니다)?|해뒀(?:어|어요|습니다)?|적용됐(?:어|어요|습니다)?)/u.test( + trimmed, + ); + if (mentionsDiscord && (asksDiscordVerification || reportsDiscordNicknameCompletion)) { + return { + intent: intent("discord-verify-question"), + confidence: 0.96, + source: "regex", + }; + } + if (/(디스코드|디코|discord)/u.test(lower)) { return { intent: intent("discord-question"), @@ -123,6 +141,7 @@ function parseIntent(raw: unknown): Intent { raw === "nickname-question" || raw === "photo-question" || raw === "discord-question" || + raw === "discord-verify-question" || raw === "age-question" || raw === "chitchat" || raw === "off-topic-to-other" @@ -147,7 +166,7 @@ async function classifyByLlm( { role: "system", content: - '다음 유저 메시지의 intent를 JSON으로만 분류해. {"intent":"..."} 형식만 출력하고, intent는 greeting, acknowledgement, status-question, help-how, help-where, nickname-question, photo-question, discord-question, age-question, chitchat, off-topic-to-other, unknown 중 하나만 사용해.', + '다음 유저 메시지의 intent를 JSON으로만 분류해. {"intent":"..."} 형식만 출력하고, intent는 greeting, acknowledgement, status-question, help-how, help-where, nickname-question, photo-question, discord-question, discord-verify-question, age-question, chitchat, off-topic-to-other, unknown 중 하나만 사용해.', }, { role: "user", diff --git a/src/skills/onboarding/state/derive.test.ts b/src/skills/onboarding/state/derive.test.ts index 4211954..ec13b26 100644 --- a/src/skills/onboarding/state/derive.test.ts +++ b/src/skills/onboarding/state/derive.test.ts @@ -11,8 +11,10 @@ function makeSession( chatroomId: "room-1", deadlineAt: new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString(), joinedAt: new Date().toISOString(), + kakaotalkNickname: "프리리/95/여/D", + kakaotalkNicknameAliases: [], + kakaotalkNicknameVerified: false, lastEventAt: new Date().toISOString(), - nickname: "프리리/95/여/D", nicknameVerified: false, photoVerified: false, status: "pending", @@ -58,4 +60,38 @@ describe("deriveState", () => { expect(derived.allowShortResponse).toBe(true); expect(derived.suggestedMaxTokens).toBe(96); }); + + it("uses tool mode for discord verification questions", () => { + const derived = deriveState( + makeSession(), + "user-message", + intent("discord-verify-question"), + ); + expect(derived.responseMode).toBe("llm-with-tools"); + expect(derived.tier).toBe(1); + }); + + it("does not mark completed when only step1 is done for extended sessions", () => { + const derived = deriveState( + makeSession({ + discordProfileMessageVerified: false, + discordProfileNicknameVerified: false, + identityRoomJoined: true, + nicknameVerified: true, + photoVerified: true, + recruitingRoomJoined: true, + step1CompletedAt: new Date().toISOString(), + }), + "user-message", + intent("status-question"), + ); + + expect(derived.phase.kind).toBe("step1-completed"); + if (derived.phase.kind === "step1-completed") { + expect(derived.phase.remaining).toEqual([ + "discord-profile-nickname", + "discord-profile-message", + ]); + } + }); }); diff --git a/src/skills/onboarding/state/derive.ts b/src/skills/onboarding/state/derive.ts index 6057e2d..1de5d12 100644 --- a/src/skills/onboarding/state/derive.ts +++ b/src/skills/onboarding/state/derive.ts @@ -27,6 +27,7 @@ function getSuggestedMaxTokens( intent.kind === "help-where" || intent.kind === "nickname-question" || intent.kind === "photo-question" || + intent.kind === "discord-verify-question" || trigger === "nickname-invalid" || trigger === "photo-failed" ) { @@ -76,6 +77,9 @@ export function deriveState( if (phase.kind === "nickname-rejected") { responseMode = "llm-with-tools"; tier = 1; + } else if (intent.kind === "discord-verify-question") { + responseMode = "llm-with-tools"; + tier = 1; } else if (phase.kind === "deadline-near") { responseMode = "llm"; tier = 1; diff --git a/src/skills/onboarding/state/intent-keywords.ts b/src/skills/onboarding/state/intent-keywords.ts index fb6945a..48a742f 100644 --- a/src/skills/onboarding/state/intent-keywords.ts +++ b/src/skills/onboarding/state/intent-keywords.ts @@ -4,7 +4,8 @@ export const EXPECTED_KEYWORDS: Record = { acknowledgement: ["네", "좋아요", "천천히"], "age-question": ["27", "가입", "가능"], chitchat: [], - "discord-question": ["디스코드", "권한", "완료"], + "discord-question": ["디스코드", "프로필", "권한", "설정"], + "discord-verify-question": ["디스코드", "확인", "닉네임"], greeting: ["반갑", "환영", "어서 오세요"], "help-how": ["하트", "닉네임", "스크린샷", "형식", "커버 보기"], "help-where": ["오른쪽 상단", "커버 보기", "프로필"], diff --git a/src/skills/onboarding/state/onboarding-state.ts b/src/skills/onboarding/state/onboarding-state.ts index 035a585..e15bc83 100644 --- a/src/skills/onboarding/state/onboarding-state.ts +++ b/src/skills/onboarding/state/onboarding-state.ts @@ -1,12 +1,19 @@ import type { NicknameIssue } from "../types.js"; -export type RemainingStep = "nickname" | "photo"; +export type RemainingStep = + | "nickname" + | "photo" + | "identity-room" + | "recruiting-room" + | "discord-profile-nickname" + | "discord-profile-message"; export type OnboardingPhase = | { kind: "fresh" } | { kind: "nickname-pending"; current: string } | { kind: "photo-pending" } | { kind: "both-pending" } + | { kind: "step1-completed"; remaining: RemainingStep[] } | { kind: "nickname-rejected"; current: string; issues: NicknameIssue[] } | { kind: "photo-rejected"; reason?: string | undefined } | { kind: "deadline-near"; remaining: RemainingStep[] } @@ -22,6 +29,7 @@ export type Intent = | { kind: "nickname-question" } | { kind: "photo-question" } | { kind: "discord-question" } + | { kind: "discord-verify-question" } | { kind: "age-question" } | { kind: "chitchat" } | { kind: "off-topic-to-other" } diff --git a/src/skills/onboarding/state/progress.ts b/src/skills/onboarding/state/progress.ts new file mode 100644 index 0000000..7ce229b --- /dev/null +++ b/src/skills/onboarding/state/progress.ts @@ -0,0 +1,173 @@ +import type { OnboardingSession } from '../types.js'; +import type { RemainingStep } from './onboarding-state.js'; + +const REMAINING_STEP_LABELS: Record = { + nickname: '카카오톡 닉네임 변경', + photo: '방 하트 인증', + 'identity-room': '디스코드 본인인증방 입장', + 'recruiting-room': '디스코드 구인방 입장', + 'discord-profile-nickname': '디스코드 프로필 닉네임 설정', + 'discord-profile-message': '디스코드 주민신청 채널에 메시지 남기기', +}; + +export function isStep1Completed(session: OnboardingSession | null): boolean { + return Boolean(session?.nicknameVerified && session?.photoVerified); +} + +export function hasExtendedOnboardingTracking(session: OnboardingSession | null): boolean { + if (!session) { + return false; + } + + return ( + session.step1CompletedAt !== undefined || + session.identityRoomJoined !== undefined || + session.identityRoomJoinedAt !== undefined || + session.recruitingRoomJoined !== undefined || + session.recruitingRoomJoinedAt !== undefined || + session.discordProfileNicknameVerified !== undefined || + session.discordProfileNicknameVerifiedAt !== undefined || + session.discordProfileMessageVerified !== undefined || + session.discordProfileMessageVerifiedAt !== undefined + ); +} + +function shouldTrackDiscordRooms(session: OnboardingSession | null): boolean { + if (!session) { + return false; + } + + return ( + session.identityRoomJoined !== undefined || + session.identityRoomJoinedAt !== undefined || + session.recruitingRoomJoined !== undefined || + session.recruitingRoomJoinedAt !== undefined + ); +} + +function shouldTrackDiscordProfile(session: OnboardingSession | null): boolean { + if (!session) { + return false; + } + + return ( + session.discordProfileNicknameVerified !== undefined || + session.discordProfileNicknameVerifiedAt !== undefined || + session.discordProfileMessageVerified !== undefined || + session.discordProfileMessageVerifiedAt !== undefined + ); +} + +function hasJoinedAllTrackedDiscordRooms(session: OnboardingSession | null): boolean { + if (!session) { + return false; + } + + if (!shouldTrackDiscordRooms(session)) { + return true; + } + + return session.identityRoomJoined !== false && session.recruitingRoomJoined !== false; +} + +export function getRemainingSteps(session: OnboardingSession | null): RemainingStep[] { + if (!session) { + return ['nickname', 'photo']; + } + + const remaining: RemainingStep[] = []; + + if (!session.nicknameVerified) { + remaining.push('nickname'); + } + + if (!session.photoVerified) { + remaining.push('photo'); + } + + if (remaining.length > 0) { + return remaining; + } + + if (!hasExtendedOnboardingTracking(session)) { + return []; + } + + if (shouldTrackDiscordRooms(session)) { + if (session.identityRoomJoined === false) { + remaining.push('identity-room'); + } + if (session.recruitingRoomJoined === false) { + remaining.push('recruiting-room'); + } + } + + if (!hasJoinedAllTrackedDiscordRooms(session)) { + return remaining; + } + + if (shouldTrackDiscordProfile(session)) { + if (session.discordProfileNicknameVerified === false) { + remaining.push('discord-profile-nickname'); + } + if (session.discordProfileMessageVerified === false) { + remaining.push('discord-profile-message'); + } + } + + return remaining; +} + +export function isOnboardingCompleted(session: OnboardingSession | null): boolean { + if (!session) { + return false; + } + + if (session.status === 'completed') { + return true; + } + + if (!isStep1Completed(session)) { + return false; + } + + if (!hasExtendedOnboardingTracking(session)) { + return true; + } + + return getRemainingSteps(session).length === 0; +} + +export function isDiscordGuidanceUnlocked(session: OnboardingSession | null): boolean { + return isStep1Completed(session); +} + +export function formatRemainingStep(step: RemainingStep): string { + return REMAINING_STEP_LABELS[step]; +} + +function appendKoreanAnd(left: string, right: string): string { + const lastChar = left.charCodeAt(left.length - 1); + const hasBatchim = lastChar >= 0xac00 && lastChar <= 0xd7a3 && (lastChar - 0xac00) % 28 !== 0; + + return `${left}${hasBatchim ? '과' : '와'} ${right}`; +} + +export function formatRemainingSteps(steps: RemainingStep[]): string { + const labels = steps.map(formatRemainingStep); + if (labels.length === 0) { + return ''; + } + + if (labels.length === 1) { + return labels[0] ?? ''; + } + + if (labels.length === 2) { + return appendKoreanAnd(labels[0] ?? '', labels[1] ?? ''); + } + + const head = labels.slice(0, -1).join(', '); + const tail = labels[labels.length - 1] ?? ''; + return appendKoreanAnd(head, tail); +} diff --git a/src/skills/onboarding/state/transitions.ts b/src/skills/onboarding/state/transitions.ts index 0566870..9343cb8 100644 --- a/src/skills/onboarding/state/transitions.ts +++ b/src/skills/onboarding/state/transitions.ts @@ -2,23 +2,11 @@ import { DEADLINE_NEAR_THRESHOLD_MIN } from "../constants.js"; import { analyzeNicknameIssues } from "../onboarding-templates.js"; import type { OnboardingSession } from "../types.js"; import type { OnboardingPhase, RemainingStep } from "./onboarding-state.js"; - -function getRemainingSteps( - session: OnboardingSession | null, -): RemainingStep[] { - if (!session) { - return ["nickname", "photo"]; - } - - const remaining: RemainingStep[] = []; - if (!session.nicknameVerified) { - remaining.push("nickname"); - } - if (!session.photoVerified) { - remaining.push("photo"); - } - return remaining; -} +import { + getRemainingSteps, + isOnboardingCompleted, + isStep1Completed, +} from "./progress.js"; function isDeadlineNear(session: OnboardingSession | null): boolean { if (!session?.deadlineAt) { @@ -45,15 +33,15 @@ export function derivePhaseFromSession( return { kind: "timed-out" }; } - if (session.status === "completed" || (session.nicknameVerified && session.photoVerified)) { + if (isOnboardingCompleted(session)) { return { kind: "completed" }; } if (trigger === "nickname-invalid") { return { kind: "nickname-rejected", - current: session.nickname, - issues: analyzeNicknameIssues(session.nickname), + current: session.kakaotalkNickname, + issues: analyzeNicknameIssues(session.kakaotalkNickname), }; } @@ -73,7 +61,7 @@ export function derivePhaseFromSession( if (!session.nicknameVerified) { return { kind: "nickname-pending", - current: session.nickname, + current: session.kakaotalkNickname, }; } @@ -81,5 +69,12 @@ export function derivePhaseFromSession( return { kind: "photo-pending" }; } + if (isStep1Completed(session) && remaining.length > 0) { + return { + kind: "step1-completed", + remaining, + }; + } + return { kind: "fresh" }; } diff --git a/src/skills/onboarding/types.ts b/src/skills/onboarding/types.ts index e1c2d44..cd92b42 100644 --- a/src/skills/onboarding/types.ts +++ b/src/skills/onboarding/types.ts @@ -47,14 +47,31 @@ export interface OnboardingSession { completedAt?: string; deadlineAt: string; discordMemberId?: string; + discordProfileMessageVerified?: boolean; + discordProfileMessageVerifiedAt?: string; + discordProfileNicknameVerified?: boolean; + discordProfileNicknameVerifiedAt?: string; + identityRoomJoined?: boolean; + identityRoomJoinedAt?: string; joinedAt: string; + kakaotalkNickname: string; + kakaotalkNicknameAliases: string[]; + kakaotalkNicknameVerified: boolean; + kakaotalkNicknameVerifiedAt?: string; lastEventAt: string; - nickname: string; nicknameVerified: boolean; nicknameVerifiedAt?: string; photoVerified: boolean; photoVerifiedAt?: string; + recruitingRoomJoined?: boolean; + recruitingRoomJoinedAt?: string; + step1CompletedAt?: string; status: OnboardingStatus; timedOutAt?: string; userId: string; } + +export type StoredOnboardingSession = Partial & { + nickname?: string; + nicknameAliases?: string[]; +}; diff --git a/src/tools/builtins/check-onboarding-progress.test.ts b/src/tools/builtins/check-onboarding-progress.test.ts new file mode 100644 index 0000000..dc53c76 --- /dev/null +++ b/src/tools/builtins/check-onboarding-progress.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from "vitest"; + +import { checkOnboardingProgressTool } from "./check-onboarding-progress.js"; +import type { OnboardingSession } from "@skills/onboarding/types"; + +function makeSession( + overrides?: Partial, +): OnboardingSession { + return { + chatroomId: "room-1", + deadlineAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), + joinedAt: "2026-04-21T16:57:27.244Z", + kakaotalkNickname: "날으는꼴뚜기/95/여/D", + kakaotalkNicknameAliases: ["날으는꼴뚜기/95/여/D"], + kakaotalkNicknameVerified: true, + lastEventAt: "2026-04-21T17:00:03.862Z", + nicknameVerified: true, + photoVerified: true, + status: "pending", + userId: "user-1", + ...overrides, + }; +} + +describe("checkOnboardingProgressTool", () => { + it("returns discord profile steps for extended sessions after step1", async () => { + const result = await checkOnboardingProgressTool.execute( + { + chatroomId: "room-1", + userId: "user-1", + }, + { + chatroomId: "room-1", + session: makeSession({ + discordProfileMessageVerified: false, + discordProfileNicknameVerified: false, + identityRoomJoined: true, + recruitingRoomJoined: true, + step1CompletedAt: "2026-04-21T16:57:44.767Z", + }), + userId: "user-1", + }, + ); + + expect(result.step1Done).toBe(true); + expect(result.overallDone).toBe(false); + expect(result.remainingSteps).toEqual([ + "discord-profile-nickname", + "discord-profile-message", + ]); + expect(result.remainingStepLabels).toEqual([ + "디스코드 프로필 닉네임 설정", + "디스코드 프로필 메시지 설정", + ]); + }); + + it("treats legacy sessions as completed when nickname and photo are done", async () => { + const result = await checkOnboardingProgressTool.execute( + { + chatroomId: "room-1", + userId: "user-1", + }, + { + chatroomId: "room-1", + session: makeSession(), + userId: "user-1", + }, + ); + + expect(result.step1Done).toBe(true); + expect(result.overallDone).toBe(true); + expect(result.remainingSteps).toEqual([]); + }); +}); diff --git a/src/tools/builtins/check-onboarding-progress.ts b/src/tools/builtins/check-onboarding-progress.ts index 0772a85..d704e3f 100644 --- a/src/tools/builtins/check-onboarding-progress.ts +++ b/src/tools/builtins/check-onboarding-progress.ts @@ -1,6 +1,16 @@ import { z } from "zod"; import { getOnboardingSessionKeyPrefix } from "../../config.js"; -import type { OnboardingSession } from "@skills/onboarding/types"; +import { normalizeOnboardingSession } from "@skills/onboarding/session"; +import { + formatRemainingStep, + getRemainingSteps, + isOnboardingCompleted, + isStep1Completed, +} from "@skills/onboarding/state/progress"; +import type { + OnboardingSession, + StoredOnboardingSession, +} from "@skills/onboarding/types"; import type { Tool } from "../tool.js"; const argsSchema = z.object({ @@ -11,32 +21,27 @@ const argsSchema = z.object({ const resultSchema = z.object({ nicknameDone: z.boolean(), photoDone: z.boolean(), - remainingSteps: z.array(z.enum(["nickname", "photo"])), + step1Done: z.boolean(), + overallDone: z.boolean(), + remainingStepLabels: z.array(z.string()), + remainingSteps: z.array(z.enum([ + "nickname", + "photo", + "identity-room", + "recruiting-room", + "discord-profile-nickname", + "discord-profile-message", + ])), deadlineInHours: z.number().nullable(), }); -function getRemainingSteps(session: OnboardingSession | null): Array<"nickname" | "photo"> { - if (!session) { - return ["nickname", "photo"]; - } - - const remaining: Array<"nickname" | "photo"> = []; - if (!session.nicknameVerified) { - remaining.push("nickname"); - } - if (!session.photoVerified) { - remaining.push("photo"); - } - return remaining; -} - export const checkOnboardingProgressTool: Tool< z.infer, z.infer > = { name: "check-onboarding-progress", description: - "현재 유저의 온보딩 진행 상태를 읽어 남은 절차와 데드라인까지 남은 시간을 구조화해서 반환한다.", + "현재 유저의 온보딩 진행 상태를 읽어 카카오톡 단계와 디스코드 단계를 포함한 남은 절차를 구조화해서 반환한다.", argsSchema, resultSchema, async execute(args, ctx) { @@ -44,8 +49,10 @@ export const checkOnboardingProgressTool: Tool< ctx.session && ctx.chatroomId === args.chatroomId && ctx.userId === args.userId ? ctx.session : ctx.garnetClient - ? await ctx.garnetClient.getJson( - `${getOnboardingSessionKeyPrefix()}:onboarding:${args.chatroomId}:${args.userId}`, + ? normalizeOnboardingSession( + await ctx.garnetClient.getJson( + `${getOnboardingSessionKeyPrefix()}:onboarding:${args.chatroomId}:${args.userId}`, + ), ) : null; @@ -57,6 +64,9 @@ export const checkOnboardingProgressTool: Tool< return { nicknameDone: session?.nicknameVerified ?? false, photoDone: session?.photoVerified ?? false, + step1Done: isStep1Completed(session), + overallDone: isOnboardingCompleted(session), + remainingStepLabels: getRemainingSteps(session).map(formatRemainingStep), remainingSteps: getRemainingSteps(session), deadlineInHours, }; diff --git a/src/tools/builtins/index.ts b/src/tools/builtins/index.ts index 7e40a78..3f0d00c 100644 --- a/src/tools/builtins/index.ts +++ b/src/tools/builtins/index.ts @@ -3,13 +3,15 @@ import { checkOnboardingProgressTool } from "./check-onboarding-progress.js"; import { getRoomContextTool } from "./get-room-context.js"; import { lookupCommunityRuleTool } from "./lookup-community-rule.js"; import { validateNicknameTool } from "./validate-nickname.js"; +import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js"; export function createBuiltInToolRegistry(): ToolRegistry { return new ToolRegistry() .register(validateNicknameTool) .register(checkOnboardingProgressTool) .register(lookupCommunityRuleTool) - .register(getRoomContextTool); + .register(getRoomContextTool) + .register(verifyDiscordNicknameTool); } export { @@ -17,4 +19,5 @@ export { getRoomContextTool, lookupCommunityRuleTool, validateNicknameTool, + verifyDiscordNicknameTool, }; diff --git a/src/tools/builtins/verify-discord-nickname.test.ts b/src/tools/builtins/verify-discord-nickname.test.ts new file mode 100644 index 0000000..481d4bf --- /dev/null +++ b/src/tools/builtins/verify-discord-nickname.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, it, vi } from "vitest"; + +import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js"; +import type { OnboardingSession } from "@skills/onboarding/types"; +import type { DiscordMemberLookupResponse } from "@common/nats-subjects"; + +function makeSession( + overrides?: Partial, +): OnboardingSession { + return { + chatroomId: "room-1", + deadlineAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), + joinedAt: "2026-04-17T00:00:00.000Z", + kakaotalkNickname: "프리리/95/여/E", + kakaotalkNicknameAliases: [], + kakaotalkNicknameVerified: true, + lastEventAt: new Date().toISOString(), + nicknameVerified: true, + photoVerified: false, + status: "pending", + userId: "user-1", + ...overrides, + }; +} + +describe("verifyDiscordNicknameTool", () => { + it("returns nickname format guidance when the session nickname is invalid", async () => { + const result = await verifyDiscordNicknameTool.execute( + {}, + { + session: makeSession({ + kakaotalkNickname: "프리리/95/여D", + }), + }, + ); + + expect(result.status).toBe("invalid-nickname-format"); + expect(result.formatExample).toBe("홍길동/95/남/G"); + expect(result.issueMessages?.length).toBeGreaterThan(0); + }); + + it("stores discordMemberId when a unique nickname match is found", async () => { + const setJson = vi.fn().mockResolvedValue(undefined); + const response: DiscordMemberLookupResponse = { + status: "ok", + nicknameMatches: [ + { + memberId: "discord-1", + joinedAt: "2026-04-17T00:10:00.000Z", + globalName: "프리리", + guildNickname: "프리리#KR1/95/E", + matchedBy: "global-name", + username: "priri", + }, + ], + joinedAfterMatches: [], + }; + const request = vi.fn( + async ( + _subject: string, + _payload: TRequest, + _options?: { timeoutMs?: number }, + ): Promise => response as TResponse, + ); + const session = makeSession(); + const result = await verifyDiscordNicknameTool.execute( + {}, + { + chatroomId: session.chatroomId, + garnetClient: { + setJson, + } as never, + natsClient: { + request: request as never, + }, + session, + userId: session.userId, + }, + ); + + expect(result.status).toBe("matched-renamed"); + expect(result.message).toContain("올바른 형식으로 설정되어 있어요"); + expect(result.discordMemberId).toBe("discord-1"); + expect(session.discordMemberId).toBe("discord-1"); + expect(request).toHaveBeenCalledTimes(1); + expect(setJson).toHaveBeenCalledTimes(1); + }); + + it("does not mark renamed when only the raw kakao nickname matches literally", async () => { + const response: DiscordMemberLookupResponse = { + status: "ok", + nicknameMatches: [ + { + memberId: "discord-1", + globalName: "프리리", + guildNickname: "프리리/95/여/E", + joinedAt: "2026-04-17T00:10:00.000Z", + matchedBy: "global-name", + username: "priri", + }, + ], + joinedAfterMatches: [], + }; + const request = vi.fn( + async ( + _subject: string, + _payload: TRequest, + _options?: { timeoutMs?: number }, + ): Promise => response as TResponse, + ); + + const result = await verifyDiscordNicknameTool.execute( + {}, + { + natsClient: { + request: request as never, + }, + session: makeSession(), + }, + ); + + expect(result.status).toBe("matched-pending-rename"); + expect(result.message).toContain("이름#태그/출생연도/티어"); + }); + + it("falls back to joined-after candidates and returns not-confirmed when ambiguous", async () => { + const response: DiscordMemberLookupResponse = { + status: "ok", + nicknameMatches: [], + joinedAfterMatches: [ + { + memberId: "discord-1", + joinedAt: "2026-04-17T00:10:00.000Z", + username: "user-a", + }, + { + memberId: "discord-2", + joinedAt: "2026-04-17T00:11:00.000Z", + username: "user-b", + }, + ], + }; + const request = vi.fn( + async ( + _subject: string, + _payload: TRequest, + _options?: { timeoutMs?: number }, + ): Promise => response as TResponse, + ); + + const result = await verifyDiscordNicknameTool.execute( + {}, + { + natsClient: { + request: request as never, + }, + session: makeSession(), + }, + ); + + expect(result.status).toBe("not-confirmed"); + expect(result.reason).toBe("joined-after-ambiguous"); + expect(result.joinedAfterMatchCount).toBe(2); + }); +}); diff --git a/src/tools/builtins/verify-discord-nickname.ts b/src/tools/builtins/verify-discord-nickname.ts new file mode 100644 index 0000000..cf6a947 --- /dev/null +++ b/src/tools/builtins/verify-discord-nickname.ts @@ -0,0 +1,366 @@ +import { z } from "zod"; +import { + getDiscordMemberLookupSubject, + getDiscordVerifyTimeoutMs, + getOnboardingSessionKeyPrefix, +} from "../../config.js"; +import type { + DiscordMemberCandidate, + DiscordMemberLookupRequest, + DiscordMemberLookupResponse, +} from "@common/nats-subjects"; +import { getContext, getRequestLogger } from "@obs/context"; +import { + NICKNAME_FORMAT_EXAMPLE, + NICKNAME_FORMAT_TEXT, +} from "@skills/onboarding/constants"; +import { analyzeNicknameIssues } from "@skills/onboarding/onboarding-templates"; +import { + getKakaotalkNickname, + matchesDiscordNicknameRule, + parseKakaoNickname, +} from "@skills/onboarding/session"; +import type { Tool, ToolContext } from "../tool.js"; + +const argsSchema = z.object({}).passthrough(); + +const resultSchema = z.object({ + status: z.enum([ + "invalid-nickname-format", + "lookup-unavailable", + "matched-pending-rename", + "matched-renamed", + "not-confirmed", + ]), + message: z.string(), + reason: z + .enum([ + "joined-after-ambiguous", + "joined-after-none", + "lookup-error", + "missing-search-name", + "missing-session", + "nickname-search-ambiguous", + "nickname-search-none", + "request-budget-exhausted", + ]) + .optional(), + expectedNickname: z.string().optional(), + searchName: z.string().optional(), + discordMemberId: z.string().optional(), + currentDisplayName: z.string().optional(), + formatExample: z.string().optional(), + guidance: z.string().optional(), + issueMessages: z.array(z.string()).optional(), + joinedAfterMatchCount: z.number().int().nonnegative().optional(), + matchSource: z.enum(["joined-after", "nickname"]).optional(), + matchedBy: z + .enum(["global-name", "guild-nickname", "joined-after", "username"]) + .optional(), + nicknameMatchCount: z.number().int().nonnegative().optional(), +}); + +function pickDisplayName(candidate: DiscordMemberCandidate): string { + return ( + candidate.guildNickname?.trim() || + candidate.globalName?.trim() || + candidate.username.trim() + ); +} + +function resolveTimeoutMs(): number | null { + const configured = getDiscordVerifyTimeoutMs(); + const deadlineAt = getContext()?.deadlineAt; + + if (!deadlineAt) { + return configured; + } + + const remainingMs = Date.parse(deadlineAt) - Date.now() - 100; + if (!Number.isFinite(remainingMs) || remainingMs <= 0) { + return null; + } + + return Math.min(configured, remainingMs); +} + +async function persistDiscordMemberId( + memberId: string, + ctx: ToolContext, +): Promise { + if (!ctx.garnetClient || !ctx.session) { + return; + } + + const nextSession = { + ...ctx.session, + discordMemberId: memberId, + }; + const key = `${getOnboardingSessionKeyPrefix()}:onboarding:${nextSession.chatroomId}:${nextSession.userId}`; + await ctx.garnetClient.setJson(key, nextSession); + ctx.session.discordMemberId = memberId; +} + +export const verifyDiscordNicknameTool: Tool< + z.infer, + z.infer +> = { + name: "verify-discord-nickname", + description: + "현재 유저의 카카오톡 인증 닉네임과 세션 입장 시각을 기준으로 디스코드 멤버를 찾아, 닉네임 변경이 확인됐는지 구조화해서 반환한다.", + argsSchema, + resultSchema, + async execute(_args, ctx) { + const logger = getRequestLogger(); + if (!ctx.session) { + logger.debug("[VerifyDiscordNickname] Missing session in tool context"); + return { + status: "lookup-unavailable" as const, + message: "세션 정보를 찾을 수 없어서 디스코드 닉네임을 조회할 수 없어요.", + reason: "missing-session" as const, + }; + } + + const expectedNickname = getKakaotalkNickname(ctx.session).trim(); + logger.debug( + { + expectedNickname, + joinedAt: ctx.session.joinedAt, + nicknameVerified: ctx.session.nicknameVerified, + photoVerified: ctx.session.photoVerified, + }, + "[VerifyDiscordNickname] Starting verification", + ); + const issues = analyzeNicknameIssues(expectedNickname); + if (issues.length > 0) { + logger.debug( + { + expectedNickname, + issueMessages: issues.map((issue) => issue.message), + }, + "[VerifyDiscordNickname] Nickname format invalid", + ); + return { + status: "invalid-nickname-format" as const, + message: `카카오톡 닉네임 형식이 올바르지 않아요. ${NICKNAME_FORMAT_TEXT}`, + expectedNickname, + formatExample: NICKNAME_FORMAT_EXAMPLE, + guidance: NICKNAME_FORMAT_TEXT, + issueMessages: issues.map((issue) => issue.message), + }; + } + + const parsedKakaoNickname = parseKakaoNickname(expectedNickname); + const searchName = parsedKakaoNickname?.baseName ?? ""; + if (!searchName) { + logger.debug( + { + expectedNickname, + }, + "[VerifyDiscordNickname] Failed to derive search name", + ); + return { + status: "lookup-unavailable" as const, + message: "닉네임에서 검색할 이름을 추출할 수 없어서 디스코드 조회가 불가능해요.", + reason: "missing-search-name" as const, + expectedNickname, + }; + } + + if (!ctx.natsClient) { + logger.debug( + { + expectedNickname, + searchName, + }, + "[VerifyDiscordNickname] Missing NATS client in tool context", + ); + return { + status: "lookup-unavailable" as const, + message: "지금은 디스코드 서버 조회가 불가능해요. 잠시 후 다시 시도해주세요.", + reason: "lookup-error" as const, + expectedNickname, + searchName, + }; + } + + const timeoutMs = resolveTimeoutMs(); + if (!timeoutMs) { + logger.debug( + { + expectedNickname, + searchName, + }, + "[VerifyDiscordNickname] No timeout budget left for lookup", + ); + return { + status: "lookup-unavailable" as const, + message: "응답 시간이 부족해서 디스코드 조회를 건너뛰었어요. 다시 물어봐 주세요.", + reason: "request-budget-exhausted" as const, + expectedNickname, + searchName, + }; + } + + let lookupResult: DiscordMemberLookupResponse; + try { + const payload: DiscordMemberLookupRequest = { + chatroomId: ctx.chatroomId ?? ctx.session.chatroomId, + joinedAfter: ctx.session.joinedAt, + searchName, + userId: ctx.userId ?? ctx.session.userId, + }; + + logger.debug( + { + payload, + subject: getDiscordMemberLookupSubject(), + timeoutMs, + }, + "[VerifyDiscordNickname] Sending lookup request", + ); + lookupResult = await ctx.natsClient.request< + DiscordMemberLookupRequest, + DiscordMemberLookupResponse + >(getDiscordMemberLookupSubject(), payload, { + timeoutMs, + }); + } catch { + logger.debug( + { + expectedNickname, + searchName, + }, + "[VerifyDiscordNickname] Lookup request failed", + ); + return { + status: "lookup-unavailable" as const, + message: "디스코드 서버 조회 중 오류가 발생했어요. 잠시 후 다시 시도해주세요.", + reason: "lookup-error" as const, + expectedNickname, + searchName, + }; + } + + if (lookupResult.status === "error") { + logger.debug( + { + expectedNickname, + reason: lookupResult.reason, + searchName, + }, + "[VerifyDiscordNickname] Lookup service returned error", + ); + return { + status: "lookup-unavailable" as const, + message: "디스코드 서버에서 오류가 반환됐어요. 잠시 후 다시 시도해주세요.", + reason: "lookup-error" as const, + expectedNickname, + searchName, + }; + } + + const nicknameMatches = lookupResult.nicknameMatches; + const joinedAfterMatches = lookupResult.joinedAfterMatches; + logger.debug( + { + expectedNickname, + joinedAfterMatches: joinedAfterMatches.length, + nicknameMatches: nicknameMatches.length, + searchName, + }, + "[VerifyDiscordNickname] Lookup response received", + ); + let candidate: DiscordMemberCandidate | null = null; + let matchSource: "joined-after" | "nickname" | undefined; + let reason: + | "joined-after-ambiguous" + | "joined-after-none" + | "nickname-search-ambiguous" + | "nickname-search-none" + | undefined; + + if (nicknameMatches.length === 1) { + candidate = nicknameMatches[0] ?? null; + matchSource = "nickname"; + } else if (nicknameMatches.length > 1) { + reason = "nickname-search-ambiguous"; + } else if (joinedAfterMatches.length === 1) { + candidate = joinedAfterMatches[0] ?? null; + matchSource = "joined-after"; + } else { + reason = + joinedAfterMatches.length === 0 + ? "joined-after-none" + : "joined-after-ambiguous"; + } + + if (!candidate) { + logger.debug( + { + expectedNickname, + joinedAfterMatchCount: joinedAfterMatches.length, + nicknameMatchCount: nicknameMatches.length, + reason: + reason ?? + (nicknameMatches.length === 0 + ? "nickname-search-none" + : "nickname-search-ambiguous"), + searchName, + }, + "[VerifyDiscordNickname] Verification not confirmed", + ); + return { + status: "not-confirmed" as const, + message: `디스코드 서버에서 "${searchName}" 닉네임을 찾을 수 없었어요. 디스코드 서버에 가입했는지, 닉네임이 올바른지 확인해주세요.`, + reason: + reason ?? + (nicknameMatches.length === 0 + ? "nickname-search-none" + : "nickname-search-ambiguous"), + expectedNickname, + searchName, + joinedAfterMatchCount: joinedAfterMatches.length, + nicknameMatchCount: nicknameMatches.length, + }; + } + + await persistDiscordMemberId(candidate.memberId, ctx); + + const currentDisplayName = pickDisplayName(candidate); + const currentGuildNickname = candidate.guildNickname?.trim(); + const isRenamed = matchesDiscordNicknameRule( + currentGuildNickname, + expectedNickname, + ); + const status = isRenamed ? "matched-renamed" : "matched-pending-rename"; + const message = isRenamed + ? "디스코드 서버 닉네임이 올바른 형식으로 설정되어 있어요. 확인 완료!" + : currentGuildNickname + ? `디스코드에서 유저를 찾았지만 서버 닉네임이 아직 올바른 형식으로 확인되지는 않았어요. 현재 서버 닉네임은 "${currentGuildNickname}"으로 보여요. 이름#태그/출생연도/티어 형식인지 확인해주세요.` + : `디스코드에서 유저를 찾았지만 서버 닉네임이 아직 설정되지 않았거나 확인되지 않았어요. 현재 표시 이름은 "${currentDisplayName}"으로 보여요. 서버 닉네임이 이름#태그/출생연도/티어 형식인지 확인해주세요.`; + + logger.debug( + { + currentDisplayName, + discordMemberId: candidate.memberId, + expectedNickname, + matchSource, + matchedBy: candidate.matchedBy, + status, + }, + "[VerifyDiscordNickname] Verification resolved", + ); + + return { + status, + message, + currentDisplayName, + discordMemberId: candidate.memberId, + expectedNickname, + matchSource, + matchedBy: candidate.matchedBy, + searchName, + }; + }, +}; diff --git a/src/tools/tool.ts b/src/tools/tool.ts index bfcbdf6..c011ee6 100644 --- a/src/tools/tool.ts +++ b/src/tools/tool.ts @@ -1,10 +1,12 @@ import type { GarnetClient } from "@common/garnet"; +import type { NatsClient } from "@common/nats"; import type { RoomContextService } from "@room/room-context-service"; import type { ZodType } from "zod"; import type { OnboardingSession } from "@skills/onboarding/types"; export interface ToolContext { chatroomId?: string | undefined; + natsClient?: Pick | undefined; userId?: string | undefined; session?: OnboardingSession | null | undefined; garnetClient?: GarnetClient | undefined;