@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
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# 变更记录
|
|
2
|
+
|
|
3
|
+
## 0.9.0
|
|
4
|
+
|
|
5
|
+
- 共享大范围依赖,紧凑存放只有样式的空格,减少计算线程间的复制;不完整计算不再在主线程重复建图。
|
|
6
|
+
- 条件汇总复用索引,连续数组运算减少临时数组;按分配量回收计算临时对象。
|
|
7
|
+
- 修正 `VLOOKUP`/`HLOOKUP` 查到空格的语义,减少整列查找被未读取区域误判成循环的情况。
|
|
8
|
+
- 未设置 `refreshOnLoad="1"` 的原生透视当前保存值可作为下游公式输入;不将其声明为本次刷新。
|
|
9
|
+
- 修正 EXP 舍入差异被抵消放大的问题,保持其他函数和双精度运算次序不变。
|
|
10
|
+
- 首次通过 npm 平台包和本公开仓库发行,提供 11 个配方、agent 使用说明与主题参考。
|
|
11
|
+
|
|
12
|
+
实际验证和发行例外见 [VALIDATION.md](VALIDATION.md)。
|
package/DISTRIBUTION.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# 安装包验证
|
|
2
|
+
|
|
3
|
+
公开发行复用 0.9.0 已验收的三个独立程序,SHA-256 见 `release.json`。工作簿、性能、Excel 和三平台历史验收见 [VALIDATION.md](VALIDATION.md),本次不重复这些实验。
|
|
4
|
+
|
|
5
|
+
本次新增的是 Node.js 安装入口和 npm 平台包:入口只选择与平台相符、版本完全相同的程序,原样传递参数、标准输入输出、退出状态及取消信号,不做公式计算,不启动额外后台服务,也没有安装时下载脚本。
|
|
6
|
+
|
|
7
|
+
公开 Actions 只接受手动触发与 `release.json` 中固定的源码 SHA,用只读 Deploy Key 临时检出私有源码。构建日志不公开,artifact 只含三份已逐字节核对的程序,保留一天;不上传源码、完整构建 manifest、业务语料或测试结果。npm 发布在三个平台包全部准备并检查后串行进行,主包最后发布。
|
|
8
|
+
|
|
9
|
+
发布前检查包文件清单、权限、许可、平台选择及错误路径;在 macOS ARM64 上从打包文件进行干净安装,核对版本、标准输入、会话和退出行为。公开发布后再从 registry 实际安装核对。Windows 和 macOS x64 的程序本体复用既有验证,安装入口在这些系统上的实际 npm 安装尚未重跑,不将本机检查外推为三平台新验收。
|
|
10
|
+
|
|
11
|
+
包内示例是合成数据或另附许可的第三方 fixture,不含私有业务工作簿。公开仓库不包含核心源码、源码构建脚本、测试、内部证据或其提交历史。
|
|
12
|
+
|
|
13
|
+
许可仅允许个人非商业使用,禁止商用与再分发。第三方组件仍适用各自许可。
|
package/LICENSE
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
excel-kit 使用许可 / Use License
|
|
2
|
+
Copyright (c) 2026 dztabel-happy. All rights reserved.
|
|
3
|
+
|
|
4
|
+
本许可适用于 excel-kit 官方发行的程序、安装入口、文档及自有示例。
|
|
5
|
+
它不是开源许可。公开下载不代表授予再分发权或核心源码许可。
|
|
6
|
+
|
|
7
|
+
允许:
|
|
8
|
+
1. 自然人免费安装、运行本软件,仅用于个人非商业活动。
|
|
9
|
+
2. 为本人的上述使用制作必要副本和备份。
|
|
10
|
+
3. 在上述使用范围内修改请求、示例和脚本以完成个人任务。
|
|
11
|
+
4. 在个人非商业活动中使用、编辑和分享自己处理的工作簿与结果;
|
|
12
|
+
本许可不对用户文件及结果主张所有权。第三方输入材料的权利仍须尊重。
|
|
13
|
+
|
|
14
|
+
不允许:
|
|
15
|
+
禁止将本软件用于商业活动,包括企业经营、受雇工作、付费服务、
|
|
16
|
+
商业项目及为组织或客户处理业务材料。商业使用须另获书面许可。
|
|
17
|
+
未经权利人另行书面许可,不得向第三方再分发、转售、镜像、重新
|
|
18
|
+
打包、公开发布本软件或其自有内容(包括修改版本);不得将其作为
|
|
19
|
+
其他产品的一部分分发。需要使用时,请引导用户从官方地址下载:
|
|
20
|
+
https://github.com/dztabel-happy/excel-kit
|
|
21
|
+
https://www.npmjs.com/package/@dztabel/excel-kit
|
|
22
|
+
|
|
23
|
+
本许可不授予访问、披露或再许可 excel-kit 核心源码的权利。未明确
|
|
24
|
+
授予的权利全部保留。个人副本应保留本许可及第三方声明。
|
|
25
|
+
|
|
26
|
+
本软件按现状提供,不提供适销性、特定用途适用性或计算结果符合
|
|
27
|
+
任意场景的保证。在适用法律允许的范围内,权利人不对使用本软件
|
|
28
|
+
造成的损失承担责任。请按任务需要核对输出及其计算状态。
|
|
29
|
+
|
|
30
|
+
第三方组件、样本及其许可独立适用,见 THIRD-PARTY-NOTICES.txt
|
|
31
|
+
与各样本目录中的 LICENSE/NOTICE。本许可不限制这些第三方许可
|
|
32
|
+
已授予的权利,也不将它们的许可扩展至 excel-kit 自有内容。
|
|
33
|
+
|
|
34
|
+
Use is permitted only for personal, non-commercial activities, including
|
|
35
|
+
necessary personal copies, backups, and adaptation of examples for that use.
|
|
36
|
+
Commercial use, including business operations, employment, paid services,
|
|
37
|
+
commercial projects or processing business materials for organizations or
|
|
38
|
+
clients, requires separate written permission.
|
|
39
|
+
Redistribution, resale, mirroring, repackaging or publication of the software
|
|
40
|
+
or its proprietary materials, including modified versions, requires separate
|
|
41
|
+
written permission. No ownership of user workbook outputs is claimed.
|
|
42
|
+
No rights to the proprietary core source code are granted.
|
|
43
|
+
The software is provided AS IS, without warranties, to the extent permitted
|
|
44
|
+
by applicable law. Third-party components retain their separate licenses.
|
|
45
|
+
The Chinese text above states the complete terms of this license.
|
package/README.md
CHANGED
|
@@ -1,3 +1,75 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">excel-kit</h1>
|
|
2
|
+
<p align="center">让 agent 读取、编辑、计算并交付可继续使用的 Excel 工作簿。</p>
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
把本地工作簿和任务要求交给能执行命令的 agent。excel-kit 负责读取、修改、计算及保存 XLSX/XLSM,返回结构化结果和需要处理的问题。处理文件时不依赖 Excel、LibreOffice 或云端服务。
|
|
5
|
+
|
|
6
|
+
**许可:仅限个人非商业使用,禁止商用和再分发。** 商业使用须另获书面许可;完整条款见 [LICENSE](LICENSE)。
|
|
7
|
+
|
|
8
|
+
- **批量整理与汇总**:清洗个人记录、去重、关联分类、追加 Table、更新汇总。
|
|
9
|
+
- **模型与预算调整**:调整个人预算或学习模型的假设、计算指定结果、滚动到下一期间,保留公式和格式。
|
|
10
|
+
- **模板与交付**:填写模板、设置验证和保护、检查公式问题,保存新的工作簿。
|
|
11
|
+
|
|
12
|
+
## 安装
|
|
13
|
+
|
|
14
|
+
### 1. 安装命令行程序
|
|
15
|
+
|
|
16
|
+
已有 Node.js 20 或更新版本时:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm install -g @dztabel/excel-kit
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
npm 自动安装当前平台的程序。支持 macOS ARM64/x64、Windows x64;Windows ARM64 使用 x64 仿真程序。当前没有 Linux 发行包。
|
|
23
|
+
|
|
24
|
+
无需 Node.js 的安装方式:从 [Releases](https://github.com/dztabel-happy/excel-kit/releases) 下载对应平台的 ZIP,核对同页 `SHA256SUMS` 后解压。macOS 执行 `./excel-kit`,Windows 执行 `.\excel-kit.exe`,也可将所在目录加入 PATH。
|
|
25
|
+
|
|
26
|
+
### 2. 确认安装
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
excel-kit version
|
|
30
|
+
excel-kit help
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
当前版本应返回 `cli: "0.9.0"`、`protocol: 1`。帮助首页是索引,`excel-kit help <名称>` 查询具体命令、操作或函数。
|
|
34
|
+
|
|
35
|
+
### 3. 交给 agent 使用
|
|
36
|
+
|
|
37
|
+
让 agent 先阅读 [SKILL.md](SKILL.md),再给出文件路径和任务,例如:
|
|
38
|
+
|
|
39
|
+
> 用 excel-kit 整理我的家庭支出,按编号去重,关联分类表,更新月度汇总。保留原件,另存为新的工作簿,并说明未能计算的内容。
|
|
40
|
+
|
|
41
|
+
> 把我的学习用预算模型滚动到下一期间,保留公式、格式和打印设置;更新给出的假设,并核对总金额。
|
|
42
|
+
|
|
43
|
+
`SKILL.md`、`reference/` 和 11 个[配方](recipes/README.md)也包含在 npm 安装目录中。全局安装目录可用 `npm root -g` 查找,其下的 `@dztabel/excel-kit/` 就是说明目录。使用配方前将其复制到工作目录,按对应 README 执行。
|
|
44
|
+
|
|
45
|
+
## 调用方式
|
|
46
|
+
|
|
47
|
+
| 方式 | 适合的任务 |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `run`/`batch` | 事先能写全的编辑、计算与核对步骤 |
|
|
50
|
+
| `session` | 边看边改,跨调用保留工作簿,最后保存或另存 |
|
|
51
|
+
| `script` | 在一个工作簿事务中循环、分支、根据中间结果继续操作 |
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
excel-kit inspect input.xlsx
|
|
55
|
+
excel-kit run request.json
|
|
56
|
+
excel-kit help session
|
|
57
|
+
excel-kit help script
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
请求由 agent 按任务与帮助生成。命令返回 JSON,既要检查 `ok`,也要检查计算状态和值来源:`ok:true` 可以伴随不完整计算;文件里的历史缓存不代表本次算出的结果。要求整本算完才能保存时,显式设置 `requireCompleteCalculation:true`。
|
|
61
|
+
|
|
62
|
+
## 范围与版本
|
|
63
|
+
|
|
64
|
+
0.9.0 主要降低大工作簿的内存占用,并修正查找空值、透视结果读取与 EXP 舍入问题。实际验证、发行例外和资源边界见 [VALIDATION.md](VALIDATION.md),版本变化见 [CHANGELOG.md](CHANGELOG.md)。
|
|
65
|
+
|
|
66
|
+
不执行 VBA,不编辑加密文件,不提供多工作簿依赖求值。具体函数边界见 [函数限制](reference/function-limits.md),未支持范围见 [unsupported.md](reference/unsupported.md)。脚本不是安全沙箱,只运行可信代码。内存与时间取决于文件结构,不能保证所有大表都在固定预算内完成。
|
|
67
|
+
|
|
68
|
+
## 安装排查
|
|
69
|
+
|
|
70
|
+
- 提示缺少平台包:重新执行 `npm install -g --include=optional @dztabel/excel-kit`,不要省略 optional dependencies。
|
|
71
|
+
- 安装后找不到命令:确认 npm 全局可执行目录已加入 PATH,或使用 `npx @dztabel/excel-kit version`。
|
|
72
|
+
- 不使用 npm:ZIP 内含独立运行时,不需要安装 Bun、Python 或办公软件。
|
|
73
|
+
- Node.js 客户端通过子进程调用 CLI/[JSON-RPC 会话](reference/api.md);本 npm 包不导出工作簿内核库。
|
|
74
|
+
|
|
75
|
+
本仓库用于公开构建、安装入口和使用说明,正式程序在 Release 和 npm 平台包中。构建仅由维护者手动触发,只传出已核对摘要的程序;核心源码始终保存在独立私有仓库。许可范围见 [LICENSE](LICENSE),第三方声明见 [THIRD-PARTY-NOTICES.txt](THIRD-PARTY-NOTICES.txt)。问题反馈请附版本、操作和可公开的最小样本,勿上传敏感工作簿。
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: excel-kit
|
|
3
|
+
description: 需要在本地读取、编辑、重算并保存 XLSX/XLSM 工作簿,且已安装 excel-kit 命令或解压程序包时使用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# excel-kit
|
|
7
|
+
|
|
8
|
+
npm 安装后运行 `excel-kit <命令>`。以下命令以此为例;ZIP 用户在包目录用 `./excel-kit`(Windows 是 `.\excel-kit.exe`)替代命令名。`run`、`query` 这类命令读一份 JSON 请求文件;每个响应在标准输出上占一行 JSON,大的输出先存文件再解析取字段,按行用 `head` 截不短它。先 `excel-kit inspect input.xlsx` 看有哪些工作表与对象,再把要做的事写成一份请求:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
cat > edit.json <<'EOF'
|
|
12
|
+
{"input":"input.xlsx","output":"output.xlsx",
|
|
13
|
+
"operations":[{"op":"write","sheet":"Sheet1","range":"B2","values":[[1200]]}],
|
|
14
|
+
"read":[{"sheet":"Sheet1","range":"B10","form":"compact"}]}
|
|
15
|
+
EOF
|
|
16
|
+
excel-kit run edit.json > edit.out.json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
只读不改用 `query`:请求里同样写 `read`,没有 `output`。输出旁的 `.excel-kit-*.lock.guard.sqlite` 是写入锁留下的,不是交付物,也不要删。操作名与参数查 `excel-kit help <名字>`。动手前要知道的是下面八条;其余按文末的表读一篇。
|
|
20
|
+
|
|
21
|
+
## 契约
|
|
22
|
+
|
|
23
|
+
### 1. `run` 是事务
|
|
24
|
+
|
|
25
|
+
读入 `input`、执行 `operations`、计算、写出并读回核对、原子替换 `output`,任何一步失败都不动 `output`。`output` 已存在就拒绝,除非在 `overwrite.expectedVersion` 给出它当前的版本;核对的是写出的文件与内存一致,不是与 Excel 一致。
|
|
26
|
+
|
|
27
|
+
### 2. 四种调用方式
|
|
28
|
+
|
|
29
|
+
默认用一次 `run`,改动、计算、读取写进同一份请求。其余三种:
|
|
30
|
+
|
|
31
|
+
- `batch`:多个写好的步骤各自成败。默认一步失败就都不发布;`commit:"successful"` 允许只发布成功的步骤,这时返回 `ok:false`、`status:"partial"`。
|
|
32
|
+
- `script`:下一步取决于上一步的结果。正常返回后尝试发布成功的步骤;失败的 `wb.run` 只是没生效,不影响外层的 `ok`,要看 `script.stepFailures`;抛错、超时等才整体回滚。`strict:true` 让失败的 `wb.*` 抛错:不捕获就整体回滚并带出原错误,捕获了就只是那次没生效。
|
|
33
|
+
- `session`:跨调用保留工作簿,可另存多份。`session.run` 只改内存,失败的一步不留痕迹;`session.save` 才写文件,没保存就结束则修改丢弃。
|
|
34
|
+
|
|
35
|
+
批次和脚本有没有写文件,看 `output.saved`。
|
|
36
|
+
|
|
37
|
+
### 3. 值的来源
|
|
38
|
+
|
|
39
|
+
紧凑读取(`"form":"compact"`,数据在 `rows`,`cells` 是空数组)里公式格是 `{"f","v","s"}`。`s` 为 `result` 才是本次请求算出的当前值;`cache` 是文件里存着的上次结果;`invalidated` 是被本次修改作废的存值,`v` 仍是旧数;`unavailable` 是没有值。`result` 只出现在算它的那次请求里:刚算好并保存的值,下一次不计算的读取里就是 `cache`。
|
|
40
|
+
|
|
41
|
+
### 4. 计算方式
|
|
42
|
+
|
|
43
|
+
- `all`:尝试整本计算;不完整也发布可得结果,`ok:true`、`calculation.status:"incomplete"`,并给 `CALCULATION_INCOMPLETE` 警告。要旧的拒绝行为,在请求顶层写 `requireCompleteCalculation:true`。
|
|
44
|
+
- `targets`:算列出的格及其全部上游,只保证这些格。其余受本次修改影响的普通公式在文件里没有值(警告 `FORMULAS_WITHOUT_VALUES`),不重算的读取方看到的就是没有值。
|
|
45
|
+
- `none`:不做最后的重算,受影响的普通公式同上;操作自己要当前值时仍会就地算一小块。
|
|
46
|
+
|
|
47
|
+
普通公式缺值保存时,`auto/autoNoTable` 自动设 `fullCalcOnLoad:true`(覆盖原 false/缺省);手动模式保留并警告。模拟运算表失效缓存仍保留,`autoNoTable` 仍需人工重算。完整不可得清单在发布时给出的 JSONL 文件,读法见 [deliverable.md](reference/deliverable.md)。
|
|
48
|
+
|
|
49
|
+
省略 `calculation`:`run`、`preflight`、`audit` 是 `all`;批次步骤、`session.run`、`wb.run` 沿用批次根、`session.open`、脚本请求上的那个;读取和查询不沿用,读取默认 `none`。
|
|
50
|
+
|
|
51
|
+
### 5. 取值与判失败
|
|
52
|
+
|
|
53
|
+
先看 `ok`;失败的响应不保证有成功时的字段。
|
|
54
|
+
|
|
55
|
+
- `run`、`preflight`、`read`、`query`:错误在顶层 `error`。读取在顶层 `ranges`,其他查询在同名键。读取算不完整时 `ok:false` 而没有 `error`,看 `calculation`。
|
|
56
|
+
- `batch`:每步在 `batch.steps[i]`,读取在其 `result.ranges`,错误在其 `error`;整批中止或执行前被拒才有顶层 `error`,后者没有 `batch`。
|
|
57
|
+
- `script`:返回值在 `script.result`,错误在顶层 `error`。
|
|
58
|
+
- 会话:每行应答的 `result.response` 才是业务响应,错误在其 `error`;`session.run` 的读取在其 `result.ranges`。
|
|
59
|
+
|
|
60
|
+
协议层成功不等于做成了:JSON-RPC 应答有 `result`、退出码 0 只说明请求被处理,它顶层的 `error` 只报协议错误。`ok:true` 也要看:保存步骤和 `query` 的 `calculation.status` 都可以是 `incomplete`;算完整了、`s` 是 `result` 的值也可以是 `{"e":"#DIV/0!"}` 等错误值。
|
|
61
|
+
|
|
62
|
+
### 6. 什么贵
|
|
63
|
+
|
|
64
|
+
贵的是步数与整本重算:每个写步骤都把整本写出再读回核对,每次读取、查询都重新解析整本;只要少数结果用 `targets`,中间步骤用 `none`。默认期限 30 秒(`timeoutMs`,上限 300000)。硬上限在 `capabilities` 的 `limits`。
|
|
65
|
+
|
|
66
|
+
### 7. 怎么查
|
|
67
|
+
|
|
68
|
+
- `help` 是索引;`help <名字>` 查一项,主题、操作、原生编辑用本名,其余带类别前缀,如 `query.<种类>`、`session.<方法>`、`wb.<成员>`、`fn.<函数名>`;`help all <主题>` 给全文;`help find <词…>` 按名字和描述找。
|
|
69
|
+
- `capabilities`:程序认得的全部名字,不保证参数都能算。
|
|
70
|
+
- `inspect <文件>`:工作簿概况与文件版本,不计算;其余对象用 `query` 查。
|
|
71
|
+
- `preflight`:把同一份 `run` 请求在内存里完整做一遍而不写文件。它查输出目录在不在、`output` 是否已存在;不占写入锁,不查能否写入,不保证之后没人改文件。
|
|
72
|
+
|
|
73
|
+
### 8. 选择与数量断言
|
|
74
|
+
|
|
75
|
+
`query` 的 `select` 与 `selection.edit` 用同一套条件。`expectedMatches` 只核对个数:个数相符不证明选中的是你要的对象,改完看 `selections[i].targets`。条件涉及公式的值要写 `source:"calculation"`,否则公式的值算未知,整个条件因此判不出时,查询标 `status:"incomplete"`,`selection.edit` 整步拒绝。文本的值比较区分大小写,数字与文本不互转(`"001"` 不等于 `1`);写错不报错,只是选错。
|
|
76
|
+
|
|
77
|
+
## 下一跳
|
|
78
|
+
|
|
79
|
+
参数与字段只在 `help` 里。`reference/` 下每篇只讲一个主题里推不出来的语义,按情形读一篇:
|
|
80
|
+
|
|
81
|
+
| 情形 | 读 |
|
|
82
|
+
|---|---|
|
|
83
|
+
| 读单元格、在代码里取值 | `reference/reading.md` |
|
|
84
|
+
| 一页读不完、要续页(`READ_TOO_LARGE`、`VERSION_REQUIRED`) | `reference/paging.md` |
|
|
85
|
+
| 写请求、覆盖文件(`OUTPUT_EXISTS`)、预检、批次、`FILE_BUSY` | `reference/editing-and-saving.md` |
|
|
86
|
+
| 按条件选出或批量修改 | `reference/selection.md` |
|
|
87
|
+
| 决定算多少、读懂计算范围 | `reference/calculation.md` |
|
|
88
|
+
| 核对交付件;公式没有值(`FORMULAS_WITHOUT_VALUES`);要 Excel 打开时重算 | `reference/deliverable.md` |
|
|
89
|
+
| 慢、超时(`*_TIMEOUT`)、工作簿大 | `reference/cost.md` |
|
|
90
|
+
| 计算不完整警告或严格拒绝(`CALCULATION_INCOMPLETE`),要找源头与影响范围 | `reference/audit.md` |
|
|
91
|
+
| 宏、加密、模拟运算表等不支持项,怎样向用户说明 | `reference/unsupported.md` |
|
|
92
|
+
| 某个函数算不出来或与 Excel 不同 | `reference/function-limits.md` |
|
|
93
|
+
| 不认识的错误码、错误里的 `suggestions` | `reference/errors.md` |
|
|
94
|
+
| 下一步取决于上一步的结果 | `reference/scripts.md` |
|
|
95
|
+
| 边看边改、一次打开交付多份 | `reference/sessions.md`,可运行的驱动在 `reference/session-loop.md` |
|
|
96
|
+
| 工作表或工作簿受保护 | `reference/protection.md` |
|
|
97
|
+
| 有透视表或切片器 | `reference/pivots.md` |
|
|
98
|
+
| 公式引用别的工作簿 | `reference/external-links.md` |
|
|
99
|
+
| 自己实现会话的客户端 | `reference/api.md` |
|
|
100
|
+
|
|
101
|
+
现成的脚本在 `recipes/README.md`,验证范围在 `VALIDATION.md`。
|