Architecture
Workflows live in workflows/ with components and flows:
CODEBLOCK0
Quick Reference
| Topic | File |
|---|
| Directory layout, naming, formats | INLINECODE1 |
| Data passing between nodes |
data-flow.md |
| Cursor, seen set, checkpoint |
state.md |
| Retry, rollback, idempotency |
errors.md |
| Connections, nodes, triggers |
components.md |
| Create, test, update, archive |
lifecycle.md |
Requirements
- - jq — JSON processing
- yq — YAML config parsing
- curl — HTTP requests
- flock — Lock files to prevent concurrent runs
- Secrets in macOS Keychain (
security find-generic-password)
Data Storage
- - Location:
workflows/ in workspace root - State:
flows/{name}/state/ — cursor.json, seen.json, checkpoint.json - Logs:
flows/{name}/logs/ — JSONL per run - Data:
flows/{name}/data/ — intermediate files between nodes
Core Rules
1. Data Flow Pattern
Each node writes output to
data/{NN}-{name}.json. Next node reads it.
curl ... > data/01-fetch.json
jq '...' data/01-fetch.json > data/02-filter.json
Breaking this pattern = nodes can't communicate.
2. Error Declaration
Every node in flow.md MUST declare:
- - On error: retry(N) | fail | continue | alert
- On empty: skip | continue | fail
Undefined behavior = unpredictable workflow.
3. Lock Files
Prevent concurrent runs:
CODEBLOCK2
4. State Files
| File | Purpose |
|---|
| cursor.json | "Where did I leave off?" |
| seen.json |
"What have I processed?" |
| checkpoint.json | "Multi-step recovery" |
5. Component Reuse
Before creating new connections/nodes/triggers:
ls workflows/components/connections/
ls workflows/components/nodes/
Use existing. Update "Workflows Using This" when adding.
Related: For LLM-driven multi-phase processes, see the
cycle skill.
架构
工作流位于 workflows/ 目录下，包含组件和流程：
workflows/
├── index.md # 带标签的清单
├── components/
│ ├── connections/ # 认证配置
│ ├── nodes/ # 可复用操作
│ └── triggers/ # 事件源
└── flows/{name}/
├── flow.md # 定义
├── config.yaml # 参数
├── run.sh # 可执行文件
├── state/ # 运行间持久化状态
└── logs/
快速参考
| 主题 | 文件 |
|---|
| 目录结构、命名规范、格式 | structure.md |
| 节点间数据传递 |
data-flow.md |
| 游标、已处理集合、检查点 | state.md |
| 重试、回滚、幂等性 | errors.md |
| 连接、节点、触发器 | components.md |
| 创建、测试、更新、归档 | lifecycle.md |
依赖要求
- - jq — JSON 处理
- yq — YAML 配置解析
- curl — HTTP 请求
- flock — 文件锁，防止并发运行
- macOS 钥匙串中的密钥（security find-generic-password）
数据存储
- - 位置： 工作区根目录下的 workflows/
- 状态： flows/{name}/state/ — cursor.json、seen.json、checkpoint.json
- 日志： flows/{name}/logs/ — 每次运行的 JSONL 格式日志
- 数据： flows/{name}/data/ — 节点间的中间文件
核心规则
1. 数据流模式
每个节点将输出写入 data/{NN}-{name}.json。下一个节点读取该文件。
bash
curl ... > data/01-fetch.json
jq ... data/01-fetch.json > data/02-filter.json
打破此模式 = 节点间无法通信。
2. 错误声明
flow.md 中的每个节点必须声明：
- - 出错时： retry(N) | fail | continue | alert
- 空结果时： skip | continue | fail
未定义行为 = 工作流不可预测。
3. 文件锁
防止并发运行：
bash
LOCKFILE=/tmp/workflow-${NAME}.lock
exec 200>$LOCKFILE
flock -n 200 || exit 0
4. 状态文件
| 文件 | 用途 |
|---|
| cursor.json | 我上次运行到哪里？ |
| seen.json |
我已经处理了什么？ |
| checkpoint.json | 多步骤恢复 |
5. 组件复用
在创建新的连接/节点/触发器之前：
bash
ls workflows/components/connections/
ls workflows/components/nodes/
使用现有组件。添加时更新使用此组件的工作流。
相关： 对于 LLM 驱动的多阶段流程，请参阅 cycle 技能。
