@guandata/guanwf 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## @guandata/guanwf 0.1.3 - 2026-05-28
+
+- 优化试用账号场景下的运行上下文识别，提升命令执行记录与问题排查的一致性。
+- 重新构建发布产物，纳入共享运行上下文处理更新。
+
+## @guandata/guanwf 0.1.2 - 2026-05-26
+
+- 构建流程会将 npm 包版本注入到 `guanwf` 二进制，确保运行时版本信息与发布包一致。
+- 改进工作流数据流命令的 profile 与版本上下文传递，提升多环境排查时的一致性。
+- 补充相关测试覆盖，提升数据流命令辅助逻辑稳定性。
+
+## @guandata/guanwf 0.1.1 - 2026-05-21
+
+- 强化工作流数据流编辑的源文件驱动流程，明确修改应落在 `etl/etl.go`、`etl/*.sql` 或被引用的 `etl/node_*.json`。
+- 明确 `_exported.json`、`_parent_snapshot.json`、`_input.json` 等根目录 JSON 为系统状态或派生产物，不应手工修改。
+- 优化新建、编辑、导出、预览、保存的固定工作顺序说明，降低保存时覆盖父工作流其他数据流的风险。
+- 调整 create/export 相关行为说明，使新建数据流默认通过 `etl/` 事实源生成。
+
+## @guandata/guanwf 0.1.0 - 2026-05-20
+
+- 新增 `@guandata/guanwf` npm 发布包，提供构建、预检、安装同步与跨平台二进制分发流程。
+- 支持 workflow platform 的导入/导出闭环，完善工作流数据流编辑与发布链路。
+- 扩展工作流数据流节点预览能力，并补充节点与 ETL AI 开发参考文档。
+- 调整用户侧命令与文档命名，移除 `-skill` 后缀并清理旧引用。
+- 改进跨平台运行体验，包括 Linux 构建目标与 Windows 控制台 UTF-8 输出兼容。

package/README.md

@@ -0,0 +1,61 @@
+# guanwf
+
+观远工作流数据流编辑工具，支持创建、编辑、导出、预览、保存数据流。
+
+## 本地安装（开发/测试阶段）
+
+```bash
+# 编译所有平台 binary（需要 Go 工具链）
+npm run build
+
+# 安装到本地 node global
+npm link
+```
+
+安装后即可在终端使用：
+
+```bash
+guanwf create --name "我的数据流" --parent-dir <dirId>
+guanwf edit <parentWorkflowId>
+guanwf export --dir <workdir>
+guanwf preview --dir <workdir>
+guanwf save --dir <workdir>
+guanwf run --wait --dir <workdir>
+```
+
+说明：npm 包名为 `@guandata/guanwf`，用户侧 CLI 命令统一为 `guanwf`。
+
+也可以为 AI Coding Assistant 安装 Skill：
+
+```bash
+guanwf install-skill
+```
+
+## 版本更新
+
+### 0.1.3
+
+- 优化试用账号场景下的运行上下文识别，提升命令执行记录与问题排查的一致性。
+- 重新构建发布产物，纳入共享运行上下文处理更新。
+
+## 卸载
+
+```bash
+npm unlink -g @guandata/guanwf
+```
+
+## 支持平台
+
+- macOS (Apple Silicon / Intel)
+- Linux (x64 / arm64)
+- Windows (x64)
+
+## 开发
+
+```bash
+# 编译所有平台 binary（需要 Go 工具链）
+npm run build
+
+# 发布到内部 Nexus npm 仓库
+npm publish
+```

