用途
这套技能把 Apple Numbers 当作可通过脚本驱动的表格工具，用 osascript（JXA）调用 Numbers 的脚本字典来创建、读取、导出和校验表格文件。每次脚本调用自行打开所需文档、完成工作后关闭，没有常驻桥接或监听进程，唯一的门槛是 macOS 的自动化授权。资料说明其已在 macOS 27 上的 Numbers Creator Studio 15.4（bundle id com.apple.Numbers）验证。
主要能力
- 环境检查：
bash scripts/numbers.sh --check检查应用、版本、自动化权限和区域分隔符，建议首先运行。 - 构建：
python3 scripts/numbers-build.py IN.csv -o D.numbers ...从 CSV/TSV/JSON 生成新表格，支持类型化值、格式、公式、汇总行与导出。 - 读取：
python3 scripts/numbers-read.py D.numbers [--totals]输出工作表、表格、重算后的值、公式和错误单元格。 - 导出：
python3 scripts/numbers-export.py SRC... --to FMT将单个文件或文件夹（-r，镜像目录结构）导出为 xlsx、csv、pdf、numbers09。 - 校验：
python3 scripts/numbers-verify.py FILE ...对 .numbers、.xlsx 或 .csv 断言单元格值、公式、计数和无错误。 - 弹窗检测：
bash scripts/numbers.sh --dialog判断是否有模态 alert 阻塞脚本并截图。 - 清理遗留：
bash scripts/numbers.sh --close-leftovers关闭中断运行后遗留打开的文档。
所有 Python 仅用标准库，运行于系统 python3；失败时非零退出，build 与 read 的 --json 提供机器可读输出。
使用方式
构建示例：
S=scripts
python3 $S/numbers-build.py sales.csv -o sales.numbers --summary-row --export sales.xlsx
python3 $S/numbers-build.py sales.csv -o sales.numbers --sheet Sales --table Q3 \
--format "Revenue=currency" --format "C:D=number" --formula F2 "=D2-C2" --summary-row
python3 $S/numbers-build.py eu.csv -o eu.numbers --delimiter ';' --decimal , --thousands .
python3 $S/numbers-build.py more.csv -o sales.numbers --into --sheet Sales --table Q4
CSV 由脚本自行解析而非交给 Numbers 导入，避免区域分隔符导致数值误解。默认 . 为小数点、, 为千分位，分隔符自动嗅探，UTF-8（支持 BOM）。以 0 开头的编码（如 007）和 Numbers 会重新解释的内容保持文本；12% 会转为 0.12 并套用百分比格式。--summary-row [FUNC] 在每个数值列下追加 FUNC(first:last) 公式页脚行（默认 SUM，可选 AVERAGE、MIN、MAX、COUNT 等），--summary-label 指定首列文本（默认 Total）；公式以英文函数名输入并由 Numbers 重算，脚本回读结果，任何公式求值为错误则退出 1。--format 接受表头名、列字母或范围（C:D、Q1:Q2 两个表头名）或 A1 范围，格式选项包括 number、currency、percent、text、date、duration、fraction、scientific、checkbox、automatic。--formula CELL EXPR 设置任意单元格。CSV 中以 = 开头的单元格保持文本，除非加 --csv-formulas。--into 向已有文档添加表格，会就地保存该文档，建议在副本上操作；不带 --into 时已存在的输出会被拒绝，除非加 --force。JSON 输入可以是行列表（首行为表头）或对象列表（键作表头），JSON 数字保持数字、字符串不被重新解析。性能约每单元格 19 ms（每个 Apple 事件一次），1000 个单元格约 20 秒。
读取示例：
python3 $S/numbers-read.py budget.numbers
python3 $S/numbers-read.py budget.numbers --totals
python3 $S/numbers-read.py budget.numbers --table Costs --cells B7 C7
python3 $S/numbers-read.py budget.numbers --json > budget.json
--totals 按工作表/表格报告页脚行（若有，即作者汇总），否则对主体行各数值列求和，输出会说明采用哪种。公式文本以界面语言返回（如匈牙利语下为 =SZUM(B2:B9)），应比较值而非公式文本；错误单元格会被列出（如 B7 处 ERRORS），否则读作空。也可只读打开 .xlsx 和 .csv。
导出与校验示例：
python3 $S/numbers-export.py budget.numbers --to xlsx
python3 $S/numbers-export.py ~/Reports -r --to xlsx --out-dir ~/Reports-xlsx
python3 $S/numbers-export.py budget.numbers --to pdf --out /tmp/budget.pdf --pdf-quality best
python3 $S/numbers-export.py budget.numbers --to csv --flat-csv
python3 $S/numbers-export.py budget.numbers --to csv --raw-csv
python3 $S/numbers-verify.py ~/Reports-xlsx/q3.xlsx --numbers-coords --expect B14=1250 --formula B14
XLSX 每个表格一个工作表，名为 Sheet - Table（表格保持默认名时仅 Sheet），表名占第 1 行，导致地址下移一行，校验时用 --numbers-coords。公式转为带缓存值的英文数组公式（openpyxl data_only=True 可读）。本地化汇总工作表默认省略，除非 --summary-worksheet。CSV 导出使用区域列表分隔符和格式化值，多表格会生成文件夹；--flat-csv 扁平化，--raw-csv 输出逗号分隔原始值（程序读取时优先）。--password/--password-hint 适用于 XLSX、PDF、Numbers 09；已有输出默认跳过，除非 --force。
适用场景
适合在 macOS 上批量从数据文件生成 Numbers 表格、读取现有表格并汇总、转成常见格式、以及自动化校验表格内容。
限制
- 图表无法通过脚本创建或读取，
make new chart会失败，图表仅暴露位置和大小；应先在界面中添加，或用 matplotlib 渲染，或用 openpyxl 写入 XLSX。 - 模态 alert 会阻塞所有脚本调用，后续调用超时（-1712）；应请用户手动关闭，脚本不尝试点击。
- 数字格式跟随区域设置：货币符号与舍入、小数点、CSV 分隔符均受区域影响，没有脚本化的 decimal-places 设置；值保持精确，显示舍入可能隐藏小数。
- 不要打开用户正在打开的文档，以免未保存编辑冲突，脚本会拒绝。
- 原始 AppleScript 中应以 alias 打开文件、用
tell d to make new sheet创建后重命名；AppleScript 以区域小数点打印数字，需要解析值时用 JXA。
安全
脚本只写新文件，源文件打开后不保存关闭；--into 是唯一例外（保存目标文档），已有输出仅在 --force 时替换。值通过 numbers_ops.js 读取的 JSON 请求文件传入，不拼接进脚本源码。每次调用在 NUMBERS_TIMEOUT（默认 300 秒）结束；中断后用 --close-leftovers 仅关闭脚本自己打开的文档；脚本从不退出 Numbers、不关闭用户文档、不点击对话框。--password 会出现在 Python 进程参数中，传给 Numbers 时仅经私有请求文件（权限 600）并在调用后删除。
更完整的注意事项与字典参考见 references/gotchas.md、references/dictionary.md，以及 references/recipes.md。