@fcg-labs/cx-agent-hook 0.1.0

package/index.js

@@ -0,0 +1,150 @@
+/**
+ * @fcg-labs/cx-agent-hook — FCG CX Agent 후킹 SDK (공개 표면).
+ *
+ * 소비처(고객사 관리자 화면)가 닿는 것은 이 파일과 `./react` 뿐이다.
+ * 전송 계층(`CxAgentClient`)은 `client.js` 에 있고 **밖으로 내보내지 않는다** —
+ * 열어 두면 새 능력을 붙일 때 자연히 그리로 내려가고, 그 순간 `answer_id`
+ * 수명 관리 같은 제품 지식이 다시 고객사 코드로 흩어진다. 능력이 모자라면
+ * 저수준을 노출하는 게 아니라 **여기 표면을 채운다.**
+ *
+ *   ① 답변 제안 수신          requestAnswer
+ *   ② 상담사 판단 후킹         answerSent · scored · edited · discarded
+ *   ③ 문의·답변 쌍 적재        inquirySent   ★ 이게 빠지면 아무것도 안 쌓인다
+ *
+ * 원칙: 의존성 0 (내장 fetch), 어떤 메서드도 throw 하지 않는다.
+ */
+import { CxAgentClient } from "./client.js";
+import { LOCALES, MESSAGES, normalizeLocale, resolveMessages } from "./locales.js";
+
+export { LOCALES, MESSAGES, normalizeLocale };
+
+/** 사유 코드 → 상담사가 읽을 평문.
+ *
+ * 보통은 `hook.declineText` 를 쓴다 — setup 에서 정한 로케일이 이미 적용돼 있다.
+ * 이 함수는 훅 없이 문구만 필요할 때(테스트·미리보기)의 출구다.
+ */
+export function declineText(reason, locale) {
+  return textOf(resolveMessages(locale), reason);
+}
+
+/** 문구 한 벌에서 사유 하나 꺼내기. 기계 코드를 화면에 노출하지 않는다. */
+function textOf(messages, reason) {
+  const known = messages[reason];
+  if (known) return known;
+  if (String(reason || "").startsWith("http_")) return messages.http_error;
+  return messages.unknown;
+}
+
+const NOT_CONFIGURED = {
+  ok: false, answered: false, answer: "", answerId: null,
+  evidence: [], declinedReason: "not_configured", raw: {},
+};
+
+/** 후킹 한 벌을 만든다 — 미설정이면 전부 무동작.
+ *
+ * 소비하는 쪽이 써야 할 것은 **주소·토큰·도메인 세 값을 자기 빌드 방식으로 읽어
+ * 넘기는 일**뿐이다. 미설정 판정, 널 가드, 실패 시 돌려줄 모양, 사유 문구,
+ * 채택 식별자의 수명은 전부 여기에 있다.
+ */
+export function createCxHook(config = {}) {
+  const {
+    baseUrl, token, domain, api = "hub", onError,
+    // 화면 언어. 소비처가 이미 아는 값이라 setup 에서 한 번 넘기면 끝이고,
+    // 이후 문구는 전부 훅이 낸다 — 고객사가 사유별 문구를 알 필요가 없다.
+    locale, messages: messageOverrides,
+    ...rest
+  } = config;
+  const messages = resolveMessages(locale, messageOverrides);
+  const client =
+    baseUrl && token && domain
+      ? new CxAgentClient({
+          baseUrl, token, domain, api,
+          // 후킹 실패는 CS 업무와 무관 — 기록만 하고 화면을 막지 않는다.
+          onError:
+            onError ||
+            ((err, ctx) => console.warn("[cx-agent-hook]", ctx.op, err.message)),
+          ...rest,
+        })
+      : null;
+
+  // 상담사가 어느 제안을 에디터에 넣었는지. **이 기록이 gold 쌍의 유일한 근거다**
+  // — 발송된 최종 문구가 어느 answer_id 의 교정본인지 잇는 값이라, 여기가 비면
+  // 후킹은 일어나도 "AI 초안 → 사람 최종본" 델타가 성립하지 않는다.
+  // 고객사가 들고 다니게 하면 지우는 시점(문의 전환·발송 완료)까지 남의 코드에
+  // 흩어진다. 라이브러리가 소유한다.
+  let adoptedAnswerId = null;
+
+  /** 채택된 제안에 대한 교정 후킹. 채택이 없었으면 조용히 무동작.
+   *
+   * `consume` 이 true 면 보낸 뒤 기록을 비운다 — 발송·폐기는 그 제안에 대한
+   * 마지막 판단이라 두 번 세면 안 되고, 점수·수정은 발송 전에 여러 번 올 수 있다.
+   */
+  const emit = (send, consume) => {
+    const id = adoptedAnswerId;
+    if (consume) adoptedAnswerId = null;
+    if (!client || !id) return;
+    send(id);
+  };
+
+  return {
+    /** 세 값이 다 있으면 true */
+    enabled: Boolean(client),
+    /** setup 에서 정해진 화면 언어 (정규화된 값) */
+    locale: normalizeLocale(locale),
+    /** 이 훅의 문구 한 벌 — 패널이 UI 라벨까지 여기서 가져간다 */
+    messages,
+    /** 사유 코드 → 이 훅의 언어로 된 평문 */
+    declineText(reason) {
+      return textOf(messages, reason);
+    },
+
+    /** 답변 제안 요청 — throw 하지 않음 */
+    requestAnswer(inquiry) {
+      if (!client || !inquiry) return Promise.resolve(NOT_CONFIGURED);
+      return client.getAnswer(inquiry);
+    },
+
+    /** 제안을 에디터에 넣었다 (패널이 부른다) */
+    noteAdopted(answerId) {
+      adoptedAnswerId = answerId || null;
+    },
+    /** 채택 기록 폐기 — 다른 문의로 옮겼을 때 */
+    clearAdopted() {
+      adoptedAnswerId = null;
+    },
+    /** 지금 채택된 제안이 있나 (표시·검증용) */
+    get adoptedAnswerId() {
+      return adoptedAnswerId;
+    },
+
+    /** 답변 발송됨 — 채택본이었다면 gold 쌍으로 후킹 (fire-and-forget).
+     *
+     * 채택 없이 상담사가 직접 쓴 답변이면 아무 일도 안 한다. 한 번 보내면
+     * 기록을 비운다 — 같은 문의를 다시 발송해도 중복 교정이 쌓이지 않는다.
+     */
+    answerSent(finalText, agent) {
+      emit((id) => client.sent(id, finalText, agent), true);
+    },
+    /** 제안 품질 점수 1~5 (발송 전에 여러 번 올 수 있어 기록을 비우지 않는다) */
+    scored(score, agent) {
+      emit((id) => client.scored(id, score, agent), false);
+    },
+    /** 제안을 고쳐 썼다 — 초안↔최종본 델타 (발송 전 중간 저장 가능) */
+    edited(finalText, agent) {
+      emit((id) => client.edited(id, finalText, agent), false);
+    },
+    /** 제안을 버렸다 + 이유. 그 제안에 대한 마지막 판단이라 기록을 비운다. */
+    discarded(agent, note) {
+      emit((id) => client.discarded(id, agent, note), true);
+    },
+
+    /** 문의+상담사 최종답변 쌍 적재 (fire-and-forget, external_id 멱등).
+     *
+     * AI 제안을 안 써도 이것만 붙으면 광물이 쌓인다 — 인입의 유일한 통로.
+     */
+    inquirySent({ externalId, inquiry, reply, agent, meta } = {}) {
+      if (!client || !externalId || !inquiry) return;
+      client.logInquiry({ externalId, inquiry, reply, agent, meta });
+    },
+  };
+}

