迁移不是「把代码改完就上线」，而是「改完之后能证明没漏」。最常见的翻车是：字段名都换了，自测也跑通了，结果上线两周后有人在老接口分支里发现一处没改干净的 messages，或者日志里悄悄多了一串 choices 路径的兼容代码。这一节给一份可勾选的迁移清单，再用一组可离线跑的回归用例，证明两种写法在归一化后等价。

本节不复述 3.1 的字段对照表，只解决「怎么知道迁移完整」与「怎么防回归」两个问题。

一、问题不是「改没改完」，而是「怎么证明改完了」

迁移完成有两个标准：一是所有请求体都走新写法，二是所有解析层都配对。这两个条件都能用代码断言，不必靠人眼 review 历史分支。下面是迁移清单与回归 harness 的最小实现。

二、最小可运行示例：迁移清单与回归

下面的脚本不联网、不需要真实密钥。它用同一组对话意图分别走旧写法与新写法，断言归一化后等价；同时把「无法自动断言」的项单独列出来。

"""迁移回归：用同一组意图，分别走旧写法与新写法，断言归一化后等价。"""

def legacy_build(messages: list[dict]) -> dict:
    return {"model": "grok-4.7", "messages": messages}

def responses_build(history: list[dict]) -> dict:
    return {"model": "grok-4.7", "input": history}

def normalize(body: dict) -> dict:
    """两种写法都归一化到 input 数组，便于断言等价。"""
    if "messages" in body:
        return {"model": body["model"], "input": body["messages"]}
    return {"model": body["model"], "input": body["input"]}

CHECKLIST = [
    "请求体顶层用 input，不再有 messages",
    "答案从 output_text 取，不再走 choices",
    "端点切到 /v1/responses",
    "多轮历史在 stateless 模式本地维护，stateful 模式确认平台存历史",
    "加密推理内容不进日志",
]

def run_regression() -> None:
    cases = [
        [{"role": "user", "content": "解释上下文窗口"}],
        [{"role": "user", "content": "q1"}, {"role": "assistant", "content": "a1"}, {"role": "user", "content": "q2"}],
    ]
    for spec in cases:
        legacy = legacy_build(spec)
        new = responses_build(spec)
        assert normalize(legacy) == normalize(new), "归一化后不等价"
        assert "messages" not in new, "新版不应残留 messages"
    pending = [item for item in CHECKLIST if "stateful" in item or "日志" in item]
    print("回归通过：", len(cases), "组意图，两种写法归一化等价")
    print("仍需人工确认项：", pending)

if __name__ == "__main__":
    run_regression()

真正上线前，把 legacy_build 接到你代码里还能编译的旧分支上，让回归用例同时跑新旧两条路径；只要归一化结果一致，就说明迁移在结构上没有破坏对话语义。

三、迁移逐项清单（区分自动可验与人工确认）

清单项	能否自动断言	验证方式
请求体顶层用 input，不再有 messages	能	正则/键检查，如 normalize 后无 messages
答案从 output_text 取，不再走 choices	能	解析层断言取 output_text
端点切到 /v1/responses	能	配置断言，不出现旧端点常量
多轮历史在 stateless 本地维护 / stateful 确认平台存	部分	行为测试 + 平台侧确认
加密推理内容不进日志	部分	日志关卡单测 + 线上抽样

三件要强调的事：

• 清单不是给 PM 看的，是给 CI 看的。前三项能直接写成断言，放进流水线，每次提交都跑；后两项至少要有单测覆盖，不能只靠口头约定。
• 不要宣称旧端点已废弃。截至目前，Chat Completions 的废弃状态只见于第三方指南，官方页未在本次核验中直接确认；迁移是出于「统一到新写法、便于维护」的工程原因，不是因为旧端点明天就停。若沿用旧端点，请到官方页确认当前支持状态。
• 回归要覆盖多轮。单轮意图归一化等价很容易，多轮（含 assistant 历史）才容易漏——旧分支可能在拼 messages 时偷偷改了顺序或丢了角色，归一化后会立刻不等价。

四、预期输出与异常分支

运行回归 harness，预期输出：

回归通过： 2 组意图，两种写法归一化等价
仍需人工确认项： ['多轮历史在 stateless 模式本地维护，stateful 模式确认平台存历史', '加密推理内容不进日志']

换成真实流量灰度时，若出现异常，按下面顺序定位：

现象	优先怀疑	第一步动作
归一化断言失败	旧分支改写了历史	对比新旧 normalize 结果
线上仍出现 messages	某分支漏改	全仓搜 messages 调用点
日志出现加密 blob	日志关卡没接	在写盘前加 safe_log 过滤
灰度回退	新写法解析层未配对	先核对取答案属性

最后一行尤其重要：回归用例通过不代表可以立刻全量切流。前三项断言只证明「结构等价」，后两项（历史语义、日志合规）仍需灰度期观察。把「可以切流量」的条件写死，比凭感觉放量安全。

五、判据卡

判断项	该这么做	不该这么做
迁移验证	两类写法归一化后做等价断言	靠真实额度反复试错
清单落地	前三项写进 CI 每次跑	把清单当文档存着不执行
端点决策	出于维护原因统一新写法	照第三方说法写「旧端点已废弃」
切流条件	灰度达标再放量	回归过了就全量切
出错排查	先对比新旧 normalize	先回退或重发

这张卡的重点是把「证明改完」和「改完」分开。五类现象里「归一化失败」和「线上仍出现 messages」常常同源：某条历史分支没改干净，表现一个是测试红灯一个是线上残留，但修法都在全仓搜调用点。

六、来源与核验

• 官方 Quickstart：https://docs.x.ai/developers/quickstart（核验日期 2026-11-04）。client.responses.create、input、output_text 与 /v1/responses 写法均以该页为准。
• 官方 API 参考：https://docs.x.ai/developers/rest-api-reference。Chat Completions 端点的当前状态以官方页为准；本教程不在未确认时写「已废弃」。
• 多轮与加密推理内容处理见 3.2；价格、额度与区域可用性以控制台当前页面为准。

七、动手试

1. 给 run_regression() 加一个会失败的用例：故意在 legacy_build 里把 assistant 历史丢掉一轮，验证断言能抓到「归一化不等价」。想一想：这种丢失在灰度期靠什么指标最先暴露？
2. 把 CHECKLIST 扩成带「负责人 / 验证命令 / 通过标准」三列的表格，让每一项都能指派和复核，而不是一份纯勾选清单。
3. 设计一条「可以切流量」的发布门禁：列出至少三个必须同时满足的信号（例如回归绿、日志关卡单测绿、灰度错误率不升），并说明任意一个不满足时该怎么处理。