@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
package/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # 变更记录
2
+
3
+ ## 0.10.0
4
+
5
+ - 新增图表系列与副轴编辑、直方图和箱线图、透视日期分组与筛选、条件格式和验证展示。
6
+ - 会话支持按版本提交、试算并恢复未保存状态,成功后按范围和图表重读。
7
+ - 支持两个工作簿的内容比较、带版本和引用绑定的跨簿区域迁移、条件透视指标和文字截断查询。
8
+ - 随包提供新组合配方;skill 入口按任务链接到 19 个专题。
9
+
10
+ ## 0.9.0
11
+
12
+ - 共享大范围依赖,紧凑存放只有样式的空格,减少计算线程间的复制;不完整计算不再在主线程重复建图。
13
+ - 条件汇总复用索引,连续数组运算减少临时数组;按分配量回收计算临时对象。
14
+ - 修正 `VLOOKUP`/`HLOOKUP` 查到空格的语义,减少整列查找被未读取区域误判成循环的情况。
15
+ - 未设置 `refreshOnLoad="1"` 的原生透视当前保存值可作为下游公式输入;不将其声明为本次刷新。
16
+ - 修正 EXP 舍入差异被抵消放大的问题,保持其他函数和双精度运算次序不变。
17
+ - 首次通过 npm 平台包和本公开仓库发行,提供 11 个配方、agent 使用说明与主题参考。
18
+
19
+ 实际验证和发行例外见 [VALIDATION.md](VALIDATION.md)。
@@ -0,0 +1,13 @@
1
+ # 安装包验证
2
+
3
+ 公开发行使用 Bun 1.4.2 从同一固定版本构建三个独立程序,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 实际安装核对。历史三平台验收按版本保留,安装入口在这些系统上的实际 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
- # Temporary Holding Version
1
+ <h1 align="center">excel-kit</h1>
2
+ <p align="center">让 agent 读取、编辑、计算并交付可继续使用的 Excel 工作簿。</p>
2
3
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.10.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/` 和 12 个[配方](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.10.0 新增图表系列和统计图、透视规则、跨工作簿局部迁移、两版内容比较、会话试算、精细重读和文字截断检查。实际验证、发行例外和资源边界见 [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,52 @@
1
+ ---
2
+ name: excel-kit
3
+ description: 用 ExcelKit 处理本地 XLSX/XLSM。适用于 agent 需要了解陌生工作簿、核对两个版本、编辑公式与原生对象、试算方案或交付可继续编辑的 Excel 文件时。
4
+ ---
5
+
6
+ # ExcelKit
7
+
8
+ 先用 `excel-kit inspect <文件>` 找工作表、名称、Table、对象及文件版本。把任务拆成要查明的事实、要改的对象和验收用的格或绑定。用 `excel-kit help find <英文关键词>` 找入口,再用精确帮助查字段。一次能说清的修改写进 `run` 的 `operations`,把验收用的 `read` 放在同一次计算里。独立程序包在当前目录用 `./excel-kit`,Windows 用 `.\excel-kit.exe`。
9
+
10
+ ### 1. 确定输入与输出
11
+
12
+ `preflight` 执行并核对一次拟议的修改,返回已绑定版本的执行请求。需要确认覆盖、迁移或影响范围时使用。一次 `run` 原子发布到 `output`。替换已有文件必须给出 `overwrite.expectedVersion`。[编辑、预检与保存](reference/editing-and-saving.md)
13
+
14
+ ### 2. 选择执行方式
15
+
16
+ 步骤已知,用一次 run。多个分别计成败的步骤用 `batch`。需要根据中间值判断、循环或断言,用 `script` 和 `strict:true`。跨调用积累未保存编辑用 `session`;在当前状态探索多个情景,用 `session.script` 的 `trial:true` 取回结果。以 `output.saved` 确认文件实际发布。[脚本](reference/scripts.md) · [会话、试算与重读](reference/sessions.md)
17
+
18
+ ### 3. 读值时确认来源
19
+
20
+ 紧凑读取的公式格看 `s`。本次计算为 `result`,历史保存值为 `cache`,已失效为 `invalidated`,没有可用值为 `unavailable`。需要解释差异时先看公式和输入,再查上下游。[读取与取值](reference/reading.md) · [双文件比较与续页](reference/paging.md)
21
+
22
+ ### 4. 决定要算多少
23
+
24
+ 中间编辑用 `none`,核对指定指标用 `targets`,交付要求整本当前结果时用 `all` 并检查完整性。缺普通公式值时自动模式可以设置 `fullCalcOnLoad`,手动模式要读警告。[计算范围](reference/calculation.md) · [交付核对](reference/deliverable.md)
25
+
26
+ ### 5. 用响应决定下一步
27
+
28
+ 先看业务响应的 `ok` 和 `error`,会话从 `result.response` 取。再看计算状态、目标格是否为 Excel 错误值,以及步骤是否实际保存。根据错误提供的位置和恢复建议重选范围、补绑定或修改请求。[错误恢复](reference/errors.md) · [审计与依赖](reference/audit.md)
29
+
30
+ ### 6. 控制读取和计算成本
31
+
32
+ 先取一个有代表性的范围。续页绑定版本,将同一轮需要的编辑和读数组合起来。遇到超时先检查计算范围、步骤数与 `timeoutMs`,上限见 capabilities 的 `limits`。[成本与期限](reference/cost.md)
33
+
34
+ ### 7. 查本机能力并组合
35
+
36
+ `inspect` 给工作簿事实,`capabilities` 给当前程序识别的名称,`help <精确名称>` 给请求契约。按对象用 `help query.<种类>` 查可读取的状态,然后选修改操作,再确定如何验证。例如迁移模型区块前用 `help compare` 定位内容差异,查 `help range.transfer` 了解源绑定和目标覆盖授权,必要时用 `preflight`。涉及某个函数时单查 `help fn.<函数名>`。[跨簿绑定](reference/external-links.md) · [函数边界](reference/function-limits.md)
37
+
38
+ ### 8. 验证选中的对象
39
+
40
+ 批量选择先核对地址、名称或系列身份。`expectedMatches` 只能断言数量;按公式当前值选择时指定 `source:"calculation"`。用版本绑定后的结果复核实际目标,再决定提交。[条件选择](reference/selection.md)
41
+
42
+ ## 按任务深入
43
+
44
+ | 需要判断的事 | 按需阅读 |
45
+ |---|---|
46
+ | 指标在分组、总计和刷新之后如何计算 | [透视与切片器](reference/pivots.md) |
47
+ | 交付前检查换行文字、图表系列或原生规则 | [版面与对象](reference/presentation.md) |
48
+ | 能否编辑受保护的区域,怎样恢复权限 | [保护](reference/protection.md) |
49
+ | 写自己的会话客户端 | [协议与调用方式](reference/api.md) · [逐条应答驱动](reference/session-loop.md) |
50
+ | 文件含宏、外部来源或不受支持的对象 | [保留与计算边界](reference/unsupported.md) |
51
+
52
+ 程序包的 `recipes/README.md` 索引可运行的组合示例,`VALIDATION.md` 说明该版本的实测范围。