wa-audit

あなたのWhatsAppビジネス番号の商用監査。 これを WAHA インスタンスに向けると、全チャット履歴をエクスポートし、クリーンな会話コーパスを構築し、コーパスに対して検証済みのLLM分析を実行し、マルチシートのXLSXレポート（応答時間、実際のFAQ、顧客アーキタイプ、反対意見、ボットが実際に解決できること）を生成します。さらに、検証が反駁した内容を記録する方法論シートも含まれます。

すべてはあなたのマシン上で実行されます。パイプライン全体で唯一の外部送信トラフィックは、フェーズ4の分析呼び出しで、あなたが設定するLLMプロバイダーへのものだけです。さらに、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（Apache-2.0、公式リポジトリから入手可能）を再配布、バンドル、または変更するものではありません。

WAHAは非公式の方法でWhatsAppにアクセスします。WhatsAppはプラットフォーム上でのボットや非公式クライアントを許可しておらず、アカウントがブロックされないという保証はありません。このプロジェクトのメンテナーは、WhatsAppの利用規約に違反するいかなる使用も容認せず、一括メッセージング、スパム、ストーカーウェア、または人々の監視を明示的に推奨しません。ビジネスクリティカルな統合には、公式のWhatsApp Business APIを検討してください。想定されるユースケースは、企業が自社の会話履歴を分析することです。

個人データ: チャット履歴は第三者の個人データです。それを処理する有効な法的根拠を持ち、適用される法律（GDPR、LGPD、Ley 25.326など）を遵守する責任は、完全にあなたにあります。処理はあなた自身のインフラストラクチャで行われ、このプロジェクトは作成者に何も送信しません。唯一の外部フローは分析フェーズであり、コーパスのダイジェストをあなたが設定したLLMプロバイダーに送信します。ローカルまたはモックプロバイダーを使用する場合は、まったく送信されません。プロバイダーはそれに応じて選択してください。

このソフトウェアは「現状のまま」提供され、いかなる種類の保証もありません。

Related MCP server: Wasapi MCP Server

検証機能がすべての理由

このパイプラインは実際のビジネスのために構築されました：11,782メッセージ、610会話、8か月の履歴。LLM分析は7つの次元にわたって60の所見を生成しました。その後、各次元は独立した検証機能によって、すべての引用を再配置し、すべての主張をコーパスに対して再集計しました。

検証機能は60の所見のうち34を反駁しました。

もっともらしく、よく書かれ、自信を持って数字が付けられた所見—しかしその半分以上はデータとの接触に耐えられませんでした。検証パスなしのLLM分析は、分析ではなく、見た目だけのフィクションです。だからこそ、このプロジェクトでは：

• すべての所見は逐語的な証拠（thread_id + 引用）を引用しなければならず、決定的なコードチェックが、引用がコーパスに存在しない所見を反駁します—モデルはそれについて投票できません;

• 2回目の独立したLLMパスがすべての頻度主張を再集計し、記載どおりに成立しないものを反駁します;

• スキーマは評決を必須にします：記録された検証パスのない分析は、構造的に無効です;

• レポートの方法論シートは反駁された所見を印刷するため、後で悪い数字を再引用する人はいません。

2つの分析レンズ：商用 + FATE行動分析

分析には2つの次元セットが付属しており、両方とも同じ必須検証の対象です：

• 商用（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

デモは合成コーパスを生成し、モックWAHAサーバーを起動し、モックLLMを使用してパイプライン全体（プローブ→エクスポート→コーパス→検証済み分析→レポート）を実行し、レポートをout/demo/に3つの形式すべてで残します—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

同じコーパス、同じ検証機能、同じレポート。正直なトレードオフが1つ：公式プラットフォームには遡及的なバックフィルがないため、履歴は番号がそこに接続されてからKapsoを通じて流れたものをカバーします。詳細と、アカウントなしで試すためのモックサーバー：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 をコピーして編集するか、環境変数のオーバーライドを使用します（envが優先）。基本事項：

シークレットはenvのみ：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。