结构化输出 Harness：先挡住形状错误，再处理业务错误

{
  "order_id": "ORD-2026-9912",
  "items": [
    { "id": "item_001", "price": 99.9

import { z } from "zod";

export const OrderOutputSchema = z.object({
  order_id: z.string().min(1, "Order ID 不能为空"),
  items: z.array(
    z.object({
      id: z.string(),
      price: z.number().positive("价格必须为正数"),
    })
  ),
  total_price: z.number()
});

export type OrderOutput = z.infer<typeof OrderOutputSchema>;

{
  "order_id": "ORD-2026-9913",
  "items": [],
  "total_price": -50.0
}

async function validateBusinessRules(order: OrderOutput): Promise<{ isValid: boolean; reason?: string }> {
  // 1. 业务逻辑校验：商品列表不能为空
  if (order.items.length === 0) {
    return { isValid: false, reason: "商品列表不能为空，至少需包含一件商品" };
  }
  // 2. 状态一致性校验：核对总价
  const computedTotal = order.items.reduce((sum, item) => sum + item.price, 0);
  if (Math.abs(computedTotal - order.total_price) > 0.01) {
    return {
      isValid: false,
      reason: `总价计算不一致。模型标称总价 ${order.total_price}，但项目累加为 ${computedTotal}`
    };
  }
  return { isValid: true };
}

                     +------------------+
                     |  LLM 原始输出     |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     |  第一层：物理校验  | --- [物理失败] ---> [原地修复/重试机制]
                     +--------+---------+                     |
                              | (合格 JSON)                    v
                              v                        如果重试达到上限
                     +------------------+                     |
                     |  第二层：业务校验  | --- [业务失败]            |
                     +--------+---------+                      |
                              | (完全合格)                     |
                              v                                v
                     +------------------+            +------------------+
                     |   写入核心数据库  |            |  Quarantine 队列 |
                     +------------------+            +------------------+

npm install zod dotenv
npm install -D typescript @types/node

import { z } from "zod";

// ---- 1. 定义物理 Schema ----
export const OrderSchema = z.object({
  order_id: z.string().min(1, "Order ID 不能为空"),
  items: z.array(
    z.object({
      id: z.string(),
      price: z.number().positive("单价必须大于 0"),
    })
  ),
  total_price: z.number()
});

export type Order = z.infer<typeof OrderSchema>;

// ---- 2. 模拟 LLM 调用的物理/业务注入器 ----
// 用于在教学中模拟各种损坏的 LLM 原始输出
export type MockOutputType = "valid" | "shape_broken" | "business_broken";

class MockLLMService {
  private type: MockOutputType;
  constructor(type: MockOutputType) {
    this.type = type;
  }

  async generateOrderText(): Promise<string> {
    if (this.type === "shape_broken") {
      // 缺失闭合，物理形状破损的 JSON
      return `{
        "order_id": "ORD-2026-9901",
        "items": [
          { "id": "item_001", "price": 49.9`;
    } 
    if (this.type === "business_broken") {
      // 物理完全合格，但账目不平，业务严重不合理
      return JSON.stringify({
        order_id: "ORD-2026-9902",
        items: [
          { id: "item_101", price: 100.0 },
          { id: "item_102", price: 200.0 }
        ],
        total_price: 150.0 // 100 + 200 !== 150
      }, null, 2);
    }
    // 完全合法的输出
    return JSON.stringify({
      order_id: "ORD-2026-9903",
      items: [
        { id: "item_201", price: 10.0 },
        { id: "item_202", price: 15.5 }
      ],
      total_price: 25.5
    }, null, 2);
  }

  // 模拟原地修复调用
  async repairOrderText(brokenText: string, errorMessage: string): Promise<string> {
    console.log(`[Mock LLM] 收到物理修复请求。原损坏文本: "${brokenText.trim()}", 错误原因: "${errorMessage}"`);
    // 模拟修复成功：重新返回合法的物理 JSON
    return JSON.stringify({
      order_id: "ORD-2026-9901-REPAIRED",
      items: [{ id: "item_001", price: 49.9 }],
      total_price: 49.9
    }, null, 2);
  }
}

// ---- 3. 隔离队列模拟 ----
class QuarantineQueue {
  private queue: Array<{ payload: string; errors: string[]; stage: string; timestamp: Date }> = [];

  push(payload: string, errors: string[], stage: 'shape' | 'business') {
    const record = { payload, errors, stage, timestamp: new Date() };
    this.queue.push(record);
    console.error(`🚨 [Quarantine Queue] 已将可疑数据丢入隔离区！[阶段: ${stage.toUpperCase()}]`);
    console.error(`   - 原始 Payload: ${payload}`);
    console.error(`   - 拦截错误原因: ${errors.join(" | ")}`);
  }

  getRecords() {
    return this.queue;
  }
}

const quarantineQueue = new QuarantineQueue();

// ---- 4. 核心防御 Harness 管道 ----
export class OrderHarness {
  private llm: MockLLMService;
  private maxRetries = 2;

  constructor(outputType: MockOutputType) {
    this.llm = new MockLLMService(outputType);
  }

  // 处理物理形状拦截
  private parsePhysicalShape(rawText: string): { success: true; data: Order } | { success: false; error: string } {
    try {
      const parsed = JSON.parse(rawText);
      const validated = OrderSchema.safeParse(parsed);
      if (!validated.success) {
        const errMsg = validated.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
        return { success: false, error: `Schema 校验失败: ${errMsg}` };
      }
      return { success: true, data: validated.data };
    } catch (e: any) {
      return { success: false, error: `JSON 解析异常: ${e.message}` };
    }
  }

  // 处理业务规则拦截
  private validateBusiness(order: Order): { success: true } | { success: false; errors: string[] } {
    const errors: string[] = [];
    if (order.items.length === 0) {
      errors.push("商品列表为空，无法生成订单");
    }
    const totalSum = order.items.reduce((sum, item) => sum + item.price, 0);
    if (Math.abs(totalSum - order.total_price) > 0.01) {
      errors.push(`账目不一致：明细项累加值为 ${totalSum}，但模型返回总额为 ${order.total_price}`);
    }
    if (errors.length > 0) {
      return { success: false, errors };
    }
    return { success: true };
  }

  // 外部执行主入口
  async executeWorkflow(): Promise<Order | null> {
    let rawOutput = await this.llm.generateOrderText();
    let retryCount = 0;
    let currentError = "";

    // ---- 第一阶段：物理防御环 (含重试) ----
    while (retryCount <= this.maxRetries) {
      console.log(`[Harness 形状防御] 正在对输出结果进行物理审查... (尝试次数: ${retryCount + 1}/${this.maxRetries + 1})`);
      const shapeResult = this.parsePhysicalShape(rawOutput);

      if (shapeResult.success) {
        console.log("✅ [Harness 形状防御] 物理拦截通过。进入第二阶段校验...");
        
        // ---- 第二阶段：业务防御环 (直落隔离区，不执行原地修复) ----
        const businessResult = this.validateBusiness(shapeResult.data);
        if (businessResult.success) {
          console.log("🎉 [Harness 业务防御] 业务安全检查通过。数据已安全送达下游系统。");
          return shapeResult.data;
        } else {
          console.error("❌ [Harness 业务防御] 拒绝接收此数据：业务逻辑矛盾。正在将 Payload 流转至 Quarantine 队列...");
          quarantineQueue.push(rawOutput, businessResult.errors, "business");
          return null; // 中断链路，降级保护
        }
      }

      // 物理校验失败，记录当前错误
      currentError = shapeResult.error;
      console.warn(`⚠️ [Harness 形状防御] 物理检查被拦截：${currentError}`);

      if (retryCount < this.maxRetries) {
        retryCount++;
        console.log(`[Harness 自动恢复] 启动原地退避修复，准备向 LLM 投递修复反馈...`);
        rawOutput = await this.llm.repairOrderText(rawOutput, currentError);
      } else {
        break;
      }
    }

    // 达到重试上限依然无法修复物理形状，流转至隔离区并降级
    console.error("🚨 [Harness 严重错误] 达到物理修复上限，依然无法获取合法物理 JSON。注入隔离区...");
    quarantineQueue.push(rawOutput, [currentError], "shape");
    return null;
  }
}

import { OrderHarness } from "./orderHarness";

async function runTests() {
  console.log("=== 场景 A：物理形状破损 JSON，预期执行修复并成功通关 ===");
  const harnessA = new OrderHarness("shape_broken");
  const resA = await harnessA.executeWorkflow();
  console.log("最终产出:", resA ? "成功获取对象" : "失败（已被安全拦截）", "\n");

  console.log("=== 场景 B：合法 JSON 但业务数据矛盾，预期直接丢入 Quarantine 队列，无重试 ===");
  const harnessB = new OrderHarness("business_broken");
  const resB = await harnessB.executeWorkflow();
  console.log("最终产出:", resB ? "成功获取对象" : "失败（已被安全拦截）", "\n");

  console.log("=== 场景 C：黄金流程，完全合法的数据 ===");
  const harnessC = new OrderHarness("valid");
  const resC = await harnessC.executeWorkflow();
  console.log("最终产出:", resC ? "成功获取对象" : "失败（已被安全拦截）", "\n");
}

runTests();