《AI Agent 产品开发·组织、平台与规模化》10.3 能力下线与迁移

能力下线是产品承诺的一部分,不是清理动作。本节给通知、并行、迁移、退役四阶段流程与迁移工具清单,用 A Relay 的旧队列下线说明 8 退 1、12.5%、3,300 单与 10 周并行期怎么算,并说明不下线的真实代价,最后给出一段可运行的下线门禁代码。

以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。

产品团队擅长发布,不擅长下线。发布有仪式感,下线像打扫卫生:旧队列还在跑,旧模板还有人用,旧接口还有调用,于是所有人都同意「先留着」,一留就是一年。

但能力下线不是清理动作,是产品承诺的一部分。你承诺过用户「这个队列会一直可用」,现在要收回,就必须给出通知、并行期与迁移路径;否则用户会在某天发现自己的工单进了另一个队列,而没有任何人告诉过他。

这一节讲三件事:下线流程怎么排、A Relay 的旧队列怎么退、不下线的代价是什么。

下线是承诺,不是清理

把一个能力下线,至少改变了三件事:用户的习惯、系统的路由、责任的归属。三件事里任何一件没处理好,下线都会变成事故。

习惯:用户可能已经把「这个队列」写进了自己的周报、自动化规则或培训材料。你删掉它,用户的流程就断了。

路由:旧能力往往还有调用方,包括内部报表、外部集成、历史任务。你停掉它,调用方会在半夜报警。

责任:旧能力下线后,原来由它承担的责任要有人接。如果新路径只是「理论上等价」,但没有审计与回滚,责任就落空了。

所以下线不是「删代码」,是「把一段承诺迁移到另一段承诺上」。这也解释了为什么下线流程里,通知与并行期比技术迁移更重要。

下线流程的四个阶段

一个可执行的下线流程至少有四个阶段。每个阶段都有产出物,不能靠「大家都知道」。

阶段要做什么产出物退出条件
通知告诉用户与调用方,说明替代路径与时间表公告、迁移指南、负责人关键调用方确认收到
并行新旧路径同时跑,记录差异差异报表、影子对比差异可解释,无未归因错误
迁移把调用方与任务逐步切到新路径迁移清单、覆盖率覆盖率达标,回滚可用
退役停掉旧路径,保留审计与回滚窗口退役记录、复盘观察期无异常,责任人签字

四个阶段里,「并行」最容易被压缩。团队觉得新旧路径都跑一遍浪费资源,于是直接切换;结果差异在切换后才暴露,用户已经受影响。并行期的长度不能拍脑袋,至少要覆盖一个完整产品周期,因为很多差异只在跨周期时出现。

A Relay 的旧队列怎么退

A Relay 有 8 个队列:账单、登录、集成、数据、Bug、功能请求、退款、其他。假设要退掉其中 1 个旧队列,把它合并到相邻队列。

影响面。 按 8 个队列均摊,退 1 个约影响 12.5% 的工单;月工单量 26,400 单,折算约 3,300 单/月。这个数字只能用于估算,真实分布不会均匀;迁移前必须按实际路由重算,不能拿均摊数当承诺。

并行期。 A 的第一个产品周期是 10 周,并行期至少 10 周。低于这个长度,跨月的工单分布、季节性峰值、模板轮换都可能没被覆盖。

退役门槛。 新队列要达到全量放量的同一质量线:采纳率 ≥ 75.0%,错误率 ≤ 3.0%。A 当前的 78.0% 采纳率与 2.9% 采纳后错误率刚好过线;但这是「当前水平」,不是「迁移后自动继承」,迁移后要重新跑一遍。

回滚。 退役后仍要保留回滚路径:旧队列的路由规则不删除,只是不再接收新任务;一旦新队列出现未归因错误,可以把后续任务切回旧规则。

通知。 支持团队要知道哪个队列没了、工单会去哪里、周报口径怎么改;否则他们会在客户问起时才发现。

这五件事合起来,才是一次完整的下线。只做「技术迁移」那一件,等于把承诺悄悄换掉。

不下线的代价

旧能力留着,看起来没有成本,其实成本一直在发生。

审计面翻倍。 旧队列不退役,审计就要同时看两套路由规则:新规则命中什么、旧规则还会不会兜底。A 的 8 个队列在退 1 个之前,审计面是 8;退役后是 7。数字不大,但每一条旧路由都要有规则、测试与文档。

维护摊销不减少。 A 的月维护摊销是 1,200 美元,用于提示词、评测与数据标注。多留一条旧路径,不会让这 1,200 美元变少,只会让同样的维护预算覆盖更多分支。

