《互联网产品的 AI 架构·模型接入与能力边界》7.1 结构化输出的契约与校验

// file: src/structured/schema.ts
// tier: L1
// verify: node --test test/structured/schema.test.ts

/** 只实现「回声」用得到的 JSON Schema 子集，避免引入第三方校验器。 */
export type SchemaNode =
  | {
      type: "object";
      properties: Record<string, SchemaNode>;
      required?: string[];
      additionalProperties?: boolean;
    }
  | { type: "array"; items: SchemaNode; minItems?: number; maxItems?: number }
  | { type: "string"; enum?: string[]; minLength?: number; maxLength?: number }
  | { type: "number"; minimum?: number; maximum?: number }
  | { type: "integer"; minimum?: number; maximum?: number }
  | { type: "boolean" }
  | { type: "null" };

export type IssueCode =
  | "type"
  | "required"
  | "enum"
  | "range"
  | "length"
  | "additional-property";

export interface SchemaIssue {
  /** 绝对路径，例如 $.order.id 或 $.items[0]。 */
  path: string;
  code: IssueCode;
  expected: string;
  actual: string;
}

export type FailureKind =
  | "json-syntax"
  | "wrong-type"
  | "missing-required"
  | "value-out-of-contract"
  | "unknown-field";

export interface FailureReport {
  stage: "json" | "schema";
  kinds: FailureKind[];
  issues: SchemaIssue[];
  message: string;
}

export type ParseResult =
  | { ok: true; value: unknown }
  | { ok: false; report: FailureReport };

const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function actualType(value: unknown): string {
  if (value === null) return "null";
  if (Array.isArray(value)) return "array";
  return typeof value;
}

/** 长度按 Unicode 码点计算，避免把 emoji 当成两个字符。 */
function codePointLength(value: string): number {
  return Array.from(value).length;
}

function childPath(base: string, key: string): string {
  return IDENTIFIER.test(key) ? `${base}.${key}` : `${base}[${JSON.stringify(key)}]`;
}

function compareText(a: string, b: string): number {
  if (a < b) return -1;
  if (a > b) return 1;
  return 0;
}

function collect(schema: SchemaNode, value: unknown, path: string): SchemaIssue[] {
  const issues: SchemaIssue[] = [];

  if (schema.type === "object") {
    if (!isRecord(value)) {
      return [{ path, code: "type", expected: "object", actual: actualType(value) }];
    }
    for (const key of schema.required ?? []) {
      if (!Object.prototype.hasOwnProperty.call(value, key)) {
        issues.push({
          path: childPath(path, key),
          code: "required",
          expected: "present",
          actual: "missing",
        });
      }
    }
    for (const key of Object.keys(value)) {
      const child = schema.properties[key];
      if (child === undefined) {
        if (schema.additionalProperties === false) {
          issues.push({
            path: childPath(path, key),
            code: "additional-property",
            expected: "defined property",
            actual: "unexpected",
          });
        }
        continue;
      }
      issues.push(...collect(child, value[key], childPath(path, key)));
    }
    return issues;
  }

  if (schema.type === "array") {
    if (!Array.isArray(value)) {
      return [{ path, code: "type", expected: "array", actual: actualType(value) }];
    }
    if (schema.minItems !== undefined && value.length < schema.minItems) {
      issues.push({
        path,
        code: "range",
        expected: `>= ${schema.minItems} items`,
        actual: String(value.length),
      });
    }
    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
      issues.push({
        path,
        code: "range",
        expected: `<= ${schema.maxItems} items`,
        actual: String(value.length),
      });
    }
    value.forEach((item, index) => {
      issues.push(...collect(schema.items, item, `${path}[${index}]`));
    });
    return issues;
  }

  if (schema.type === "string") {
    if (typeof value !== "string") {
      return [{ path, code: "type", expected: "string", actual: actualType(value) }];
    }
    if (schema.enum !== undefined && !schema.enum.includes(value)) {
      issues.push({
        path,
        code: "enum",
        expected: schema.enum.join("|"),
        actual: value,
      });
    }
    const length = codePointLength(value);
    if (schema.minLength !== undefined && length < schema.minLength) {
      issues.push({
        path,
        code: "length",
        expected: `>= ${schema.minLength} chars`,
        actual: String(length),
      });
    }
    if (schema.maxLength !== undefined && length > schema.maxLength) {
      issues.push({
        path,
        code: "length",
        expected: `<= ${schema.maxLength} chars`,
        actual: String(length),
      });
    }
    return issues;
  }

  if (schema.type === "integer" || schema.type === "number") {
    if (
      typeof value !== "number" ||
      !Number.isFinite(value) ||
      (schema.type === "integer" && !Number.isInteger(value))
    ) {
      return [{ path, code: "type", expected: schema.type, actual: actualType(value) }];
    }
    if (schema.minimum !== undefined && value < schema.minimum) {
      issues.push({
        path,
        code: "range",
        expected: `>= ${schema.minimum}`,
        actual: String(value),
      });
    }
    if (schema.maximum !== undefined && value > schema.maximum) {
      issues.push({
        path,
        code: "range",
        expected: `<= ${schema.maximum}`,
        actual: String(value),
      });
    }
    return issues;
  }

  if (schema.type === "boolean") {
    if (typeof value !== "boolean") {
      return [{ path, code: "type", expected: "boolean", actual: actualType(value) }];
    }
    return issues;
  }

  if (value !== null) {
    return [{ path, code: "type", expected: "null", actual: actualType(value) }];
  }
  return issues;
}

/** 校验入口：问题按路径与问题码排序，保证同一输入每次得到同一份报告。 */
export function validate(schema: SchemaNode, value: unknown): SchemaIssue[] {
  const issues = collect(schema, value, "$");
  issues.sort((a, b) => compareText(a.path, b.path) || compareText(a.code, b.code));
  return issues;
}

export function classifyIssue(issue: SchemaIssue): FailureKind {
  if (issue.code === "type") return "wrong-type";
  if (issue.code === "required") return "missing-required";
  if (issue.code === "additional-property") return "unknown-field";
  return "value-out-of-contract";
}

export function classifyIssues(issues: SchemaIssue[]): FailureKind[] {
  const kinds = new Set(issues.map(classifyIssue));
  return [...kinds].sort(compareText);
}

/** 类型错误通常意味着输出被截断或整体走形，重写比局部修复更划算。 */
export function isRepairableKind(kind: FailureKind): boolean {
  return kind !== "wrong-type";
}

function summarize(issues: SchemaIssue[]): string {
  return issues
    .map((issue) => `${issue.path} ${issue.code} expected=${issue.expected} actual=${issue.actual}`)
    .join("; ");
}

export function describeFailure(report: FailureReport): string {
  if (report.stage === "json") return `json syntax error: ${report.message}`;
  return summarize(report.issues);
}

export function parseStructured(schema: SchemaNode, text: string): ParseResult {
  let value: unknown;
  try {
    value = JSON.parse(text);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    return {
      ok: false,
      report: { stage: "json", kinds: ["json-syntax"], issues: [], message },
    };
  }
  const issues = validate(schema, value);
  if (issues.length > 0) {
    return {
      ok: false,
      report: {
        stage: "schema",
        kinds: classifyIssues(issues),
        issues,
        message: summarize(issues),
      },
    };
  }
  return { ok: true, value };
}

node --test test/structured/schema.test.ts

ℹ tests 12
ℹ suites 0
ℹ pass 12
ℹ fail 0
ℹ duration_ms 197.620083