alchaincyf/huashu-excel

何を解決するか

huashu-excel は、AI駆動のデータ分析における「静黙エラー」の重大な問題に対処します。標準的な方法（例：pd.read_excel()）は、マージセル、複数レベルのヘッダー、または合計行が生データと混在しているなどの構造的異常を検出できず、数学的に誤った結果が正当なように見える状態になります。このプロジェクトは、生のExcelセルから最終レポートまでデータの整合性とトレーサビリティを保証する、厳格で監査対応可能なワークフローを提供します。

動作方法

このプロジェクトは、Claude CodeやCursorなどと互換性のあるエージェント非依存の「スキル」として動作し、厳密な8ステップの標準作業手順を実装します：

1. 物理的検査：openpyxl を使って pandas に読み込む前に生のセルを検査し、構造的な「汚れ」（マージセル、ヘッダーなど）を特定します。
2. クリーニング：トレーサブルな監査ログを持つ整理された形式にデータを変換します。
3. 整合：データの理解後、ユーザーと定義やベンチマークについて明確化します。
4. 分析：統計的罠（例：シンプソンのパラドックス、架空のグループ化）をスキャンします。
5. 再検証：Excelシート自体の「合計」行をチェックサムとして使用し、計算結果の検証を行います。
6. 配信：HTML、XLSX、またはDOCX形式でレポートを生成します。
7. 視覚的検証：棒グラフの軸が0から始まっているかなど、誤解を招く要素がないかチェックします。
8. 品質管理：別エージェントを用いて生データから独立して再計算を行い、結果の正確性を検証します。

対象ユーザー

正確性が絶対に求められるプロフェッショナルなデータ分析が必要なAIエージェントやユーザー向けに設計されています。特に、人為的に入力された合計値や複雑なフォーマットを含む、現実世界のビジネススプレッドシートを扱うユーザーに適しています。

特徴

• 生セル最優先：pandas処理前に openpyxl を使って元のExcel構造を検査し、情報損失を防ぎます。
• チェックサム統合：スプレッドシート内の既存の「合計」行をノイズではなく、真実の検証ポイントとして扱います。
• 知覚的正確性：クレービン・マギルの知覚階層に基づき、チャート選択を実装（例：3カテゴリを超える場合は円グラフを拒否）。
• 強固な統計：偏ったビジネスデータに対応するため、平均ではなく五数要約（ターキーのロバスト統計）をデフォルトとしています。
• 最小限の依存：コアの検査スクリプトは openpyxl または標準ライブラリのみを必要とし、制限環境でも実行可能になります。