新逻辑别直接全量：让 Codex 先把风险改动藏到开关后面

教程定位

这篇教程解决什么问题

很多风险改动不适合跟着代码发布一起全量生效。比如你要把订单推荐从旧规则切到新算法，把客服工单分配从固定队列改成动态评分，把会员页的权益计算换成新服务，或者把一个接口从同步处理改成异步任务。代码可以先合并，行为不一定要立刻打开。更稳的方式，是先把新逻辑接到功能开关后面，只让少量用户、租户、角色或内部账号进入新路径；一旦指标异常，马上关闭开关，让流量回到旧逻辑。

这篇文章讲的是怎样让 Codex 帮你完成“开关隔离风险”的落地方案。它不是单纯新增一个配置项，也不是讨论开发、测试、生产的默认值该放在哪个配置文件。这里的核心问题是：新逻辑已经要写进代码了，但它不能直接替代旧逻辑。你需要让 Codex 先读现有 feature flag 体系，找出开关定义、读取方式、目标用户匹配、前后端传递、日志埋点和回退路径，再输出一份可审查的接入方案。

最终产物有两份。第一份是功能开关接入方案：开关叫什么、默认是否关闭、在哪些入口判断、目标用户规则怎么匹配、新逻辑和旧逻辑如何分流、测试要覆盖哪些路径。第二份是回退检查表：关闭开关后入口是否隐藏，后端是否停止执行新逻辑，已经进入新流程的数据如何处理，日志和监控是否能证明回退成功。

本文用一个虚构的“客服工单智能分配”场景说明。原系统按固定队列分配工单，新逻辑会根据客户等级、问题类型、客服负载和历史响应时间打分。产品希望先给 5 个内部租户和 2 个低风险业务线试用，确认没有分配异常后再扩大范围。这个需求的重点不是“把开关变量加到配置文件”，而是让新分配逻辑在运行时被开关保护，并且任何时候都能回到旧分配函数。

使用场景

什么情况下最适合用这一套

你是负责上线新逻辑的工程师。需求本身已经比较清楚，团队也同意先灰度。你现在担心的不是“这个功能能不能写出来”，而是“它会不会跟着发版直接影响所有用户”。你希望 Codex 帮忙查代码、设计接入点、生成方案，甚至后续协助改代码，但不能让它凭感觉把 `if (enabled)` 随便塞进某个文件。

典型场景是这样的：系统里有一个旧函数 `assignTicketByQueue(ticket)`，已经稳定运行很久。新需求要新增 `assignTicketByScore(ticket)`，先让少量租户试用。工单创建入口不止一个：用户提交表单会创建工单，客服后台也能手动创建，邮件导入会批量创建，定时补偿任务会重试失败工单。前端可能还会展示“智能分配中”的状态。你如果只在页面按钮旁边加一个开关，后台导入和定时任务仍可能直接走新逻辑。

这时你要的不是一段孤立代码，而是一套受控接入方案：

这篇教程适合这些情况：新逻辑会改变用户体验、业务结果、分配规则、计费结果、权限范围、推荐排序、任务调度或外部服务调用；你希望先对内部用户、少量租户、低风险城市、测试账号或指定比例开放；团队已有 feature flag、实验平台、租户配置或运行时开关体系；你需要 Codex 先给方案，再决定是否让它动代码。

不适合这篇的情况也要说清楚。如果你只是新增一个环境变量，并且问题集中在不同环境的默认值如何覆盖，那应该看配置默认值那类文章。如果你还没有确认新逻辑能不能上线，或者风险涉及支付、权限、删除、合规审批，那还需要先做高风险开工问题确认。本文默认业务方向已经确认，重点是用功能开关隔离运行时风险。

1. 找到现有功能开关体系，而不是新造一套判断。
2. 明确开关默认关闭，生产打开必须是单独动作。
3. 明确目标用户规则，例如租户白名单、用户角色、业务线或百分比。
4. 在所有会触发新逻辑的入口做同一语义的判断。
5. 新逻辑失败或开关关闭时，能回到旧逻辑。
6. 日志能看出某次请求走了新路径还是旧路径。
7. 测试同时覆盖开关开、关、规则不匹配和新逻辑异常。

材料准备

开始前先把材料和边界备齐

