@guandata/guanetl 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guanetl 0.1.25 - 2026-08-04
+
+- ETL 已在运行时可直接跟踪当前任务，无需管理员级全局任务权限。
+- 执行完成后会核验新增输出字段是否已完成物化、注册并可查询，避免任务成功但字段不可用。
+- 预览输出会明确区分 CLI 展示行数与后端样本或数据集总量，减少对数据规模的误判。
+
+## @guandata/guanetl 0.1.24 - 2026-07-29
+
+- ETL 预览支持一次选择多个节点，并按批次并行执行，复杂流程的检查效率更高。
+- 创建 ETL 后会直接显示可编辑的 `etl.go` 骨架，Agent 可立即继续编写和保存流程。
+- 优化大型目录树的查询指引，并更新底层依赖以提升安全性和运行稳定性。
+
 ## @guandata/guanetl 0.1.23 - 2026-07-28
 
 - 写操作会按 clifetch 实际选中的 `guancli`、`guancli-lite` 或自定义 CLI 回显目标环境，避免混合安装时提示与真实写入环境相反；`task cancel` 也会在远端变更前提示目标。

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.25
+
+- ETL 已在运行时可直接跟踪当前任务，无需管理员级全局任务权限。
+- 执行完成后会核验新增输出字段是否已完成物化、注册并可查询，避免任务成功但字段不可用。
+- 预览输出会明确区分 CLI 展示行数与后端样本或数据集总量，减少对数据规模的误判。
+
+### @guandata/guanetl 0.1.24
+
+- ETL 预览支持一次选择多个节点，并按批次并行执行，复杂流程的检查效率更高。
+- 创建 ETL 后会直接显示可编辑的 `etl.go` 骨架，Agent 可立即继续编写和保存流程。
+- 优化大型目录树的查询指引，并更新底层依赖以提升安全性和运行稳定性。
+
 ### @guandata/guanetl 0.1.23
 
 - ETL 写操作会准确提示实际目标环境，混合安装或切换环境时更容易确认操作位置。
@@ -77,7 +89,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
@@ -143,7 +155,4 @@ npm unlink -g @guandata/guanetl
 ```bash
 # 编译所有平台 binary（需要 Go 工具链）
 npm run build
-
-# 发布到内部 Nexus npm 仓库
-npm publish
 ```

package/package.json

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

package/skills/guanetl/SKILL.md

@@ -140,7 +140,10 @@ guanetl edit <etl_id> --dir <work_dir>
 ```bash
 guanetl export --dir <work_dir>
 # 保存闭环默认要求预览至少返回 1 行；明确允许合法空结果时可省略 --require-nonempty
-guanetl preview <node_id> --dir <work_dir> --require-nonempty
+# 多输出 ETL 一次传多个节点 ID：分批并行执行（默认同时最多 2 个任务，对齐 BI
+# 单用户预览并发上限）、结果按序输出，不要逐节点调用；若网页端另有预览在跑
+# 导致提交被拒，加 --max-parallel 1 串行重试
+guanetl preview <node_id> [node_id...] --dir <work_dir> --require-nonempty
 guanetl save --dir <work_dir> --dry-run
 guanetl save --dir <work_dir>
 guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待完成
@@ -152,7 +155,7 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 
 如果 `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。
@@ -167,8 +170,9 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 2. 如需在指定子目录下创建，先分别确认 ETL 目录树和数据集目录树。两棵树相互独立，同名目录的 id 也不同，不能把 `guancli etl get` 输出节点里的 ParentDirId 当作 `create --parent-dir` 使用。`guancli workflow tree` 返回的是工作流/经典数据流目录树，也不能用于智能 ETL 的 `create --parent-dir`。
 
 ```bash
-guancli etl tree       # ETL 所在目录，用于 create --parent-dir
-guancli ds tree        # 输出数据集目录，用于 create --output-parent-dir / BasicOutputDatasetInDir
+guancli etl tree --max-depth 2       # ETL 所在目录，用于 create --parent-dir
+guancli ds tree --max-depth 2        # 输出数据集目录，用于 create --output-parent-dir / BasicOutputDatasetInDir
+# 目录树很大时用 --keyword 词 过滤；--max-depth 0（默认不传）为全量
 guanetl mkdir-pair "ODS" --etl-parent <etl_parent_id> --ds-parent <ds_parent_id>
 ```
 

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 依赖。