refactor(instructions): share instruction template rendering via @d3ro/core

packages/core/src/instruction-template.ts

@@ -0,0 +1,117 @@
+// 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}`
+}