给 Codex 的材料要围绕“新旧逻辑如何分流”和“关闭后怎么回退”。不要只贴一句“帮我加 feature flag”。至少准备四类输入。

第一类是新功能需求。写清楚新逻辑解决什么问题、会替代哪段旧逻辑、哪些场景先开放、哪些场景绝不能进入新逻辑。例如：“客服工单智能分配只影响新创建的普通咨询工单；投诉、退款、VIP 客户人工指定工单不纳入本轮；旧队列分配逻辑保留。”

第二类是开关配置样例。给 Codex 看现有项目里 feature flag 怎么定义、怎么读取、怎么传递。可以是 `featureFlags.ts`、`flags.yml`、租户配置表结构、实验平台 SDK 调用、后端中间件、前端 `useFeatureFlag()` hook、测试里的 mock 写法。目标是让它复用现有体系，不要自己发明 `process.env.NEW_LOGIC === "true"`。

第三类是目标用户规则。说明灰度对象如何判断：租户 ID、用户 ID、角色、业务线、城市、账号标签、百分比、内部员工、白名单文件，还是配置平台里的规则。这里必须由人提供边界，Codex 只能把规则落到代码里，不能替你决定谁该试用。

第四类是旧逻辑入口。列出旧函数、接口、队列任务、页面入口和批处理入口。比如 `createTicket()`、`manualCreateTicket()`、`importEmailTickets()`、`retryUnassignedTickets()`、`assignTicketByQueue()`。如果你不确定入口完整性，就让 Codex 先只读搜索，输出入口清单和证据，再进入方案设计。

建议你一开始就给 Codex 加上硬边界：

这段边界能防止两个常见问题。一个是 Codex 直接开始写代码，结果只改了最显眼的入口。另一个是它为了“完整”自己设计一套开关系统，反而绕过了团队已有的审批、配置和监控习惯。

本轮先只读分析并输出功能开关接入方案，不直接改代码。
请先查现有 feature flag 或实验体系，复用项目已有写法。
不要决定灰度对象，只根据我提供的目标用户规则落地。
方案必须包含默认关闭、旧逻辑回退、日志埋点和测试覆盖。
如果入口不完整，请列为待确认，不要假设只有一个入口。

实操流程

按这套步骤把工作跑起来

第一步，让 Codex 查现有开关体系。要求它搜索 `featureFlag`、`experiment`、`rollout`、`beta`、`tenantConfig`、`isEnabled`、`useFeature`、`launchDarkly`、`unleash`、`split` 等线索，也要看测试里怎么 mock 开关。输出里必须包含：开关定义位置、读取 API、默认值策略、目标用户匹配方式、前后端是否共用同一语义、生产打开由谁操作。

第二步，让 Codex 找新旧逻辑的所有入口。不要只看你打算修改的函数。以客服工单为例，创建工单可能来自网页表单、客服后台、邮件导入、开放 API、批量重试和补偿任务。Codex 要输出入口清单，每个入口都标明当前是否调用旧逻辑、是否会触发新逻辑、是否需要开关判断、是否用户可见。

第三步，定义开关语义。一个合格的 feature flag 名字应该描述行为，而不是描述发布批次。比如 `smartTicketAssignment` 比 `release202607` 更好。语义要写清楚：开关打开时，符合目标用户规则的新建普通咨询工单走智能分配；开关关闭、规则不匹配或新逻辑失败时，走旧队列分配。不要把“打开入口”和“执行新逻辑”混成一个没有边界的布尔值。

第四步，设计目标用户匹配。让 Codex 根据你给的规则输出匹配函数，而不是散落在多个入口里重复判断。比如 `isSmartAssignmentEligible(context)` 可以检查租户 ID、业务线、工单类型、用户角色和内部账号标记。匹配函数应该接收明确的上下文，不应该在函数内部偷偷读页面状态或全局变量。这样测试才能覆盖“开关开但用户不符合”“用户符合但开关关”这两种路径。

第五步，选择分流位置。分流点越靠近核心业务入口，越容易覆盖所有触发方式。前端入口可以隐藏按钮或提示，但后端仍必须保护执行逻辑。对工单分配来说，较稳的位置通常是 `assignTicket(ticket, context)` 这类统一服务层，而不是某个页面组件。Codex 要解释为什么选择这个位置，并列出没有覆盖到的入口。

