Workflow

核心用法

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 累积，长期运行需定期清理策略

核心功能

Workflow 是一个纯文档型 Skill，专注于自动化流水线构建的规范与最佳实践。它定义了一套完整的目录结构、组件复用模式和数据流标准，帮助用户构建可维护、可扩展的 Shell-based 工作流系统。

显著优点

1. 清晰的架构设计：采用 workflows/ 根目录、components/ 组件库、flows/ 具体流程的三层结构，实现关注点分离
2. 标准化数据流：强制使用 data/{NN}-{name}.json 的文件传递模式，确保节点间通信可追溯
3. 完善的状态管理：提供 cursor（断点续传）、seen（去重）、checkpoint（多步恢复）三类状态文件
4. 生产级安全实践：内置 flock 并发锁、幂等性设计、错误声明（retry/fail/continue/alert）机制
5. 零依赖风险：纯 Markdown 文档，无实际可执行代码，示例代码均展示安全模式

潜在局限

1. T3 来源可信度：维护者为匿名标识符，无 GitHub 组织背书，无官方来源链接
2. 缺少完整示例：未提供可直接运行的示例工作流仓库
3. 许可证缺失：未声明开源协议，存在使用边界模糊的风险
4. 平台限制：依赖 macOS Keychain 存储密钥，Linux 需额外适配

适合人群

• DevOps 工程师构建 CI/CD 流水线
• 数据工程师编排 ETL 任务
• 系统管理员自动化运维脚本
• 需要理解工作流设计模式的技术团队

常规风险

• 误用示例代码：文档中的 curl 示例为占位符，实际使用时需验证目标 URL
• 敏感信息泄露：需确保 API Key 按文档建议存入 Keychain，而非硬编码
• 并发冲突：需严格遵循 flock 锁机制，防止同一工作流并行运行导致状态损坏
• T3 来源审查：建议在使用前通过版本控制追踪文档变更，验证维护者信誉