@fcg-labs/cx-agent-hook 0.6.0 → 0.7.1

package/MIGRATION.md

@@ -1,3 +1,25 @@
+# 0.6.0 → 0.7.0 마이그레이션
+
+## 요약 — 좋아요/싫어요 바가 추가된다. **깨지는 것 없음** (additive)
+
+## 새로 생긴 것
+
+- `AiFeedbackBar`(react) + `feedbackBarView`/`feedbackBarTree`/`FB_CLS`(view 코어) —
+  상담사의 명시적 품질 판단. 신호는 **기존 `scored` 5|1** — 새 action·프로토콜
+  변경 없음(허브·서버 재배포 불필요). 비소모라 발송 전 판단 변경 가능, 집계는
+  같은 응답 최신본 우선.
+- 배치는 답변 편집기 곁 1줄:
+  `<AiFeedbackBar session={getCsSession(csId)} agent={agent} actorClaimed={answerWriter} />`
+- 로케일 키 4종: `ui_feedback_ask/up/down/done` (ko·en·ja·zh-TW).
+
+## 행동 계약
+
+- 초안(answerId)이 없으면 바 자체가 그려지지 않는다.
+- 세션 sink 를 새로 만들지 않는다 — 초안 유무는 부모 리렌더 시점에
+  `session.adoptedAnswerId` 로 읽는다 (compose 종료·문의 전환이 리렌더를 보장).
+
+---
+
 # 0.5.x → 0.6.0 마이그레이션
 
 ## 요약 — 대상 확정(더블체크, 계약 §B.10)이 추가된다. **깨지는 것 없음** (additive)

package/client.js

