@guandata/guanetl 0.1.21 → 0.1.23

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## @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 脚本执行与文件交换，大型导出不再受小缓冲区限制。
+
 ## @guandata/guanetl 0.1.21 - 2026-07-23
 
 - JOIN 字段类型检查覆盖预览、保存和运行全过程，可提前发现字符串、数值、日期等类型不匹配风险。

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,15 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.23
+
+- ETL 写操作会准确提示实际目标环境，混合安装或切换环境时更容易确认操作位置。
+- 创建流程会明确区分本地工作区初始化和首次保存，避免把尚未保存误判为创建失败。
+
+### @guandata/guanetl 0.1.22
+
+- 增强受控 Agent 运行环境中的 ETL 脚本执行与文件交换，大型导出不再受小缓冲区限制。
+
 ### @guandata/guanetl 0.1.21
 
 - JOIN 字段类型检查覆盖预览、保存和运行全过程，可提前发现字符串、数值、日期等类型不匹配风险。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanetl",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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. 真正改代码前先读这些
 
 至少先读：
@@ -172,6 +179,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 +215,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` 就能完成服务端保存。