@dztabel/excel-kit 0.0.0-stage → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/DISTRIBUTION.md +13 -0
- package/LICENSE +45 -0
- package/README.md +74 -2
- package/SKILL.md +101 -0
- package/THIRD-PARTY-NOTICES.txt +3050 -0
- package/VALIDATION.md +39 -0
- package/bin/excel-kit.cjs +50 -0
- package/package.json +19 -4
- package/recipes/README.md +29 -0
- package/recipes/audit-and-repair/README.md +30 -0
- package/recipes/audit-and-repair/inspect.json +7 -0
- package/recipes/audit-and-repair/recipe.js +48 -0
- package/recipes/audit-and-repair/request.json +22 -0
- package/recipes/audit-and-repair/sample/clean-control.xlsx +0 -0
- package/recipes/audit-and-repair/sample/expected.json +15 -0
- package/recipes/audit-and-repair/sample/model-to-check.xlsx +0 -0
- package/recipes/edit-protected-workbook/README.md +30 -0
- package/recipes/edit-protected-workbook/prepare.json +10 -0
- package/recipes/edit-protected-workbook/recipe.js +41 -0
- package/recipes/edit-protected-workbook/request.json +14 -0
- package/recipes/fill-template/README.md +30 -0
- package/recipes/fill-template/recipe.js +46 -0
- package/recipes/fill-template/request.json +18 -0
- package/recipes/fill-template/sample/derive-template.request.json +22 -0
- package/recipes/fill-template/sample/original/LICENSE +201 -0
- package/recipes/fill-template/sample/original/cf-hyperlink-image-protection.xlsx +0 -0
- package/recipes/fill-template/sample/template.xlsx +0 -0
- package/recipes/import-clean-append/README.md +30 -0
- package/recipes/import-clean-append/prepare.json +8 -0
- package/recipes/import-clean-append/recipe.js +77 -0
- package/recipes/import-clean-append/request.json +22 -0
- package/recipes/import-clean-append/sample/incoming-1.csv +4 -0
- package/recipes/import-clean-append/sample/incoming-2.csv +3 -0
- package/recipes/import-clean-append/sample/trading-table.xlsx +0 -0
- package/recipes/inventory-media/README.md +31 -0
- package/recipes/inventory-media/prepare.json +9 -0
- package/recipes/inventory-media/recipe.js +44 -0
- package/recipes/inventory-media/request.json +7 -0
- package/recipes/inventory-media/sample/LICENSE +268 -0
- package/recipes/inventory-media/sample/NOTICE +36 -0
- package/recipes/inventory-media/sample/WithEmbeded.xlsx +0 -0
- package/recipes/inventory-media/sample/blue.png +0 -0
- package/recipes/inventory-media/sample/green.jpg +0 -0
- package/recipes/normalize-codes/README.md +30 -0
- package/recipes/normalize-codes/prepare.json +73 -0
- package/recipes/normalize-codes/recipe.js +34 -0
- package/recipes/normalize-codes/request.json +7 -0
- package/recipes/normalize-codes/sample/trading-table.xlsx +0 -0
- package/recipes/pivot-by-slicer/README.md +30 -0
- package/recipes/pivot-by-slicer/prepare.json +11 -0
- package/recipes/pivot-by-slicer/recipe.js +34 -0
- package/recipes/pivot-by-slicer/request.json +14 -0
- package/recipes/roll-forward-period/README.md +30 -0
- package/recipes/roll-forward-period/prepare.json +10 -0
- package/recipes/roll-forward-period/recipe.js +49 -0
- package/recipes/roll-forward-period/request.json +13 -0
- package/recipes/roll-forward-period/sample/budget-template.xlsx +0 -0
- package/recipes/style-matching-sheets/README.md +28 -0
- package/recipes/style-matching-sheets/recipe.js +38 -0
- package/recipes/style-matching-sheets/request.json +17 -0
- package/recipes/style-matching-sheets/sample/build-workbook.request.json +13 -0
- package/recipes/style-matching-sheets/sample/report-tables.xlsx +0 -0
- package/recipes/update-assumptions/README.md +29 -0
- package/recipes/update-assumptions/recipe.js +66 -0
- package/recipes/update-assumptions/request.json +10 -0
- package/recipes/update-assumptions/sample/build-model.request.json +12 -0
- package/recipes/update-assumptions/sample/cost-model.xlsx +0 -0
- package/recipes/update-matching-records/README.md +35 -0
- package/recipes/update-matching-records/incomplete-strict.json +33 -0
- package/recipes/update-matching-records/incomplete.json +32 -0
- package/recipes/update-matching-records/prepare-incomplete.json +21 -0
- package/recipes/update-matching-records/recipe.js +35 -0
- package/recipes/update-matching-records/request.json +29 -0
- package/recipes/update-matching-records/sample/trading-table.xlsx +0 -0
- package/reference/api.md +59 -0
- package/reference/audit.md +50 -0
- package/reference/calculation.md +82 -0
- package/reference/cost.md +61 -0
- package/reference/deliverable.md +66 -0
- package/reference/editing-and-saving.md +69 -0
- package/reference/errors.md +67 -0
- package/reference/external-links.md +35 -0
- package/reference/function-limits.md +30 -0
- package/reference/paging.md +59 -0
- package/reference/pivots.md +40 -0
- package/reference/protection.md +63 -0
- package/reference/reading.md +70 -0
- package/reference/scripts.md +74 -0
- package/reference/selection.md +43 -0
- package/reference/session-loop.md +62 -0
- package/reference/sessions.md +48 -0
- package/reference/unsupported.md +31 -0
- package/release.json +41 -0
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# 算多少
|
|
2
|
+
|
|
3
|
+
按交付要求选计算方式、读懂响应里的计算范围、各调用省略 `calculation` 时算什么、`none` 下哪些操作仍会算。三种方式各保证什么见 `SKILL.md` 第 4 条;算完之后文件里存的是什么见 [deliverable.md](deliverable.md);期限见 [cost.md](cost.md);`calculation` 对象的字段查 `help calculation.policy`。
|
|
4
|
+
|
|
5
|
+
## 三种"没算出来"
|
|
6
|
+
|
|
7
|
+
- Excel 的错误值(如 `#NUM!`)是计算所得,可以按 `IFERROR` 的规则处理。
|
|
8
|
+
- 计算不可得是程序没有本次结果,`IFERROR` 不能把它变成可信的零或别的数。
|
|
9
|
+
- 保存被拒是没有发布输出,未必是公式算不了(例如公式过长)。
|
|
10
|
+
|
|
11
|
+
先看计算状态与值的来源,再看保存结果。
|
|
12
|
+
|
|
13
|
+
## 按交付要求选方式
|
|
14
|
+
|
|
15
|
+
- 只要少数本次结果,接受其余公式没有当前值:`targets`。把写输入、算目标、读结果放在同一步。
|
|
16
|
+
- 交付件要全部公式都是当前值、下游读者不会重算却要用全部结果、要整本数值审计:`all`。算不完整就报告阻断原因。
|
|
17
|
+
- 只查公式与结构:`none`。
|
|
18
|
+
- 选 `targets` 的依据是交付范围,不是 `all` 失败之后任意缩小。目标范围内算不完整,这一步默认仍保存可得结果并列清单;顶层 `requireCompleteCalculation:true` 才按旧行为拒绝。该选项在批次、会话打开与一次性脚本顶层设默认,各分组步骤可用 true/false 覆盖;与 calculation 独立继承,不沿用前一步覆盖。
|
|
19
|
+
- `targets` 里 `s` 为 `result` 的值可以采信,但只证明所列的格及其上游,不能据此说整本已经重算。
|
|
20
|
+
|
|
21
|
+
## 范围怎么读
|
|
22
|
+
|
|
23
|
+
响应的 `calculation.scope` 有 `mode`、`targets`、`selectedFormulas`、`omittedFormulas`、`workbookComplete`。`status:"complete"` 配 `workbookComplete:false` 只表示所选范围算完了。
|
|
24
|
+
|
|
25
|
+
- 目标至多 100 个(`limits.calculationTargets`),每个是一格或一个矩形;相邻的格合并成矩形写。
|
|
26
|
+
- 带 `validate` 时校验的范围并入这次计算,动态数组也会把范围扩大;保证仍只对你列出的格成立。
|
|
27
|
+
|
|
28
|
+
## 省略时的默认与沿用
|
|
29
|
+
|
|
30
|
+
| 调用 | 省略 `calculation` 时 |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `run`、`preflight`、`audit` | `all` |
|
|
33
|
+
| 批次的步骤、`session.run`、`wb.run` | 沿用批次根、`session.open`、脚本请求上的那个;那里也没写就是 `all` |
|
|
34
|
+
| `read` 命令、`session.read`、`wb.read` | `none`,不沿用上层 |
|
|
35
|
+
| `query`、`session.query`、`wb.query` | `none`,不沿用上层;带 `ruleResults` 或 `source:"calculation"` 的 `select` 时,程序自动只算它们要用的格 |
|
|
36
|
+
|
|
37
|
+
- 步骤自己写了 `calculation`,就整个对象替换上层的:上层写的 `locale`、`characterSet`、`textSortLocale` 不带过来,要用就在这一步重写。时钟与随机种子例外,在一个批次、会话、脚本的范围内固定,各步共用。
|
|
38
|
+
- `calculation` 写了就必须带 `mode`。
|
|
39
|
+
- 命令行 `read`:`--calculate` 是 `all`;`--calculation targets` 的目标就是所读的范围。
|
|
40
|
+
|
|
41
|
+
## `none` 下仍会算的地方
|
|
42
|
+
|
|
43
|
+
`none` 只是不做最后那次重算。下面的操作自己要用当前值,会就地算所需的区域及其上游:
|
|
44
|
+
|
|
45
|
+
| 操作 | 什么时候算 | 算不出来时 |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `range.copy`,`mode:"values"` | 来源里有公式或数组 | `RANGE_CALCULATION_INCOMPLETE` |
|
|
48
|
+
| `data` 的工作表来源 | 写了 `formulaValues:"calculate"`;不写就拒绝含公式的来源 | `DATA_CALCULATION_INCOMPLETE` |
|
|
49
|
+
| `selection.edit` | 选择写了 `source:"calculation"` | `SELECTION_INCOMPLETE` |
|
|
50
|
+
| `filter.set`、`filter.reapply` | 写了 `formulaValues:"calculate"`;要用公式的值而没写,报 `FILTER_FORMULA_VALUES_REQUIRED` | `FILTER_CALCULATION_INCOMPLETE` |
|
|
51
|
+
| `range.sort`、`range.sort.reapply`、`range.deduplicate`、`range.split` | 同上;没写报 `DATA_FORMULA_VALUES_REQUIRED` | `DATA_CALCULATION_INCOMPLETE` |
|
|
52
|
+
| `pivot.create`、`pivot.set`、`pivot.refresh`、`pivot.copy`、`pivot.move` | 来源区域里有公式 | `PIVOT_CALCULATION_INCOMPLETE` |
|
|
53
|
+
| `layout.autofit` | 范围里有公式 | `AUTOFIT_CALCULATION_INCOMPLETE` |
|
|
54
|
+
|
|
55
|
+
这些值不算这一步的结果:响应顶层的 `calculation.status` 仍是 `not_requested`;同一步读来源格,得到的是 `cache`,这一步改过它的上游时是 `invalidated`(旧数,保存后没有值)。
|
|
56
|
+
|
|
57
|
+
## 时钟与随机数
|
|
58
|
+
|
|
59
|
+
`RAND`、`TODAY`、`NOW` 按请求的随机种子与时钟(`calculation.clock`)计算,不会与 Excel 的某次重算相同。
|
|
60
|
+
|
|
61
|
+
## 例
|
|
62
|
+
|
|
63
|
+
只算一个目标,读回目标之内与之外各一格:
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
cat > targets.json <<'EOF'
|
|
67
|
+
{"input":"input.xlsx","output":"targets.xlsx",
|
|
68
|
+
"operations":[{"op":"write","sheet":"Data","range":"C2","values":[[75]]}],
|
|
69
|
+
"calculation":{"mode":"targets","targets":[{"sheet":"Sheet1","range":"D2"}]},
|
|
70
|
+
"read":[{"sheet":"Sheet1","range":"D2:D3","form":"compact"}]}
|
|
71
|
+
EOF
|
|
72
|
+
./excel-kit run targets.json > targets.out.json || true
|
|
73
|
+
python3 - <<'EOF'
|
|
74
|
+
import json
|
|
75
|
+
d = json.load(open('targets.out.json'))
|
|
76
|
+
if not d['ok']:
|
|
77
|
+
raise SystemExit(f"failed: {json.dumps(d.get('error') or d.get('calculation'))}")
|
|
78
|
+
print(d['calculation']['status'], d['calculation']['scope']) # complete,而 workbookComplete 是 false
|
|
79
|
+
print(d['warnings']) # FORMULAS_WITHOUT_VALUES
|
|
80
|
+
print(d['ranges'][0]['rows']) # D2 是 result,D3 不是
|
|
81
|
+
EOF
|
|
82
|
+
```
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# 成本、期限与上限
|
|
2
|
+
|
|
3
|
+
什么贵、怎样少花、四种期限各管什么、超时之后怎样改、有哪些硬上限。计算方式怎么选见 [calculation.md](calculation.md)。
|
|
4
|
+
|
|
5
|
+
## 什么贵
|
|
6
|
+
|
|
7
|
+
- 每个写步骤都把整本写出再读回核对;每次读取、查询都重新解析整本;每条一次性命令另付进程启动与读写文件。
|
|
8
|
+
- 整本重算是最大的一项。算出的值不带到下一次调用。
|
|
9
|
+
- 唯一少解析一遍的情形:会话里连续的 `session.run`,每一步都只含写常量(字符串、数字、布尔、`null`;公式不算)的 `write` 或没有操作,不带 `validate`、原生编辑和结构变化,工作簿不含动态数组。读取、查询、`inspect`、脚本、保存与另存、失败或取消之后要重新开始,所以每步之后都保存的流程没有这项收益。不用配置,响应不变。
|
|
10
|
+
|
|
11
|
+
## 少调用、少输出、少计算
|
|
12
|
+
|
|
13
|
+
- 已知的改动放进一份 `run` 或同一步的 `operations`;核对用的读取写进这一步的 `read`。
|
|
14
|
+
- 要分支、循环或读很多区域,用一个脚本,不要多次 `run` 或多次命令行 `read`;同一个文件的多块区域放进一次查询的 `read`。
|
|
15
|
+
- 只读需要的范围,用紧凑形式;响应重定向到文件再取字段,不要整份打印;`help all` 同理。脚本只返回需要的数据,`"report":"full"` 的体积随步数线性增长。
|
|
16
|
+
- 只查公式、结构和引用用 `none`。纯格式或视图的改动可以用 `none`,但要看 `FORMULAS_WITHOUT_VALUES`。
|
|
17
|
+
- 只关心少数结果用 `targets`。有动态数组的工作簿上 `targets` 可能比 `all` 更慢、更占内存,这时用 `all` 或 `none`。
|
|
18
|
+
- 会话或多步脚本里,不需要中间结果的步骤用 `none`,交付那一步再按要求选 `targets` 或 `all`。
|
|
19
|
+
- 大模型上直接带足 `timeoutMs` 去 `run`,不要先 `preflight`。
|
|
20
|
+
|
|
21
|
+
## 四种期限
|
|
22
|
+
|
|
23
|
+
期限写在各自请求或步骤的**外层**,不写在 `calculation` 里,也不写在读取范围里。
|
|
24
|
+
|
|
25
|
+
| 写在哪里 | 管什么 | 超时 |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `run`、`preflight`、`query`、`audit`、`session.read`、`wb.read` 的 `timeoutMs`;命令行 `read` 的 `--timeout-ms` | 计算阶段;`query` 里每个 `select`、每个 `find` 另按同一个数各自计时。不是整份请求的总期限 | `CALCULATION_TIMEOUT`,`run` 不写文件;选择是 `SELECTION_TIMEOUT`,文本查找是 `TEXT_MATCH_TIMEOUT` |
|
|
28
|
+
| 批次的 `steps[i]`、`session.run`、`wb.run` 上的 `timeoutMs` | 整步:解析、编辑、计算、写出与核对 | `STEP_TIMEOUT`,这一步不生效 |
|
|
29
|
+
| 批次请求顶层的 `timeoutMs` | 整批 | `BATCH_TIMEOUT`,不发布 |
|
|
30
|
+
| 脚本的 `scriptTimeoutMs` | 整段脚本 | `SCRIPT_TIMEOUT`,整体回滚 |
|
|
31
|
+
|
|
32
|
+
- `session.open`、脚本请求顶层的 `timeoutMs` 是其中各步的默认值。`session.read`、`wb.read` 也沿用它;`session.query`、`wb.query` 不沿用,没写就是 30000。
|
|
33
|
+
- 会话没有总期限,也没有空闲超时。每步数十秒的大模型上跑长循环,脚本的整段期限可能不够:改用会话,或分成几段脚本、每段以上一段的输出为输入。
|
|
34
|
+
|
|
35
|
+
## 超时之后
|
|
36
|
+
|
|
37
|
+
错误的 `details` 写明是哪一种期限(`deadline` 为 `calculation`、`step` 或 `batch`)、这次的 `timeoutMs`、可调的上限 `maxTimeoutMs` 和该改哪个字段(`hints`),并在 `suggestions` 里给出候选。程序不会自动重试,不会替你改计算方式或期限。`suggestions` 怎么用见 [errors.md](errors.md)。
|
|
38
|
+
|
|
39
|
+
- 批次先改顶层的整批期限,再按需要改各步。
|
|
40
|
+
- "只算目标"的候选始终以"如果只需要这些格"为条件:算多少由交付要求定,不由超时定。读取范围少时候选直接给出目标;没有读取范围、超过 100 个或放不下时,要你把示例换成确实需要的目标,至多 100 项。
|
|
41
|
+
- 上限 300000 是允许的最大值,不是预计用时。已知是大模型,第一次就把 `timeoutMs` 设大。
|
|
42
|
+
- 超过上限的 `timeoutMs` 报 `INVALID_REQUEST`(命令行参数是 `INVALID_ARGUMENT`),`details.path` 指向被拒的字段。
|
|
43
|
+
- 有些超时路径不带这些提示,已经到上限时也没有调整的建议;以实际的 `details` 为准。
|
|
44
|
+
|
|
45
|
+
## 上限与大模型
|
|
46
|
+
|
|
47
|
+
数值在 `capabilities` 的 `limits`,越界即拒:
|
|
48
|
+
|
|
49
|
+
| `limits` 的键 | 管什么 | 越界时 |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| `editedCells` | 一次请求或一步编辑的格数 | `BATCH_TOO_LARGE` |
|
|
52
|
+
| `readCells` | 一个读取范围一页的格数 | `READ_TOO_LARGE`,见 [paging.md](paging.md) |
|
|
53
|
+
| `validateCells` | `validate` 每个区域的格数 | `VALIDATION_CHECK_TOO_LARGE` |
|
|
54
|
+
| `calculationTargets`、`batchSteps`、`timeoutMs`、`scriptTimeoutMs` | 计算目标个数、批次步数、两种期限的最大值 | `INVALID_REQUEST` |
|
|
55
|
+
| `scriptSteps` | 一段脚本里 `wb.run` 的次数 | `SCRIPT_STEP_LIMIT` |
|
|
56
|
+
| `scriptBytes`、`scriptArgumentsBytes` | 脚本文本、`arguments` 的字节数 | `SCRIPT_TOO_LARGE`、`SCRIPT_ARGUMENTS_TOO_LARGE` |
|
|
57
|
+
| `scriptLogEntries`、`scriptLogBytes` | 脚本日志的条数与总量 | 不报错,`logsTruncated:true` |
|
|
58
|
+
|
|
59
|
+
`defaultTimeoutMs`、`defaultScriptTimeoutMs` 是两种期限没写时的值。
|
|
60
|
+
|
|
61
|
+
约百万公式级的整本计算可能超过期限的上限;性能不保证任意工作簿都能在固定预算内算完。
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# 交付件
|
|
2
|
+
|
|
3
|
+
保存之后怎样核对、文件里每个公式存的是什么、要打开时重算该怎么办。选哪种计算方式见 [calculation.md](calculation.md)。
|
|
4
|
+
|
|
5
|
+
## 核对交付件
|
|
6
|
+
|
|
7
|
+
1. 响应:`ok`、`output.saved`、`calculation.status`,逐项看 `warnings`。脚本另看 `script.stepFailures`。
|
|
8
|
+
2. `fileVerification` 说的是写出的文件与内存一致(`source:"serialized_in_memory"`);数值与 Excel 是否一致不在核对之内,`numericalVerification.status` 恒为 `not_performed`。
|
|
9
|
+
3. `output.version` 是写出文件的 SHA-256。会话里它与会话版本相等,就确认了写出的内容,不必重新打开。
|
|
10
|
+
4. 结构性结果(工作表次序、可见性、保护、名称)对交付件 `inspect` 或 `query`。
|
|
11
|
+
5. 关键数值用紧凑读取,确认 `s` 是 `result`。对交付件不计算地读,读到的是存值(`cache`);要当前值就让这次读取计算。
|
|
12
|
+
6. 要证明"其他内容没变",用同一份读取请求(`none`、紧凑形式)分别读原件和交付件,在本地逐格比较,只比任务可能影响到的区域。
|
|
13
|
+
|
|
14
|
+
## 一步之后,每个公式存的是什么
|
|
15
|
+
|
|
16
|
+
| 这个公式 | 文件里 | 下一次不计算的读取 |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| 这一步算了 | 当前值 | `cache` |
|
|
19
|
+
| 没算,也没受这次修改影响 | 原来的存值 | `cache` |
|
|
20
|
+
| 没算,受了影响的普通公式 | 没有值 | `unavailable` |
|
|
21
|
+
| 受了影响的模拟运算表 | 旧的存值原样留着 | `cache`,看不出已经失效 |
|
|
22
|
+
|
|
23
|
+
## 哪些公式保留存值
|
|
24
|
+
|
|
25
|
+
不在本次计算范围内的公式,没受影响的保留存值。保留下来的是上次的结果,不是本次的;要本次结果仍须计算。
|
|
26
|
+
|
|
27
|
+
- 只新增工作表(可以同时移动、隐藏工作表)时,绑定没有变化的公式及其下游保留存值。照旧作废的:引用了新表名的公式;依赖表数或表序的公式;动态引用;绑定不明的引用(例如保留下来的三维引用)及其下游。
|
|
28
|
+
- 复制、删除、改名工作表与插删行列,保守作废。
|
|
29
|
+
- 只引用外部工作簿固定地址的公式,在与它无关的本地编辑之后保留存值;同一公式若还引用了被改的本地格,照常作废。
|
|
30
|
+
- 动态引用、绑定不明与结构变化会保守地扩大作废范围:不能凭静态的依赖查询断言别的存值都没受影响。
|
|
31
|
+
|
|
32
|
+
## `FORMULAS_WITHOUT_VALUES`
|
|
33
|
+
|
|
34
|
+
发布的文件里有公式没有值时,`warnings` 里有这一项,附数量与示例位置;每步的报告另有 `uncachedFormulas`。原因是编辑作废了存值而本次没有算到/算不出,或输入文件里本来就没有值;用 `targets` 或 `none` 编辑之后常见。
|
|
35
|
+
|
|
36
|
+
- 它只数没有值的公式。保留着存值的公式不触发它,所以没有这条警告不等于都是本次结果,仍要读回看来源 `s`。
|
|
37
|
+
- 处理:工作簿能整本算,就改用 `all` 重新生成;不能,就把需要显示值的区域纳入 `targets`,仍须检查不可得清单,其余在报告里说明。
|
|
38
|
+
|
|
39
|
+
## 模拟运算表
|
|
40
|
+
|
|
41
|
+
- 程序原样保留模拟运算表,不计算它。表内的结果与依赖它的本次结果不可得,默认 all 仍保存其他可靠结果。
|
|
42
|
+
- 改了它的输入:它的存值已经失效,但仍留在文件里,不计入上面的警告;下一次读取里标成 `cache`。不要把它当作当前值报告,告诉用户运算表要在 Excel 里重算。
|
|
43
|
+
- 这时工作簿存的计算方式若是自动(或没有声明),程序替你设 `fullCalcOnLoad`;若是手动或 `autoNoTable`,运算表本身不触发该标志(普通公式缺值仍可能触发),响应的 `cacheInvalidation.dataTables[i].consumerRecalculation` 是 `manual_required`。
|
|
44
|
+
|
|
45
|
+
## 打开时重算
|
|
46
|
+
|
|
47
|
+
普通公式不带值地保存时,程序在 auto/autoNoTable 自动设 fullCalcOnLoad:true,覆盖原来的 false/缺省;manual 不改并给 MANUAL_RECALCULATION_REQUIRED。该标志只是请求,不保证消费者支持未知函数或能取得外部材料。可显式选择消费者计算方式:
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{"op":"workbook.settings","calculation":{"mode":"auto","fullCalcOnLoad":true}}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- 这是一个操作,写进 `operations`。它里面的 `calculation` 是存进文件的设置,与这一步算不算无关。之后的保存保留这项设置。
|
|
54
|
+
- 没有普通公式缺值时保留原设置;手动模式即使已经为 true 仍提示人工重算。autoNoTable 的运算表仍须人工重算,与普通公式的自动重算请求并存。
|
|
55
|
+
- 查它现在是什么:`query` 的 `"workbookSettings":true`,看 `workbookSettings.calculation.values`。
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
## 完整不可得清单与同次保存证据
|
|
59
|
+
|
|
60
|
+
`run` 的 `calculation.unavailable` 给 `count/formulaCount/byReason/examples(≤10)/stepId/report`;计算不可得与保存缺值是两项不同统计,多个原因的计数也不能相加当格数。报告 `{path,sha256,records}` 指向本次发布的独立 JSONL 文件;批次提交、session.save、一次性脚本在顶层 `calculationReport` 给聚合文件。会话步骤只给统计与 stepId,清单先留在内存;预检不写报告文件。
|
|
61
|
+
|
|
62
|
+
文件第一行是头:schemaVersion、最终输出版本、各步骤 inputVersion/outputVersion、计算条件及摘要、不可得格数 count、压缩记录数 records、recordsSha256 与同次保存核验。之后每行是一条区域记录,带 stepId/sheetId/sheet/range/count/reasons/owner/savedValue。每步按表序、行、列排列,同原因/同保存状态/同所有者的横向连续格压成一段,不跨空隙。
|
|
63
|
+
|
|
64
|
+
先核对文件的 SHA-256 与响应一致,再从第二行开始按行分批读取(例如每 1000 行一页);保留每行原始 UTF-8 字节及换行。按 stepId 分组核对记录条数 records、展开格数 count 与原始记录行的 SHA-256(recordsSha256),并检查区域无重叠。这样取完整份清单,不需调用 query 或重新计算。发布文件与报告应一起保留;报告本身存在不能证明工作簿已经发布,仍看 output.saved/version 与批次 publication。
|
|
65
|
+
|
|
66
|
+
`fileVerification.calculation` 给本次 computedFormulas/computedResults、missingFormulas/missingResults、historicalResults、computedSha256 和 outputVersion;computedSha256 是表序/行/列顺序的 `[sheetId,cell,type,value]` JSON UTF-8 行摘要(每行末尾 LF)。保存核验逐格确认写出值与本次模型一致;这不等于与 Excel 真值一致。不可把保留的 historical 值当本次计算结果,也不能用后一次 query 或 Excel 重算替代同次保存依据。
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# 编辑与保存
|
|
2
|
+
|
|
3
|
+
一份请求怎样组合、输出文件怎样覆盖、`preflight` 与 `batch` 各保证什么、写入锁。事务的规则见 `SKILL.md` 第 1、2 条;请求外壳的字段查 `help run.request`,每个操作查 `help <操作名>`,批次查 `help batch`;保存之后怎样核对见 [deliverable.md](deliverable.md)。
|
|
4
|
+
|
|
5
|
+
## 请求怎样组合
|
|
6
|
+
|
|
7
|
+
- `operations` 按顺序执行,后一个看到前一个的结果。互相依赖的修改必须放在同一步,否则中间状态过不了计算或校验:同时修多个循环引用、向带筛选的 Table 追加后重新应用筛选、改透视来源后刷新透视。
|
|
8
|
+
- 公式写成 `{"formula":"=B2*1.1"}`;以 `=` 开头的普通字符串仍是文本。Table 的当前行引用写 `[@列]`。
|
|
9
|
+
- 步骤有两种写法。完整的:`{"operations":[…],"nativeEdits":[…],"read":[…],"validate":[…],"calculation":{…},"timeoutMs":…}`。简写:只在批次的步骤、`session.run`、`wb.run` 里,可以把单个操作 `{"op":…}` 直接当一步;用了简写就不能在旁边写 `calculation`、`read` 这些步骤字段,要它们就换成完整写法。一次性 `run` 只有完整写法。
|
|
10
|
+
- `workbook.settings` 操作自己的 `calculation` 是存进文件的 Excel 设置,写在这个操作里面;它不是这一步的计算方式。
|
|
11
|
+
- `validate` 让工作簿自己的数据验证规则判定:不通过,这一步失败、不留下任何修改。规则程序求不了值时也失败:这时去掉 `validate`,用 `query` 的 `rules` 读出规则自己核对,并在报告里说明。它不能与 `"mode":"none"` 同用。
|
|
12
|
+
- 不保留原工作簿、只要新表时用 `create` 代替 `input`,例如 `"create":{"sheets":["Data"]}`。
|
|
13
|
+
|
|
14
|
+
## 输出、覆盖与版本
|
|
15
|
+
|
|
16
|
+
- 输出目录要先存在,程序不创建目录。
|
|
17
|
+
- `output` 已存在报 `OUTPUT_EXISTS`,`details.currentVersion` 是现有文件的版本;确认覆盖就在请求外层写 `"overwrite":{"expectedVersion":"<版本>"}`。原地修改(`input` 与 `output` 是同一个文件)也要写。
|
|
18
|
+
- 版本是文件的 SHA-256,取自 `inspect` 的 `workbook.version`、读取与查询的 `workbookVersion`、上一步的 `output.version`。`expectedInputVersion` 让输入不是这个版本时拒绝执行。
|
|
19
|
+
- 发布前会再核对一次:输入在执行期间变了报 `SOURCE_CHANGED`,目标变了报 `TARGET_CHANGED`。
|
|
20
|
+
- 扩展名要与工作簿类型一致,否则 `WORKBOOK_FORMAT_MISMATCH`:`.xlsm` 仍存为 `.xlsm`,改扩展名不等于转换格式或去掉宏。
|
|
21
|
+
- 新增或改写的公式换成原生存储形式后超过 8192 字符,报 `FORMULA_TOO_LONG`、不发布;只数请求里的字符可能不够。原样保留的公式不受影响。
|
|
22
|
+
|
|
23
|
+
## `preflight`
|
|
24
|
+
|
|
25
|
+
把同一份 `run` 请求在内存里完整做一遍:解析、操作、所请求的计算、写出、读回核对,带 `read` 时返回这次计算的值。它只差最后的写文件,所以与 `run` 一样贵:大模型上不要先 `preflight` 再 `run`,`run` 失败本来就不写文件。
|
|
26
|
+
|
|
27
|
+
| | |
|
|
28
|
+
|---|---|
|
|
29
|
+
| 查 | 输出的扩展名与目录(`INVALID_OUTPUT`、`OUTPUT_UNAVAILABLE`);`output` 已存在而没给版本(`OUTPUT_EXISTS`)、版本不对(`TARGET_CHANGED`) |
|
|
30
|
+
| 不查 | 目录能不能写;不占写入锁,不留任何文件 |
|
|
31
|
+
| 不保证 | 之后没人改输入与输出:`run` 时重新核对 |
|
|
32
|
+
| 给 | `executionRequest`:原请求加上输入的版本、外部来源的版本、这次用的时钟、随机种子与区域设置。里面没有"选择命中了哪些对象",重放时起作用的仍是你写的 `expectedMatches` |
|
|
33
|
+
|
|
34
|
+
## 批次的结局
|
|
35
|
+
|
|
36
|
+
| 情形 | `ok` | `status` | `output.saved` | 顶层 `error` |
|
|
37
|
+
|---|---|---|---|---|
|
|
38
|
+
| 全部成功 | `true` | `completed` | `true` | 无 |
|
|
39
|
+
| 有步骤没成功:`commit:"atomic"`(默认),或 `successful` 而一步都没成功 | `false` | `failed` | `false` | 无 |
|
|
40
|
+
| 有步骤没成功,`commit:"successful"` 且至少一步成功 | `false` | `partial` | `true` | 无 |
|
|
41
|
+
| 被中止:取消、整批超时、内部错误、发布前版本变了、写文件失败 | `false` | `aborted` | `false` | 有 |
|
|
42
|
+
| 解析、检查输出目标或读入输入时就失败 | `false` | 没有 `batch` | | 有 |
|
|
43
|
+
|
|
44
|
+
部分发布时响应带 `continuationRequest`:只含没发布的步骤,绑定到已保存的版本。它们将在已保存的最终状态上执行,位置不会自动换算;先改对再发。`"preflight":true` 的批次不写文件。
|
|
45
|
+
|
|
46
|
+
## 写入锁
|
|
47
|
+
|
|
48
|
+
写入时程序持有目标文件的锁,并在输出旁留下 `.excel-kit-*.lock.guard.sqlite`。它不影响工作簿,不是死锁,也不是交付物;不要为了"解锁"删它。交付前要清理,先确认没有 excel-kit 进程在写这个目录,下次写入会重建。`FILE_BUSY` 是另一个写入者持有锁,或遗留的锁记录无法安全确认:看 `details` 的原因与恢复提示。确有写入者时等它结束;是遗留的锁记录时等待不一定解决,按提示处理。锁记录与 guard 是两种文件。
|
|
49
|
+
|
|
50
|
+
## 例:被拒之后带上版本重试
|
|
51
|
+
|
|
52
|
+
失败的响应只有 `ok` 与 `error`,修正要用的值在 `error.details` 里:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
cat > inplace.json <<'EOF'
|
|
56
|
+
{"input":"input.xlsx","output":"input.xlsx",
|
|
57
|
+
"operations":[{"op":"write","sheet":"Sheet1","range":"B2","values":[[1200]]}]}
|
|
58
|
+
EOF
|
|
59
|
+
./excel-kit run inplace.json > refused.json || true
|
|
60
|
+
python3 - <<'EOF'
|
|
61
|
+
import json
|
|
62
|
+
refused, request = json.load(open('refused.json')), json.load(open('inplace.json'))
|
|
63
|
+
if refused['ok'] or refused['error']['code'] != 'OUTPUT_EXISTS':
|
|
64
|
+
raise SystemExit(f"unexpected: {json.dumps(refused.get('error'))}")
|
|
65
|
+
request['overwrite'] = {'expectedVersion': refused['error']['details']['currentVersion']}
|
|
66
|
+
json.dump(request, open('inplace.json', 'w'))
|
|
67
|
+
EOF
|
|
68
|
+
./excel-kit run inplace.json > inplace.out.json
|
|
69
|
+
```
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# 错误码
|
|
2
|
+
|
|
3
|
+
先按 `SKILL.md` 第 5 条判失败。表里没有的码,先看响应自己的 `error.message` 与 `error.details`,再用 `help find <词>` 找相关的帮助。文件名都在 `reference/` 下。
|
|
4
|
+
|
|
5
|
+
## `details.suggestions` 的读法
|
|
6
|
+
|
|
7
|
+
超时与读取超限的错误在 `details.suggestions` 里给出候选的改法,`details.hints` 写明字段该放在哪里。
|
|
8
|
+
|
|
9
|
+
- 每项有 `path`(改哪里)和 `condition`(适用条件与操作顺序),另有 `set`(要设置或替换的小对象)或 `request`(可以独立发送的只读请求)。
|
|
10
|
+
- **不要把 `set` 当作整份请求发出去**:按 `path` 改对应的层级,保留其余的输入、编辑、版本、输出与计算环境。
|
|
11
|
+
- 简写的步骤先把原操作包成 `operations:[原操作]`(原生编辑是 `nativeEdits`);旧式查询先删 `calculate` 再设 `calculation`。
|
|
12
|
+
- 每项至多 1024 字符,合计至多 4096;缩减或省略时 `details.suggestionsTruncated:true`。候选不回显编辑的数据、公式或脚本文本,也不是可以盲目执行的恢复计划。
|
|
13
|
+
- 脚本里:`strict` 下在 `error.details.cause.details`,否则在 `error.details.lastCallFailure.details`;其余详情过大被省去时有 `detailsOmitted:true`。
|
|
14
|
+
|
|
15
|
+
## 请求与读取
|
|
16
|
+
|
|
17
|
+
| 码 | 是什么 | 怎么办 |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `INVALID_REQUEST` | 请求结构不对,或字段放错了位置 | `details.path` 指出出错的对象;有 `details.hints` 就照它写明的位置改。单个操作 `{op:…}` 旁边写了 `calculation`、`read` 时,把操作放进 `operations` |
|
|
20
|
+
| `UNKNOWN_HELP_TOPIC` | `help` 的名字不对 | 从 `details.suggestions` 里挑一个,或 `help find <词>` |
|
|
21
|
+
| `READ_TOO_LARGE` | 一个范围这一页超过上限 | `paging.md` |
|
|
22
|
+
| `VERSION_REQUIRED` | 续页没带版本,或会话、脚本里没有登记过的续页 | 同上 |
|
|
23
|
+
| `SOURCE_CHANGED` | 续页之前有过成功的步骤;或输入文件在读入之后被改了 | 续页:从偏移 0 重读。输入被改:重新打开重做 |
|
|
24
|
+
| `CALCULATION_INCOMPLETE` | 默认是计算不完整的警告,仍发布;`requireCompleteCalculation:true` 时是拒绝发布的错误。`strict` 脚本里算不完整的读取仍以它抛出 | 看 `details` 的诊断,`audit.md` |
|
|
25
|
+
|
|
26
|
+
## 计算
|
|
27
|
+
|
|
28
|
+
| 码 | 是什么 | 怎么办 |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| `UNSUPPORTED_FUNCTION` | 函数没有计算入口,或是 VBA 自定义函数、Excel 4 宏表函数 | `help fn.<函数名>`;`unsupported.md` |
|
|
31
|
+
| `EXTERNAL_REFERENCE` | 依赖外部工作簿 | `external-links.md` |
|
|
32
|
+
| `CIRCULAR_REFERENCE` | 真实循环;不支持迭代计算 | 报告,或按业务改公式,多个循环在同一步里改 |
|
|
33
|
+
| `UNSUPPORTED_UNION_REFERENCE` | 联合多区域引用用在了不支持的位置 | 该公式不可得,报告 |
|
|
34
|
+
| `ARRAY_MODE_REQUIRED` | 公式的数组模式不受支持;Excel 去掉显式交集后保存的旧式公式也会触发 | `function-limits.md`;存值不能代替本次结果 |
|
|
35
|
+
| `PIVOT_REFRESH_REQUIRED` | 透视的来源变了,却没有在同一步刷新 | 改来源的同一步里 `pivot.refresh`,`pivots.md` |
|
|
36
|
+
| `PIVOT_RESULT_UNAVAILABLE` | 公式引用的透视缓存设了打开时刷新,或同一步里刷新过、之后来源又变了;或另一张透视以未刷新的透视结果为来源 | 在同一步刷新该透视,用该步自带的 `read` 读;打开时刷新的透视请用户在 Excel 里刷新,`pivots.md` |
|
|
37
|
+
| `PIVOT_NOT_REFRESHED` | 只保留、不支持编辑的透视,来源变了 | 不当作本次结果;请用户在 Excel 里刷新 |
|
|
38
|
+
| `CALCULATION_TIMEOUT`、`STEP_TIMEOUT`、`BATCH_TIMEOUT` | 计算、整步、整批超过期限 | `cost.md` |
|
|
39
|
+
| `…_CALCULATION_INCOMPLETE`(`RANGE`、`DATA`、`FILTER`、`PIVOT`、`AUTOFIT`)、`…_FORMULA_VALUES_REQUIRED`(`FILTER`、`DATA`) | 操作自己要用的当前值算不出来;或要用公式的值而没写 `formulaValues:"calculate"` | `calculation.md` |
|
|
40
|
+
| `RULE_CALCULATION_REQUIRED`、`SELECTION_CALCULATION_REQUIRED` | 要当前值的校验、规则结果或选择,配了 `"mode":"none"` | 去掉 `none` |
|
|
41
|
+
| `FORMULAS_WITHOUT_VALUES`(警告) | 发布的文件里有公式没有值;与计算不可得数量不同 | `deliverable.md` |
|
|
42
|
+
| `MANUAL_RECALCULATION_REQUIRED`(警告) | 手动模式缺值公式,或手动/autoNoTable 的失效模拟运算表须人工重算 | `deliverable.md` |
|
|
43
|
+
|
|
44
|
+
## 编辑与保存
|
|
45
|
+
|
|
46
|
+
| 码 | 是什么 | 怎么办 |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| `OUTPUT_EXISTS`、`TARGET_CHANGED` | 目标已存在,或在读入之后被改了 | 换输出名;确认覆盖就把 `details.currentVersion` 填进 `overwrite.expectedVersion` |
|
|
49
|
+
| `INVALID_OUTPUT`、`OUTPUT_UNAVAILABLE` | 输出的扩展名不对;输出目录不存在或路径不可用 | 前者改扩展名;后者先建目录,或按 `details` 改路径 |
|
|
50
|
+
| `WORKBOOK_FORMAT_MISMATCH` | 扩展名与工作簿类型不符 | `.xlsm` 仍存为 `.xlsm` |
|
|
51
|
+
| `FORMULA_TOO_LONG` | 写入的公式换成原生存储形式后超过 8192 字符 | 缩短实际写入的公式;`editing-and-saving.md` |
|
|
52
|
+
| `FILE_BUSY`、`LOCK_UNAVAILABLE` | 另一个写入者持有锁,或遗留的锁记录无法确认;取不到锁(如目录不可写) | 看 `details`;不要为了解锁删 guard 文件 |
|
|
53
|
+
| `FILE_IDENTITY_MISMATCH` | 含 `CELL` 公式的会话另存到别的文件名 | `sessions.md` |
|
|
54
|
+
| `SELECTION_COUNT_MISMATCH`、`SELECTION_INCOMPLETE` | 命中个数与 `expectedMatches` 不符;条件判不出 | `selection.md` |
|
|
55
|
+
| `EXTERNAL_LINK_IN_USE`、`EXTERNAL_LINK_RENUMBERING` | 外部链接还在用,或删除会改变别的链接的序号 | `external-links.md` |
|
|
56
|
+
| `NO_CHANGES` | 不是错误:`session.save` 成功响应里的 `status`,没有写文件 | `sessions.md` |
|
|
57
|
+
| `SESSION_EXISTS` | 会话 id 已被占用 | 换一个 `sessionId` |
|
|
58
|
+
| `CANCELLED` | 请求被取消 | 这一步不改状态;脚本整体回滚 |
|
|
59
|
+
|
|
60
|
+
## 脚本与会话
|
|
61
|
+
|
|
62
|
+
| 码 | 是什么 | 怎么办 |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| `SCRIPT_FAILED` | 脚本抛错、有语法错误或线程退出,整体回滚 | 原错误在 `error.details.cause`(`strict`)或 `error.details.lastCallFailure`,不是每次都有;`scripts.md` |
|
|
65
|
+
| `SCRIPT_TIMEOUT`、`SCRIPT_STEP_LIMIT`、`SCRIPT_RESULT_NOT_SERIALIZABLE` | 整段超时;`wb.run` 次数超限;返回值不能序列化。都整体回滚 | 同上 |
|
|
66
|
+
|
|
67
|
+
会话应答顶层的 `error`(`-32700` 等)只表示协议问题,不在 `result.response` 里;各码的含义见 `api.md`。
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# 外部工作簿引用与外部链接
|
|
2
|
+
|
|
3
|
+
公式引用别的工作簿时程序怎样处理、怎样向用户说明、怎样删除不再使用的外部链接。参数查 `help externalLink.delete`。
|
|
4
|
+
|
|
5
|
+
## 程序怎样处理外部引用
|
|
6
|
+
|
|
7
|
+
- 依赖外部工作簿的公式报告 `EXTERNAL_REFERENCE`,并列出文件里存储的来源。
|
|
8
|
+
- 程序不读取外部文件,也不把文件里存的外部缓存值当作本次输入,所以依赖它的本次结果不可得;`all` 默认仍发布其他可靠结果,并列出不可得位置。显式 `requireCompleteCalculation:true` 才拒绝。
|
|
9
|
+
- 程序不改写外部引用。
|
|
10
|
+
- 只引用外部工作簿固定地址的公式,在与它无关的本地编辑之后保留文件里的存值(读取时标 `cache`),不是本次结果;规则见 [deliverable.md](deliverable.md)。
|
|
11
|
+
|
|
12
|
+
`inspect` 的 `workbook.externalLinks` 列出工作簿里的外部链接。
|
|
13
|
+
|
|
14
|
+
## 怎么办
|
|
15
|
+
|
|
16
|
+
- 向用户说明依赖哪些外部来源。
|
|
17
|
+
- 只对不依赖外部来源的结果用 `targets` 计算(见 [calculation.md](calculation.md)),交付件里其余公式没有值或只有历史保存值的,在报告里说明。
|
|
18
|
+
- 需要这些值时,请用户提供把外部链接转成值的版本;或按用户要求把公式改为引用本工作簿。
|
|
19
|
+
|
|
20
|
+
## 删除不再使用的外部链接
|
|
21
|
+
|
|
22
|
+
公式都改完、某个外部链接已经没有任何使用时,用 `externalLink.delete` 删除它:参数是 `index`,可选 `target`,对照 `inspect` 的 `workbook.externalLinks` 取值。登记、关系、部件与内容类型一并删除。
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{ "op": "externalLink.delete", "index": 1 }
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
(片段:只示意操作的形状,它和其他操作一样写进请求的 `operations` 数组。)
|
|
29
|
+
|
|
30
|
+
删不掉时:
|
|
31
|
+
|
|
32
|
+
- 链接仍被单元格公式、名称、条件格式、数据验证、Table 列公式、图表公式、形状或表单控件的单元格链接使用时,报 `EXTERNAL_LINK_IN_USE`,并列出使用处。先按细节把使用处改掉,再删除。
|
|
33
|
+
- 删除会让后面仍在使用的链接改变序号时,报 `EXTERNAL_LINK_RENUMBERING`。换一个删除次序。
|
|
34
|
+
- 无法按 XML 解析的旧式 VML 绘图部件里,任何 `[n]`(包括注释和普通文字里的)都算作使用,这时可能保守地拒绝删除。
|
|
35
|
+
- 仍删不掉的,请用户在 Excel 里断开链接。
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 函数的限制与 Excel 的已知差异
|
|
2
|
+
|
|
3
|
+
函数层面哪些写法会报告不可得、哪些结果与 Excel 仍可能不同。一个函数是否受支持查 `help fn.<函数名>`;整类不支持的情形见 [unsupported.md](unsupported.md)。
|
|
4
|
+
|
|
5
|
+
## 会报告不可得的写法
|
|
6
|
+
|
|
7
|
+
下列写法仍报告不可得或诊断:以函数名作参数、经 `CHOOSE` 等选出再调用的 `LAMBDA`、名称含 `?` 的 `LET`/`LAMBDA` 变量;两边都只有坐标的空格交集(如 `=A1:C3 B2:D4`;有名称参与的交集照常计算);不受支持的旧式数组公式(如单独的 `FREQUENCY(...)`)。不能把这一限制扩大成所有普通录入的数组计算都不可用。
|
|
8
|
+
|
|
9
|
+
- **显式交集与区域计数**:`@`/`SINGLE` 和 `AREAS` 已公开;显式交集成功时保留单格引用身份,数组取首格。实际调用这些内建入口时,自己的引用操作数若需要相对名称绑定、空格引用交集或 `INDEX` 多区域引用形式,仍不可得;未测的多冒号引用也会报告 `NONSCALAR_UNMEASURED_RANGE`。普通绝对名称、局部名称及普通联合不因此一律被拒绝。名称在自身作用域确定这两个内建入口的身份,与同名局部函数区分;已有其他函数跨名称作用域的 Excel 兼容性未验证。
|
|
10
|
+
- **交集公式的数组模式**:Excel 有时会把 `@SEQUENCE(...)` 或 `@溢出引用` 去掉显式包裹,保存为旧式公式;本程序读入后可能报 `ARRAY_MODE_REQUIRED`。文件里的保存值不能代替本次结果。保留显式入口的公式与已支持的普通引用不因此扩大限制。Table 数据体内实际为单格的动态结果不再仅因 Table 被阻挡,实际多格结果与 Table 相交仍会被阻挡;表头与汇总行未得到同样的验证。
|
|
11
|
+
- **统计参数限制**:公开的分布、反函数、百分秩和排列函数仍有形状、尾概率、样本规模、精度与收敛限制,按实际诊断判断。`BETA.DIST`/`BETADIST` 的非默认上下界归一化可能因表示误差与形状灵敏度而不可得,即使 Excel 能给值;密度端点写法另有限制。`GAMMA.INV`/`GAMMAINV` 的单位尺度根落入特定次正规范围时也不可得。不要把这些限制说成 Excel 的合法参数边界。
|
|
12
|
+
- **复数限制**:`IMTAN`/`IMCOT` 的部分非实轴极点附近因抵消风险报告 `COMPLEX_POLE_CANCELLATION_UNAVAILABLE`;实轴不套用这项保护。`IM*` 的日期样复数分量报告 `COMPLEX_DATE_COMPONENT_UNVERIFIED`,不猜测日期或地区含义。普通非法文本仍按原规则返回错误;不能把保护诊断伪装成 `#NUM!`。
|
|
13
|
+
- **债券与证券限制**:迭代 `YIELD`/`ODDFYIELD` 对部分高票息、极端价格与赎回比报告 `BOND_YIELD_PARAMETER_UNAVAILABLE`,单期 `YIELD` 的闭式不套用该限制;合法的长期零息债也可能被限制。部分二月末次付息、早期应计期、二月首期和日期系统转换后的上溢路径另有日期限制;根精度不能确认时报告 `BOND_ROOT_PRECISION_UNAVAILABLE`。按诊断说明具体原因,不把这些输入称为非法。
|
|
14
|
+
- **标量辅助与数字成文限制**:`AMORDEGRC` 在 1904 日期系统中,部分接近日期上限的购入日或首期末转换后不可得(`AMORDEGRC_DATE_OVERFLOW_UNVERIFIED`);请求很大的期号时还可能超过递推预算(`CALCULATION_BUDGET_EXCEEDED`),这不是 Excel 期数上界或耗时保证。`BAHTTEXT`/`NUMBERSTRING` 在极大数的上边界仍可能报告 `NUMBER_WORDS_UPPER_BOUNDARY_PENDING`。
|
|
15
|
+
|
|
16
|
+
上述不可得会传播到受影响的依赖与读取状态,`IFERROR` 不能把它们变成已验证数值。让 Excel 重算保存件时,Excel 不执行这些保护诊断,可能得到自己的数值、文本或错误。
|
|
17
|
+
|
|
18
|
+
## 与 Excel 的值仍可能不同的地方
|
|
19
|
+
|
|
20
|
+
- `LAMBDA` 的可选参数(`[y]` 写法)不受支持,但不报不可得:计算标为完成,结果是 `#VALUE!`,诊断里有 `UNKNOWN_NAME`。Excel 接受这种写法,这个 `#VALUE!` 不是它会给的值。用逗号留空的参数配 `ISOMITTED` 可以计算。
|
|
21
|
+
- `BETA.DIST`/`BETADIST` 与 `F.DIST.RT`/`FDIST` 带已知数值差异公开,并非全部与 Excel 逐值相同;保存后让 Excel 重算,结果可能变化。
|
|
22
|
+
- 复数函数保留已登记的文本差异,不能承诺文本逐字一致;部分函数兼容 Excel 的数值行为也不代表数学真值保证。
|
|
23
|
+
- `AMORLINC`、`ACCRINT`、`ODDFPRICE`、`ODDLPRICE`、`ODDLYIELD`、`YIELD`、`ODDFYIELD` 带已知差异公开,尤其收益率求解可能与 Excel 不同。
|
|
24
|
+
- `HOUR`、`MINUTE`、`SECOND` 在恰好 23:59:59.5 这一点:Excel 进到次日,本程序为 23:59:59。
|
|
25
|
+
- `TEXT` 的 `A/P` 在极少数格式串或文字值上退回原来的输出。
|
|
26
|
+
- `en-US` 下带货币符号的文本没有 Excel 实测。
|
|
27
|
+
- 普通加减乘除的结果落进次正规数范围(绝对值小于最小正规数)时,Excel 给 0,本程序保留这个极小值。
|
|
28
|
+
- 特定极小结果在 Excel 内存重算时非零,另存的文件缓存却可能为 0;不计算的读取应如实报告文件缓存,不能把它当作本次计算。这是已观测到的有限形态,不推广到所有极小数或所有 Excel/WPS 组合。
|
|
29
|
+
|
|
30
|
+
结果依赖上面任何一类时,要向用户注明。0.5.0 新增的函数没有做过 WPS 重算的兼容性验证。
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# 分页与续页
|
|
2
|
+
|
|
3
|
+
一个读取范围一页读不完时怎样续、续页要绑定哪个版本、`READ_TOO_LARGE` 之后怎样改。读取的入口与形状见 [reading.md](reading.md),字段查 `help read`。
|
|
4
|
+
|
|
5
|
+
## 一页多少、怎样续
|
|
6
|
+
|
|
7
|
+
- 一个范围一页至多 10,000 格(行数乘列数,`limits.readCells`),超过报 `READ_TOO_LARGE`。`offsetRows`、`limitRows` 写在各个范围里。
|
|
8
|
+
- 每个范围的结果里有 `page.nextOffsetRows`:为 `null` 才是这一项读完了。一份请求读多个范围时各管各的:第 0 项读完不代表第 1 项读完。续页保留整个范围数组与顺序,只改那一项的 `offsetRows`。
|
|
9
|
+
|
|
10
|
+
## 续页的版本
|
|
11
|
+
|
|
12
|
+
续页要绑定第一页读到的版本,保证各页来自同一份工作簿。
|
|
13
|
+
|
|
14
|
+
- **一次性命令**:第二页起必须在请求**外层**带 `expectedInputVersion`,值是第一页响应的 `workbookVersion`,否则报 `VERSION_REQUIRED`。命令行 `read` 用 `--expected-version`。
|
|
15
|
+
- **会话与脚本**:全部偏移为 0 的成功读取登记"页身份",即去掉偏移与显式版本之后的请求,含 `limitRows` 与计算参数。同一身份的续页可以不带版本,自动沿用第一页的。
|
|
16
|
+
- 登记之后只要有一个步骤成功(不含编辑的、只做计算的也算),自动续页报 `SOURCE_CHANGED`,`details` 里有 `boundVersion` 与 `currentVersion`;从偏移 0 重读就重新登记。
|
|
17
|
+
- 显式的 `expectedInputVersion` 优先,但仍须与当前字节一致。没有登记过的续页报 `VERSION_REQUIRED`。
|
|
18
|
+
- 脚本回滚时登记一起回滚。
|
|
19
|
+
|
|
20
|
+
## `READ_TOO_LARGE` 之后
|
|
21
|
+
|
|
22
|
+
错误的 `message` 给出实际列宽与每页能放的行数,`details.suggestions` 给出改法(读法见 [errors.md](errors.md)):
|
|
23
|
+
|
|
24
|
+
- 独立的单范围只读请求(`read`、`query`、`session.read`、`wb.read`):候选里的小 `request` 可以照发,它就是第一页。
|
|
25
|
+
- `run`、`preflight` 与步骤:候选只给 `$.read[i]`、`$.steps[i].read[j]` 的 `set`,用它替换那一个读取项,其余编辑与读取项原样保留。原来的非零偏移也从 0 重读。
|
|
26
|
+
- 多个范围同时超限:每次只报第一项。逐项改到第一页成功,再各自按 `nextOffsetRows` 读到 `null`。
|
|
27
|
+
- 一行就超过上限:第一页缩成 10,000 列,其余的列块配 `limitRows:1`。纯读取也可以改用 `query` 的 `cells`:结果在 `cells[].items`,按 `nextOffset` 续,同样绑定第一页的版本。
|
|
28
|
+
- 带编辑的请求只重试一次。之后要续读,用 `query` 读已发布的输出,或用会话的 `read` 读已提交的状态,都从偏移 0 起。
|
|
29
|
+
|
|
30
|
+
## 批次与预检里的页
|
|
31
|
+
|
|
32
|
+
- 批次步骤里读到的页不能与发布后的页拼接:后面的步骤可能改了同一个范围。发布成功后对最终输出从偏移 0 重读,之后各页绑定这一页的 `workbookVersion`。
|
|
33
|
+
- `"preflight":true` 的批次不发布,没有可续读的输出。单独的 `preflight` 不写文件,续页绑定它响应里的 `inputVersion`。
|
|
34
|
+
|
|
35
|
+
## 例
|
|
36
|
+
|
|
37
|
+
跟着 `nextOffsetRows` 读完一个范围。偏移写在范围里,版本写在外层。
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
python3 - <<'EOF'
|
|
41
|
+
import json, subprocess
|
|
42
|
+
request = {"input": "input.xlsx", "read": [
|
|
43
|
+
{"sheet": "Sheet1", "range": "A1:D200", "form": "compact", "offsetRows": 0, "limitRows": 80}]}
|
|
44
|
+
rows = []
|
|
45
|
+
while True:
|
|
46
|
+
json.dump(request, open("page.json", "w"))
|
|
47
|
+
out = subprocess.run(["./excel-kit", "query", "page.json"], capture_output=True, text=True).stdout
|
|
48
|
+
page = json.loads(out)
|
|
49
|
+
if not page["ok"]:
|
|
50
|
+
raise SystemExit(f"failed: {json.dumps(page.get('error') or page.get('calculation'))}")
|
|
51
|
+
rows += page["ranges"][0]["rows"]
|
|
52
|
+
offset = page["ranges"][0]["page"]["nextOffsetRows"]
|
|
53
|
+
if offset is None:
|
|
54
|
+
break
|
|
55
|
+
request["read"][0]["offsetRows"] = offset
|
|
56
|
+
request["expectedInputVersion"] = page["workbookVersion"]
|
|
57
|
+
print(len(rows))
|
|
58
|
+
EOF
|
|
59
|
+
```
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# 透视表与切片器
|
|
2
|
+
|
|
3
|
+
透视表的来源变了怎样刷新、依赖透视结果的公式怎样读、只保留而不支持编辑的原生透视怎样处理。参数查 `help pivot.refresh`、`help slicer.select`、`help query.pivots`。
|
|
4
|
+
|
|
5
|
+
## 两类透视
|
|
6
|
+
|
|
7
|
+
- **程序支持刷新的透视**:来源变化了,必须在改动它的**同一步**里执行 `pivot.refresh`,否则这一步以 `PIVOT_REFRESH_REQUIRED` 失败。追加明细、改透视来源和刷新透视要写进同一个 `operations` 数组。
|
|
8
|
+
- **程序只保留、不支持编辑的原生透视**:来源变化时缓存被标为失效,报告 `PIVOT_NOT_REFRESHED`,结果状态为需要刷新,不一定报 `PIVOT_REFRESH_REQUIRED`。这类保留下来的结果不是本次刷新的结果;需要时请用户在 Excel 里刷新。
|
|
9
|
+
|
|
10
|
+
透视不会自动刷新。追加明细后刷新的写法是在同一步里写 `[{"op":"table.append",…},{"op":"pivot.refresh","sheet":…,"name":…}]`。`inspect` 的 `workbook.pivots` 列出透视。
|
|
11
|
+
|
|
12
|
+
## 依赖透视结果的公式
|
|
13
|
+
|
|
14
|
+
依赖透视结果的公式按工作簿当前保存的透视结果计算,与 Excel 重算而不刷新透视相同:公式本次算出了值,但透视没有因此刷新,其与当前来源的一致性未获确认。要让这些公式反映刷新后的透视,就在执行 `pivot.refresh` 或 `slicer.select` 的同一步里,用该步自带的 `read` 读取它们;结果在该步的 `result.ranges`。之后单独读取(`session.read`、`wb.read`)默认不计算,读到的是存值(`s:"cache"`);让那次读取计算,公式按保存的透视结果重算,透视仍是 `stored`。
|
|
15
|
+
|
|
16
|
+
例外:透视缓存设了打开时刷新(`refreshOnLoad="1"`),或同一步里先刷新、之后又改了它的来源而没有再刷新时,引用它的公式不可得,诊断是 `PIVOT_RESULT_UNAVAILABLE`。以透视结果为来源再建透视(直接或经过公式),上游透视也要先在同一步刷新。
|
|
17
|
+
|
|
18
|
+
下面是配方 `recipes/pivot-by-slicer` 的做法(片段:它要求 `Pivot` 表上有名为 `RegionSlicer` 的切片器、`Report` 表上有依赖透视结果的公式):
|
|
19
|
+
|
|
20
|
+
```js
|
|
21
|
+
// 片段:脚本函数体内,每次选择都用这一步自带的 read
|
|
22
|
+
const step = await wb.run({
|
|
23
|
+
operations: [ { op: 'slicer.select', sheet: 'Pivot', name: 'RegionSlicer', items: ['East'] } ],
|
|
24
|
+
read: [ { sheet: 'Report', range: 'B1:B2' } ],
|
|
25
|
+
});
|
|
26
|
+
if (!step.ok) throw new Error(`${step.error.code}: ${step.error.message}`);
|
|
27
|
+
const values = step.result.ranges[0].cells;
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
读取透视结果区域时,紧凑形式里透视结果的格是 `{"v":值,"pivot":"current"|"stored"}`:`current` 是这一步刷新出来的结果,`stored` 是文件里存着的结果,不是本次的。
|
|
31
|
+
|
|
32
|
+
## 新增工作表之后的透视状态
|
|
33
|
+
|
|
34
|
+
只新增工作表时,只有数据源公式的保存值**确实保留下来**、来源没有变化的透视,才不会因为这次新增工作表而被标成需要刷新。数据源里有会被作废的公式时(哪几类见 [deliverable.md](deliverable.md) 的"哪些公式保留存值"),不能这样保证;原来就已经失效的状态,也不会因为新增工作表而恢复。
|
|
35
|
+
|
|
36
|
+
满足条件、这一步也没有刷新透视时,做了修改的那一步的编辑响应里,`pivots[]` 的对应项为 `sourceChange: unchanged`,`resultStatus` 保留原来的状态,原生缓存不置为失效:原来是 `stored_unverified` 的仍是它(`diagnostic` 为 `PIVOT_RESULT_UNVERIFIED`);原来是 `refresh_required` 的仍是 `refresh_required`,不会恢复。`query` 的 `pivots` 查询不返回 `sourceChange` 和单数的 `diagnostic`,它的状态在 `pivots[i].items[j].resultStatus`。`stored_unverified` 的意思是来源没变,但并没有重新证明原透视结果正确;它仍是文件里保存的结果,不是本次结果。
|
|
37
|
+
|
|
38
|
+
## 报告时
|
|
39
|
+
|
|
40
|
+
依赖未刷新透视的公式有值,但只与透视保存的结果一致。报告里要写明:公式已按工作簿当前保存的透视结果重新计算;透视未刷新,其与当前来源的一致性未获确认。列出哪些值依赖透视;来源变过(`PIVOT_NOT_REFRESHED`、`refresh_required`)的,请用户在 Excel 里刷新后再采信。打开时刷新的透视,引用它的公式不可得,`all` 默认仍发布其他可靠结果并给清单;`requireCompleteCalculation:true` 才拒绝。
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# 工作表与工作簿保护
|
|
2
|
+
|
|
3
|
+
怎样查清保护状态、怎样在不破坏原有权限的前提下编辑受保护的工作簿、保护带口令时怎么办。参数查 `help sheet.protect`、`help workbook.protect`、`help query.protection`。
|
|
4
|
+
|
|
5
|
+
## 先查清保护状态
|
|
6
|
+
|
|
7
|
+
`inspect` 给出保护的概况;要看完整权限,用 `query` 的 `protection`。下例中 `{}` 表示工作簿结构保护,`{"sheet":"Sheet1"}` 表示这张工作表的保护:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
cat > protection.json <<'EOF'
|
|
11
|
+
{ "input": "input.xlsx", "protection": [ {}, { "sheet": "Sheet1" }, { "sheet": "Data" } ] }
|
|
12
|
+
EOF
|
|
13
|
+
./excel-kit query protection.json > protection.out.json
|
|
14
|
+
python3 - <<'EOF'
|
|
15
|
+
import json
|
|
16
|
+
d = json.load(open('protection.out.json'))
|
|
17
|
+
if not d.get('ok'):
|
|
18
|
+
raise SystemExit(f"query failed: {d.get('error')}")
|
|
19
|
+
for p in d['protection']:
|
|
20
|
+
print(p.get('scope'), p.get('sheet'), p.get('protected'), p.get('password'), p.get('unsupportedAttributes'))
|
|
21
|
+
EOF
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- 结果在响应的 `protection` 数组里,与请求一一对应。每项有 `scope`、`protected`、`password.present` 和 `unsupportedAttributes`。
|
|
25
|
+
- 工作表保护的结果另有 `allow`(权限);工作簿结构保护的结果没有 `allow`,另有 `lockWindows`、`lockRevision` 等。
|
|
26
|
+
|
|
27
|
+
## 怎样编辑
|
|
28
|
+
|
|
29
|
+
- **只往未锁定的格里填写**:可以先直接写。失败的步骤不改变任何状态。
|
|
30
|
+
- **需要解除无口令保护才能编辑**:用配方 `recipes/edit-protected-workbook`。它在同一个事务里保存原有权限、只解除本次写入涉及的工作表保护(以及新增工作表所需的结构保护)、执行编辑、恢复并核对权限,最后只发布一次;中途任何一步失败都不发布。配方只接受 `write` 和 `sheet.add` 两种操作;`calculation` 省略时用 `none` 做保存维护。在程序包目录里运行(`input` 换成工作簿的实际路径):
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
cat > protected.json <<'EOF'
|
|
34
|
+
{
|
|
35
|
+
"input": "input.xlsx",
|
|
36
|
+
"output": "output.xlsx",
|
|
37
|
+
"strict": true,
|
|
38
|
+
"scriptPath": "recipes/edit-protected-workbook/recipe.js",
|
|
39
|
+
"arguments": {
|
|
40
|
+
"operations": [ { "op": "write", "sheet": "Sheet1", "range": "B2", "values": [[12]] } ],
|
|
41
|
+
"calculation": { "mode": "all" }
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
EOF
|
|
45
|
+
./excel-kit script protected.json > protected.out.json
|
|
46
|
+
python3 - <<'EOF'
|
|
47
|
+
import json
|
|
48
|
+
d = json.load(open('protected.out.json'))
|
|
49
|
+
if not d.get('ok'):
|
|
50
|
+
err = d.get('error') or {}
|
|
51
|
+
raise SystemExit(f"{err.get('code')}: {err.get('message')}")
|
|
52
|
+
print(d['output'].get('saved'), d['script']['result']['restored'])
|
|
53
|
+
EOF
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- **自己恢复保护时**,要传回查询得到的**完整 `allow`**:`{"op":"sheet.protect","sheet":"Sheet1","allow":<查询得到的 allow>}`。只写一个不带参数的 `sheet.protect`,会换成新保护的默认权限。解除、编辑、恢复要放在同一步里,这样中途失败也不会留下一个已解除保护的版本。
|
|
57
|
+
- **用户要求加保护的**,放在所有填写之后做,免得保护挡住前面的填写(配方 `recipes/fill-template` 就是这样做的)。
|
|
58
|
+
|
|
59
|
+
## 保护带口令时
|
|
60
|
+
|
|
61
|
+
不猜测口令,也不绕过校验。请用户在 Excel 里解除相应保护、另存一份副本,再用副本重试。配方遇到需要解除的保护带口令时,会在编辑前失败并给出同样的提示。有扩展的、程序不支持的保护属性(`unsupportedAttributes` 不为空)时,配方同样拒绝。
|
|
62
|
+
|
|
63
|
+
保护只是存在、本次操作并没有触及它时,不影响本次计算与发布。
|