1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | upstash-workflow-js-upstash-skills |
| 作者/维护者 | Upstash(Serverless 数据与消息服务厂商,Workflow 与 QStash 的所有者) |
| 来源链接 | https://github.com/upstash/skills/tree/main/skills/upstash-workflow-js |
| 许可证 | MIT |
| GitHub Stars / Forks | 31 / 7(属 upstash/skills 整个仓库,非本技能独有;GitHub API) |
| 底层 SDK | upstash/workflow-js 156 stars;npm 月下载约 51 万(GitHub API / npm API) |
| 技能安装量 | skills.sh 显示约 1,930 次安装 |
| 最近更新 | 本技能目录最近一次修改于 2026-08-31,仓库 2026-10-06 仍有提交 |
| 安装方式 | npx skills add https://github.com/upstash/skills --skill upstash-workflow-js 或 Claude Code 插件 |
2. 功能介绍与亮点
面向 @upstash/workflow TypeScript/JavaScript SDK 的编码指南。Workflow 让 Serverless 函数跑出可跨越超时、重试、重启的多步骤持久化流程,底层由 QStash 承载。
- 步骤编排:
serve()暴露工作流端点,context.run/sleep/call把长流程拆成可检查点的步骤,睡眠几分钟到几天不占用函数实例 - 等待与调用:等待外部事件或 webhook、跨工作流
invoke、人工审批(human-in-the-loop)与实时更新 - 可靠性:重试、失败回调、死信队列(DLQ)
- 流控:按 flow control key 限制并发、速率与周期
- Client 管理:触发、取消、查询运行状态、通知等待中的运行
- 本地开发:设置
QSTASH_DEV=true自动拉起本地 QStash 开发服务;也可手动npx @upstash/qstash-cli dev或用 ngrok 隧道 - 中间件与迁移:生命周期与调试事件中间件;含 1.0.0 大版本迁移说明(Agents API 拆到独立包)
- 排障文档:单列常见坑,例如 try/catch 吞掉
WorkflowAbort会让流程停住 - 渐进加载:SKILL.md 约 3KB 作入口,其余 15 个参考文件(basics / features / how-to / agents / rest-api / troubleshooting)按需读取
3. 适用场景
分类:集成与工作流自动化。
- 在 Vercel / Next.js / Cloudflare Workers 上做超过单次函数时限的后台流程
- 带检查点的多步骤任务:订单处理、用户引导、数据同步
- 等待 webhook 或人工审批后继续的流程
- 用 Workflow Agents 搭建 LLM 代理与编排器
- 控制对第三方 API 的调用速率与并发
受益人群:使用 Serverless 架构的全栈与后端开发者。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 仓库带 Claude Code 插件清单,也可用 skills CLI 安装 |
| Codex | 原生支持 | 仓库带 Codex 插件清单与 marketplace 配置 |
| OpenClaw | 未验证 | 遵循通用 Agent Skills 格式(SKILL.md + front matter),理论可复制使用,未见官方说明 |
| Hermes Agent | 未验证 | 同上 |
5. 推荐理由
持久化工作流有几处反直觉的规则:步骤会主动抛出 WorkflowAbort、不能随手包 try/catch;步骤结果要可序列化;流控 key 决定限额共享范围。LLM 凭印象容易写出看似正常、实际不会推进的流程。该技能由厂商自己维护,示例与排障条目可直接对照,并把 1.0.0 的破坏性变更单独成文,能减少接入返工。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 厂商官方出品;技能安装量约 1.9K,底层 SDK npm 月下载约 51 万 |
| 可用性 | 8 | 一条命令安装;文档含大量示例与排障;近三个月有维护;需要 QStash 账号与 token(有免费额度) |
| 安全性 | 8 | 纯文档型技能;本地开发模式说明 SDK 会下载 QStash CLI 二进制并启动本地服务,范围明确且在生产环境不生效;凭据走环境变量 |
综合 = 三项均值 = 8.00。
安全检查清单:
- 执行 shell:技能本身无脚本;文档示例含
npx @upstash/qstash-cli dev,以及开发模式下 SDK 自动下载并运行 QStash CLI 二进制(文档注明生产环境、构建期与浏览器/边缘运行时不生效) - 运行时联网:技能本身不联网;示例中的 SDK 访问用户自己的 QStash 与自定义端点;本地开发首次使用会下载二进制
- 凭据:示例用
QSTASH_TOKEN等环境变量,不要求硬编码 - 可疑指令:通读 SKILL.md 与全部参考文件标题及关键章节,未发现越权指令或夹带推广
- 作者信誉:Upstash 为知名 Serverless 数据服务商
- License:MIT
- 维护:技能目录 2026-08-31 修改,仓库 2026-10 仍有提交
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 差异 |
|---|---|---|
| 本技能(Upstash 官方) | @upstash/workflow 多步骤持久化工作流 |
覆盖步骤、等待、流控、DLQ、Agents 与迁移,贴合 Serverless 无常驻进程的执行模型 |
| Upstash 的 upstash-qstash-js 技能 | @upstash/qstash 单条消息队列与调度 |
偏消息投递、cron 与签名校验;是本技能的底层 |
| Inngest / Trigger.dev 类技能 | 另一类后台任务与工作流平台 | 绑定各自平台与 SDK,执行模型与 Upstash 的 HTTP 回调不通用 |
| Temporal 类技能 | 自托管或云端的持久化执行引擎 | 需常驻 worker 与独立服务端,面向更重的后端场景 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。可参考的间接信号:@upstash/workflow 在 npm 上月下载约 51 万次,skills.sh 安装量约 1.9K。
9. 其他补充
- 同一仓库还有 Redis、QStash、Ratelimit、Vector、Search、Blob、Box 等 Upstash 技能,以及合并全部内容的
upstash总技能 - 仓库同时提供插件清单,可同时安装 Upstash 官方 MCP 服务
10. 安装使用方式
# 仅安装本技能
npx skills add https://github.com/upstash/skills --skill upstash-workflow-js
# Claude Code 插件(技能 + MCP)
/plugin marketplace add upstash/skills
/plugin install upstash@upstash
安装后在项目里说“用 Upstash Workflow 做一个带审批等待的流程”“给工作流加重试和 DLQ”等即可触发;使用前需 npm install @upstash/workflow 并设置 QSTASH_TOKEN,本地开发可设 QSTASH_DEV=true。
11. 注意事项
- 仅覆盖
@upstash/workflow(TS/JS SDK);Agents API 在 1.0.0 起拆为独立包@upstash/workflow-agents - 依赖 Upstash QStash 服务;超出免费额度按计划计费
- 本地开发的自动模式会下载并运行 QStash CLI 二进制,受限网络环境需改用手动方式
- 步骤内不要用 try/catch 吞掉
WorkflowAbort - 技能内容随 SDK 迭代,建议定期更新