《互联网产品的 AI 架构·多能力编排与任务闭环》5.2 部分可用的验收标准

// file: src/orch/partial.ts
// tier: L1
// verify: node --test test/orch/failure.test.ts

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

/** 字段有三种去向：原样交付、使用降级产物、缺失。 */
export type FieldState = "present" | "degraded" | "missing";

export interface FieldRule {
  name: string;
  required: boolean;
  /** 缺失时的处置：中止、接受降级替代、或直接省略。 */
  onMissing: "abort" | "degrade" | "omit";
  /** 给用户看的字段名，用于生成降级说明。 */
  label: string;
}

/** 一条链路的交付契约：哪些字段必须有，哪些可以缺。 */
export interface PartialContract {
  chainId: ChainId;
  fields: readonly FieldRule[];
}

export interface ProducedField {
  name: string;
  state: FieldState;
  /** 降级产物的来源，例如 template、cache、neighbor-chain。 */
  source?: string;
  /** 该字段自身的置信度，缺省时按 present=1、degraded=0.6 计。 */
  confidence?: number;
}

export interface PartialVerdict {
  chainId: ChainId;
  status: "complete" | "partial" | "rejected";
  /** 是否允许把这份结果交给用户或下游。 */
  deliverable: boolean;
  missingRequired: string[];
  missingOptional: string[];
  degraded: string[];
  delivered: string[];
  /** 用户可见标记：无、提示、横幅、阻断。 */
  notice: "none" | "notice" | "banner" | "block";
  /** 已交付字段占契约字段的比例，含降级交付。 */
  coverage: number;
  /** 按字段置信度求平均，缺失字段记 0。 */
  confidence: number;
  /** 可直接展示给用户的说明，不允许静默降级。 */
  message: string;
}

/** 「回声」三条链的交付契约：必须字段少而硬，可缺字段多而软。 */
export const ECHO_PARTIAL_CONTRACTS: Record<ChainId, PartialContract> = {
  A: {
    chainId: "A",
    fields: [
      { name: "summary", required: true, onMissing: "degrade", label: "摘要" },
      { name: "risk_level", required: true, onMissing: "abort", label: "风险等级" },
      { name: "key_points", required: false, onMissing: "omit", label: "要点" },
      { name: "risk_flags", required: false, onMissing: "omit", label: "风险标记" },
    ],
  },
  B: {
    chainId: "B",
    fields: [
      { name: "answer", required: true, onMissing: "abort", label: "答复" },
      { name: "citations", required: false, onMissing: "omit", label: "引用出处" },
      { name: "intent", required: false, onMissing: "omit", label: "意图" },
    ],
  },
  C: {
    chainId: "C",
    fields: [
      { name: "ranked_ids", required: true, onMissing: "abort", label: "排序结果" },
      { name: "answer", required: true, onMissing: "degrade", label: "推荐说明" },
      { name: "citations", required: false, onMissing: "omit", label: "引用出处" },
    ],
  },
};

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

function validate(contract: PartialContract, produced: readonly ProducedField[]): void {
  if (contract.fields.length === 0) fail(`${contract.chainId} 的契约不能为空`);
  const rules = new Set<string>();
  for (const rule of contract.fields) {
    if (rule.name.trim() === "") fail("字段名不能为空");
    if (rules.has(rule.name)) fail(`${contract.chainId} 重复声明字段 ${rule.name}`);
    rules.add(rule.name);
    if (rule.required && rule.onMissing === "omit") {
      fail(`${rule.name} 是必需字段，不能省略`);
    }
  }
  const seen = new Set<string>();
  for (const field of produced) {
    if (!rules.has(field.name)) fail(`${contract.chainId} 收到契约外字段 ${field.name}`);
    if (seen.has(field.name)) fail(`${contract.chainId} 重复产出字段 ${field.name}`);
    seen.add(field.name);
    if (field.confidence !== undefined && (!Number.isFinite(field.confidence) || field.confidence < 0 || field.confidence > 1)) {
      fail(`${field.name}.confidence 必须落在 [0, 1]`);
    }
  }
}

/**
 * 验收只看契约，不看上游「尽力了没有」：
 * 必需字段全在（含允许的降级替代）才可交付，否则直接拒绝。
 */
export function acceptPartial(
  contract: PartialContract,
  produced: readonly ProducedField[],
): PartialVerdict {
  validate(contract, produced);
  const byName = new Map(produced.map((field) => [field.name, field]));
  const missingRequired: string[] = [];
  const missingOptional: string[] = [];
  const degraded: string[] = [];
  const delivered: string[] = [];
  let confidenceSum = 0;

  for (const rule of contract.fields) {
    const field = byName.get(rule.name);
    const state: FieldState = field?.state ?? "missing";

    if (state === "present") {
      delivered.push(rule.name);
      confidenceSum += field?.confidence ?? 1;
      continue;
    }

    if (state === "degraded" && rule.onMissing === "degrade") {
      delivered.push(rule.name);
      degraded.push(rule.name);
      confidenceSum += field?.confidence ?? 0.6;
      continue;
    }

    if (rule.required) {
      missingRequired.push(rule.name);
      continue;
    }
    missingOptional.push(rule.name);
  }

  const status: PartialVerdict["status"] = missingRequired.length > 0
    ? "rejected"
    : degraded.length > 0
      ? "partial"
      : "complete";
  const notice: PartialVerdict["notice"] = status === "rejected"
    ? "block"
    : status === "partial"
      ? "banner"
      : missingOptional.length > 0
        ? "notice"
        : "none";
  const labels = new Map(contract.fields.map((rule) => [rule.name, rule.label]));

  return {
    chainId: contract.chainId,
    status,
    deliverable: status !== "rejected",
    missingRequired,
    missingOptional,
    degraded,
    delivered,
    notice,
    coverage: Number((delivered.length / contract.fields.length).toFixed(4)),
    confidence: Number((confidenceSum / contract.fields.length).toFixed(4)),
    message: buildMessage(status, labels, missingRequired, missingOptional, degraded),
  };
}

function buildMessage(
  status: PartialVerdict["status"],
  labels: Map<string, string>,
  missingRequired: readonly string[],
  missingOptional: readonly string[],
  degraded: readonly string[],
): string {
  const names = (items: readonly string[]): string =>
    items.map((name) => labels.get(name) ?? name).join("、");

  if (status === "rejected") {
    return `结果不可交付：缺少必需字段 ${names(missingRequired)}。`;
  }
  if (status === "partial") {
    return `部分结果可用：${names(degraded)}使用降级内容，已标注。`;
  }
  if (missingOptional.length > 0) {
    return `主结果完整，可选的${names(missingOptional)}暂缺。`;
  }
  return "结果完整，可直接使用。";
}