CSV 報告撰寫器 是做什麼的？
當任務產生一系列結果行，而您想要一份可供試算表使用的整潔 CSV，外加一個用於 PR 評論或 Telegram 摘要的 Markdown 表格時，請使用此技能——只需一份欄位定義，兩種輸出便不會產生偏差。您一次性宣告欄位（鍵名、標題、選擇性格式化器）；輔助函式會自動產出兩者，並維持穩定的欄位順序、正確的 CSV 引號跳脫以及 Markdown 的管線跳脫。無需 pandas。
何時呼叫
- 使用者說：「將結果寫入 CSV」、「匯出報告」、「為此內容製作 Markdown 表格」、「將任務輸出存成試算表」。
- 對話中的程式碼有一個
list[dict]（或物件列表），但目前只是隨意印出。
何時不應呼叫
- 數據需要真正的資料框操作——合併、分組、樞紐分析；此時請改用 pandas/polars。
- 只有單一純量結果，使用 CSV/表格過於繁瑣。
具體範例
使用者輸入：
我有一個掃描到的代幣列表，包含分數與價格。請儲存一份 CSV，同時給我一張 Markdown 表格用於 Telegram 摘要。
輸出：
# 將 assets/report.py 複製到您的專案中，然後：
from report import Column, write_csv, to_markdown
columns = [
Column("symbol", "Symbol"),
Column("score", "Score", fmt=lambda v: f"{v:.1f}"),
Column("price_usd", "Price", 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=...)；兩個寫入器都使用同一個列表，因此標題與順序保持一致。 - 保持欄位順序穩定且明確——不要依賴任意行的字典插入順序。
- 讓
fmt可呼叫物件負責呈現格式（貨幣、四捨五入）；將原始值儲存在行字典中。 - 使用
csv.writer進行正確的引號跳脫；為 Markdown 表格跳脫|與換行，以免破壞版面。 - 將缺失的鍵視為空白儲存格而非觸發錯誤，這樣部分行仍能被呈現。
參考檔案：assets/report.py。
來源
由作者在生產環境中跨多個自動化專案的使用經驗萃取而成。v1.0.0。 另請參見：[[pr-body-formatter]]、[[sqlite-state]]、[[telegram-alerter]]。
→ 使用 Trawlkit 建立完整可執行的機器人。