@guandata/guanetl 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guanetl 0.1.19 - 2026-07-08
+
+- 新增 `move` 命令，支持将一个或多个智能 ETL 移动到指定 ETL 目录，并在接口异常时读回确认移动结果。
+- `run` 新增 `--run-upstream` 与配套 `--dry-run`，支持递归解析智能 ETL 上游链路、按拓扑顺序执行并等待每个节点完成。
+- `run --wait` 遇到同一 ETL 已在运行的 40001 响应时，会查找当前运行中的任务并等待其完成，减少级联触发后重复 run 的误判失败。
+- `export` 静态检查新增 JOIN 键类型不一致 warning，提示 STRING/LONG 等隐式 coercion 风险。
+
 ## @guandata/guanetl 0.1.18 - 2026-07-01
 
 - 创建 ETL 时目录类型诊断更清晰，会识别误用工作流/经典数据流目录的场景，并提示使用智能 ETL 目录。

package/README.md

@@ -23,13 +23,16 @@ guanetl save --dir <work_dir>
 
 说明：npm 包名为 `@guandata/guanetl`，用户侧 CLI 命令统一为 `guanetl`。
 
-标准 ETL 写入闭环：`create/edit → export → preview → save → run --wait`。
+标准 ETL 写入闭环：`create/edit → export → preview → save → run --wait`。如果目标 ETL 依赖的智能 ETL 上游也需要刷新，可先用 `guanetl run <etl_id> --run-upstream --dry-run` 查看拓扑计划，再用 `guanetl run <etl_id> --run-upstream` 从最上游依次执行并等待完成。
 
-> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息。触发前会检查直接上游数据集状态；若发现上游处于失败态，会先输出警告但继续执行，可用 `--skip-upstream-check` 跳过检查。
+> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息；如果同一 ETL 已被级联触发并正在运行，`run --wait` 会改为等待当前运行中的任务。触发前会检查直接上游数据集状态；若发现上游处于失败态，会先输出警告但继续执行，可用 `--skip-upstream-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`。
 
-`export` 成功后会自动输出本地静态检查提示；其中 `BasicCalculator` 的每个 `Formula` 都应显式填写 `Type`，否则可能导致下游原生 GroupBy/Join 节点出现静态类型警告。
+移动已有 ETL 使用 `guanetl move <etl_id> [etl_id...] --dir-id <etl_dir_id>`；目标目录同样来自 `guancli etl tree`，可先加 `--dry-run` 查看请求体。
+
+`export` 成功后会自动输出本地静态检查提示；其中 `BasicCalculator` 的每个 `Formula` 都应显式填写 `Type`，否则可能导致下游原生 GroupBy/Join 节点出现静态类型警告。JOIN 键两侧类型不一致时会提示隐式 coercion 风险，建议统一键类型。
 
 也可以为 AI Coding Assistant 安装 Skill：
 
@@ -39,6 +42,13 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.19
+
+- 新增 `move` 命令，支持将一个或多个智能 ETL 移动到指定 ETL 目录，并在接口异常时读回确认移动结果。
+- `run` 新增 `--run-upstream` 与配套 `--dry-run`，支持递归解析智能 ETL 上游链路、按拓扑顺序执行并等待每个节点完成。
+- `run --wait` 遇到同一 ETL 已在运行的 40001 响应时，会查找当前运行中的任务并等待其完成，减少级联触发后重复 run 的误判失败。
+- `export` 静态检查新增 JOIN 键类型不一致 warning，提示 STRING/LONG 等隐式 coercion 风险。
+
 ### @guandata/guanetl 0.1.18
 
 - 创建 ETL 时目录类型诊断更清晰，会识别误用工作流/经典数据流目录的场景，并提示使用智能 ETL 目录。

package/package.json

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

package/skills/guanetl/SKILL.md

