@guandata/guanwf 0.1.832 → 0.1.833

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guanwf 0.1.833 - 2026-09-09
+
+- DSL 新增节点类型、依赖类型和更新模式等类型化常量，同时保留已有字符串写法的兼容性。
+- 改进工作流定义的序列化、导入与导出稳定性，减少往返编辑时的语义漂移。
+- 统一错误分类和提示，自动化流程可更准确地区分输入、状态与后端失败。
+
 ## @guandata/guanwf 0.1.832 - 2026-09-03
 
 - 同步底层 CLI 执行器解析更新，改善 Windows npm 全局安装和多种程序路径下的运行兼容性。

package/README.md

@@ -48,6 +48,11 @@ guanwf install-skill
 
 ## 版本更新
 
+### @guandata/guanwf 0.1.833
+
+- DSL 提供节点类型、依赖类型和更新模式等类型化常量，并兼容已有字符串写法。
+- 改进定义的序列化和往返编辑稳定性，统一可供自动化判断的错误分类。
+
 ### @guandata/guanwf 0.1.832
 
 - 改善 Windows npm 全局安装和多种程序路径下的底层调用兼容性。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanwf",
-  "version": "0.1.832",
+  "version": "0.1.833",
   "description": "观远工作流数据流编辑工具 - 创建、编辑、导出、预览、保存数据流",
   "bin": {
     "guanwf": "bin/run.js"

package/skills/guanwf/references/ETL_AI_DEVELOP.md

@@ -52,9 +52,9 @@ func DefineETL() []Node
 
 ```go
 orders := BasicInputDataset("id_1001", "订单", "ds_orders", []Field{
-    BasicField("user_id", "STRING"),
-    BasicField("amount", "DOUBLE"),
-    BasicField("order_date", "DATE"),
+    BasicField("user_id", FieldTypeSTRING),
+    BasicField("amount", FieldTypeDOUBLE),
+    BasicField("order_date", FieldTypeDATE),
 }, Position{X: 100, Y: 100})
 ```
 
@@ -74,19 +74,19 @@ orders := BasicInputDataset("id_1001", "订单", "ds_orders", []Field{
 calc := BasicCalculator("id_1002", "解析展示格式度量", inputA, []Formula{
     {
         Name: "下单转化率_数值",
-        Type: "DOUBLE",
+        Type: FieldTypeDOUBLE,
         Expr: "CAST(REPLACE([下单转化率], \"%\", \"\") AS DOUBLE) / 100",
         Key:  "formula_order_rate_value",
     },
     {
         Name: "营业时长_分钟",
-        Type: "DOUBLE",
+        Type: FieldTypeDOUBLE,
         Expr: "CAST(IF(REGEXP_EXTRACT([营业时长], \"([0-9.]+)小时\", 1) = \"\", \"0\", REGEXP_EXTRACT([营业时长], \"([0-9.]+)小时\", 1)) AS DOUBLE) * 60 + CAST(IF(REGEXP_EXTRACT([营业时长], \"([0-9.]+)分\", 1) = \"\", \"0\", REGEXP_EXTRACT([营业时长], \"([0-9.]+)分\", 1)) AS DOUBLE)",
         Key:  "formula_open_minutes",
     },
     {
         Name: "店铺分_数值",
-        Type: "DOUBLE",
+        Type: FieldTypeDOUBLE,
         Expr: "CAST([店铺分] AS DOUBLE)",
         Key:  "formula_store_score_value",
     },
@@ -122,7 +122,7 @@ BasicOutputDataset(id, name string, source Node, outputDsName string, position P
 BasicOutputDatasetInDir(id, name string, source Node, outputDsName, parentDirId string, position Position)
 ```
 
-`BasicOutputDatasetInDir` 允许指定输出数据集的父目录 ID，避免落到根目录。目录 ID 可通过 `guancli ds tree` 获取。
+**新建输出节点必须用 `BasicOutputDatasetInDir`** 并传入 `guanetl create --output-parent-dir` 确认过的 DATA_SET 目录 id；`save` 会拒绝没有目录的新输出（服务端对空目录不报错而是静默落到根目录，不符合目录管理规范）。无目录版本的 `BasicOutputDataset` 只用于 `edit` 回读已物化输出时的往返兼容（目录已固化在服务端 dataSource 中），不要在新增输出时使用。目录 ID 可通过 `guancli ds tree` 获取，不存在时用 `guanetl mkdir --type DATA_SET` 显式创建。
 
 新建 ETL 时有两类目录 id，不能混用：
 
@@ -147,20 +147,20 @@ BasicSelectColumns(id, name string, source Node, columns []ColumnSetting, positi
 ### 筛选
 
 ```go
-BasicFilterRows(id, name string, source Node, combineType string, conditions []FilterCondition, position Position)
+BasicFilterRows(id, name string, source Node, combineType CombineType, conditions []FilterCondition, position Position)
 ```
 
-- `combineType` 只能是 `AND` 或 `OR`
-- 高频操作符：`EQ` `NE` `LT` `LE` `GT` `GE` `IN` `BT` `CONTAINS` `NOT_CONTAINS` `STARTSWITH` `NOT_STARTSWITH` `ENDSWITH` `NOT_ENDSWITH`
+- `combineType` 用常量 `CombineTypeAND` / `CombineTypeOR`
+- 操作符用 `FilterOp*` 常量：`FilterOpEQ` `FilterOpNE` `FilterOpLT` `FilterOpLE` `FilterOpGT` `FilterOpGE` `FilterOpIN` `FilterOpBT` `FilterOpCONTAINS` `FilterOpNOTCONTAINS` `FilterOpSTARTSWITH` `FilterOpNOTSTARTSWITH` `FilterOpENDSWITH` `FilterOpNOTENDSWITH`
 - 当前 `BasicFilterRows` 不支持 `IS_NULL` / `NOT_NULL`；null 过滤请改用 SQL 节点（如 ``WHERE `列名` IS NULL`` / ``IS NOT NULL``）。
 
 ### 等值 JOIN
 
 ```go
-BasicJoinData(id, name string, leftSource, rightSource Node, joinType string, joinColumns []JoinColumnPair, outputColumns []JoinOutputColumn, position Position)
+BasicJoinData(id, name string, leftSource, rightSource Node, joinType JoinType, joinColumns []JoinColumnPair, outputColumns []JoinOutputColumn, position Position)
 ```
 
-- `joinType` 只能是 `INNER` `LEFT_OUTER` `RIGHT_OUTER` `FULL_OUTER`
+- `joinType` 用常量 `JoinTypeINNER` `JoinTypeLEFTOUTER` `JoinTypeRIGHTOUTER` `JoinTypeFULLOUTER`
 
 ### 聚合
 
@@ -168,7 +168,7 @@ BasicJoinData(id, name string, leftSource, rightSource Node, joinType string, jo
 BasicGroupBy(id, name string, source Node, groupByColumns []GroupByColumn, aggregationColumns []AggregationColumn, position Position)
 ```
 
-- 聚合类型只用：`SUM` `COUNT` `COUNT_DISTINCT` `MIN` `MAX` `AVG` `FIRST_NOT_NULL`
+- 聚合类型用常量 `AggrTypeSUM` `AggrTypeCOUNT` `AggrTypeCOUNTDISTINCT` `AggrTypeMIN` `AggrTypeMAX` `AggrTypeAVG` `AggrTypeFIRSTNOTNULL`
 
 ### 计算列
 
@@ -181,14 +181,14 @@ BasicCalculator(id, name string, source Node, formulas []Formula, position Posit
 ```go
 Formula{
     Name: "订单金额等级",
-    Type: "STRING",
+    Type: FieldTypeSTRING,
     Expr: "IF([金额] >= 1000, \"大额\", \"普通\")",
     Key:  "formula_amount_level",
 }
 ```
 
 - `Name` 是新增列名。
-- `Type` 是新增列类型，只用：`INT` `DOUBLE` `STRING` `TIMESTAMP` `LONG` `SHORT` `FLOAT` `DATE` `BOOL` `DECIMAL` `ARRAY`。
+- `Type` 是新增列类型，用 `FieldType*` 常量：`FieldTypeINT` `FieldTypeDOUBLE` `FieldTypeSTRING` `FieldTypeTIMESTAMP` `FieldTypeLONG` `FieldTypeSHORT` `FieldTypeFLOAT` `FieldTypeDATE` `FieldTypeBOOL` `FieldTypeDECIMAL` `FieldTypeARRAY`。
 - `Expr` 是服务端公式表达式，字段引用必须写成 `[字段名]`。
 - `Key` 在同一个 `CALCULATOR` 节点内必须唯一；建议用稳定字符串，不要留空。
 
@@ -217,13 +217,13 @@ Formula{
 calc := BasicCalculator("id_1002", "新增计算列", inputA, []Formula{
     {
         Name: "含税金额",
-        Type: "DOUBLE",
+        Type: FieldTypeDOUBLE,
         Expr: "ROUND([金额] * 1.13, 2)",
         Key:  "formula_tax_amount",
     },
     {
         Name: "门店前缀",
-        Type: "STRING",
+        Type: FieldTypeSTRING,
         Expr: "LEFT([门店ID], 2)",
         Key:  "formula_store_prefix",
     },
@@ -264,14 +264,14 @@ import . "guanetl/internal/framework"
 
 func DefineETL() []Node {
     inputA := BasicInputDataset("id_1001", "输入A", "ds_a", []Field{
-        BasicField("id", "STRING"),
+        BasicField("id", FieldTypeSTRING),
     }, Position{X: 100, Y: 100})
 
     transformed := BasicFilterRows(
         "id_1002",
         "筛选A",
         inputA,
-        "AND",
+        CombineTypeAND,
         []FilterCondition{},
         Position{X: 320, Y: 100},
     )
@@ -292,9 +292,9 @@ import . "guanetl/internal/framework"
 
 func DefineETL() []Node {
     orders := BasicInputDataset("id_1001", "订单", "ds_orders", []Field{
-        BasicField("门店", "STRING"),
-        BasicField("订单号", "STRING"),
-        BasicField("销售额", "DOUBLE"),
+        BasicField("门店", FieldTypeSTRING),
+        BasicField("订单号", FieldTypeSTRING),
+        BasicField("销售额", FieldTypeDOUBLE),
     }, Position{X: 100, Y: 120})
 
     detail := BasicSelectColumns("id_1002", "订单明细", orders, []ColumnSetting{
@@ -308,10 +308,10 @@ func DefineETL() []Node {
         "门店汇总",
         orders,
         []GroupByColumn{
-            BasicGroupByColumn("门店", "STRING"),
+            BasicGroupByColumn("门店", FieldTypeSTRING),
         },
         []AggregationColumn{
-            BasicAggregationColumnWithAlias("销售额", "DOUBLE", "SUM", "销售额合计"),
+            BasicAggregationColumnWithAlias("销售额", FieldTypeDOUBLE, AggrTypeSUM, "销售额合计"),
         },
         Position{X: 340, Y: 200},
     )
@@ -378,12 +378,12 @@ 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)
+BasicFilterRows(id, name string, source Node, combineType CombineType, conditions []FilterCondition, position Position)
+BasicJoinData(id, name string, leftSource, rightSource Node, joinType JoinType, 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)
+BasicAppendRows(id, name string, sources []Node, unionType UnionType, schemaSource string, position Position)
 BasicSqlScript(id, name string, sources []Node, sql string, position Position)
 ```
 
@@ -407,18 +407,18 @@ NewSqlScript(id, name string, sources []Node, config SqlScriptConfig)
 ### 高频辅助函数
 
 ```go
-BasicField(name, fieldType string)
+BasicField(name string, fieldType FieldType)
 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)
+BasicGroupByColumn(name string, columnType FieldType)
+BasicGroupByColumnWithAlias(name string, columnType FieldType, newName string)
+BasicAggregationColumn(name string, columnType FieldType, aggregationType AggregationType)
+BasicAggregationColumnWithAlias(name string, columnType FieldType, aggregationType AggregationType, newName string)
+BasicFilterCondition(columnName string, operator FilterOperator, filterValues []FilterValue)
 BasicFilterValue(value string)
 BasicFilterColumnValue(columnName string)
 ReadSQLFile(filename string)
@@ -428,55 +428,29 @@ ReadSQLFile(filename string)
 
 ```go
 type Formula struct {
-    Name string `json:"name"`
-    Type string `json:"type"`
-    Expr string `json:"expr"`
-    Key  string `json:"key"`
+    Name string    `json:"name"`
+    Type FieldType `json:"type"`
+    Expr string    `json:"expr"`
+    Key  string    `json:"key"`
 }
 ```
 
-### 合法枚举
+### 枚举常量（优先使用常量）
 
-筛选组合：
+JOIN 类型、筛选组合、操作符、聚合类型、UNION 类型、字段/公式类型都是命名类型，
+框架提供同名常量，命名规则是 `<类型前缀> + 去掉下划线的值`（`COUNT_DISTINCT` → `AggrTypeCOUNTDISTINCT`）。
+**优先写常量**：常量名拼错会在 `export` 求值脚本时直接报 `undefined`，而字符串字面量拼错要等到图校验阶段才发现。
+字符串字面量（`"INNER"`）仍然可用（存量脚本无需修改，`guanetl lint` 会提示改用常量）；
+把 `string` 变量传给枚举参数需要显式转换，例如 `JoinType(v)`。
 
-- `AND`
-- `OR`
-
-筛选操作符：
-
-- `EQ` `NE`
-- `LT` `LE` `GT` `GE`
-- `IN`
-- `BT`
-- `CONTAINS` `NOT_CONTAINS`
-- `STARTSWITH` `NOT_STARTSWITH`
-- `ENDSWITH` `NOT_ENDSWITH`
-
-当前限制：
-
-- `BasicFilterRows` 暂不支持 `IS_NULL` / `NOT_NULL`；null 过滤请使用 `BasicSqlScript`。
-
-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`
+| 枚举 | 常量 | 说明 |
+|---|---|---|
+| 筛选组合 `CombineType` | `CombineTypeAND` `CombineTypeOR` | |
+| 筛选操作符 `FilterOperator` | `FilterOpEQ` `FilterOpNE` `FilterOpLT` `FilterOpLE` `FilterOpGT` `FilterOpGE` `FilterOpIN` `FilterOpBT` `FilterOpCONTAINS` `FilterOpNOTCONTAINS` `FilterOpSTARTSWITH` `FilterOpNOTSTARTSWITH` `FilterOpENDSWITH` `FilterOpNOTENDSWITH` | `FilterOpISNULL` / `FilterOpNOTNULL` 当前后端 FILTER_ROWS 不支持，null 过滤请用 `BasicSqlScript` |
+| 筛选值类型 `FilterValueType` | `FilterValueTypeVALUE` `FilterValueTypeCOLUMN` | 通常经 `BasicFilterValue` / `BasicFilterColumnValue` 间接使用 |
+| JOIN 类型 `JoinType` | `JoinTypeINNER` `JoinTypeLEFTOUTER` `JoinTypeRIGHTOUTER` `JoinTypeFULLOUTER` | 服务端把 FULL_OUTER 记为 OUTER，框架自动转换 |
+| 聚合类型 `AggregationType` | `AggrTypeSUM` `AggrTypeCOUNT` `AggrTypeCOUNTDISTINCT` `AggrTypeMIN` `AggrTypeMAX` `AggrTypeAVG` `AggrTypeFIRSTNOTNULL` | 服务端记为 SUM/CNT/CNT_DISTINCT/MIN/MAX/AVG/NUL，框架自动转换 |
+| APPEND_ROWS `UnionType` | `UnionTypeINCLUDESHARED` `UnionTypeINCLUDEALL` `UnionTypeINCLUDEFROM` | |
+| 字段/公式类型 `FieldType` | `FieldTypeINT` `FieldTypeDOUBLE` `FieldTypeSTRING` `FieldTypeTIMESTAMP` `FieldTypeLONG` `FieldTypeSHORT` `FieldTypeFLOAT` `FieldTypeDATE` `FieldTypeBOOL` `FieldTypeDECIMAL` `FieldTypeARRAY` | `Formula.Type` 只能取这些值；`BasicInputDataset` 的字段类型来自服务端，可能超出该列表，按 `guancli ds get` 的结果照写即可 |
 
 `BasicAppendRows` 会按列名对齐各输入源。参与拼接的同名列类型必须一致；例如一侧为 `DATE`、另一侧为 `LONG` 会在 `export` 阶段报错。遇到冲突时，先用 `BasicCalculator` / `BasicSelectColumns` 把各源字段统一类型或移除不用的冲突列，再执行行拼接。

package/skills/guanwf/references/WORKFLOW_DSL.md

@@ -54,7 +54,7 @@ func DefineWorkflow() Workflow {
 	py := PythonNode("python_1", "汇总分析", PythonConfig{
 		InputDatasets: []string{"<输入数据集ID>"},
 		Outputs: []PythonOutput{
-			{Name: "销售汇总", ParentDirID: "<数据集目录ID>", UpdateMode: "OVERWRITE"},
+			{Name: "销售汇总", ParentDirID: "<数据集目录ID>", UpdateMode: UpdateModeOVERWRITE},
 		},
 	}, After(df)) // 依赖：df 成功后运行
 
@@ -181,7 +181,7 @@ PythonConfig{
 			ClearDatasetBinding: false,       // 显式解除 edit 回读的已有 dsId 绑定
 			Created:     false,              // true 仅表示数据集由当前工作流创建
 			ParentDirID: "<数据集目录ID>",   // 必填，guancli dir tree 可查
-			UpdateMode:  "OVERWRITE",        // OVERWRITE（覆盖）/ APPEND（追加），默认 OVERWRITE
+			UpdateMode:  UpdateModeOVERWRITE, // UpdateModeOVERWRITE（覆盖）/ UpdateModeAPPEND（追加），默认 OVERWRITE；字面量 "OVERWRITE" 仍可用
 			PrimaryKeys: []string{"id"},     // 可选，按主键去重
 			Desc:        "描述",             // 可选
 		},

package/skills/guanwf/references/WORKFLOW_NODES.md

@@ -46,13 +46,13 @@ node_1005 := BasicOutputDatasource("id_1005", "数据回写", node_1004, OutputD
     AcId:        "ac_xxx",
     CnId:        "cn_yyy",
     TargetTable: "target_table",
-    UpdateMode:  "OVERWRITE",
+    UpdateMode:  UpdateModeOVERWRITE,
 })
 ```
 
 配置说明：
 - `TargetTable`: 目标表名
-- `UpdateMode`: `OVERWRITE`（覆盖）、`APPEND`（追加）、`UPSERT`（更新插入）
+- `UpdateMode`: `UpdateModeOVERWRITE`（覆盖）、`UpdateModeAPPEND`（追加）、`UpdateModeUPSERT`（更新插入）；字面量 `"OVERWRITE"` 等仍可用，`guanetl lint` 会提示改用常量
 - `Schema`: 目标 schema（可选）
 - `PrimaryKeys`: UPSERT 模式的主键列
 - `PreSql`/`PostSql`: 写入前/后执行的 SQL（可选）
@@ -69,7 +69,7 @@ node_1006 := LoadNodeFromFile("node_1006.json", node_1005)
 配置说明：
 - `OutputDsId`: 输出数据集 ID（序列化为服务端的 `dsId` 键；绑定已有数据集时填写）
 - `ParentDirID`: 输出数据集目录（DATA_SET 目录树 id，新建输出必填，缺失会导致运行期报错）
-- `UpdateMode`: `APPEND`（追加）或 `UPSERT`（更新插入）
+- `UpdateMode`: `UpdateModeAPPEND`（追加）或 `UpdateModeUPSERT`（更新插入）
 - `PrimaryKeys`: UPSERT 模式的主键列
 
 推荐优先使用透传模式（LoadNodeFromFile），可保留服务端节点的全部配置。