@guandata/guanetl 0.1.24 → 0.1.26

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guanetl 0.1.26 - 2026-08-07
+
+- 新增输出数据集落位闭环校验，并同步目录意图，提升 ETL 保存、运行后的结果一致性。
+- 修复 ETL 编辑往返时配置丢失问题，并拦截 JOIN 未知类型，增强配置保真与校验可靠性。
+- `save` 影响报告新增字段级变更明细，便于使用者了解保存操作的具体影响。
+- 修复工作流输出绑定中的字段错位问题，提升输出配置的准确性。
+## @guandata/guanetl 0.1.25 - 2026-08-04
+
+- ETL 已在运行时可直接跟踪当前任务，无需管理员级全局任务权限。
+- 执行完成后会核验新增输出字段是否已完成物化、注册并可查询，避免任务成功但字段不可用。
+- 预览输出会明确区分 CLI 展示行数与后端样本或数据集总量，减少对数据规模的误判。
+
 ## @guandata/guanetl 0.1.24 - 2026-07-29
 
 - ETL 预览支持一次选择多个节点，并按批次并行执行，复杂流程的检查效率更高。

package/README.md

@@ -32,7 +32,7 @@ guanetl save --dir <work_dir>
 
 `create` 只申请 `dataFlowId` 并初始化本地工作区，首次 `save` 成功后才形成可被服务端 `get/edit/move` 查询和操作的完整 ETL。首次 `save` 时若服务端尚无 edit 基线，CLI 会输出 `信息 [save.first_save_fallback]` 并使用本地 base，这是正常路径。`警告 [save.edit_fallback]` 则表示其他 edit 读取故障后发生了兼容回退，需要检查网络、权限和本地基线。
 
-> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息；如果同一 ETL 已被级联触发并正在运行，`run --wait` 会改为等待当前运行中的任务。触发前会检查直接上游数据集状态和服务端 JOIN 键类型；发现风险时先告警但继续执行，可分别用 `--skip-upstream-check`、`--skip-join-type-check` 跳过检查。
+> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息；如果同一 ETL 已被级联触发并正在运行，`run --wait` 会通过当前 ETL 的最近执行信息恢复 taskId 并等待，不需要查询管理员级全局运行任务列表。触发前会检查直接上游数据集状态和服务端 JOIN 键类型；发现风险时先告警但继续执行，可分别用 `--skip-upstream-check`、`--skip-join-type-check` 跳过检查。
 > `run --run-upstream` 会包含目标 ETL 本身，并对计划内每个 ETL 等待终态；任一上游执行失败时会停止后续节点。
 
 新建 ETL 时注意目录树不同：`create --parent-dir` 使用 ETL 目录树 id，输出数据集目录使用 DATA_SET 目录树 id。可用 `guancli etl tree` / `guancli ds tree` 分别查询，或用 `guanetl mkdir-pair` 成对创建。`guancli workflow tree` 是工作流/经典数据流目录树，不能作为智能 ETL 的 `create --parent-dir`。
@@ -51,6 +51,18 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.26
+
+- 新增输出数据集落位校验，提升 ETL 保存和运行后的结果一致性。
+- 修复 ETL 编辑往返时配置丢失和输出绑定字段错位问题。
+- 保存影响报告补充字段级变更明细，便于了解具体调整内容。
+
+### @guandata/guanetl 0.1.25
+
+- ETL 已在运行时可直接跟踪当前任务，无需管理员级全局任务权限。
+- 执行完成后会核验新增输出字段是否已完成物化、注册并可查询，避免任务成功但字段不可用。
+- 预览输出会明确区分 CLI 展示行数与后端样本或数据集总量，减少对数据规模的误判。
+
 ### @guandata/guanetl 0.1.24
 
 - ETL 预览支持一次选择多个节点，并按批次并行执行，复杂流程的检查效率更高。
@@ -83,7 +95,7 @@ guanetl install-skill
 
 - 新增 `move` 命令，支持将一个或多个智能 ETL 移动到指定 ETL 目录，并在接口异常时读回确认移动结果。
 - `run` 新增 `--run-upstream` 与配套 `--dry-run`，支持递归解析智能 ETL 上游链路、按拓扑顺序执行并等待每个节点完成。
