@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,63 @@
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
+ ```
60
+
61
+ ## 找两个版本之间的内容变化
62
+
63
+ 用 `help compare`。比较单元格输入与展开后的公式,先缩到可疑的同名表与矩形。首批响应给出两份文件版本,续页同时传回两者。若只改名定义、格式或对象,应改查相应对象;若同值公式变常量,比较会直接列出两侧类型。
@@ -0,0 +1,46 @@
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` 才拒绝。
41
+
42
+ 本地来源透视的 `pivot.create`、`pivot.set` 支持以下定义,`query.pivots` 的 `settings` 可读回。改源数据后执行 `pivot.refresh`。
43
+
44
+ - `dateGroups:[{field:"Date",by:"quarters"},{field:"Date",by:"years",name:"Year"}]` 以季度和年分组。在行字段中依次引用 Year、Date。最细级沿用来源字段名,较粗级取唯一名称。支持年、季、月、日。
45
+ - `rules:[{type:"captionBeginsWith",field:"Team",value:"North"},{type:"topN",field:"Team",measure:"Revenue",count:1}]` 在当前透视过滤标签并按指定度量排名。并列边界保留所有命中的成员。
46
+ - `calculatedFields:[{name:"Unit price",formula:"Sales/Units"}]` 声明计算字段,随后在 `values` 中按字段名引用。分组和总计均先汇总来源字段,再计算比值。条件费率、零分母与舍入指标可组合数值比较、IF、ABS 和 ROUND。先手算同组多行的分组合计和总计,再对照刷新结果;函数形状查 `help pivot.create calculatedFields`。
@@ -0,0 +1,11 @@
1
+ # 版面与对象
2
+
3
+ 固定行高的换行文本可以用 `help query.layout` 的 `axis:"textClipping"` 查。观察报告中的地址、合并范围和以磅计的可用及估计所需高度。未取得当前公式结果的格会报告无法判断,需要时在同一查询对该格指定 targets。可先在受保护的表上检查,挑出值得调整的行,再决定是否修改行高。调整后用相同范围复查。
4
+
5
+ ## 已有图表、透视与规则的局部编辑
6
+
7
+ 先以 `query.charts` 定位工作表内的图表名称、系列 `index` 与来源。用 `chart.set.seriesEdit` 指定一个系列。例如 `{"index":1,"sources":{"values":"Data!D2:D4"},"marker":{"symbol":"diamond","size":6}}` 会同时更新系列来源和标记。线图和散点图可设置 `linearTrendline` 与 `fixedErrorBars`,传 `null` 可删除。点覆盖使用 `point.index` 和 `point.appearance`,传空外观值可清除覆盖。
8
+
9
+ 在 `chart.create` 中指定 `type:"histogram"` 或 `type:"boxWhisker"`、本地单列或单行数值来源 `series:[{values:"Data!A1:A5"}]`,并传入绘图锚点。直方图用 `binning:{width:3}` 或 `binning:{count:4}`,箱线图用 `quartileMethod:"exclusive"` 或 `"inclusive"`。已有图可用 `chart.set` 改设置,用 `chart.refresh` 从当前工作簿刷新数值缓存。Excel 保存后可能把来源写为隐藏定义名称,查询返回文件实际绑定。对带分箱设置的直方图,Excel 使用分箱元素的 `val` 属性;固定版 Open XML SDK 的严格校验可能在该元素上同时报属性与文本诊断。
10
+
11
+ `conditional-format.set` 的 `condition` 支持 `{kind:"average",equal:true}` 和 `{kind:"time-period",period:"today"}`。数据条在同一条件对象传 `negativeColor`、`axisPosition` 和 `direction`。列表验证的 `showDropdown` 放在 `validation.set` 操作顶层,false 隐藏箭头。用 `query.rules` 查定义,`query.ruleResults` 查当前输入的匹配结果。
@@ -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
+ 保护只是存在、本次操作并没有触及它时,不影响本次计算与发布。
@@ -0,0 +1,70 @@
1
+ # 读单元格与取值
2
+
3
+ 三个读取入口的差别、返回的格长什么样、怎样在代码里只取当前值。来源标记 `s` 的四个取值见 `SKILL.md` 第 3 条,字段查 `help read` 与 `help read.cells`,一页读不完见 [paging.md](paging.md)。
4
+
5
+ ## 三个入口
6
+
7
+ - **`query` 请求的 `read`**:一份请求列出同一个文件的多块区域,一次读完;结果在顶层 `ranges`,顺序与请求一致。一次性 `run` 的 `read` 相同。
8
+ - **`wb.read`、`session.read`**:读取项写在 `ranges`,不是 `read`;结果同样在 `ranges`。
9
+ - **命令行 `read`**:只接受命令行参数,不接受请求文件,一次一块。每次调用都重新解析整本,不要用它逐页读大表。
10
+
11
+ 分页参数 `offsetRows`、`limitRows` 写在各个范围里;`expectedInputVersion` 与 `timeoutMs` 写在请求外层,不写在范围里,也不写在 `calculation` 里。
12
+
13
+ ## `inspect` 给什么
14
+
15
+ `inspect` 返回工作簿概况,不计算:`workbook.sheets`(每项有 `name`)、`definedNames`、`tables`、`pivots`、`externalLinks`、`fileType`、`diagnostics`,以及文件版本 `workbook.version`。它不是完整的对象盘点:图表、图片、批注、保护的完整权限等用 `query` 的对应种类查。`wb.inspect()`、`session.inspect` 返回同样的形状。
16
+
17
+ ## 两种形状
18
+
19
+ - **不写 `form`**:格在 `cells`(按行的二维数组),每格是带 `kind`、`formula`、`result` 的对象。没有本次结果时 `result` 是 `null`,文件里的存值在 `cache`、状态在 `cacheState`;直接取 `result.value` 会抛类型错误。`display.text` 可能由存值格式化而来,先看 `display.source`。
20
+ - **`"form":"compact"`**:格在 `rows`。常量就是它的 JSON 值,没有来源标记:真正的空白是 `null`,空文本是 `""`,错误值是 `{"e":"#N/A"}`。公式是 `{"f","v","s"}`,数组结果的成员是 `{"a":锚点,"v","s"}`,模拟运算表的结果另带 `d`,透视结果格是 `{"v","pivot":"current"|"stored"}`,格内图片是 `{"image"}`。它不含格式、显示文本与行可见性,不能与 `include` 同用;体量能小一个数量级。
21
+
22
+ ## 要当前值
23
+
24
+ - 把读取写进做计算的那一步的 `read`:与这一步的计算是同一次,之后再单独读就是 `cache`。
25
+ - 不计算的读取里,有存值的公式标 `cache` 是正常的;报告它时要说明这是文件里保存的上次计算值,没有经过本次验证。文件里本来就没有存值的公式是 `unavailable`,不一定是出错。
26
+ - `s` 是 `result` 的值仍可能是错误值 `{"e":…}`。
27
+
28
+ ## 取值片段
29
+
30
+ 下面的函数适用于一次性 `run`、`query`、`read` 的响应,`session.run`、`wb.run` 的步骤响应,以及 `report:"full"` 里的步骤结果。它只返回常量或本次结果;失败、计算不完整、存值、不可得与错误值都抛出原因。
31
+
32
+ ```js
33
+ function currentCell(response, rangeIndex = 0, row = 0, column = 0) {
34
+ if (response?.ok !== true) {
35
+ throw new Error(JSON.stringify(response?.error ?? response?.calculation ?? response));
36
+ }
37
+ const report = response.status === 'succeeded' ? response.result : response;
38
+ const status = report?.calculation?.status;
39
+ if (status !== 'complete' && status !== 'not_requested') {
40
+ throw new Error(JSON.stringify(report?.calculation ?? 'Missing full step report'));
41
+ }
42
+ const range = report.ranges?.[rangeIndex];
43
+ if (!range) throw new Error('Missing requested range');
44
+ if (range.form === 'compact') {
45
+ const cell = range.rows?.[row]?.[column];
46
+ if (cell === undefined) throw new Error('Cell outside returned page');
47
+ if (cell !== null && typeof cell === 'object') {
48
+ if ('image' in cell) throw new Error('Image is not a scalar');
49
+ if ('s' in cell && cell.s !== 'result') throw new Error('Formula is not current: ' + cell.s);
50
+ if ('pivot' in cell && cell.pivot !== 'current') throw new Error('Pivot is not current');
51
+ const value = 'v' in cell ? cell.v : cell;
52
+ if (value !== null && typeof value === 'object') throw new Error(JSON.stringify(value));
53
+ return value;
54
+ }
55
+ return cell;
56
+ }
57
+ const cell = range.cells?.[row]?.[column];
58
+ if (!cell || cell.result === null || cell.result === undefined) throw new Error('No current scalar');
59
+ if (cell.pivotResult && cell.pivotResult.source !== 'current_pivot_result') throw new Error('Pivot is not current');
60
+ if (cell.result.type === 'error') throw new Error(String(cell.result.value));
61
+ return cell.result.value;
62
+ }
63
+ ```
64
+
65
+ 传什么进去:
66
+
67
+ - 一次性命令:整个响应。脚本里:`currentCell(await wb.run(step))`。
68
+ - 会话:先处理应答顶层的协议 `error`,再传 `reply.result.response`。
69
+ - 脚本的报告:一次性脚本先看外层 `ok` 与 `script.ok`,再传 `response.script.steps[i]`;会话脚本传 `response.steps[i]`。默认的报告没有每步的 `result`,要加 `report:"full"`。
70
+ - `script.result` 是脚本自己返回的 JSON,不要假定它有 `ranges`。
@@ -0,0 +1,74 @@
1
+ # 脚本
2
+
3
+ 发布方式见入口第 2 条;请求字段与成员查 `help script`、`help wb.<成员>`。可运行脚本见包内 `recipes/README.md`。
4
+
5
+ ## 请求与脚本体
6
+
7
+ - 脚本是 JavaScript **异步函数体**,不是模块:可以用顶层 `await` 和 `return`,不能 `import`、`export`。参数是 `wb` 和 `args`(请求里的 `arguments`)。长脚本放进文件用 `scriptPath`。
8
+ - 只读的脚本也必须写 `output`,给一个不存在的路径;没有成功的 `wb.run` 就不写文件,`output.saved:false`。
9
+ - `session.script` 在未保存状态上执行。默认保留成功修改,`session.save` 才写盘;`trial:true` 只带回结果并恢复原状态。见[会话](sessions.md)。
10
+ - 修改只有 `wb.run` 一条路,用的是与 `run` 相同的操作。`wb` 没有通用文件接口:CSV 用 `data` 操作导入工作表再读回,图片与附件用 `image-extract`、`attachment-extract` 命令提取。
11
+
12
+ ## 默认写 `strict:true`
13
+
14
+ 像普通 JavaScript 的异常:任何一次 `wb.run`、`wb.read`、`wb.query`、`wb.inspect` 失败都抛出 `ExcelKitError`,不用逐个判 `ok`。
15
+
16
+ ```sh
17
+ cat > flag.js <<'EOF'
18
+ const page = await wb.read({ ranges: [{ sheet: 'Sheet1', range: 'A2:C200', form: 'compact' }] });
19
+ let flagged = 0;
20
+ for (const [i, row] of page.ranges[0].rows.entries()) {
21
+ if (typeof row[1] !== 'number' || row[1] <= args.limit) continue;
22
+ await wb.run({ op: 'format', sheet: 'Sheet1', range: `A${i + 2}:C${i + 2}`, style: { fill: 'FFC7CE' } });
23
+ flagged++;
24
+ }
25
+ return { flagged };
26
+ EOF
27
+ cat > flag.json <<'EOF'
28
+ {"input":"input.xlsx","output":"flagged.xlsx","strict":true,"calculation":{"mode":"none"},
29
+ "arguments":{"limit":1900},"scriptPath":"flag.js"}
30
+ EOF
31
+ ./excel-kit script flag.json > flag.out.json
32
+ ```
33
+
34
+ - 抛出的对象有 `method`(`run`、`read`、`query`、`inspect`)、`code`、`message`、`details` 和原响应 `response`。
35
+ - 不捕获:脚本以 `SCRIPT_FAILED` 失败并整体回滚,`error.message` 形如 `wb.read failed: SHEET_NOT_FOUND: …`,原错误在 `error.details.cause`(`{method, code, message, details}`,过大的 `details` 会省去)。
36
+ - 要自己处理某一次失败,就只捕获那一次:`const step = await wb.run(…).catch(error => error.response);`,拿回的是原响应,再判 `step.ok`。被捕获的失败 `wb.run` 仍计入 `stepFailures`。
37
+ - `wb.run` 默认计算不完整也 `ok:true`,`strict:true` 不抛;要拒绝可在打开参数或分组步骤写 `requireCompleteCalculation:true`。独立读取/查询的两种计算不完整:**查询**仍是 `ok:true`、不抛,自己看 `calculation.status`;**读取**抛 `CALCULATION_INCOMPLETE`,`details` 带 `scope` 与 `diagnostics`。未知动态数组的范围可能影响读取或查询位置时,两者仍可能报 `ARRAY_EXTENT_UNAVAILABLE`;`strict:true` 会将该失败抛出。
38
+
39
+ ## 不带 `strict` 时
40
+
41
+ 失败的调用不抛错,返回 `ok:false`:`wb.run` 是 `{ok:false, status:"failed", inputVersion, error}`,其余是 `{ok:false, error}`;计算不完整的读取有 `calculation` 而**没有 `error`**。所以每次取值之前都要判:
42
+
43
+ ```js
44
+ const need = (r, what) => {
45
+ if (r.ok) return r;
46
+ throw new Error(`${what}: ${r.error ? r.error.code : 'calculation ' + r.calculation?.status}`);
47
+ };
48
+ const page = need(await wb.read({ ranges: [{ sheet: 'Sheet1', range: 'A2:C200' }] }), 'read');
49
+ ```
50
+
51
+ - 没判就取,通常是一个 `TypeError`:脚本以 `SCRIPT_FAILED` 失败,原错误码只在 `error.details.lastCallFailure` 里。
52
+ - 失败之后继续执行并正常返回,成功的步骤照样发布。只有失败的 `wb.run` 计入 `stepFailures`;被忽略的读取、查询失败在报告里看不出来。要整段作废就 `throw`。
53
+
54
+ ## 整体回滚的情形
55
+
56
+ 脚本抛错或有语法错误、线程在返回前退出(没人处理的 Promise 拒绝、定时器回调里抛错)是 `SCRIPT_FAILED`;超过 `scriptTimeoutMs` 是 `SCRIPT_TIMEOUT`;被取消是 `CANCELLED`;`wb.run` 超过次数上限是 `SCRIPT_STEP_LIMIT`(失败的调用也计数);返回值不能序列化(BigInt、循环引用)是 `SCRIPT_RESULT_NOT_SERIALIZABLE`;某一步出内部错误也整段回滚。返回之前已经发出、没有 `await` 的调用照常执行并计入步骤;返回之后才发生的拒绝不影响结果。
57
+
58
+ ## 响应与发布
59
+
60
+ 一次性 `script` 的外层与 `run` 相同,但**没有 `calculation`**;报告在 `script` 下:
61
+
62
+ - `script.status` 是 `completed`、`completed_with_failures` 或 `failed`;`script.result` 是返回值(`undefined`、函数、Symbol 记为 `null`)。
63
+ - `script.steps` 每次 `wb.run` 一项,默认只有状态、版本和错误;要每步的结果加 `"report":"full"`,体积随步数线性增长。回滚后仍列出已执行的步骤:报告的 `outputVersion` 等于 `inputVersion`,步骤记录保留执行时的版本。
64
+ - 一步都没成功:`ok:true`、`output.saved:false`、退出码 0。脚本成功而发布被拒(例如运行期间输入文件被改):外层 `ok:false`,`error` 是发布的错误,`script.ok` 仍为真。请求在脚本开始前就被拒:只有 `ok` 与 `error`,没有 `script`。
65
+ - 所以检查一次性脚本看三样:`ok`、`script.stepFailures`、`output.saved`。退出码 0 包含 `completed_with_failures`。
66
+ - 全程持有目标文件的锁,其间别的写入者得到 `FILE_BUSY`。
67
+
68
+ ## 环境
69
+
70
+ - `console` 的输出进 `script.logs`,不进标准输出;有条数与总量上限,超出时 `logsTruncated:true`。
71
+ - `Bun`、`process`、`require`、`fetch` 被遮蔽,只为防止误用,不是安全沙箱:脚本仍能经 `globalThis` 访问宿主,那些文件或网络访问不受事务回滚保护。
72
+ - 脚本之间不共享 JavaScript 状态。每次 `wb.read` 都重新解析工作簿:只读需要的范围,页开到上限。
73
+ - 没有脚本的预检;要预演就在会话里运行脚本而不保存。
74
+ - 步数与整段期限有上限(`limits`);长循环的办法见 [cost.md](cost.md)。
@@ -0,0 +1,43 @@
1
+ # 按条件选与改
2
+
3
+ 按条件选出格、行或对象,再一次改掉它们:怎样先数再改,条件在哪些地方不按直觉走。条件的写法查 `help select.where`,字段名查 `help select.fields`,动作查 `help selection.edit`。
4
+
5
+ ## 先数再改
6
+
7
+ - 用 `query` 的 `select` 数出匹配数量(`select[0].total`),再用 `selection.edit` 修改,带上 `expectedMatches`。个数不符报 `SELECTION_COUNT_MISMATCH`(`details` 里有 `expected` 与 `actual`),这一步什么都不改。
8
+ - 先数和修改放在同一个脚本里做,中间不会有别的写入。
9
+ - 个数相符不证明选中的是你要的对象。改完看这一步响应里的 `selections[i].targets`:它列出改动之前的位置,只列前 100 个,多了带 `truncated:true`。
10
+ - `selection.edit` 的选择不带 `offset`、`limit`:改的总是完整的命中集,不能靠查询的分页挑着改。删行自下而上进行。
11
+ - 原生编辑里也有一个 `expectedMatches`(缺省 1),那是另一回事。
12
+
13
+ ## 条件的语义
14
+
15
+ - 列名不区分大小写;值的文本比较**区分**大小写,要不区分就写 `"caseSensitive":false`。
16
+ - 数字与文本不互转。数字列对文本值:`eq` 一个都不中,`ne` 全部命中,`gt` 这类比较不中、并在结果的 `diagnostics` 里记一条 `SELECTION_NON_COMPARABLE`(带个数与实际值的样本)。
17
+ - 查询完整而命中 0 个时,结果里有 `noMatch`(`SELECTION_NO_MATCH`),附每个条件实际遇到的值的样本。先看样本的类型与大小写,再判断是真的没有。
18
+ - 公式的值:不写 `"source":"calculation"` 时算未知。条件按三值逻辑合并:`any` 里有一个为真就是真,`all` 里有一个为假就是假;这样仍判不出的记在 `unavailable` 里,查询标 `status:"incomplete"`,`selection.edit` 报 `SELECTION_INCOMPLETE`、整步拒绝。
19
+ - 写了 `"source":"calculation"`,程序只算条件要用的格。`query` 里这时不要再显式写 `"mode":"none"`(`SELECTION_CALCULATION_REQUIRED`),省略 `calculation` 即可;`selection.edit` 在 `none` 的步骤里也会就地算。
20
+ - 行的三种目标:`{"kind":"rows","table":…}`、`{"kind":"rows","sheet":…,"range":…}`(第一行是表头)、只写 `{"kind":"rows"}` 让程序按列名找。最后一种优先找真正的 Table,否则推断表头区域,并在结果的 `binding` 里标 `stable:false`;先看它找对了没有。
21
+
22
+ ## 例
23
+
24
+ 把 `Amount` 不小于 1990 的行的 `Limit` 改成 0。`Amount` 一列里有公式,所以条件要写 `source:"calculation"`;不写的话 `found.status` 是 `incomplete`。
25
+
26
+ ```sh
27
+ cat > select-edit.js <<'EOF'
28
+ const selection = { target: { kind: 'rows', sheet: 'Sheet1', range: 'A1:D200' },
29
+ where: { column: 'Amount', operator: 'gte', value: 1990 }, source: 'calculation' };
30
+ const found = (await wb.query({ select: [{ ...selection, limit: 1 }] })).select[0];
31
+ if (found.status !== 'complete') throw new Error(`selection ${found.status}: ${JSON.stringify(found.unavailable)}`);
32
+ if (found.total === 0) return { matched: 0 };
33
+ const step = await wb.run({ op: 'selection.edit', selection, expectedMatches: found.total,
34
+ action: { kind: 'set', values: [{ column: 'Limit', value: 0 }] } });
35
+ return { matched: found.total, targets: step.result.selections[0].targets };
36
+ EOF
37
+ cat > select-edit.json <<'EOF'
38
+ {"input":"input.xlsx","output":"edited.xlsx","strict":true,"scriptPath":"select-edit.js"}
39
+ EOF
40
+ ./excel-kit script select-edit.json > select-edit.out.json
41
+ ```
42
+
43
+ 请求带 `"strict":true`,所以脚本里不用逐个判 `ok`:任何一次失败都会抛出(见 [scripts.md](scripts.md))。
@@ -0,0 +1,62 @@
1
+ # 逐条读应答的会话驱动
2
+
3
+ 下一步要看上一条应答才能定、又想让工作簿一直留在内存里时,自己驱动 `excel-kit session`:发一行,读一行。下面的例子顺带做了一件常见的事:同一个模板改一个输入,交付多份。会话的规则见 [sessions.md](sessions.md)。
4
+
5
+ ## 例
6
+
7
+ ```sh
8
+ python3 - <<'EOF'
9
+ import json, subprocess
10
+ from pathlib import Path
11
+
12
+ inputs = [100, 200, 300] # 每份交付改成的输入值
13
+ sheet, input_cell, target = "Sheet1", "B2", "B10"
14
+ out = Path("deliveries"); out.mkdir()
15
+ p = subprocess.Popen(["./excel-kit", "session"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
16
+ count = 0
17
+
18
+ def call(method, **params):
19
+ global count
20
+ count += 1
21
+ p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": count, "method": method,
22
+ "params": {"sessionId": "s", **params}}) + "\n")
23
+ p.stdin.flush()
24
+ reply = json.loads(p.stdout.readline())
25
+ if "error" in reply: # 协议层:这一行没有被当作请求执行
26
+ raise RuntimeError(reply["error"])
27
+ response = reply["result"]["response"] # 业务响应
28
+ if not response["ok"]:
29
+ raise RuntimeError(response.get("error") or response)
30
+ return response
31
+
32
+ try:
33
+ call("session.open", input="input.xlsx", output=str(out / "first.xlsx"), calculation={"mode": "none"})
34
+ call("session.run", operations=[{"op": "workbook.settings",
35
+ "calculation": {"mode": "auto", "fullCalcOnLoad": True}}])
36
+ for value in inputs:
37
+ step = call("session.run",
38
+ operations=[{"op": "write", "sheet": sheet, "range": input_cell, "values": [[value]]}],
39
+ calculation={"mode": "targets", "targets": [{"sheet": sheet, "range": target}]},
40
+ read=[{"sheet": sheet, "range": target, "form": "compact"}])
41
+ cell = step["result"]["ranges"][0]["rows"][0][0]
42
+ if cell["s"] != "result":
43
+ raise RuntimeError(cell)
44
+ saved = call("session.save", output=str(out / f"{value}.xlsx"))
45
+ if not saved["output"]["saved"]:
46
+ raise RuntimeError(saved)
47
+ print(value, cell["v"], saved.get("warnings"))
48
+ call("session.close")
49
+ finally:
50
+ p.stdin.close()
51
+ p.wait()
52
+ EOF
53
+ ```
54
+
55
+ ## 改成自己的任务时
56
+
57
+ - `call` 的两层判断都要留:先看应答顶层的协议 `error`,再看业务响应的 `ok`。一次只发一条、读一条,应答就与请求一一对应。失败就停;已经保存的文件仍在。
58
+ - 这是连续修改同一个会话:另存之后会话绑定刚保存的文件,下一轮从它继续,早先的交付件不被改写。不要每一份重新打开模板,保存之前也不需要再发一次 `all`。
59
+ - 打开时用 `none`,所以设置那一步不计算;每一份把写输入、只算目标、读取放在同一步。读取范围不等于计算范围:目标之外的格没有本次结果。
60
+ - 这样交付的文件里,目标之外受影响的公式没有当前值(保存时有 `FORMULAS_WITHOUT_VALUES`,步骤的 `calculation.scope.omittedFormulas` 是没算的个数),自动模式下缺值保存会设上打开重算,手动模式则警告,见 [deliverable.md](deliverable.md)。要尝试整本当前值可用 `all`,仍须检查不完整警告与清单。
61
+ - 模板里有 `CELL` 公式时不能这样换文件名另存,有模拟运算表时目标要避开依赖它的格,分别见 [sessions.md](sessions.md)、[deliverable.md](deliverable.md)。
62
+ - 大模型上给 `session.open` 带足 `timeoutMs`,各步沿用它。
@@ -0,0 +1,54 @@
1
+ # 会话
2
+
3
+ 会话怎样驱动、保存与另存的规则、哪些默认值与一次性命令不同。会话保证什么见 `SKILL.md` 第 2、5 条;各方法的参数查 `help session.<方法>`;协议的细节在 [api.md](api.md);逐条读应答的驱动见 [session-loop.md](session-loop.md)。
4
+
5
+ ## 两种驱动方式
6
+
7
+ - **整段管入**:`session.open` 时自己定 `sessionId`,后面的请求直接用它,整段对话一次送进标准输入。后面的请求看不到前面的应答,不能据此分支。
8
+ - **逐条读应答**:保持管道打开,发一行读一行,根据应答决定下一步。
9
+ - 执行环境不向子进程传标准输入时,会话收不到任何请求,也没有输出:改用 `run` 或 `script`。
10
+
11
+ ## 例:整段管入
12
+
13
+ ```sh
14
+ ./excel-kit session <<'EOF'
15
+ {"jsonrpc":"2.0","id":1,"method":"session.open","params":{"sessionId":"s","input":"input.xlsx","output":"output.xlsx","calculation":{"mode":"none"}}}
16
+ {"jsonrpc":"2.0","id":2,"method":"session.run","params":{"sessionId":"s","op":"write","sheet":"Sheet1","range":"B2","values":[[1200]]}}
17
+ {"jsonrpc":"2.0","id":3,"method":"session.run","params":{"sessionId":"s","operations":[{"op":"write","sheet":"Sheet1","range":"B3","values":[[300]]}],"calculation":{"mode":"all"},"read":[{"sheet":"Sheet1","range":"B10","form":"compact"}]}}
18
+ {"jsonrpc":"2.0","id":4,"method":"session.read","params":{"sessionId":"s","ranges":[{"sheet":"Sheet1","range":"B10","form":"compact"}]}}
19
+ {"jsonrpc":"2.0","id":5,"method":"session.save","params":{"sessionId":"s"}}
20
+ {"jsonrpc":"2.0","id":6,"method":"session.close","params":{"sessionId":"s"}}
21
+ EOF
22
+ ```
23
+
24
+ - 第 2 行是简写的一步,沿用打开时的 `none`,不计算。第 3 行要计算和读取,所以用完整写法;读到的值在这条应答的 `result.response.result.ranges`,`s` 是 `result`。
25
+ - 第 4 行随后再读同一格,值相同,`s` 却是 `cache`:`session.read` 不沿用计算方式,默认不计算。
26
+ - 每行应答按 `id` 对应请求,业务响应在 `result.response`。
27
+
28
+ ## 保存与另存
29
+
30
+ - `session.save` 不带 `output` 保存到当前目标;带 `output` 是另存,扩展名须与当前目标相同。另存成功后会话改为绑定新文件,早先的交付件不再被改写;所以一个会话可以依次交付多份。
31
+ - 原地编辑(`input` 与 `output` 是同一个文件)在 `session.open` 时就要给 `overwrite.expectedVersion`。
32
+ - 保存时目标已存在或被改过,报 `OUTPUT_EXISTS`、`TARGET_CHANGED`;确认覆盖的写法查 `help session.save`。来源与目标不是同一个文件、且还没保存过时,原始输入变了报 `SOURCE_CHANGED`,只能重新打开。保存被拒不改变会话状态,修正后可以再试。
33
+ - 没有可保存的东西时,保存返回 `{"ok":true,"status":"NO_CHANGES","output":{"saved":false}}`,不写文件:保存到当前目标,条件是自打开或上次保存以来没有成功的步骤;另存,条件是自打开以来没有成功的步骤。
34
+ - 想把一个没改动的工作簿另存为副本,先发一个空步骤 `session.run {}`。空步骤沿用打开会话时的计算方式;工作簿里有不支持的函数时,把它写成 `{"calculation":{"mode":"none"}}`。
35
+ - 工作簿里有 `CELL` 公式时,另存到别的文件名报 `FILE_IDENTITY_MISMATCH`,因为 `CELL` 的结果按当前文件路径计算。先保存到当前目标,再以它为输入、新文件为输出开一个新会话重算。
36
+
37
+ ## 与一次性命令不同的地方
38
+
39
+ - `session.run` 省略 `calculation`、`timeoutMs` 时沿用 `session.open` 上的。`session.read`、`session.query` 不沿用计算方式,默认不计算;期限 `session.read` 沿用,`session.query` 不沿用(没写就是 30000)。
40
+ - 时钟与随机种子在 `session.open` 时固定,整个会话取同一组值;要别的时钟就在 `calculation.clock` 里写。
41
+ - `session.read`、`session.query`、`session.inspect` 读的是内存里的当前状态,不访问磁盘。
42
+ - 没有 `audit` 方法:`session.query` 加 `"calculation":{"mode":"all"}` 就是它的默认行为。
43
+ - 不接受 `structure` 来源。相对路径按 `excel-kit session` 进程启动时的工作目录解析。
44
+ - 依赖透视结果的公式按保存的透视结果计算;要反映刷新后的透视,在刷新的那一步里读,见 [pivots.md](pivots.md)。续页的版本在会话里自动绑定,见 [paging.md](paging.md)。
45
+
46
+ ## 结束与取消
47
+
48
+ 标准输入关闭后,会话做完已经收到的请求,丢弃没保存的状态,退出码 0。取消一条请求用通知 `{"jsonrpc":"2.0","method":"$/cancel","params":{"id":<请求 id>}}`。信号、并发与协议错误见 [api.md](api.md)。
49
+
50
+ ## 试算与提交
51
+
52
+ 先记下当前版本。用 `help session.script` 的 `trial:true` 在该版本及其未保存编辑上试算。脚本只返回所需的普通 JSON。应答中的试算结果属于该情景,之后仍可在同一基准上换参数。选定后以原版本为 `expectedSessionVersion` 正常执行,再保存。
53
+
54
+ 需要增量读取时查 `help session.open`,打开时设 `reread:"precise"`。成功编辑后按 `reread.version` 重读列出的范围和图表对象。返回整簿时重新查询整簿。试算恢复后不发变更提示。
@@ -0,0 +1,31 @@
1
+ # 不支持的情形
2
+
3
+ 程序明确不支持什么,遇到时怎样交付、怎样向用户说明。找出具体是哪些格见 [audit.md](audit.md);函数层面的限制与 Excel 的已知差异见 [function-limits.md](function-limits.md);一个函数是否受支持查 `help fn.<函数名>`。
4
+
5
+ ## 总的做法
6
+
7
+ 先分清三件事:Excel 的错误值是计算所得;计算不可得是没有本次结果;保存被拒是没有发布(见 [calculation.md](calculation.md))。
8
+
9
+ 遇到下面的情形,不要绕过,也不要用文件里的存值冒充本次结果。要么用 `targets` 只交付不受影响的部分,要么停下来向用户说明,并写清需要用户在 Excel 里完成的事项。
10
+
11
+ 它们让本次需要的公式不可得时,`all/targets` 默认仍保存可靠结果并给逐格清单;`requireCompleteCalculation:true` 才拒绝。操作自己需要的当前值不可得仍拒绝。只是存在而不影响本次计算的不在此列:工作簿只含 VBA 工程而没有公式依赖它,或有口令保护但本次操作没有触及。不依赖它们的结果可以用 `targets` 计算并采信,但报告里不能说"整本已完整重算",也不要笼统地说"源文件有错",按具体原因分别说明。
12
+
13
+ ## 不支持的情形
14
+
15
+ - **VBA 不执行**:XLSM 可以编辑,VBA 工程原样保留,另存时扩展名保持 `.xlsm`。工作簿自带的 VBA 自定义函数报告 `UNSUPPORTED_FUNCTION`;定义名称里的 Excel 4 宏表函数(如 `GET.WORKBOOK`)同样不可得。依赖它们的格需要在 Excel 中启用宏后重算。
16
+ - **加密文件不编辑**:请用户提供解除加密的副本,不要尝试破解。
17
+ - **模拟运算表(dataTable)不重算**:程序原样保留它,表内结果和依赖它的本次计算都不可得;默认 `all` 仍发布其他可靠结果;不受支持的区域编辑或位移会被整体拒绝。改了它的输入之后,文件里留着的仍是旧的存值,见 [deliverable.md](deliverable.md)。用 `targets` 计算不依赖它的结果,并告诉用户运算表要在 Excel 里重算。
18
+ - **透视表不自动刷新**:依赖它的公式按保存的透视结果计算(与 Excel 重算不刷新透视相同),透视本身不算本次刷新;缓存设了打开时刷新的透视,依赖它的公式不可得,见 [pivots.md](pivots.md)。
19
+ - **外部工作簿引用不读取、不改写**:依赖它的结果不可得;只有已无任何使用的链接可以删除,见 [external-links.md](external-links.md)。
20
+ - **迭代计算不支持**:真实循环报告 `CIRCULAR_REFERENCE`,不按工作簿的迭代设置求解。
21
+ - **部分函数没有公开计算入口**:统计函数 `WEIBULL`、`F.INV`、`F.INV.RT`、`FINV`、`BINOM.INV`、`CRITBINOM` 仍不支持,直接调用报告 `UNSUPPORTED_FUNCTION`,受影响下游的诊断为 `INCOMPLETE_DEPENDENCY`;`WEIBULL.DIST` 与旧名 `WEIBULL` 的支持状态不同。完整入口以 `capabilities` 为准。
22
+ - **保留公式不等于支持计算**:`TRIMRANGE` 等公式及泰语辅助函数(如 `THAIDIGIT`、`THAINUMSTRING`)可以保留原生存储写法,但仍没有公开计算支持,不能把它们写成总会返回某个 Excel 错误的函数。
23
+ - **联合多区域引用**(如 `(A1:A3,C1:C3)` 或定义为多块区域的名称)可用于已支持的汇总与顺序统计参数;`AREAS` 也支持按区域项计数,重复、重叠和相邻区域不合并。其他不支持的位置报告 `UNSUPPORTED_UNION_REFERENCE`,不能从一个入口可用推断所有函数都支持联合引用。
24
+ - **整列 `XLOOKUP`/`XMATCH`**:空白查找值可能落到数据末行之后时会被拒绝。
25
+ - **省略引用的 `CELL`** 按公式所在格解释,与 Excel 的"最后改动格"不同;需要读取自身值的选择器会被拒绝。
26
+ - **口令保护**:不猜测、不移除校验,带口令的保护需要用户自行解除,见 [protection.md](protection.md)。
27
+ - **规模**:约百万公式级的整本计算可能超过期限的上限,见 [cost.md](cost.md)。
28
+
29
+ ## 核对的是什么
30
+
31
+ 保存时的核对是写出的文件与内存一致,不是与 Excel 一致。函数有公开入口,不代表所有参数组合都能计算或与 Excel 逐值相同。
package/release.json ADDED
@@ -0,0 +1,41 @@
1
+ {
2
+ "version": "0.10.0",
3
+ "protocol": 1,
4
+ "runtime": {
5
+ "name": "Bun",
6
+ "version": "1.4.2"
7
+ },
8
+ "sourceCommit": "55f6609f5fb719aa27ac2c0359bf7c7e7cd316ab",
9
+ "builtAt": "2026-11-19T08:51:39.008Z",
10
+ "sourceDigest": "2fb39e6a6058ec215c5ceb4ae854b6cdbae72c595e237add6dba595fb9895b9a",
11
+ "binaryRebuild": true,
12
+ "artifacts": [
13
+ {
14
+ "platform": "macos-arm64",
15
+ "binary": "excel-kit",
16
+ "bytes": 94920690,
17
+ "sha256": "2df9951126122207ed906129a197ace22d015760414ef36261e1e7c476dcd0a9",
18
+ "build": {
19
+ "inputs": "3edf226cc46a302a442109e94d97e0d43358935f66ab0ab7abd6eaa472aedffa"
20
+ }
21
+ },
22
+ {
23
+ "platform": "macos-x64",
24
+ "binary": "excel-kit",
25
+ "bytes": 101773584,
26
+ "sha256": "4380e4de7bc45c50e7af31b6e887d1e0dd09c0b8e79e6801a0af862f654b3ea9",
27
+ "build": {
28
+ "inputs": "b876cb8bc55824e8f3fc81ca811e083002ad5ee0a2b80794cc66de88545c2bf9"
29
+ }
30
+ },
31
+ {
32
+ "platform": "windows-x64",
33
+ "binary": "excel-kit.exe",
34
+ "bytes": 118537728,
35
+ "sha256": "c4ce062913292b9f4de865db66de1919bcaba2eb3ce2fe173f9a29cc8c0830f1",
36
+ "build": {
37
+ "inputs": "f9c05dc52f7d13ccdbe6ebe38d6b85a6d30d4985355559b43323a8fd21e14be2"
38
+ }
39
+ }
40
+ ]
41
+ }