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

Agent 写完一个功能,最省事的验证方式是直接在生产环境看:只对你自己打开,确认没问题再逐步放给用户,出了状况一条命令关掉。Vercel CLI 现在把这套流程需要的命令都给齐了:vercel flags 管功能开关、定向和灰度,vercel metrics 查线上指标,两者都能输出 JSON,Agent 在终端里就能自己操作和读数。这篇按官方文档把「开关上线 → 只给自己看 → 分阶段放量 → 盯指标 → 回滚或收尾」串成一套可以写进 AGENTS.md 的流程。
前置条件
- 一个部署在 Vercel 上的 Next.js 项目(SvelteKit 也支持,SDK 入口换成
flags/sveltekit),装好最新版 Vercel CLI,项目已vercel link。 - Vercel Flags 官方标注所有套餐可用。
vercel metrics里,Web Analytics 和 Speed Insights 的指标不需要 Observability Plus,其他指标需要。 - 项目里有登录体系,能在服务端拿到当前用户 ID,用来做定向。
为什么让 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 并告诉我。
- 全量稳定后,先删掉代码里的开关判断并部署,再归档开关。
常见坑
- 加了 targets 却没生效。保存直接目标不会自动打开定向,环境还在发固定值时 CLI 只给警告。必须再跑一次
vercel flags targeting enable。 - Agent 在非交互环境里卡住或报错。很多子命令缺参数时会进入交互提问,Agent 的终端通常是非交互的。文档写明非交互环境下必须显式传参,所以规则里要求每条命令都带
-e、--by、--message等完整参数,删除、移除类操作带--yes,读结果一律加--json。 --by用了没定义的属性。灰度和分流用的分桶属性要先在实体里定义,而且不能用 timestamp 类型的属性。- 直接归档还在用的开关。归档后开关不再求值,要删除也必须先归档。顺序应该是:全量 → 删代码里的判断 → 部署 → 归档。
- 以为所有指标都能查。除 Web Analytics 和 Speed Insights 外,
vercel metrics需要 Observability Plus。没开的话,至少用flags evaluations确认放量比例对不对,再结合你自己的错误监控。
完成标准
- 一个新功能已经以关闭状态部署到生产,你本人登录能看到,其他账号看不到;
vercel flags evaluations new-checkout --json能看到 true / false 两个变体的求值次数;- 灰度阶段已配置,你知道暂停用哪条命令;
- AGENTS.md 里写明了「放量须人确认」和收尾顺序。
站内的 Agent PR 合并风险评估 讲合并前怎么给改动打分,和这篇的上线后流程正好前后衔接。
最后
下次让 Agent 做一个面向用户的改动时,在提示词末尾加一句「放在 Vercel Flags 开关后面,生产环境只对我打开」,跑完这一轮再决定要不要写进 AGENTS.md。