@guandata/guanwf 0.1.824 → 0.1.826

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## @guandata/guanwf 0.1.826 - 2026-08-07
+
+- 完善工作流输出落位闭环，支持目录预检与目标资源存在性判定，提升保存和执行流程的可靠性。
+- 修复工作流输出绑定中的字段错位问题，确保数据集同步与输出配置正确关联。
+- 更新工作流节点使用说明，补充输出落位相关行为和操作指引。
+## @guandata/guanwf 0.1.825 - 2026-08-05
+
+- Python 节点输出支持绑定已有数据集，可直接覆盖或追加到指定数据集，避免重复创建输出并保持下游引用稳定。
+- 编辑已有工作流时会回读并保留输出数据集绑定状态，同时在保存前校验无效配置。
+
 ## @guandata/guanwf 0.1.824 - 2026-07-29
 
 - 工作流目录树支持按关键词和最大深度缩小范围，文本与 JSON 输出都能清楚标记被省略的层级。

package/README.md

@@ -47,6 +47,16 @@ guanwf install-skill
 
 ## 版本更新
 
+### @guandata/guanwf 0.1.826
+
+- 完善工作流输出落位校验，保存和执行时能更准确地确认目标数据集。
+- 修复输出绑定中的字段错位问题，提升数据集同步准确性。
+
+### @guandata/guanwf 0.1.825
+
+- Python 节点输出支持绑定已有数据集，可直接覆盖或追加到指定数据集，避免重复创建输出并保持下游引用稳定。
+- 编辑已有工作流时会回读并保留输出数据集绑定状态，同时在保存前校验无效配置。
+
 ### @guandata/guanwf 0.1.824
 
 - 工作流目录树支持按关键词和最大深度缩小范围，文本与 JSON 输出都能清楚标记被省略的层级。

package/package.json

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

package/skills/guanwf/SKILL.md

@@ -348,8 +348,15 @@ NEED_FAULT_TOLERANCE。适用于长链路编排中
    本地快照里有、导出里删了的节点 → 删除；服务端有、本地快照不知道的节点（他人并发新增）→
    保留并打印提示
 5. dataflowJson 按 dataflow id 经 etlmerge 做 actions 字段级合并（成员判断同上）
-6. 调用 `/process/save-draft` 或 `/process/save`，成功后刷新本地快照并把服务端回写的
-   Python 参数同步进 `python.json`
+6. 调用 `/process/save-draft` 或 `/process/save`，成功后把**本次提交的定义**刷新为本地快照
+   并同步进 `python.json`（不是服务端回写值——服务端在保存/运行后对输出 dataSource/dsId
+   等字段的回写需要重新 `guanwf edit` 才能拿到），随后回读服务端做输出落位诊断：
+   目录被纠正时提示 `save.output_dir_rectified`，输出尚未物化时提示
+   `save.output_pending_materialization`（此时 dsId 是临时值，首次成功运行前每次保存都会
+   重新生成，勿用于下游引用）。`run` 等待成功后会校验所有输出的数据集实体线上存在
+   （`created=true` 直接通过；`created=false` 会查询数据集本身——绑定其他流程创建的
+   已有数据集时 DSL 要求保持 `Created=false`，该状态合法），数据集不存在的输出会直接
+   报错（后端存在"脚本未产出输出时静默跳过注册但任务 SUCCESS"的路径）。
 
 因此用户和 AI 都不需要手写服务端保存 payload。多人/多端并发修改同一工作流时，以服务端
 最新版本为基底合并，不会把别人新加的节点冲掉；但同一节点的并发修改仍是后保存者覆盖。

package/skills/guanwf/references/ETL_AI_DEVELOP.md

