wa-audit

귀하의 WhatsApp 비즈니스 번호에 대한 상업적 감사(audit). WAHA 인스턴스를 지정하면 전체 채팅 기록을 내보내고, 깔끔한 대화 코퍼스(corpus)를 구축하며, 귀하에게 도달하기 전에 코퍼스에 대해 검증되는 LLM 분석을 실행하고, 다중 시트 XLSX 보고서(응답 시간, 실제 FAQ, 고객 아키타입, 반대 의견, 봇이 실제로 해결할 수 있는 것 — 검증이 반박한 내용을 기록하는 방법론 시트 포함)를 제공합니다.

모든 것은 귀하의 머신에서 실행됩니다. 전체 파이프라인에서 유일한 외부 트래픽은 귀하가 구성하는 LLM 제공업체로의 4단계 분석 호출뿐입니다. 그리고 llm.provider: "mock" 또는 자체 호스팅 OpenAI 호환 엔드포인트를 사용하면 그마저도 사라져 완전히 오프라인으로 실행됩니다.

Leé esto en castellano: README.es.md.

⚠️ 먼저 읽어주세요

이 프로젝트는 WhatsApp, Meta Platforms Inc. 또는 그 자회사들과 제휴, 관련, 승인, 보증 또는 어떤 방식으로든 공식적으로 연결되어 있지 않습니다. "WhatsApp" 및 "Meta"와 관련 이름, 마크 및 이미지는 해당 소유자의 상표입니다. 공식 WhatsApp 웹사이트는 https://whatsapp.com입니다.

또한 WAHA 프로젝트와도 제휴 관계가 아닙니다. 이 도구는 귀하가 운영하는 WAHA 인스턴스의 HTTP API만 소비할 뿐, WAHA(아파치-2.0 라이선스, 공식 저장소에서 얻을 수 있음)를 재배포, 번들링 또는 수정하지 않습니다.

WAHA는 비공식적인 방법으로 WhatsApp에 접근합니다. WhatsApp은 플랫폼에서 봇이나 비공식 클라이언트를 허용하지 않으며, 귀하의 계정이 차단되지 않을 것이라는 보장도 없습니다. 이 프로젝트의 관리자들은 WhatsApp 서비스 약관을 위반하는 어떠한 사용도 묵인하지 않으며, 대량 메시징, 스팸, 스토커웨어 또는 개인 감시를 명시적으로 권장하지 않습니다. 비즈니스에 중요한 통합이 필요하다면 공식 WhatsApp Business API를 고려하십시오. 의도된 사용 사례는 기업이 자체 대화 기록을 분석하는 것입니다.

개인 데이터: 채팅 기록은 제3자의 개인 데이터입니다. 이를 처리할 유효한 법적 근거를 보유하고 귀하에게 적용되는 법률(GDPR, LGPD, Ley 25.326 등)을 준수할 책임은 전적으로 귀하에게 있습니다. 처리는 귀하의 자체 인프라에서 이루어지며, 이 프로젝트는 작성자에게 아무것도 전송하지 않습니다. 유일한 외부 흐름은 분석 단계로, 코퍼스 요약본을 귀하가 구성한 LLM 제공업체로 보내는 것입니다 — 로컬 또는 mock 제공업체를 사용하면 전혀 전송되지 않습니다. 이에 따라 제공업체를 선택하십시오.

이 소프트웨어는 어떠한 종류의 보증 없이 "있는 그대로(AS IS)" 제공됩니다.

Related MCP server: Wasapi MCP Server

검증기(verifier)가 핵심인 이유

이 파이프라인은 실제 비즈니스를 위해 구축되었습니다: 11,782개의 메시지, 610개의 대화, 8개월의 기록. LLM 분석은 7개 차원에 걸쳐 60개의 발견사항을 생성했습니다. 그런 다음 각 차원은 독립적인 검증기를 거쳐 모든 인용문을 다시 찾고 모든 주장을 코퍼스에 대해 다시 집계했습니다.

검증기는 60개 발견사항 중 34개를 반박했습니다.

그럴듯하고, 잘 작성되었으며, 자신 있게 숫자를 제시한 발견사항들 — 그러나 절반 이상이 데이터와의 접촉에서 살아남지 못했습니다. 검증 단계 없이 이루어진 귀하의 비즈니스에 대한 LLM 분석은 분석이 아니라 멋진 형식을 갖춘 허구입니다. 그래서 이 프로젝트에서는:

• 모든 발견사항은 축어적 증거(thread_id + 인용문)를 인용해야 하며, 결정론적 코드 검사가 코퍼스에 존재하지 않는 인용문이 있는 발견사항을 반박합니다 — 그 판단에 모델이 개입할 수 없습니다;

