Vendo 自动化工作流入门:让 AI Agent 按定时任务自动执行任务的完整指南
Vendo 自动化工作流入门:让 AI Agent 按定时任务自动执行任务的完整指南
Vendo 是一款开源的嵌入式 Agent 层,而 Vendo 自动化(Automations)是其中最实用的一环:你只需要用一句话描述"每天早 8 点把逾期发票整理好发给我",AI Agent 就会把这句话变成一条持久化的定时任务记录,并在你的后端按时自动执行,全程以任务所有者的身份、使用其授权来操作。本文是面向新手和普通用户的完整指南,帮你快速理解 Vendo 定时任务如何工作、如何创建、以及如何安全地控制它。
先搞清楚:Vendo 的自动化是一条"记录",不是一段脚本
很多人对 AI 定时任务的想象是"写个脚本挂到 cron 上"。Vendo 的设计完全不同:
- 一条 automation 就是一条数据库记录,包含四个要素:所有者(owner)、触发器(trigger)、任务(task)、负责思考的 agent 名称。
- 记录存在你自己的数据库里,运行在你自己的后端进程中,外部只需要一个"闹钟"按点叫醒它。
- 执行时它不携带任何浏览器会话,而是以任务创建者本人的授权去调用你的 API——换句话说,Agent 只能做"这个用户本来就能点鼠标做到的事"。
💡 核心心智模型:代码是同意(consent)。开发者用代码声明的自动化,每次部署都会与数据库对账;用户用对话创建的自动化,则完全归用户所有,部署不会去动它。
两种创建方式:一句话 or 一行声明
方式一:让用户在聊天里用自然语言创建
这是最贴近"普通用户"的方式。用户直接说:
"每个工作日的早 8 点,把昨晚到期的逾期发票整理成邮件发给我。"
Agent 会当场创建这条自动化记录,并在对话里用一张卡片告诉你"我武装了什么"。没有表单,没有单独的自动化配置页面——用户说完即生效,撤销某个授权也会立刻停止任务,而不是悄悄放行。
方式二:开发者在代码中用 .on() 声明
如果你希望产品自带"出厂设置"的定时任务,在 agent 定义处声明即可:
import { agent } from "@vendoai/vendo";
export const support = agent({ name: "support" });
support.on("0 9 * * 1", "summarize the week and email ops"); // 每周一 9 点
support.on({ every: "1d" }, "refresh credit scores"); // 每天
support.on({ event: "payment.failed" }, "triage and notify the user"); // 事件触发
.on() 只是一个声明:调用时不写数据库、不执行任何东西,等进程启动时才与存量记录对账一次。如果 cron 写错(比如写成 "every monday"),错误会在声明的那一行立刻抛出,而不是在凌晨 2 点任务触发时才爆雷。
三种触发方式:定时、事件、Webhook
Vendo 自动化支持三类触发器,覆盖了绝大多数自动化工作流场景:
| 触发方式 | 写法示例 | 适用场景 |
|---|---|---|
| 🕘 定时计划(Schedule) | "0 8 * * 1-5"、{ every: "15m" }、{ at: "2026-09-01T09:00Z" } |
标准 cron、固定间隔、一次性时间点 |
| ⚡ 宿主事件(Host event) | { event: "invoice.paid" } |
你自己产品里发出的业务事件 |
| 📮 Webhook | { webhook: "stripe" } |
已连接服务的签名回调 |
宿主事件在你的进程内、就在发出事件的那一行代码处同步触发;而定时任务需要一个"敲门"机制——调用 POST /api/vendo/tick。使用 Vendo Cloud 时完全免配置(心跳服务只是闹钟,不做任何决策);自托管时自己设置 VENDO_TICK_SECRET,再用自己的 cron 按分钟敲门即可。敲门是幂等的,重复敲门不会产生重复执行。
权限模型:为什么凌晨的任务也能安全调用你的 API
定时任务触发时,用户并不在场,没人能点"批准"。Vendo 的解法是:把要权限的动作提前到"开启"那一刻一次性完成。
const { enabled, missing, grantSetId } = await vendo.automations.enable(id, ctx);
missing列出用户还需要授权的权限项;同属一个 grant set 的权限,一次决策全部解决。- 授权未补齐时,任务会在第一次缺少权限的调用处响亮地停下,运行记录里写清楚它缺的是哪条权限,随后可以用
runs.rerun(runId)补跑。 - 凌晨的"无人值守"运行没有浏览器 cookie 可用,Vendo 通过
actAs接缝在每次外呼前为所有者现铸身份凭证,并内置冒充防护:权限主体与运行主体不一致时直接拒绝外呼,且每次尝试都会留下审计记录(minted/declined/mismatch/error)。
观察与控制:运行历史、dry run 与一键急停
管理自动化不需要你自建任何界面,一个 hook 就把所有能力带进你自己的面板:
const { automations, enable, disable, runs, dryRun, stopRun, rerun } = useAutomations();
几个新手最实用的操作:
- dryRun:预演任务"将会做什么",但不真正执行——上线前验证任务逻辑的最佳手段。
- runs.list / runs.get:查看每次执行的记录,谁触发、缺了什么权限、成功还是失败,一目了然。
- disable 是急停开关,而且它的优先级高于代码:即使你重新部署,对账也永远不会把用户手动关掉的自动化重新武装起来。
顺带一提:自动化任务可以操作用户已连接的外部账户(Gmail、Slack 等)。用户连接一次,之后定时任务执行时就能以"他们本人"的身份调用,这是"定时发邮件通知"类场景的基础。
快速上手:三步让 AI Agent 按你的时间表工作
第 1 步:安装 Vendo 到现有项目
npm install @vendoai/vendo
npx vendo init
vendo init 会读取你应用的品牌信息,并在 .vendo/ 下生成主题与配置。
第 2 步:把 Agent 面板挂进你的产品
在根 layout 中包一层 <VendoProvider>,再加一个 <VendoOverlay />,你的产品就有了一个品牌原生的 AI Agent 入口。详细步骤见 quickstart.mdx。
第 3 步:声明你的第一个定时任务
按上一节的方式,用 .on() 声明一个 cron 任务(代码作者)或者引导用户用一句话创建(用户作者)。启动后端后,对账自动完成、任务武装就绪,剩下的交给"闹钟"。
值得进一步阅读的资料
- 自动化能力总览(记录模型、触发器、actAs 全貌):docs-site/capabilities/automations.mdx
.on()声明式 API 详解(所有形态、选项、对账规则):docs-site/backend/automate.mdx- 自动化端到端测试集(含调度、权限、急停、重跑等场景):fixtures/automations-e2e/tests/
- 项目主文档与安装说明:README.md
小结
Vendo 自动化的设计哲学可以浓缩成三句话:
- 自动化是记录,不是脚本——存在你的库里,跑在你的进程里,权限属于创建者本人。
- 两种作者,一个模型——用户一句话、开发者一行声明,共享同一套触发、执行与审计机制。
- 失败要响亮——cron 写错在声明处炸,权限不够在执行处停,绝不在凌晨 2 点静默出错。
理解了这套模型,你就可以在产品里放心地"让 AI Agent 按时上班"了。