-- `run --wait` 遇到同一 ETL 已在运行的 40001 响应时，会查找当前运行中的任务并等待其完成，减少级联触发后重复 run 的误判失败。
+- `run --wait` 遇到同一 ETL 已在运行的 40001 响应时，会从当前 ETL 的最近执行信息恢复 taskId 并等待其完成，不依赖管理员级全局运行任务接口。
 - `export` 静态检查新增 JOIN 键类型不一致 warning，提示 STRING/LONG 等隐式 coercion 风险。
 
 ### @guandata/guanetl 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanetl",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "观远 ETL 本地开发工具 - 拉取、编辑、导出、预览、保存 ETL",
   "bin": {
     "guanetl": "bin/run.js"

package/skills/guanetl/SKILL.md

@@ -153,9 +153,11 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 
 `save` 会协调已保存 ETL 的输出身份：当本地 `OUTPUT_DATASET` 节点 id 变化，但它与服务端已绑定输出在同一目录、同名且双方唯一时，CLI 会自动恢复原节点 id 和 dsId，继续原地更新已有输出数据集。该协调不会修改本地 `_exported.json`，保存影响报告会显示 `save.output_binding_reconciled`。
 
+**输出数据集落位语义（重要，勿用 dsId 判断输出是否创建）**：服务端保存时总会给每个输出补一个 `dataSource{dsId, created:false}`，但在该 ETL **首次成功运行**之前数据集实体并不存在，且每次 save/run 都会重新生成一个全新的临时 dsId。因此"保存后 dsId 非空"不代表输出已创建；判断依据是 `dataSource.created == true`。`save` 成功后 CLI 会回读服务端并输出两类诊断：`save.output_dir_rectified` 表示 `parentDirId` 无效、已被服务端静默纠正（通常纠正到数据集根目录，页面"保存至"可能显示"请选择"）——必须修正 etl.go 中的目录 id 后重新保存；`save.output_pending_materialization` 表示输出尚未物化，dsId 是临时值，勿用于下游引用。`run --wait` 成功后 CLI 会校验输出 `created == true`，存在未创建的输出会直接报错，按错误提示排查目录与节点连线，不要循环重试 save/run。例外：仅以顶层 dsId 绑定已有数据集且无 `dataSource` 的增量输出无法自动核验，会以 `run.output_placement_unverified` 警告提示，需用 `guancli etl get <etl_id> --raw` 人工确认（默认渲染不显示 `dataSource.created` 字段）。
+
 如果 `save` 在 direct-save 前提示输出数据集绑定风险，按提示处理，不要手动删除或重命名旧输出数据集。跨目录、重名歧义、删除旧输出或无法唯一匹配时，CLI 不会猜测并默认停止保存。修复优先级：重新 `edit` 到新目录、同步 `outputDsName`、确认输出目录；确实要替换已绑定输出时，设置新的节点 id、`outputDsName` 或 `parentDirId`，并显式加 `--allow-output-replacement`。该选项只放行保存，不会迁移任何下游 dsId 引用。
 
-只追加输出列是安全例外：新增列、不改名、不删已有列、不改已有列类型，并保持输出名称和目录时，可以原地 `save`，保存前仍需 `preview` 目标输出确认结果。改列名、删列、改类型、换输入数据集或重接输出链路仍按下游 schema 风险处理；输出节点 id 变化仅在唯一匹配时自动协调。
+只追加输出列只是在输出绑定层面的安全例外：新增列、不改名、不删已有列、不改已有列类型，并保持输出名称和目录时，可以原地 `save`，保存前仍需 `preview` 目标输出确认结果；这**不代表**旧 DATAFLOW 数据集已注册该字段。`run --wait` 对本轮新增且透传到输出的 `BasicCalculator` 字段，会逐个输出等待其自身的 `lastExecution.endTime` 与 `datasourceModifyTime` 推进，并同时检查数据集 metadata 和实际 preview 返回字段。任一目标输出仍在产出，或字段没有注册/不可查询，命令会以错误结束；可用 `--timeout` 延长这段校验时间。改列名、删列、改类型、换输入数据集或重接输出链路仍按下游 schema 风险处理；输出节点 id 变化仅在唯一匹配时自动协调。
 
 保存前优先执行 `save --dry-run` 查看影响报告；`--format json` 可用于自动化检查。dry-run 不调用 direct-save，若报告出现阻断风险，先修 `etl/` 后重新 `export -> preview -> save --dry-run`。
 如果报告出现“输出字段风险”，表示同一输出数据集中的同名字段发生类型或来源变化，服务端可能重建该列 fdId；保存前先用 `guands dataset cards <输出dsId>` 看下游卡片，保存执行后再按列名核对并重绑页面卡片 fdId。

package/skills/guanetl/references/ETL_AI_DEVELOP.md

@@ -357,7 +357,7 @@ func DefineETL() []Node {
 当本地输出节点 id 被重新生成，但 `outputDsName + parentDirId` 与一个服务端已绑定输出唯一匹配时，`save` 会在请求副本中自动恢复原节点 id 和 dsId，并在影响报告中输出 `save.output_binding_reconciled`。源 `_exported.json` 不会被改写。跨目录、双方重名歧义、删除旧输出或无法唯一匹配时不会自动协调。
 
 - 再次修改已保存 ETL，优先重新执行 `guanetl edit <etl_id> --dir <新目录>`，不要长期复用旧工作目录。
-- 只追加输出列时，可以原地 `save`：新增列，不改名、不删已有列、不改已有列类型，并保持原 `OUTPUT_DATASET` 节点 id 和 `outputDsName`。
+- 只追加输出列时，可以原地 `save`：新增列，不改名、不删已有列、不改已有列类型，并保持原 `OUTPUT_DATASET` 节点 id 和 `outputDsName`；但这只保证输出身份稳定，不保证旧 DATAFLOW 数据集的字段目录已同步。对新增并透传到输出的 `BasicCalculator` 字段，必须执行 `guanetl run <etlId> --wait`：命令会按输出数据集独立等待本轮物化，并同时验证 metadata 与实际 preview 返回字段；任一目标输出尚未完成或字段缺失都会报错。
 - 修改已有输出 schema 时，保持原 `OUTPUT_DATASET` 节点 id；改列名、删列、改已有列类型、换输入数据集或重接输出链路都可能影响下游绑定，保存前必须重新 `preview` 并评估下游。
 - 如果用 `guands dataset rename` 改过 ETL 输出数据集名称，必须同步 `etl.go` 中 `BasicOutputDataset(..., outputDsName, ...)` 或 `BasicOutputDatasetInDir(..., outputDsName, ...)` 的名称。
 - 不要为了绕过同名错误手动删除旧输出数据集；旧输出通常仍被 ETL 依赖。