《互联网产品的 AI 架构·多能力编排与任务闭环》1.3 什么该编排，什么该固定流程

score = runtimeDecisions × 2
      + max(0, pathVariants - 1)
      + humanSteps
      + sideEffects
      + (changeFrequencyPerMonth ≥ 2 ? 1 : 0)
      + (capabilities ≥ 3 ? 1 : 0)

1 × 2 + (2 - 1) + 0 + 1 + 0 + 0 = 4

// file: src/orch/shape-choice.ts
// tier: L1
// verify: node --test test/orch/workflow-shape.test.ts

import { AiError } from "../core/errors.ts";
import type { ChainId } from "./workflow-shape.ts";

export type WorkflowDecision = "fixed-flow" | "declarative-orchestration" | "agent-loop";

/**
 * 判据只吃结构信号，不吃“感觉”。运行时才知道的决策越多、路径越散，
 * 越需要编排；路径完全可枚举时，固定流程更容易测试与回滚。
 */
export interface ShapeSignals {
  capabilities: number;
  /** 只能在请求到达后才能确定的分支数。 */
  runtimeDecisions: number;
  /** 预期会出现的不同执行路径数。 */
  pathVariants: number;
  humanSteps: number;
  /** 不可回滚或回滚代价高的外部动作数。 */
  sideEffects: number;
  changeFrequencyPerMonth: number;
}

export interface ShapeDecision {
  decision: WorkflowDecision;
  score: number;
  reasons: string[];
  controls: string[];
}

const DECLARATIVE_MAX = 10;
const FIXED_MAX = 3;

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

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

export function validateSignals(signals: ShapeSignals): void {
  count(signals.capabilities, "capabilities");
  count(signals.runtimeDecisions, "runtimeDecisions");
  count(signals.pathVariants, "pathVariants");
  count(signals.humanSteps, "humanSteps");
  count(signals.sideEffects, "sideEffects");
  count(signals.changeFrequencyPerMonth, "changeFrequencyPerMonth");
  if (signals.runtimeDecisions > 0 && signals.pathVariants < 2) {
    fail("存在运行时决策，但 pathVariants 小于 2，信号自相矛盾");
  }
}

/**
 * 三段判定：
 * 1) 单能力或路径完全可枚举 → 固定流程；
 * 2) 有运行时分支但结构可声明 → 声明式编排；
 * 3) 分支与路径超出可枚举范围 → Agent 循环，必须另加硬上限。
 */
export function decideShape(signals: ShapeSignals): ShapeDecision {
  validateSignals(signals);
  const reasons: string[] = [];
  const controls: string[] = [];

  if (signals.capabilities <= 1) {
    reasons.push("只涉及一个能力，不需要跨能力调度");
    return { decision: "fixed-flow", score: 0, reasons, controls };
  }

  if (signals.runtimeDecisions === 0 && signals.pathVariants <= 1) {
    reasons.push("执行顺序在请求到达前完全确定，固定流程即可覆盖");
    if (signals.sideEffects > 0) {
      controls.push("外部动作使用幂等键，失败走补偿而不是盲目重放");
      controls.push("动作前保留可回滚检查点");
    }
    return { decision: "fixed-flow", score: 0, reasons, controls };
  }

  const score = signals.runtimeDecisions * 2 +
    Math.max(0, signals.pathVariants - 1) +
    signals.humanSteps +
    signals.sideEffects +
    (signals.changeFrequencyPerMonth >= 2 ? 1 : 0) +
    (signals.capabilities >= 3 ? 1 : 0);

  reasons.push(`运行时决策 ${signals.runtimeDecisions} 个`);
  reasons.push(`预期路径 ${signals.pathVariants} 条`);
  if (signals.humanSteps > 0) reasons.push(`人工节点 ${signals.humanSteps} 个`);
  if (signals.sideEffects > 0) reasons.push(`外部副作用 ${signals.sideEffects} 个`);
  if (signals.changeFrequencyPerMonth >= 2) {
    reasons.push(`每月变更 ${signals.changeFrequencyPerMonth} 次，需要配置化`);
  }

  let decision: WorkflowDecision;
  if (score > DECLARATIVE_MAX) {
    decision = "agent-loop";
    reasons.push(`结构分 ${score} 超过声明式上限 ${DECLARATIVE_MAX}`);
    controls.push("设置步数、花费与时限三重上限，并定义终止条件");
    controls.push("每一轮循环都必须可观测，禁止无界自省");
  } else if (score > FIXED_MAX) {
    decision = "declarative-orchestration";
    reasons.push(`结构分 ${score} 落在 (${FIXED_MAX}, ${DECLARATIVE_MAX}]，路径可声明`);
    controls.push("把阶段、条件与重试写成可版本化的声明");
    controls.push("每次路径变更跑一组固定回归样本");
  } else {
    decision = "fixed-flow";
    reasons.push(`结构分 ${score} 不超过 ${FIXED_MAX}，固定流程更易测试`);
  }

  if (signals.humanSteps > 0) {
    if (decision === "fixed-flow") decision = "declarative-orchestration";
    controls.push("人工节点设超时、升级路径与默认动作");
  }
  if (signals.sideEffects > 0) {
    controls.push("写动作前保留人工确认或可回滚检查点");
  }
  if (signals.changeFrequencyPerMonth >= 3) {
    controls.push("高频变更走配置开关，不直接改编排代码");
  }

  return { decision, score, reasons, controls };
}

/** 三条链的结构信号。数字来自链路定义，不是事后拟合的评分。 */
export const CHAIN_SIGNALS: Record<ChainId, ShapeSignals> = {
  A: {
    capabilities: 2,
    runtimeDecisions: 2,
    pathVariants: 4,
    humanSteps: 1,
    sideEffects: 1,
    changeFrequencyPerMonth: 2,
  },
  B: {
    capabilities: 2,
    runtimeDecisions: 2,
    pathVariants: 5,
    humanSteps: 0,
    sideEffects: 0,
    changeFrequencyPerMonth: 3,
  },
  C: {
    capabilities: 2,
    runtimeDecisions: 0,
    pathVariants: 1,
    humanSteps: 0,
    sideEffects: 1,
    changeFrequencyPerMonth: 1,
  },
};