@dztabel/excel-kit 0.0.0-stage → 0.10.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.
Files changed (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/DISTRIBUTION.md +13 -0
  3. package/LICENSE +45 -0
  4. package/README.md +74 -2
  5. package/SKILL.md +52 -0
  6. package/THIRD-PARTY-NOTICES.txt +3050 -0
  7. package/VALIDATION.md +46 -0
  8. package/bin/excel-kit.cjs +50 -0
  9. package/package.json +19 -4
  10. package/recipes/README.md +31 -0
  11. package/recipes/audit-and-repair/README.md +30 -0
  12. package/recipes/audit-and-repair/inspect.json +7 -0
  13. package/recipes/audit-and-repair/recipe.js +48 -0
  14. package/recipes/audit-and-repair/request.json +22 -0
  15. package/recipes/audit-and-repair/sample/clean-control.xlsx +0 -0
  16. package/recipes/audit-and-repair/sample/expected.json +15 -0
  17. package/recipes/audit-and-repair/sample/model-to-check.xlsx +0 -0
  18. package/recipes/edit-protected-workbook/README.md +30 -0
  19. package/recipes/edit-protected-workbook/prepare.json +10 -0
  20. package/recipes/edit-protected-workbook/recipe.js +41 -0
  21. package/recipes/edit-protected-workbook/request.json +14 -0
  22. package/recipes/fill-template/README.md +30 -0
  23. package/recipes/fill-template/recipe.js +46 -0
  24. package/recipes/fill-template/request.json +18 -0
  25. package/recipes/fill-template/sample/derive-template.request.json +22 -0
  26. package/recipes/fill-template/sample/original/LICENSE +201 -0
  27. package/recipes/fill-template/sample/original/cf-hyperlink-image-protection.xlsx +0 -0
  28. package/recipes/fill-template/sample/template.xlsx +0 -0
  29. package/recipes/import-clean-append/README.md +30 -0
  30. package/recipes/import-clean-append/prepare.json +8 -0
  31. package/recipes/import-clean-append/recipe.js +77 -0
  32. package/recipes/import-clean-append/request.json +22 -0
  33. package/recipes/import-clean-append/sample/incoming-1.csv +4 -0
  34. package/recipes/import-clean-append/sample/incoming-2.csv +3 -0
  35. package/recipes/import-clean-append/sample/trading-table.xlsx +0 -0
  36. package/recipes/inventory-media/README.md +31 -0
  37. package/recipes/inventory-media/prepare.json +9 -0
  38. package/recipes/inventory-media/recipe.js +44 -0
  39. package/recipes/inventory-media/request.json +7 -0
  40. package/recipes/inventory-media/sample/LICENSE +268 -0
  41. package/recipes/inventory-media/sample/NOTICE +36 -0
  42. package/recipes/inventory-media/sample/WithEmbeded.xlsx +0 -0
  43. package/recipes/inventory-media/sample/blue.png +0 -0
  44. package/recipes/inventory-media/sample/green.jpg +0 -0
  45. package/recipes/normalize-codes/README.md +30 -0
  46. package/recipes/normalize-codes/prepare.json +73 -0
  47. package/recipes/normalize-codes/recipe.js +34 -0
  48. package/recipes/normalize-codes/request.json +7 -0
  49. package/recipes/normalize-codes/sample/trading-table.xlsx +0 -0
  50. package/recipes/pivot-by-slicer/README.md +30 -0
  51. package/recipes/pivot-by-slicer/prepare.json +11 -0
  52. package/recipes/pivot-by-slicer/recipe.js +34 -0
  53. package/recipes/pivot-by-slicer/request.json +14 -0
  54. package/recipes/repair-and-test-model/README.md +13 -0
  55. package/recipes/repair-and-test-model/workflow.py +108 -0
  56. package/recipes/roll-forward-period/README.md +30 -0
  57. package/recipes/roll-forward-period/prepare.json +10 -0
  58. package/recipes/roll-forward-period/recipe.js +49 -0
  59. package/recipes/roll-forward-period/request.json +13 -0
  60. package/recipes/roll-forward-period/sample/budget-template.xlsx +0 -0
  61. package/recipes/style-matching-sheets/README.md +28 -0
  62. package/recipes/style-matching-sheets/recipe.js +38 -0
  63. package/recipes/style-matching-sheets/request.json +17 -0
  64. package/recipes/style-matching-sheets/sample/build-workbook.request.json +13 -0
  65. package/recipes/style-matching-sheets/sample/report-tables.xlsx +0 -0
  66. package/recipes/update-assumptions/README.md +29 -0
  67. package/recipes/update-assumptions/recipe.js +66 -0
  68. package/recipes/update-assumptions/request.json +10 -0
  69. package/recipes/update-assumptions/sample/build-model.request.json +12 -0
  70. package/recipes/update-assumptions/sample/cost-model.xlsx +0 -0
  71. package/recipes/update-matching-records/README.md +35 -0
  72. package/recipes/update-matching-records/incomplete-strict.json +33 -0
  73. package/recipes/update-matching-records/incomplete.json +32 -0
  74. package/recipes/update-matching-records/prepare-incomplete.json +21 -0
  75. package/recipes/update-matching-records/recipe.js +35 -0
  76. package/recipes/update-matching-records/request.json +29 -0
  77. package/recipes/update-matching-records/sample/trading-table.xlsx +0 -0
  78. package/reference/api.md +59 -0
  79. package/reference/audit.md +50 -0
  80. package/reference/calculation.md +82 -0
  81. package/reference/cost.md +61 -0
  82. package/reference/deliverable.md +66 -0
  83. package/reference/editing-and-saving.md +69 -0
  84. package/reference/errors.md +65 -0
  85. package/reference/external-links.md +39 -0
  86. package/reference/function-limits.md +30 -0
  87. package/reference/paging.md +63 -0
  88. package/reference/pivots.md +46 -0
  89. package/reference/presentation.md +11 -0
  90. package/reference/protection.md +63 -0
  91. package/reference/reading.md +70 -0
  92. package/reference/scripts.md +74 -0
  93. package/reference/selection.md +43 -0
  94. package/reference/session-loop.md +62 -0
  95. package/reference/sessions.md +54 -0
  96. package/reference/unsupported.md +31 -0
  97. package/release.json +41 -0
@@ -0,0 +1,29 @@
1
+ {
2
+ "input": "sample/trading-table.xlsx",
3
+ "output": "trading-table-updated.xlsx",
4
+ "scriptPath": "recipe.js",
5
+ "strict": true,
6
+ "arguments": {
7
+ "target": {
8
+ "kind": "rows",
9
+ "table": "交易明细"
10
+ },
11
+ "where": {
12
+ "column": "数量",
13
+ "operator": "gte",
14
+ "value": 2
15
+ },
16
+ "set": [
17
+ {
18
+ "column": "单价",
19
+ "value": 9.9
20
+ }
21
+ ],
22
+ "read": [
23
+ {
24
+ "sheet": "月汇总",
25
+ "range": "A2:B3"
26
+ }
27
+ ]
28
+ }
29
+ }
@@ -0,0 +1,59 @@
1
+ # 会话协议
2
+
3
+ 给从 Bun 程序里调用 excel-kit、或自己实现 `excel-kit session` 客户端的人;只用命令行不需要读这一篇。字段查 `excel-kit help`;调用方式的契约在 `SKILL.md`,会话怎样用见 [sessions.md](sessions.md)。
4
+
5
+ ## 1. 会话协议
6
+
7
+ `excel-kit session` 在标准输入输出上说换行分隔的 JSON-RPC 2.0:每行一个 JSON 对象,不支持批量数组,标准输出只有协议消息。请求按到达顺序逐个执行,一个进程里的多个会话也是串行的。
8
+
9
+ ```json rpc
10
+ {"jsonrpc":"2.0","id":1,"method":"session.open","params":{"sessionId":"s","input":"input.xlsx","output":"output.xlsx"}}
11
+ {"jsonrpc":"2.0","id":2,"method":"session.run","params":{"sessionId":"s","op":"write","sheet":"Sheet1","range":"B2","values":[[1200]]}}
12
+ {"jsonrpc":"2.0","id":3,"method":"session.save","params":{"sessionId":"s"}}
13
+ ```
14
+
15
+ 应答有三种样子,按 `id` 对应请求:
16
+
17
+ ```json response
18
+ {"jsonrpc":"2.0","id":2,"result":{"session":{"id":"s","version":"<SHA-256>"},"elapsedMs":41.2,"queuedMs":0.3,"response":{"ok":true,"status":"succeeded","inputVersion":"<SHA-256>","outputVersion":"<SHA-256>","result":{}}}}
19
+ ```
20
+
21
+ ```json response
22
+ {"jsonrpc":"2.0","id":2,"result":{"session":{"id":"s","version":"<SHA-256>"},"elapsedMs":12.5,"queuedMs":0.3,"response":{"ok":false,"status":"failed","inputVersion":"<SHA-256>","error":{"code":"SHEET_NOT_FOUND","message":"Worksheet does not exist.","details":{}}}}}
23
+ ```
24
+
25
+ ```json response
26
+ {"jsonrpc":"2.0","id":4,"error":{"code":-32601,"message":"Unknown method."}}
27
+ ```
28
+
29
+ - `result.response` 是该方法的业务响应,业务失败也在这里;顶层的 `error` 只报协议错误,这一行没有被当作请求执行。
30
+ - `result.session.version` 是当前内存字节的 SHA-256,与读取、查询响应里的 `workbookVersion` 是同一个值。`elapsedMs` 是执行时长,排队时长在 `queuedMs`。
31
+ - 应答不保证与请求同序:一行的格式、`id`、方法名、`params` 不对时立即应答,可能排在更早请求的应答之前。
32
+
33
+ | 协议错误 | 含义 |
34
+ |---|---|
35
+ | `-32700` | 该行不是合法 JSON;应答的 `id` 是 `null` |
36
+ | `-32600` | 不是合法请求:不是对象、缺 `jsonrpc` 或 `method`、缺 `id`,或 `id` 属于一个还没结束的请求 |
37
+ | `-32601` | 未知方法 |
38
+ | `-32602` | `params` 不是对象;`sessionId` 缺失或不是字符串(`session.open` 自选的要 1–128 个字符) |
39
+ | `-32001` | 未知会话:没有打开过,或已经关闭。轮到这条请求执行时才判,所以打开与后续调用可以一起管入 |
40
+
41
+ `id` 只接受字符串或数字,`1` 与 `"1"` 是不同的 id。像 JSON-RPC,不像的地方是除 `$/cancel` 外每条消息都必须带 `id`:缺 `id` 的消息得到 `-32600`,不会被静默执行。
42
+
43
+ 取消用通知 `{"jsonrpc":"2.0","method":"$/cancel","params":{"id":<请求 id>}}`:排队中的请求立即以 `CANCELLED` 应答,运行中的步骤以 `CANCELLED` 失败且不改状态,运行中的脚本整体回滚;未知或已结束的 id 被忽略。
44
+
45
+ 结束:
46
+
47
+ - 标准输入关闭后,已收到的请求全部执行并应答,然后丢弃未保存的状态,退出码 0。
48
+ - SIGINT、SIGTERM:停止读入,取消运行中的调用,排队中的请求逐条以 `CANCELLED` 应答,退出码 130。Windows 上没有 SIGTERM,用 `$/cancel` 取消、用关闭标准输入结束。
49
+ - 标准输出管道断开:中止运行中的调用,退出码 1。
50
+
51
+ 一个进程可以打开多个会话,每个持有一份工作簿字节,不设数量上限;要并行就启动多个进程。两个会话指向同一个目标文件时,保存时的版本核对保证后保存的一方不会悄悄覆盖先保存的。会话不是守护进程:没有端口、鉴权和后台常驻,生命周期就是这个子进程。
52
+
53
+ ## 2. 退出码
54
+
55
+ 响应 `ok:false` 是 1,其中 `error.code` 为 `CANCELLED` 是 130,其余是 0。所以 0 不等于做成了:一次性脚本有失败步骤、甚至一步都没成功时是 0;会话在输入结束后退出也是 0,不论其中有多少业务失败。
56
+
57
+ ## 3. 客户端接入
58
+
59
+ 使用子进程调用 CLI 或连接会话协议。版本前置条件、试算与重读见 [sessions.md](sessions.md)。
@@ -0,0 +1,50 @@
1
+ # 找出算不出来的公式与影响范围
2
+
3
+ 整本计算不完整时,怎样列出问题、追到源头、查清一处改动影响到哪里。不支持的原因见 [unsupported.md](unsupported.md),字段查 `help query.findings`、`help query.dependencies`。
4
+
5
+ ## 问题清单:`findings`
6
+
7
+ - `query` 加 `"calculation":{"mode":"all"}` 和 `findings`,就是 `audit` 的默认行为。计算不完整时查询仍是 `ok:true`,要自己看 `calculation.status`。
8
+ - `findings.items` 不全是算不出来的格:`kind` 为 `diagnostic` 的是诊断(`code` 是原因,如 `UNSUPPORTED_FUNCTION`),`cache_difference` 是本次结果与文件里存值不同的格。按 `kind` 与 `classification` 筛。
9
+ - 默认每页 100 条,`limit` 让一页多取;`findings.nextOffset` 不为 `null` 还有下一页。`assessment` 是汇总:已确认的错误、不可得、存值差异各多少。
10
+
11
+ ## 引用关系:`dependencies`
12
+
13
+ - 查一个格的上游(`"direction":"precedents"`)或下游(`"dependents"`),加 `"transitive":true` 一直追到头。名称会展开,比自己解析公式可靠。
14
+ - 结果与请求一一对应。条目用 `sheet` 加 `range` 定位,`range` 可能是一块区域;`nextOffset` 不为 `null` 还有下一页。
15
+ - 它只给**静态**引用,也就是公式里写明的。`INDIRECT`、`OFFSET` 这类运行时才定的区域不在其中:结果的 `limitations.count` 大于 0,`items` 里标出是哪些格(如 `RUNTIME_REFERENCES_PENDING`)。这时即使翻完所有页,也不是完整的影响范围;用它组计算目标或说明影响之前先看 `limitations`。
16
+ - 要判断一个上游格是输入还是公式,读回它看 `kind`,紧凑形式看有没有 `f`。
17
+
18
+ ## 整本算不完整时
19
+
20
+ 默认 all 计算不完整仍保存可靠结果,先读 calculation.unavailable.report 指向的 JSONL 清单。显式 requireCompleteCalculation:true 的 all 被拒绝、没有写文件时:
21
+
22
+ 1. 读错误 `details` 里的诊断,按格找出不可得的源头:不支持的函数、外部引用、循环、模拟运算表、打开时刷新的透视。要列全就用上面的 `findings`。
23
+ 2. 用 `dependents` 加 `transitive` 查这些源头影响到的格,先看 `limitations`。
24
+ 3. 任务要的结果里,不受影响的那些作为 `targets` 计算。这是按交付要求缩小范围,不是绕过失败:受影响的结果仍然没有。
25
+ 4. 报告里写清哪些是本次结果,哪些没有值或没有更新,各自是什么原因;不要笼统地说"源文件有错"。
26
+
27
+ 修复时,互相牵连的问题(多个循环、未知函数)要在同一步里改,否则中间状态仍算不出来;改完再审计一次。包里的配方 `recipes/audit-and-repair` 是完整的做法。
28
+
29
+ ## 例
30
+
31
+ 一份查询同时要问题清单和两处引用关系:
32
+
33
+ ```sh
34
+ cat > audit.json <<'EOF'
35
+ {"input":"input.xlsx","calculation":{"mode":"all"},
36
+ "findings":{"limit":1000},
37
+ "dependencies":[{"sheet":"Sheet1","cell":"B10","direction":"precedents","transitive":true},
38
+ {"sheet":"Data","cell":"C2","direction":"dependents","transitive":true}]}
39
+ EOF
40
+ ./excel-kit query audit.json > audit.out.json || true
41
+ python3 - <<'EOF'
42
+ import json
43
+ d = json.load(open('audit.out.json'))
44
+ if not d['ok']:
45
+ raise SystemExit(f"failed: {json.dumps(d['error'])}")
46
+ print(d['calculation']['status'], d['assessment'], len(d['findings']['items']), d['findings']['nextOffset'])
47
+ for dep in d['dependencies']:
48
+ print(dep['limitations']['count'], dep['nextOffset'], [(i['sheet'], i['range']) for i in dep['items']][:3])
49
+ EOF
50
+ ```
@@ -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. 核对输入与公式的变化用 [compare](paging.md)。样式、对象和布局另查对应属性。
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
+ 首行记录版本、计算条件、不可得格数 count、压缩条数 records、recordsSha256 与保存核验。之后逐行列出区域及原因、所有者和存值状态,按步骤、表、行、列排序。
63
+
64
+ 核对文件 SHA-256 后流式读第二行起的记录。按 stepId 核对 records、count、区域无重叠及原始 UTF-8 行(含换行)的 recordsSha256。保留文件与报告,以 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,65 @@
1
+ # 错误码
2
+
3
+ 先看 `error.message` 与 `error.details`,用 `help find <词>` 查相关帮助。
4
+
5
+ ## `details.suggestions` 的读法
6
+
7
+ 超时与读取超限的错误在 `details.suggestions` 里给出候选的改法,`details.hints` 写明字段该放在哪里。
8
+
9
+ - 按 `condition` 判断适用条件,按 `path` 合并局部修改 `set`,保留输入、编辑、版本与计算环境。`request` 可作为独立只读请求。
10
+ - 简写的步骤先把原操作包成 `operations:[原操作]`(原生编辑是 `nativeEdits`);旧式查询先删 `calculate` 再设 `calculation`。
11
+ - 单项限 1024 字符,合计 4096;截断见 `details.suggestionsTruncated`。脚本错误路径见末节。详情过大时有 `detailsOmitted:true`。
12
+
13
+ ## 请求与读取
14
+
15
+ | 码 | 是什么 | 怎么办 |
16
+ |---|---|---|
17
+ | `INVALID_REQUEST` | 请求结构不对,或字段放错了位置 | `details.path` 指出出错的对象;有 `details.hints` 就照它写明的位置改。单个操作 `{op:…}` 旁边写了 `calculation`、`read` 时,把操作放进 `operations` |
18
+ | `UNKNOWN_HELP_TOPIC` | `help` 的名字不对 | 从 `details.suggestions` 里挑一个,或 `help find <词>` |
19
+ | `READ_TOO_LARGE` | 一个范围这一页超过上限 | `paging.md` |
20
+ | `VERSION_REQUIRED` | 续页没带版本,或会话、脚本里没有登记过的续页 | 同上 |
21
+ | `SOURCE_CHANGED` | 续页之前有过成功的步骤;或输入文件在读入之后被改了 | 续页:从偏移 0 重读。输入被改:重新打开重做 |
22
+ | `CALCULATION_INCOMPLETE` | 默认是计算不完整的警告,仍发布;`requireCompleteCalculation:true` 时是拒绝发布的错误。`strict` 脚本里算不完整的读取仍以它抛出 | 看 `details` 的诊断,`audit.md` |
23
+
24
+ ## 计算
25
+
26
+ | 码 | 是什么 | 怎么办 |
27
+ |---|---|---|
28
+ | `UNSUPPORTED_FUNCTION` | 函数没有计算入口,或是 VBA 自定义函数、Excel 4 宏表函数 | `help fn.<函数名>`;`unsupported.md` |
29
+ | `EXTERNAL_REFERENCE` | 依赖外部工作簿 | `external-links.md` |
30
+ | `CIRCULAR_REFERENCE` | 真实循环;不支持迭代计算 | 报告,或按业务改公式,多个循环在同一步里改 |
31
+ | `UNSUPPORTED_UNION_REFERENCE` | 联合多区域引用用在了不支持的位置 | 该公式不可得,报告 |
32
+ | `ARRAY_MODE_REQUIRED` | 公式的数组模式不受支持;Excel 去掉显式交集后保存的旧式公式也会触发 | `function-limits.md`;存值不能代替本次结果 |
33
+ | `PIVOT_REFRESH_REQUIRED` | 透视的来源变了,却没有在同一步刷新 | 改来源的同一步里 `pivot.refresh`,`pivots.md` |
34
+ | `PIVOT_RESULT_UNAVAILABLE` | 公式引用的透视缓存设了打开时刷新,或同一步里刷新过、之后来源又变了;或另一张透视以未刷新的透视结果为来源 | 在同一步刷新该透视,用该步自带的 `read` 读;打开时刷新的透视请用户在 Excel 里刷新,`pivots.md` |
35
+ | `PIVOT_NOT_REFRESHED` | 只保留、不支持编辑的透视,来源变了 | 不当作本次结果;请用户在 Excel 里刷新 |
36
+ | `CALCULATION_TIMEOUT`、`STEP_TIMEOUT`、`BATCH_TIMEOUT` | 计算、整步、整批超过期限 | `cost.md` |
37
+ | `…_CALCULATION_INCOMPLETE`(`RANGE`、`DATA`、`FILTER`、`PIVOT`、`AUTOFIT`)、`…_FORMULA_VALUES_REQUIRED`(`FILTER`、`DATA`) | 操作自己要用的当前值算不出来;或要用公式的值而没写 `formulaValues:"calculate"` | `calculation.md` |
38
+ | `RULE_CALCULATION_REQUIRED`、`SELECTION_CALCULATION_REQUIRED` | 要当前值的校验、规则结果或选择,配了 `"mode":"none"` | 去掉 `none` |
39
+ | `FORMULAS_WITHOUT_VALUES`(警告) | 发布的文件里有公式没有值;与计算不可得数量不同 | `deliverable.md` |
40
+ | `MANUAL_RECALCULATION_REQUIRED`(警告) | 手动模式缺值公式,或手动/autoNoTable 的失效模拟运算表须人工重算 | `deliverable.md` |
41
+
42
+ ## 编辑与保存
43
+
44
+ | 码 | 是什么 | 怎么办 |
45
+ |---|---|---|
46
+ | `OUTPUT_EXISTS`、`TARGET_CHANGED` | 目标已存在,或在读入之后被改了 | 换输出名;确认覆盖就把 `details.currentVersion` 填进 `overwrite.expectedVersion` |
47
+ | `INVALID_OUTPUT`、`OUTPUT_UNAVAILABLE` | 输出的扩展名不对;输出目录不存在或路径不可用 | 前者改扩展名;后者先建目录,或按 `details` 改路径 |
48
+ | `WORKBOOK_FORMAT_MISMATCH` | 扩展名与工作簿类型不符 | `.xlsm` 仍存为 `.xlsm` |
49
+ | `FORMULA_TOO_LONG` | 写入的公式换成原生存储形式后超过 8192 字符 | 缩短实际写入的公式;`editing-and-saving.md` |
50
+ | `FILE_BUSY`、`LOCK_UNAVAILABLE` | 另一个写入者持有锁,或遗留的锁记录无法确认;取不到锁(如目录不可写) | 看 `details`;不要为了解锁删 guard 文件 |
51
+ | `FILE_IDENTITY_MISMATCH` | 含 `CELL` 公式的会话另存到别的文件名 | `sessions.md` |
52
+ | `SELECTION_COUNT_MISMATCH`、`SELECTION_INCOMPLETE` | 命中个数与 `expectedMatches` 不符;条件判不出 | `selection.md` |
53
+ | `EXTERNAL_LINK_IN_USE`、`EXTERNAL_LINK_RENUMBERING` | 外部链接还在用,或删除会改变别的链接的序号 | `external-links.md` |
54
+ | `NO_CHANGES` | 不是错误:`session.save` 成功响应里的 `status`,没有写文件 | `sessions.md` |
55
+ | `SESSION_EXISTS` | 会话 id 已被占用 | 换一个 `sessionId` |
56
+ | `CANCELLED` | 请求被取消 | 这一步不改状态;脚本整体回滚 |
57
+
58
+ ## 脚本与会话
59
+
60
+ | 码 | 是什么 | 怎么办 |
61
+ |---|---|---|
62
+ | `SCRIPT_FAILED` | 脚本抛错、有语法错误或线程退出,整体回滚 | 原错误在 `error.details.cause`(`strict`)或 `error.details.lastCallFailure`,不是每次都有;`scripts.md` |
63
+ | `SCRIPT_TIMEOUT`、`SCRIPT_STEP_LIMIT`、`SCRIPT_RESULT_NOT_SERIALIZABLE` | 整段超时;`wb.run` 次数超限;返回值不能序列化。都整体回滚 | 同上 |
64
+
65
+ 会话应答顶层的 `error`(`-32700` 等)只表示协议问题,不在 `result.response` 里;各码的含义见 `api.md`。
@@ -0,0 +1,39 @@
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 里断开链接。
36
+
37
+ ## 从另一份工作簿迁入可独立工作的区块
38
+
39
+ 用 `help range.transfer` 查看矩形、图表与映射契约。先定位来源,再为区外引用和名称逐个选择目标绑定;两簿同名的定义可以指向不同输入。将变换后的公式与系列落点纳入核对。非空目标须根据预检确认的精确矩形、当前目标版本授权。会话里可用试算预检未保存版本。遇到跨区对象时缩小范围或选择整表导入。
@@ -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 重算的兼容性验证。