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 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 从最上游依次执行并等待完成。

触发成功 ≠ ETL 执行成功：run 返回"执行已触发"仅表示后端接受了请求。使用 run --wait 等待终态，FAILED 时会展示真实错误消息；如果同一 ETL 已被级联触发并正在运行，run --wait 会改为等待当前运行中的任务。触发前会检查直接上游数据集状态；若发现上游处于失败态，会先输出警告但继续执行，可用 --skip-upstream-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 风险，建议统一键类型。

也可以为 AI Coding Assistant 安装 Skill：

guanetl install-skill

版本更新

@guandata/guanetl 0.1.19

• 新增 move 命令，支持将一个或多个智能 ETL 移动到指定 ETL 目录，并在接口异常时读回确认移动结果。
• run 新增 --run-upstream 与配套 --dry-run，支持递归解析智能 ETL 上游链路、按拓扑顺序执行并等待每个节点完成。
• run --wait 遇到同一 ETL 已在运行的 40001 响应时，会查找当前运行中的任务并等待其完成，减少级联触发后重复 run 的误判失败。
• export 静态检查新增 JOIN 键类型不一致 warning，提示 STRING/LONG 等隐式 coercion 风险。

@guandata/guanetl 0.1.18

• 创建 ETL 时目录类型诊断更清晰，会识别误用工作流/经典数据流目录的场景，并提示使用智能 ETL 目录。
• 更新使用说明，明确智能 ETL、数据集输出目录和工作流目录的边界。

@guandata/guanetl 0.1.17

• install-skill 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

@guandata/guanetl 0.1.16

• save --dry-run 增加保存影响预览基础能力，帮助在提交前检查关键配置变化。
• run 会在执行前提示上游数据集失败状态，降低基于异常上游继续执行的风险。
• schedule 修复上游触发调度的默认输入处理，减少调度配置误差。
• export / save 增强输入字段类型校验，并在 preview 中提示 LEFT JOIN 桥接列全空样本。

@guandata/guanetl 0.1.15

• save 增强输出数据集保护，保留级联相关配置，并对追加写入场景的行数据结构提前校验。
• 补充多输出数据集和追加写入保存流程说明，降低 ETL 保存时误改输出配置的风险。

@guandata/guanetl 0.1.14

• 移除 delete 命令。ETL / 数据集删除属于高风险操作，后续不再通过 guanetl 暴露。
• 修复 edit -> export -> save 保存已绑定输出数据集时，导出空 dataSource 覆盖服务端绑定并触发保存保护的问题。
• run --wait 明确区分触发响应状态与最终执行结果，避免把触发任务的 FINISHED 误读为 ETL 执行成功。
• 修复 ETL 导出与 merge 过程中部分节点字段丢失问题，并补充相关测试覆盖。

@guandata/guanetl 0.1.13

• lint 增加字段 raw name 与 alias/displayName 疑似误用诊断，帮助识别 SQL/算子字段引用风险。
• create / save 增加目录树类型 preflight，区分 ETL 目录和 DATA_SET 输出目录，并支持必要时跳过检查。
• save 增加输出数据集绑定风险检查，提前拦截可能创建重名输出或输出数据集 rename 未同步的 payload。
• export 成功后会输出静态检查提示，并补充 BasicCalculator / Formula.Expr 字段引用、类型和函数说明。

@guandata/guanetl 0.1.12

• import 去掉对 guanetl-server 的依赖，改为基于 BI 数据集 schema 在本地生成 SQL。
• 新增本地 SQL 生成与 schema provider 测试覆盖，提升 ETL 导入链路稳定性。
• create / edit / import 路径适配新的本地导入链路。
• install-skill 增加 WorkBuddy skill 安装路径支持。

0.1.11

• 优化试用账号场景下的运行上下文识别，提升命令执行记录与问题排查的一致性。
• 重新构建发布产物，纳入共享运行上下文处理更新。

卸载

npm unlink -g @guandata/guanetl

支持平台

• macOS (Apple Silicon / Intel)
• Windows (x64)

开发

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

# 发布到内部 Nexus npm 仓库
npm publish