Schema-first AI 输出：让模型结果能被系统消费

// ❌ 只描述了成功情况
const ClassificationSchema = {
  type: 'object',
  properties: {
    category: { type: 'string', enum: ['tech', 'finance', 'health'] },
    confidence: { type: 'number', minimum: 0, maximum: 1 },
    tags: { type: 'array', items: { type: 'string' } }
  },
  required: ['category', 'confidence', 'tags']
}

// ✅ 成功和失败路径都在 schema 里
const ClassificationResult = z.object({
  status: z.enum(['success', 'uncertain', 'insufficient_input', 'refused']),
  // 只有 success 和 uncertain 时有分类结果
  category: z.enum(['tech', 'finance', 'health']).nullable(),
  confidence: z.number().min(0).max(1).nullable(),
  tags: z.array(z.string()).default([]),
  // 失败时给下游一个可操作的信号
  reason: z.string().optional(),
  // 是否需要人工复核
  needsReview: z.boolean().default(false)
})

// ❌ 直接改名，下游全部断裂
// v1: { tags: string[] }
// v2: { keywords: string[] }  // tags 没了
 
// ✅ 渐进式迁移
// v2: { tags: string[], keywords: string[] }  // 两个都有
// v3: { tags?: string[], keywords: string[] }  // tags 标 deprecated
// v4: { keywords: string[] }  // 大版本移除 tags

// ❌ 假设所有提供商都支持相同的 JSON Schema 特性
const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1, maxLength: 100 },
    score: { type: 'number', minimum: 0, maximum: 1 }
  }
}
 
// ✅ 取各提供商的交集，或在后处理中补充约束
const portableSchema = {
  type: 'object',
  properties: {
    // minLength/maxLength 在约束解码阶段不跨提供商保证
    // 放到 Zod/Pydantic 后处理里校验
    name: { type: 'string' },
    // minimum/maximum 同样，后处理兜底
    score: { type: 'number' }
  },
  required: ['name', 'score'],
  additionalProperties: false
}

// ❌ 只有成功路径，遇到异常下游只能猜
const ArticleSchema = z.object({
  title: z.string(),
  summary: z.string(),
  category: z.string()
})
// 模型拒答时返回 "I cannot classify this article"
// 下游 JSON.parse 直接报错，没有兜底逻辑
 
// ✅ 显式编码所有可能的输出状态
const ArticleResult = z.object({
  status: z.enum(['success', 'refused', 'insufficient_input']),
  title: z.string().nullable(),
  summary: z.string().nullable(),
  category: z.string().nullable(),
  // 失败时给下游可操作的解释
  reason: z.string().optional(),
  // 标记是否需要人工介入
  needsReview: z.boolean().default(false)
})
// 下游直接 switch(result.status) 路由
// 每种状态有明确的处理策略，不需要猜

// ❌ 普通 chat completion，靠 Prompt 要求 JSON 格式
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: '请返回 JSON 格式，包含 title 和 category 字段' },
    { role: 'user', content: articleText }
  ]
  // 模型可能返回 markdown 包裹的 JSON
  // 可能漏掉某个字段
  // 可能在 JSON 后面加一段解释文字
})
const data = JSON.parse(response.choices[0].message.content)
// 以上每一步都可能出错
 
// ✅ 使用 Structured Outputs，约束解码保证格式
const completion = await openai.chat.completions.parse({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: '按照 schema 提取文章信息' },
    { role: 'user', content: articleText }
  ],
  response_format: ArticleResult,  // 直接传入 Zod/Pydantic 模型
  // 约束解码保证：
  // 1. 输出一定是合法 JSON
  // 2. 一定包含 schema 定义的所有字段
  // 3. 字段类型一定匹配
})
const data = completion.choices[0].message.parsed
// 跳过 JSON.parse，直接拿到类型安全的对象

// ❌ 只相信约束解码，不做后处理
function processResult(data: ArticleResult) {
  // 直接用，假设一切正确
  await db.articles.create({
    category: data.category,
    confidence: data.confidence
  })
  // 问题：confidence 可能返回 1.5 或 -0.3
  // 约束解码保证它是 number，但不保证它在 0-1 之间
  // 因为某些提供商的约束解码不完全支持 minimum/maximum
}
 
// ✅ 约束解码 + Zod 后处理双重校验
function processResult(raw: unknown): ArticleResult {
  const result = ArticleResult.safeParse(raw)
  if (!result.success) {
    // 语义校验失败，记录错误并进入重试或降级
    logger.warn('Schema validation failed', {
      errors: result.error.issues,
      raw
    })
    throw new ValidationError(result.error.issues)
  }
  // 额外业务规则校验（超出 JSON Schema 表达能力）
  if (result.data.status === 'success' && result.data.confidence! < 0.3) {
    return { ...result.data, needsReview: true }
  }
  return result.data
}

// ❌ 无限重试，或者不重试
async function classify(text: string): Promise<ArticleResult> {
  const result = await callLLM(text)
  if (!isValid(result)) {
    return classify(text)  // 无限递归，没有退出条件
    // 或者完全不重试，直接返回可能错误的结果
  }
  return result
}
 
// ✅ 有限重试，把错误信息反馈给模型
async function classify(text: string, maxRetries = 2): Promise<ArticleResult> {
  let lastError: string | null = null
 
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const messages = buildMessages(text, lastError)
    const result = await callLLM(messages)
    const validation = ArticleResult.safeParse(result)
 
    if (validation.success) {
      return validation.data
    }
 
    // 把校验错误反馈给模型，让它修正
    lastError = formatValidationErrors(validation.error.issues)
    logger.info('Validation failed, retrying', {
      attempt: attempt + 1,
      errors: lastError
    })
  }
 
  // 超过重试上限，走降级路径
  return {
    status: 'insufficient_input',
    title: null,
    summary: null,
    category: null,
    reason: `Failed after ${maxRetries} retries`,
    needsReview: true
  }
}

// ❌ 格式要求全靠 Prompt 描述
const prompt = `
请分析以下文章并返回 JSON，格式如下：
{
  "category": 分类，必须是 tech/finance/health 之一,
  "confidence": 置信度，0到1之间,
  "reasoning": 分析过程,
  "tags": 标签列表
}
注意：必须返回合法 JSON，不要包含其他内容。
`
// 即使写了这么多要求，模型仍然可能输出 markdown 包裹的 JSON
// 或者把 confidence 写成 "high" 而不是数字
 
// ✅ 格式由 schema 保证，Prompt 只负责语义引导
const schema = z.object({
  reasoning: z.string().describe('先分析文章内容和关键信号，再给出分类结论'),
  category: z.enum(['tech', 'finance', 'health']).describe('文章的主分类，只能选一个'),
  confidence: z.number().min(0).max(1).describe('分类置信度，低于 0.5 表示不确定'),
  tags: z.array(z.string()).max(5).describe('最多 5 个关键词标签')
})
const prompt = '分析以下文章，按照 schema 提取分类信息。'
// 约束解码保证格式，Prompt 只引导语义