@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanetl/SKILL.md

@@ -0,0 +1,391 @@
+---
+name: guanetl
+description: 当用户要新建、修改、调试、定时调度、立即执行、保存发布观远 BI / Guandata 的 ETL，或给出 ETL ID、dataFlowId、etl.go、meta.json、SQL 节点、dsId、节点报错时，优先使用这个 skill。即使用户只说"帮我改一下这个 ETL""这个 ETL 导出失败""新建一个观远 ETL""把这个 ETL 配成每天 2 点跑""保存后立即执行并等完成"，也要主动使用。它把线上 ETL 拉到本地工作目录，约束 AI 只编辑 etl/ 下文件，并完成 create/edit → export → preview → save → run/schedule 闭环。查 ETL/数据集元信息走 guancli；数据源/数据集 CRUD 走 guands。
+compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts (local) or npm install -g --foreground-scripts @guandata/guanetl (from internal Nexus registry) so the AI skill refresh result is visible. CLI command: guanetl."
+---
+
+# guanetl
+
+这是一个执行型 skill，不是只读分析 skill。
+
+- `guancli` 负责找 ETL / 数据集 / 字段上下文。
+- `guanetl` 负责把 ETL 拉到本地、修改 `etl/`、再完成 `export -> preview -> save`。
+
+## 何时使用
+
+遇到这些任务就用：
+
+- 新建观远 BI ETL。
+- 修改已有 ETL 的节点、SQL、字段、输出。
+- 用户给了 ETL ID / dataFlowId，希望直接拉下来改。
+- 用户保存 ETL 后希望立即触发执行并等待完成。
+- 用户希望配置 ETL 定时执行调度。
+- 用户遇到 `export`、预览、保存失败，希望定位并修复。
+- 用户提到 `etl.go`、`meta.json`、节点 ID、SQL 节点、输入输出数据集。
+
+只查信息时不要单独用它：
+
+- ETL 清单、目录树、节点详情、血缘、数据集结构、数据集预览，优先用 `guancli`。
+
+## 固定工作方式
+
+### 0. 先确认前置条件
+
+- 确认底层 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（本地可测契约）
+
+`guanetl` 是源文件驱动的 ETL 构建 harness。工作目录中只有 `etl/` 是可编辑事实源；导入、导出、保存过程产生的 JSON 都是系统状态或派生产物。
+
+| 路径/产物 | 类型 | 规则 |
+|---|---|---|
+| `etl/etl.go` | 可编辑事实源 | 定义 `DefineETL()`，只在这里表达节点、依赖、输出意图 |
+| `etl/*.sql` | 可编辑事实源 | 仅供 `BasicSqlScript(..., ReadSQLFile(...))` 引用，新增 SQL 节点必须同步新增文件 |
+| `etl/meta.json` | 可编辑事实源（谨慎） | 只有需要保留导入 ETL 的额外 metadata 时才改 |
+| `_guanetl_state.json` | 系统状态 | 不手改；由 create/edit/export/preview 维护 |
+| `_input.json` / `_base_etl.json` | 服务端快照 | 不手改；保存时会重新拉取线上 edit base 并合并 |
+| `_exported.json` | 派生产物 | 不手改；由 `export` 从 `etl/` 重新生成 |
+
+本地可测 gate：
+
+1. `go test ./...` 覆盖 workspace、merge、runner helper、request/merge 逻辑。
+2. 对 fixture 工作目录执行 `guanetl export --dir <fixture>`，比较 `_exported.json` 的关键节点、字段、SQL 文件引用和输出数据集配置。
+3. `preview/save/run/schedule` 属于线上闭环：只有在认证、目标 ETL 和数据集明确后执行，并在汇报中说明是否实际跑到这些步骤。
+
+失败修复顺序固定为：读失败输出 -> 判断是源代码/SQL/节点配置/线上任务问题 -> 修改 `etl/` 中最小责任文件 -> 重跑失败命令 -> 再重跑依赖的后续验证。不要为了修一个 export/preview 错误去重写整个 ETL。
+
+### 开发态生成飞轮
+
+当任务目标是“评估自然语言生成 ETL 的质量 / benchmark / 失败复跑 / 回灌规则”，不要把普通单次编辑流程硬扩成评估系统。使用仓库根目录的 `.skill/etl-generation-flywheel/`：运行证据放在 `etl_runs/<run-id>`，真正的 ETL 工作目录放在 `etl_workspaces/<run-id>`，再按 `export -> preview -> data_fit -> save/run -> final_judgment` 闭环推进。
+
+### 1. 先分场景
+
+- `编辑已有 ETL`
+- `新建 ETL`
+- `修复失败`
+
+### 2. 缺上下文先查，不要猜
+
+缺 ETL ID / dsId / 字段时，先用：
+
+```bash
+guancli auth status
+guancli etl search <关键词>
+guancli etl get <etl_id>
+guancli ds search <关键词>
+guancli ds get <ds_id>
+guancli ds preview <ds_id> --limit 20
+```
+
+多环境操作时，使用 `GUANCLI_PROFILE=<profile>` 固定当前进程链的目标环境，不修改机器级默认 profile。写操作会先按 `GUANCLI_PATH → PATH 中 guancli → PATH 中 guancli-lite` 解析实际底层 CLI，再在 stderr 回显对应目标：`guancli` 显示 profile，`guancli-lite` 显示脱敏后的 `GUANCLI_BASE_URL` 主机，自定义 shim 则明确提示目标由该 CLI 决定。执行前可用同一环境变量运行 `guancli auth status`，核对环境名和 URL：
+
+```bash
+GUANCLI_PROFILE=dev33 guancli auth status
+GUANCLI_PROFILE=dev33 guanetl create --name "ETL名称" --dir <work_dir>
+```
+
+### 3. 真正改代码前先读这些
+
+至少先读：
+
+- `etl/etl.go`
+- `etl/*.sql`
+- `references/ETL_AI_DEVELOP.md`
+
+必要时再读：
+
+- `etl/meta.json`
+- `guancli etl get <etl_id>` 的线上结构
+
+### 4. 只改 `etl/`
+
+只允许修改这些文件：
+
+- `etl/etl.go`
+- `etl/meta.json`
+- `etl/*.sql`
+
+不要手改这些系统文件：
+
+- `_guanetl_state.json`
+- `_base_etl.json`
+- `_input.json`
+- `_exported.json`
+
+### 5. 改完永远按这个顺序
+
+1. `export`
+2. 需要看结果时再 `preview`
+3. 确认无误后才 `save`
+4. 需要立即执行时用 `run`
+
+如果 `export` 没过，不要直接 `preview` 或 `save`。
+
+## 三种场景的默认流程
+
+### 编辑已有 ETL
+
+1. 如 ETL ID 不明确，先用 `guancli` 查。
+2. 执行：
+
+```bash
+guanetl edit <etl_id> --dir <work_dir>
+```
+
+3. 阅读 `etl/` 下文件并修改。
+4. 执行：
+
+```bash
+guanetl export --dir <work_dir>
+# 保存闭环默认要求预览至少返回 1 行；明确允许合法空结果时可省略 --require-nonempty
+# 多输出 ETL 一次传多个节点 ID：分批并行执行（默认同时最多 2 个任务，对齐 BI
+# 单用户预览并发上限）、结果按序输出，不要逐节点调用；若网页端另有预览在跑
+# 导致提交被拒，加 --max-parallel 1 串行重试
+guanetl preview <node_id> [node_id...] --dir <work_dir> --require-nonempty
+guanetl save --dir <work_dir> --dry-run
+guanetl save --dir <work_dir>
+guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待完成
+```
+
+**再次修改已 save 过的 ETL 时**：即使本地还保留着上次的工作目录，也必须重新执行 `guanetl edit <etl_id> --dir <新目录>` 拉取服务端最新版本，不要在旧工作目录上直接改了再 save。原因：服务端版本可能已经变化，直接复用旧 base 会导致合并冲突（如"输出数据集目录中存在同名文件"）。
+
+`save` 会协调已保存 ETL 的输出身份：当本地 `OUTPUT_DATASET` 节点 id 变化，但它与服务端已绑定输出在同一目录、同名且双方唯一时，CLI 会自动恢复原节点 id 和 dsId，继续原地更新已有输出数据集。该协调不会修改本地 `_exported.json`，保存影响报告会显示 `save.output_binding_reconciled`。
+
+**输出数据集落位语义（重要，勿用 dsId 判断输出是否创建）**：服务端保存时总会给每个输出补一个 `dataSource{dsId, created:false}`，但在该 ETL **首次成功运行**之前数据集实体并不存在，且每次 save/run 都会重新生成一个全新的临时 dsId。因此"保存后 dsId 非空"不代表输出已创建；判断依据是 `dataSource.created == true`。`save` 成功后 CLI 会回读服务端并输出两类诊断：`save.output_dir_rectified` 表示 `parentDirId` 无效、已被服务端静默纠正（通常纠正到数据集根目录，页面"保存至"可能显示"请选择"）——必须修正 etl.go 中的目录 id 后重新保存；`save.output_pending_materialization` 表示输出尚未物化，dsId 是临时值，勿用于下游引用。`run --wait` 成功后 CLI 会校验输出 `created == true`，存在未创建的输出会直接报错，按错误提示排查目录与节点连线，不要循环重试 save/run。例外：仅以顶层 dsId 绑定已有数据集且无 `dataSource` 的增量输出无法自动核验，会以 `run.output_placement_unverified` 警告提示，需用 `guancli etl get <etl_id> --raw` 人工确认（默认渲染不显示 `dataSource.created` 字段）。
+
+**维护约束（首次运行字段校验）**：新增或修改 CLI 的运行前校验时，只有 `dataSource.created == true` 的输出 dsId 才能当作可查询的既有数据集并读取 baseline。显式 `created:false` 表示首跑临时 dsId，运行前不得查询它、更不得因此阻断 `/api/etl/execute`；应保留输出节点 ID 与预期字段，在任务完成、输出落位校验通过后 fresh edit 回读稳定 dsId，再校验 metadata 和定向 preview。缺失 `created` 标记不等于首跑，必须保留既有的严格校验/失败语义，避免把旧 DATAFLOW 的字段注册漂移静默放行。
+
+如果 `save` 在 direct-save 前提示输出数据集绑定风险，按提示处理，不要手动删除或重命名旧输出数据集。跨目录、重名歧义、删除旧输出或无法唯一匹配时，CLI 不会猜测并默认停止保存。修复优先级：重新 `edit` 到新目录、同步 `outputDsName`、确认输出目录；确实要替换已绑定输出时，设置新的节点 id、`outputDsName` 或 `parentDirId`，并显式加 `--allow-output-replacement`。该选项只放行保存，不会迁移任何下游 dsId 引用。
+
+只追加输出列只是在输出绑定层面的安全例外：新增列、不改名、不删已有列、不改已有列类型，并保持输出名称和目录时，可以原地 `save`，保存前仍需 `preview` 目标输出确认结果；这**不代表**旧 DATAFLOW 数据集已注册该字段。`run --wait` 对本轮新增且透传到输出的 `BasicCalculator` 字段，会逐个输出等待其自身的 `lastExecution.endTime` 与 `datasourceModifyTime` 推进，并同时检查数据集 metadata 和实际 preview 返回字段。任一目标输出仍在产出，或字段没有注册/不可查询，命令会以错误结束；可用 `--timeout` 延长这段校验时间。改列名、删列、改类型、换输入数据集或重接输出链路仍按下游 schema 风险处理；输出节点 id 变化仅在唯一匹配时自动协调。
+
+保存前优先执行 `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` 查输入数据集和字段。
+2. **创建前必须先与用户确认目录**：ETL 本体目录（`--parent-dir`，来自 ETL 目录树）必填，缺失 `create` 直接拒绝（缺省会被服务端静默落到根目录，不符合目录管理规范）；输出数据集目录（`--output-parent-dir`，来自 DATA_SET 目录树）在 `create` 时可选（纯中间产物 ETL 可以没有输出），但只要 etl.go 里有输出节点，`save` 前就必须为每个输出指定目录，所以有输出的 ETL 也在创建前一并确认。先用目录树查出候选目录的路径和 id，把"ETL 放在 <路径>、输出数据集放在 <路径>"交给用户确认；目录不存在时用 `guanetl mkdir` / `guanetl mkdir-pair` 显式创建，CLI 不会自动建目录。用户明确要求放根目录时显式传根目录 id。两棵树相互独立，同名目录的 id 也不同，不能把 `guancli etl get` 输出节点里的 ParentDirId 当作 `create --parent-dir` 使用。`guancli workflow tree` 返回的是工作流/经典数据流目录树，也不能用于智能 ETL 的 `create --parent-dir`。
+
+```bash
+guancli etl tree --max-depth 2       # ETL 所在目录，用于 create --parent-dir
+guancli ds tree --max-depth 2        # 输出数据集目录，用于 create --output-parent-dir / BasicOutputDatasetInDir
+# 目录树很大时用 --keyword 词 过滤；--max-depth 0（默认不传）为全量
+guanetl mkdir-pair "ODS" --etl-parent <etl_parent_id> --ds-parent <ds_parent_id>
+guanetl rmdir <dirId> --yes          # 删空的 ETL 目录（非空拒绝并列出内容；物理删除不可恢复）
+```
+
+3. 执行（可先 `--dry-run` 看落位计划：只校验目录并打印"路径 (id)"，不申请 dataFlowId）：
+
+```bash
+guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --output-parent-dir <dataset_dir_id> --dry-run
+guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --output-parent-dir <dataset_dir_id>
+```
+
+`create` 只向服务端申请 `dataFlowId` 并初始化本地工作区，不代表完整 ETL 已持久化。首次 `save` 成功前，服务端 `get/edit/move` 可能返回 ETL 不存在；完成 `etl.go -> export -> preview -> save` 后再执行这些服务端操作。
+
+`create` / `save` 会校验目录 id 类型：`--parent-dir` 必须来自 ETL 树，输出数据集目录必须来自 DATA_SET 树。只有在确认目录 id 正确但当前账号无法读取目录树时，才使用 `--skip-dir-check`。
+
+**`save` 的目录规则**：每个新建输出节点都必须带 DATA_SET 目录（`BasicOutputDatasetInDir`），无目录的新输出会在 direct-save 前被拒绝；首次保存还要求 ETL 本体目录（来自 `create --parent-dir`）。**已物化的输出（线上已有 dsId）一律沿用服务端绑定的 dsId 和目录**，落位计划按服务端 `dataSource` 展示并标注"不会改动"，本地 `parentDirId` 意图不会覆盖它；要换目录属于替换/迁移，走既有的输出绑定风险流程。绑定已有数据集的增量输出不要求目录。`save --dry-run` 和真实保存都会打印"落位计划"（ETL 本体与每个输出的目标目录路径 + id，JSON 报告在 `saveImpact.placements`）；修改已保存 ETL 时若落位计划中出现新目录或新输出，同样要先把落位计划交给用户确认再去掉 `--dry-run`。保存成功后会逐个输出数据集打印 `路径:` 与 `链接:`（尚未创建的输出只有路径，链接要等 `run --wait` 成功后 dsId 固定才会给出）。
+如果错误提示目录 id 属于 `MASTER_FLOW`，说明拿到了工作流/经典数据流目录 id；智能 ETL 改用 `guancli etl tree` 查询，工作流/数据流创建改用 `guanwf create --parent-dir`。
+
+移动已有智能 ETL 用 `move`，目标目录同样必须来自 `guancli etl tree`。可先加 `--dry-run` 查看将提交的 `/api/etl/move` 请求体；批量移动直接追加多个 ETL ID：
+
+```bash
+guanetl move <etl_id> --dir-id <etl_dir_id> --dry-run
+guanetl move <etl_id1> <etl_id2> --dir-id <etl_dir_id>
+```
+
+4. 在 `etl/` 中实现 ETL。
+5. 再执行 `export -> preview -> save`。
+6. 需要立即执行时：`run <etl_id> --wait`；需要先刷新可识别的智能 ETL 上游链路时，先用 `run <etl_id> --run-upstream --dry-run` 看计划，再用 `run <etl_id> --run-upstream` 执行。
+
+### 修复失败
+
+1. 先确认失败发生在 `export`、`preview` 还是 `save`。
+2. 没有工作目录时，先 `edit` 或 `create` 恢复上下文。
+3. 只做最小必要修改。
+4. 从失败步骤往后重跑，不要整条链路乱重做。
+
+## 保存与执行说明
+
+### save 的工作机制
+
+`save` 不是简单把本地 JSON 上传。它的内部流程是：
+
+1. 读取本地 `_exported.json`（由 `export` 生成）
+2. 从 BI 服务端拉取当前版本的 ETL 作为合并基准（edit API）
+3. 将本地修改合并到服务端版本
+4. 调用 direct-save API 写入
+
+`save --dry-run` 只执行到合并和保存影响检查，不执行第 4 步。
+
+新建 ETL 首次保存前，服务端还没有完整 ETL，因此 edit API 可能返回不存在。此时 `save` 会使用 `create` 生成的本地 `_base_etl.json`，并输出 `信息 [save.first_save_fallback]`；这是正常的首次保存路径，不代表 create 或 save 失败。其他服务端 edit 读取失败会输出 `警告 [save.edit_fallback]`，表示虽然已回退本地 base，但仍需确认网络、权限及本地基线是否可靠。
+
+用户不需要手写服务端保存 payload。`export` 通过只表示本地产物可生成，保存仍由服务端校验。`direct-save` 返回 `success:false` 时，`save` 会非零退出并显示服务端原因与输入节点校验详情，不报告保存成功、不刷新本地 base；先处理失败原因，再重试保存，不要继续运行未保存的修改。
+
+### run --wait、run --run-upstream 与任务状态
+
+> **触发成功 ≠ ETL 执行成功**。`run` 返回 `✓ ETL 执行已触发` 仅表示后端接受了执行请求，ETL 可能在运行中失败。
+
+- 不加 `--wait` 时，`run` 只触发后返回。**再次执行 `run` 会重新触发一次执行**（增量写入类 ETL 会重复产出数据）；只有 ETL 仍在运行时，`run <etl_id> --wait` 才会被服务端拒绝重复提交并改为跟随当前执行。
+- 加 `--wait` 后，CLI 会等待本次执行直到终态（FINISHED / FAILED / CANCELED），FAILED 时会展示真实错误消息。任务 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` 后想知道结果：用只读的 `guancli etl get <etl_id>`，默认输出的「最近执行」段落给出 status / 提交 / 开始 / 结束时间，不要再次 `run`。
+
+### 排查执行失败
+
+```bash
+# 1. 触发执行并等待完成
+guanetl run <etl_id> --wait
+
+# 2. 如果已经触发但不知道结果，用只读元信息查看最近执行（不要再次 run，那会重新触发执行）
+guancli etl get <etl_id>
+
+# 3. 只有确认 ETL 仍在运行时，run --wait 才会跟随当前执行而不重复触发
+guanetl run <etl_id> --wait
+```
+
+常见失败原因：
+- 输入数据集权限不足（有读权限但缺少运行权限）
+- SQL 语法错误（本地 preview 通过但全量数据触发不同的执行路径）
+- 输出数据集目录冲突
+- 上游数据集数据为空或 schema 变更
+
+### preview 返回 0 行
+
+preview 成功但行数为 0 是合法结果，**不一定代表有错误**。CLI 默认返回成功但会输出 warning，且不会再宣称“预览验证通过”。自动化发布或确认输出必须有数据时使用 `preview --require-nonempty`；零行将返回非零退出码，应停止后续 `save`。排查顺序：
+1. 确认输入数据集本身有数据（用 `guancli ds preview <dsId> --limit 5`）
+2. 如果节点有 FILTER_ROWS 或 WHERE 条件，临时简化筛选条件再 preview
+
+## 调度配置（Schedule）
+
+配置 ETL 的触发方式：定时执行（CRON）或上游数据集更新后触发。默认不开启，必须显式调用 `schedule` 命令。
+
+### 触发模式（--trigger）
+
+| trigger | API triggerType | 说明 |
+|---|---|---|
+| `cron`（默认） | `CRON` | 按配置的 cron 定时执行 |
+| `upstream` | `AFTER_REFRESH` | 任一上游数据集更新完成后触发 |
+| `upstream-all` | `AFTER_ALL_REFRESH` | 全部上游数据集更新完成后触发 |
+
+### 定时触发示例
+
+```bash
+guanetl schedule <etl_id> --cron-type daily --hour 3 --minute 0    # 每天 03:00
+guanetl schedule <etl_id> --cron-type hourly --interval 6          # 每 6 小时
+guanetl schedule <etl_id> --cron-type minute --interval 30         # 每 30 分钟
+guanetl schedule <etl_id> --cron-type weekly --day-of-week MON --hour 5  # 每周一 05:00
+guanetl schedule <etl_id> --cron-type monthly --day-of-month 1 --hour 3  # 每月 1 号 03:00
+guanetl schedule <etl_id> --disable                                # 关闭调度
+```
+
+### 上游触发示例
+
+```bash
+# 任一上游数据集更新后执行
+guanetl schedule <etl_id> --trigger upstream
+guanetl schedule <etl_id> --trigger upstream --inputs <dsId1>,<dsId2>
+
+# 全部上游数据集更新后执行
+guanetl schedule <etl_id> --trigger upstream-all
+guanetl schedule <etl_id> --trigger upstream-all --inputs <dsId1>,<dsId2>
+```
+
+不指定 `--inputs` 时，`guanetl` 会读取 ETL 当前输入数据集并默认全部监听；指定 `--inputs` 时只监听列出的 dsId。
+
+### 定时调度类型说明
+
+| cron-type | 参数 | 说明 |
+|---|---|---|
+| `daily` | `--hour`, `--minute` | 每天指定时间执行 |
+| `hourly` | `--interval`, `--minute` | 每隔 N 小时执行 |
+| `minute` | `--interval` | 每隔 N 分钟执行（最小 5） |
+| `weekly` | `--day-of-week`, `--hour`, `--minute` | 每周指定日期时间执行 |
+| `monthly` | `--day-of-month`, `--hour`, `--minute` | 每月指定日期时间执行 |
+
+- `--day-of-week`: `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, `SUN`
+- `--day-of-month`: `1`-`31` 或 `L`（最后一天）
+
+**调度频率限制**：定时模式最高 5 分钟一次，低于 1 小时会输出性能警告。
+
+## 执行结果与任务
+
+- 没有独立的任务命令：不支持按任务 ID 查询、等待或取消任务。等待一律以 ETL ID 为入口（`run <etl_id> --wait`）；查历史结果用只读的 `guancli etl get <etl_id>`。
+- 并行触发多个 ETL 时，分别对每个 ETL 执行 `run <etl_id> --wait`（可并行起多个进程）；`--run-upstream` 会按拓扑顺序逐个等待。
+- 需要停止正在执行的 ETL 时，请到 BI 管理中心任务详情操作；CLI 不提供取消能力。
+
+## 硬约束
+
+- **编辑 ≠ 删除重建**：编辑已有 ETL 永远走 `edit → export → preview → save` 原地保存闭环，保留原 etlId/dataFlowId 和输出数据集 dsId。guanetl 没有提供 ETL 重命名和删除命令：用户要求给 ETL 改名或删除 ETL 时，直接说明 CLI 暂不支持；**禁止**用"新建一个 ETL 替代旧 ETL"来模拟编辑或改名——新 ETL 会创建新的输出数据集（dsId 变化），下游卡片、指标、其他 ETL 的输入引用全部断链，旧 ETL 的调度配置、权限和运行历史也不会迁移。只有用户明确指示"新建替代、再废弃旧的"时才允许，且执行前必须列出上述影响并获得确认。
+- 不要改 `DefineETL()` 函数签名。
+- 节点 ID 必须唯一，且是 `id_数字`。
+- 节点顺序必须满足依赖顺序。
+- 能用专用节点时，不要先写 `SQL_SCRIPT`。
+- 等值 JOIN 优先 `JOIN_DATA`，不要用 SQL 模拟。
+- 输入字段 schema 优先维护在 `BasicInputDataset(..., []Field{...})` 中。
+- 新版 ETL 默认以输入字段 `alias` / 展示名作为算子列名；字段存在别名时，SQL 和直接列名算子优先使用展示名，raw name 只作为底层数据集元数据理解。
+- ETL 执行时以真实数据集字段元数据为准；如果需要设置或确认展示名，先用 `guands dataset fields <dsId>` / `guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"`，不要只在 `etl.go` 手写 alias 后假设服务端会采用。
+- 本地字段解析优先级为 `alias -> displayName/showName/title -> name`；遇到同一来源下有效字段名重复，先消除歧义再继续写算子。
+- 新增 SQL 节点时，要同步新增对应 `.sql` 文件。
+- 对 `edit` 导入出来的 ETL，优先局部修改，不要为“重构”大面积推翻。
+- **文件访问边界**：只允许访问以下路径，不要主动探索或读取用户未明确授权的其他目录：
+  - 当前工作目录（`--dir` 指定的目录或 cwd）
+  - 本 skill 的 `references/` 目录（如 `ETL_AI_DEVELOP.md`）
+  - `guancli` / `guanetl` CLI 工具的输出
+  - 用户在对话中明确提到或授权的路径
+  - 禁止为了"查找参考代码""寻找类似实现"而主动扫描用户机器上的其他项目目录，这会引起安全顾虑。
+
+具体函数、枚举值和推荐骨架，都看 `references/ETL_AI_DEVELOP.md`。
+
+## ETL 节点类型速查（详细用法见 references/ETL_AI_DEVELOP.md）
+
+优先用专用节点，最后才用 SQL：
+
+| 节点函数 | 用途 | 何时使用 | 关键约束 |
+|---|---|---|---|
+| `BasicInputDataset` | 引入数据集 | 每个 ETL 至少一个 | 必须提供 `[]Field` schema |
+| `BasicOutputDataset` | 输出数据集 | 每个 ETL 至少一个，可有多个（叶子节点） | `DefineETL()` 返回值；多输出共享一次 save/run/schedule |
+| `BasicSelectColumns` | 选列/重命名 | 只需要部分字段或改名 | - |
+| `BasicFilterRows` | 行筛选 | 按条件过滤数据 | combineType: `AND`/`OR` |
+| `BasicJoinData` | 等值 JOIN | 两表关联 | **优先用这个，不要写 SQL JOIN** |
+| `BasicGroupBy` | 分组聚合 | SUM/COUNT/AVG 等 | 聚合类型: `SUM`/`COUNT`/`AVG`/`MIN`/`MAX` |
+| `BasicCalculator` | 新增计算列 | 公式计算新字段 | `Formula` 必须包含 `Name`/`Type`/`Expr`/`Key`；字段引用用 `[展示名]` |
+| `BasicRemoveDuplicates` | 去重 | 按指定列去重 | - |
+| `BasicAppendRows` | 上下合并 | 多表 UNION | unionType: `INCLUDE_SHARED`/`INCLUDE_ALL` |
+| `BasicSqlScript` | 自定义 SQL | 上述节点无法满足时 | SQL 放独立 `.sql` 文件，上游用 `input1`/`input2` 引用 |
+
+## 最后怎么向用户汇报
+
+至少说明这四件事：
+
+- 处理的是哪个 ETL / 工作目录，并附上 `edit`/`save`/`move`/`mkdir` 输出里的 `链接:` 和 `路径:`（ETL 详情页为 `<BI 地址>/data-flow/<etlId>/details/datasets`，目录为 `<BI 地址>/data-center/data-flow/<dirId>`），让用户能直接在 BI 中打开而不是拿着 ID 自己找。`create` 申请到的 dataFlowId 在首次 `save` 成功前服务端尚未持久化，此时不要编造链接。
+- 每个输出数据集的 `路径:` 和 `链接:`，取自 `save` 成功后的"输出数据集落位"段或 `run --wait` 成功后的逐输出输出（数据集详情页为 `<BI 地址>/data-source/<dsId>/details/overview`）。`save` 后仍标注"尚未创建"的输出不要编造链接，改为说明需要 `run --wait` 成功后再取。
+- 改了哪些 `etl/` 文件。
+- `export`、`preview`、`save`、`run` 哪些已经成功。
+- 如果没闭环，卡在哪一步，下一步最小动作是什么。
+
+
+---
+
+## VM 环境差异（观远 BI 工作站）
+
+本技能在 MCP 虚拟工作站中运行，与本地 CLI 有以下差异：
+
+- 命令名直接可用：在工作站里直接执行 `guancli` / `guanetl` / `guanvis` / `guands` / `guanmetric` / `guanwf`（无需安装）。
+- 认证：BI 凭证由网关注入，**不要**执行 `auth login` 或设置 token，直接运行业务命令即可。
+- 文件路径一律用以 `/` 开头的绝对路径（`/` 即工作区根，跨会话持久）。
+- 本技能的参考文档在 `/skills/<技能名>/references/` 下、示例工程在 `/skills/<技能名>/evals/` 下（均只读），用 read_file 工具或 `cat` 按需阅读；正文引用 `references/xxx` / `evals/xxx` 时按此路径解析。
+- 图片文件（png/jpg/gif/webp）用 read_file 工具读取，**不要**用 `cat`/`head` 读图片。默认部署下图片以图像内容返回、模型可直接查看；若 read_file 返回"当前部署已关闭图像内容返回"的提示（部署方接入的模型不支持图像理解），则只有文本元信息，此时不要做任何依赖看图的验证，改用数据类命令核对。
+- 不支持 `cd`、`$VAR` 展开、命令替换 `$(...)`、glob 展开；需要组合时把中间结果写入文件。
+- 文本搜索用 `rg`（工作站内无独立 grep 二进制，`grep`/`egrep`/`fgrep` 会自动转成 `rg` 执行，无需绕路）。
+- `install-skill` / profile 切换 / npm 相关步骤在工作站内不适用，忽略即可。