第六步，保留旧逻辑回退。不要让新函数直接替换旧函数。更稳的写法是保留 `assignTicketByQueue()`，新增 `assignTicketByScore()`，再由一个分流函数决定调用谁。关闭开关后，新的请求走旧逻辑；如果新逻辑抛出可恢复错误，也要明确是回退到旧逻辑、返回错误，还是进入人工处理。这个策略需要你确认，Codex 不能自己决定。

第七步，补日志和观测字段。每次分流都应该能看出：开关值是什么，目标用户是否匹配，实际路径是 `old_queue` 还是 `smart_score`，回退原因是什么，请求 ID、租户 ID 和工单类型是什么。日志不要记录用户隐私明文，也不要把目标名单打出来。监控上至少要能比较新旧路径的成功率、耗时、分配失败率和人工改派率。

第八步，写测试矩阵。功能开关不是只测“打开后能用”。要覆盖开关关闭、开关打开但用户不匹配、开关打开且用户匹配、新逻辑异常、旧逻辑仍可用、所有入口都能遵守同一判断。让 Codex 把测试名写出来，并标明哪些是单元测试、哪些是服务层集成测试、哪些是端到端或手工验收。

第九步，生成回退检查表。检查表要面向发布当天使用，不要写成抽象原则。它应该回答：在哪里关闭开关，关闭后多久生效，是否需要清缓存，前端入口是否同步隐藏，后端是否停止调用新逻辑，队列中已进入新逻辑的任务如何处理，日志里如何确认流量回到旧路径，谁负责观察指标。

第十步，再决定是否让 Codex 改代码。方案通过人工审查后，才把任务缩小成具体实现：新增开关定义、接入分流函数、补测试、补日志、更新回退说明。每一步都要限制范围，不让 Codex 顺手重构旧分配逻辑、改目标用户规则、或把生产开关直接打开。

输入示例

可以直接参考的输入材料

下面是一段可以直接给 Codex 的脱敏输入。它包含新功能需求、现有开关样例、目标用户规则和旧逻辑入口，但不包含真实租户、真实客户、真实密钥或生产配置。

这份输入有几个关键点。它没有让 Codex 猜“哪些用户风险低”，而是给了目标用户规则。它没有只说“加个开关”，而是给出现有体系样例。它也没有只给一个旧函数，而是列出多个可能入口，提醒 Codex 不要漏掉批处理和重试任务。

需求：
我们要给客服工单系统接入“智能分配”新逻辑。旧逻辑是按固定队列分配，新逻辑会根据客户等级、问题类型、客服负载和历史响应时间打分。新逻辑先只给少量灰度对象试用，不能全量打开。

目标用户规则：
- 仅租户 tenant_internal_001、tenant_internal_002、tenant_trial_101、tenant_trial_102、tenant_trial_103。
- 仅普通咨询工单，ticket.type = "general_question"。
- 不包含投诉、退款、VIP 客户和人工指定客服的工单。
- 内部员工账号可以在预发环境试用，但生产仍需租户白名单。

旧逻辑入口：
- services/ticket/assignment.ts 里有 assignTicketByQueue(ticket)
- services/ticket/createTicket.ts 里有 createTicket(input, context)
- services/ticket/manualCreate.ts 里有 manualCreateTicket(input, context)
- jobs/importEmailTickets.ts 会批量创建工单
- jobs/retryUnassignedTickets.ts 会重试未分配工单

现有开关体系样例：

// packages/flags/src/flags.ts
export const flags = {
  betaAgentWorkspace: {
    defaultValue: false,
    description: "客服新版工作台入口"
  },
  invoiceAutoExport: {
    defaultValue: false,
    description: "发票自动导出任务"
  }
};

// packages/flags/src/server.ts
export async function isFeatureEnabled(flagName, context) {
  const rule = await flagStore.getRule(flagName);
  return evaluateRule(rule, {
    tenantId: context.tenantId,
    userId: context.userId,
    role: context.role,
    environment: context.environment
  });
}

// 测试里常用：
mockFeatureFlag("betaAgentWorkspace", true, {
  tenantIds: ["tenant_internal_001"]
});

请先只读分析，输出功能开关接入方案和回退检查表，不要直接改代码。

提示词

可复制使用的提示词