复用率被拖住。 A 的能力复用率是 0.0%,只有一个产品;如果旧队列长期保留,未来做第二个产品时,团队还要先判断「新能力要不要兼容旧队列」。旧路径越多,复用越难。

用户认知混乱。 同一个工单可能被旧规则分到 A 队列、被新规则分到 B 队列;用户看到两个入口,不知道哪个是准的。时间一长,用户会绕开 Agent,回到人工。

责任无人接。 旧路径的 owner 往往已经转岗或不再维护;它还在跑,但出事时没人能解释规则。这是最危险的一种成本:不是花钱,是责任悬空。

迁移工具的最小清单

下线要靠工具,不能靠人肉对照。最小清单有五项:

  1. 路由导出:把旧路径的规则、阈值、例外完整导出,能逐条对照。
  2. 影子对比:新旧路径同时跑,记录每条任务的差异与原因。
  3. 差异归因:差异要能归到「规则不同」「数据不同」「模型不同」,不能只列「不一致」。
  4. 回滚开关:一条命令把后续任务切回旧路径,且不影响已经迁移的数据。
  5. 覆盖率报表:按队列、按任务类型看迁移进度,避免「总体 90%」掩盖某个队列没动。

五项里,影子对比与差异归因最重要。没有它们,迁移就只是「把开关拨过去」,你永远不知道拨过去之后错在哪。

把下线门禁写成函数

下面的模型把四阶段、A 的旧队列计划、影响面计算与退役门禁写进同一个文件。它不执行迁移,只回答一个问题:现在能不能退役。

// file: src/scale/10-3-deprecation.ts
// tier: L2
// verify: node --test test/scale/10-3-deprecation.test.ts

// 能力下线是产品承诺的一部分:先通知、再并行、再迁移、最后退役。
// 没有迁移证据就下线,等于把旧路径上的任务直接丢给用户。

import { RELAY, type Profile } from "../cases.ts";
import { divide, formatBps } from "../core/rate.ts";

export type Phase = "announce" | "parallel" | "migrate" | "retire";

export const PHASES: readonly Phase[] = [
  "announce",
  "parallel",
  "migrate",
  "retire",
];

export const PHASE_LABEL: Record<Phase, string> = {
  announce: "通知",
  parallel: "并行",
  migrate: "迁移",
  retire: "退役",
};

export type DeprecationPlan = {
  readonly caseKey: "A" | "B" | "C";
  readonly capability: string;
  readonly replacement: string;
  readonly totalUnits: number;
  readonly retiringUnits: number;
  readonly monthlyTasks: number;
  // 并行期必须覆盖至少一个完整产品周期。
  readonly parallelWeeks: number;
  // 迁移后新路径的采纳率与错误率,单位基点。
  readonly adoptionBps: number;
  readonly errorBps: number;
  readonly rollbackAvailable: boolean;
  readonly noticeSent: boolean;
};

export type PlanCheck = {
  readonly ok: boolean;
  readonly blockers: readonly string[];
};

// 第一个产品周期取自事实表:A 10 周,B 16 周,C 14 周。
export const FIRST_CYCLE_WEEKS: Record<"A" | "B" | "C", number> = {
  A: 10,
  B: 16,
  C: 14,
};

// 退役门槛沿用全量放量的质量线:采纳率 ≥ 75.0%,错误率 ≤ 3.0%。
export const RETIRE_MIN_ADOPTION_BPS = 7_500;
export const RETIRE_MAX_ERROR_BPS = 300;

export function affectedShareBps(plan: DeprecationPlan): number {
  return divide(plan.retiringUnits, plan.totalUnits);
}

// 按均摊估算受影响任务量;真实分布不会均匀,迁移前必须按实际路由重算。
export function affectedTasks(plan: DeprecationPlan): number {
  return Math.round(
    (plan.monthlyTasks * plan.retiringUnits) / plan.totalUnits,
  );
}

export function checkPlan(plan: DeprecationPlan): PlanCheck {
  const blockers: string[] = [];

  if (plan.replacement.trim().length === 0) {
    blockers.push("no replacement path");
  }
  if (!plan.noticeSent) {
    blockers.push("users have not been notified");
  }
  if (plan.parallelWeeks < FIRST_CYCLE_WEEKS[plan.caseKey]) {
    blockers.push("parallel period is shorter than one product cycle");
  }
  if (!plan.rollbackAvailable) {
    blockers.push("no rollback path after retirement");
  }
  if (plan.adoptionBps < RETIRE_MIN_ADOPTION_BPS) {
    blockers.push("migration adoption is below the full-rollout gate");
  }
  if (plan.errorBps > RETIRE_MAX_ERROR_BPS) {
    blockers.push("migration error is above the full-rollout gate");
  }

  return { ok: blockers.length === 0, blockers };
}

