《互联网产品的 AI 架构·多能力编排与任务闭环》12.1 从单能力到编排的重构

// file: src/orch/evolution.ts
// tier: L2
// verify: node --test test/orch/evolution.test.ts

import { AiError } from "../core/errors.ts";

export type RefactorStepId = "node-contract" | "executor" | "chain-split";

export const STEP_ORDER: readonly RefactorStepId[] = ["node-contract", "executor", "chain-split"];

/** 一次重构步骤的可观测证据；比例用 0–1，计数用整数。 */
export interface RefactorEvidence {
  step: RefactorStepId;
  /** 已声明并校验输入输出的节点 / 全部节点。 */
  contractCoverage: number;
  /** 经统一执行器调用的能力占比；其余仍是业务代码直连。 */
  executorShare: number;
  /** 同一批请求在新旧路径上的行为一致率。 */
  behaviorParity: number;
  /** 旧路径是否保留，可一键切回。 */
  legacyPathRetained: boolean;
  /** 有独立开关、可单独回退的链路数。 */
  chainToggles: number;
  /** 回退演练通过次数。 */
  rollbackDrills: number;
}

export interface GateResult {
  id: string;
  expected: string;
  actual: string;
  ok: boolean;
}

export interface StepAssessment {
  step: RefactorStepId;
  title: string;
  passed: boolean;
  checks: GateResult[];
  failed: string[];
  /** 回退到上一步的具体动作。 */
  rollback: string;
  /** 通过后允许进入的下一步。 */
  next: string;
}

interface Gate {
  id: string;
  expected: string;
  ok: (evidence: RefactorEvidence) => boolean;
  actual: (evidence: RefactorEvidence) => string;
}

const pct = (value: number): string => `${(value * 100).toFixed(2)}%`;

/** 每一步只回答一个问题：现有证据是否足以支撑下一步。 */
const STEP_GATES: Record<RefactorStepId, readonly Gate[]> = {
  "node-contract": [
    { id: "contract-coverage", expected: ">= 95.00%", ok: (e) => e.contractCoverage >= 0.95, actual: (e) => pct(e.contractCoverage) },
    { id: "behavior-parity", expected: ">= 99.00%", ok: (e) => e.behaviorParity >= 0.99, actual: (e) => pct(e.behaviorParity) },
    { id: "legacy-path", expected: "retained", ok: (e) => e.legacyPathRetained, actual: (e) => String(e.legacyPathRetained) },
  ],
  executor: [
    { id: "executor-share", expected: ">= 90.00%", ok: (e) => e.executorShare >= 0.9, actual: (e) => pct(e.executorShare) },
    { id: "behavior-parity", expected: ">= 99.00%", ok: (e) => e.behaviorParity >= 0.99, actual: (e) => pct(e.behaviorParity) },
    { id: "rollback-drill", expected: ">= 1", ok: (e) => e.rollbackDrills >= 1, actual: (e) => String(e.rollbackDrills) },
    { id: "legacy-path", expected: "retained", ok: (e) => e.legacyPathRetained, actual: (e) => String(e.legacyPathRetained) },
  ],
  "chain-split": [
    { id: "chain-toggles", expected: ">= 3", ok: (e) => e.chainToggles >= 3, actual: (e) => String(e.chainToggles) },
    { id: "behavior-parity", expected: ">= 99.00%", ok: (e) => e.behaviorParity >= 0.99, actual: (e) => pct(e.behaviorParity) },
    { id: "rollback-drill", expected: ">= 2", ok: (e) => e.rollbackDrills >= 2, actual: (e) => String(e.rollbackDrills) },
    { id: "legacy-path", expected: "retained", ok: (e) => e.legacyPathRetained, actual: (e) => String(e.legacyPathRetained) },
  ],
};