package/bin/run.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execFileSync, execSync, spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "guanwf-darwin-arm64",
+  "darwin-x64": "guanwf-darwin-x64",
+  "linux-x64": "guanwf-linux-x64",
+  "linux-arm64": "guanwf-linux-arm64",
+  "win32-x64": "guanwf-win32-x64.exe",
+};
+
+function getBinaryPath() {
+  const key = `${process.platform}-${process.arch}`;
+  const binaryName = PLATFORM_MAP[key];
+  if (!binaryName) {
+    console.error(
+      `Unsupported platform: ${key}\nSupported: ${Object.keys(PLATFORM_MAP).join(", ")}`
+    );
+    process.exit(1);
+  }
+
+  const binaryPath = path.join(__dirname, "..", "binaries", binaryName);
+  if (!fs.existsSync(binaryPath)) {
+    console.error(
+      `Binary not found: ${binaryPath}\nRun 'npm run build' to compile binaries.`
+    );
+    process.exit(1);
+  }
+
+  return binaryPath;
+}
+
+if (process.argv[2] === "version" && process.argv.length === 3) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (process.argv[2] === "install-skill") {
+  const pkgRoot = path.join(__dirname, "..");
+  const extraArgs = process.argv.slice(3);
+  const args = [
+    "skills",
+    "add",
+    pkgRoot,
+    "--skill",
+    "guanwf",
+    "-g",
+    "-y",
+    ...extraArgs,
+  ];
+  console.log("Installing guanwf to AI coding assistants...");
+  const result = spawnSync("npx", args, { stdio: "inherit", env: process.env, shell: true });
+  if (result.error) throw result.error;
+  process.exit(result.status || 0);
+}
+
+const binary = getBinaryPath();
+
+try {
+  if (process.platform !== "win32") {
+    fs.chmodSync(binary, 0o755);
+  }
+} catch (_) {
+  // chmod may fail in read-only environments
+}
+
+if (process.platform === "win32") {
+  try { execSync("chcp 65001", { stdio: "ignore" }); } catch (_) {}
+}
+
+try {
+  execFileSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env: { ...process.env, GUANWF_PROG_NAME: "guanwf" },
+  });
+} catch (err) {
+  if (err.status != null) {
+    process.exit(err.status);
+  }
+  throw err;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@guandata/guanwf",
+  "version": "0.1.3",
+  "description": "观远工作流数据流编辑工具 - 创建、编辑、导出、预览、保存数据流",
+  "bin": {
+    "guanwf": "bin/run.js"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "skills/",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "keywords": [
+    "guandata",
+    "workflow",
+    "dataflow",
+    "cli",
+    "agent-skill"
+  ],
+  "license": "UNLICENSED",
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/guanwf/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: guanwf
+description: 当用户要创建、编辑、保存工作流引擎中的数据流（Dataflow），或需要预览/运行数据流，或需要查询工作流/数据流列表和详情时使用。数据流是 BI ETL 的扩展，运行在独立的工作流引擎中。适用于用户说"创建一个数据流""编辑这个工作流中的数据流""保存数据流""预览数据流节点""运行工作流""列出所有数据流""查看这个工作流的定义"等场景。
+compatibility: "Requires Node.js 14+. Install via npm link (local) or npm install -g @guandata/guanwf (from internal Nexus registry). CLI command: guanwf."
+---
+
+# guanwf
+
+工作流引擎数据流 (Dataflow) 的编辑闭环工具。
+
+这是一个执行型 skill，不是只读分析 skill。
+
+- `guancli workflow` 负责查询工作流、数据流、目录和线上结构。
+- `guanwf` 负责把目标数据流拉到本地工作目录，修改 `etl/` 事实源，再完成 `export -> preview -> save-draft/save -> run`。
+
+## 核心概念
+
+- **工作流 (Workflow / PROCESS)**: 顶层容器，包含任务节点 DAG
+- **数据流 (Dataflow / DATAFLOW)**: 嵌入在工作流中的 ETL 流程，actions 结构与 BI ETL 相同
+- **数据库数据流 (DB_DATAFLOW)**: 数据流的变体，支持 SQL 下推
+- **父工作流**: 每个数据流必须属于一个父工作流，保存时必须提交完整的父工作流上下文
+
+## 关键不变式
+
+**保存数据流时，必须携带完整的父工作流快照（包含所有 dataflowJson）。**
+如果只提交被编辑的 dataflow，后端会删除父工作流中其他数据流的定义。
+
+## Harness 工作法：源文件驱动，不手写最终 JSON
+
+`guanwf` 复用 `guanetl` 的本地 harness 思路：先改可读、可复现的源文件，再用明确命令重新生成派生产物。不要为了让保存请求看起来正确而直接改最终 JSON。
+
+**如果任务是生成或修改数据流，但本轮没有修改下面任一事实源，不要汇报完成，也不要直接 save：**
+
+- `etl/etl.go`
+- `etl/*.sql`
+- `etl/node_*.json`（仅限被 `etl.go` 里的 `LoadNodeFromFile(...)` 引用的透传节点）
+
+查询、预览、运行、排查已有导出结果时可以不修改源文件；但只要目标是“生成/调整数据流逻辑”，最终变更必须落在 `etl/` 事实源中。
+
+### Artifact contract（本地可测契约）
+
+工作目录中 `etl/` 是可编辑事实源。导入、导出、预览、保存过程产生的根目录 JSON 是系统状态或派生产物。
+
+| 路径/产物 | 类型 | 规则 |
+|---|---|---|
+| `etl/etl.go` | 可编辑事实源（默认首选） | 定义 `DefineETL()`，使用 guanetl framework DSL 声明节点、依赖和叶子输出 |
+| `etl/*.sql` | 可编辑事实源 | 仅供 `BasicSqlScript(..., ReadSQLFile(...))` 或数据源 SQL 配置引用；新增 SQL 节点必须同步新增文件 |
+| `etl/node_*.json` | 可编辑事实源（透传节点） | 仅用于 `LoadNodeFromFile(...)` 引用的复杂节点配置；改透传节点时改这里，不改 `_exported.json` |
+| `etl/actions.json` | 历史兼容输入 | 不作为 AI 编辑入口；新建/修改数据流不要写这个文件 |
+| `_wf_state.json` | 系统状态 | 不手改 |
+| `_parent_snapshot.json` | 服务端快照 | 不手改；save 时会重新拉取线上最新版本并合并 |
+| `_input.json` | 服务端快照 | 不手改；仅用于 `edit` 导入排查，不是新建数据流的输入配置入口 |
+| `_exported.json` | 派生产物 | 不手改；由 `export` 从 `etl/` 重新生成 |
+
+默认工作方式：编写 `etl/etl.go`、`etl/*.sql` 和必要的 `etl/node_*.json`，然后执行 `export`。`export` 检测到 `etl.go` 后会通过 `guanetl go2json`（yaegi 解释器）生成 actions JSON，并写入 `_exported.json`。
+
+输入信息写在 `etl/` 事实源中：
+
+- 数据集输入：在 `etl/etl.go` 里用 `BasicInputDataset(..., dsId, []Field{...})` 声明数据集 ID 和字段 schema。
+- 数据库直连输入：优先在 `etl/etl.go` 里用 `BasicInputDatasource(...)` 声明账号、连接和 SQL；复杂导入节点才编辑被 `LoadNodeFromFile(...)` 引用的 `etl/node_*.json`。
+- SQL 转换：SQL 放在 `etl/*.sql`，并由 `ReadSQLFile(...)` 引用。
+- `_input.json` 是导入快照，不参与新建数据流配置。
+
+### 禁止的偷懒路径
+
+不要做这些事：
+
+- 不要直接编辑 `_exported.json` 来“修好”预览或保存。
+- 不要直接编辑 `_parent_snapshot.json` 或 `_input.json` 来拼保存 payload。
+- 不要把 `guancli workflow get --raw` 的结果复制成最终 JSON 后手改。
+- 不要把新建/修改需求写进 `etl/actions.json`。
+- 不要跳过 `export`，拿上一次的 `_exported.json` 去 `preview` 或 `save`。
+
+如果 `export`、`preview` 或 `save` 失败，修复顺序固定为：读失败输出 -> 判断是 `etl.go`、SQL、透传节点 JSON、认证/网络还是线上任务问题 -> 修改 `etl/` 中最小责任源文件 -> 从失败步骤往后重跑。不要通过手改根目录 JSON 绕过失败。
+
+## 认证
+
+复用 guancli 的认证链路：
+```bash
+guancli auth login   # 先确保已登录
+guancli auth status  # 检查连接状态
+```
+
+## 固定工作方式
+
+### 0. 先分场景
+
+- `只读查询`: 用 `guancli workflow`，不要创建工作目录。
+- `编辑已有数据流`: 用 `guanwf edit <parentWorkflowId>` 拉取父工作流和目标数据流。
+- `新建数据流`: 用 `guanwf create --name ... --parent-dir ...` 建工作目录，然后新建 `etl/etl.go`。
+- `修复失败`: 先定位失败发生在 `export`、`preview`、`save` 还是 `run`，只修最小责任源文件。
+
+### 1. 缺上下文先查，不要猜
+
+查询工作流和数据流定义时使用 `guancli workflow`。工作流/数据流由独立的 workflow 引擎管理。
+
+```bash
+guancli workflow tree                           # 工作流目录树
+guancli workflow list                           # 列出工作流 + 内嵌数据流（默认）
+guancli workflow list --show-embedded=false     # 只列工作流，不展示内嵌数据流
+guancli workflow list 销售                      # 按关键词搜索
+guancli workflow list --page-size 50            # 调整每页条数
+guancli workflow list --parent-dir <dirId>      # 指定父目录
+guancli workflow get <processDefinitionId>      # 查看工作流详情（含数据流节点详情）
+guancli workflow get <id> --raw                 # 输出原始 JSON
+guancli workflow get <id> -f json               # JSON 格式输出
+```
+
+`workflow tree` 调用 `/api/directory/MASTER_FLOW/authorized-tree` 获取工作流目录树。
+
+数据流以 SUB_PROCESS 节点形式内嵌在工作流中（`dataFlowNode=true`），不作为独立记录存在。
+`list` 默认展示内嵌数据流（遍历每个工作流并汇总），使用 `--show-embedded=false` 可关闭。
+
+`get` 详情输出包含：工作流节点 DAG（区分 DATAFLOW/DB_DATAFLOW/SUB_PROCESS 节点类型）、数据流摘要（节点数/类型分布/输入输出），以及各节点的详细信息（Sources/UsedBy 依赖关系、字段、SQL 等），按拓扑排序输出（INPUT → 中间处理 → OUTPUT）。
+
+### 2. 真正改文件前先读这些
+
+至少先读：
+
+- `etl/etl.go`
+- `etl/*.sql`
+- `etl/node_*.json`
+- `references/ETL_AI_DEVELOP.md`
+- `references/WORKFLOW_NODES.md`
+
+必要时再读：
+
+- `_input.json`（只读，用于排查导入前结构）
+- `_exported.json`（只读，用于对比导出结果）
+- `guancli workflow get <parentWorkflowId> -f json` 的线上结构
+
+### 3. 只改 `etl/`
+
+只允许修改这些文件：
+
+- `etl/etl.go`
+- `etl/*.sql`
+- `etl/node_*.json`
+
+不要手改这些系统文件：
+
+- `_workspace_state.json`
+- `_wf_state.json`
+- `_parent_snapshot.json`
+- `_input.json`
+- `_exported.json`
+
+### 4. 改完永远按这个顺序
+
+1. `guanwf export --dir <workdir>`
+2. 需要看数据结果时再 `guanwf preview --dir <workdir>` 或 `guanwf preview <nodeId> --dir <workdir>`
+3. 确认无误后才 `guanwf save-draft --dir <workdir>` 或 `guanwf save --dir <workdir>`
+4. 需要执行时再 `guanwf run --wait --dir <workdir>`
+
+如果 `export` 没过，不要直接 `preview` 或 `save`。
+
+## 三种默认流程
+
+### 编辑已有数据流
+
+```bash
+# 获取数据流（参数必须是父工作流 ID，自动保存父工作流 snapshot）
+guanwf edit <parentWorkflowId>                        # 仅含一个数据流时自动选中
+guanwf edit <parentWorkflowId> --dataflow-id <dfId>   # 指定数据流
+
+# 在 etl/ 下修改 etl.go、*.sql、必要的 node_*.json
+# 不要改 _input.json、_parent_snapshot.json 或 _exported.json
+
+# 导出验证（有 etl.go 时自动走 yaegi runner）
+guanwf export --dir <workdir>
+
+# 预览节点
+guanwf preview --dir <workdir>
+guanwf preview <nodeId> --dir <workdir>
+
+# 保存草稿或发布
+guanwf save-draft --dir <workdir>
+guanwf save --dir <workdir>
+```
+
+`edit` 会把线上 actions 导入为 `etl.go`。复杂工作流节点可能被导入为 `etl/node_*.json` 并在 `etl.go` 中以 `LoadNodeFromFile(...)` 引用；这种 `node_*.json` 是可编辑源文件。
+
+### 新建数据流
+
+```bash
+# 创建（自动生成父工作流包裹）
+guanwf create --name "我的数据流" --parent-dir <dirId>
+guanwf create --name "DB数据流" --type DB_DATAFLOW --parent-dir <dirId>
+
+# 新建 etl/etl.go，按 references/ETL_AI_DEVELOP.md 编写 DefineETL()
+
+# 导出 -> 保存
+guanwf export --dir <workdir>
+guanwf save-draft --dir <workdir>
+```
+
+新建场景尤其不要把需求直接写进 `etl/actions.json`。应创建 `etl/etl.go`，把节点、依赖、输入、输出都放进 `DefineETL()`；输入数据集 ID 和字段 schema 写在 `BasicInputDataset(...)`，不是 `_input.json`。
+
+### 修复失败
+
+1. 先确认失败发生在 `export`、`preview`、`save` 还是 `run`。
+2. 如果失败来自 `export`，只改 `etl.go`、SQL 或被引用的 `node_*.json`。
+3. 如果失败来自 `preview`，先确认 `_exported.json` 是否由最新 `etl/` 生成；必要时先重跑 `export`。
+4. 如果失败来自 `save`，不要手写保存 payload；检查父工作流是否能重新拉取、目标 dataflow 是否还存在、以及本地 `_exported.json` 是否来自最新源文件。
+5. 从失败步骤往后重跑，不要把整个工作目录推倒重来。
+
+### 运行工作流
+
+```bash
+guanwf run --dir <workdir>              # 触发运行
+guanwf run --wait --dir <workdir>        # 等待完成
+guanwf run --wait --timeout 600 --dir <workdir>  # 自定义超时
+```
+
+## 工作目录结构
+
+```
+<workdir>/
+  _workspace_state.json   # etlworkspace 通用状态
+  _wf_state.json          # 工作流特有状态（parentId, dataflowId, isNew 等）
+  _parent_snapshot.json   # 父工作流完整快照（保存时使用）
+  _input.json             # 原始输入（runner 格式）
+  _exported.json          # export 导出结果（派生产物，不手改）
+  etl/
+    etl.go                 # 数据流节点定义（推荐，yaegi DSL）
+    *.sql                  # SQL 节点的独立 SQL 文件
+    node_*.json            # LoadNodeFromFile 透传节点配置
+    actions.json           # 历史兼容输入；新建/修改不要编辑
+```
+
+## save 的工作机制
+
+`save` / `save-draft` 不是简单把本地 JSON 上传。内部流程是：
+
+1. 读取本地 `_exported.json`（必须由 `export` 从 `etl/` 生成）
+2. 从服务端重新拉取父工作流最新版本
+3. 用字段级合并把目标 dataflow actions 替换进父工作流完整上下文
+4. 调用 `/process/save-draft` 或 `/process/save`
+5. 保存成功后刷新本地 parent snapshot
+
+因此用户和 AI 都不需要手写服务端保存 payload。只要 `etl/` 事实源正确、`export` 通过、父工作流仍可拉取，保存流程会保留同一父工作流里的其他数据流。
+
+## API 路由
+
+所有 API 通过 `/api/offline-dev/*` 前缀走 BFF 代理到工作流引擎。
+
+| 操作 | 方法 | 路径 |
+|------|------|------|
+| 分页查询 | POST | `/api/offline-dev/process/list-paging` |
+| 查询详情 | GET | `/api/offline-dev/process/{id}/select-by-id` |
+| 保存草稿 | POST | `/api/offline-dev/process/save-draft` |
+| 保存发布 | POST | `/api/offline-dev/process/save` |
+| 预览数据流 | POST | `/api/offline-dev/dataflow/preview-async` |
+| 查询预览任务 | GET | `/api/offline-dev/dataflow/task/{taskId}` |
+| 取消预览 | POST | `/api/offline-dev/dataflow/task/{taskId}/cancel` |
+| 运行工作流 | POST | `/api/offline-dev/process/{id}/start-process-instance` |
+| 查询运行实例 | GET | `/api/offline-dev/process/instance/{id}/select-by-id` |
+
+## 与其他 skill 的关系
+
+| 任务 | 工具 |
+|------|------|
+| BI ETL 编辑 | guanetl |
+| 工作流/数据流只读查询 | guancli workflow（隐藏子命令，需手动输入） |
+| 数据流编辑闭环 | guanwf（本工具） |
+| 数据集管理 | guands |
+| 通用 ETL 节点函数参考 | guanwf/references/ETL_AI_DEVELOP.md（symlink → guanetl） |
+| 工作流扩展节点参考 | guanwf/references/WORKFLOW_NODES.md |
+
+## 工作流特有节点
+
+工作流数据流是 BI ETL 的超集，额外支持以下节点类型：
+
+| 节点类型 | 函数 | 说明 |
+|---|---|---|
+| `INPUT_DATASOURCE` | `LoadNodeFromFile` / `BasicInputDatasource` | 数据库直连输入（无上游） |
+| `OUTPUT_DATASOURCE` | `LoadNodeFromFile` / `BasicOutputDatasource` | 数据回写到数据库 |
+| `INCREMENT_OUTPUT_DATASET` | `LoadNodeFromFile` / `BasicIncrementOutputDataset` | 增量输出数据集 |
+| `TRIM_COLUMNS` | `BasicTrimColumns` | 去空格 |
+| `VALUE_MAPPER` | `LoadNodeFromFile` | 值映射/替换 |
+| `SINGLE_VALUE_MAPPER` | `LoadNodeFromFile` | Null 值替换 |
+| `COMBINE_COLUMNS` | `BasicCombineColumns` | 合并列 |
+
+`guanwf edit` 导入时：
+- INPUT_DATASOURCE / OUTPUT_DATASOURCE / INCREMENT_OUTPUT_DATASET / VALUE_MAPPER / SINGLE_VALUE_MAPPER → 保存为 `node_<id>.json` + `LoadNodeFromFile("node_<id>.json")`
+- TRIM_COLUMNS / COMBINE_COLUMNS → 直接生成结构化 Go DSL 代码
+
+详细配置参数见 `references/WORKFLOW_NODES.md`。
+
+## 注意事项
+
+- 编辑时自动获取并保存父工作流 snapshot，save 时从服务端重新获取最新版本
+- actions 结构与 BI ETL 相同，节点函数和约束复用 guanetl 的 framework
+- DB_DATAFLOW 涉及 SQL 下推和单账号约束，后续可能需要额外处理
+- `guancli workflow` 子命令在 `guancli --help` 中不显示（隐藏命令），但手动输入可正常使用
+- 透传节点（`LoadNodeFromFile`）和结构化节点可互换使用，框架不限制

package/skills/guanwf/references/ETL_AI_DEVELOP.md

@@ -0,0 +1,281 @@
+# GuanETL AI 开发参考
+
+这份参考只保留 AI 真正常用、且最容易写错的部分。
+
+## 先读什么
+
+写 ETL 前，先按这个顺序看：
+
+1. `etl/etl.go`
+2. `etl/*.sql`
+3. 必要时 `etl/meta.json`
+4. 缺上下文时，用 `guancli` 查 ETL / ds / 字段，不要猜
+
+## 不可违反的规则
+
+```go
+import . "guanetl/internal/framework"
+
+func DefineETL() []Node
+```
+
+- 不要改点导入和 `DefineETL()` 签名。
+- 返回值必须是叶子节点数组，通常是一个或多个 `OUTPUT_DATASET`。
+- 节点 ID 必须唯一，格式必须是 `id_数字`。
+- 下游节点必须写在上游节点之后。
+- 只改 `etl/` 目录，不要手改 `_base_etl.json`、`_input.json`、`_exported.json`。
+- 对 `edit` 导入出来的 ETL，优先局部修改，尽量保留现有节点顺序和文件命名。
+
+## 节点选择顺序
+
+优先用专用节点，最后才用 SQL：
+
+1. `BasicInputDataset`
+2. `BasicSelectColumns`
+3. `BasicFilterRows`
+4. `BasicJoinData`
+5. `BasicGroupBy`
+6. `BasicCalculator`
+7. `BasicRemoveDuplicates`
+8. `BasicAppendRows`
+9. `BasicSqlScript`
+
+特别注意：
+
+- 等值 JOIN 不要写成 SQL，优先 `JOIN_DATA`。
+- 只是筛选、选列、聚合、去重时，不要默认上 SQL。
+- SQL 很长或有很多 CTE 时，优先拆成多个节点。
+
+## 输入字段 schema 放哪里
+
+输入字段 schema 以 `BasicInputDataset(..., []Field{...})` 为主。
+
+```go
+orders := BasicInputDataset("id_1001", "订单", "ds_orders", []Field{
+    BasicField("user_id", "STRING"),
+    BasicField("amount", "DOUBLE"),
+    BasicField("order_date", "DATE"),
+}, Position{X: 100, Y: 100})
+```
+
+- `go run ./cmd/guanetl export` 会把这里的字段带到最终 JSON。
+- `meta.json` 主要保留 ETL 名称等元信息。
+- 字段相关报错时，优先检查 `[]Field`，不要先怀疑 `meta.json`。
+
+## 最常用函数
+
+### 输入 / 输出
+
+```go
+BasicInputDataset(id, name, inputDsID string, fields []Field, position Position)
+BasicOutputDataset(id, name string, source Node, outputDsName string, position Position)
+BasicOutputDatasetInDir(id, name string, source Node, outputDsName, parentDirId string, position Position)
+```
+
+`BasicOutputDatasetInDir` 允许指定输出数据集的父目录 ID，避免落到根目录。目录 ID 可通过 `guancli ds tree` 获取。
+
+### 选列
+
+```go
+BasicSelectColumns(id, name string, source Node, columns []ColumnSetting, position Position)
+```
+
+```go
+[]ColumnSetting{
+    BasicColumnSetting("user_id"),
+    {Name: "amount", NewName: "pay_amount"},
+}
+```
+
+### 筛选
+
+```go
+BasicFilterRows(id, name string, source Node, combineType string, conditions []FilterCondition, position Position)
+```
+
+- `combineType` 只能是 `AND` 或 `OR`
+- 高频操作符：`EQ` `NE` `LT` `LE` `GT` `GE` `IN` `BT` `IS_NULL` `NOT_NULL` `CONTAINS` `NOT_CONTAINS` `STARTSWITH` `NOT_STARTSWITH` `ENDSWITH` `NOT_ENDSWITH`
+
+### 等值 JOIN
+
+```go
+BasicJoinData(id, name string, leftSource, rightSource Node, joinType string, joinColumns []JoinColumnPair, outputColumns []JoinOutputColumn, position Position)
+```
+
+- `joinType` 只能是 `INNER` `LEFT_OUTER` `RIGHT_OUTER` `FULL_OUTER`
+
+### 聚合
+
+```go
+BasicGroupBy(id, name string, source Node, groupByColumns []GroupByColumn, aggregationColumns []AggregationColumn, position Position)
+```
+
+- 聚合类型只用：`SUM` `COUNT` `COUNT_DISTINCT` `MIN` `MAX` `AVG` `FIRST_NOT_NULL`
+
+### SQL
+
+```go
+BasicSqlScript(id, name string, sources []Node, sql string, position Position)
+```
+
+推荐把 SQL 放到独立文件：
+
+```go
+node := BasicSqlScript(
+    "id_1005",
+    "复杂转换",
+    []Node{inputA, inputB},
+    ReadSQLFile("node_1005.sql"),
+    Position{X: 900, Y: 100},
+)
+```
+
+SQL 规则：
+
+- 上游节点在 SQL 中用 `input1`、`input2` 这类名字引用。
+- 特殊列名、中文列名、带空格列名，用反引号。
+- 新增 SQL 节点时，要同步新增 `.sql` 文件。
+
+## 推荐骨架
+
+```go
+package main
+
+import . "guanetl/internal/framework"
+
+func DefineETL() []Node {
+    inputA := BasicInputDataset("id_1001", "输入A", "ds_a", []Field{
+        BasicField("id", "STRING"),
+    }, Position{X: 100, Y: 100})
+
+    transformed := BasicFilterRows(
+        "id_1002",
+        "筛选A",
+        inputA,
+        "AND",
+        []FilterCondition{},
+        Position{X: 320, Y: 100},
+    )
+
+    output := BasicOutputDataset("id_1003", "输出", transformed, "结果数据集", Position{X: 560, Y: 100})
+    return []Node{output}
+}
+```
+
+## 每次改完都检查
+
+1. `DefineETL()` 返回的是叶子节点吗？
+2. 新节点 ID 唯一吗？格式对吗？
+3. 节点顺序符合依赖吗？
+4. `JOIN_DATA` / `GROUP_BY` / `FILTER_ROWS` 的枚举值合法吗？
+5. 新增 SQL 文件了吗？文件名和代码引用一致吗？
+6. 输入字段 schema 足够支撑后续节点吗？
+
+## 验证顺序
+
+始终按这个顺序：
+
+1. `go run ./cmd/guanetl export --dir <work_dir>`
+2. 需要看结果时：`go run ./cmd/guanetl preview <node_id> --dir <work_dir>`
+3. 确认无误后：`go run ./cmd/guanetl save --dir <work_dir>`
+
+如果 `export` 没过，不要直接 `save`。
+
+## Appendix: Framework Surface
+
+这部分只列 AI 写 ETL 时最值得记住的公开函数和合法枚举。
+源码真相在 runner framework 中，但不要把源码实现细节当成日常写法。
+
+### 推荐优先使用的 Basic 函数
+
+```go
+BasicInputDataset(id, name, inputDsID string, fields []Field, position Position)
+BasicOutputDataset(id, name string, source Node, outputDsName string, position Position)
+BasicOutputDatasetInDir(id, name string, source Node, outputDsName, parentDirId string, position Position)
+BasicSelectColumns(id, name string, source Node, columns []ColumnSetting, position Position)
+BasicFilterRows(id, name string, source Node, combineType string, conditions []FilterCondition, position Position)
+BasicJoinData(id, name string, leftSource, rightSource Node, joinType string, joinColumns []JoinColumnPair, outputColumns []JoinOutputColumn, position Position)
+BasicGroupBy(id, name string, source Node, groupByColumns []GroupByColumn, aggregationColumns []AggregationColumn, position Position)
+BasicCalculator(id, name string, source Node, formulas []Formula, position Position)
+BasicRemoveDuplicates(id, name string, source Node, columnNames []string, position Position)
+BasicAppendRows(id, name string, sources []Node, unionType string, schemaSource string, position Position)
+BasicSqlScript(id, name string, sources []Node, sql string, position Position)
+```
+
+### 只有需要完整配置时再用的 New 函数
+
+```go
+NewInputDataset(id, name string, config InputDatasetConfig)
+NewOutputDataset(id, name string, source Node, config OutputDatasetConfig)
+NewSelectColumns(id, name string, source Node, config SelectColumnsConfig)
+NewFilterRows(id, name string, source Node, config FilterRowsConfig)
+NewJoinData(id, name string, leftSource, rightSource Node, config JoinDataConfig)
+NewGroupBy(id, name string, source Node, config GroupByConfig)
+NewCalculator(id, name string, source Node, config CalculatorConfig)
+NewRemoveDuplicates(id, name string, source Node, config RemoveDuplicatesConfig)
+NewAppendRows(id, name string, sources []Node, config AppendRowsConfig)
+NewSqlScript(id, name string, sources []Node, config SqlScriptConfig)
+```
+
+默认优先 `Basic*`，除非你明确需要手动控制更底层配置。
+
+### 高频辅助函数
+
+```go
+BasicField(name, fieldType string)
+BasicColumnSetting(name string)
+BasicJoinColumnPair(leftColumn, rightColumn string)
+BasicJoinOutputFromLeft(columnName string)
+BasicJoinOutputFromRight(columnName string)
+BasicJoinOutputFromLeftWithAlias(columnName, alias string)
+BasicJoinOutputFromRightWithAlias(columnName, alias string)
+BasicGroupByColumn(name, columnType string)
+BasicGroupByColumnWithAlias(name, columnType, newName string)
+BasicAggregationColumn(name, columnType, aggregationType string)
+BasicAggregationColumnWithAlias(name, columnType, aggregationType, newName string)
+BasicFilterCondition(columnName, operator string, filterValues []FilterValue)
+BasicFilterValue(value string)
+BasicFilterColumnValue(columnName string)
+ReadSQLFile(filename string)
+```
+
+### 合法枚举
+
+筛选组合：
+
+- `AND`
+- `OR`
+
+筛选操作符：
+
+- `EQ` `NE`
+- `LT` `LE` `GT` `GE`
+- `IN`
+- `BT`
+- `IS_NULL` `NOT_NULL`
+- `CONTAINS` `NOT_CONTAINS`
+- `STARTSWITH` `NOT_STARTSWITH`
+- `ENDSWITH` `NOT_ENDSWITH`
+
+JOIN 类型：
+
+- `INNER`
+- `LEFT_OUTER`
+- `RIGHT_OUTER`
+- `FULL_OUTER`
+
+聚合类型：
+
+- `SUM`
+- `COUNT`
+- `COUNT_DISTINCT`
+- `MIN`
+- `MAX`
+- `AVG`
+- `FIRST_NOT_NULL`
+
+APPEND_ROWS unionType：
+
+- `INCLUDE_SHARED`
+- `INCLUDE_ALL`
+- `INCLUDE_FROM`

package/skills/guanwf/references/WORKFLOW_NODES.md

@@ -0,0 +1,163 @@
+# 工作流数据流扩展节点参考
+
+本文档描述工作流数据流中相对于 BI ETL 的超集节点类型。
+通用 ETL 节点（INPUT_DATASET、OUTPUT_DATASET、SQL_SCRIPT 等）的用法参见 `ETL_AI_DEVELOP.md`（symlink 到 guanetl）。
+
+## 透传节点（LoadNodeFromFile 模式）
+
+以下节点在 `guanwf edit` 导入时自动保存为 `node_XXXX.json` 独立文件，`etl.go` 中通过 `LoadNodeFromFile` 引用。
+这些节点配置复杂且与数据库连接紧密绑定，通常不需要手动修改。
+
+### INPUT_DATASOURCE（数据源输入）
+
+数据库直连输入，无上游 source。从关系型数据库中读取数据到数据流。
+
+```go
+// 透传模式（edit 路径推荐）
+node_1001 := LoadNodeFromFile("node_1001.json")
+
+// 结构化模式（create 路径）
+node_1001 := BasicInputDatasource("id_1001", "数据库输入", InputDatasourceConfig{
+    BaseConfig: BaseConfig{Position: Position{X: 100, Y: 100}},
+    AcId:       "ac_xxx",
+    CnId:       "cn_yyy",
+    Sql:        ReadSQLFile("input_query.sql"),
+    SourceType: "DIRECT_CONNECT",
+})
+```
+
+配置说明：
+- `AcId`: 数据账号 ID（通过 `guands account list` 获取）
+- `CnId`: 数据连接 ID（通过 `guands account get <acId>` 获取）
+- `Sql`: 查询 SQL（支持 ReadSQLFile 引用独立文件）
+- `SourceType`: `DIRECT_CONNECT`（数据库直连）或 `DATASET`（引用数据集）
+
+### OUTPUT_DATASOURCE（数据源输出）
+
+数据回写到数据库，有上游 source。
+
+```go
+// 透传模式（edit 路径推荐）
+node_1005 := LoadNodeFromFile("node_1005.json", node_1004)
+
+// 结构化模式（create 路径）
+node_1005 := BasicOutputDatasource("id_1005", "数据回写", node_1004, OutputDatasourceConfig{
+    BaseConfig:  BaseConfig{Position: Position{X: 500, Y: 100}},
+    AcId:        "ac_xxx",
+    CnId:        "cn_yyy",
+    TargetTable: "target_table",
+    UpdateMode:  "OVERWRITE",
+})
+```
+
+配置说明：
+- `TargetTable`: 目标表名
+- `UpdateMode`: `OVERWRITE`（覆盖）、`APPEND`（追加）、`UPSERT`（更新插入）
+- `Schema`: 目标 schema（可选）
+- `PrimaryKeys`: UPSERT 模式的主键列
+- `PreSql`/`PostSql`: 写入前/后执行的 SQL（可选）
+
+### INCREMENT_OUTPUT_DATASET（增量输出数据集）
+
+增量方式写入观远数据集（与 OUTPUT_DATASET 的区别是支持增量更新策略）。
+
+```go
+// 透传模式
+node_1006 := LoadNodeFromFile("node_1006.json", node_1005)
+```
+
+配置说明：
+- `OutputDsId`: 输出数据集 ID
+- `UpdateMode`: `APPEND`（追加）或 `UPSERT`（更新插入）
+- `PrimaryKeys`: UPSERT 模式的主键列
+
+## 原生 DSL 节点
+
+以下节点有结构化的 Go DSL 函数，import 后会生成可直接编辑的代码。
+
+### TRIM_COLUMNS（去空格）
+
+对指定列去除首尾空格。
+
+```go
+node := BasicTrimColumns("id_1002", "去空格", source, []string{"name", "address"}, Position{X: 300, Y: 100})
+```
+
+参数：
+- `columnNames`: 要处理的列名列表（对应 BI 端 `columnNames` 字段）
+
+### COMBINE_COLUMNS（合并列）
+
+将多个列合并为一个新列。
+
+```go
+node := BasicCombineColumns("id_1005", "合并地址", source, "full_address", []string{"city", "street"}, ", ", false, Position{X: 600, Y: 100})
+```
+
+参数：
+- `targetFieldName`: 新列名
+- `fields`: 要合并的源列名列表
+- `separator`: 分隔符
+- `removeSelectedFields`: 是否删除源列
+
+## 透传 DSL 节点（复杂 mappings 类）
+
+以下节点因配置结构复杂（含嵌套数组/对象），import 时使用 `LoadNodeFromFile` 透传模式保存完整 JSON，确保往返保真。
+
+### VALUE_MAPPER（值映射/值替换）
+
+将指定列的值按映射表替换。
+
+```go
+// import 自动生成（透传模式）
+node_1003 := LoadNodeFromFile("node_id_1003.json", source)
+```
+
+配置说明（编辑 `node_*.json` 文件）：
+- `column`: 源列名
+- `targetField`: 目标列名（可与源列相同）
+- `mappings`: 映射规则数组
+- `defaultValue`: 不匹配时的默认值
+
+### SINGLE_VALUE_MAPPER（Null 值替换）
+
+将指定列的 null 值替换为固定值。import 时使用 LoadNodeFromFile 透传模式。
+
+```go
+// import 自动生成（透传模式）
+node_1004 := LoadNodeFromFile("node_id_1004.json", source)
+```
+
+配置说明（编辑 `node_*.json` 文件中的 `mappings` 数组）：
+- `mappings`: 列值映射列表，每条包含：
+  - `colName`: 目标列名
+  - `origValue`: 原始值（`null` 表示匹配 null）
+  - `toValue`: 替换值
+
+## SQL Fallback 节点
+
+以下节点类型不做原生支持，import 时由 guanetl-server 生成等价 SQL 转为 `BasicSqlScript`：
+
+| 节点类型 | 说明 |
+|---|---|
+| `COLLAPSE_COLUMNS` | 列转行 |
+| `UNCOLLAPSE_COLUMNS` | 行转列 |
+| `BENCHMARKING` | 智能对标 |
+| `FREQ_PATTERN` | 关联性挖掘 |
+| `DATA_INSIGHT` | 智能归因 |
+
+## 不支持的节点类型
+
+以下节点类型在当前版本中不支持 import，遇到时会报错：
+
+| 节点类型 | 说明 |
+|---|---|
+| `SAP_ERP_INPUT` | SAP ERP 输入 |
+| `FTP_INPUT` | FTP 输入 |
+
+## LoadNodeFromFile 使用规则
+
+1. **透传与结构化可互换**：用户可以把 `LoadNodeFromFile(...)` 替换为 `BasicInputDatasource(...)`（或反过来），框架不限制。
+2. **修改透传节点**：直接编辑对应的 `node_XXXX.json` 文件即可。
+3. **JSON 文件命名**：`node_` + 节点 ID（sanitize 后保留字母/数字/下划线/连字符）+ `.json`。
+4. **sources 自动处理**：export 时 `LoadedNode.ToMap()` 会根据函数参数中的 sources 自动更新 `sources` 字段。