技能介绍

它解决什么问题

业务团队日常维护一份本地 Excel 物流台账，单号齐全，但查验状态、货代信息等字段长期空缺。完整数据散落在飞书多 sheet 的「物流跟踪表」里（美国/加拿大/英国/德国/法国/澳洲六个国家表）。人工逐行对照回填既慢又容易错，同步之后还要手工统计各货代的查验率。这个技能把「按单号匹配 + 回填 + 统计」串成一条可重复执行的流水线。

它如何工作

核心是两个脚本加一份映射表：

scripts/download_feishu_data.py：调用 lark-cli sheets +csv-get --format json 自动发现并下载全部数据 sheet，解析返回的 annotated_csv 后合并为单个 CSV。之所以不直接用 --output，是因为该参数在 lark-cli 的 csv-get 中不被支持。
scripts/sync_logistics.py：以 --action sync 为例，先解析 CSV 构建以单号为键的查找字典，再遍历本地 Excel 中所有含单号列的 sheet，逐行匹配后把缺失字段写回对应列。
references/field_mapping.json：定义本地列名与飞书列名的映射关系，脚本自动加载；飞书表头改名时只需更新这个文件。

同步完成后默认自动生成统计：按货代名称分组，输出总票数、查验数与查验率（格式化为 XX.X%）；含国家列的「空运总表」按目的国家 + 货代双重分组。写回目标默认是原表，可用 --output 另存副本。

适用边界与注意点

写入依赖 openpyxl，运行前必须关闭目标 Excel，否则写入失败。
回填默认只填空单元格，要覆盖已有数据需显式加 --no-backfill-only。
飞书「物流跟踪表」通常同时有客户单号与订单号两列，本地单号列一般对应订单号，执行前要确认映射，必要时用 --feishu-单号-column "订单号" 指定。
统计区数据写入前会被清空，从第 2 行起写入 N-Q 列（空运总表为 N-R 列）。
所有修改直接覆盖原文件，不放心就先备份。