@guandata/guanetl 0.1.22 → 0.1.24

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## @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` 也会在远端变更前提示目标。
+- `create` 明确区分 dataFlowId 申请、本地工作区初始化与首次 `save` 服务端持久化，避免把首次保存前的 ETL 不存在误判为创建失败。
+
 ## @guandata/guanetl 0.1.22 - 2026-07-25
 
 - 增强受控 Agent 运行环境中的 ETL 脚本执行与文件交换，大型导出不再受小缓冲区限制。

package/README.md

@@ -26,9 +26,11 @@ guanetl save --dir <work_dir>
 
 标准 ETL 写入闭环：`create/edit → export → preview → save → run --wait`。如果目标 ETL 依赖的智能 ETL 上游也需要刷新，可先用 `guanetl run <etl_id> --run-upstream --dry-run` 查看拓扑计划，再用 `guanetl run <etl_id> --run-upstream` 从最上游依次执行并等待完成。
 
+多环境操作使用 `GUANCLI_PROFILE=<profile>` 固定当前进程链。写命令会先解析实际底层 CLI，再在 stderr 回显对应目标：`guancli` 显示 profile，`guancli-lite` 显示脱敏后的 `GUANCLI_BASE_URL` 主机，自定义 shim 不推测其环境语义；`task cancel` 同样会在远端变更前回显。可先运行 `GUANCLI_PROFILE=<profile> guancli auth status` 核对环境名和 URL，不需要切换机器级默认 profile。
+
 `preview` 返回 0 行时默认输出 warning 并保持兼容的成功退出码；自动化发布或要求输出必须有数据时使用 `preview --require-nonempty`，并仅在命令成功后继续 `save`。
 
-新建 ETL 首次 `save` 时若服务端尚无 edit 基线，CLI 会输出 `信息 [save.first_save_fallback]` 并使用本地 base，这是正常路径。`警告 [save.edit_fallback]` 则表示其他 edit 读取故障后发生了兼容回退，需要检查网络、权限和本地基线。
+`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` 跳过检查。
 > `run --run-upstream` 会包含目标 ETL 本身，并对计划内每个 ETL 等待终态；任一上游执行失败时会停止后续节点。
@@ -49,6 +51,17 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.24
+
+- ETL 预览支持一次选择多个节点，并按批次并行执行，复杂流程的检查效率更高。
+- 创建 ETL 后会直接显示可编辑的 `etl.go` 骨架，Agent 可立即继续编写和保存流程。
+- 优化大型目录树的查询指引，并更新底层依赖以提升安全性和运行稳定性。
+
+### @guandata/guanetl 0.1.23
+
+- ETL 写操作会准确提示实际目标环境，混合安装或切换环境时更容易确认操作位置。
+- 创建流程会明确区分本地工作区初始化和首次保存，避免把尚未保存误判为创建失败。
+
 ### @guandata/guanetl 0.1.22
 
 - 增强受控 Agent 运行环境中的 ETL 脚本执行与文件交换，大型导出不再受小缓冲区限制。
@@ -136,7 +149,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.22",
+  "version": "0.1.24",
   "description": "观远 ETL 本地开发工具 - 拉取、编辑、导出、预览、保存 ETL",
   "bin": {
     "guanetl": "bin/run.js"

package/skills/guanetl/SKILL.md

@@ -79,6 +79,13 @@ guancli ds get <ds_id>
 guancli ds preview <ds_id> --limit 20
 ```
 
+多环境操作时，使用 `GUANCLI_PROFILE=<profile>` 固定当前进程链的目标环境，不修改机器级默认 profile。写操作会先按 `GUANCLI_PATH → PATH 中 guancli → PATH 中 guancli-lite` 解析实际底层 CLI，再在 stderr 回显对应目标：`guancli` 显示 profile，`guancli-lite` 显示脱敏后的 `GUANCLI_BASE_URL` 主机，自定义 shim 则明确提示目标由该 CLI 决定。`task cancel` 等远端状态变更命令也遵循该规则。执行前可用同一环境变量运行 `guancli auth status`，核对环境名和 URL：
+
+```bash
+GUANCLI_PROFILE=dev33 guancli auth status
+GUANCLI_PROFILE=dev33 guanetl create --name "ETL名称" --dir <work_dir>
+```
+
 ### 3. 真正改代码前先读这些
 
 至少先读：
@@ -133,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            # 可选：保存后触发执行并等待完成
@@ -160,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>
 ```
 
@@ -172,6 +183,8 @@ guanetl create --name "ETL名称" --dir <work_dir>
 guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --output-parent-dir <dataset_dir_id>
 ```
 
+`create` 只向服务端申请 `dataFlowId` 并初始化本地工作区，不代表完整 ETL 已持久化。首次 `save` 成功前，服务端 `get/edit/move` 可能返回 ETL 不存在；完成 `etl.go -> export -> preview -> save` 后再执行这些服务端操作。
+
 `create` / `save` 会校验目录 id 类型：`--parent-dir` 必须来自 ETL 树，输出数据集目录必须来自 DATA_SET 树。只有在确认目录 id 正确但当前账号无法读取目录树时，才使用 `--skip-dir-check`。
 如果错误提示目录 id 属于 `MASTER_FLOW`，说明拿到了工作流/经典数据流目录 id；智能 ETL 改用 `guancli etl tree` 查询，工作流/数据流创建改用 `guanwf create --parent-dir`。
 
@@ -206,7 +219,7 @@ guanetl move <etl_id1> <etl_id2> --dir-id <etl_dir_id>
 
 `save --dry-run` 只执行到合并和保存影响检查，不执行第 4 步。
 
-新建 ETL 首次保存前，服务端可能还没有可供 edit API 读取的完整基线。此时 `save` 会使用 `create` 生成的本地 `_base_etl.json`，并输出 `信息 [save.first_save_fallback]`；这是正常的首次保存路径，不代表 create 或 save 失败。其他服务端 edit 读取失败会输出 `警告 [save.edit_fallback]`，表示虽然已回退本地 base，但仍需确认网络、权限及本地基线是否可靠。
+新建 ETL 首次保存前，服务端还没有完整 ETL，因此 edit API 可能返回不存在。此时 `save` 会使用 `create` 生成的本地 `_base_etl.json`，并输出 `信息 [save.first_save_fallback]`；这是正常的首次保存路径，不代表 create 或 save 失败。其他服务端 edit 读取失败会输出 `警告 [save.edit_fallback]`，表示虽然已回退本地 base，但仍需确认网络、权限及本地基线是否可靠。
 
 用户不需要手写服务端保存 payload。只要 `etl/` 修改正确、`export` 通过，`save` 就能完成服务端保存。