用 CLI 分析 CSV 文件

---
name: analyze-csv-workflow
description: "先 profile 文件，再用 DuckDB 或 csvkit 本地查询，并把分析结果与源文件分开保存。"
---

# 分析 CSV 文件

## 适用目标

用可复现命令回答表格数据问题，并清楚说明数据质量限制。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **csvkit**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`pipx install csvkit`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。
- **DuckDB CLI**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`brew install duckdb`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
  - 安装：`brew install jq`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。

## 输入合同

- CSV 路径
- 分析问题
- 分隔符和编码假设
- 敏感字段规则

## 输出合同

- Schema profile
- 有限查询结果
- 摘要表
- 数据质量警告

## 安全工作流

1. **Profile 文件** — 检查大小、Header、推断类型、空值和小样本。
   - 输入: 源 CSV
   - 输出: Schema 与质量概览
   - 风险: `read-only`
   - 命令: `duckdb -c "describe select * from read_csv_auto('input.csv')"`
2. **执行有限分析** — 运行明确 SELECT，不 attach 或写入外部数据库。
   - 输入: 已审查 SQL 和源文件
   - 输出: CSV 或 JSON 查询结果
   - 风险: `read-only`
   - 命令: `duckdb -csv -c "select category, count(*) from read_csv_auto('input.csv') group by 1 order by 2 desc"`
3. **保存可复现摘要** — 在独立产物中记录命令、假设、行数和警告。
   - 输入: 结果和 profile
   - 输出: 分析报告
   - 风险: `local-write`

## 必须先确认

- 上传数据集
- 覆盖或重写源 CSV
- 关联敏感数据或导出行级记录

## 回滚

- 把分析输出放在独立目录
- 删除包含敏感字段的临时提取
- 若替换已有报告则从版本控制恢复

## 官方来源

- [DuckDB CLI documentation](https://duckdb.org/docs/stable/clients/cli/overview.html) — 用于核对当前命令、认证、输出和操作边界。
- [jq manual](https://jqlang.github.io/jq/manual/) — 用于核对当前命令、认证、输出和操作边界。