• 두 번째의 독립적인 LLM 패스가 모든 빈도 주장을 다시 집계하고, 명시된 대로 성립하지 않는 것을 반박합니다;

• 스키마는 판정을 필수로 만듭니다: 검증 패스가 기록되지 않은 분석은 구조적으로 무효입니다;

• 보고서의 방법론 시트는 반박된 발견사항을 출력하므로, 누구도 나중에 잘못된 숫자를 다시 인용하지 않습니다.

두 가지 분석 렌즈: 상업적 + FATE 행동 분석

분석에는 두 가지 차원 세트가 포함되며, 둘 다 동일한 필수 검증을 받습니다:

• 상업적(7개 차원): 실제 FAQ, 응답 시간 및 운영, 고객 아키타입, 제품 및 주제, 반대 의견 및 마찰, 봇 기회, 어조 및 스타일.

• FATE 행동 분석(5개 차원, npm run analyze -- --dimensions fate): 비즈니스가 어떻게 주의를 사로잡는지(Focus), 확신을 투사하고 약속을 지키는지(Authority), 고객이 이해받는다고 느끼게 하는지(Tribe), 사양을 늘어놓는 대신 감정적 층위에 도달하는지(Emotion), 그리고 고객 상태 신호를 읽는지 — 클러스터만, 무해한 설명 우선, 개인에 대한 판정이 아닌 상태만. Chase Hughes의 The Behavior Ops Manual에 있는 FATE 모델에서 영감을 받음(원래 표현; 저자와 제휴하거나 보증하지 않음). 먼저 운영자와 인터뷰하고 business-context.json을 입력하십시오 — analysis/PLAYBOOK.md 참조.

2분 만에 시도해보기 (WhatsApp 불필요)

git clone https://github.com/Leandrozz/wa-audit && cd wa-audit
npm install
npm run demo

데모는 합성 코퍼스를 생성하고, mock WAHA 서버를 시작하고, mock LLM으로 전체 파이프라인(프로브 → 내보내기 → 코퍼스 → 검증된 분석 → 보고서)을 실행하며, 보고서를 out/demo/에 세 가지 형식 — XLSX(클라이언트 스프레드시트), HTML(공유 가능한 단일 파일) 및 DOCX(Word) — 으로 남깁니다. 키도, 네트워크도, 실제 데이터도 필요 없습니다.

실제 WhatsApp에 대해 실행하기

비즈니스 번호가 연결된 실행 중인 WAHA 인스턴스가 필요합니다 — 며칠을 소모하게 한 함정들(엔진 선택, fullSync, 디바이스 슬롯, @lid)은 docs/waha-setup.md를 참조하십시오.

cp waha.env.example waha.env        # fill in WAHA_BASE_URL + WAHA_API_KEY
# 0. read-only probe: right engine? how deep does the history go?
node --env-file=waha.env src/probe.mjs
# 2. dump the raw history (resumable)
node --env-file=waha.env src/export.mjs <session-name>
# 3. clean corpus: threads.json + messages.csv + summary.json
node --env-file=waha.env src/threads.mjs --session <session-name>
# 4. LLM analysis with mandatory verification (needs ANTHROPIC_API_KEY,
#    or any OpenAI-compatible endpoint — see Configuration)
node --env-file=waha.env src/analyze.mjs
# 5. the report, in any or all formats
node src/report-xlsx.mjs && node src/report-html.mjs && node src/report-docx.mjs

내장 엔진 대신 자체 에이전트(Claude Code, Cursor, 무엇이든)로 분석을 실행하고 싶으신가요? 그것은 일급 경로입니다: analysis/PLAYBOOK.md.

공식 API 경로 (Kapso)

번호가 Kapso를 통해 공식 WhatsApp Business Platform에서 운영되는 경우, WAHA를 완전히 건너뛰십시오 — 비공식 클라이언트도, 이 소스에 대한 ToS 면책 조항도, @lid도 필요 없습니다:

cp kapso.env.example kapso.env      # KAPSO_API_KEY + KAPSO_PHONE_NUMBER_ID
npm run export:kapso
node src/threads.mjs --session kapso --no-net

동일한 코퍼스, 동일한 검증기, 동일한 보고서. 정직한 트레이드오프 하나: 공식 플랫폼에는 소급 백필(backfill)이 없으므로, 기록은 번호가 Kapso에 연결된 이후 그곳을 통해 흐른 내용만을 포함합니다. 계정 없이 시도할 수 있는 세부 사항 및 mock 서버: docs/kapso-setup.md.

또는 Claude가 전체를 주도하게 하기 (MCP)