你可以把下面这段提示词贴给 Codex，再把自己的材料追加到后面：

这段提示词的重点，是把 Codex 的输出从“帮我实现新功能”收窄到“先给我可审查的接入方案”。你也可以在方案通过后，把其中一小步改成实现任务，例如“只新增开关定义和匹配函数，不接入分流”，或者“只在服务层统一入口接入开关，不改页面”。

你现在是这个仓库的功能开关接入助手。请先只读分析，不要改代码。

我要把一段风险较高的新逻辑接到 feature flag 后面，只给少量目标用户试用，不能跟随代码发布直接全量生效。

请按下面顺序工作：
1. 查找现有 feature flag、实验、租户配置或灰度体系，说明开关在哪里定义、如何读取、如何 mock、默认值是什么、生产打开通常由谁操作。
2. 查找旧逻辑入口和所有会触发该逻辑的调用路径，特别注意页面入口、后端接口、后台操作、导入任务、重试任务和队列消费。
3. 设计一个开关语义和目标用户匹配函数，必须复用现有开关体系，不要新造一套配置读取方式。
4. 给出新旧逻辑分流方案，说明判断应该放在哪一层，哪些入口会被覆盖，哪些入口需要人工确认。
5. 说明默认关闭、规则不匹配、新逻辑异常、关闭开关后的回退行为。
6. 输出日志和监控建议，能区分 old_path、new_path、fallback 和 ineligible。
7. 输出测试矩阵，覆盖开关开关、目标用户匹配、入口覆盖和异常回退。
8. 输出发布当天可用的回退检查表。

硬性边界：
- 不要决定灰度名单，只使用我提供的目标用户规则。
- 不要把生产开关改成打开。
- 不要移除旧逻辑。
- 不要顺手重构无关代码。
- 如果找不到统一入口，请列出风险和待确认点。

我的材料如下：
[粘贴新功能需求、现有开关样例、目标用户规则、旧逻辑入口和相关路径]

输出样例

AI 应该输出到什么程度

下面是一份理想输出的缩略版。真实项目里，Codex 应该附上具体文件路径、函数名和证据行号。

# 功能开关接入方案：smartTicketAssignment

教程正文

1. 现有开关体系

• 开关定义：packages/flags/src/flags.ts
• 服务端读取：packages/flags/src/server.ts 的 isFeatureEnabled(flagName, context)
• 规则评估：evaluateRule 支持 tenantIds、userIds、roles、environment
• 测试 mock：mockFeatureFlag(flagName, enabled, rule)
• 现有默认策略：用户可见或会触发后台任务的开关默认 false
• 结论：新增 smartTicketAssignment 应复用 flags.ts 和 isFeatureEnabled，不新增 process.env 直读逻辑

教程正文

2. 建议开关语义

flagName: smartTicketAssignment defaultValue: false description: "客服工单智能分配，仅对符合灰度规则的新建普通咨询工单启用"

打开且符合目标规则时：

关闭、规则不匹配或目标类型不适用时：

• 新建普通咨询工单调用 assignTicketByScore(ticket, context)
• 调用现有 assignTicketByQueue(ticket)

教程正文

3. 目标用户匹配

建议新增： isSmartAssignmentEligible(ticket, context)

匹配条件：

待人工确认：

• flag smartTicketAssignment 对 context 返回 true
• tenantId 在规则允许范围内
• ticket.type === "general_question"
• ticket.customerTier !== "vip"
• ticket.source 不属于 complaint/refund
• ticket.assigneeId 为空，表示不是人工指定
• 邮件导入的 VIP 判断字段是否可靠
• retryUnassignedTickets 是否可能处理历史投诉工单

教程正文

4. 分流位置

建议在 services/ticket/assignment.ts 新增 assignTicket(ticket, context) 作为统一分流点：

if (await shouldUseSmartAssignment(ticket, context)) { return assignTicketByScore(ticket, context); } return assignTicketByQueue(ticket);

需要改造调用方：

不建议只在前端入口判断，因为后台创建、邮件导入和重试任务会绕过页面。

• createTicket(input, context)
• manualCreateTicket(input, context)
• importEmailTickets job
• retryUnassignedTickets job

教程正文

5. 回退行为

