GeminiInteractionsAPI写作流程怎么从outputs迁移到steps

迁移影响范围

Gemini API 更新记录指出，Interactions API 的请求和响应结构会从 outputs 转为 steps，旧结构会被移除。对写作自动化而言，风险通常不只在正文读取，还可能出现在任务状态、日志、失败重试和发布前校验。

• 搜索代码、工作流配置和数据库映射中所有 outputs 引用。
• 列出每个引用的用途：取正文、取结构化字段、记录状态，或保留原始响应。
• 准备一组已验证的标题、提纲、正文和异常样本，作为迁移前后的对照数据。
• 确认当前接入版本及官方迁移说明，避免按猜测拼接 steps 内部内容。

结果适配层

不要让编辑器、发布器和统计任务分别直接读取 API 响应。先在接口边界把响应转换为系统内部统一对象，例如 article_text、task_status、raw_response 和 parse_error。这样后续业务代码只依赖内部字段。

1. 在单独的解析函数中接收完整响应。
2. 按当前规范从 steps 提取系统真正需要的内容，并保留原始响应供排查。
3. 解析失败时返回明确错误，不要用空正文代替成功结果。
4. 为内部对象标记解析版本，便于区分历史记录和新记录。
5. 发布服务只读取统一对象中的已校验正文，不直接访问 API 响应。

function normalizeWritingResult(response) {
  const result = {
    article_text: "",
    task_status: "pending_review",
    raw_response: response,
    parse_error: null
  };

  try {
    result.article_text = extractTextFromSteps(response.steps);
    result.task_status = result.article_text ? "generated" : "parse_failed";
  } catch (error) {
    result.task_status = "parse_failed";
    result.parse_error = String(error);
  }

  return result;
}

示例中的 extractTextFromSteps 需要依据你使用的官方迁移说明实现。资料包只确认字段迁移方向，没有提供 steps 的完整嵌套字段定义，因此不应把未经确认的路径写死。

样本验证链路

以“为新产品写一篇包含标题、摘要和正文的文章”为固定样本。迁移后，请求一次生成任务，将响应先送入适配层，再把统一对象写入草稿表。

1. 记录任务 ID、输入版本、调用时间和原始响应。
2. 检查 article_text 是否包含预期正文，而不是空字符串或调试内容。
3. 检查任务状态是否为 generated，解析失败应进入人工处理队列。
4. 让编辑器从草稿表读取正文，确认页面展示正常。
5. 通过发布校验后再进入发布队列。

模型或接口调整后的固定样本对比方法，也可参考Gemini API 模型更新后写作结果怎么做回归测试。

故障排查

• 故障：请求成功但正文为空。原因：业务代码仍读取 outputs，或 steps 解析路径与实际响应不符。修正：记录完整响应，核对官方迁移说明，在适配层更新提取逻辑，并让空正文返回 parse_failed。
• 故障：任务被标记完成却无法发布。原因：状态记录与正文解析分散处理，成功状态先于内容校验写入。修正：仅在统一对象通过正文校验后写入 generated，发布端额外拒绝空正文。
• 故障：历史任务重放失败。原因：新解析器把历史 outputs 响应当作 steps 响应处理。修正：按响应保存时间或解析版本选择对应解析器，并保留历史原始响应。
• 故障：同一文章出现重复草稿。原因：解析失败后直接重试整个发布流程。修正：以任务 ID 或内部幂等键去重，先修复解析，再决定是否重新生成。

发布验收

• 所有生产调用点均不再依赖 outputs。
• steps 响应能够转换为统一的正文和状态字段。
• 标题、摘要、正文和结构化字段的固定样本均通过对照。
• 空正文、未知响应和解析异常不会进入发布队列。
• 原始响应、解析版本和错误信息可供后续追溯。
• 历史记录与新记录都能在编辑器中正常打开。
• 灰度任务稳定后，再将新解析逻辑用于全量写作任务。