kakaotalk-chat-analyzer 0.16.1 → 0.16.3

package/README.md

@@ -2,33 +2,30 @@
 
 # KakaoTalk Chat Analyzer
 
-### 카카오톡 CSV 보내기 → 익명 집계 리포트 → 선택적 임시 공유 · 한 번에 끝내는 CLI
+### 카카오톡 CSV 보내기 → 터미널 한 줄 → 브라우저 리포트 링크
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-22c55e?style=flat-square)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22-3b82f6?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
 [![GitHub Pages](https://img.shields.io/badge/docs-GitHub%20Pages-8b5cf6?style=flat-square&logo=github)](https://claudianus.github.io/kakaotalk-chat-analyzer/)
 [![npm · kcachat](https://img.shields.io/npm/v/kcachat?label=npm%20kcachat&color=cb3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/kcachat)
-[![npm · 본체](https://img.shields.io/npm/v/kakaotalk-chat-analyzer?label=npm%20본체&color=cb3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/kakaotalk-chat-analyzer)
 
-[**랜딩 (GitHub Pages)**](https://claudianus.github.io/kakaotalk-chat-analyzer/) · [**소스 코드**](https://github.com/claudianus/kakaotalk-chat-analyzer) · [**이슈**](https://github.com/claudianus/kakaotalk-chat-analyzer/issues)
-
-카카오톡 **CSV 보내기** → 터미널 **한 줄** → 브라우저에서 읽는 Wrapped·차트 리포트 링크.
+[**랜딩 (GitHub Pages)**](https://claudianus.github.io/kakaotalk-chat-analyzer/) · [**소스**](https://github.com/claudianus/kakaotalk-chat-analyzer) · [**이슈**](https://github.com/claudianus/kakaotalk-chat-analyzer/issues)
 
 ```bash
 npx kcachat@latest
 ```
 
-[Node.js 22+](https://nodejs.org/) · CSV 생략 시 `KCA_CSV_DIR` 기본 폴더(Win: `Documents\카카오톡 받은 파일`, macOS: Downloads) · `--local` ([빠른 시작](#빠른-시작))
+[Node.js 22+](https://nodejs.org/) · 설치 없이 `npx` · CSV 경로 생략 가능 · [`--local`](#업로드-없이-내-pc에만)
 
 <table>
   <tr>
-    <td align="center" width="33%"><strong>Wrapped</strong><br><img src="docs/assets/demo/wrapped.png" alt="Wrapped 요약과 활동 그리드" width="100%" /></td>
-    <td align="center" width="33%"><strong>차트</strong><br><img src="docs/assets/demo/charts.png" alt="워드클라우드와 시간대 차트" width="100%" /></td>
-    <td align="center" width="33%"><strong>키워드</strong><br><img src="docs/assets/demo/keywords.png" alt="키워드 순위 표" width="100%" /></td>
+    <td align="center" width="33%"><strong>Wrapped</strong><br><img src="docs/assets/demo/wrapped.png" alt="Wrapped 요약" width="100%" /></td>
+    <td align="center" width="33%"><strong>차트</strong><br><img src="docs/assets/demo/charts-viz.png" alt="차트" width="100%" /></td>
+    <td align="center" width="33%"><strong>키워드</strong><br><img src="docs/assets/demo/keywords.png" alt="키워드" width="100%" /></td>
   </tr>
 </table>
 
-<p><sub>미리보기는 테스트 fixture 리포트 캡처입니다. UI 변경 후 <code>npm run docs:capture-demo</code>로 갱신.</sub></p>
+<p><sub><a href="https://claudianus.github.io/kakaotalk-chat-analyzer/#demo">리포트 미리보기 전체</a> (12장 · 탭하면 크게 보기)</sub></p>
 
 </div>
 
@@ -36,318 +33,219 @@ npx kcachat@latest
 
 ## 목차
 
-- [왜 이 프로젝트인가요?](#왜-이-프로젝트인가요)
-- [핵심 기능](#핵심-기능)
-- [대용량·속도](#대용량속도)
-- [리포트 UX](#리포트-ux)
-- [카카오톡에서 CSV 보내기](#카카오톡에서-csv-보내기)
-- [빠른 시작](#빠른-시작)
-- [생성되는 리포트](#생성되는-리포트)
-- [프라이버시 기본값](#프라이버시-기본값)
-- [아키텍처 한눈에](#아키텍처-한눈에)
-- [개발](#개발)
-- [문서 사이트 (GitHub Pages)](#문서-사이트-github-pages)
-- [기여하기](#기여하기)
+**처음 쓰는 분**
 
----
+- [3분 안에 시작하기](#3분-안에-시작하기)
+- [리포트에서 볼 수 있는 것](#리포트에서-볼-수-있는-것)
+- [개인정보·공유 전에](#개인정보공유-전에)
+- [자주 묻는 질문](#자주-묻는-질문)
 
-## 왜 이 프로젝트인가요?
+**더 쓰고 싶을 때**
 
-카카오톡 대화를 **CSV로 보낸 뒤**, 팀·친구·커뮤니티에 **재미있는 통계**를 공유하고 싶을 때가 있습니다.  
-그런데 원문 그대로 올리기엔 **개인정보·민감 URL** 리스크가 큽니다.
+- [옵션·고급](#옵션고급)
+- [최근 업데이트](#최근-업데이트)
 
-**`kca`(KakaoTalk Chat Analyzer)**는 메시지 본문을 **리포트 파일에 저장하지 않고**, 집계 통계만 담은 **단일 `index.html`**을 생성합니다. 몇 개월·수십만 줄 규모도 **파일 전체를 RAM에 올리지 않는 스트리밍 집계**로 처리하고, 리포트는 **한글 프리미엄 UI**(채팅방 이름·히트맵·오전/오후 리듬·인사이트 카드)로 바로 읽을 수 있습니다. 기본은 참여자 **부분 마스킹**, 필요 시 **가입 없이** BrewPage 등에 올려 링크로 공유합니다.
+**개발자**
 
-> 이 도구는 카카오 공식 제품이 아닙니다. 보낸 CSV 형식 변경에 따라 파싱이 깨질 수 있으니, 중요한 데이터는 항상 백업하세요.
+- [개발·기여](#개발기여)
+- [문서 사이트 (GitHub Pages)](#문서-사이트-github-pages)
 
 ---
 
-## 핵심 기능
+## 3분 안에 시작하기
 
-| 영역 | 설명 |
-|------|------|
-| **인코딩** | UTF-8 BOM, UTF-8, CP949/EUC-KR 등 보내기 인코딩 자동 감지 |
-| **파싱** | `Date,User,Message` 헤더 기반 CSV + 멀티라인 메시지 처리 |
-| **리포트** | Wrapped·**ECharts**·**주제 맵**(c-TF-IDF)·**Kiwi+BM25** 키워드 120개·잔디·인사이트 등 **집계 전용** 시각화 |
-| **성능** | 줄 단위 스트림 파싱 · 단일 패스 집계 · 3MB+ Worker · 진행률 **기본 ON** (`--no-progress`로 끔) |
-| **배포** | BrewPage(기본) / TempFile / Cloudflare 등 **TTL 기반** 임시 호스팅 · iframe 공유 링크 안전 처리 |
-| **npx** | 짧은 별칭 **[`kcachat`](https://www.npmjs.com/package/kcachat)** 또는 본체 **`kakaotalk-chat-analyzer`** |
-| **프라이버시** | 원문 미포함, 참여자 **부분 마스킹 표시명**(기본), URL은 **도메인**만 집계 |
+### 1. 카카오톡에서 CSV 보내기
 
----
+1. PC 카카오톡에서 채팅방 열기  
+2. **더보기(≡)** → **대화 보내기** → **CSV 보내기**
 
-## 대용량·속도
+파일명은 보통 `KakaoTalk_Chat_…` 형태입니다. **원문이 들어 있는 파일**이므로 다른 사람에게 보내기 전에 내용을 확인하세요.
 
-카카오 보내기 CSV는 **일반 표 CSV가 아니라** “날짜 줄 + 이어지는 본문” 형식입니다. `kca`는 이 형식에 맞춘 **전용 스트림 파서**로 읽고, 메시지마다 통계만 누적한 뒤 **본문은 즉시 버립니다**.
+### 2. 터미널에서 한 줄 실행
 
-| 설계 | 효과 |
-|------|------|
-| **스트리밍 파싱** | 파일 전체를 문자열/배열로 펼치지 않음 |
-| **단일 패스 집계** | `Map`·히스토그램·온라인 통계(간격 P90 등)만 유지 |
-| **Worker (≥3MB)** | 대용량일 때 메인 스레드 멈춤 완화 |
-| **키워드** | **Kiwi** 한국어 형태소(+방별·glossary userWords) + **BM25**·PMI + **한국어 방 자동 시맨틱**(다국어 임베딩) |
-| **kcachat@latest** | 실행 시 `kakaotalk-chat-analyzer@latest` 본체를 받아 최신 CLI 사용 |
+[Node.js 22+](https://nodejs.org/)가 설치되어 있어야 합니다.
 
-로컬 벤치(합성 20만 메시지, 집계만): **약 0.4초대** — 환경·디스크·실제 대화 밀도에 따라 달라집니다.
+**공유 링크까지 (기본)** — 저장 폴더에서 **가장 최근** CSV를 자동으로 고릅니다:
 
 ```bash
-# 진행률은 기본으로 stderr에 표시 (집계 → Kiwi 준비 → 키워드·주제). 끄려면:
-npx kcachat@latest "./KakaoTalk_Chat_....csv" --no-progress
-
-# 한국어 방은 시맨틱 키워드가 기본 ON (multilingual-e5-small, 끄려면 --no-semantic-keywords)
-# 영어 위주 방에서 강제: --semantic-keywords
-# 이전 MiniLM: KCA_SEMANTIC_MODEL=Xenova/paraphrase-multilingual-MiniLM-L12-v2
-
-# 단계별 ms (Worker 끔)
-npx kcachat@latest "./KakaoTalk_Chat_....csv" --profile --no-worker
-
-# 개발용 벤치
-npm run bench:stream -- 100000
+npx kcachat@latest
 ```
 
-> 외부 DB(DuckDB 등) 없이 **Node.js만**으로 동작합니다. 의존성·설치 부담을 줄이기 위한 선택입니다.
-
----
-
-## 리포트 UX
+**내 PC에만 저장** (인터넷 업로드 없음):
 
-생성되는 `index.html`은 **브라우저만** 있으면 열리는 단일 파일입니다. (인터랙티브 차트는 CDN으로 ECharts를 불러옵니다.)
+```bash
+npx kcachat@latest --local
+```
 
-- **⓪ Wrapped · 스토리**: 카드형 한 장면 요약, **페르소나·챕터**, **활동 기간/연간 그리드**(짧은 기간은 「활동 기간 그리드」), **이벤트 스파인**, 방 프로필·타임라인
-- **빠른 이동**: Wrapped · 페르소나 · 연간 그리드 · 숫자 요약 · 하이라이트 · 주제 맵 · 인터랙티브 차트 · 용어 설명
-- **혁신 레이어**: **dyad**(누가 누구에게 답하는가)·기간 비교·내러티브·브러시 기간 탐색
-- **인터랙티브 차트**: 워드클라우드, 시간대·**요일 7색**·월별, **대화 테마 · c-TF-IDF**, **키워드 순위 목록**(인라인 막대·전체 120개)
-- **숫자·인사이트**: 지니·리듬 점수·응답 간격(초/분)·하이라이트·시스템 알림 분리
-- **키워드**: **Kiwi** + **BM25/PMI** + 한국어 방 **자동 시맨틱**(e5-small), 오픈채팅·잡음어 필터
-- **참여자**: 말풍선 맵 + 마스킹 닉네임 + 랭킹 테이블
-- **생성 메타 (0.13.3+)**: 사이드 카드 **생성 도구**(`kca` 버전), 접기 **리포트 정보**, `#kca-provenance` JSON — BrewPage 링크로 **어떤 kca로 만들었는지** 확인 가능
-- **BrewPage**: iframe 섹션 점프·외부 링크 안전 처리
-- **테마**: 라이트 / 다크 / 시스템 · **OLED glass** 비주얼
+| OS | 자동으로 찾는 폴더 |
+|----|-------------------|
+| **Windows** | `문서\카카오톡 받은 파일` (없으면 `문서\카카오톡` → `다운로드`) |
+| **Mac** | `다운로드` (Downloads) |
 
-원문 메시지·전체 URL은 HTML에 넣지 않습니다(BrewPage 5MiB 한도 고려). **이미 올린 링크는 재업로드해야** UI·버전 메타가 바뀝니다.
+다른 폴더를 쓰려면: `KCA_CSV_DIR=~/Desktop npx kcachat@latest`
 
-### 최근
+### 3. 링크 열기
 
-| 버전 | 요약 |
-|------|------|
-| **0.16.1** | Windows 기본 CSV 경로 `Documents\카카오톡 받은 파일` 자동 탐색 |
-| **0.16.0** | **최신 CSV 자동**(`npx kcachat`·`latest --list/--pick`)·진행률 추정·30분 세션 gap·topicModel provenance·Facts/Wrapped DOM 정렬 |
-| **0.15.0** | Trust UX(조건부 네비·참여자 카드)·키워드 RRF·burst MAD·Kiwi 1×CSV read·오픈채팅 인사이트·임베딩 주제 옵션 |
-| **0.13.8** | burst 활동일 스케일·대용량 gap exact quantile·주제맵 PMI/약한 edge·벤치 **추정** UI·회귀 fixture |
-| **0.13.7** | **BM25** 키워드·**담화어** 통합 lexicon·주제맵 discourse 게이트·시맨틱 k-means++/coherence·타임라인 meme **peakDate** |
-| **0.13.6** | 활동 그리드 일별 셀·dyad 전체 숫자·주제맵 품질·키워드 요약 펼침·샵검색 집계·시스템 테마 |
-| **0.13.5** | 키워드 **순위 목록** 통합(ECharts 막대+표 → 인라인 막대 표) · ② 요약 상위 12·접기 기본 |
-| **0.13.4** | Worker 분석 시 provenance **`kiwiAvailable`** 정확 표시 (`kiwiAvailableAtAnalysis`) |
-| **0.13.3** | HTML **provenance**: `kca` 버전·`#kca-provenance` JSON·**리포트 정보** `<details>`·`kcachat` → `KCA_INVOKER` |
-| **0.13.2** | 키워드 막대 insideLeft·상위 3색, **활동 기간 그리드**(compact), 주제 테마/기간 분리, dyad visualMap |
-| **0.13.1** | 생성 시각·소요, 이벤트 스파인, 히트맵/참여 pie, 주제맵·키워드 UX |
-| **0.13.0** | dyad·타임라인·내러티브·기간 탐색(혁신 레이어) |
-| **0.12.0** | OLED glassmorphism 리포트 비주얼 |
-| **0.11.2** | lazy charts·Playwright `report:screenshots` |
-| **0.11.1** | ECharts 반응형 grid·모바일 말풍선·`npm run report:viewport` |
-| **0.11.0** | 반응형 6레이어·ResizeObserver·스크롤 리빌 |
-| **0.10.x** | Open Props CSS 번들·테마 대비·Pretendard ([Releases](https://github.com/claudianus/kakaotalk-chat-analyzer/releases)에서 0.10.0–0.10.2) |
-| **0.9.x** | e5-small 시맨틱 기본·스크롤 스파이 네비 ([Releases](https://github.com/claudianus/kakaotalk-chat-analyzer/releases)) |
-| **0.3–0.8** | Kiwi·BM25·주제 맵·한국어 시맨틱·스트림 2단계 등 — [Releases](https://github.com/claudianus/kakaotalk-chat-analyzer/releases) 참고 |
+터미널에 나온 **URL**을 브라우저에서 열면 Wrapped·차트·키워드가 있는 리포트를 볼 수 있습니다.
 
----
+- **최초 1회**는 한국어 분석 모델 다운로드로 **1~3분** 걸릴 수 있습니다.  
+- 이미 올린 예전 링크는 **다시 실행·업로드**해야 UI가 바뀝니다.
 
-## 카카오톡에서 CSV 보내기
+### 파일을 직접 고르고 싶을 때
 
-1. 카카오톡에서 분석할 **채팅방**을 엽니다.
-2. 우측 상단 **더보기(≡)** → **대화 보내기** → **CSV 보내기**로 파일을 저장합니다. (파일명은 보통 `KakaoTalk_Chat_…` 형태입니다.)
-3. 아래 [빠른 시작](#빠른-시작)의 `npx` 명령에 **저장한 파일 경로**를 넣어 실행합니다.
+```bash
+npx kcachat@latest latest --list      # 후보 목록
+npx kcachat@latest latest --pick 1    # 두 번째로 최근 파일
+npx kcachat@latest "C:\경로\KakaoTalk_Chat_....csv"
+```
 
-> iOS/Android 앱 버전에 따라 메뉴 문구가 조금 다를 수 있습니다. **메시지 원문이 포함된 CSV**이므로, 공유·업로드 전에 항상 내용을 확인하세요.
+> 카카오 **공식 앱이 아닙니다.** 보내기 CSV 형식이 바뀌면 동작이 깨질 수 있으니 중요한 대화는 백업해 두세요.
 
 ---
 
-## 빠른 시작
-
-### 요구 사항
+## 리포트에서 볼 수 있는 것
 
-- [Node.js](https://nodejs.org/) **22 이상**
+브라우저만 있으면 되는 **단일 HTML**입니다. **대화 원문은 파일에 넣지 않습니다.**
 
-### npx 한 줄 (추천)
+| 구역 | 내용 |
+|------|------|
+| **Wrapped** | 한 장면 요약, 활동 달력, 페르소나·하이라이트 |
+| **차트** | 워드클라우드, 요일·시간대, 주제 맵 |
+| **키워드** | 상위 단어 순위 (한국어 형태소 + 통계) |
+| **참여자** | 말풍선·랭킹 (이름은 **일부만** 보이게 마스킹) |
+| **테마** | 라이트 / 다크 / 시스템 |
 
-**짧은 패키지명 [`kcachat`](https://www.npmjs.com/package/kcachat)** 으로 본체(`kakaotalk-chat-analyzer`)와 똑같이 실행할 수 있습니다.
+공유 링크(BrewPage 등)로 열어도 되고, `--local`로 만든 `index.html`을 더블클릭해도 됩니다.
 
-| 상황 | 대략 소요 (M1급, 참고) |
-|------|------------------------|
-| 최초 `npx` + Kiwi 모델 | 1~3분 (1회) |
-| 2천 건 · `--local` · 시맨틱 끔 | 수 초 |
-| 9만 건 · Kiwi ON · 시맨틱 ON | 수십 초~2분 |
+---
 
-**로컬에만** (`--local`: HTML만 만들고 기본 BrewPage 업로드는 생략. 출력 기본 `.tmp/kca-report`, `-o ./report`로 변경):
+## 개인정보·공유 전에
 
-```bash
-npx kcachat@latest --local
-# 또는 경로 지정: npx kcachat@latest "./KakaoTalk_Chat_....csv" --local
-```
+- 메시지 **본문은 리포트 HTML에 저장하지 않습니다** (집계에만 사용).
+- 참여자 이름은 기본적으로 **앞·뒤만 남기고 가운데 마스킹**합니다.
+- URL은 **도메인**만 집계합니다.
+- 그래도 **키워드·통계**만으로 방 분위기가 드러날 수 있습니다. 링크를 보내기 전에 한 번 훑어 보세요.
+- `--local`을 쓰면 기본적으로 **외부 업로드 없이** 내 PC에만 저장합니다.
 
-**리포트 생성 후 기본 호스트(BrewPage)로 업로드** (CSV 생략 시 **KCA_CSV_DIR** 또는 OS 기본 폴더에서 최신 `KakaoTalk*.csv` 자동 선택):
+---
 
-| OS | 기본 폴더 |
-|----|-----------|
-| Windows | `%USERPROFILE%\Documents\카카오톡 받은 파일` |
-| macOS 등 | `~/Downloads` |
+## 자주 묻는 질문
 
-```bash
-npx kcachat@latest
-npx kcachat@latest latest --list    # 후보 10개 목록
-npx kcachat@latest latest --pick 1  # 두 번째로 최근 파일
-KCA_CSV_DIR=~/Desktop npx kcachat@latest
-```
+**Q. Node.js가 없어요.**  
+→ [nodejs.org](https://nodejs.org/)에서 LTS(22+) 설치 후 터미널을 다시 엽니다.
 
-> **버전:** `kcachat@latest`는 본체 `kakaotalk-chat-analyzer@latest`를 매 실행 받습니다. 고정하려면 `npx kakaotalk-chat-analyzer@0.13.4`. 리포트 사이드 카드·`grep kca-provenance`로 실제 생성 버전을 확인하세요. 오프라인은 `kcachat … --bundled`. ([kcachat README](kcachat/README.md))
+**Q. CSV를 못 찾는다고 해요.**  
+→ 위 [OS별 폴더](#2-터미널에서-한-줄-실행)에 파일이 있는지 확인하거나, 경로를 직접 넣으세요.
 
-CSV와 같은 폴더에 **`.kca-glossary.txt`**(한 줄에 한 단어)를 두면 Kiwi 사용자 사전에 자동 반영됩니다.
+**Q. 첫 실행이 너무 느려요.**  
+→ Kiwi 한국어 모델을 **처음 한 번** 받는 중입니다. 이후에는 훨씬 빨라집니다.
 
-전체 이름으로 실행해도 동일합니다:
+**Q. 친구에게 링크만내면 되나요?**  
+→ 네. 다만 통계·키워드가 방 성격을 드러낼 수 있으니 공유 범위는 스스로 판단하세요.
 
-```bash
-npx kakaotalk-chat-analyzer@latest "./KakaoTalk_Chat_....csv" --local
-```
+**Q. 예전에 만든 링크 UI가 옛날이에요.**  
+→ 그 링크는 업로드 당시 HTML이 고정됩니다. CSV로 **다시 실행**해 새 링크를 받으세요.
 
-GitHub 소스에서 직접:
+**Q. `kcachat`와 `kakaotalk-chat-analyzer` 차이?**  
+→ 같은 프로그램입니다. `kcachat`는 짧은 `npx` 이름입니다.
 
-```bash
-npx github:claudianus/kakaotalk-chat-analyzer "./KakaoTalk_Chat_....csv" --local
-```
-
-### 로컬 클론 개발
-
-```bash
-git clone https://github.com/claudianus/kakaotalk-chat-analyzer.git
-cd kakaotalk-chat-analyzer
-npm install
-npm run build
-npm test
-```
+---
 
-### CLI 요약
+## 옵션·고급
 
-기본 동작은 **서브커맨드 없이** `<csv>` 한 개만 주면 됩니다.
+<details>
+<summary><strong>CLI 전체 옵션 (펼치기)</strong></summary>
 
 ```bash
 # 기본: HTML 생성 후 BrewPage 업로드
 kca ./KakaoTalk_Chat_....csv
 
 # 업로드 없이 로컬만
-kca ./KakaoTalk_Chat_....csv --local -o ./report
+kca ./chat.csv --local -o ./report
 
 # 업로드 생략(드라이런)
-kca ./KakaoTalk_Chat_....csv --dry-run
+kca ./chat.csv --dry-run
 
-# TempFile 호스트
+# 다른 호스트
 kca ./chat.csv --host tempfile --ttl 30
 
-# 보내기 구조 점검(원문 출력 없음, 스트리밍)
-kca inspect ./KakaoTalk_Chat_....csv
+# 보내기 구조 점검(원문 출력 없음)
+kca inspect ./chat.csv
 
-# 진행률 끄기(CI·스크립트) / 단계별 ms 프로파일
+# 진행률 끄기 / 프로파일
 kca ./chat.csv --no-progress
 kca ./chat.csv --profile --no-worker
 
-# YYYY-MM-DD 이후만 집계
+# 날짜 필터
 kca ./chat.csv --since 2025-01-01
 
 kca --help
 ```
 
-업로드가 실패해도 **로컬 `index.html`은 남습니다**.
-
----
-
-## 생성되는 리포트
+업로드가 실패해도 **로컬 `index.html`은 남습니다.**
 
-- **단일 `index.html`**: CSS·차트·안내 문구가 **한 파일에 포함**되어 오프라인에서도 동작합니다.
-- **원문 미저장**: 메시지 본문은 통계 계산에만 사용되며 HTML에 남기지 않습니다.
-- **provenance (CLI)**: `kca` 버전·분석 옵션·HTML 크기·생성 소요가 **생성 도구** / **리포트 정보** / `#kca-provenance`에 기록됩니다.
-- **재업로드 안내**: 예전 BrewPage 링크는 생성 시점 HTML이 고정됩니다. UI·버그 수정 후에는 **다시 업로드**해야 반영됩니다.
-- 자세한 화면 구성은 [리포트 UX](#리포트-ux)를 참고하세요.
+</details>
 
----
-
-## 프라이버시 기본값
+<details>
+<summary><strong>성능·키워드·벤치 (개발·파워유저)</strong></summary>
 
-- 기본(`public-masked`)은 참여자 이름을 **앞·뒤 글자만 남기고 가운데 마스킹**합니다(동명이의 충돌 시 `·2`처럼 구분자가 붙을 수 있음). 완전 별칭(`User 001`)은 `--privacy public-anonymous` 로 선택할 수 있습니다.
-- 메시지 텍스트는 **통계 계산에만** 사용되며, **생성된 HTML에 원문이 쓰이지 않습니다**.
-- URL에서 **도메인**만 집계하고, 전체 URL 문자열은 리포트에 보존하지 않습니다.
-- BrewPage **owner 토큰**은 로컬에 저장되어, 이후 링크 관리·삭제에 활용할 수 있습니다.
+- **스트리밍 파싱**: 대용량 CSV도 RAM에 통째로 올리지 않음  
+- **진행률**: 기본 ON (`--no-progress`로 끔)  
+- **시맨틱 키워드**: 한국어 방 기본 ON (`--no-semantic-keywords`로 끔)  
+- CSV 옆 **`.kca-glossary.txt`**(한 줄에 한 단어) → Kiwi 사용자 사전 반영  
 
 ```bash
-# 저장된 owner 토큰 삭제
-kca token clear --host brewpage --ns kakao-chat-report
+npx kcachat@latest "./chat.csv" --profile --no-worker
+npm run bench:stream -- 100000   # 저장소 클론 후
 ```
 
----
+</details>
 
-## 아키텍처 한눈에
-
-```
-CSV 파일 (스트림 read)
-   → 인코딩 샘플(512KB) + 줄 단위 Kakao 파서
-   → ReportAggregator (단일 패스 · 메시지 본문 비보관)
-        ├─ [≥3MB] Worker 스레드 (선택)
-        └─ Gap/키워드 온라인 통계
-   → report.ts (단일 HTML, 다크/라이트)
-   → [선택] providers → BrewPage / TempFile / Cloudflare
-```
-
-`kcachat`는 npm에서 **짧은 이름**으로 위 파이프라인을 실행하는 래퍼입니다.
-
----
+**버전 고정:** `npx kakaotalk-chat-analyzer@0.16.1` · 최신은 `kcachat@latest`가 매번 본체를 받습니다. 리포트 사이드 카드·`#kca-provenance`로 실제 생성 버전을 확인할 수 있습니다.
 
-## 개발
+**로컬 개발:**
 
 ```bash
-npm install
-npm run build   # sync-version → CSS 번들 → tsc
-npm test
+git clone https://github.com/claudianus/kakaotalk-chat-analyzer.git
+cd kakaotalk-chat-analyzer && npm install && npm run build && npm test
 ```
 
-유용한 스크립트: `npm run report:qa` · `report:qa:serve` · `report:screenshots` · `docs:capture-demo` · `keyword:audit` · `bench:stream` · Pages pill `node scripts/sync-docs-version.mjs`
-
 ---
 
-## 문서 사이트 (GitHub Pages)
-
-### Kiwi 모델·환경 변수
-
-- **최초 실행** 시 GitHub에서 Kiwi 한국어 모델을 **무료**로 받아 `~/.cache/kakaotalk-chat-analyzer/kiwi-base/`에 둡니다.
-- **`KCA_NO_KIWI=1`**: 형태소 없이 휴리스틱만(빠름, 품질↓).
-- **진행률**: 기본으로 stderr에 `대화 분석 42% (…)` 표시. 끄려면 `--no-progress`.
-- **키워드 비교**: `npm run keyword:diff -- ./KakaoTalk_Chat_....csv 30`
-- LGPL 고지: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)
+## 최근 업데이트
 
-랜딩([`docs/index.html`](docs/index.html))은 **업로드 한 줄 명령**·**리포트 데모 스크린샷**·짧은 팁만 담은 단일 HTML입니다. 상세 옵션은 이 README를 봅니다. `main`에 `docs/` 변경을 푸시하면 **GitHub Actions**가 Pages를 배포합니다.
+| 버전 | 요약 |
+|------|------|
+| **0.16.3** | 기본 **품질 우선** 프로필(메인 스레드·시맨틱 샘플 확대·RRF 완화·임베딩 주제). 가속은 `--worker` / `--fast` |
+| **0.16.1** | Windows 기본 CSV 폴더 `문서\카카오톡 받은 파일` |
+| **0.16.0** | 경로 생략·`latest --list/--pick`·진행률 추정·세션 gap |
+| **0.15.0** | 모바일 참여자 카드·키워드 RRF·오픈채팅 인사이트 |
+| **0.13.8** | burst·주제맵·벤치 UI |
+| **0.13.3** | 리포트에 `kca` 버전(provenance) 표시 |
 
-- **공개 URL:** [https://claudianus.github.io/kakaotalk-chat-analyzer/](https://claudianus.github.io/kakaotalk-chat-analyzer/)
-- **워크플로:** [`.github/workflows/pages.yml`](.github/workflows/pages.yml)
+이전 버전: [Releases](https://github.com/claudianus/kakaotalk-chat-analyzer/releases)
 
-### 저장소를 새로 쓸 때 (Pages 켜기)
+---
 
-1. GitHub **Settings → Pages**
-2. **Build and deployment → Source:** **GitHub Actions** 선택
-3. `main`에 푸시하면 **Deploy GitHub Pages** 워크플로가 `docs/`를 게시합니다. (최초 1회는 Actions 탭에서 권한/환경 승인이 필요할 수 있습니다.)
+## 개발·기여
 
----
+```bash
+npm install && npm run build && npm test
+```
 
-## 기여하기
+유용한 스크립트: `report:qa` · `report:screenshots` · `docs:capture-demo` · `bench:stream`
 
-이슈·PR·아이디어 모두 환영합니다. 큰 변경 전에는 이슈에서 방향을 먼저 짧게 나누면 리뷰가 빨라집니다.
+이슈·PR 환영합니다. 민감한 CSV·토큰은 이슈에 첨부하지 마세요.
 
-1. Fork → 브랜치 생성  
-2. `npm test` 통과  
-3. PR 설명에 **동기(왜)** 와 **테스트 방법**을 적어 주세요.
+**아키텍처 (요약):** CSV 스트림 → 집계(본문 비보관) → 단일 HTML → [선택] BrewPage 등 업로드.
 
 ---
 
-## 보안
+## 문서 사이트 (GitHub Pages)
 
-민감한 CSV나 토큰이 포함된 스크린샷은 **이슈/PR에 첨부하지 마세요**.  
-취약점으로 보이는 내용은 비공개 채널(예: GitHub Security Advisories)로 알려 주시면 감사하겠습니다.
+- **공개 URL:** [https://claudianus.github.io/kakaotalk-chat-analyzer/](https://claudianus.github.io/kakaotalk-chat-analyzer/)
+- [`docs/index.html`](docs/index.html) — 시작 명령·OS별 폴더·짧은 팁
+- `main`에 `docs/` 푸시 시 Actions가 배포 · pill 버전: `node scripts/sync-docs-version.mjs`
 
 ---
 
@@ -355,12 +253,8 @@ npm test
 
 [MIT License](./LICENSE)
 
----
-
 <div align="center">
 
 **Made with care for safer chat analytics** · [@claudianus](https://github.com/claudianus)
 
-⭐ 이 프로젝트가 도움이 되었다면 스타 한 번 부탁드립니다.
-
 </div>

package/dist/src/aggregator.d.ts

@@ -8,7 +8,11 @@ export interface FinalizeSourceMeta {
 export interface FinalizeOptions {
     usedSemanticKeywords?: boolean;
     koreanPrimary?: boolean;
+    useEmbeddingTopics?: boolean;
+    semanticSupplementRrfWeight?: number;
 }
+/** 시맨틱 supplement messageHits 상한 — RRF 독점 방지 */
+export declare function semanticSupplementHitCap(corpusMessages: number): number;
 export interface AggregatorOptions {
     /** 시맨틱 키워드용 메시지 샘플 수집 */
     semanticSamples?: boolean;
@@ -89,7 +93,7 @@ export declare class ReportAggregator {
         label: string;
         messageHits: number;
         score?: number;
-    }[]): void;
+    }[], corpusMessages: number): void;
     consume(record: ChatRecord, opts?: {
         keywordsOnly?: boolean;
         skipKeywords?: boolean;

package/dist/src/aggregator.js

@@ -10,6 +10,7 @@ import { buildTopicStopwords } from "./topic-stopwords.js";
 import { MessageReservoir } from "./message-reservoir.js";
 import { semanticReservoirCap, semanticSampleCap, subsampleSemanticMessages } from "./semantic-policy.js";
 import { mergeKeywordRankings } from "./keyword-merge.js";
+import { isNoiseKeyword } from "./keyword-quality.js";
 import { formatCompactNumber, formatReplyGapMinutes } from "./report-util.js";
 import { KeywordCounter } from "./keyword-counter.js";
 import { RepeatPhraseCounter } from "./repeat-phrase-counter.js";
@@ -47,6 +48,10 @@ const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const LAUGH_RE = /(?:ㅋ{2,}|ㅎ{2,}|ㅠ+|ㅜ+|ㅇㅇ|ㅋㅋ|ㅎㅎ|ㅋㅎ|ㅎㅋ)/;
 const LINK_HINT_RE = /https?:\/\/|www\./i;
 const HAS_TOKEN_CHAR_RE = /[가-힣A-Za-z]/;
+/** 시맨틱 supplement messageHits 상한 — RRF 독점 방지 */
+export function semanticSupplementHitCap(corpusMessages) {
+    return Math.min(24, 4 + Math.floor(Math.sqrt(Math.max(corpusMessages, 1))));
+}
 export class ReportAggregator {
     filePath;
     privacy;
@@ -156,14 +161,17 @@ export class ReportAggregator {
         if (this.semanticReservoir && messageLength >= 12)
             this.semanticReservoir.push(msg);
     }
-    applySemanticKeywordBoost(items) {
-        this.semanticThemeCandidates = items.map((item) => ({
+    applySemanticKeywordBoost(items, corpusMessages) {
+        const hitCap = semanticSupplementHitCap(corpusMessages);
+        const valid = items.filter((item) => !isNoiseKeyword(item.label));
+        this.semanticThemeCandidates = valid.map((item) => ({
             label: item.label,
             messageHits: item.messageHits,
             score: item.score ?? item.messageHits,
         }));
-        for (const item of items) {
-            this.keywordSupplement.addHits(item.label, Math.max(2, item.messageHits));
+        for (const item of valid) {
+            const hits = Math.max(2, Math.min(item.messageHits, hitCap));
+            this.keywordSupplement.addHits(item.label, hits);
         }
     }
     consume(record, opts) {
@@ -445,9 +453,9 @@ export class ReportAggregator {
             limit: keywordLimit,
             minDocFreq: adaptiveMinCount(total, finalizeOpts?.koreanPrimary !== false),
         });
-        const keywords = mergeKeywordRankings(wordRankItems, this.keywordSupplement, keywordLimit);
+        const keywords = mergeKeywordRankings(wordRankItems, this.keywordSupplement, keywordLimit, finalizeOpts?.semanticSupplementRrfWeight ?? 0.5);
         let topics = this.topicMap.buildTopics(total, buildTopicStopwords());
-        if (process.env.KCA_EMBEDDING_TOPICS === "1" && this.semanticThemeCandidates.length > 0) {
+        if (finalizeOpts?.useEmbeddingTopics && this.semanticThemeCandidates.length > 0) {
             topics = mergeEmbeddingThemes(topics, this.semanticThemeCandidates, total);
         }
         const burstDetectionMethod = resolveBurstDetectionMethod();