@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,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
|
+
脚本什么时候发布、失败留下什么,见 `SKILL.md` 第 2 条;请求的键与 `wb` 的成员查 `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`。
|
|
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,48 @@
|
|
|
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)。
|
|
@@ -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.9.0",
|
|
3
|
+
"protocol": 1,
|
|
4
|
+
"runtime": {
|
|
5
|
+
"name": "Bun",
|
|
6
|
+
"version": "1.4.2"
|
|
7
|
+
},
|
|
8
|
+
"sourceCommit": "2b0432997cc1d68f30eddf78648197d257b5c361",
|
|
9
|
+
"builtAt": "2026-11-15T02:36:02.054Z",
|
|
10
|
+
"sourceDigest": "4b54b86467b76b5a47e6cdbe0b967f96dbbdbfd634cf34bc3dd5b36ecff728e0",
|
|
11
|
+
"binaryRebuild": false,
|
|
12
|
+
"artifacts": [
|
|
13
|
+
{
|
|
14
|
+
"platform": "macos-arm64",
|
|
15
|
+
"binary": "excel-kit",
|
|
16
|
+
"bytes": 94656498,
|
|
17
|
+
"sha256": "6ee295691e30c622ad1e37aebb930b72b3085df2eb32c972bb3db67d89df31e0",
|
|
18
|
+
"build": {
|
|
19
|
+
"inputs": "10e3ed5c6f4897b40031ed4c4197db3e6fde3ce0f806568e888e03ddc1319c7c"
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"platform": "macos-x64",
|
|
24
|
+
"binary": "excel-kit",
|
|
25
|
+
"bytes": 101511440,
|
|
26
|
+
"sha256": "452e94386788d83f0f75cf0028074a5a0698184a972ce5f8e75b727f82b61773",
|
|
27
|
+
"build": {
|
|
28
|
+
"inputs": "41504f3e90c43dd919e379497316cf52179c09711b877d21fd091ae80fc278cd"
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"platform": "windows-x64",
|
|
33
|
+
"binary": "excel-kit.exe",
|
|
34
|
+
"bytes": 118278144,
|
|
35
|
+
"sha256": "25a12c8356fbb7a30a0bc58ef9b16c994d37a7c680364267cc8c603ab113533f",
|
|
36
|
+
"build": {
|
|
37
|
+
"inputs": "532fdde35d5b84adec09d0abb69026e79265f2e893f6739f982815166f176507"
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
]
|
|
41
|
+
}
|