@guandata/guanetl 0.1.38 → 0.1.40

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guanetl 0.1.40 - 2026-10-12
+
+- 无法读取服务端当前 ETL 版本时停止保存，避免用过期本地基线覆盖。
+- 初始化工作目录时清除旧导出结果；共享配置写入增加并发保护。
+- 平台包发布校验兼容 npm 12。
+
+## @guandata/guanetl 0.1.39 - 2026-10-12
+
+- ETL 保存接口即使返回 HTTP 200，只要结果为 `success=false` 就明确报错，并列出输入数据集校验失败项。
+- 更新任务级 profile 使用指引，明确环境切换方式。
+- 优化 `npm link` 开发场景提示：缺少本地构建时，提示执行 `npm run build`。
+
 ## @guandata/guanetl 0.1.38 - 2026-09-24
 
 - 修复 ETL 输入数据集类型误判：导出及校验时使用数据集详情中的实际类型，避免错误覆盖输入节点类型。

package/README.md

@@ -53,6 +53,17 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.40
+
+- 无法读取服务端当前 ETL 版本时停止保存，避免用过期本地基线覆盖。
+- 初始化工作目录时清除旧导出结果；共享配置写入增加并发保护。
+- 平台包发布校验兼容 npm 12。
+
+### @guandata/guanetl 0.1.39
+
+- ETL 保存接口返回 `success=false` 时明确报错并列出输入数据集校验结果，避免误报保存成功。
+- 从源码目录运行但尚未构建时，启动器会提示先执行 `npm run build`。
+
 ### @guandata/guanetl 0.1.38
 
 - 修复 ETL 输入数据集类型误判：导出及校验时使用数据集详情中的实际类型，避免错误覆盖输入节点类型。

package/bin/run.js

