data-cleaner-agent

data-cleaner-agent

使用 Agent 工作流清理杂乱的 CSV。大模型会判断数据需要执行哪些清理步骤，而经过测试的 Python 函数负责实际处理。模型只规划清理步骤，绝不会接触数据值，因此不会凭空捏造或悄悄改写数据。

开箱即可离线运行（无需 API 密钥）。可以由大模型驱动，其他 AI Agent 也可以将其作为 MCP 工具调用。

清理前后对比

Full Name , Country, Signup Date, Amount Paid          full_name    country  signup_date  amount_paid
 Alice  ,Netherlands,2023-01-05,"€1.200,50"                Alice  Netherlands   2023-01-05       1200.5
Bob,nederland,05/01/2023,"$900"              ─────▶          Bob  Netherlands   2023-01-05        900.0
 Alice  ,NL,2023-01-05,"€1.200,50"                         Carol      Germany   2023-02-10       1000.0
Carol , Germany ,2023-02-10,1000                             Dan      Belgium   2023-03-01        750.0
Dan,belgie,2023/03/01,"€ 750,00"

一次处理就修正了表头、去除了空白、将三种不同的日期格式解析为 ISO 格式、把 €1.200,50 / $900 / € 750,00 转换为数字、统一了国家名称，并删除了重复的 Alice 行。

安装和运行

pip install agentic-csv-cleaner

clean-csv messy.csv cleaned.csv       # clean a file
clean-csv messy.csv                   # or just print the result

无需 API 密钥。默认规划器使用一组离线启发式规则。

原理

“Agent 工作流”其实就是由几个部分组成的软件：

   look at the data   ->   planner picks the steps   ->   run the steps   ->   report
                           (rules, or an LLM)             (tested code)

让人可以放心使用它的关键决策：

规划器决定在哪一列运行哪种工具。工具负责转换。 语言模型擅长判断（“这一列看起来像金额”），但不擅长充当可靠的计算器。因此，大模型只会从固定的操作集中选择操作。它绝不会读取某个值，再写回一个“清理后”的值；而这正是大模型清理数据时通常出错的地方。

两种规划器，同一个循环

规划器	说明	需要
RuleBasedPlanner	根据快速数据分析得出的离线启发式规则。默认规划器。	无
LLMPlanner	将分析结果和工具列表发送给大模型，并获取 JSON 计划。	pip install "agentic-csv-cleaner[llm]" + ANTHROPIC_API_KEY

两者都会返回相同格式的步骤列表，因此循环完全相同。你可以更换“大脑”，而无须改动底层流程。

日志会报告每个步骤的实际处理结果，包括无法得到干净转换结果的情况（无法解析的数字／日期、无法映射的类别），因此你可以区分干净的解析结果和看似可信的猜测。

在其他代码或 Agent 中使用

from cleaner.api import clean_csv_text

result = clean_csv_text(open("messy.csv").read())
print(result["cleaned_csv"])
print(result["steps"])

作为 MCP 工具使用（Claude Desktop）

其他 AI Agent 可以将清理器作为工具调用，从而正确清理 CSV，而不是在提示词中逐个 token 重新格式化。分为三个步骤：

1. 安装

pip install "agentic-csv-cleaner[mcp]"

2. 添加到客户端的配置中（在 macOS 上，Claude Desktop 的配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，位于 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "csv-cleaner": { "command": "python", "args": ["-m", "cleaner.mcp_server"] }
  }
}

3. 重启 Claude Desktop。 现在，Agent 可以使用 clean_csv 工具，输入 CSV 文本并获取清理后的 CSV，以及操作报告。

与其他 MCP 客户端搭配使用

同一个服务适用于任何 MCP 客户端，只是配置有所不同。命令为 python -m cleaner.mcp_server。

Cursor — ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目），支持热重载：

{ "mcpServers": { "csv-cleaner": { "command": "python", "args": ["-m", "cleaner.mcp_server"] } } }

VS Code / GitHub Copilot — .vscode/mcp.json。请注意，这里使用不同的键（servers，而非 mcpServers），并且必须指定 type。工具只能在 Copilot 的 Agent 模式下运行：

{ "servers": { "csv-cleaner": { "type": "stdio", "command": "python", "args": ["-m", "cleaner.mcp_server"] } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json（如果文件不存在，请创建）：

{ "mcpServers": { "csv-cleaner": { "command": "python", "args": ["-m", "cleaner.mcp_server"] } } }

Cline — 在 VS Code 扩展的 MCP 设置面板中添加。

了解报告

该工具不仅会返回整洁的数据，还会告诉你每个步骤的实际处理结果，包括无法得到干净结果的情况，以便你区分干净的解析结果和看似可信的猜测：

- coerce_numeric(amount): all 4 value(s) parsed cleanly
- standardize_dates(signup): 1/3 value(s) could not be parsed, set to null
- standardize_categorical(country): 1 value(s) not in the mapping, left unchanged: ['MARS']

因此，它不会悄悄丢弃某个值或保留错误的类别，而是会将问题呈现出来，让你准确知道哪些单元格需要再次检查。

包含内容

cleaner/tools.py 保存了这些转换：snake_case_headers、strip_whitespace、 coerce_numeric、standardize_dates、standardize_categorical、drop_duplicate_rows。

以 standardize_dates 为例。2023-01-05（年在前、月在中间）和 05/01/2023（日 在前）需要相反的解析规则，而全局设置会导致其中一种格式解析错误，因此该工具会针对每个 值单独判断。混合日期确实存在歧义，该工具会明确处理歧义，而不是猜测。

测试

python -m unittest discover -s tests

许可证

MIT。