# guanwf

观远工作流数据流编辑工具，支持创建、编辑、导出、预览、保存数据流。

## 本地安装（开发/测试阶段）

```bash
# 编译所有平台 binary（需要 Go 工具链）
npm run build

# 安装到本地 node global
npm link
```

安装后即可在终端使用：

```bash
guanwf create --name "我的数据流" --parent-dir <dirId>
guanwf create --name "HTTP作业" --type HTTP --parent-dir <dirId>
guanwf create --name "SQL作业" --type SQL --parent-dir <dirId>
guanwf edit <parentWorkflowId>
guanwf python-runtime --dir <workdir> --format json
guanwf export --dir <workdir>
guanwf preview --dir <workdir>
guanwf save --dir <workdir> --dry-run
guanwf save --dir <workdir> --confirm
guanwf run --wait --dir <workdir> --dry-run
guanwf run --wait --dir <workdir> --confirm
guanwf run --dir <workdir> --param biz_date=2026-07-14 --confirm
guanwf schedule set --cron "0 0 2 * * ?" --param biz_date=2026-07-14 --dir <workdir> --confirm
guanwf schedule event set --rule <datasetId>:<taskName> --param biz_date=2026-07-14 --dir <workdir> --confirm
guanwf instance latest --dir <workdir> --logs -f json
```

8.2.0 兼容说明：SHELL/LOOP 后端未注册，CLI 会提前拒绝；离线开发输出数据集不能作为
DatasetNode 刷新目标，应使用 SubWorkflowNode 调用产出工作流。参数赋值查询 StarRocks
直连表时使用 DATABASE 来源，不要把直连数据集作为 DATASET 来源。

说明：npm 包名为 `@guandata/guanwf`，用户侧 CLI 命令统一为 `guanwf`。

也可以为 AI Coding Assistant 安装 Skill：

```bash
guanwf install-skill
```

> `npm install -g --foreground-scripts @guandata/guanwf` / `npm link --foreground-scripts` 会通过 postinstall 自动刷新 skill，并显示明确的成功、失败或跳过结果；上述 `guanwf install-skill` 仅用于失败后的手动修复或排查。CI 等无需 skill 的环境可设 `GUAN_SKIP_INSTALL_SKILL=1` 跳过。

安装包会通过 npm `optionalDependencies` 自动选择当前系统的原生二进制。不要使用 `--omit=optional` 或 `optional=false`；企业 npm 镜像也需要同步对应的 `@guandata/guanwf-<平台>-<架构>` 包。若平台包缺失，CLI 会显示对应包名和重新安装方法。

## 版本更新

### @guandata/guanwf 0.1.836

- 安装时自动选择当前系统和架构的原生程序，减少下载量与磁盘占用，原有安装命令不变；离线安装也支持自动选包。

### @guandata/guanwf 0.1.835

- 修复 Python 镜像版本解析：优先读取 `pythonVersion`，旧接口降级解析 `runtimeEnv`，两者都不可用时才回退兼容契约 Python 3.8。

### @guandata/guanwf 0.1.834

- `schedule set --failure-strategy` 仅接受 `CONTINUE`，显式传 `END` 会在本地校验阶段失败；后继调度改由 `FAILURE` / `ALL` 连线决定。
- 同步共享鉴权与环境识别更新，支持识别内部 OAuth2 应用认证环境。

### @guandata/guanwf 0.1.833

- DSL 提供节点类型、依赖类型和更新模式等类型化常量，并兼容已有字符串写法。
- 改进定义的序列化和往返编辑稳定性，统一可供自动化判断的错误分类。

### @guandata/guanwf 0.1.832

- 改善 Windows npm 全局安装和多种程序路径下的底层调用兼容性。

### @guandata/guanwf 0.1.831

- 首次创建输出后，完成绑定和发布保存前会阻断再次运行，避免输出数据集绑定状态漂移。
- 增强已有工作流编辑、导出、保存及输出绑定的保真与并发保护。