package/locales.d.ts

@@ -0,0 +1,9 @@
+export type Locale = "ko" | "en" | "ja" | "zh-TW";
+export declare const LOCALES: Locale[];
+export declare const DEFAULT_LOCALE: Locale;
+export declare const MESSAGES: Record<Locale, Record<string, string>>;
+export declare function normalizeLocale(locale: unknown): Locale;
+/** 로케일 문구 + 덮어쓴 값. 빠진 키는 기본 로케일로 메운다. */
+export declare function resolveMessages(
+  locale?: string, overrides?: Record<string, string>,
+): Record<string, string>;

package/locales.js

@@ -0,0 +1,136 @@
+/**
+ * 상담사에게 보이는 문구 — 로케일별 한 벌.
+ *
+ * **왜 라이브러리가 갖나.** 어떤 사유가 존재하고 각각이 무슨 뜻인지는 제품
+ * 지식이다. 고객사마다 따로 쓰면 같은 상태를 다르게 안내하게 되고, 서버가
+ * 사유를 하나 늘릴 때마다 고객사 저장소를 전부 고쳐야 한다.
+ *
+ * **왜 무거운 i18n 이 아닌가.** 문구가 20개 남짓이고 런타임에 언어를 바꿀 일이
+ * 없다(관리자 화면은 한 언어로 뜬다). 라이브러리를 하나 더 물리는 대신 평범한
+ * 객체로 둔다 — 소비처 번들에 얹히는 것도 이게 가장 작다.
+ *
+ * **모르는 로케일은 조용히 영어로 떨어진다.** 화면에 기계 코드가 나오는 것보다
+ * 낫고, 번역이 빠진 항목도 같은 규칙으로 메운다(`resolveMessages`).
+ *
+ * 사유 코드의 출처(전부 서버가 준다):
+ *   허브   answer_disabled(답변 미담당) · answer_unavailable(업스트림 장애)
+ *   공장   serving_disabled · gate_blocked · no_evidence · contract_violation
+ *   SDK    not_configured · unsupported_api · network_error
+ */
+
+/** 지원 로케일. 값은 BCP 47 접두와 맞춘다 (ko-KR → ko). */
+export const LOCALES = ["ko", "en", "ja", "zh-TW"];
+
+/** 폴백 기준 — 여기 있는 키가 전체 목록이다. */
+export const DEFAULT_LOCALE = "en";
+
+const en = {
+  // 패널 UI
+  ui_request: "Suggest a reply",
+  ui_requesting: "Generating…",
+  ui_adopt: "Insert into editor",
+  ui_evidence: "Sources",
+  // 거절·오류 사유
+  not_configured: "AI reply suggestions are not connected yet.",
+  unsupported_api: "AI reply suggestions are not connected yet.",
+  // 아직 안 켠 상태다. 장애가 아니므로 "다시 시도"라고 하지 않는다 —
+  // 몇 번을 눌러도 달라지지 않고, 기다릴 일도 아니다.
+  answer_disabled:
+    "AI reply suggestions are not enabled yet. Only inquiry collection is running.",
+  serving_disabled:
+    "AI reply suggestions are not enabled yet. Only inquiry collection is running.",
+  answer_unavailable: "Could not reach the reply service. Please try again shortly.",
+  network_error: "Could not reach the reply service. Please try again shortly.",
+  gate_blocked:
+    "Not enough approved manuals or sources yet, so no reply was suggested. This improves automatically as manuals are approved.",
+  no_evidence: "No sufficiently similar source was found for this inquiry.",
+  contract_violation: "The draft did not pass the quality checks, so it was held back.",
+  http_error: "The reply service could not process the request. Please try again shortly.",
+  unknown: "No reply could be suggested.",
+};
+
+const ko = {
+  ui_request: "AI 답변 제안",
+  ui_requesting: "제안 생성 중...",
+  ui_adopt: "에디터에 넣기",
+  ui_evidence: "근거",
+  not_configured: "AI 답변 제안이 아직 연결되지 않았습니다.",
+  unsupported_api: "AI 답변 제안이 아직 연결되지 않았습니다.",
+  answer_disabled: "AI 답변 제안은 아직 켜지지 않았습니다. 문의·답변 수집만 진행 중입니다.",
+  serving_disabled: "AI 답변 제안은 아직 켜지지 않았습니다. 문의·답변 수집만 진행 중입니다.",
+  answer_unavailable: "응답 서버에 연결하지 못했습니다. 잠시 후 다시 시도해 주세요.",
+  network_error: "응답 서버에 연결하지 못했습니다. 잠시 후 다시 시도해 주세요.",
+  gate_blocked:
+    "아직 승인된 매뉴얼·자료 출처가 부족해서 답변을 제안하지 못했습니다. 매뉴얼 승인이 쌓이면 자동으로 좋아집니다.",
+  no_evidence: "이 문의와 충분히 비슷한 근거를 찾지 못했습니다.",
+  contract_violation: "제안 문구가 품질 기준을 통과하지 못해 보류했습니다.",
+  http_error: "응답 서버가 요청을 처리하지 못했습니다. 잠시 후 다시 시도해 주세요.",
+  unknown: "답변을 제안하지 못했습니다.",
+};
+
+const ja = {
+  ui_request: "AI 返信案",
+  ui_requesting: "生成中...",
+  ui_adopt: "エディタに挿入",
+  ui_evidence: "根拠",
+  not_configured: "AI 返信案はまだ接続されていません。",
+  unsupported_api: "AI 返信案はまだ接続されていません。",
+  answer_disabled: "AI 返信案はまだ有効になっていません。問い合わせの収集のみ実行中です。",
+  serving_disabled: "AI 返信案はまだ有効になっていません。問い合わせの収集のみ実行中です。",
+  answer_unavailable: "応答サーバーに接続できませんでした。しばらくしてからもう一度お試しください。",
+  network_error: "応答サーバーに接続できませんでした。しばらくしてからもう一度お試しください。",
+  gate_blocked:
+    "承認済みのマニュアル・資料がまだ足りないため、返信案を作成できませんでした。マニュアルの承認が増えると自動的に改善します。",
+  no_evidence: "この問い合わせに十分に近い根拠が見つかりませんでした。",
+  contract_violation: "返信案が品質基準を満たさなかったため保留しました。",
+  http_error: "応答サーバーがリクエストを処理できませんでした。しばらくしてからもう一度お試しください。",
+  unknown: "返信案を作成できませんでした。",
+};
+
+const zhTW = {
+  ui_request: "AI 回覆建議",
+  ui_requesting: "產生中...",
+  ui_adopt: "插入編輯器",
+  ui_evidence: "依據",
+  not_configured: "AI 回覆建議尚未連接。",
+  unsupported_api: "AI 回覆建議尚未連接。",
+  answer_disabled: "AI 回覆建議尚未啟用，目前僅進行問題收集。",
+  serving_disabled: "AI 回覆建議尚未啟用，目前僅進行問題收集。",
+  answer_unavailable: "無法連接回覆伺服器，請稍後再試。",
+  network_error: "無法連接回覆伺服器，請稍後再試。",
+  gate_blocked:
+    "已核准的手冊或資料來源尚不足，因此未提供回覆建議。隨著手冊核准累積會自動改善。",
+  no_evidence: "找不到與此問題足夠相似的依據。",
+  contract_violation: "建議內容未通過品質標準，已暫緩提供。",
+  http_error: "回覆伺服器無法處理此請求，請稍後再試。",
+  unknown: "無法提供回覆建議。",
+};
+
+export const MESSAGES = { en, ko, ja, "zh-TW": zhTW };
+
+/** "ko-KR" · "KO" · "zh_TW" 같은 표기를 지원 로케일로 정규화. 모르면 기본값. */
+export function normalizeLocale(locale) {
+  const raw = String(locale || "").trim().replace("_", "-");
+  if (!raw) return DEFAULT_LOCALE;
+  const lower = raw.toLowerCase();
+  for (const known of LOCALES) {
+    if (known.toLowerCase() === lower) return known;
+  }
+  // 지역 없는 표기로 재시도 (ko-KR → ko). 중국어는 번체/간체가 갈리므로
+  // 언어만으로 zh-TW 에 붙이지 않는다 — 간체 사용자에게 번체를 보이면 안 된다.
+  const lang = lower.split("-")[0];
+  for (const known of LOCALES) {
+    if (known.toLowerCase() === lang) return known;
+  }
+  return DEFAULT_LOCALE;
+}
+
+/** 로케일 문구 한 벌 + 소비처가 덮어쓴 값.
+ *
+ * 빠진 키는 기본 로케일로 메운다 — 번역이 늦은 항목이 화면에서 `undefined` 로
+ * 새는 것을 막는다.
+ */
+export function resolveMessages(locale, overrides) {
+  const base = MESSAGES[normalizeLocale(locale)] || MESSAGES[DEFAULT_LOCALE];
+  return { ...MESSAGES[DEFAULT_LOCALE], ...base, ...(overrides || {}) };
+}

