// packages/core/src/instruction-template.ts // 지시문(커스텀 명령) 템플릿 렌더링 정책 SSOT — 데스크톱·모바일·웹 공용 순수 함수. // // 규칙: // - `{{text}}`와 `{{userPrompt}}`는 **사용자 텍스트 자리(user slot)**를 표시한다. // 사용자 자리가 있는 지시문은 치환 결과 전체가 사용자 메시지가 되고, 시스템 프롬프트는 // 만들지 않는다. 사용자 텍스트(음성·화면 컨텍스트 포함)는 절대 시스템 프롬프트로 가지 않는다. // - 사용자 자리가 없으면 지시문은 시스템 프롬프트, 사용자 텍스트는 사용자 메시지다. // (시스템 프롬프트를 쓰지 못하는 전송 경로는 `renderInstructionAsSingleMessage`로 이어 붙인다.) // - 치환은 한 번의 패스 + 함수 replacer로 한다. 문자열 replacer는 `$&`, `$'`, `` $` ``, `$$` // 패턴을 해석해 사용자 텍스트를 훼손하고, 순차 치환은 사용자 텍스트에 들어 있는 // `{{userPrompt}}` 같은 문자열까지 다시 치환한다. // // 입력 검증(trim, 최대 길이)과 앱별 에러 타입, 로깅은 각 앱 래퍼의 책임이다. /** 사용자 텍스트 자리를 표시하는 플레이스홀더 (하위 호환 기본형). */ export const INSTRUCTION_TEXT_PLACEHOLDER = '{{text}}' /** 사용자 텍스트 자리를 표시하는 플레이스홀더 (자유 프롬프트 프리셋). */ export const INSTRUCTION_USER_PROMPT_PLACEHOLDER = '{{userPrompt}}' /** 번역 대상 언어 플레이스홀더. */ export const INSTRUCTION_TARGET_LANGUAGE_PLACEHOLDER = '{{targetLanguage}}' /** 대상 언어가 주어지지 않았을 때의 기본값. */ export const DEFAULT_INSTRUCTION_TARGET_LANGUAGE = 'English' /** 렌더러가 아는 플레이스홀더 이름. */ const KNOWN_PLACEHOLDERS = new Set(['text', 'userPrompt', 'targetLanguage']) /** 지시문 안의 `{{name}}` 탐지 (단일 패스 치환 + 남은 플레이스홀더 탐지 공용). */ const PLACEHOLDER_PATTERN = /\{\{([^{}]+)\}\}/g /** * 지시문이 사용자 텍스트 자리를 어떻게 지정했는지. * - `'text'`: `{{text}}` (둘 다 있으면 `{{text}}`가 우선) * - `'userPrompt'`: `{{userPrompt}}` — 사용자가 말한 내용 자체가 요청인 자유 프롬프트 * - `null`: 자리 지정 없음 — 지시문이 시스템 프롬프트가 된다 */ export type InstructionUserSlot = 'text' | 'userPrompt' | null export interface InstructionTemplateVars { /** 사용자 텍스트 (데스크톱은 화면 컨텍스트 프리픽스 포함). */ text: string /** 번역 대상 언어. 생략 시 {@link DEFAULT_INSTRUCTION_TARGET_LANGUAGE}. */ targetLanguage?: string } export interface RenderedInstruction { /** 시스템 프롬프트. 사용자 자리가 있는 지시문이면 `undefined`. */ system?: string /** 사용자 메시지. */ user: string /** 사용자 텍스트 자리 판정 결과. */ userSlot: InstructionUserSlot /** 지시문에 있었지만 치환하지 못한 플레이스홀더 이름 (중복 제거). */ unresolved: string[] } /** 지시문이 사용자 텍스트 자리를 지정했는지 판정한다. */ export function detectUserSlot(prompt: string): InstructionUserSlot { if (prompt.includes(INSTRUCTION_TEXT_PLACEHOLDER)) return 'text' if (prompt.includes(INSTRUCTION_USER_PROMPT_PLACEHOLDER)) return 'userPrompt' return null } /** 지시문 템플릿에서 렌더러가 모르는 플레이스홀더 이름을 모은다 (중복 제거, 등장 순서). */ export function findUnresolvedPlaceholders(prompt: string): string[] { const names: string[] = [] for (const match of prompt.matchAll(PLACEHOLDER_PATTERN)) { const name = match[1] if (!KNOWN_PLACEHOLDERS.has(name) && !names.includes(name)) names.push(name) } return names } /** * 지시문의 플레이스홀더를 한 번에 치환한다. * 알려지지 않은 플레이스홀더는 그대로 둔다. 치환값은 문자 그대로 들어간다. */ export function fillInstructionPlaceholders(prompt: string, vars: InstructionTemplateVars): string { const targetLanguage = vars.targetLanguage ?? DEFAULT_INSTRUCTION_TARGET_LANGUAGE return prompt.replace(PLACEHOLDER_PATTERN, (whole: string, name: string) => { if (name === 'text' || name === 'userPrompt') return vars.text if (name === 'targetLanguage') return targetLanguage return whole }) } /** * 지시문과 사용자 텍스트를 `{ system?, user }` 메시지 쌍으로 렌더링한다. * * - 사용자 자리(`{{text}}`/`{{userPrompt}}`)가 있으면: `user` = 치환된 지시문, `system` 없음. * - 없으면: `system` = 지시문(`{{targetLanguage}}`만 치환), `user` = 사용자 텍스트. */ export function renderInstruction(prompt: string, vars: InstructionTemplateVars): RenderedInstruction { const userSlot = detectUserSlot(prompt) const rendered = fillInstructionPlaceholders(prompt, vars) const unresolved = findUnresolvedPlaceholders(prompt) if (userSlot !== null) { return { user: rendered, userSlot, unresolved } } return { system: rendered, user: vars.text, userSlot, unresolved } } /** * 시스템 프롬프트를 따로 보낼 수 없는 전송 경로(단일 사용자 메시지)용. * 사용자 자리가 있으면 치환 결과를, 없으면 `지시문\n\n사용자 텍스트`를 돌려준다. */ export function renderInstructionAsSingleMessage( prompt: string, vars: InstructionTemplateVars, ): string { const { system, user } = renderInstruction(prompt, vars) return system === undefined ? user : `${system}\n\n${user}` }