package/skills-bundle/guanetl/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "guanetl",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "帮我修改一个观远 BI 的 ETL。ETL ID 是 etl_abcd1234，我要把订单表和用户表按 user_id 做等值关联，补出用户等级，再按订单日期筛选最近 30 天，最后输出到一个新的结果数据集。你直接拉下来改，并告诉我应该预览哪个节点。",
+      "expected_output": "代理应识别为编辑已有 ETL 场景，先获取并导入 ETL，再基于专用节点优先的规则修改 etl/ 下文件，执行 export，并建议或执行 preview 针对最终输出节点或关键中间节点。",
+      "files": [],
+      "expectations": [
+        "使用 guanetl 而不是只停留在 guancli 的只读分析",
+        "先执行 edit 获取本地工作目录，再修改 etl/ 文件",
+        "对等值关联优先选择 JOIN_DATA，而不是直接写 SQL_SCRIPT",
+        "在改动后执行 export 验证，并给出可预览的节点建议"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "新建一个观远 ETL，名字叫“门店销售日报汇总”。输入来自两个数据集：一个是门店销量明细，一个是门店维表。我现在没有 dsId，你先帮我找，再把这个 ETL 建出来，最后输出每个门店每天的销售额和订单数。",
+      "expected_output": "代理应识别为新建 ETL 场景，先联动 guancli 查找合适数据集和字段，再使用 create 初始化工作目录，按照 ETL_AI_DEVELOP 约束编写 etl.go，最后进入 export、preview、save 流程。",
+      "files": [],
+      "expectations": [
+        "先通过 guancli 查找 dsId 和字段，而不是直接假设输入数据集",
+        "执行 create 创建新的工作目录",
+        "在真正编写节点前参考 ETL_AI_DEVELOP.md",
+        "输出中包含 export、preview、save 的后续闭环步骤"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "我这个观远 ETL 本地 export 失败了，报错像是 SQL 校验不过。工作目录已经有了，你帮我定位问题并修掉，不要乱改根目录里的系统文件。",
+      "expected_output": "代理应聚焦修复失败场景，先确定工作目录和失败步骤，检查 etl/ 下的 etl.go、SQL 文件和相关约束，做最小必要修改，只重跑 export 以及后续需要的 preview/save 步骤。",
+      "files": [],
+      "expectations": [
+        "明确只修改 etl/ 子目录中的文件",
+        "先分析 export 报错和 SQL/节点配置问题，再做代码修改",
+        "修复后重新执行 export，而不是直接 save",
+        "避免修改 _base_etl.json、_input.json、_exported.json 等系统文件"
+      ]
+    }
+  ]
+}