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 构建完整的可运行机器人。