《互联网产品的 AI 架构·多能力编排与任务闭环》12.3 从固定编排到自主 Agent

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

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

export type BoundaryRecommendation = "fixed" | "bounded-agent" | "autonomous-agent";

export type BoundaryComponentId =
  | "path"
  | "steps"
  | "failure-cost"
  | "audit"
  | "reversibility"
  | "variability"
  | "tools";

export interface BoundaryInput {
  /** 任务路径能否在编译期枚举；可枚举时固定编排已经能表达全部路径。 */
  pathEnumerable: boolean;
  /** 典型任务需要的步骤数；未知时不要用 0，而应显式给出上限。 */
  typicalSteps: number;
  /** 单次失败的业务代价，整数微元。 */
  failureCostMicros: number;
  /** 是否要求每一步可审计、可复现。 */
  auditRequired: boolean;
  /** 动作是否可逆：可撤销、可补偿、可重放。 */
  reversible: boolean;
  /** 任务分布漂移：0 稳定，1 高度长尾。 */
  taskVariability: number;
  /** 可调用工具数；工具越多，路径越难枚举。 */
  toolCount: number;
}

export interface BoundaryComponent {
  id: BoundaryComponentId;
  weight: number;
  /** 0 表示更像固定编排，1 表示更像自主 Agent。 */
  value: number;
  note: string;
}

export interface BoundaryDecision {
  score: number;
  recommendation: BoundaryRecommendation;
  components: BoundaryComponent[];
  vetoes: string[];
  guardrails: {
    maxSteps: number;
    maxCostMicros: number;
    requiresHumanCheckpoint: boolean;
    auditTrail: boolean;
  };
}

/** 权重之和为 1；硬判据不参与加权，而是直接否决。 */
export const BOUNDARY_WEIGHTS: Record<BoundaryComponentId, number> = {
  path: 0.3,
  steps: 0.15,
  "failure-cost": 0.2,
  audit: 0.15,
  reversibility: 0.1,
  variability: 0.05,
  tools: 0.05,
};

export const STEP_CAP = 24;
export const HIGH_FAILURE_COST_MICROS = 1_000_000;
export const CHECKPOINT_FAILURE_COST_MICROS = 100_000;
export const AGENT_THRESHOLD = 0.7;
export const BOUNDED_THRESHOLD = 0.45;

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

function clamp01(value: number): number {
  return Math.min(1, Math.max(0, value));
}

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

function validate(input: BoundaryInput): void {
  if (!Number.isInteger(input.typicalSteps) || input.typicalSteps < 1) fail("typicalSteps 必须是正整数");
  finite(input.failureCostMicros, "failureCostMicros");
  if (!Number.isFinite(input.taskVariability) || input.taskVariability < 0 || input.taskVariability > 1) {
    fail("taskVariability 必须落在 [0, 1]");
  }
  if (!Number.isInteger(input.toolCount) || input.toolCount < 0) fail("toolCount 必须是 >= 0 的整数");
}

/** 失败代价越低，越适合让 Agent 试错；按对数插值，避免被极端值拉偏。 */
function costAffinity(failureCostMicros: number): number {
  const low = Math.log10(100);
  const high = Math.log10(HIGH_FAILURE_COST_MICROS);
  const value = Math.log10(Math.max(failureCostMicros, 1));
  return clamp01((high - value) / (high - low));
}

function stepAffinity(steps: number): number {
  return clamp01((steps - 4) / 8);
}

function toolAffinity(toolCount: number): number {
  return clamp01((toolCount - 2) / 8);
}

/**
 * 固定编排与自主 Agent 的边界判定。
 * 先收集硬否决，再加权评分；有任意否决时一律回到固定编排。
 */
export function decideBoundary(input: BoundaryInput): BoundaryDecision {
  validate(input);
  const components: BoundaryComponent[] = [
    { id: "path", weight: BOUNDARY_WEIGHTS.path, value: input.pathEnumerable ? 0 : 1, note: input.pathEnumerable ? "路径可枚举" : "路径不可枚举" },
    { id: "steps", weight: BOUNDARY_WEIGHTS.steps, value: stepAffinity(input.typicalSteps), note: `${input.typicalSteps} 步` },
    { id: "failure-cost", weight: BOUNDARY_WEIGHTS["failure-cost"], value: costAffinity(input.failureCostMicros), note: `${input.failureCostMicros} 微元` },
    { id: "audit", weight: BOUNDARY_WEIGHTS.audit, value: input.auditRequired ? 0 : 1, note: input.auditRequired ? "要求逐步审计" : "不要求逐步审计" },
    { id: "reversibility", weight: BOUNDARY_WEIGHTS.reversibility, value: input.reversible ? 1 : 0, note: input.reversible ? "可逆" : "不可逆" },
    { id: "variability", weight: BOUNDARY_WEIGHTS.variability, value: input.taskVariability, note: `漂移 ${input.taskVariability}` },
    { id: "tools", weight: BOUNDARY_WEIGHTS.tools, value: toolAffinity(input.toolCount), note: `${input.toolCount} 个工具` },
  ];

  const score = Number(components.reduce((sum, component) => sum + component.weight * component.value, 0).toFixed(4));
  const vetoes: string[] = [];
  if (input.pathEnumerable) vetoes.push("path-enumerable");
  if (input.auditRequired && !input.reversible) vetoes.push("audit-irreversible");
  if (input.failureCostMicros >= HIGH_FAILURE_COST_MICROS) vetoes.push("failure-cost");
  if (input.typicalSteps > STEP_CAP) vetoes.push("step-cap");

  let recommendation: BoundaryRecommendation =
    score >= AGENT_THRESHOLD ? "autonomous-agent" : score >= BOUNDED_THRESHOLD ? "bounded-agent" : "fixed";
  if (vetoes.length > 0) {
    recommendation = "fixed";
  } else if (!input.reversible && recommendation === "autonomous-agent") {
    recommendation = "bounded-agent";
  }

  const maxSteps = recommendation === "fixed"
    ? input.typicalSteps
    : recommendation === "bounded-agent"
      ? Math.min(12, Math.max(6, input.typicalSteps + 2))
      : STEP_CAP;

  return {
    score,
    recommendation,
    components,
    vetoes,
    guardrails: {
      maxSteps,
      maxCostMicros: Math.max(1_000, Math.floor(input.failureCostMicros / 2)),
      requiresHumanCheckpoint: input.auditRequired || !input.reversible || input.failureCostMicros >= CHECKPOINT_FAILURE_COST_MICROS,
      auditTrail: input.auditRequired || recommendation !== "fixed",
    },
  };
}

/** 一组任务的建议分布；用来确认「大多数请求仍然是固定编排」。 */
export function summarizeBoundary(decisions: readonly BoundaryDecision[]): Record<BoundaryRecommendation, number> {
  const summary: Record<BoundaryRecommendation, number> = {
    fixed: 0,
    "bounded-agent": 0,
    "autonomous-agent": 0,
  };
  for (const decision of decisions) summary[decision.recommendation] += 1;
  return summary;
}