概念

工作流

工作流是你命名的项目。它保存图（节点+边）、状态（active/paused）以及可选的间隔分钟数。带间隔的启用工作流会被后台 worker 调度。暂停的不会自动跑，但仍可随时手动运行。

interval_minutes 示例：1440=每天，60=每小时（视套餐），空/null=仅手动。设置了间隔时，一次运行尝试后 next_run_at 会按间隔前进。

例子：「每日商品列表」，status=active，interval=1440。

控制台 → 工作流。API：GET/POST /api/v1/workflows。

节点

节点是画布上的一步。共四类：scrape（读页面）、url_gen（造 URL 列表）、store（写表）、notify（变更发信）。每个节点有 id（如 s1）、type 与 config。

抓取、通知、URL 生成可存成「工作流 → 节点」里的预设。存储总是在具体工作流上配置，因为它指向某张数据集。

例子：一个列表抓取 + 一个名为「商品」的存储。

打开工作流编辑器，或「工作流 → 节点」管理预设。

运行

运行是整张图执行一次。状态为 ok 或 error。每个节点写入带 input/output/error 的节点运行记录。失败也会保留记录，方便看哪一步断了。

控制台运行与 API POST …/run 都会等到图结束。改配置前先打开运行详情检查 items。

例子：运行 #42：抓取 ok（18 条），存储 ok（18 次 upsert）。

工作流编辑器 → 运行历史。API：GET …/runs 与 …/runs/{id}。

数据集

数据集是你账号下的逻辑表，由存储节点写入。行按 key_fields 哈希做 upsert：相同键更新，新键插入。默认键是 url、link——你几乎总应显式指定商品 URL。

可在控制台浏览、用 API 分页，或导出 CSV/JSON（大表有上限）。列在首次成功写入后出现。

例子：数据集「products」，列 title/price/url，一次运行后 120 行。

控制台 → 数据集。API：GET /api/v1/datasets、…/rows、…/export。

预设

预设是带名称的已保存 scrape/notify/url_gen 配置。可拖到其他工作流，避免重复发现。抓取预设必须已含勾选字段。

预设本身不占配额；配额在抓取节点出现在已保存工作流图上时才计算。

例子：预设「商店列表抓取」用在两个工作流上。

工作流 → 节点，或从节点配置保存。API：/api/v1/node-presets。

Graph JSON

画布底层是 JSON：nodes: [{id, type, config}] 与 edges: [{from, to}]。from 是上游节点 id。API 写入用 graph；响应里可能叫 graph_json。

不要用 source/target，要用 from 与 to。有环会拒绝。通常在可视化编辑；API 指南演示如何用 curl PATCH。

例子：边 {from:"s1", to:"st1"} 表示抓取输出进入存储。

抓取

抓取节点打开网页并变成行（items）。mode=list 表示「这一页有多张卡片/多行」。mode=detail 表示「一页=更丰富的一行」，常接在列表抓取传出的商品链接之后。用 requirement 描述列，再保留发现到的 fields。

运行成功时，抓取节点每实际请求 1 个网页扣 1 额度。默认每次运行最多处理 20 个 URL。列表→详情时，用 input_field 指定装下一跳 URL 的列。

例子：在 /catalog?page=1 做列表抓取保留 title/price/url；详情抓取读该 url 取 description。

URL 生成

URL 生成器不打开页面，只为下游抓取构造 URL 列表。range 模式用模板填充，如 https://example.com/list?page={page}。list 模式在不是简单数字序列时，每行粘贴一个 URL。

输出始终是 [{url:"…"}] 形态的 items。单节点最多 500 条。不占配额。只应连到抓取（通常 list 模式）。

例子：把目录第 1–10 页送进一个抓取节点。

在画布添加 URL 生成；应用前先预览数量。

通知

通知在触发条件满足时发邮件，并与同一通知节点上次运行比较。when=new 只发上次没有的行键（url/link/id/title）。when=field_change 比较 watch_fields（如 price）。其他 when 对整份 items 哈希，有变化就发。

email 默认账号邮箱。节点测试可 dry-run 不发信。工作流通知在 v1 为邮件（Webhook 可能出现在任务/套餐的其他位置）。

例子：每日运行；仅当已有商品 URL 的价格变化时发信。

额度

套餐按月（或年付 ×12）发放额度。抓取节点每次实际请求网页扣 1 额度。保存图不扣。触顶后升级或等下个周期。

剩余额度不足时运行返回 HTTP 402。仅保存不消耗额度。

例子：免费版 20 额度；列表抓取请求 3 个翻页 URL 扣 3 额度。

调度

后台 worker 查找 next_run_at 到期的启用工作流。若设置了 interval_minutes，一次运行尝试后 next_run_at ≈ 现在 + 间隔。status=paused 时完全跳过。

无论调度如何都可以手动运行。还在调字段时请保持暂停，以免突然收到邮件。

例子：启用 + 1440 分钟 → 大约每天自动跑一次。