• 开关关闭：所有新请求走 assignTicketByQueue。
• 规则不匹配：走 assignTicketByQueue，并记录 ineligible_reason。
• 新逻辑抛出 ScoreServiceUnavailable：记录 fallback_to_old_queue，走 assignTicketByQueue。
• 新逻辑返回 invalid_score：不自动分配，进入人工处理队列。此策略需人工确认。
• 已经由新逻辑分配成功的历史工单：关闭开关后不自动改派，除非人工操作。

教程正文

6. 日志和监控

每次分流记录：

监控建议：

• requestId
• tenantId hash
• ticketType
• flagName
• flagEnabled
• eligible
• assignmentPath: old_queue | smart_score | fallback_old_queue | manual_review
• fallbackReason
• smart_score 分配成功率
• fallback_old_queue 次数
• manual_review 次数
• 新旧路径平均分配耗时
• 灰度租户的人工改派率

教程正文

7. 测试矩阵

| 场景 | 预期 | | --- | --- | | 开关关闭，租户在白名单 | 走旧队列 | | 开关打开，租户不在白名单 | 走旧队列 | | 开关打开，白名单租户，普通咨询 | 走智能分配 | | 开关打开，白名单租户，退款工单 | 走旧队列 | | 开关打开，白名单租户，VIP 客户 | 走旧队列 | | 智能分配服务不可用 | 记录 fallback，走旧队列 | | 邮件导入创建普通咨询工单 | 遵守同一分流规则 | | 重试未分配工单 | 不绕过开关 |

教程正文

8. 回退检查表

• 确认生产 smartTicketAssignment 当前规则和启用状态。
• 关闭 smartTicketAssignment，并记录操作人、时间和审批单号。
• 等待配置刷新窗口，确认新请求日志 assignmentPath 不再出现 smart_score。
• 检查前端是否不再展示智能分配相关提示。
• 检查 createTicket、manualCreateTicket、importEmailTickets、retryUnassignedTickets 都回到 old_queue 或 ineligible。
• 确认队列里已进入 smart_score 的任务处理策略：已成功的不自动改派，未完成的转人工或旧逻辑重试。
• 观察 30 分钟：分配失败率、人工改派率、队列积压、客服响应时长。

这份输出合格的地方在于，它没有把 feature flag 当成一个孤立布尔值。它先证明了项目已有开关体系，再把目标用户匹配、所有入口、旧逻辑保留、异常回退、日志和测试连成一个完整方案。它也没有替你决定灰度名单，而是把不确定点列出来给人确认。

人工验收

人要怎么检查和改到可用

第一，检查开关语义是否足够窄。`smartTicketAssignment` 只应该控制客服工单智能分配，不应该顺手控制新版客服工作台、推荐话术、统计报表或别的体验。如果一个开关同时控制太多东西，关闭时很难判断影响面。

第二，检查默认值和打开动作。代码里的开关定义应该默认关闭；生产打开应该通过配置平台、实验平台或租户规则单独完成，并留下审批记录。不要在同一个 PR 里既新增开关，又把生产规则改成全量打开。

第三，检查判断点是否覆盖所有入口。前端隐藏只是体验控制，不是风险隔离。真正的执行逻辑必须在后端服务层、任务处理器或统一业务入口被保护。对每个入口都问一句：如果用户绕过页面、批处理重试、开放 API 调用，这个判断还生效吗？

第四，检查目标用户规则有没有被 Codex 自行扩大。比如你只说 5 个租户，它不能改成“租户 ID 前缀匹配 trial”；你只说普通咨询，它不能把退款咨询也算进去。灰度规则必须来自人确认的输入。

第五，检查旧逻辑是否仍然可运行。旧函数不要被重命名、删除或大幅重构。上线初期，旧逻辑就是回退路径。如果 Codex 为了复用代码把旧逻辑拆得面目全非，回退就不再可靠。

第六，检查新逻辑异常时的策略。不是所有异常都应该自动回退。有些异常可以走旧逻辑，有些异常说明数据不完整，需要人工处理。比如评分服务短暂不可用可以回旧队列；评分结果非法可能应该进入人工处理，避免错误分配。这个策略要由业务和工程共同确认。

第七，检查日志是否能支撑回退判断。关闭开关后，你要能从日志看到 `smart_score` 不再出现，而不是只能凭用户反馈判断。日志字段要足够说明路径，但不能包含客户隐私、完整租户名单或敏感规则。

