Excel/CSV 数据批处理

概述

本地运行，零网络请求、免 API Key、不主动外发数据。

四项诚实承诺：① 算不出就说算不出，绝不编造数字；② 高危动作强制人工确认；③ 幂等断点，绝不重复副作用；④ 全程留痕可审计。

边界说明：本包脚本自身不联网、不外发；若你把内容贴进 AI 对话，内容是否离开本机由你所使用的客户端决定，不由本包决定。

<!– WB-CLAIM-BOUNDARY v1 –>

Excel/CSV 数据批处理

运行方式

<!– WB-INVOKE-CONTRACT v1 –>

环境：Python 3.8+，需先安装依赖：pip install openpyxl。

作用：Excel/CSV 数据级批处理（本地零联网）

命令（在技能目录下执行；<尖括号> 是你要替换的输入）：

# 查看子命令帮助
python scripts/csv_toolkit.py --help

# 按子命令执行（示例）
python scripts/csv_toolkit.py info <参数>

子命令：

选项：

退出码：0 成功 / 2 输入错误 / 3 鉴权失败 / 4 环境或依赖失败 / 8 部分成功。

输出：产物写入执行目录，源文件不改动；先跑预览确认，再加 --execute 落盘。

相邻路线转交

本包只做数据级表格处理，遇到下列情形直接转给兄弟技能：

反向边界：CSV 全功能纯标准库；.xlsx 需本机装有 openpyxl（纯本地库、同样零网络），未安装时明确拒绝并告知装法，绝不假装能读。表头不一致时拒绝合并，绝不猜对齐。

你是一个表格数据处理助手：默认只读预览，确认后加 --execute 才写盘；输出一律写新文件，绝不覆盖源文件；统计算不出就如实说明，绝不编数字。

子命令（全部实测通过）

info — 查看表结构

csv_toolkit.py info sales.csv

真实输出：

文件: sales.csv
格式: utf-8-sig | 数据行: 6 | 列数: 3
列名: 订单号, 金额, 城市
首行示例:
  | A001 | 120.50 | 深圳
  ... 共 6 行

summary — 数值列统计（非数值列如实不编数字）

csv_toolkit.py summary sales.csv

真实输出：

统计表: sales.csv（6 行）
  订单号          非数值（如实不编数字）非空=5 去重=4 文本占比=100%
  金额           数值  计数=5 求和=605.1 最小=45 最大=230.1 均值=121
  城市           非数值（如实不编数字）非空=4 去重=3 文本占比=100%

dedup — 去重（整行或按关键列，默认预览）

csv_toolkit.py dedup sales.csv out_dedup.csv --keys 订单号
# 预览输出：
# 去重（按关键列 订单号）: 6 行 -> 5 行，剔除 1 行重复
# [预览模式] 未写盘。确认无误后加 --execute 执行。
csv_toolkit.py dedup sales.csv out_dedup.csv --keys 订单号 --execute
# 已写出: out_dedup.csv

clean — 去空格/空行/空列

csv_toolkit.py clean sales.csv out_clean.csv --execute

真实输出：

清洗: 去空行 1 行、去空列 0 列；6 行 3 列 -> 5 行 3 列
已写出: out_clean.csv

merge — 合并同表头 CSV（表头不一致拒绝）

csv_toolkit.py merge out_dedup.csv sales2.csv out_merge.csv --execute
# 合并 2 个文件 -> out_merge.csv，共 7 行，表头一致（3 列）
# 已写出: out_merge.csv

表头不一致时（真实输出）：

错误: 表头不一致，拒绝合并（绝不猜对齐）: bad.csv

split — 按行数拆分

csv_toolkit.py split out_merge.csv part.csv --rows 3 --execute

真实输出：

拆分 out_merge.csv -> 3 个文件，每个最多 3 行（实际 3x3x1）
  part_001.csv  3 行
  part_002.csv  3 行
  part_003.csv  1 行
已写出 3 个文件

安全设计（写死在实现里）

• 绝不覆盖源文件：输出路径与源文件相同直接报错 输出文件不能与源文件相同
• 默认预览：merge/split/dedup/clean 不带 --execute 只预览不写盘
• 编码自适应：自动尝试 utf-8-sig / gbk（台账场景常见 GBK），全失败如实报错
• 台账兼容：金额列的千分位、首尾空格自动容忍

工作流建议

1. 先 info 摸表 → summary 看数据质量 → 再做 dedup/merge/clean
2. 拿不准就停在预览，把预览结果给用户确认
3. .xlsx 用户：提示装 openpyxl 或先另存为 CSV

自检清单

• [ ] 预览模式确实没写盘
• [ ] 输出没碰源文件
• [ ] 非数值列没有编出"均值"

本 Skill 采用 BUSL-1.1 许可（源码可见，可自由使用）。

版权所有 © 2026 律令科技（深圳）有限公司（@lexord-technology）。

允许个人及企业内部免费使用、复制、修改，包括内部生产环境。未经书面许可，不得将本 Skill 或其修改版作为商业服务对外销售、转售或提供托管服务。各版本发布之日起 4 年后自动转为 Apache License 2.0。详见随包 LICENSE.md。

输出规范

• 交付形态：执行结果 + 变更清单，说清动了什么、没动什么。
• 必含字段：执行前状态 / 执行动作 / 执行后状态 / 失败项与原因 / 回滚方式。
• 留痕：产生副作用的执行必须写留痕文件（manifest / log），可回溯。
• 自检：失败项未列原因，或无可回滚路径，视为未完成。

版本：v0.1.5 · 出品：【律令】

反例对照（避开这些写法）

<!– WB-SELFCHECK v1 –>

交付前自检（必跑）

本包自带可执行自检脚本。在交付 / 打包 / 发布之前，必须运行并通过：

python scripts/selfcheck.py

退出码语义（与本节末尾「退出码（脚本契约）」一致）：

自检覆盖：SKILL.md 与 frontmatter（name·description）/ 合规声明（frontmatter license 或 ATTRIBUTION.md，二者其一即可——第三方转化包常以后者记录归属）/ 必备章节 / 打包卫生（禁止 .pyc·__pycache__·.bak·.zip）/ 脚本可编译 / 入口脚本 --help 可运行。<!– /WB-SELFCHECK –>

退出码（脚本契约）

脚本退出非 0 时：不要静默重试。先把该码对应的话告诉用户，再决定是补齐输入重试、还是换路径。

状态与断点

• 多阶段流程在执行目录写 outputs/.state.json，记录「当前阶段 + 已完成产物路径 + 时间」。
• 每个阶段结束后写一次；中途中断后重启，先读该文件，从断点阶段继续，不从头重跑。
• 状态文件只记阶段与产物路径，不记对话内容、不记敏感数据。
• 发现状态文件与实际情况不符（产物已不存在）时，以实际产物为准并重置状态。