@guandata/guanetl 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## @guandata/guanetl 0.1.22 - 2026-07-25
+
+- 增强受控 Agent 运行环境中的 ETL 脚本执行与文件交换，大型导出不再受小缓冲区限制。
+
+## @guandata/guanetl 0.1.21 - 2026-07-23
+
+- JOIN 字段类型检查覆盖预览、保存和运行全过程，可提前发现字符串、数值、日期等类型不匹配风险。
+- 增强字段别名、计算字段和多级上游 ETL 的识别，复杂 ETL 保存与运行前的诊断更准确。
+- 优化多数据集结构读取效率，批量检查复杂 ETL 时等待更少。
+
 ## @guandata/guanetl 0.1.20 - 2026-07-20
 
 - `save` 会按“同一输出目录 + 同名 + 唯一匹配”自动恢复已绑定输出的节点 id 和 dsId，避免 AI 重写输出节点 id 时误建新数据集并断开下游依赖。

package/README.md

@@ -30,14 +30,14 @@ guanetl save --dir <work_dir>
 
 新建 ETL 首次 `save` 时若服务端尚无 edit 基线，CLI 会输出 `信息 [save.first_save_fallback]` 并使用本地 base，这是正常路径。`警告 [save.edit_fallback]` 则表示其他 edit 读取故障后发生了兼容回退，需要检查网络、权限和本地基线。
 
-> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息；如果同一 ETL 已被级联触发并正在运行，`run --wait` 会改为等待当前运行中的任务。触发前会检查直接上游数据集状态；若发现上游处于失败态，会先输出警告但继续执行，可用 `--skip-upstream-check` 跳过检查。
+> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息；如果同一 ETL 已被级联触发并正在运行，`run --wait` 会改为等待当前运行中的任务。触发前会检查直接上游数据集状态和服务端 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`。
 
 移动已有 ETL 使用 `guanetl move <etl_id> [etl_id...] --dir-id <etl_dir_id>`；目标目录同样来自 `guancli etl tree`，可先加 `--dry-run` 查看请求体。
 
-`export` 成功后会自动输出本地静态检查提示；其中 `BasicCalculator` 的每个 `Formula` 都应显式填写 `Type`，否则可能导致下游原生 GroupBy/Join 节点出现静态类型警告。JOIN 键两侧类型不一致时会提示隐式 coercion 风险，建议统一键类型。
+`export` 成功后会自动输出本地静态检查提示；`preview` 和 `save` 也会在远端调用前重新检查 `_exported.json`。其中 `BasicCalculator` 的每个 `Formula` 都应显式填写 `Type`，否则可能导致下游原生 GroupBy/Join 节点出现静态类型警告。JOIN 键两侧类型不一致时会提示隐式 coercion 风险；STRING 与数值类型 JOIN 时，纯数字字符串可能匹配，`"001"` 可能折叠后匹配数值 `1`，非数字值可能无法匹配，超长 ID 可能丢失精度，业务标识键应统一为 STRING。warning 不阻断执行，确定性 lint error 会在 preview/save 的远端调用前阻断；`save --dry-run --format json` 的 warning 只写 stderr，不污染 JSON stdout。
 
 也可以为 AI Coding Assistant 安装 Skill：
 
@@ -49,6 +49,16 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.22
+
+- 增强受控 Agent 运行环境中的 ETL 脚本执行与文件交换，大型导出不再受小缓冲区限制。
+
+### @guandata/guanetl 0.1.21
+
+- JOIN 字段类型检查覆盖预览、保存和运行全过程，可提前发现字符串、数值、日期等类型不匹配风险。
+- 增强字段别名、计算字段和多级上游 ETL 的识别，复杂 ETL 保存与运行前的诊断更准确。
+- 优化多数据集结构读取效率，批量检查复杂 ETL 时等待更少。
+
 ### @guandata/guanetl 0.1.20
 
 - `save` 会在同目录同名输出唯一匹配时自动恢复原输出节点 id 和 dsId，避免编辑已有 ETL 时误建新输出数据集。

package/package.json

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

package/skills/guanetl/SKILL.md

@@ -150,6 +150,10 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 保存前优先执行 `save --dry-run` 查看影响报告；`--format json` 可用于自动化检查。dry-run 不调用 direct-save，若报告出现阻断风险，先修 `etl/` 后重新 `export -> preview -> save --dry-run`。
 如果报告出现“输出字段风险”，表示同一输出数据集中的同名字段发生类型或来源变化，服务端可能重建该列 fdId；保存前先用 `guands dataset cards <输出dsId>` 看下游卡片，保存执行后再按列名核对并重绑页面卡片 fdId。
 
+`preview` 和 `save` 会在远端调用前重新检查本地 `_exported.json`。启发式 warning（包括 JOIN 键类型不一致）会提示风险但继续执行；确定性 lint error 会在创建预览任务或保存请求前阻断。`save --dry-run --format json` 的 warning 写入 stderr，stdout 仍只输出结构化 JSON。
+
+不要把“JOIN 键类型不一致”直接判断为零匹配。STRING 与 LONG/DOUBLE 等数值类型 JOIN 时，Spark 可能做隐式数值 coercion：纯数字字符串可能匹配，`"001"` 可能折叠后匹配数值 `1`，非数字值可能无法匹配，超长 ID 可能丢失精度。业务标识键应在 JOIN 前显式统一为 STRING。
+
 ### 新建 ETL
 
 1. 先用 `guancli` 查输入数据集和字段。
@@ -215,6 +219,7 @@ guanetl move <etl_id1> <etl_id2> --dir-id <etl_dir_id>
 - 需要递归刷新智能 ETL 上游链路时，用 `run <etl_id> --run-upstream`。CLI 会读取目标 ETL 的输入数据集，按数据集的生产 ETL 继续向上解析，生成拓扑顺序后从最上游依次执行，包含目标 ETL；每个 ETL 都会等待终态，任一失败即停止并报告失败节点。
 - 不确定上游范围时，先用 `run <etl_id> --run-upstream --dry-run` 输出执行计划；dry-run 只读拓扑，不触发任何 ETL。
 - 触发前，`run` 会检查直接上游数据集状态；若发现上游处于 `FAILED`/`失败` 态，会先输出警告但继续触发执行。确认不需要检查时可加 `--skip-upstream-check`。
+- `run <etl_id>` 还会读取服务端 edit 结构，按 JOIN 键类型组合提示隐式 coercion、精度或日期时间风险；`--run-upstream` 会在每个计划节点执行前做同样检查，检查失败不阻断执行。`preview` / `save` 会阻断明确不可用于行级 JOIN 的 aggregation/window 字段，并按服务端字段身份解析 JOIN predicate alias。批量自动化确认不需要运行前检查时可加 `--skip-join-type-check`。
 - 如果不加 `--wait` 后想查状态：`task status <taskId>` 或 `task wait <taskId>`。
 
 ### 排查执行失败
@@ -313,6 +318,7 @@ guanetl task cancel <t1> <t2>             # 批量取消多个任务
 
 ## 硬约束
 
+- **编辑 ≠ 删除重建**：编辑已有 ETL 永远走 `edit → export → preview → save` 原地保存闭环，保留原 etlId/dataFlowId 和输出数据集 dsId。guanetl 没有提供 ETL 重命名和删除命令：用户要求给 ETL 改名或删除 ETL 时，直接说明 CLI 暂不支持；**禁止**用"新建一个 ETL 替代旧 ETL"来模拟编辑或改名——新 ETL 会创建新的输出数据集（dsId 变化），下游卡片、指标、其他 ETL 的输入引用全部断链，旧 ETL 的调度配置、权限和运行历史也不会迁移。只有用户明确指示"新建替代、再废弃旧的"时才允许，且执行前必须列出上述影响并获得确认。
 - 不要改 `DefineETL()` 函数签名。
 - 节点 ID 必须唯一，且是 `id_数字`。
 - 节点顺序必须满足依赖顺序。

package/skills/guanetl/references/ETL_AI_DEVELOP.md

@@ -104,6 +104,9 @@ calc := BasicCalculator("id_1002", "解析展示格式度量", inputA, []Formula
 - 新版 ETL 默认使用输入字段别名：如果数据集字段有 `alias`，进入 ETL 算子后的列名通常是 `alias`；没有 `alias` 时才是原始 `name`。
 - 输入字段别名的事实源是数据集字段元数据；可用 `guands dataset fields <dsId>` 回读，用 `guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"` 更新。`BasicInputDataset(..., []Field{...})` 中的字段 schema 主要用于导入/导出和本地 lint，不会把一个未设置过数据集 alias 的字段强制变成展示名列。
 - 本地校验按 `alias -> displayName/showName/title -> name` 解析有效字段名；同一来源下两个字段解析成相同有效名会被视为歧义，建模前应先改名或明确上游输出。