package/next.d.ts

@@ -0,0 +1,3 @@
+/** Next.js (App Router) 진입점 — react 와 같되 "use client" 경계를 선언한다. */
+export { AiSuggestPanel, aiSuggestView, default } from "./react.js";
+export type { AiSuggestPanelProps, AiSuggestView } from "./react.js";

package/next.js

@@ -0,0 +1,20 @@
+"use client";
+
+/**
+ * AI 답변 제안 패널 — Next.js (App Router).
+ *
+ * ```jsx
+ * import { AiSuggestPanel } from "@fcg-labs/cx-agent-hook/next";
+ * import "@fcg-labs/cx-agent-hook/styles.css";
+ * ```
+ *
+ * **왜 별도 진입점인가.** App Router 는 기본이 서버 컴포넌트라 `useState`·
+ * `useEffect` 를 쓰는 이 패널이 그대로는 못 뜬다. 소비처가 자기 파일마다
+ * `"use client"` 를 적게 하는 대신, 경계를 **라이브러리가 선언**한다 —
+ * 그 지시자를 어디에 둬야 하는지도 제품 지식이고, 빠뜨리면 빌드가 아니라
+ * 런타임에서 깨진다.
+ *
+ * Pages Router 나 순수 React 라면 `@fcg-labs/cx-agent-hook/react` 와 같다.
+ * 지시자는 그쪽에서 무시되므로 이 진입점을 써도 문제는 없다.
+ */
+export { AiSuggestPanel, aiSuggestView, default } from "./react.js";

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@fcg-labs/cx-agent-hook",
+  "version": "0.1.0",
+  "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./react.js"
+    },
+    "./next": {
+      "types": "./next.d.ts",
+      "import": "./next.js"
+    },
+    "./vue": {
+      "types": "./vue.d.ts",
+      "import": "./vue.js"
+    },
+    "./astro": {
+      "types": "./astro.d.ts",
+      "import": "./astro.js"
+    },
+    "./angular": {
+      "types": "./angular.d.ts",
+      "import": "./angular.js"
+    },
+    "./element": {
+      "types": "./element.d.ts",
+      "import": "./element.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "//exports": "client.js(전송 계층)는 의도적으로 맵에 없다 — 소비처가 저수준으로 내려가면 answer_id 수명 관리 같은 제품 지식이 고객사 코드로 흩어진다. 능력이 모자라면 createCxHook 표면을 채운다.",
+  "//peerDependencies": "react 는 './react' 서브패스에서만 필요하다. 본체(전송 계층)는 여전히 의존성 0 이고, React 를 안 쓰는 소비처는 './react' 를 import 하지 않으면 그만이다 (optional).",
+  "peerDependencies": {
+    "react": ">=16.8",
+    "vue": ">=3.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "client.js",
+    "client.d.ts",
+    "view.js",
+    "view.d.ts",
+    "locales.js",
+    "locales.d.ts",
+    "react.js",
+    "react.d.ts",
+    "next.js",
+    "next.d.ts",
+    "vue.js",
+    "vue.d.ts",
+    "astro.js",
+    "astro.d.ts",
+    "angular.js",
+    "angular.d.ts",
+    "element.js",
+    "element.d.ts",
+    "styles.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node scripts/prepublish-guard.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "FCG (FCG-labs)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FCG-labs/FCG-CX-Agent.git",
+    "directory": "sdk/cx-agent-hook"
+  },
+  "//frameworks": "astro·angular 는 표준 커스텀 엘리먼트(./element)를 쓴다. 프레임워크별 컴포넌트를 따로 짜면 메이저 버전마다 우리가 따라다니게 되고, 빌드 단계 없음(의존성 0) 성질도 깨진다.",
+  "devDependencies": {
+    "@vue/server-renderer": "^3.5.40",
+    "happy-dom": "^20.11.1",
+    "vue": "^3.5.40"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//name": "스코프는 @fcg-labs — org 소유이고 @fcg-labs/tlm 과 같은 자리다. @fcg 는 우리 것이 아니다(발행 불가)."
+}

package/react.d.ts

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import type { AnswerResult, CxHook } from "./index.js";
+
+export { aiSuggestView } from "./view.js";
+export type { AiSuggestView } from "./view.js";
+
+export interface AiSuggestPanelProps {
+  hook: CxHook;
+  inquiry: string | undefined | null;
+  onAdopt?: (text: string) => void;
+  /** 바깥 배치용 (레이아웃만 — 색·간격은 styles.css 변수로) */
+  className?: string;
+}
+
+/** AI 답변 제안 패널. hook 이 미설정이면 아무것도 그리지 않는다. */
+export declare function AiSuggestPanel(props: AiSuggestPanelProps): ReactElement | null;
+
+export default AiSuggestPanel;

package/react.js

@@ -0,0 +1,110 @@
+/**
+ * AI 답변 제안 패널 — 상담사 화면에 그대로 꽂는 제품 UI.
+ *
+ * 왜 라이브러리에 있나: 이 패널의 상태 전이(누름→생성중→결과), 거절 사유 안내,
+ * 근거 표기, 채택 시 answer_id 를 발송 후킹에 잇는 규약은 **전부 제품 지식**이다.
+ * 고객사 화면에 손으로 짜 두면 2호 고객이 올 때 또 짜야 하고, 규약이 바뀌면
+ * 고객사마다 따로 고쳐야 한다.
+ *
+ * ```jsx
+ * import { AiSuggestPanel } from "@fcg-labs/cx-agent-hook/react";
+ * import "@fcg-labs/cx-agent-hook/styles.css";
+ *
+ * <AiSuggestPanel hook={cxHook} inquiry={selected?.content} onAdopt={setAnswerText} />
+ * ```
+ *
+ * React 는 peer 다 (>=16.8). 여기서는 JSX 를 쓰지 않는다 — 이 패키지는 빌드
+ * 단계가 없고(의존성 0 이 설계 성질), JSX 를 그대로 배포하면 소비처 번들러가
+ * node_modules 를 변환해 주기를 기대해야 한다. createElement 로 직접 쓴다.
+ */
+import { createElement as h, useCallback, useEffect, useState } from "react";
+
+import { aiSuggestView, CLS } from "./view.js";
+
+// 표시 판단은 프레임워크 중립 코어가 갖는다 — Vue·웹 컴포넌트와 같은 것을 쓴다.
+export { aiSuggestView };
+
+/**
+ * @param {object}   props
+ * @param {object}   props.hook      createCxHook() 결과
+ * @param {string}   props.inquiry   대상 문의 원문
+ * @param {(text: string) => void} props.onAdopt  "에디터에 넣기"
+ * @param {string}  [props.className] 바깥 배치용 (레이아웃만)
+ */
+export function AiSuggestPanel({ hook, inquiry, onAdopt, className }) {
+  const [state, setState] = useState("idle");
+  const [result, setResult] = useState(null);
+
+  // 다른 문의로 옮기면 앞 문의의 제안이 남아 있으면 안 된다. 채택 기록도 같이
+  // 지운다 — 안 지우면 다음 문의를 발송할 때 엉뚱한 answer_id 로 후킹된다.
+  useEffect(() => {
+    setState("idle");
+    setResult(null);
+    hook.clearAdopted();
+  }, [inquiry, hook]);
+
+  const request = useCallback(async () => {
+    if (!inquiry || state === "loading") return;
+    setState("loading");
+    setResult(await hook.requestAnswer(inquiry));
+    setState("done");
+  }, [hook, inquiry, state]);
+
+  const adopt = useCallback(() => {
+    if (!result || !result.answered) return;
+    hook.noteAdopted(result.answerId);
+    if (onAdopt) onAdopt(result.answer);
+  }, [hook, onAdopt, result]);
+
+  if (!hook || !hook.enabled) return null;
+
+  const view = aiSuggestView({
+    state, result, declineText: hook.declineText, messages: hook.messages,
+  });
+
+  return h(
+    "div",
+    {
+      className: className ? `${CLS.root} ${className}` : CLS.root,
+      // 이 패널은 보통 "클릭하면 선택되는" 문의 행 안에 놓인다. 버튼을 누르려다
+      // 행 선택이 토글되면 제안이 초기화된다.
+      onClick: (event) => event.stopPropagation(),
+    },
+    h(
+      "div",
+      { className: CLS.head },
+      h(
+        "button",
+        {
+          type: "button",
+          className: CLS.button,
+          disabled: view.buttonDisabled,
+          onClick: request,
+        },
+        view.buttonLabel,
+      ),
+      view.showAdopt &&
+        h(
+          "button",
+          { type: "button", className: CLS.adopt, onClick: adopt },
+          view.adoptLabel,
+        ),
+    ),
+    view.body.kind === "answer" &&
+      h(
+        "div",
+        { className: CLS.body },
+        h("div", { className: CLS.answer }, view.body.text),
+        view.body.evidence.length > 0 &&
+          h(
+            "div",
+            { className: CLS.evidence },
+            `${view.body.evidenceLabel}: ${view.body.evidence.join(" · ")}`,
+          ),
+      ),
+    view.body.kind === "declined" &&
+      h("div", { className: CLS.declined }, view.body.text),
+  );
+}
+
+export default AiSuggestPanel;

package/styles.css

@@ -0,0 +1,40 @@
+/* AI 답변 제안 패널 기본 스타일.
+ *
+ * 클래스는 `fcx-` 로 시작한다 — 소비처(고객사 관리자 화면)의 이름 공간과
+ * 겹치지 않게 하기 위해서다. 배치(margin·위치)는 여기서 정하지 않고 소비처가
+ * `className` 으로 준다. 색·간격을 바꾸려면 아래 변수만 덮어쓰면 된다.
+ */
+.fcx-ai {
+  --fcx-accent: #2f6fed;
+  --fcx-surface: #f5f9ff;
+  --fcx-border: #d7e3f4;
+  --fcx-text: #1f2d3d;
+  --fcx-muted: #5b6b7e;
+  --fcx-warn: #8a5a00;
+
+  padding: 10px 12px;
+  border: 1px solid var(--fcx-border);
+  border-radius: 10px;
+  background: var(--fcx-surface);
+}
+
+.fcx-ai-head { display: flex; gap: 8px; align-items: center; }
+
+.fcx-ai-button,
+.fcx-ai-adopt {
+  padding: 6px 12px;
+  border: 1px solid var(--fcx-accent);
+  border-radius: 8px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.fcx-ai-button { background: var(--fcx-accent); color: #fff; }
+.fcx-ai-button:disabled { opacity: 0.6; cursor: default; }
+.fcx-ai-adopt { background: #fff; color: var(--fcx-accent); }
+
+.fcx-ai-body { margin-top: 8px; }
+.fcx-ai-answer { white-space: pre-wrap; font-size: 13px; color: var(--fcx-text); }
+.fcx-ai-evidence { margin-top: 6px; font-size: 11px; color: var(--fcx-muted); }
+.fcx-ai-declined { margin-top: 8px; font-size: 12px; color: var(--fcx-warn); }

package/view.d.ts

@@ -0,0 +1,27 @@
+/** 표시 판단과 클래스 이름 — 프레임워크 중립.
+ *  React·Vue·웹 컴포넌트가 같은 판단을 쓴다. */
+import type { AnswerResult } from "./client.js";
+
+export interface AiSuggestView {
+  buttonLabel: string;
+  buttonDisabled: boolean;
+  showAdopt: boolean;
+  adoptLabel: string;
+  body:
+    | { kind: "none" }
+    | { kind: "answer"; text: string; evidence: string[]; evidenceLabel: string }
+    | { kind: "declined"; text: string };
+}
+
+export declare function aiSuggestView(input: {
+  state: "idle" | "loading" | "done";
+  result: AnswerResult | null;
+  declineText: (reason: string) => string;
+  messages?: Record<string, string>;
+}): AiSuggestView;
+
+/** 세 어댑터가 공유하는 클래스 이름 (styles.css 와 짝) */
+export declare const CLS: Record<
+  "root" | "head" | "button" | "adopt" | "body" | "answer" | "evidence" | "declined",
+  string
+>;