npm run mcp는 Claude Desktop / Claude Code / ChatGPT / Cursor를 감사 엔진으로 바꾸는 MCP 서버를 시작합니다: 에이전트가 귀하를 인터뷰하고, WAHA 설정을 안내하며, 채팅에서 바로 페어링 QR을 보여주고, 기록을 내보내고 분석을 직접 실행합니다. 서버는 구조적으로 정직함을 유지합니다 — submit_dimension은 기록된 검증 판정이 없는 차원을 거부하고, 모든 증거 인용문은 서버 측에서 코퍼스에 대해 다시 확인되며, 채팅 콘텐츠는 신뢰할 수 없는 데이터로 제공됩니다. WhatsApp 메시지를 절대 보내지 않습니다. 설정: docs/mcp-setup.md.

파이프라인

 probe ──► export ──► threads ──► analyze ──► report-xlsx
 (0)       (2)        (3)         (4)         (5)
 read-only raw dump   clean       LLM + two-  11-sheet XLSX
 sanity    JSONL,     corpus,     layer       with styles,
 check     resumable  @lid        verifier    frozen panes &
                      resolution              a methodology
                      + metrics               sheet

각 단계는 일반 로컬 파일(기본 data/wa-history/)을 읽고 쓰므로, 이전 단계를 반복하지 않고도 어떤 단계든 다시 실행할 수 있습니다 — 파싱 버그 때문에 덤프가 다시 스크래핑되지 않습니다.

구성

wa-audit.config.json을 복사하여 편집하거나, 환경 변수 오버라이드를 사용하십시오(환경 변수가 우선). 핵심 사항:

비밀값은 환경 변수로만 제공됩니다: WAHA_BASE_URL, WAHA_API_KEY (+ 4단계용 ANTHROPIC_API_KEY 또는 LLM_API_KEY). WAHA_BASE_URL은 의도적으로 기본값이 없습니다 — 잘못된 인스턴스를 가리키는 것이 가장 비용이 큰 실수이기 때문입니다.

보고서의 산문은 현재 스페인어(es-AR 프리셋)입니다; 그 아래의 데이터 계약은 영어입니다. 산문 i18n은 로드맵에 있습니다.

데이터 계약

threads.json, summary.json 및 analysis.json은 버전 관리되며(schema_version: 1) docs/data-contract.md에 문서화되어 있습니다. 분석 계약은 analysis/analysis.schema.json에 공식화되어 있습니다(npm run check:analysis): 유효한 analysis.json을 생성하는 모든 엔진 — LLM, 규칙, SQL, 사람 — 은 변경 없이 보고서에 연결됩니다.

정직한 한계

• WAHA의 대량 기록 엔드포인트는 NOWEB/GOWS 엔진에만 존재합니다; WEBJS는 채팅별 내보내기가 필요합니다(여기서는 지원되지 않음 — 프로브가 알려줍니다).

• ~3개월을 넘는 기록 깊이는 덤프 전에 noweb.store.fullSync로 세션을 생성해야 합니다(docs/waha-setup.md).

• 응답 시간 중앙값은 각 인바운드 버스트의 첫 번째 메시지에 기준을 두며, 아웃바운드 메시지는 사람과 봇을 구분하지 않습니다 — 둘 다 보고서의 방법론 시트에 명시되어 있습니다.

• 미디어에는 분석 가능한 텍스트가 없습니다(downloadMedia=false): 사진과 음성 메모는 유형화된 것으로 표시되지만 내용은 비어 있습니다.

• xlsx@0.18.5(고정됨: 스타일 후처리가 이에 의존함)에는 알려진 업스트림 권고(신뢰할 수 없는 스프레드시트에 대한 프로토타입 오염 / ReDoS)가 있습니다. 이 프로젝트는 XLSX를 쓰기만 하고 자체 출력만 다시 읽으므로 해당 벡터는 적용되지 않습니다 — 그러나 npm audit이 이를 표시할 것이며, 우리는 숨기기보다 알려드리는 것이 낫다고 생각합니다.

• XLSX 스타일링은 파일을 ZIP으로 후처리하여 작동합니다 — 의도적이고 문서화된 블랙 매직: docs/xlsx-postprocess.md.

개발

npm test                 # unit + two end-to-end lanes against goldens
node fixtures/generate.mjs   # regenerate the deterministic synthetic fixture
node test/record-golden.mjs  # re-record goldens (review the diff like a spec)

fixtures/의 모든 것은 합성적이고 가상의 것입니다. 이 저장소에는 실제 비즈니스의 실제 대화, 전화번호 또는 이름이 존재하지 않습니다.

라이선스

MIT.