GuanETL 使用指南
GuanETL 是什么
GuanETL 是观远 BI 的 ETL 开发和运行辅助工具。配合 AI Agent 使用时，用户可以用自然语言描述数据处理需求，例如“帮我修改销售订单清洗流程，过滤掉金额为空的记录”，AI 会自动读取 ETL 结构、修改处理逻辑、检查配置、预览结果，并在确认后保存到观远环境。
GuanETL 适合用于快速搭建数据清洗流程、修改现有 ETL、排查 ETL 运行失败原因、配置定时调度等场景。也适合在售前、实施、客户试用和内部验证阶段快速搭建 ETL 初稿。
使用 GuanETL 时，建议先在测试环境、演示环境或个人测试目录中生成和验证结果。涉及正式客户环境、生产目录或重要线上 ETL 时，请先确认字段口径、输出位置、下游依赖和影响范围，再保存到正式环境。
目前产品处于公测阶段，可以免费使用所有功能，公测后需要获得商业授权才能继续使用，如仍需体验请联系观远数据商务人员或客户成功经理（通常是贵公司当前的服务交流负责人）。
前提条件
安装 GuanETL 前，请确认电脑已安装 Node.js、npm 和 GuanCLI，并已完成 guancli auth login。GuanCLI 的安装和登录方式可参考 GuanCLI 使用指南。
安装 GuanETL
方式一：通过 npm 命令全局安装
-
安装 GuanETL
# 首次安装npm install -g @guandata/guanetlguanetl install-skill# 已安装过的更新版本npm update -g @guandata/guanetlguanetl install-skill说明guanetl install-skill 该命令会为 AI Agent 安装 GuanETL 的工具使用说明，让 AI 知道何时调用 GuanETL 开发、检查或运行 ETL。它不替代 GuanCLI 登录，操作 ETL 时仍会复用 GuanCLI 的认证配置。
安装完成后，即可在 Codex、Cursor、Claude Code 等 AI 工具中用自然语言提出 ETL 开发需求，例如：
请帮我查看“销售订单清洗”这个 ETL，说明它用了哪些数据和主要处理逻辑，先不要修改。 -
安装完成后验证
guanetl version终端显示版本号即表示安装成功。
说明如果安装成功但执行
guanetl version提示找不到命令，通常是 npm 全局命令目录未加入系统PATH。可执行以下命令查看全局目录，将对应目录加入PATH后重新打开终端。npm prefix -g
方式二：通过 Agent 辅助安装
直接把下面的需求发给 AI Agent，让 Agent 协助检查环境、安装工具并验证命令是否可用：
请帮我检查当前电脑是否已经安装 Node.js、GuanCLI 和 GuanETL。
如果 GuanETL 未安装，请帮我安装，指令为 npm install -g @guandata/guanetl，并确认 guanetl version 可以正常执行。
并帮我执行 guanetl install-skill，确认安装完成。
登录 BI 环境
GuanETL 使用 GuanCLI 的认证配置。只要 guancli auth login 登录成功，GuanETL 后续查询 ETL、修改流程、保存和运行任务时会自动复用当前认证信息。详细配置可参考 登录 GuanCLI。
使用 GuanETL 开发 ETL
用户通常不需要手动执行每一条 GuanETL 命令。更推荐的方式是在 AI Agent 中直接描述业务需求，让 AI 先查清楚相关数据和流程，再完成修改、检查和结果说明。
首次使用时，建议按以下阶段逐步验证。先确认工具和登录环境，再选择低风险 ETL，最后才进行修改、保存、运行或调度。
第一阶段：检查安装和登录状态
发给 Agent：
请帮我检查当前电脑是否已经安装 GuanCLI 和 GuanETL，并确认当前是否已经登录观远环境。只做检查，不要修改任何 ETL。
Agent 应该确认：
guanetl是否可用。guancli是否可用。- 当前登录的是哪个观远环境。
- 当前账号是谁。
目标是确认工具和登录状态正常，并且没有连错环境。
第二阶段：找一个低风险 ETL
发给 Agent：
请帮我找一个名称里包含“测试”或“示例”的 ETL，列出它的名称、ID、目录、输入数据和输出结果。先不要打开草稿，也不要修改。
如果你已经知道要试的 ETL，可以直接说：
请先帮我查看这个 ETL 的基本信息，说明它用了哪些输入数据、最后生成什么结果。ETL 名称是“XXX”。
目标是先理解这个 ETL 是做什么的，确认它适合试用。
第三阶段：打开 ETL 草稿但不修改
发给 Agent：
请用 GuanETL 打开这个 ETL，生成本地草稿。打开后请告诉我草稿放在哪里、包含哪些文件，以及后续哪些文件可以改。先不要修改。
目标是验证 Agent 能正确打开 ETL，并且知道只能修改草稿中的 ETL 文件。
第四阶段：做一个小改动并先检查
选择一个很小、容易确认的改动，例如调整节点名称、补充一个简单过滤条件，或修改一段明确的 SQL。
发给 Agent：
请在这个 ETL 草稿里做一个小改动：订单金额为空的数据不要进入最终结果。改完后先检查配置和结果，暂时不要保存到线上。请告诉我你改了什么、检查是否通过、结果是否符合预期。
目标是验证 Agent 能完成“修改草稿 -> 检查配置 -> 查看结果 -> 汇报”的闭环。
第五阶段：确认后再保存
只有在你确认检查结果没问题后，再发给 Agent：
检查结果我确认了。请保存到观远环境。保存前再确认一次当前环境和目标 ETL，保存后告诉我是否成功。
目标是验证保存链路。生产环境中，不建议跳过这一步确认。
第六阶段：需要时再运行并等待结果
如果需要验证 ETL 全链路运行，再发给 Agent：
请运行刚才保存的 ETL，并等待任务结束。如果失败，请告诉我真实错误信息和下一步排查建议。
目标是确认服务端运行最终成功，而不是只确认“已经开始运行”。
“已开始运行”只表示观远已经接受了运行请求，流程可能还在运行，也可能后面失败。建议让 Agent 等待任务终态。
第七阶段：尝试设置定时任务或删除前检查
设置定时任务前，可以这样说：
请把这个 ETL 设置为每天凌晨 3 点自动运行。设置前先确认当前环境和目标 ETL，设置后用简单的话说明规则。
删除前可以这样说：
请帮我检查这个 ETL 能不能删除。只做删除前检查，告诉我会影响哪些输出数据、有没有页面或其他流程还在使用它。不要直接删除。
目标是验证高风险操作前，Agent 会先检查影响范围，而不是直接执行。
使用建议
- 首次试用建议选择测试环境、个人目录或测试目录下的 ETL。
- 先说清楚业务目标和数据口径，不要只说“帮我改一下 ETL”。
- 优先选择输入输出关系清楚、字段含义明确的 ETL。
- 保存、运行、调度、删除前，先确认当前环境、字段口径、输出结果和影响范围。
- 让 AI 先说明“准备保存、运行或设置定时任务”以及影响范围，再由你确认。
- 生产环境执行前，让 Agent 列出即将执行的命令。
- 不建议首次使用就选择生产环境核心链路、多人同时维护的关键 ETL，或下游依赖复杂的 ETL。
常见问题排查
问题一：安装后提示找不到 guanetl 命令
先确认安装成功：
npm list -g @guandata/guanetl
再检查 npm 全局命令目录是否在 PATH 中：
npm prefix -g
Windows 全局命令通常位于 %AppData%\npm，macOS/Linux 通常位于 $(npm prefix -g)/bin。加入 PATH 后，请重新打开终端。
问题二：AI 没有自动使用 GuanETL
可以在问题中明确写：
请使用 GuanETL 修改这个 ETL。
或：
请按 GuanETL 的方式，先读取 ETL 结构，再修改、检查并保存。
如果仍然没有自动调用，请确认已经执行：
guanetl install-skill
问题三：提示未登录或认证失败
先查看 GuanCLI 登录状态：
guancli auth status
如果未登录或登录已失效，请重新登录：
guancli auth login
如果有多个环境，请确认当前 profile 是否正确：
guancli auth list
guancli auth use <环境名称>
问题四：保存失败怎么办
先不要反复直接保存。建议让 Agent：
- 查看保存失败的具体原因。
- 重新做配置检查。
- 检查是否复用了旧工作目录。
- 必要时重新打开线上最新版本，再做最小修改。
- 做最小修改后再次验证。
可以这样说：
保存失败了。请不要直接重复保存。先分析失败原因，如果可能是线上版本已经变化，请重新打开最新版本，再做最小修改和检查。
问题五：检查结果显示 0 行，是不是失败
不一定。检查成功但结果是 0 行，可能只是筛选条件太严格，或输入数据本身没有匹配记录。
可以让 Agent 继续检查：
检查结果是 0 行。请先看看源数据有没有数据，再检查过滤条件、关联条件和字段类型。
问题六：提示“已开始运行”，是不是就成功了
不是。“已开始运行”只表示观远已经接受了运行请求。流程可能还在运行，也可能后面失败。
建议使用：
guanetl run <etl_id> --wait --timeout 600
或：
guanetl task wait <taskId>
问题七：AI 会改电脑上的哪些内容
正常情况下，AI 只应该修改当前 ETL 草稿目录里的流程文件，例如：
etl/etl.goetl/*.sql- 必要时修改
etl/meta.json
下面这些是工具自动生成或维护的文件，不要手工修改：
_guanetl_state.json_input.json_base_etl.json_exported.json
这些是系统状态或导出产物。
问题八：可以删除 ETL 吗
可以，但要谨慎。GuanETL 默认会先做“删除前检查”，不会直接删除：
guanetl delete <etl_id>
确认后才执行：
guanetl delete <etl_id> --yes
如果要同时删除输出数据集，只有在安全检查通过时才建议执行：
guanetl delete <etl_id> --cascade --yes
问题九：权限和安全怎么处理
GuanETL 的权限与观远平台保持一致。建议：
- 使用测试环境或测试目录试做。
- 保存、执行、调度、删除前先确认当前环境。
- 不在提示词里粘贴账号密码、Token、客户隐私和敏感业务数据。
- 修改关键 ETL 前确认输入、输出、下游依赖和业务口径。
- 生产环境执行前让 Agent 列出即将执行的命令。