프롬프트 변수 시스템 — instruction-variables 코드레벨 동작 흐름

마지막 업데이트 2026-07-22

네 가지 변수 문법

런타임 펼침 — replaceAllVariables

수업 진입 시 openai-create-call.ts가 지시문을 펼쳐 OpenAI Realtime call의 instruction으로 보낸다. lib/openai-create-call.ts:64-79:

const promptVars = await getPromptVariables();                        // DB #{}
const promptVarMap = Object.fromEntries(promptVars.map(v => [v.name, v.content]));
const presetVars = getPresetVariables(user, avatar, subAvatars);    // @{} 정체성
const userVars = activity.variables || {};                          // ${}
finalInstruction = replaceAllVariables(activity.instruction, promptVarMap, presetVars, userVars);

파싱 — parseInstructionVariables

instruction-variables.ts:25-67. 세 정규식을 각각 돌려 토큰을 수집하고 위치순 정렬한다.

const presetVarRegex = /@\{([^}]+)\}/g;   // type: "preset"
const userVarRegex   = /\$\{([^}]+)\}/g;  // type: "custom"
const promptVarRegex = /#\{([^}]+)\}/g;   // type: "prompt"
// 각 토큰: { type, name, fullMatch, startIndex, endIndex } → startIndex 기준 정렬

preset 이름은 normalizeVariableName으로 정규화돼 한글·영문 별칭이 모두 동작한다(@{아동명} == @{childName}).

★ 한국어 조사 자동 — getKoreanParticle

핵심 기능. 이름 끝 글자의 받침(종성) 유무로 조사를 고른다. instruction-variables.ts:69-91:

const lastCharCode = name[name.length - 1].charCodeAt(0);
// 한글 음절 영역(0xAC00~0xD7A3) 밖이면 기본값(야/랑)
const hasBatchim = (lastCharCode - 0xac00) % 28 !== 0;   // 받침 있음?
return particleType === "아"
  ? (hasBatchim ? "아" : "야")      // 현우+아, 지우+야
  : (hasBatchim ? "이랑" : "랑"); // 현우+이랑, 지우+랑

특수 변수(@{아동명아}·@{아동+는/이는}·@{핑퐁+야/이야} 등)는 buildSpecialVarMap이 프리셋 값으로 조합한다. 단, 의존 프리셋이 비어 있으면 만들지 않는다(:215-220) — 그 경우 토큰은 원문 그대로 남는다.

치환 메커니즘 — replaceInstructionVariables

• 커스텀 변수 먼저 전처리: userVars 값 안에 들어 있는 @{} 프리셋을 먼저 펼친 뒤(:260-284), instruction 본문을 치환. (중첩 한 단계 지원.)
• 끝→앞(역순) 치환: 토큰을 endIndex 큰 것부터 바꾼다(:290). 정방향으로 바꾸면 뒤 토큰의 startIndex가 어긋나기 때문.
• 미해결은 원문 유지: getReplacement는 프리셋/특수 맵에 값이 없거나 빈 문자열이면 fullMatch(원래 @{...})를 그대로 돌려준다(:226-244).

프롬프트 변수 CRUD (#{})

/api/prompt-variables — DynamoDB 전역 변수. app/main/prompt-variable 관리 페이지.

• GET withAuthMember, POST/수정/삭제 withAuthAdminOrDeveloper.
• 중복 이름 금지: 같은 name이 있으면 409 DUPLICATE_NAME.
• 중첩 금지: content에 #{}가 들어 있으면 400 NESTED_PROMPT_VARIABLE_NOT_ALLOWED(prompt-variables/route.ts:55) — 무한 펼침 방지.
• /[id]/usage: 이 변수를 참조하는 곳 추적.

하이라이팅 — highlightInstructionVariables

lib/instruction-highlight.ts. 편집기에서 변수 토큰을 색으로 구분(preset/custom/prompt/text). 유효하지 않은 프리셋 이름(getValidPresetVariableNames에 없음)은 일반 텍스트로 표시해, 오타를 변수처럼 강조하지 않는다.

코드 맵 — 파일별 역할

읽을 때 주의할 함정

관련 문서