wa-audit

Коммерческий аудит вашего WhatsApp-номера для бизнеса. Укажите ему на WAHA — и он экспортирует всю историю переписки, строит чистый корпус диалогов, запускает LLM-анализ, который проверяется по корпусу до того, как попадёт к вам, и выдаёт многостраничный отчёт XLSX: время ответа, реальные FAQ, архетипы клиентов, возражения, что бот мог бы реально решить — с листом методологии, где зафиксировано, что проверка опровергла.

Всё выполняется на вашей машине. Единственный исходящий трафик во всём конвейере — это вызов анализа на этапе 4 к провайдеру LLM, которого вы настраиваете — и даже он исчезает при llm.provider: "mock" или самостоятельно размещённой OpenAI-совместимой конечной точке, для полностью офлайн-запуска.

Читать на испанском: README.es.md.

⚠️ Прочтите сначала

Этот проект не связан, не аффилирован, не авторизован, не одобрен и никаким образом официально не связан с WhatsApp, Meta Platforms Inc. или их дочерними компаниями. «WhatsApp» и «Meta», а также связанные названия, знаки и изображения являются товарными знаками их владельцев. Официальный сайт WhatsApp: https://whatsapp.com.

Он также не связан с проектом WAHA. Этот инструмент только использует HTTP API экземпляра WAHA, которым вы управляете; он не распространяет, не встраивает и не модифицирует WAHA (который распространяется по лицензии Apache-2.0 и доступен из официального репозитория).

WAHA использует неофициальные методы доступа к WhatsApp. WhatsApp не разрешает ботов или неофициальные клиенты на своей платформе, и нет гарантии, что ваш аккаунт не будет заблокирован. Поддерживающие этот проект не одобряют любое использование, нарушающее Условия предоставления услуг WhatsApp, и явно не рекомендуют массовые рассылки, спам, сталкерское ПО или слежку за людьми. Для критически важных бизнес-интеграций рассмотрите официальный WhatsApp Business API. Предполагаемый вариант использования — бизнес, анализирующий свою собственную историю переписки.

Персональные данные: история переписки — это персональные данные третьих лиц. Вы несёте единоличную ответственность за наличие законного основания для их обработки и за соблюдение применимого законодательства (GDPR, LGPD, Ley 25.326, …). Обработка происходит на вашей собственной инфраструктуре, и этот проект ничего не передаёт своим авторам. Единственный исходящий поток — этап анализа, который отправляет дайджест корпуса провайдеру LLM, которого вы настраиваете — никакого вообще при локальном или mock-провайдере. Выбирайте провайдера соответственно.

Это программное обеспечение предоставляется «КАК ЕСТЬ», без каких-либо гарантий.

Related MCP server: Wasapi MCP Server

Почему верификатор — это вся суть

Этот конвейер был создан для реального бизнеса: 11 782 сообщения, 610 диалогов, 8 месяцев истории. LLM-анализ выдал 60 выводов по 7 измерениям. Затем каждое измерение прошло через независимый верификатор, который заново нашёл каждую цитату и пересчитал каждое утверждение по корпусу.

Верификатор опроверг 34 из 60 выводов.

Правдоподобные, хорошо написанные, уверенно пронумерованные выводы — и более половины из них не пережили контакта с данными. LLM-анализ вашего бизнеса без этапа проверки — это не анализ; это вымысел с красивым форматированием. Вот почему в этом проекте:

• каждый вывод должен ссылаться на дословное доказательство (thread_id + цитата), и детерминированная проверка кода опровергает любой вывод, чья цитата не существует в корпусе — ни одна модель не имеет права голоса в этом;

• второй, независимый проход LLM пересчитывает каждое утверждение о частоте и опровергает то, что не подтверждается в заявленном виде;

• схема делает вердикт обязательным: анализ без зафиксированного прохода проверки недействителен по построению;

• лист методологии отчёта печатает опровергнутые выводы, чтобы никто потом не цитировал плохие цифры.

Два аналитических ракурса: коммерческий + поведенческий FATE

Анализ поставляется с двумя наборами измерений, оба подлежат одной и той же обязательной проверке:

• Коммерческий (7 измерений): реальные FAQ, время ответа и операции, архетипы клиентов, продукты и темы, возражения и трения, возможности для бота, тон и стиль.

• Поведенческий FATE (5 измерений, npm run analyze -- --dimensions fate): как бизнес захватывает внимание (Focus), транслирует уверенность и держит слово (Authority), даёт клиентам почувствовать себя понятыми (Tribe), достигает эмоционального слоя вместо вываливания спецификаций (Emotion) и считывает сигналы состояния клиента — только кластеры, сначала безобидные объяснения, состояния, а не вердикты о людях. Вдохновлено моделью FATE из книги Чейза Хьюза The Behavior Ops Manual (оригинальная формулировка; не аффилировано с автором и не одобрено им). Сначала опросите своего оператора и передайте business-context.json — см. analysis/PLAYBOOK.md.

Попробуйте за две минуты (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 с подключённым вашим бизнес-номером — см. docs/waha-setup.md о ловушках, которые стоили нам дней (выбор движка, fullSync, слоты устройств, @lid).

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)

Если номер работает на официальной платформе WhatsApp Business через Kapso, пропустите 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

Тот же корпус, тот же верификатор, те же отчёты. Один честный компромисс: на официальной платформе нет ретроактивного заполнения, поэтому история покрывает то, что прошло через Kapso с момента подключения номера там. Подробности и mock-сервер для тестирования без аккаунта: docs/kapso-setup.md.

Или позвольте Claude управлять всем (MCP)

npm run mcp запускает MCP-сервер, который превращает Claude Desktop / Claude Code / ChatGPT / Cursor в движок аудита: агент интервьюирует вас, направляет настройку 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 и отредактируйте, или используйте переопределения через env (env имеет приоритет). Основное:

Секреты только через env: WAHA_BASE_URL, WAHA_API_KEY (+ ANTHROPIC_API_KEY или LLM_API_KEY для этапа 4). WAHA_BASE_URL намеренно не имеет значения по умолчанию — указать не на тот экземпляр — дорогостоящая ошибка.

Проза отчёта в настоящее время на испанском (пресет es-AR); лежащий в основе контракт данных — на английском. Интернационализация прозы в планах.

Контракт данных

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 (зафиксирован: от него зависит постобработка стилей) имеет известное вышестоящее предупреждение (prototype pollution / 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.