面向 CLI 的轻量级工作流编排方案，基于文件系统实现节点间数据流转与状态持久化，适合开发者构建可复用的自动化管道
说明：
## 核心用法
Workflow 是一套基于 Shell 脚本和文件系统的工作流自动化框架，而非传统意义上的工作流引擎（如 Apache Airflow）。其核心设计围绕**文件驱动的数据流**展开：
– **组件层**：预置 connections（认证配置）、nodes（可复用操作）、triggers（事件源）三类组件，支持跨工作流复用
– **编排层**：通过 `flow.md` 声明节点依赖关系，利用 `config.yaml` 管理参数
– **执行层**：`run.sh` 作为入口脚本，借助 `flock` 实现并发锁控制，通过管道将数据写入 `data/NN-name.json` 序列化文件
### 显著优点
1. **零运行时依赖**：仅需 jq/yq/curl 等常见 CLI 工具，无需守护进程或数据库
2. **透明可调试**：所有中间状态以明文 JSON 留存于 `state/` 和 `data/` 目录，`cursor.json`/`seen.json` 实现断点续传
3. **Git 友好**：纯文本配置与代码，天然支持版本控制和代码审查
4. **错误策略显式化**：强制声明 `on error`（retry/fail/continue/alert）和 `on empty`（skip/continue/fail）行为
### 潜在局限
– **无分布式能力**：锁机制基于本地文件（`/tmp/workflow-*.lock`），无法跨机器协调
– **状态一致性风险**：文件系统状态非事务性，异常中断可能导致 `checkpoint.json` 与实际执行状态不一致
– **学习曲线**：需熟练掌握 jq 语法及 Shell 错误处理，对非 CLI 用户门槛较高
– **macOS Keychain 绑定**：密钥管理强依赖 Apple 生态，Linux 环境需额外适配
### 适合人群
个人开发者、DevOps 工程师、需要轻量 ETL 或定时任务编排的小型团队，尤其适合已有 Shell 脚本积累、追求”可 git diff”可审计的场景。
### 常规风险
– **并发竞态**：`flock` 虽防重复执行，但节点间若共享外部资源（如 API 限流），需额外幂等设计
– **敏感信息泄露**：`config.yaml` 可能含明文凭据，需配合 `.gitignore` 或外部密钥管理
– **磁盘膨胀**：`logs/` 以 JSONL 累积，长期运行需定期清理策略
