199 lines
9.4 KiB
Markdown
199 lines
9.4 KiB
Markdown
# 工作簿操作接口
|
||
|
||
以下路径相对 xlsx skill 根目录，通过 execute_skill_script 调用。
|
||
|
||
## 下载远程工作簿
|
||
|
||
只接受 HTTPS 地址。完整保留 URL 及查询参数传给脚本，但不要在回复、日志摘要或输出文件名中复述敏感参数。
|
||
|
||
调用 `scripts/download_workbook.py`：
|
||
|
||
```text
|
||
--url 'https://example.com/report.xlsx?signature=...' --output '/usr/local/src/excel/tmp/<任务名>/source.xlsx'
|
||
```
|
||
|
||
可选参数：
|
||
|
||
- `--timeout <1-600>`：连接和读取超时秒数，默认 `60`。
|
||
- `--max-bytes <字节数>`：默认且最高 `26214400`（25 MiB），只允许设置更小的限制。
|
||
- `--overwrite`：只在目标是本次任务生成的旧缓存时使用。
|
||
|
||
`output` 扩展名必须是 `.xlsx`、`.xlsm`、`.xltx`、`.xltm`、`.xls`、`.csv` 或 `.tsv`。脚本阻止 HTTPS 重定向降级到 HTTP，流式限制大小，先写同目录临时文件，再原子发布；OOXML 会检查 ZIP 路径、成员大小、内容类型并用 `openpyxl` 打开，CSV/TSV 会拒绝二进制或网页响应。实际 OOXML 格式与 `output` 扩展名不一致时，根据错误中的实际格式更正缓存扩展名，再调用同一脚本。
|
||
|
||
成功结果包含 `path`、`size_bytes`、`format` 和 `validation`；OOXML 还包含 `sheet_count`。后续脚本只使用返回的本地 `path`，不再访问原 URL。
|
||
|
||
## 下载通用附件
|
||
|
||
需要下载作为 Excel 任务素材的图片、视频、音频、压缩包或其他文件时，调用 `scripts/download_attachment.py`：
|
||
|
||
```text
|
||
--url 'https://example.com/asset.bin?signature=...' --output '/usr/local/src/excel/tmp/<任务名>/asset.bin'
|
||
```
|
||
|
||
只接受 HTTPS 地址，`output` 可使用任意附件扩展名。可选参数只有 `--timeout <1-600>`（默认 `60`）和 `--overwrite`。附件上限固定为 25 MiB（26214400 字节），不可调高：脚本先用 HEAD 探测远端声明大小，再检查 GET 响应声明，并在流式接收时持续兜底计数；任一阶段发现超限都会返回 `ok: false` 和明确的“已拒绝下载”错误，且不会发布部分文件。
|
||
|
||
成功结果包含 `path`、实际 `size_bytes`、`declared_size_bytes`、`size_limit_bytes`、`size_probe` 和 `content_type`。本脚本不校验文件业务格式；远程 Excel/CSV/TSV 源文件仍使用 `download_workbook.py`。
|
||
|
||
## 检查工作簿
|
||
|
||
调用 `scripts/inspect_workbook.py`：
|
||
|
||
```text
|
||
--input 'source.xlsx'
|
||
```
|
||
|
||
可选参数：
|
||
|
||
- `--sheet <名称>`：选择工作表；默认活动工作表。
|
||
- `--start-row <行>`、`--start-column <列>`：读取起点，均从 `1` 开始。
|
||
- `--max-rows <1-200>`、`--max-columns <1-100>`：限制单次输出，默认 `40 × 20`。
|
||
|
||
结果同时给出公式字符串和缓存值：
|
||
|
||
- `formula`：原始公式。
|
||
- `cached_value`：Excel/LibreOffice 上次计算后保存的结果。
|
||
- `has_external_links`：为 `true` 时，编辑或重算可能破坏外部链接缓存；默认停止并向用户说明。
|
||
- `selection.has_more`、`next_row`、`next_column`：用于继续读取大表，不要一次返回整本工作簿。
|
||
|
||
CSV/TSV 只返回行数据，不存在工作表。`.xls` 必须先转换。
|
||
|
||
## 创建或编辑
|
||
|
||
调用 `scripts/apply_workbook.py`，新建时省略 `--input`，编辑时提供源文件：
|
||
|
||
```text
|
||
--output '/usr/local/src/excel/result.xlsx' --spec '<JSON对象>'
|
||
```
|
||
|
||
或：
|
||
|
||
```text
|
||
--input 'source.xlsx' --output '/usr/local/src/excel/result.xlsx' --spec-file '/usr/local/src/excel/tmp/task/operations.json'
|
||
```
|
||
|
||
目标已存在且确认是本次任务的旧产物时才传 `--overwrite`。输入含外部链接时脚本默认拒绝保存；只有用户明确接受缓存值可能丢失的风险时才传 `--allow-external-links`。`.xlsm` 必须继续输出 `.xlsm` 才能保留宏；只有用户明确同意丢弃宏时才输出 `.xlsx` 并传 `--drop-macros`。
|
||
|
||
操作说明顶层字段：
|
||
|
||
```json
|
||
{
|
||
"properties": {
|
||
"title": "销售分析",
|
||
"creator": "示例公司"
|
||
},
|
||
"calculation_mode": "auto",
|
||
"active_sheet": "汇总",
|
||
"operations": []
|
||
}
|
||
```
|
||
|
||
支持的 `operations[].type`：
|
||
|
||
| 类型 | 关键字段 |
|
||
| --- | --- |
|
||
| `add_sheet` | `name`，可选 `index` |
|
||
| `remove_sheet` | `sheet` |
|
||
| `rename_sheet` | `sheet`、`name` |
|
||
| `set_cells` | `sheet`、`cells[]` |
|
||
| `write_rows` | `sheet`、`start_cell`、`rows[][]`，可选统一 `style` |
|
||
| `append_rows` | `sheet`、`rows[][]` |
|
||
| `style_range` | `sheet`、`range`、`style` |
|
||
| `clear_range` | `sheet`、`range`，可选 `values/styles/comments/hyperlinks` |
|
||
| `insert_rows` / `delete_rows` | `sheet`、`index`、`amount` |
|
||
| `insert_columns` / `delete_columns` | `sheet`、`index`、`amount` |
|
||
| `merge_cells` / `unmerge_cells` | `sheet`、`range` |
|
||
| `set_column_widths` | `sheet`、`widths`，如 `{"A": 18, "B:D": 12}` |
|
||
| `set_row_heights` | `sheet`、`heights`，如 `{"1": 28, "2:5": 20}` |
|
||
| `auto_fit` | `sheet`、`range`，可选 `min_width/max_width`（默认 8/40）；调整列宽、换行和行高，保留完整文本 |
|
||
| `freeze_panes` | `sheet`、`cell`；传空值取消冻结 |
|
||
| `set_auto_filter` | `sheet`、`range`；传空值取消筛选 |
|
||
| `add_table` | `sheet`、`range`、`name`，可选 `style` |
|
||
| `add_chart` | `sheet`、`chart_type`、`data_range`、`anchor`；可选 `categories_range/title` |
|
||
| `add_image` | `sheet`、`path`、`anchor`；可选像素 `width/height` |
|
||
| `add_data_validation` | `sheet`、`range`、`validation_type`、`formula1` |
|
||
| `add_conditional_format` | `sheet`、`range`、`rule_type` 及对应规则参数 |
|
||
| `set_print` | `sheet`，可选 `print_area/orientation/paper_size/fit_to_width/margins` |
|
||
| `set_named_range` | `sheet`、`name`、`range` |
|
||
|
||
`set_cells.cells[]` 中每项使用：
|
||
|
||
```json
|
||
{
|
||
"cell": "B2",
|
||
"formula": "=SUM(B3:B10)",
|
||
"style": {
|
||
"font": {"name": "Arial", "size": 11, "bold": true, "color": "FFFFFF"},
|
||
"fill": {"color": "1F4E78"},
|
||
"alignment": {"horizontal": "center", "vertical": "center", "wrap_text": true},
|
||
"number_format": "#,##0.00",
|
||
"border": {
|
||
"bottom": {"style": "thin", "color": "808080"}
|
||
},
|
||
"protection": {"locked": true}
|
||
},
|
||
"comment": {"author": "AI", "text": "来源：用户提供的 2026 年预算"},
|
||
"hyperlink": "https://example.com/source"
|
||
}
|
||
```
|
||
|
||
同一单元格不能同时传 `value` 和 `formula`。`value` 中的字符串始终按文本写入，即使以 `=` 开头；公式使用明确的 `formula` 字段。`formula` 必须以 `=` 开头。`write_rows.rows[][]` 可直接传值，也可在某个位置传带 `value/formula/style/comment/hyperlink` 的对象。
|
||
|
||
## 转换文件
|
||
|
||
调用 `scripts/convert_workbook.py`：
|
||
|
||
```text
|
||
--input 'legacy.xls' --output '/usr/local/src/excel/tmp/task/source.xlsx'
|
||
```
|
||
|
||
常见用法：
|
||
|
||
- CSV/TSV → XLSX：可传 `--sheet-name <名称>`；默认所有字段按文本保留，确认可以推断数字/布尔值时才传 `--infer-types`。
|
||
- XLSX/XLSM → CSV/TSV：可传 `--sheet <名称>`；默认导出缓存结果，明确需要公式字符串时传 `--formulas`。
|
||
- Excel → PDF：输出路径使用 `.pdf`；该 PDF 仅用于预览或用户明确要求的转换，不替代工作簿交付。
|
||
- 中文旧系统文本可传 `--encoding gb18030`；默认 `utf-8-sig`。
|
||
|
||
## 公式重算
|
||
|
||
含公式的工作簿必须调用 `scripts/recalculate_workbook.py`：
|
||
|
||
```text
|
||
--input '/usr/local/src/excel/result.xlsx' --output '/usr/local/src/excel/result-recalculated.xlsx'
|
||
```
|
||
|
||
检查返回值：
|
||
|
||
- `status: success` 且 `total_errors: 0`：公式可被 LibreOffice 计算。
|
||
- `status: errors_found`：根据 `error_summary` 中的工作表、单元格和公式修复，再重算。
|
||
- `missing_cached_value_count > 0`：可能是公式结果为空字符串，也可能未正确计算；逐个抽查。
|
||
|
||
优先使用 Excel 2007 时代即可稳定重算的函数，如 `SUMIFS`、`INDEX`、`MATCH`、`IFERROR`、`SUMPRODUCT`。避免 `XLOOKUP`、`XMATCH`、`SORT`、`FILTER`、`UNIQUE`、`SEQUENCE` 等动态数组或新函数；脚本会提示但不能证明其结果完整。
|
||
|
||
## 渲染与视觉检查
|
||
|
||
调用 `scripts/render_workbook.py`：
|
||
|
||
```text
|
||
--input '/usr/local/src/excel/result-recalculated.xlsx' --output-dir '/usr/local/src/excel/tmp/task/rendered'
|
||
```
|
||
|
||
默认 150 DPI、单次最多 20 页。可传：
|
||
|
||
- `--start-page`、`--end-page`、`--max-pages`：分批渲染。
|
||
- `--dpi <72-300>`：小字或复杂图表可提高到 180–220。
|
||
- `--include-pdf`：同时保留 `workbook.pdf`。
|
||
- `--overwrite`：只覆盖本次任务旧渲染。
|
||
|
||
若 `has_more: true`，用 `next_page` 继续。通过可用的图片查看工具逐页检查返回的 PNG。
|
||
|
||
## 质量要求
|
||
|
||
- 默认使用专业字体：中文使用 `Noto Sans CJK SC` 或与原文件一致的字体，拉丁文字使用 Arial；编辑现有文件时原有规范优先。
|
||
- 表头、单位、日期、货币、百分比和负数格式必须明确；百分比按小数存储，例如 `0.15` 显示为 `15.0%`。
|
||
- 可计算结果使用公式，不把当前结果硬编码进单元格；假设值单独放在有标签的输入单元格中。
|
||
- 每个外部数据、假设和硬编码数字都用批注或邻近单元格说明来源。
|
||
- 新建供他人填写的模板要包含填写说明和一行格式示例；编辑现有文件时不要擅自插入示例行。
|
||
- 精确遵循用户指定的工作表名、表头、公式和输出格式，不擅自重构业务逻辑。
|
||
- 合并单元格只写左上角锚点；编辑 `.xlsm` 时保留宏；不要用 `data_only=True` 读取后再保存。
|
||
- 公式重算、关键值抽查和全部页面视觉检查全部通过后再交付。
|