+- 不要把 JOIN 键类型不一致直接断言为零匹配。STRING 与 LONG/DOUBLE 等数值类型 JOIN 时，Spark 可能做隐式数值 coercion：纯数字字符串可能匹配，`"001"` 可能折叠后匹配数值 `1`，非数字值可能无法匹配，超长 ID 可能丢失精度。业务标识键应在 JOIN 前显式统一为 STRING，并用 preview 验证真实匹配率。
+- `preview` / `save` 会从数据集元数据补齐 `fdId -> alias` 的运行时映射，并把 JOIN predicate 中的输入 alias 归一化为 raw name；本地 `BasicInputDataset` 声明与服务端不一致时，以服务端字段身份为准，且不会修改工作区中的原始 `_exported.json`。当前服务端仍不支持把“设置过 alias 的数据集计算字段”直接选作 JOIN 输出列，应输出其原始依赖列或先在 ETL 中生成普通列。
+- aggregation/window 计算字段不是行级字段，不能直接作为 JOIN 键；请先在 ETL 中生成普通计算列。`preview` / `save` 会在提交远端请求前拦截该用法。
 - SQL 节点使用上游表 `input1`、`input2` 的当前列名。字段有中文展示名时，SQL 里应写展示名并用反引号，例如 ``SELECT `门店ID` FROM input1``。
 - `SELECT_COLUMNS`、`FILTER_ROWS`、`REMOVE_DUPLICATES`、`GROUP_BY` 等直接列名算子，也以当前上游列名为准。
 - 底层数据集读取和数据集元数据仍保留原始 `name`，所以 `guancli` / `guands` 输出字段时要同时关注 `name` 和 `alias`。