第 61 章：输出的精确控制

// → src/my-agent/output-config.ts
interface OutputConfig {
  effort?: "low" | "medium" | "high" | "xhigh" | "max";
  format?: StructuredFormat;
}

const configs: Record<string, OutputConfig> = {
  quick:    { effort: "low" },      // 快速回答，token 最少
  balanced: { effort: "medium" },    // 性价比
  thorough: { effort: "high" },      // 默认，高质量
  extended: { effort: "xhigh" },     // 长期任务（Opus 4.7 专有）
  maximum:  { effort: "max" },       // 最强能力，token 最多
};

// → src/my-agent/output-config.ts
const MODEL_EFFORT_DEFAULTS: Record<string, OutputConfig> = {
  "claude-opus-4-7": {
    effort: "xhigh",   // 编码和 Agent 推荐的起步值
  },
  "claude-sonnet-4-6": {
    effort: "medium",  // 推荐默认值（Sonnet 4.6 的 high 较慢）
  },
  "claude-haiku-4-5": {
    effort: "low",     // Haiku 在低 effort 下最快
  },
};

// → src/my-agent/structured-output.ts
import type { OutputConfig } from "./types";

// 定义输出 Schema
const extractSchema: OutputConfig = {
  format: {
    type: "json_schema",
    schema: {
      type: "object",
      properties: {
        name: { type: "string", description: "人名" },
        age: { type: "integer", description: "年龄" },
        skills: {
          type: "array",
          items: { type: "string" },
          description: "技能列表",
        },
      },
      required: ["name", "age", "skills"],
      additionalProperties: false,
    },
  },
};

// 使用
const response = await client.createMessage({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  output_config: extractSchema,
  messages: [{
    role: "user",
    content: "张三，28岁，会 Python、TypeScript 和 Rust",
  }],
});

// response.content[0].text 一定是合法的 JSON
const person = JSON.parse(response.content[0].text);
// { name: "张三", age: 28, skills: ["Python", "TypeScript", "Rust"] }

// → src/my-agent/structured-output.ts
async function extractStructured<T>(
  client: ApiClient,
  prompt: string,
  schema: OutputConfig,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await client.createMessage({
      model: "claude-sonnet-4-6",
      max_tokens: 2048,
      output_config: schema,
      messages: [{ role: "user", content: prompt }],
    });

    try {
      const text = response.content.find(b => b.type === "text")?.text ?? "";
      return JSON.parse(text) as T;
    } catch {
      // JSON 解析失败（极少发生，但防范）
      if (attempt === maxRetries - 1) throw new Error("Structured output failed");
    }
  }
  throw new Error("Unreachable");
}

// → src/my-agent/sampling.ts
interface SamplingParams {
  temperature?: number;   // 0.0-1.0，默认 1.0
  top_p?: number;         // 核采样阈值
  top_k?: number;         // Top-K 采样
  stop_sequences?: string[];  // 遇到即停
}

// 确定性输出（代码生成、数据提取）
const deterministic: SamplingParams = {
  temperature: 0,
};

// 创造性输出（写作、头脑风暴）
const creative: SamplingParams = {
  temperature: 0.9,
  top_p: 0.95,
};

// 严格格式化输出
const precise: SamplingParams = {
  temperature: 0.1,
  stop_sequences: ["```", "\n\n\n"],
};

// → src/my-agent/output-controller.ts
export class OutputController {
  private config: Required<OutputConfig> & SamplingParams;

  constructor(options: {
    effort?: OutputConfig["effort"];
    schema?: object;
    temperature?: number;
    topP?: number;
  }) {
    this.config = {
      effort: options.effort ?? "high",
      temperature: options.temperature ?? 1.0,
      top_p: options.topP,
      top_k: undefined,
      stop_sequences: undefined,
    };
  }

  applyTo(params: MessageCreateParams): MessageCreateParams {
    return {
      ...params,
      output_config: {
        effort: this.config.effort,
        ...(this.config.schema ? {
          format: { type: "json_schema", schema: this.config.schema },
        } : {}),
      },
      temperature: this.config.temperature,
      top_p: this.config.top_p,
      top_k: this.config.top_k,
      stop_sequences: this.config.stop_sequences,
    };
  }

  // 预设模式
  static codeGeneration(): OutputController {
    return new OutputController({ effort: "high", temperature: 0 });
  }

  static extraction(): OutputController {
    return new OutputController({ effort: "low", temperature: 0 });
  }

  static creative(): OutputController {
    return new OutputController({ effort: "high", temperature: 0.9 });
  }
}