五分钟快速开始¶
这一节使用仓库中已经准备好的教学文件，让你先看到结果，再学习每一项配置。
如果尚未安装，请先阅读安装 ExcelFlow。
1. 准备教学文件¶
克隆 ExcelFlow 仓库后，在项目根目录运行：
uv sync
uv run python examples/generate.py
你将使用两个文件：
examples/tutorial/01_single_sheet.xlsx 计划文件
examples/tutorial/source.xlsx 源数据文件
计划文件声明“从订单 Sheet 取出订单号、状态和金额”；源数据文件保存真实订单。
2. 校验计划¶
uv run excelflow validate --plan examples/tutorial/01_single_sheet.xlsx
成功时显示：
校验通过
校验的意义是先检查计划内部的填写规则，例如是否有且只有一个主表、字段引用的对象别名是否已声明。它不会读取或修改源数据。源 Excel 中是否真的存在相应 Sheet 和列，要到运行任务时才能确认。
3. 预览任务¶
uv run excelflow preview --plan examples/tutorial/01_single_sheet.xlsx --task lesson_01
lesson_01 是“抽取计划”中的任务ID。预览让你在执行前确认要读取哪个 Sheet、输出多少列。
本例会显示：
Pandas 执行计划: lesson_01
读取: 订单 -> o
过滤条件: 0 条
输出字段: 3 个
4. 执行抽取¶
uv run excelflow run \
--plan examples/tutorial/01_single_sheet.xlsx \
--task lesson_01 \
--source examples/tutorial/source.xlsx \
--format csv \
--output examples/tutorial/output/01_orders.csv
成功时显示：
抽取完成: 3 行 -> examples/tutorial/output/01_orders.csv
输出内容是：
order_id,status,amount
1001,paid,727.0
1002,pending,499.0
1003,paid,80.0
5. 看懂 run 命令的五个选项¶
excelflow run --plan <计划文件> --task <任务ID> --source <源数据文件> --format <输出格式> --output <输出路径>
| 选项 | 短选项 | 本例 | 为什么需要 |
|---|---|---|---|
--plan |
-p |
01_single_sheet.xlsx |
告诉工具怎样加工数据 |
--task |
-t |
lesson_01 |
一个计划里可能有多个任务，需要选一个 |
--source |
-s |
source.xlsx |
真正要处理的数据 |
--format |
-f |
csv |
可以选择 csv、jsonl 或 xlsx |
--output |
-o |
01_orders.csv |
告诉工具把结果放在哪里 |
输出格式由 --format 选项决定，不是由文件后缀猜测。为了避免误解，建议让后缀与格式一致。
6. 创建自己的模板¶
excelflow template --output extraction_plan.xlsx
打开新文件，将示例内容替换成自己的任务。第一次修改时，建议只做单 Sheet 抽取，验证成功后再增加过滤和关联。