@guandata/guanetl 0.1.38 → 0.1.39

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @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,11 @@ guanetl install-skill
 
 ## 版本更新
 
+### @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.39",
   "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.39",
+    "@guandata/guanetl-darwin-x64": "0.1.39",
+    "@guandata/guanetl-linux-x64": "0.1.39",
+    "@guandata/guanetl-linux-arm64": "0.1.39",
+    "@guandata/guanetl-win32-x64": "0.1.39"
   },
   "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（本地可测契约）
@@ -227,7 +227,7 @@ guanetl move <etl_id1> <etl_id2> --dir-id <etl_dir_id>
 
 新建 ETL 首次保存前，服务端还没有完整 ETL，因此 edit API 可能返回不存在。此时 `save` 会使用 `create` 生成的本地 `_base_etl.json`，并输出 `信息 [save.first_save_fallback]`；这是正常的首次保存路径，不代表 create 或 save 失败。其他服务端 edit 读取失败会输出 `警告 [save.edit_fallback]`，表示虽然已回退本地 base，但仍需确认网络、权限及本地基线是否可靠。
 
-用户不需要手写服务端保存 payload。只要 `etl/` 修改正确、`export` 通过，`save` 就能完成服务端保存。
+用户不需要手写服务端保存 payload。`export` 通过只表示本地产物可生成，保存仍由服务端校验。`direct-save` 返回 `success:false` 时，`save` 会非零退出并显示服务端原因与输入节点校验详情，不报告保存成功、不刷新本地 base；先处理失败原因，再重试保存，不要继续运行未保存的修改。
 
 ### run --wait、run --run-upstream 与任务状态