@guandata/guanetl

v0.1.37

Published

4 days ago

观远 ETL 本地开发工具 - 拉取、编辑、导出、预览、保存 ETL

0High
0Medium
0Low

guandata etl cli agent-skill

guanetl

观远 ETL 本地开发工具，支持拉取、编辑、导出、预览、保存 ETL。

本地安装（开发/测试阶段）

# 编译所有平台 binary（需要 Go 工具链）
npm run build

# 安装到本地 node global
npm link

安装后即可在终端使用：

guanetl edit <etl_id> --dir <work_dir>
guanetl export --dir <work_dir>
guanetl preview <node_id> --dir <work_dir>
guanetl preview <node_id> --dir <work_dir> --require-nonempty
guanetl save --dir <work_dir>

说明：npm 包名为 @guandata/guanetl，用户侧 CLI 命令统一为 guanetl。

标准 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 不推测其环境语义。可先运行 GUANCLI_PROFILE=<profile> guancli auth status 核对环境名和 URL，不需要切换机器级默认 profile。

preview 返回 0 行时默认输出 warning 并保持兼容的成功退出码；自动化发布或要求输出必须有数据时使用 preview --require-nonempty，并仅在命令成功后继续 save。

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 会通过当前 ETL 的最近执行信息恢复 taskId 并等待，不需要查询管理员级全局运行任务列表。触发前会检查直接上游数据集状态和服务端 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 成功后会自动输出本地静态检查提示；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：

guanetl install-skill

npm install -g --foreground-scripts @guandata/guanetl / npm link --foreground-scripts 会通过 postinstall 自动刷新 skill，并显示明确的成功、失败或跳过结果；上述 guanetl install-skill 仅用于失败后的手动修复或排查。CI 等无需 skill 的环境可设 GUAN_SKIP_INSTALL_SKILL=1 跳过。

安装包会通过 npm optionalDependencies 自动选择当前系统的原生二进制。不要使用 --omit=optional 或 optional=false；企业 npm 镜像也需要同步对应的 @guandata/guanetl-<平台>-<架构> 包。若平台包缺失，CLI 会显示对应包名和重新安装方法。

版本更新