@@ -145,6 +145,7 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 只追加输出列是安全例外：新增列、不改名、不删已有列、不改已有列类型，并保持原 `OUTPUT_DATASET` 节点 id 和 `outputDsName` 时，可以原地 `save`，保存前仍需 `preview` 目标输出确认结果。改列名、删列、改类型、换输入数据集、重接输出链路或更换输出节点 id 都按下游绑定风险处理。
 
 保存前优先执行 `save --dry-run` 查看影响报告；`--format json` 可用于自动化检查。dry-run 不调用 direct-save，若报告出现阻断风险，先修 `etl/` 后重新 `export -> preview -> save --dry-run`。
+如果报告出现“输出字段风险”，表示同一输出数据集中的同名字段发生类型或来源变化，服务端可能重建该列 fdId；保存前先用 `guands dataset cards <输出dsId>` 看下游卡片，保存执行后再按列名核对并重绑页面卡片 fdId。
 
 ### 新建 ETL
 
@@ -167,9 +168,16 @@ guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --o
 `create` / `save` 会校验目录 id 类型：`--parent-dir` 必须来自 ETL 树，输出数据集目录必须来自 DATA_SET 树。只有在确认目录 id 正确但当前账号无法读取目录树时，才使用 `--skip-dir-check`。
 如果错误提示目录 id 属于 `MASTER_FLOW`，说明拿到了工作流/经典数据流目录 id；智能 ETL 改用 `guancli etl tree` 查询，工作流/数据流创建改用 `guanwf create --parent-dir`。
 
+移动已有智能 ETL 用 `move`，目标目录同样必须来自 `guancli etl tree`。可先加 `--dry-run` 查看将提交的 `/api/etl/move` 请求体；批量移动直接追加多个 ETL ID：
+
+```bash
+guanetl move <etl_id> --dir-id <etl_dir_id> --dry-run
+guanetl move <etl_id1> <etl_id2> --dir-id <etl_dir_id>
+```
+
 4. 在 `etl/` 中实现 ETL。
 5. 再执行 `export -> preview -> save`。
-6. 需要立即执行时：`run <etl_id> --wait`。
+6. 需要立即执行时：`run <etl_id> --wait`；需要先刷新可识别的智能 ETL 上游链路时，先用 `run <etl_id> --run-upstream --dry-run` 看计划，再用 `run <etl_id> --run-upstream` 执行。
 
 ### 修复失败
 
@@ -193,12 +201,14 @@ guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --o
 
 用户不需要手写服务端保存 payload。只要 `etl/` 修改正确、`export` 通过，`save` 就能完成服务端保存。
 
-### run --wait 与任务状态
+### run --wait、run --run-upstream 与任务状态
 
 > **触发成功 ≠ ETL 执行成功**。`run` 返回 `✓ ETL 执行已触发` 仅表示后端接受了执行请求，ETL 可能在运行中失败。
 
 - 不加 `--wait` 时，`run` 只触发并返回 `taskId`。
 - 加 `--wait` 后，CLI 会轮询任务状态直到终态（FINISHED / FAILED / CANCELED），FAILED 时会展示真实错误消息。
+- 需要递归刷新智能 ETL 上游链路时，用 `run <etl_id> --run-upstream`。CLI 会读取目标 ETL 的输入数据集，按数据集的生产 ETL 继续向上解析，生成拓扑顺序后从最上游依次执行，包含目标 ETL；每个 ETL 都会等待终态，任一失败即停止并报告失败节点。
+- 不确定上游范围时，先用 `run <etl_id> --run-upstream --dry-run` 输出执行计划；dry-run 只读拓扑，不触发任何 ETL。
 - 触发前，`run` 会检查直接上游数据集状态；若发现上游处于 `FAILED`/`失败` 态，会先输出警告但继续触发执行。确认不需要检查时可加 `--skip-upstream-check`。
 - 如果不加 `--wait` 后想查状态：`task status <taskId>` 或 `task wait <taskId>`。