Excel DuckDB ETL Runner

用途

当标准表格或已规范化 Excel/CSV 数据分析可通过一个可复用的通用执行器完成，而无需编写完整定制的 Python 脚本时，请使用本技能。内置的 scripts/duckdb_etl_runner.py 既是该技能的辅助工具，也是默认可导出、供调度器使用的复用脚本。

本技能必须与前述两项技能保持一致：

• 坚持“脚本优先”的正式执行方式；
• 优先选用 DuckDB 进行数据处理与分析；
• 在正式交付物中包含可复用脚本及 script_usage.md；
• 避免将原始电子表格直接加载至 LLM 上下文；
• 保留验证逻辑、运行清单（run manifest）、字段映射（field map）、SQL 脚本及回退日志（fallback log）。

适用场景

在以下情况下使用 scripts/duckdb_etl_runner.py：

• 数据为标准表格格式，或已完成规范化；
• 分析逻辑可用 DuckDB SQL 表达；
• 各独立查询应能脱离 ETL 依赖链单独运行；
• 后续计算依赖前期 SQL 执行结果，且可借助中间 CSV 输出（注册为临时表）实现；
• 需对多个源表执行显式 SQL JOIN 或关系校验；
• 任务需具备可重复执行能力，输入与输出产物稳定；
• 用户需要一个未来可被调度执行的脚本；
• 多表关联可通过显式 SQL 及已剖析的关系结构表达。

若需自定义转换逻辑、复杂 Excel 规范化、多阶段 DataFrame 处理，或面向特定报表的输出格式，则应改用更通用的 scaffold 技能。

必需交付物

每次正式运行均须包含以下内容：

• duckdb_etl_runner.py，或其复制/适配后的等效可复用脚本；
• script_usage.md；
• request.json；
• table_profile.json；
• queries.sql；
• validation.json；
• 至少一个业务语义命名的结果产物，例如 customer_sales.xlsx、category_metrics.csv 或按查询命名的输出文件；
• run_manifest.json。

未提供可复用脚本及使用说明文档前，不得标记正式分析任务为完成。

执行器模式

优先通过配置而非重写 Python 代码实现定制：

duckdb_etl_runner.py
recipe.json       # 可选，用于记录表文件路径、SQL 脚本、引擎策略、预期输出等
query.sql         # SQL 或多语句 SQL 文件
intermediate/*.csv # 可选：中间步骤输出，将被注册为后续步骤可用的临时表
script_usage.md

执行器支持直接传入 SQL 参数、SQL 文件及 recipe 中定义的查询。这些查询路径彼此独立，即使未使用 recipe.steps 依赖链也必须持续可用。对于需重复执行的任务，推荐使用 --sql-file 或 --recipe 参数，以确保业务逻辑脱离命令行参数、实现版本化管理。

对于具有 ETL 风格依赖关系的多步骤任务，请使用 recipe.steps。每个步骤执行只读 SQL 查询，按需生成指定格式的结果，并可声明 register_as 字段，使某 CSV 输出被注册为后续步骤可引用的表名。该机制在保障执行器安全性的同时，禁止任意 DDL 操作。

处理多表数据时，若需为每张表指定工作表名（sheet name）或需更清晰的数据血缘（lineage），建议采用含 inputs.tables 字段的 recipe；对于简单 CLI 多文件运行场景，可使用 --table-files name=path,name2=path2。所有 JOIN 必须在 SQL 中显式声明，使用 ON 或 USING 子句。

结果导出文件必须采用业务语义命名。请使用 --output-name 或 recipe.outputs.name 显式指定名称。若未指定，执行器将根据单条查询/步骤的输出推导名称；对于多结果任务，则从输出目录推导。若还需生成 CSV 和 JSON 格式结果文件，请使用 --formats xlsx,csv,json 或 recipe.outputs.formats。执行元数据 JSON 文件始终采用稳定的工程命名，以支持验证与调度系统间交接。

DuckDB 优先策略

DuckDB 是默认的数据处理与 SQL 执行引擎。应将其用于表注册、JOIN、聚合、窗口函数、过滤及本地可复现计算。仅在以下情况允许回退至其他方案：

• DuckDB 不可用；
• 需先完成 Excel 加载或规范化，再注册至 DuckDB；
• 资源限制使基于 DataFrame 或分块（chunked）的路径更安全；
• 当前任务本身不具 SQL 形态（即难以用 SQL 表达）。

请在 fallback_log.json 或 validation.json 中记录回退原因。

源码参考

用户提供的 duckdb_analyzer.py 仅为参考实现，不可整份复制使用。可借鉴其中实用的设计思路：安全的标识符引号包裹（safe identifier quoting）、只读 SQL 检查、查询风险评估、压缩 JSON 输出、多表注册支持、面向 JOIN 的 SQL 编写指引，以及诊断信息载荷（diagnostic payloads）。

详见 references/runner-design.md 中的实现说明与命令示例。