@kim123rla/hcc-bdp-agent

hcc-bdp-agent

폐쇄망 호스트에 iframe 으로 임베드하는 BDP Agent (RAG 챗봇) UI 모듈.

centri-agent 의 /agents/hdsp_rag/chat/stream SSE 엔드포인트를 호출해 답변을 스트리밍합니다. 현 버전은 mockup 모드 (백엔드 없이도 동작) 입니다.

패키지 내용

라우트/메뉴 정의는 호스트 코드에서 직접 합니다.

호스트 통합

1) 정적 자산 배포

dist/* 를 호스트 정적 서버 경로에 풀어둡니다. 권장 경로: /embedded/bdp-agent/.

scripts/sync-modules.cjs (이미 셋업된 자동 동기화 스크립트) 사용 시 npm install + npm run build 만 하면 자동으로 node_modules/hcc-bdp-agent/dist/* → public/embedded/bdp-agent/ 복사됩니다.

2) 라우트 (호스트에서 직접 작성)

// router/index.ts
const routes: RouteConfig[] = [
  // ...
  {
    path: '/agents',
    component: () => import('@/components/Layout/default/Default.vue'),
    children: [
      {
        path: '/agents/rag-chat',
        name: 'agents-rag-chat',
        component: () => import('@/views/embedded/BdpAgent.vue'),
      },
    ],
  },
]

3) iframe 페이지 컴포넌트 (호스트에서 직접 작성)

옵션 A (가장 단순) — 토큰 전달 불필요한 경우:

<!-- src/views/embedded/BdpAgent.vue -->
<template>
  <iframe
    src="/embedded/bdp-agent/index.html"
    style="width: 100%; height: calc(100vh - 64px); border: 0; display: block;"
  />
</template>

옵션 B — 토큰 전달/높이 동기화 등이 필요한 경우, 패키지의 RemoteModule.vue 활용:

<template>
  <RemoteModule
    src="/embedded/bdp-agent/index.html"
    :token="$store.state.auth.token"
    :base-url="apiBase"
    @request-token="$store.dispatch('auth/refresh')"
  />
</template>

<script lang="ts">
import RemoteModule from 'hcc-bdp-agent/host-integration/RemoteModule.vue'
// ...
</script>

4) 메뉴 (호스트에서 직접 작성)

<v-list-item :to="{ name: 'agents-rag-chat' }">
  <v-list-item-icon><v-icon>mdi-message-text</v-icon></v-list-item-icon>
  <v-list-item-content>
    <v-list-item-title>BDP Agent</v-list-item-title>
  </v-list-item-content>
</v-list-item>

플로팅 위젯의 화면 안내 · 최대화

0.5.30 부터 화면 안내(되묻기·하이라이트 투어)는 꺼져 있다 — 다음 배포에서 다듬어 다시 켠다. 스위치는 src/hostFrame.ts 의 SCREEN_GUIDE_ENABLED 한 줄이다. 채팅 창 최대화와 화면 요소 끌어다 묻기는 그대로 동작한다.

답변 관문(근거가 확인된 답만 내보내기, #1982)은 0.5.31 에서 꺼졌다가 0.5.33 에서 다시 켰다 — 0.5.31 당시는 워크플로우 설명처럼 조회 결과로 답하는 질문까지 보류됐고, 서버에 등급별 관문(#2103)이 들어간 뒤 켰다. 스위치는 src/composables/useChat.ts 의 ANSWER_GATE_ENABLED. 꺼진 번들이 운영에 있으면 사용 현황 판정이 전부 "검증 안 함 · 근거 없이 답변" 이 된다.

?widget=1 로 띄운 위젯이 호스트와 same-origin 이면, 포탈 조작법 답변 뒤에 "화면에서 직접 안내해 드릴까요?" 를 되묻고 동의 시 호스트 화면의 메뉴·버튼을 하이라이트한다. 입력창 위의 버튼으로 채팅 창을 화면 오른쪽 절반으로 키울 수도 있다. 호스트 코드 변경은 없다 — 위젯이 호스트 페이지에 하는 일과 확인 방법은 저장소의 docs/host_chat_widget_guide.md 참고.

화면 오류 제안

호스트 화면에 오류(토스트·배너·role="alert")가 뜨면 위젯이 "이 오류 분석할까요?" 를 먼저 띄운다(자동 전송 없음). same-origin 이면 호스트 코드 변경이 없고, cross-origin 이면 호스트가 host-event 메시지로 알린다 — 계약은 host-integration/HOST_INTEGRATION.md 의 「화면 오류 제안」.

업데이트 흐름

# .tgz 교체 + dep 한 줄만 수정
mv ~/Downloads/hcc-bdp-agent-X.Y.Z.tgz vendor/
# package.json 의 "file:./vendor/..." 경로 새 버전으로
npm install && npm run build

호스트의 router/메뉴 코드는 그대로. 자산 경로(/embedded/bdp-agent/)만 유지되면 됨.