第八，检查测试是否覆盖关闭状态。很多开关接入只测“打开后新功能可用”，漏掉“关闭后旧逻辑仍可用”。灰度发布最重要的测试之一，就是关闭开关后系统回到旧路径。

第九，检查回退检查表能不能在发布当天执行。它应该有明确动作、位置、观察指标和责任人，而不是“必要时回滚”。如果关闭开关还需要清缓存、等配置刷新、重启任务消费者或处理队列积压，必须提前写出来。

失败反例

这些失败反例要提前避开

【反例 1：只在前端藏入口，后端仍直接走新逻辑】

这种写法只能控制页面显示。用户从开放 API 创建工单、邮件导入创建工单、后台手动创建工单时，仍可能在后端直接调用新分配逻辑。风险改动的开关要保护执行路径，不只是保护按钮和文案。

更好的做法是在服务层统一分流，并让所有入口都调用同一个分流函数。前端可以同步读取开关来调整体验，但不能成为唯一防线。

【反例 2：把新逻辑直接替换旧逻辑，开关关闭也回不去】

如果旧逻辑已经被替换掉，开关就失去意义。哪怕你后面再补一个 `if`，也没有稳定旧路径可以回退。上线初期一定要保留旧函数和旧测试，确认关闭开关时仍能调用旧队列分配。

正确方向是新增分流层：开关打开且目标规则匹配才调用新逻辑；其他情况继续调用旧逻辑。等灰度充分稳定、团队决定长期切换后，再单独规划清理旧逻辑。

【反例 3：Codex 自己决定灰度范围】

这听起来合理，但它越权了。哪些用户适合灰度，不只是工程判断，还涉及客户承诺、销售关系、客服承接、合同范围和数据风险。Codex 可以根据你提供的规则写匹配函数，但不能替你把“少量用户”解释成某个群体。

正确做法是把灰度对象作为输入材料，或者把缺失信息列为人工确认点。没有名单、标签或规则，就不能进入实现。

【反例 4：没有记录实际分流路径】

这段代码看起来有开关，但发布后你很难判断请求到底走了哪条路径。出了问题时，客服只知道某些工单分配异常，工程师却不知道这些工单是否命中新逻辑、是否发生回退、是否因为规则不匹配而走旧逻辑。

正确做法是在分流点记录低敏日志字段，例如 `assignmentPath`、`flagEnabled`、`eligible`、`fallbackReason` 和请求 ID。这样关闭开关后，才能验证新路径流量确实归零。

if (useFeatureFlag("smartTicketAssignment")) {
  showSmartAssignmentHint();
}

export async function assignTicket(ticket, context) {
  return assignTicketByScore(ticket, context);
}

建议先对所有 trial 租户打开，因为它们风险较低。

if (enabled) {
  return assignTicketByScore(ticket, context);
}
return assignTicketByQueue(ticket);

主题边界

它和相邻主题的区别

这篇文章和“新增配置开关时，别把所有环境一起改了”不同。配置默认值文章关注的是配置层级和环境覆盖：公共默认值放哪里，开发、测试、预发、生产各读到什么值，如何避免一个默认值扩散到所有环境。本文关注的是运行时风险隔离：新逻辑和旧逻辑如何分流，目标用户规则如何匹配，哪些入口必须被开关保护，关闭后怎样回退。

它也不同于“碰到生产风险代码先问哪些问题”。高风险提问文章的重点是开工前判断是否能改，列出审计、审批、合规、灰度和人工确认点。本文默认已经决定要做新逻辑，并且已经选择用 feature flag 灰度，重点进入工程接入方案。

它还不同于“把大功能拆成小步骤”。功能拆分关注提交顺序、依赖关系和每一步能否独立合并；功能开关只是其中一个发布手段。本文把镜头拉近到开关本身：在哪里判断，谁进入新路径，旧路径怎么保留，异常怎么回退，日志如何证明开关生效。

最简单的判断方式是：如果你的问题是“这个开关在不同环境默认值怎么配”，看配置默认值；如果你的问题是“这个高风险需求能不能开始改”，先做风险提问；如果你的问题是“新逻辑已经要上线，但只能让少量用户试用，出事要能一键退回旧逻辑”，看本文。