@@ -60,11 +60,24 @@ function resolvePlatformBinaries(options = {}) {
     // Local development fallback. The generated directory is excluded from
     // the published main package, so installed users always use the optional
     // platform dependency above.
-    const localBinDir = path.join(__dirname, "..", "platforms", target.suffix, "bin");
+    const pkgRoot = path.join(__dirname, "..");
+    const localBinDir = path.join(pkgRoot, "platforms", target.suffix, "bin");
     const binaryPaths = {};
     for (const binary of target.binaries) {
       const binaryPath = path.join(localBinDir, binary);
       if (!exists(binaryPath)) {
+        // scripts/ is not published, so this is a source checkout (npm link).
+        // npm link never installs the optional platform package; reinstalling
+        // from the registry would not help, the local build is missing.
+        if (exists(path.join(pkgRoot, "scripts", "build.js"))) {
+          throw new Error(
+            `Missing local build for ${key}: ${binaryPath}\n` +
+              `This ${PACKAGE_PREFIX} is a source checkout (npm link), which runs the ` +
+              `binaries built into platforms/ instead of the optional platform package.\n` +
+              `Build them first:\n` +
+              `  cd "${pkgRoot}" && npm run build`
+          );
+        }
         throw new Error(
           `Missing optional platform package ${target.packageName} for ${key}.\n` +
             `Reinstall without disabling optional dependencies:\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanetl",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "观远 ETL 本地开发工具 - 拉取、编辑、导出、预览、保存 ETL",
   "bin": {
     "guanetl": "bin/run.js"
@@ -41,11 +41,11 @@
     "node": ">=14"
   },
   "optionalDependencies": {
-    "@guandata/guanetl-darwin-arm64": "0.1.38",
-    "@guandata/guanetl-darwin-x64": "0.1.38",
-    "@guandata/guanetl-linux-x64": "0.1.38",
-    "@guandata/guanetl-linux-arm64": "0.1.38",
-    "@guandata/guanetl-win32-x64": "0.1.38"
+    "@guandata/guanetl-darwin-arm64": "0.1.40",
+    "@guandata/guanetl-darwin-x64": "0.1.40",
+    "@guandata/guanetl-linux-x64": "0.1.40",
+    "@guandata/guanetl-linux-arm64": "0.1.40",
+    "@guandata/guanetl-win32-x64": "0.1.40"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/guanetl/SKILL.md

@@ -31,7 +31,7 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 
 ### 0. 先确认前置条件
 
-- 确认底层 CLI 认证正常：普通 guancli profile 先执行 `guancli auth use <profile>`；上游托管 OIDC Token 时在当前进程同时设置 `GUANCLI_OIDC_BASE_URL`/`GUANCLI_OIDC_ACCESS_TOKEN`，无需本地 profile；guancli-lite 设置 `GUANCLI_BASE_URL`/`GUANCLI_TOKEN`。
+- 确认底层 CLI 认证正常：普通 guancli profile 用 `GUANCLI_PROFILE=<profile> guancli auth status` 验证，后续命令继续使用同一 `GUANCLI_PROFILE`，仅用户明确要求切换机器级默认环境时才用 `auth use`；上游托管 OIDC Token 时在当前进程同时设置 `GUANCLI_OIDC_BASE_URL`/`GUANCLI_OIDC_ACCESS_TOKEN`，无需本地 profile；guancli-lite 设置 `GUANCLI_BASE_URL`/`GUANCLI_TOKEN`。
 - 如果用户指定的资源（目录、数据集、ETL）搜索不到，先用 `guancli auth list` 列出所有可用环境，提示用户确认是否需要切换环境。
 
 ### Artifact contract（本地可测契约）
@@ -225,9 +225,11 @@ guanetl move <etl_id1> <etl_id2> --dir-id <etl_dir_id>
 
 `save --dry-run` 只执行到合并和保存影响检查，不执行第 4 步。
 
-新建 ETL 首次保存前，服务端还没有完整 ETL，因此 edit API 可能返回不存在。此时 `save` 会使用 `create` 生成的本地 `_base_etl.json`，并输出 `信息 [save.first_save_fallback]`；这是正常的首次保存路径，不代表 create 或 save 失败。其他服务端 edit 读取失败会输出 `警告 [save.edit_fallback]`，表示虽然已回退本地 base，但仍需确认网络、权限及本地基线是否可靠。
+新建 ETL 首次保存时，只有服务端明确返回 ETL 不存在、且本地 base 与工作区 ETL ID 一致并尚无 actions，`save` 才使用 `create` 生成的 `_base_etl.json`，输出 `信息 [save.first_save_fallback]`。其他 edit 读取失败会终止保存（包括 dry-run）；恢复网络或权限后重试，不能使用旧 base 覆盖服务端。
 
-用户不需要手写服务端保存 payload。只要 `etl/` 修改正确、`export` 通过，`save` 就能完成服务端保存。
+`edit` / `create` 重新初始化工作目录时会清除旧 `_exported.json`，包括重新编辑同一 ETL；必须重新 `export` 后再保存，避免把旧代码的导出写到新工作区。
+
+用户不需要手写服务端保存 payload。`export` 通过只表示本地产物可生成，保存仍由服务端校验。`direct-save` 返回 `success:false` 时，`save` 会非零退出并显示服务端原因与输入节点校验详情，不报告保存成功、不刷新本地 base；先处理失败原因，再重试保存，不要继续运行未保存的修改。
 
 ### run --wait、run --run-upstream 与任务状态
 

package/skills/guanetl/references/ETL_AI_DEVELOP.md

@@ -352,7 +352,7 @@ func DefineETL() []Node {
 
 `save` 会先拉取服务端当前 ETL，再把本地 `_exported.json` 合并进去。修改已保存 ETL 时，输出节点必须复用服务端已有输出数据集绑定，否则 direct-save 可能把它当成“创建新输出数据集”，触发“输出数据集目录中存在同名文件”。
 
-新建 ETL 首次保存时，服务端 edit API 可能返回 ETL 不存在。若当前本地 base 与工作区 ETL ID 一致且尚无 actions，CLI 会将其识别为正常首次保存回退并输出 `save.first_save_fallback`；其他 edit 故障使用 `save.edit_fallback` warning，不应静默当作首次保存。
+新建 ETL 首次保存时，只有服务端明确返回 ETL 不存在、且当前本地 base 与工作区 ETL ID 一致并尚无 actions，CLI 才回退本地 base 并输出 `save.first_save_fallback`。其他 edit 故障会终止保存及 dry-run；先恢复读取能力再重试，不能用旧 base 继续写入。
 
 当本地输出节点 id 被重新生成，但 `outputDsName + parentDirId` 与一个服务端已绑定输出唯一匹配时，`save` 会在请求副本中自动恢复原节点 id 和 dsId，并在影响报告中输出 `save.output_binding_reconciled`。源 `_exported.json` 不会被改写。跨目录、双方重名歧义、删除旧输出或无法唯一匹配时不会自动协调。