@@ -387,7 +387,7 @@ export class CxAgentClient {
    * @param {string} [fb.note]
    * @returns {Promise<{ok:boolean, feedbackId:number|null, error:string}>}
    */
-  async sendFeedback({ answerId, action, score, finalText, agent, note } = {}) {
+  async sendFeedback({ answerId, action, score, finalText, agent, note, reasonCode } = {}) {
     // 계약 위반은 재시도해도 소용없다 — 즉시 보고
     if (answerId === undefined || answerId === null || answerId === "") {
       return this._fbFail(new Error("answerId 필수"), "invalid_answer_id");
@@ -411,6 +411,9 @@ export class CxAgentClient {
       ...(finalText ? { final_text: finalText } : {}),
       ...(agent ? { agent } : {}),
       ...(note ? { note } : {}),
+      // 사유 코드는 값 판정을 하지 않고 그대로 운반한다 — enum 정본은 서버(0057).
+      // 모르는 값이면 서버가 거절하고, 그 사실이 드러나는 게 조용한 소실보다 낫다.
+      ...(reasonCode ? { reason_code: reasonCode } : {}),
     };
     const path = target.path(this.domain);
     let lastErr = null;
@@ -457,9 +460,9 @@ export class CxAgentClient {
     return this.sendFeedback({ answerId, action: "edited", finalText, agent });
   }
 
-  /** 폐기 후킹 — 품질 경보 신호 */
-  discarded(answerId, agent, note) {
-    return this.sendFeedback({ answerId, action: "discarded", agent, note });
+  /** 폐기 후킹 — 품질 경보 신호. reasonCode 는 서버 enum(0057) 그대로 운반한다. */
+  discarded(answerId, agent, note, reasonCode) {
+    return this.sendFeedback({ answerId, action: "discarded", agent, note, reasonCode });
   }
 
   /**

package/element.js

@@ -57,6 +57,7 @@ function createClass() {
     #context = null;
     #state = "idle";
     #result = null;
+    #evidenceOpen = false;      // 근거는 접힘이 기본 (0.7.0)
 
     /** createCxHook() 결과 */
     get hook() { return this.#hook; }
@@ -79,6 +80,7 @@ function createClass() {
       // 후킹된다.
       this.#state = "idle";
       this.#result = null;
+      this.#evidenceOpen = false;
       if (this.#hook) this.#hook.clearAdopted();
       this.#render();
     }
@@ -114,10 +116,14 @@ function createClass() {
         result: this.#result,
         declineText: this.#hook.declineText,
         messages: this.#hook.messages,
+        expanded: this.#evidenceOpen,
+        ownRequestButton: this.hasAttribute("own-request-button"),
       });
+      if (!tree) return;
       const actions = {
         request: () => this.#request(),
         adopt: () => this.#adopt(),
+        evidence: () => { this.#evidenceOpen = !this.#evidenceOpen; this.#render(); },
       };
       const root = document.createElement("div");
       root.className = CLS.root;

package/locales.js

@@ -29,8 +29,26 @@ const en = {
   ui_request: "Suggest a reply",
   ui_requesting: "Generating…",
   ui_adopt: "Insert into editor",
+  ui_feedback_ask: "Was this draft helpful?",
+  ui_feedback_up: "Helpful",
+  ui_feedback_down: "Not helpful",
+  ui_feedback_done: "Recorded — it will tune future suggestions.",
   ui_evidence: "Sources",
   ui_correcting: "Fixing phrasing — rewriting…",
+  ui_retrieving: "Finding sources…",
+  ui_ai_label: "AI draft",
+  ui_ai_disclaimer: "AI-generated — review before sending.",
+  ui_feedback_why: "What was wrong?",
+  ui_feedback_skip: "Skip",
+  ui_feedback_note_hint: "What was wrong? (one line)",
+  ui_feedback_note_send: "Send",
+  reason_stale_period: "Outdated",
+  reason_wrong_manual: "Wrong source",
+  reason_factual_error: "Incorrect",
+  reason_missing_answer: "Incomplete",
+  reason_tone_style: "Tone",
+  reason_policy_risk: "Risky wording",
+  reason_other: "Other",
   ui_action_execute: "Process",
   ui_action_confirm_default: "Run this action?",
   ui_action_confirm_ok: "Yes, run",
@@ -76,8 +94,26 @@ const ko = {
   ui_request: "AI 답변 제안",
   ui_requesting: "제안 생성 중...",
   ui_adopt: "에디터에 넣기",
+  ui_feedback_ask: "이 초안, 쓸 만했나요?",
+  ui_feedback_up: "좋아요",
+  ui_feedback_down: "싫어요",
+  ui_feedback_done: "기록됐습니다 — 다음 제안 품질에 반영됩니다.",
   ui_evidence: "근거",
   ui_correcting: "표현 교정 중 — 다시 쓰는 중...",
+  ui_retrieving: "근거 찾는 중…",
+  ui_ai_label: "AI 초안",
+  ui_ai_disclaimer: "AI가 쓴 초안입니다 — 확인 후 전송하세요.",
+  ui_feedback_why: "무엇이 문제였나요?",
+  ui_feedback_skip: "건너뛰기",
+  ui_feedback_note_hint: "무엇이 문제였나요? (한 줄)",
+  ui_feedback_note_send: "보내기",
+  reason_stale_period: "낡은 내용",
+  reason_wrong_manual: "다른 근거",
+  reason_factual_error: "내용 오류",
+  reason_missing_answer: "일부 미답",
+  reason_tone_style: "어조·표현",
+  reason_policy_risk: "위험 표현",
+  reason_other: "기타",
   ui_action_execute: "처리하기",
   ui_action_confirm_default: "이 처리를 진행할까요?",
   ui_action_confirm_ok: "네, 진행",
@@ -118,8 +154,26 @@ const ja = {
   ui_request: "AI 返信案",
   ui_requesting: "生成中...",
   ui_adopt: "エディタに挿入",
+  ui_feedback_ask: "この下書きは役に立ちましたか?",
+  ui_feedback_up: "良い",
+  ui_feedback_down: "悪い",
+  ui_feedback_done: "記録しました — 今後の提案に反映されます。",
   ui_evidence: "根拠",
   ui_correcting: "表現を修正中 — 書き直しています…",
+  ui_retrieving: "根拠を検索中…",
+  ui_ai_label: "AI 下書き",
+  ui_ai_disclaimer: "AI が作成した下書きです — 確認してから送信してください。",
+  ui_feedback_why: "何が問題でしたか?",
+  ui_feedback_skip: "スキップ",
+  ui_feedback_note_hint: "何が問題でしたか?(一行)",
+  ui_feedback_note_send: "送信",
+  reason_stale_period: "古い内容",
+  reason_wrong_manual: "根拠が違う",
+  reason_factual_error: "内容の誤り",
+  reason_missing_answer: "一部未回答",
+  reason_tone_style: "語調・表現",
+  reason_policy_risk: "リスク表現",
+  reason_other: "その他",
   ui_action_execute: "処理する",
   ui_action_confirm_default: "この処理を実行しますか？",
   ui_action_confirm_ok: "はい、実行",
@@ -160,8 +214,26 @@ const zhTW = {
   ui_request: "AI 回覆建議",
   ui_requesting: "產生中...",
   ui_adopt: "插入編輯器",
+  ui_feedback_ask: "這份草稿有幫助嗎?",
+  ui_feedback_up: "有幫助",
+  ui_feedback_down: "沒幫助",
+  ui_feedback_done: "已記錄 — 將反映於後續建議。",
   ui_evidence: "依據",
   ui_correcting: "正在修正表述 — 重新撰寫中…",
+  ui_retrieving: "尋找依據中…",
+  ui_ai_label: "AI 草稿",
+  ui_ai_disclaimer: "AI 產生的草稿 — 請確認後再傳送。",
+  ui_feedback_why: "哪裡有問題?",
+  ui_feedback_skip: "略過",
+  ui_feedback_note_hint: "哪裡有問題?(一行)",
+  ui_feedback_note_send: "送出",
+  reason_stale_period: "內容過時",
+  reason_wrong_manual: "依據不符",
+  reason_factual_error: "內容錯誤",
+  reason_missing_answer: "部分未答",
+  reason_tone_style: "語氣表達",
+  reason_policy_risk: "風險用語",
+  reason_other: "其他",
   ui_action_execute: "處理",
   ui_action_confirm_default: "要執行這項處理嗎？",
   ui_action_confirm_ok: "是，執行",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcg-labs/cx-agent-hook",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
   "type": "module",
   "main": "index.js",

package/react.d.ts

@@ -31,4 +31,13 @@ export interface ActionOffersPanelProps {
 /** 처리 선택지 카드 (actions/1 프로파일 B) — 잠김·비활성·2단 확인·상태·미보고 규약을 갖는다. */
 export declare function ActionOffersPanel(props: ActionOffersPanelProps): ReactElement | null;
 
+export interface AiFeedbackBarProps {
+  session: InquirySession;
+  agent: CxAgent;
+  actorClaimed?: string;
+  className?: string;
+}
+/** 좋아요/싫어요 바 — scored 5|1 로 원장에 남는 상담사 품질 판단 (0.7.0). */
+export declare function AiFeedbackBar(props: AiFeedbackBarProps): ReactElement | null;
+
 export default AiSuggestPanel;

package/react.js

@@ -19,7 +19,7 @@
  */
 import { createElement as h, useCallback, useEffect, useRef, useState } from "react";
 
-import { actionOffersTree, aiSuggestTree, aiSuggestView, CLS } from "./view.js";
+import { actionOffersTree, aiSuggestTree, aiSuggestView, CLS, feedbackBarTree } from "./view.js";
 
 // 표시 판단은 프레임워크 중립 코어가 갖는다 — Vue·웹 컴포넌트와 같은 것을 쓴다.
 export { aiSuggestView };
@@ -30,6 +30,7 @@ function renderNode(node, actions, key) {
   if (node.tag === "button") {
     props.type = node.type || "button";
     props.disabled = Boolean(node.disabled);
+    if (node.pressed !== undefined) props["aria-pressed"] = Boolean(node.pressed);
   }
   if (node.action && actions[node.action]) props.onClick = actions[node.action];
   const children = node.children
@@ -48,17 +49,62 @@ function renderNode(node, actions, key) {
  * @param {(text: string) => void} props.onAdopt  "에디터에 넣기"
  * @param {string}  [props.className] 바깥 배치용 (레이아웃만)
  */
-export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
+/**
+ * 세션+agent → 패널 어댑터. **(session, agent) 쌍당 하나**만 만든다.
+ *
+ * 렌더마다 새 객체를 만들면(0.7.0 이 그랬다) 그것을 deps 로 둔 리셋 effect 가
+ * 렌더마다 돌아 `clearAdopted()` 로 세션의 answer_id 를 지운다 — compose 가
+ * 확정한 id 가 부모의 첫 리렌더에서 사라져 피드백 바가 안 뜨고, 발송 gold 쌍
+ * 후킹도 id 없이 나간다(2026-08-27 운영 실측: answered=true·answer_id 도착,
+ * `.fcx-fb` 0개). 정체성은 훅이 아니라 캐시로 고정한다 — React 밖에서도
+ * 시험할 수 있어야 한다(이 패키지는 react-dom 을 의존하지 않는다).
+ */
+const API_CACHE = new WeakMap();   // session → { agent, api }
+export function sessionApi(session, agent) {
+  if (!session || !agent) return null;
+  const hit = API_CACHE.get(session);
+  if (hit && hit.agent === agent) return hit.api;
+  const api = {
+    enabled: agent.enabled,
+    messages: agent.messages,
+    declineText: agent.declineText,
+    requestAnswer: (q, ctx) => session.compose({ inquiry: q, context: ctx }).promise,
+    noteAdopted: (id) => session.noteAdopted(id),
+    clearAdopted: () => session.clearAdopted(),
+  };
+  API_CACHE.set(session, { agent, api });
+  return api;
+}
+
+export function AiSuggestPanel({ hook, session, agent, inquiry, context, onAdopt, className, ownRequestButton }) {
+  /*
+   * 두 계약을 다 받는다 (0.7.0):
+   *   - `hook`   0.2.x 단일 훅(createCxHook) — 옛 소비처 보존
+   *   - `session`+`agent`  세션 기반(현행) — 초안 정본이 세션 버퍼라 문의 전환·
+   *     복귀에도 살아남는다. 세션엔 enabled·messages 가 없어 agent 가 짝이다.
+   * 섞어 넘기면(session 을 hook 자리에) 카드가 조용히 안 그려진다 —
+   * 실제로 2026-08-27 그 사고가 났다. 그래서 어댑터가 **명시적으로** 짝을
+   * 맞추고, 짝이 안 맞으면 개발 콘솔에 사유를 남긴다.
+   */
+  const api = hook || sessionApi(session, agent);
+  if (!api && typeof console !== "undefined") {
+    console.warn("[cx-agent-hook] AiSuggestPanel: hook 또는 (session+agent) 가 필요합니다");
+  }
   const [state, setState] = useState("idle");
   const [result, setResult] = useState(null);
+  const [evidenceOpen, setEvidenceOpen] = useState(false);   // 근거는 접힘이 기본 (0.7.0)
 
-  // 다른 문의로 옮기면 앞 문의의 제안이 남아 있으면 안 된다. 채택 기록도 같이
-  // 지운다 — 안 지우면 다음 문의를 발송할 때 엉뚱한 answer_id 로 후킹된다.
+  // 다른 문의로 옮기면 앞 문의의 제안이 남아 있으면 안 된다.
+  // 채택 기록은 **단일 훅(hook) 계약에서만** 같이 지운다 — 훅 하나가 모든 문의를
+  // 겸하므로 안 지우면 다음 문의 발송이 엉뚱한 answer_id 로 후킹된다.
+  // 세션 계약에서는 지우지 않는다: 세션이 문의별로 따로라 섞일 일이 없고,
+  // 여기서 지우면 옮겨 간 문의의 세션이 가진 id 까지 죽는다(0.7.1).
   useEffect(() => {
     setState("idle");
     setResult(null);
-    hook.clearAdopted();
-  }, [inquiry, hook]);
+    setEvidenceOpen(false);
+    if (hook) hook.clearAdopted();
+  }, [inquiry, hook, api]);
 
   // context 는 ref 로 최신값만 읽는다 — deps 에 넣으면 인라인 객체가
   // 리렌더마다 새 참조가 되어 요청 콜백이 계속 재생성된다.
@@ -68,21 +114,24 @@ export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
   const request = useCallback(async () => {
     if (!inquiry || state === "loading") return;
     setState("loading");
-    setResult(await hook.requestAnswer(inquiry, contextRef.current));
+    setResult(await api.requestAnswer(inquiry, contextRef.current));
     setState("done");
-  }, [hook, inquiry, state]);
+  }, [api, inquiry, state]);
 
   const adopt = useCallback(() => {
     if (!result || !result.answered) return;
-    hook.noteAdopted(result.answerId);
+    api.noteAdopted(result.answerId);
     if (onAdopt) onAdopt(result.answer);
-  }, [hook, onAdopt, result]);
+  }, [api, onAdopt, result]);
 
-  if (!hook || !hook.enabled) return null;
+  if (!api || !api.enabled) return null;
 
   const tree = aiSuggestTree({
-    state, result, declineText: hook.declineText, messages: hook.messages,
+    state, result, declineText: api.declineText, messages: api.messages,
+    expanded: evidenceOpen, ownRequestButton,
   });
+  // 그릴 것이 없으면 빈 상자를 남기지 않는다 (0.7.0)
+  if (!tree) return null;
 
   return h(
     "div",
@@ -92,7 +141,9 @@ export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
       // 행 선택이 토글되면 제안이 초기화된다.
       onClick: (event) => event.stopPropagation(),
     },
-    tree.children.map((node, i) => renderNode(node, { request, adopt }, i)),
+    tree.children.map((node, i) => renderNode(node, {
+      request, adopt, evidence: () => setEvidenceOpen((v) => !v),
+    }, i)),
   );
 }
 
@@ -183,3 +234,99 @@ export function ActionOffersPanel({ session, agent, actorClaimed, onResult, clas
                     onClick: (event) => event.stopPropagation() },
            tree.children.map((n, i) => render(n, i)));
 }
+
+// ── 좋아요/싫어요 바 (0.7.0) ──────────────────────────────────────────────
+//
+// 답변 패널과 같은 이유로 라이브러리에 있다: 이 판단(scored 5|1)이 절차별
+// 서빙 웨이트·재학습 라벨의 원료다. 고객사는 답변 편집기 곁에 배치만 한다.
+//
+// ```jsx
+// import { AiFeedbackBar } from "@fcg-labs/cx-agent-hook/react";
+// <AiFeedbackBar session={getCsSession(csId)} agent={agent} actorClaimed={answerWriter} />
+// ```
+//
+// 세션 sink 를 새로 늘리지 않는다 — 초안 유무는 부모 리렌더 시점에
+// `session.adoptedAnswerId` 로 읽는다 (compose 종료·문의 전환 때 CMS 가
+// 어차피 리렌더한다). scored 는 비소모라 발송 전 판단 변경이 가능하다.
+
+/**
+ * @param {object} props
+ * @param {object} props.session   agent.session(externalId)
+ * @param {object} props.agent     createCxAgent() 결과 — enabled·messages
+ * @param {string} [props.actorClaimed]  행위자 이름(자기 주장) — 원장에 남는다
+ * @param {string} [props.className]  바깥 배치용 (레이아웃만)
+ */
+export function AiFeedbackBar({ session, agent, actorClaimed, className }) {
+  const answerId = session ? session.adoptedAnswerId : null;
+  const [voted, setVoted] = useState(null);
+  const [asking, setAsking] = useState(false);   // 싫어요 뒤 사유 묻기 (선택)
+  const [noting, setNoting] = useState(false);   // 「기타」 — 한 줄 자유 입력
+  const noteRef = useRef("");
+  // 다른 초안(또는 다른 문의)이 오면 앞 판단 표시가 남으면 안 된다.
+  useEffect(() => {
+    setVoted(null); setAsking(false); setNoting(false); noteRef.current = "";
+  }, [session, answerId]);
+
+  const actorRef = useRef(actorClaimed);
+  actorRef.current = actorClaimed;
+
+  const vote = useCallback((dir) => {
+    if (!session) return;
+    // 판단은 **즉시** 기록된다 — 사유는 그 뒤의 선택이지 전제가 아니다.
+    session.scored(dir === "up" ? 5 : 1, actorRef.current);
+    setVoted(dir);
+    setAsking(dir === "down");
+  }, [session]);
+
+  const sendNote = useCallback(() => {
+    // 코드는 other, 문장은 note — 사유 코드만으로는 뜻을 못 읽는다.
+    if (session) session.discarded(actorRef.current, noteRef.current.trim(), "other");
+    setNoting(false); setAsking(false); noteRef.current = "";
+  }, [session]);
+
+  const pickReason = useCallback((code) => {
+    /*
+     * 사유는 **폐기의 이유**로 남는다 — 서버 계약(store/serving.py:600)이
+     * `reason_code` 를 discarded 에만 허용한다. 점수는 이미 남았고(1클릭),
+     * 여기서 한 번 더 남기는 것은 "이 초안을 버린 이유"다.
+     * discarded 는 소모라 이 뒤로 그 초안의 판단은 닫힌다.
+     */
+    if (code === "other") { setNoting(true); return; }   // 기타 → 한 줄 적기
+    if (session && code) session.discarded(actorRef.current, "", code);
+    setAsking(false);
+  }, [session]);
+
+  if (!session || !agent || !agent.enabled) return null;
+  const tree = feedbackBarTree({ answerId, voted, asking, noting, messages: agent.messages });
+  if (!tree) return null;
+
+  const actions = {
+    up: () => vote("up"),
+    down: () => vote("down"),
+    reason: (e) => pickReason(e.currentTarget.dataset.reason || ""),
+    skip: () => { setAsking(false); setNoting(false); },
+    note: (e) => { noteRef.current = e.target.value; },
+    noteSend: () => sendNote(),
+  };
+  const render = (node, key) => {
+    const props = { key, className: node.cls };
+    if (node.tag === "button") {
+      props.type = node.type || "button";
+      if (node.action && actions[node.action]) props.onClick = actions[node.action];
+      if (node.reason) props["data-reason"] = node.reason;
+      if (node.pressed !== undefined) props["aria-pressed"] = Boolean(node.pressed);
+    } else if (node.tag === "input") {
+      props.type = "text";
+      props.placeholder = node.placeholder || "";
+      props.defaultValue = "";
+      if (node.action && actions[node.action]) props.onChange = actions[node.action];
+      // Enter 로도 보낼 수 있게 — 한 줄 입력에 버튼만 두면 손이 한 번 더 간다
+      props.onKeyDown = (e) => { if (e.key === "Enter") { e.preventDefault(); sendNote(); } };
+    }
+    if (node.live) props.role = "status";
+    return h(node.tag, props, node.children ? node.children.map((c, i) => render(c, i)) : node.text);
+  };
+  return h("div", { className: className ? `${tree.cls} ${className}` : tree.cls,
+                    onClick: (event) => event.stopPropagation() },
+           tree.children.map((n, i) => render(n, i)));
+}

package/session.js

@@ -139,6 +139,14 @@ export class SessionStore {
   }
 }
 
+/** 의사 스트림 (0.7.0) — 통짜 청크로 판정하는 길이. 이보다 크면 조각내어 보여 준다. */
+const BULK_CHUNK_CHARS = 120;
+/** 조각 표시 주기(ms)와 전체를 다 보여주는 데 쓰는 틱 수 — 약 1.4초에 완주. */
+const REVEAL_INTERVAL_MS = 40;
+const REVEAL_TICKS = 35;
+/** 한 틱 최소 글자 — 짧은 답변이 지나치게 느리게 흐르지 않게. */
+const REVEAL_MIN_STEP = 2;
+
 export class InquirySession {
   /**
    * 직접 만들지 않는다 — `agent.session(externalId)` 가 만든다.
@@ -457,6 +465,27 @@ export class InquirySession {
     };
     const clearPending = () => {
       if (pending !== null) { clearTimeout(pending); pending = null; }
+      if (reveal !== null) { clearInterval(reveal); reveal = null; }
+    };
+
+    /*
+     * 의사 스트림 (0.7.0) — 공급자가 통짜로 줄 때도 글자가 흐르게.
+     *
+     * codex 계열은 답변을 **한 번에** 낸다(finish_reason='single_chunk') — 그대로
+     * 그리면 15초 정적 뒤 완성본이 튀어나와 "AI 가 쓰고 있다"는 신호가 0 이다.
+     * 진짜 토큰 스트림이면 이 경로는 타지 않는다(작은 청크는 그대로 흐른다).
+     * 정본(this._draft)은 늘 전체 텍스트다 — 화면에 보이는 양만 늦춘다.
+     */
+    let reveal = null;
+    let revealed = 0;
+    const revealFrom = (full) => {
+      if (reveal !== null) { clearInterval(reveal); reveal = null; }
+      const step = Math.max(REVEAL_MIN_STEP, Math.ceil(full.length / REVEAL_TICKS));
+      reveal = setInterval(() => {
+        revealed = Math.min(full.length, revealed + step);
+        if (this._ui) this._ui.setDraft(decorate(full.slice(0, revealed)));
+        if (revealed >= full.length) { clearInterval(reveal); reveal = null; }
+      }, REVEAL_INTERVAL_MS);
     };
 
     this._state = "composing";
@@ -468,7 +497,17 @@ export class InquirySession {
       signal: controller.signal,
       ...(idleTimeoutMs ? { idleTimeoutMs } : {}),
       ...(overallTimeoutMs ? { overallTimeoutMs } : {}),
-      onDelta: (text) => { accumulated += text; queueDraft(); },
+      onDelta: (text) => {
+        accumulated += text;
+        // 통짜 청크(공급자가 한 번에 준 것)면 조각내어 흘린다 — 판정은 길이뿐이라
+        // 결정적이고, 진짜 스트림의 작은 청크는 기존 스로틀 경로 그대로.
+        if (text.length >= BULK_CHUNK_CHARS) {
+          this._draft = decorate(accumulated);
+          revealFrom(accumulated);
+        } else {
+          queueDraft();
+        }
+      },
       onRestart: () => {
         // 계약 위반 교정 — 지금까지 보인 초안은 폐기본이다
         clearPending();
@@ -478,7 +517,10 @@ export class InquirySession {
         this._setStatus(d.messages.ui_correcting);
       },
       onStage: (phase) => {
-        if (phase === "generating") this._setStatus(d.messages.ui_requesting);
+        // 단계를 사람 말로 — "제안 생성 중" 한 문구로는 15초 동안 무엇이
+        // 진행 중인지 알 수 없다(근거 검색과 생성은 체감이 다른 구간이다).
+        if (phase === "retrieving") this._setStatus(d.messages.ui_retrieving);
+        else if (phase === "generating") this._setStatus(d.messages.ui_requesting);
       },
     }).then((result) => {
       clearPending();
@@ -565,7 +607,7 @@ export class InquirySession {
     this._emit((id) => this._d.client.sent(id, finalText, agent), true);
   }
 
-  /** 품질 점수 1~5 — 발송 전 여러 번 가능 (비소모) */
+  /** 품질 점수 1~5 — 발송 전 여러 번 가능 (비소모). 사유는 여기 안 실린다(아래 계약). */
   scored(score, agent) {
     this._emit((id) => this._d.client.scored(id, score, agent), false);
   }
@@ -575,8 +617,8 @@ export class InquirySession {
     this._emit((id) => this._d.client.edited(id, finalText, agent), false);
   }
 
-  /** 폐기 + 이유 — 마지막 판단이라 기록을 비운다 */
-  discarded(agent, note) {
-    this._emit((id) => this._d.client.discarded(id, agent, note), true);
+  /** 폐기 + 이유 — 마지막 판단이라 기록을 비운다. reasonCode 는 서버 enum(0057). */
+  discarded(agent, note, reasonCode) {
+    this._emit((id) => this._d.client.discarded(id, agent, note, reasonCode), true);
   }
 }

package/styles.css

@@ -178,3 +178,89 @@
 @media (prefers-reduced-motion: reduce) {
   .fcx-ai-button, .fcx-ai-adopt, .fcx-act-button, .fcx-act-resend { transition: none; }
 }
+
+/* ── 좋아요/싫어요 바 (0.7.0) ─────────────────────────────────────────── */
+/* ⚠ 줄바꿈 금지 — 편집기 폭이 좁으면 "좋아요" 가 세로로 쪼개진다(2026-08-27 실측).
+   flex 아이템은 기본적으로 자기 콘텐츠보다 작게 줄어든다(min-width:auto 예외 아님). */
+.fcx-fb { display: flex; align-items: center; gap: 8px; margin-top: 6px; font-size: 13px; flex-wrap: wrap; }
+.fcx-fb-label { color: var(--fcx-muted, #5b6b7d); }
+.fcx-fb-up, .fcx-fb-down {
+  padding: 3px 10px; border-radius: 6px; font-size: 13px; cursor: pointer;
+  border: 1px solid var(--fcx-border, #d4dde7); background: var(--fcx-surface, #fff);
+  color: var(--fcx-text, #1c2733);
+  white-space: nowrap; flex: 0 0 auto;
+}
+.fcx-fb-up[aria-pressed="true"] { background: var(--fcx-success-bg, #e8f5ec); border-color: var(--fcx-success, #1f7a3f); color: var(--fcx-success, #1f7a3f); }
+.fcx-fb-down[aria-pressed="true"] { background: var(--fcx-danger-bg, #fdecea); border-color: var(--fcx-danger, #b42318); color: var(--fcx-danger, #b42318); }
+.fcx-fb-done { color: var(--fcx-muted, #5b6b7d); }
+
+[data-fcx-theme="dark"] .fcx-fb-up, [data-fcx-theme="dark"] .fcx-fb-down {
+  background: var(--fcx-surface, #10182a); border-color: var(--fcx-border, #24344d); color: var(--fcx-text, #dbe6f3);
+}
+[data-fcx-theme="dark"] .fcx-fb-up[aria-pressed="true"] { background: var(--fcx-success-bg, #12301c); }
+[data-fcx-theme="dark"] .fcx-fb-down[aria-pressed="true"] { background: var(--fcx-danger-bg, #3a1512); }
+
+/* ── AI 제안 카드 (0.7.0) — 표식·근거 3단·고지 ─────────────────────────── */
+.fcx-ai-label {
+  align-items: center; display: inline-flex; gap: 4px;
+  border: 1px solid var(--fcx-brand-border, #d4dde7);
+  border-radius: 999px; padding: 1px 8px;
+  font-size: 11px; font-weight: 600; letter-spacing: 0.01em;
+  color: var(--fcx-brand, #5b6b7d);
+}
+.fcx-ai-label::before { content: "✦"; font-size: 10px; }
+
+
+/* 근거 — 접힌 칩이 기본, 펼치면 목록 */
+.fcx-ai-evidence { margin-top: 6px; }
+.fcx-ai-evidence-chip {
+  border: 1px solid var(--fcx-border, #d4dde7); background: var(--fcx-surface, #fff);
+  border-radius: 999px; padding: 2px 10px; font-size: 12px; cursor: pointer;
+  color: var(--fcx-muted, #5b6b7d);
+}
+.fcx-ai-evidence-chip::after { content: " ⌄"; }
+.fcx-ai-evidence-chip[aria-pressed="true"]::after { content: " ⌃"; }
+.fcx-ai-evidence-list { margin-top: 6px; display: grid; gap: 4px; }
+.fcx-ai-evidence-item {
+  font-size: 12px; color: var(--fcx-muted, #5b6b7d);
+  padding-left: 10px; border-left: 2px solid var(--fcx-border, #d4dde7);
+}
+
+/* 고지 — 상시, 그러나 조용하게 */
+.fcx-ai-disclaimer { margin-top: 8px; font-size: 11px; color: var(--fcx-muted, #5b6b7d); }
+
+[data-fcx-theme="dark"] .fcx-ai-evidence-chip { background: var(--fcx-surface, #10182a); border-color: var(--fcx-border, #24344d); }
+[data-fcx-theme="dark"] .fcx-ai-evidence-item { border-left-color: var(--fcx-border, #24344d); }
+
+
+/* 싫어요 사유 (0.7.0) — 1클릭 판단 뒤의 **선택** 단계. 강제하지 않는다. */
+.fcx-fb-why { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; margin-top: 6px; }
+.fcx-fb-why-label { color: var(--fcx-muted, #5b6b7d); font-size: 12px; }
+.fcx-fb-reason, .fcx-fb-skip {
+  border: 1px solid var(--fcx-border, #d4dde7); background: var(--fcx-surface, #fff);
+  border-radius: 999px; padding: 2px 9px; font-size: 12px; cursor: pointer;
+  color: var(--fcx-text, #1c2733); transition: background-color 140ms ease, border-color 140ms ease;
+  white-space: nowrap; flex: 0 0 auto;
+}
+
+/* 기타 = 자유 입력 (2026-08-27 사용자 지적: "기타"만으로는 싫어요의 의미를
+   알 수 없다). 사유 코드는 other 로 남고, 적은 문장은 note 로 함께 간다. */
+.fcx-fb-note { display: flex; gap: 6px; align-items: center; width: 100%; margin-top: 6px; }
+.fcx-fb-note-input {
+  flex: 1 1 auto; min-width: 0;
+  border: 1px solid var(--fcx-border, #d4dde7); border-radius: 6px;
+  padding: 4px 8px; font-size: 12px; color: var(--fcx-text, #1c2733);
+  background: var(--fcx-surface, #fff);
+}
+.fcx-fb-note-send {
+  flex: 0 0 auto; white-space: nowrap;
+  border: 1px solid var(--fcx-brand-border, #d4dde7); background: var(--fcx-surface, #fff);
+  border-radius: 6px; padding: 4px 10px; font-size: 12px; cursor: pointer;
+  color: var(--fcx-brand, #1c2733);
+}
+.fcx-fb-reason:hover { background: var(--fcx-danger-bg, #fdecea); border-color: var(--fcx-danger, #b42318); }
+.fcx-fb-skip { color: var(--fcx-muted, #5b6b7d); border-style: dashed; }
+
+[data-fcx-theme="dark"] .fcx-fb-reason, [data-fcx-theme="dark"] .fcx-fb-skip {
+  background: var(--fcx-surface, #10182a); border-color: var(--fcx-border, #24344d); color: var(--fcx-text, #dbe6f3);
+}

package/view.d.ts

@@ -69,3 +69,18 @@ export declare function actionOffersView(input: {
 }): { visible: boolean; items: ActionOfferItemView[]; disabledHint: string };
 /** action: "confirm" | "execute" | "cancel" | "resend" | "ack" — 텍스트 노드만 */
 export declare function actionOffersTree(input: Parameters<typeof actionOffersView>[0]): AiSuggestNode | null;
+
+// ── 좋아요/싫어요 (0.7.0) ────────────────────────────────────────────────
+export declare const FB_CLS: {
+  root: string; label: string; up: string; down: string; done: string;
+};
+export declare function feedbackBarView(input: {
+  answerId?: string | number | null;
+  voted?: "up" | "down" | null;
+  messages?: Record<string, string>;
+}): {
+  label: string; upLabel: string; downLabel: string; doneText: string;
+  voted: "up" | "down" | null;
+} | null;
+/** action: "up" | "down" — 어댑터가 자기 이벤트로 배선한다 */
+export declare function feedbackBarTree(input: Parameters<typeof feedbackBarView>[0]): AiSuggestNode | null;

package/view.js

@@ -29,10 +29,18 @@ export function aiSuggestView({ state, result, declineText, messages = {} }) {
     body = {
       kind: "answer",
       text: result.answer || "",
-      // 근거 제목이 없으면 키로 대신한다 — 빈 칩을 그리지 않는다.
+      /*
+       * 근거는 **구조로** 낸다 (0.7.0). 예전엔 제목을 이어붙인 문자열 하나라
+       * 소비처가 칩·목록·원문의 3단 접기를 만들 수 없었다 — 화면이 근거를
+       * 아예 안 그리는 실질적 원인이었다. 키는 남긴다(클릭 시 원문 조회용).
+       */
       evidence: (result.evidence || [])
-        .map((e) => e.title || e.unit_key)
-        .filter(Boolean),
+        .map((e) => ({
+          key: e.unit_key || "",
+          title: e.title || e.unit_key || "",
+          score: typeof e.score === "number" ? e.score : null,
+        }))
+        .filter((e) => e.title),
       evidenceLabel: messages.ui_evidence,
     };
   } else if (done) {
@@ -44,6 +52,10 @@ export function aiSuggestView({ state, result, declineText, messages = {} }) {
     buttonDisabled: loading,
     showAdopt: answered,
     adoptLabel: messages.ui_adopt,
+    // AI 산출물의 상시 표식 — Carbon 의 AI label 자리(장식 아님, 설명의 문).
+    aiLabel: messages.ui_ai_label,
+    // "확인 후 전송" 상시 고지 — Cloudscape 의 disclaimer 블록 자리.
+    disclaimer: answered ? messages.ui_ai_disclaimer : "",
     body,
   };
 }
@@ -51,11 +63,16 @@ export function aiSuggestView({ state, result, declineText, messages = {} }) {
 export const CLS = {
   root: "fcx-ai",
   head: "fcx-ai-head",
+  label: "fcx-ai-label",
   button: "fcx-ai-button",
   adopt: "fcx-ai-adopt",
   body: "fcx-ai-body",
   answer: "fcx-ai-answer",
   evidence: "fcx-ai-evidence",
+  evidenceChip: "fcx-ai-evidence-chip",
+  evidenceList: "fcx-ai-evidence-list",
+  evidenceItem: "fcx-ai-evidence-item",
+  disclaimer: "fcx-ai-disclaimer",
   declined: "fcx-ai-declined",
 };
 
@@ -75,11 +92,19 @@ export const CLS = {
  */
 export function aiSuggestTree(input) {
   const v = aiSuggestView(input);
+  const expanded = Boolean(input && input.expanded);
+  // 소비처가 요청 버튼을 자기 화면에 따로 뒀는가 (그러면 카드 안 버튼은 잉여다)
+  const ownRequestButton = Boolean(input && input.ownRequestButton);
   const head = {
     tag: "div", cls: CLS.head,
     children: [
-      { tag: "button", cls: CLS.button, type: "button",
-        disabled: v.buttonDisabled, text: v.buttonLabel, action: "request" },
+      // AI 산출물의 상시 표식 — 답변이 있을 때만(빈 카드에 라벨을 달지 않는다)
+      ...(v.body.kind === "answer" && v.aiLabel
+        ? [{ tag: "span", cls: CLS.label, text: v.aiLabel }] : []),
+      ...(ownRequestButton ? [] : [{
+        tag: "button", cls: CLS.button, type: "button",
+        disabled: v.buttonDisabled, text: v.buttonLabel, action: "request",
+      }]),
       ...(v.showAdopt
         ? [{ tag: "button", cls: CLS.adopt, type: "button",
              disabled: false, text: v.adoptLabel, action: "adopt" }]
@@ -88,19 +113,46 @@ export function aiSuggestTree(input) {
   };
   const children = [head];
   if (v.body.kind === "answer") {
+    /*
+     * 근거는 3단으로 접는다 (0.7.0, 관행 조사 반영): 칩("근거 N") → 목록 →
+     * (소비처가 원하면) 원문. 기본은 접힘 — 상담사가 읽는 것은 답변이지
+     * 출처 목록이 아니다. 펼침 상태는 어댑터가 `expanded` 로 준다.
+     */
+    const ev = v.body.evidence;
+    const evNodes = ev.length > 0
+      ? [{
+          tag: "div", cls: CLS.evidence,
+          children: [
+            { tag: "button", cls: CLS.evidenceChip, type: "button",
+              text: `${v.body.evidenceLabel} ${ev.length}`, action: "evidence",
+              pressed: Boolean(expanded) },
+            ...(expanded
+              ? [{ tag: "div", cls: CLS.evidenceList,
+                   children: ev.map((e) => ({
+                     tag: "div", cls: CLS.evidenceItem, text: e.title,
+                   })) }]
+              : []),
+          ],
+        }]
+      : [];
     children.push({
       tag: "div", cls: CLS.body,
       children: [
         { tag: "div", cls: CLS.answer, text: v.body.text },
-        ...(v.body.evidence.length > 0
-          ? [{ tag: "div", cls: CLS.evidence,
-               text: `${v.body.evidenceLabel}: ${v.body.evidence.join(" · ")}` }]
-          : []),
+        ...evNodes,
+        ...(v.disclaimer ? [{ tag: "div", cls: CLS.disclaimer, text: v.disclaimer }] : []),
       ],
     });
   } else if (v.body.kind === "declined") {
     children.push({ tag: "div", cls: CLS.declined, text: v.body.text });
   }
+  /*
+   * 요청 버튼을 소비처가 자기 화면에 따로 두면(`ownRequestButton`), 초안이 없는
+   * 동안 이 카드는 **테두리·여백만 남은 빈 상자**가 된다 — 2026-08-27 실사고:
+   * CSS 로 버튼만 숨겼더니 화면에 빈 카드가 떠 있었다. 그때는 아예 그리지 않는다.
+   * SDK 는 소비처의 CSS 를 모르므로 **소비처가 선언**한다(추론 금지).
+   */
+  if (ownRequestButton && v.body.kind === "none") return null;
   return { tag: "div", cls: CLS.root, children };
 }
 
@@ -266,3 +318,104 @@ export function actionOffersTree(input) {
   if (v.disabledHint) items.push({ tag: "div", cls: ACTION_CLS.status, text: v.disabledHint });
   return { tag: "div", cls: ACTION_CLS.root, children: items };
 }
+
+// ── 좋아요/싫어요 (0.7.0) — 상담사의 명시적 품질 판단 ─────────────────────
+//
+// 왜 라이브러리에 있나: 이 판단이 절차별 서빙 웨이트·재학습 라벨의 원료다
+// (북극성 "상담사의 매일의 판단이 곧 라벨"). 신호는 기존 scored 5|1 —
+// 새 action·프로토콜 없음. 비소모라 발송 전 판단 변경 가능하고, 집계는
+// 같은 응답 최신본 우선이라 마지막 판단이 이긴다.
+
+export const FB_CLS = {
+  root: "fcx-fb",
+  label: "fcx-fb-label",
+  up: "fcx-fb-up",
+  down: "fcx-fb-down",
+  done: "fcx-fb-done",
+  why: "fcx-fb-why",
+  whyLabel: "fcx-fb-why-label",
+  reason: "fcx-fb-reason",
+  skip: "fcx-fb-skip",
+  note: "fcx-fb-note",
+  noteInput: "fcx-fb-note-input",
+  noteSend: "fcx-fb-note-send",
+};
+
+/** 무엇을 그릴지 — 초안(answerId)이 없으면 판단 대상이 없다(null). */
+/** 기각 사유 코드 — 서버 enum(0057)과 같은 키. 값 판정은 서버가 한다. */
+export const FB_REASONS = [
+  "wrong_manual", "factual_error", "missing_answer",
+  "stale_period", "tone_style", "policy_risk", "other",
+];
+
+export function feedbackBarView({ answerId, voted, asking, noting, messages = {} }) {
+  if (!answerId) return null;
+  const v = voted === "up" || voted === "down" ? voted : null;
+  return {
+    label: messages.ui_feedback_ask,
+    upLabel: messages.ui_feedback_up,
+    downLabel: messages.ui_feedback_down,
+    doneText: v ? messages.ui_feedback_done : "",
+    voted: v,
+    /*
+     * 싫어요 뒤에만 사유를 묻는다 (0.7.0). 1클릭이 기본이고 사유는 선택 —
+     * 관행(Open WebUI RateComment·Claude·Zendesk)이 공통으로 그렇고, 강제하면
+     * 상담사가 싫어요 자체를 안 누른다(신호가 통째로 사라진다).
+     */
+    asking: Boolean(asking) && v === "down",
+    /*
+     * 「기타」는 코드만으로는 뜻이 없다 — 무엇이 문제였는지 못 읽으면 그 신호는
+     * 집계 숫자로만 남고 개선에 못 쓴다(2026-08-27 사용자 지적). 그래서 기타를
+     * 고르면 한 줄 적는 칸이 열린다: 코드는 other, 문장은 note 로 함께 간다.
+     */
+    noting: Boolean(noting) && v === "down",
+    whyLabel: messages.ui_feedback_why,
+    skipLabel: messages.ui_feedback_skip,
+    notePlaceholder: messages.ui_feedback_note_hint,
+    noteSendLabel: messages.ui_feedback_note_send,
+    reasons: FB_REASONS.map((code) => ({ code, label: messages[`reason_${code}`] || code })),
+  };
+}
+
+/** 트리 스펙 — 어댑터가 action "up"/"down" 을 자기 이벤트로 배선한다. */
+export function feedbackBarTree(input) {
+  const v = feedbackBarView(input);
+  if (!v) return null;
+  return {
+    tag: "div", cls: FB_CLS.root,
+    children: [
+      { tag: "span", cls: FB_CLS.label, text: v.label },
+      { tag: "button", cls: FB_CLS.up, type: "button",
+        text: v.upLabel, action: "up", pressed: v.voted === "up" },
+      { tag: "button", cls: FB_CLS.down, type: "button",
+        text: v.downLabel, action: "down", pressed: v.voted === "down" },
+      ...(v.doneText && !v.asking
+        ? [{ tag: "span", cls: FB_CLS.done, text: v.doneText, live: true }]
+        : []),
+      ...(v.noting
+        ? [{
+            tag: "div", cls: FB_CLS.note,
+            children: [
+              { tag: "input", cls: FB_CLS.noteInput, action: "note",
+                placeholder: v.notePlaceholder },
+              { tag: "button", cls: FB_CLS.noteSend, type: "button",
+                text: v.noteSendLabel, action: "noteSend" },
+            ],
+          }]
+        : []),
+      ...(v.asking && !v.noting
+        ? [{
+            tag: "div", cls: FB_CLS.why,
+            children: [
+              { tag: "span", cls: FB_CLS.whyLabel, text: v.whyLabel },
+              ...v.reasons.map((r) => ({
+                tag: "button", cls: FB_CLS.reason, type: "button",
+                text: r.label, action: "reason", reason: r.code,
+              })),
+              { tag: "button", cls: FB_CLS.skip, type: "button", text: v.skipLabel, action: "skip" },
+            ],
+          }]
+        : []),
+    ],
+  };
+}