@@ -357,7 +357,7 @@ func DefineETL() []Node {
 当本地输出节点 id 被重新生成，但 `outputDsName + parentDirId` 与一个服务端已绑定输出唯一匹配时，`save` 会在请求副本中自动恢复原节点 id 和 dsId，并在影响报告中输出 `save.output_binding_reconciled`。源 `_exported.json` 不会被改写。跨目录、双方重名歧义、删除旧输出或无法唯一匹配时不会自动协调。
 
 - 再次修改已保存 ETL，优先重新执行 `guanetl edit <etl_id> --dir <新目录>`，不要长期复用旧工作目录。
-- 只追加输出列时，可以原地 `save`：新增列，不改名、不删已有列、不改已有列类型，并保持原 `OUTPUT_DATASET` 节点 id 和 `outputDsName`。
+- 只追加输出列时，可以原地 `save`：新增列，不改名、不删已有列、不改已有列类型，并保持原 `OUTPUT_DATASET` 节点 id 和 `outputDsName`；但这只保证输出身份稳定，不保证旧 DATAFLOW 数据集的字段目录已同步。对新增并透传到输出的 `BasicCalculator` 字段，必须执行 `guanetl run <etlId> --wait`：命令会按输出数据集独立等待本轮物化，并同时验证 metadata 与实际 preview 返回字段；任一目标输出尚未完成或字段缺失都会报错。
 - 修改已有输出 schema 时，保持原 `OUTPUT_DATASET` 节点 id；改列名、删列、改已有列类型、换输入数据集或重接输出链路都可能影响下游绑定，保存前必须重新 `preview` 并评估下游。
 - 如果用 `guands dataset rename` 改过 ETL 输出数据集名称，必须同步 `etl.go` 中 `BasicOutputDataset(..., outputDsName, ...)` 或 `BasicOutputDatasetInDir(..., outputDsName, ...)` 的名称。
 - 不要为了绕过同名错误手动删除旧输出数据集；旧输出通常仍被 ETL 依赖。

package/skills/guanwf/references/WORKFLOW_DSL.md

@@ -143,6 +143,8 @@ PythonConfig{
 	Outputs: []PythonOutput{                   // 输出数据集，顺序对应 output1, output2, ...
 		{
 			Name:        "输出数据集名",      // 必填，目录内唯一
+			DatasetID:   "",                 // 新建时留空；更新已有数据集时填写其 dsId
+			Created:     false,              // true 仅表示数据集由当前工作流创建
 			ParentDirID: "<数据集目录ID>",   // 必填，guancli dir tree 可查
 			UpdateMode:  "OVERWRITE",        // OVERWRITE（覆盖）/ APPEND（追加），默认 OVERWRITE
 			PrimaryKeys: []string{"id"},     // 可选，按主键去重
@@ -155,9 +157,10 @@ PythonConfig{
 }
 ```
 
-输出数据集**不需要也不应该手填 dsId**：首次运行时 BI 服务端在 `ParentDirID` 下创建并注册
-数据集，生成的 dsId 落在服务端定义里。之后 `guanwf edit` 回读时这些字段进入
-`nodes/<id>/python.json` 透传层，`save` 时自动保留，不会丢失。
+新建输出数据集时不要填写 `DatasetID`：首次运行由 BI 服务端在 `ParentDirID` 下创建并注册。
+只有明确更新已有数据集时才填写该数据集的 dsId。更新其他流程创建的数据集时保持
+`Created: false`；仅当数据集确由当前工作流创建时使用 `Created: true`。`guanwf edit` 会把
+服务端已有 dsId 和 created 状态回读，后续导出会继续保留。
 
 ### script.py 沙箱约定
 

package/skills/guanwf/references/WORKFLOW_NODES.md

@@ -67,10 +67,13 @@ node_1006 := LoadNodeFromFile("node_1006.json", node_1005)
 ```
 
 配置说明：
-- `OutputDsId`: 输出数据集 ID
+- `OutputDsId`: 输出数据集 ID（序列化为服务端的 `dsId` 键；绑定已有数据集时填写）
+- `ParentDirID`: 输出数据集目录（DATA_SET 目录树 id，新建输出必填，缺失会导致运行期报错）
 - `UpdateMode`: `APPEND`（追加）或 `UPSERT`（更新插入）
 - `PrimaryKeys`: UPSERT 模式的主键列
 
+推荐优先使用透传模式（LoadNodeFromFile），可保留服务端节点的全部配置。
+
 ## 原生 DSL 节点
 
 以下节点有结构化的 Go DSL 函数，import 后会生成可直接编辑的代码。