CSVレポートライター
このスキルは、ジョブが結果行のリストを生成し、スプレッドシート用の整形式CSVと、PRコメントやTelegramダイジェスト用のMarkdownテーブルの両方が必要な場合に使用します。単一の列定義から両方を生成するので、二つの出力がずれることはありません。列（キー、ヘッダー、オプションのフォーマッター）を一度宣言するだけで、ヘルパーが安定した列順序、適切なCSV引用符、Markdown用のパイプエスケープ処理を施した両方を出力します。pandasは不要です。
呼び出しタイミング
- ユーザーが「結果をCSVに書き出して」「レポートをエクスポートして」「これのMarkdownテーブルを作って」「実行結果をスプレッドシートとして保存して」と依頼したとき。
- 会話内のコードに
list[dict]（またはオブジェクトのリスト）があり、現在アドホックにprintしているとき。
呼び出してはいけないタイミング
- データに本当のデータフレーム処理（結合、グループ化、ピボット）が必要な場合。その場合はpandas/polarsを使用してください。
- 単一のスカラー結果の場合。CSV/テーブルは過剰です。
具体的な例
ユーザー入力：
スキャンしたトークンのリストがあり、スコアと価格が含まれています。CSVを保存し、Telegramダイジェスト用のMarkdownテーブルもください。
出力：
# assets/report.py をプロジェクトにコピーしてから:
from report import Column, write_csv, to_markdown
columns = [
Column("symbol", "シンボル"),
Column("score", "スコア", fmt=lambda v: f"{v:.1f}"),
Column("price_usd", "価格", fmt=lambda v: f"${v:,.4f}"),
]
rows = [
{"symbol": "ABC", "score": 8.4, "price_usd": 0.0123},
{"symbol": "XYZ", "score": 6.1, "price_usd": 1.5},
]
write_csv("scan.csv", columns, rows) # スキーマ定義されたCSV、安定した列順序
print(to_markdown(columns, rows)) # 同じ列でMarkdownテーブル
両方の出力はまったく同じ列をまったく同じ順序で使用するため、CSVとダイジェストテーブルは常に一致します。
適用するパターン
- 各
Column(key, header, fmt=...)を一度だけ宣言します。両方のライターが同じリストを消費するため、ヘッダーと順序が同期し続けます。 - 列の順序を安定かつ明示的に保ちます。任意の行のdict挿入順序に依存しないでください。
fmtコールバックに表示（通貨、丸め）を任せ、生の値は行のdictに保持します。- 正しい引用のために
csv.writerを使用し、Markdownテーブルでは|と改行をエスケープしてレイアウトが壊れないようにします。 - キーが欠けている場合はクラッシュせずに空セルとして扱い、部分的な行でもレポート可能にします。
参考：assets/report.py。
ソース
作者の自動化プロジェクトにおける実運用から抽出。v1.0.0。 関連項目：[[pr-body-formatter]]、[[sqlite-state]]、[[telegram-alerter]]。
→ Trawlkitで完全な実行可能ボットを構築。