教程2026-11-15 · 智涌AI

让 Agent 用功能开关上线:Vercel Flags 灰度教程

让 Agent 用 Vercel Flags 功能开关上线的教程头图:左侧大字「Agent 开关上线 Vercel Flags」与生产默认关闭、5→25→50% 分阶段灰度、一条命令回滚数据卡;右侧终端展示 vercel flags create、targets add、rollout、evaluations 命令

Agent 写完一个功能,最省事的验证方式是直接在生产环境看:只对你自己打开,确认没问题再逐步放给用户,出了状况一条命令关掉。Vercel CLI 现在把这套流程需要的命令都给齐了:vercel flags 管功能开关、定向和灰度,vercel metrics 查线上指标,两者都能输出 JSON,Agent 在终端里就能自己操作和读数。这篇按官方文档把「开关上线 → 只给自己看 → 分阶段放量 → 盯指标 → 回滚或收尾」串成一套可以写进 AGENTS.md 的流程。

前置条件

为什么让 Agent 走开关上线

本地和预览环境很难复现真实数据、真实流量和真实配置。把新功能包在开关后面直接合进主干、部署到生产,默认谁都看不到;你自己打开验证,没问题再放量。出问题时关开关比回滚部署快,也不会把同一次部署里其他已经验证过的改动一起撤掉。

对 Agent 来说还有个好处:每一步都是一条明确的 CLI 命令,结果能用 JSON 读回来。Agent 可以自己建开关、自己查评估次数、自己看错误率,你只需要在「放给用户」这一步拍板。

合并代码和放给用户拆成两步,Agent 负责前一步和盯数据,放量的决定留给人。

第一步:装 Skill,建开关

官方给编程 Agent 准备了两个 Skill:vercel-flags 负责规划开关、用 CLI 管理灰度和实验;flags-sdk 负责写 SDK 里的开关声明。

npx skills add vercel/flags --skill vercel-flags
npx skills add vercel/flags --skill flags-sdk
npm i flags @flags-sdk/vercel
vercel env pull   # 拉取本地开发用的 OIDC 凭据

vercel flags create new-checkout --description "新版结算页"

不指定 --kind 时建的是布尔开关。按文档,新布尔开关在 development 返回 true,在 preview 和 production 返回 false,所以部署上去默认是关的。

第二步:代码包在开关后面,带上用户身份

要按用户定向,开关需要一个 identify 函数告诉 Vercel Flags 当前请求是谁。官方示例改写如下:

// flags.ts
import { flag, dedupe } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

type Entities = { user?: { id: string } };

const identify = dedupe(async (): Promise<Entities> => {
  const session = await getSession(); // 你项目里取登录态的函数
  return { user: session?.user ? { id: session.user.id } : undefined };
});

export const newCheckout = flag<boolean, Entities>({
  key: 'new-checkout',
  adapter: vercelAdapter(),
  identify,
});

页面里 const enabled = await newCheckout();,按结果渲染新旧两套。dedupe 保证同一个请求里多个开关共用一次身份计算。然后在 Vercel 里定义对应的实体,属性名要和代码里一致:

vercel flags entities create user --label User --attribute id:string

第三步:生产环境只对自己打开

vercel flags targets add new-checkout -e production user.id=你的用户ID \
  --message "只给开发者本人验证"
vercel flags targeting enable new-checkout -e production --default-variant false

第一条把你的用户 ID 加进直接目标(布尔开关默认分配 true);第二条打开定向,没命中任何目标的请求走兜底值 false。这时部署到生产,只有你登录后能看到新结算页,可以让 Agent 用浏览器工具在线上走一遍流程、截图留证据。

第四步:分阶段放量,边放边看

vercel flags rollout new-checkout --environment production --by user.id \
  --stage 5,6h --stage 25,12h --stage 50,1d \
  --message "新版结算页灰度"

每个 --stage 是「流量百分比,持续时间」,最后一个阶段结束后默认放到 100%。--by user.id 保证同一个用户每次分到的结果一致。只想固定比例做对比,用 vercel flags split 设权重即可。

放量期间让 Agent 定时读这两类数据:

# 开关被求值了多少次、各变体占比
vercel flags evaluations new-checkout --since 1h --granularity 15m --json

# 先查有哪些指标和维度,再按条件查询
vercel metrics schema
vercel metrics <指标名> --query 'httpStatus >= 500' --since 1h --environment production --json

发现异常,一条命令把生产环境切回旧版,定向规则保留,修好后可以再打开:

vercel flags disable new-checkout -e production --variant false \
  --message "结算报错上升,暂停灰度"

第五步:写进 AGENTS.md

把上面的流程变成 Agent 的默认做法,规则可以这样写:

## 上线规则
- 面向用户的新功能一律放在 Vercel Flags 开关后面,开关名用 kebab-case。
- 部署到生产后,只用 targets 给 user.id=<我的ID> 打开,在线上走一遍并截图。
- 未经我确认,不得运行 vercel flags rollout / split / enable 放量。
- 放量期间每小时运行 vercel flags evaluations 和 vercel metrics(--json),
  5xx 明显上升就执行 vercel flags disable 并告诉我。
- 全量稳定后,先删掉代码里的开关判断并部署,再归档开关。

常见坑

完成标准

站内的 Agent PR 合并风险评估 讲合并前怎么给改动打分,和这篇的上线后流程正好前后衔接。

最后

下次让 Agent 做一个面向用户的改动时,在提示词末尾加一句「放在 Vercel Flags 开关后面,生产环境只对我打开」,跑完这一轮再决定要不要写进 AGENTS.md。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。