const STEP_META: Record<RefactorStepId, { title: string; rollback: string; next: string }> = {
  "node-contract": {
    title: "抽节点契约",
    rollback: "契约校验先以 shadow 模式运行，只记录不拒绝；发现问题时关闭校验，不切流量。",
    next: "进入执行器抽取：把重试、超时与预算集中到一个调用点。",
  },
  executor: {
    title: "抽执行器",
    rollback: "执行器按能力维度保留直连开关；异常时按能力切回直连，不影响其他能力。",
    next: "进入链路拆分：把 A/B/C 三条链路分别开关，逐条迁移。",
  },
  "chain-split": {
    title: "拆链路",
    rollback: "每条链路独立开关；回退只切开关并停止新版本接单，不删除旧状态与旧缓存。",
    next: "三条链路都通过验收后，才允许声明编排层成为默认路径。",
  },
};

function fail(message: string): never {
  throw new AiError("invalid-request", `evolution: ${message}`);
}

function ratio(value: number, field: string): number {
  if (!Number.isFinite(value) || value < 0 || value > 1) fail(`${field} 必须落在 [0, 1]`);
  return value;
}

function integer(value: number, field: string): number {
  if (!Number.isInteger(value) || value < 0) fail(`${field} 必须是 >= 0 的整数`);
  return value;
}

function validate(evidence: RefactorEvidence): void {
  if (!STEP_ORDER.includes(evidence.step)) fail(`未知步骤 ${evidence.step}`);
  ratio(evidence.contractCoverage, "contractCoverage");
  ratio(evidence.executorShare, "executorShare");
  ratio(evidence.behaviorParity, "behaviorParity");
  integer(evidence.chainToggles, "chainToggles");
  integer(evidence.rollbackDrills, "rollbackDrills");
  if (typeof evidence.legacyPathRetained !== "boolean") fail("legacyPathRetained 必须是布尔值");
}

/** 单步验收：返回逐项证据，而不是一个通过/不通过的布尔值。 */
export function assessRefactorStep(evidence: RefactorEvidence): StepAssessment {
  validate(evidence);
  const checks = STEP_GATES[evidence.step].map((gate) => ({
    id: gate.id,
    expected: gate.expected,
    actual: gate.actual(evidence),
    ok: gate.ok(evidence),
  }));
  const failed = checks.filter((check) => !check.ok).map((check) => check.id);
  const meta = STEP_META[evidence.step];
  return {
    step: evidence.step,
    title: meta.title,
    passed: failed.length === 0,
    checks,
    failed,
    rollback: meta.rollback,
    next: meta.next,
  };
}

export type PlanStopReason = "complete" | "failed-gate" | "missing-evidence";

export interface RefactorPlan {
  completed: RefactorStepId[];
  blockedAt: RefactorStepId | null;
  reason: PlanStopReason;
  canOrchestrate: boolean;
  assessments: StepAssessment[];
}

/**
 * 重构必须按顺序验收：后一步的证据不能抵消前一步的缺口。
 * 某一步失败时立即停止，返回该步的回退动作，而不是继续评估后面的步骤。
 */
export function planRefactor(evidences: readonly RefactorEvidence[]): RefactorPlan {
  const byStep = new Map<RefactorStepId, RefactorEvidence>();
  for (const evidence of evidences) {
    validate(evidence);
    if (byStep.has(evidence.step)) fail(`重复的步骤证据 ${evidence.step}`);
    byStep.set(evidence.step, evidence);
  }
  const completed: RefactorStepId[] = [];
  const assessments: StepAssessment[] = [];
  for (const step of STEP_ORDER) {
    const evidence = byStep.get(step);
    if (evidence === undefined) {
      return { completed, blockedAt: step, reason: "missing-evidence", canOrchestrate: false, assessments };
    }
    const assessment = assessRefactorStep(evidence);
    assessments.push(assessment);
    if (!assessment.passed) {
      return { completed, blockedAt: step, reason: "failed-gate", canOrchestrate: false, assessments };
    }
    completed.push(step);
  }
  return { completed, blockedAt: null, reason: "complete", canOrchestrate: true, assessments };
}

/** 下一步的步骤 id；已完成全部步骤时返回 null。 */
export function nextRefactorStep(completed: readonly RefactorStepId[]): RefactorStepId | null {
  return STEP_ORDER.find((step) => !completed.includes(step)) ?? null;
}