1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | upstash-qstash-js-upstash-skills |
| 作者/维护者 | Upstash(Serverless 数据与消息服务厂商,QStash 的所有者) |
| 来源链接 | https://github.com/upstash/skills/tree/main/skills/upstash-qstash-js |
| 许可证 | MIT |
| GitHub Stars / Forks | 31 / 7(属 upstash/skills 整个仓库,非本技能独有;GitHub API) |
| 底层 SDK | upstash/qstash-js 270 stars;npm 周下载约 70 万(GitHub API / npm API) |
| 技能安装量 | skills.sh 显示约 2,033 次安装 |
| 最近更新 | 本技能目录最近一次修改于 2026-08-31,仓库 2026-10-06 仍有提交 |
| 安装方式 | npx skills add https://github.com/upstash/skills --skill upstash-qstash-js 或 Claude Code 插件 |
2. 功能介绍与亮点
面向 @upstash/qstash TypeScript/JavaScript SDK 的编码指南。QStash 是基于 HTTP 的消息队列与定时调度服务,适合没有常驻进程的 Serverless / Edge 环境。
- 发布与调度:向 HTTP 端点或 URL 组发布消息,延迟投递,cron 定时任务,增删改暂停恢复
- 队列与流控:FIFO 队列、并行度、流控(文档注明队列并行度将被弃用,推荐流控)
- 可靠性:重试、成功/失败回调、死信队列(DLQ)、去重(deduplicationId / 内容去重)
- 签名校验:Receiver 类校验 QStash 回调签名,含 Next.js App Router / Pages Router / Edge 专用封装
- 本地开发:
devMode: true自动拉起本地开发服务;另含多区域迁移说明与一个校验脚本 - 渐进加载:SKILL.md 约 3.9KB 作入口,其余 12 个参考文件按需读取
3. 适用场景
分类:集成与工作流自动化。
- 在 Vercel / Cloudflare Workers 上做后台任务、异步队列,不想自建 worker
- 给 Serverless 应用加 cron 定时任务
- 带重试的 webhook 投递,失败进 DLQ 并回调告警
- 校验并接收来自 QStash 的回调请求
- 在 US / EU 区域之间迁移 QStash
受益人群:使用 Serverless 架构的全栈与后端开发者。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 仓库带 Claude Code 插件清单,也可用 skills CLI 安装 |
| Codex | 原生支持 | 仓库带 Codex 插件清单与 marketplace 配置 |
| OpenClaw | 未验证 | 遵循通用 Agent Skills 格式(SKILL.md + front matter),理论可复制使用,未见官方说明 |
| Hermes Agent | 未验证 | 同上 |
5. 推荐理由
QStash 的细节(签名校验必须用原始请求体、队列与流控的区别、回调与 DLQ 的触发条件、多区域的环境变量写法)LLM 凭印象容易写错。该技能由服务厂商自己维护,示例可直接复制,并把 Next.js 各运行时的校验写法单独成文,能减少接入返工。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 厂商官方出品;技能安装量约 2.0K,底层 SDK npm 周下载约 70 万 |
| 可用性 | 8 | 一条命令安装;文档含大量示例;近三个月有维护;需要 QStash 账号与 token(有免费额度) |
| 安全性 | 9 | 纯文档型技能,无需执行脚本,凭据走环境变量;第三方审计(Gen Agent Trust Hub / Socket / Snyk)均为通过 |
综合 = 三项均值 = 8.00。
安全检查清单:
- 执行 shell:无;仅一个可选的多区域环境变量校验脚本(
.ts,用户自行运行,无参数) - 运行时联网:技能本身不联网;示例中的 SDK 访问用户自己的 QStash 与自定义端点
- 凭据:示例用
process.env.QSTASH_TOKEN与签名密钥环境变量,不要求硬编码 - 可疑指令:通读 13 个文件,未发现
- 作者信誉:Upstash 为知名 Serverless 数据服务商
- License:MIT
- 维护:技能目录 2026-08-31 修改,仓库 2026-10 仍有提交
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 差异 |
|---|---|---|
| 本技能(Upstash 官方) | @upstash/qstash 消息队列与调度 SDK |
专讲 HTTP 触发的队列、cron、DLQ 与签名校验,面向无常驻进程环境 |
| Upstash 的 upstash-workflow-js 技能 | @upstash/workflow 多步骤持久化工作流 |
偏长流程编排与状态管理;本技能是其底层的单条消息层 |
| Hookdeck 等 webhook 平台技能 | Webhook 接收、转发与重放 | 面向入站事件网关,不含队列、cron 与出站调度 |
| Inngest / Trigger.dev 类技能 | 另一类后台任务平台 | 绑定各自平台与 SDK,与 QStash 的 HTTP 回调模型不通用 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。可参考的间接信号:@upstash/qstash 在 npm 上周下载约 70 万次,skills.sh 安装量约 2.0K。
9. 其他补充
- 同一仓库还有 Redis、Ratelimit、Workflow、Vector、Search 等 Upstash SDK 技能,以及合并全部内容的
upstash总技能 - 仓库同时提供插件清单,可同时安装 Upstash 官方 MCP 服务
10. 安装使用方式
# 仅安装本技能
npx skills add https://github.com/upstash/skills --skill upstash-qstash-js
# Claude Code 插件(技能 + MCP)
/plugin marketplace add upstash/skills
/plugin install upstash@upstash
安装后在项目里说“用 QStash 加一个每天跑的定时任务”“做一个带重试的 webhook 投递”等即可触发;使用前需 npm install @upstash/qstash 并设置 QSTASH_TOKEN,接收端另需 QSTASH_CURRENT_SIGNING_KEY / QSTASH_NEXT_SIGNING_KEY。
11. 注意事项
- 仅覆盖
@upstash/qstash(TS/JS SDK);多步骤长流程需另用 Workflow SDK - 依赖 Upstash QStash 服务;超出免费额度按计划计费,DLQ 保留期随套餐
- 队列并行度写法文档已标注将被弃用,新代码优先用流控
- 技能内容随 SDK 迭代,建议定期更新