### @guandata/guanwf 0.1.830

- `run --validate` 只验证 Python 序列化，不再误触发真实输出数据集注册。
- 校验仅允许在已有草稿上执行，并在写入前再次确认版本状态，避免发布态工作流残留临时草稿。
- 强化失败恢复与并发变化诊断，生命周期变化时保持线上零写入。

### @guandata/guanwf 0.1.829

- 新增 Python Runtime 上下文和输入内存预检，脚本生成与运行会依据目标环境能力保守判断。
- 新增输出绑定、改绑、解绑和已注册输出回填命令，支持 dry-run、精确槽位定位与并发变更检查。
- 保存后会回读目标字段，执行后逐项验证输出计算、注册、更新与可读性。
- 实例日志补充完整性和根因证据，并增强工作流往返编辑时的未知字段、sidecar 与敏感文件保护。
- 结构化错误和非零退出状态更适合自动化流程判断。

### @guandata/guanwf 0.1.828

- 支持企业 OIDC 认证上下文，并升级底层请求兼容能力，改善受控环境中的工作流操作稳定性。

### @guandata/guanwf 0.1.827

- 改进 Skill 自动安装反馈和删除确认流程。
- 优化 Windows 环境下的 CLI 启动兼容性。

### @guandata/guanwf 0.1.826

- 完善工作流输出落位校验，保存和执行时能更准确地确认目标数据集。
- 修复输出绑定中的字段错位问题，提升数据集同步准确性。

### @guandata/guanwf 0.1.825

- Python 节点输出支持绑定已有数据集，可直接覆盖或追加到指定数据集，避免重复创建输出并保持下游引用稳定。
- 编辑已有工作流时会回读并保留输出数据集绑定状态，同时在保存前校验无效配置。

### @guandata/guanwf 0.1.824

- 工作流目录树支持按关键词和最大深度缩小范围，文本与 JSON 输出都能清楚标记被省略的层级。
- 更新底层依赖，提升安全性和运行稳定性。

### @guandata/guanwf 0.1.823

- 提升受控 Agent 运行环境中的工作流导出和 ETL 节点处理能力，较大的工作流定义也能稳定交换。

### @guandata/guanwf 0.1.822

- 优化工作流依赖与血缘读取效率，复杂编排的分析和校验等待更少。
- 完善已有工作流的原地编辑指引，避免更新时破坏原有调度、权限和下游引用。

### @guandata/guanwf 0.1.821

- 保持 8.2.0 专用兼容能力不变；全局安装或升级后自动刷新 AI Skill。
- 随包提供完整的工作流使用说明和参考资料。

### @guandata/guanwf 0.1.820

- 8.2.0 专用兼容版本；请勿与面向 master 的 CLI 版本混用。
- 新增结构化工作流节点、参数、实例诊断和安全 mutation 门，并修复 8.2.0 保存、预览、运行及恢复链路问题。
- 对 8.2.0 不支持的 SHELL、LOOP、PROCESS 事件源等能力在提交前给出明确阻断。

### @guandata/guanwf 0.1.7

- 工作流离线开发能力增强，支持文件夹、实例、权限、告警和调度相关命令。
- 新增工作流依赖分析、执行计划和依赖校验能力，便于把一批作业编排为统一调度主工作流。
- 数据流保存和合并能力增强，补充子工作流、事件调度和恢复场景支持。

### @guandata/guanwf 0.1.6

- `install-skill` 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

### @guandata/guanwf 0.1.5

- 工作流数据流支持 `workflow.go` DSL 模式，统一数据流创建、编辑、导出、预览、保存和运行流程。
- 新增 Python 节点 DSL 支持和本地校验，保存时采用三方合并以减少覆盖线上已有数据流配置的风险。
- 补充工作流 DSL 参考文档和测试覆盖，提升复杂数据流生成与发布链路稳定性。

### @guandata/guanwf 0.1.4

- `install-skill` 增加 WorkBuddy 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
```