export type Surface = {
  readonly activeRoutes: number;
  readonly retiredRoutes: number;
  readonly auditSurfaces: number;
};

// 保留旧路径不是零成本:每条旧路由都还在审计范围里,
// 规则、测试与文档都要同时维护两套。
export function surfaceOf(plan: DeprecationPlan): Surface {
  const retiredRoutes = plan.retiringUnits;
  const activeRoutes = plan.totalUnits - retiredRoutes;
  return {
    activeRoutes,
    retiredRoutes,
    auditSurfaces: activeRoutes + retiredRoutes,
  };
}

// A Relay 的旧队列下线:8 个队列退 1 个,按均摊约影响 12.5% 的工单。
export const RELAY_QUEUE_PLAN: DeprecationPlan = {
  caseKey: "A",
  capability: "旧分诊队列",
  replacement: "合并后的新队列",
  totalUnits: 8,
  retiringUnits: 1,
  monthlyTasks: RELAY.monthlyTasks,
  parallelWeeks: 10,
  adoptionBps: 7_800,
  errorBps: 290,
  rollbackAvailable: true,
  noticeSent: true,
};

export const RELAY_PROFILE: Profile = RELAY;

export function affectedLabel(plan: DeprecationPlan): string {
  return formatBps(affectedShareBps(plan));
}

代码里的 affectedShareBps 用基点算影响面:1 / 8 = 1250 bps,也就是 12.5%。affectedTasks 按均摊折算 3,300 单/月,并在注释里写清「真实分布不会均匀,迁移前要按实际路由重算」。

checkPlan 检查六件事:替代路径、通知、并行期、回滚、迁移采纳率、迁移错误率。任何一项不满足,退役就不该发生。RELAY_QUEUE_PLAN 用 A 的 78.0% 采纳率与 2.9% 错误率作为示例,它刚好过 75.0% / 3.0% 的线;但代码检查的是「迁移后的指标」,不是「迁移前的现状」,这一点在真实项目里要分开记录。

surfaceOf 把「不下线的代价」变成一个结构量:退役前审计面是 8,退役后是 7。它不计算钱,但能让评审看到旧路径还在占用审计与维护资源。

小结

  • 能力下线是产品承诺的一部分,不是清理动作;它改变用户习惯、系统路由与责任归属。
  • 下线流程至少四个阶段:通知、并行、迁移、退役;每个阶段都有产出物与退出条件。
  • 并行期至少覆盖一个完整产品周期:A 是 10 周,B 是 16 周,C 是 14 周;短于这个长度,跨周期差异会在切换后才暴露。
  • A Relay 的旧队列下线:8 退 1,按均摊影响 12.5%、约 3,300 单/月;真实分布不均匀,迁移前要按实际路由重算。
  • 退役门槛沿用全量放量的质量线:采纳率 ≥ 75.0%、错误率 ≤ 3.0%;A 当前的 78.0% / 2.9% 只是示例,不是自动继承。
  • 不下线的代价包括审计面翻倍、维护摊销不减少、复用率被拖住、用户认知混乱与责任悬空。
  • 迁移工具最小清单:路由导出、影子对比、差异归因、回滚开关、覆盖率报表;缺一项就会把迁移变成拨开关。

阅读导航:上一节:10.2 发布节奏与提示词发布 · 下一节:11.1 七种死法 。

常见错误与边界

  1. 把下线当清理。 删代码只是最后一步;没有通知、并行与迁移,下线就是把承诺悄悄换掉。
  2. 压缩并行期。 并行看起来浪费资源,但它暴露的是跨周期差异;短于一个产品周期,差异会在切换后才出现。
  3. 拿均摊数当承诺。 8 退 1 约 12.5%、3,300 单/月只是估算;真实队列分布不均匀,必须按实际路由重算。
  4. 把当前指标当迁移指标。 A 现在 78.0% 采纳、2.9% 错误,不代表新队列迁移后自动达标;迁移后要重新跑门槛。
  5. 旧路径不设 owner。 旧路径还在跑但没人维护,是最危险的成本;退役前要明确谁对旧规则、回滚与复盘负责。
  6. 只做总体覆盖率。 「总体 90%」可能掩盖某个队列完全没迁移;覆盖率要按队列、按任务类型拆开看。

下线做完,一个能力周期才算真正走完。下一章换一个角度:不是所有产品都能走到下线,很多会先以某种方式死掉。下一节先列七种死法。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图