执行摘要

• 一句话：修复 Harmony 解析器将约束标记误解析为收件人
• 推荐动作：值得阅读。该 PR 展示了如何在第三方解析器边界进行精确的输入归一化，以弥补上游库的解析缺陷，而不改变库本身。设计思路（静态方法、在三个出口注入）值得借鉴；review 过程中的讨论也显示了良好的设计权衡意识。对于维护 Responses API 或 GPT-OSS 工具链的开发者来说，属于精读范围。

功能与动机

Issue #45570 报告：GPT-OSS Harmony 最终消息中独立的约束内容类型标记 <|constrain|>json 被旧版 openai-harmony 误解析为收件人，导致 vLLM Responses API 将最终输出错误地转化为 MCP 调用（McpCall），而非预期的 ResponseOutputMessage。本 PR 在共享的 HarmonyParser 层修复此问题，覆盖 Chat Completions 和未来统一的 Responses 路径。

实现拆解

1. 新增归一化方法：在 vllm/parser/harmony.py 的 HarmonyParser 类中添加 _normalize_recipient 静态方法。该方法检查收件人字符串是否包含 <|constrain|> 子串：若包含，则提取该子串之前的部分（去除尾部空白），若其为空则返回 None；否则返回原值。

2. 三个收件人出口注入归一化：

   • _poll_completed_message：对从 harmony_parser.messages 获取的已完成消息的 recipient 字段进行归一化。
   • parse_delta：对 harmony_parser.current_recipient 的初始值进行归一化，用于流式 delta 中的收件人追踪。
   • process_chunk：对每次处理 token 后的 harmony_parser.current_recipient 进行归一化，确保段级别的收件人正确。

3. 测试配套：在 tests/parser/test_harmony.py 的 TestProcessChunk 类中添加 test_constrained_output_segment_recipient_normalized 测试用例，验证：

   • 段内容、收件人归一化为 None、组装文本正确；
   • 完成消息的收件人也为 None。

4. 覆盖所有语义路径：归一化覆盖了已完成消息、逐段 delta 和实时流式段，确保非流式和流式场景均正确。

关键文件：

• vllm/parser/harmony.py（模块 Harmony解析器；类别 source；类型 core-logic；符号 _normalize_recipient）: 核心变更文件：新增 _normalize_recipient 方法，并在三个关键点（_poll_completed_message、parse_delta、process_chunk）注入归一化逻辑，修复约束标记误解析为收件人的问题。
• tests/parser/test_harmony.py（模块 测试；类别 test；类型 test-coverage；符号 test_constrained_output_segment_recipient_normalized）: 新增测试用例 test_constrained_output_segment_recipient_normalized，验证段收件人和完成消息收件人均被归一化为 None，覆盖典型 bug 场景。

关键符号：_normalize_recipient

关键源码片段

tests/parser/test_harmony.py

新增测试用例 test_constrained_output_segment_recipient_normalized，验证段收件人和完成消息收件人均被归一化为 None，覆盖典型 bug 场景。

# tests/parser/test_harmony.py - TestProcessChunk 类中的测试
​
def test_constrained_output_segment_recipient_normalized(self, harmony_parser):
    """验证约束输出段的收件人被归一化为 None"""
    result = harmony_parser.process_chunk(
        encode_output(
            '<|channel|>final <|constrain|>json<|message|>{"result":true}<|end|>'
        )
    )
​
    # 检查非边界段（有 delta 内容的段）
    content_segments = [segment for segment in result.segments if segment.delta]
    # 通道应为 "final"
    assert all(segment.channel == "final" for segment in content_segments)
    # 收件人必须为 None，避免被误判为工具调用
    assert all(segment.recipient is None for segment in content_segments)
    # 最终内容应与期望一致
    assert (
        "".join(segment.delta for segment in content_segments) == '{"result":true}'
    )
​
    # 检查已完成消息（边界段）的收件人
    completed_messages = [
        segment.completed_message
        for segment in result.segments
        if segment.completed_message is not None
    ]
    assert len(completed_messages) == 1
    # 完成消息的收件人也应为 None
    assert completed_messages[0].recipient is None

评论区精华

Review 中有两项关键讨论：

1. 归一化策略（yzong-rh 提出）：最初实现只检查收件人是否以 <|constrain|> 开头，但 yzong-rh 指出应处理收件人末尾附着约束标记的情况（如 to=function.foo <|constrain|>...）。作者将实现改为使用 find 和 rstrip，保留函数名等合法前缀。

2. 覆盖范围（bbrowning 提出）：bbrowning 指出该修复无法解决约束标记完全占据收件人字段（如 commentary <|constrain|>functions.get_weather）的通用问题，但同意这是超出原始意图的更为通用的场景，因此认可本次更窄范围的修复。

最终两位 reviewer 均批准，yzong-rh 明确表示 LGTM，bbrowning 认可其对 #45570 的修复价值。

• 归一化策略：仅丢弃整个收件人还是截断 <|constrain|> 之前的部分？ (design): 使用 find 定位 <|constrain|>，保留其前面的部分（去除尾部空白），若为空则返回 None。
• 是否应覆盖已完成消息的收件人归一化？ (correctness): 在 _poll_commented_message 中对 msg.recipient 进行归一化，确保所有消费场景一致。
• 修复能否覆盖更通用的约束标记泄漏场景？ (other): 本次修复是针对 final 通道中独立约束标记的定向修复；更通用的工具调用场景留待后续（如上游 oss-harmony 库的改进）。

风险与影响

• 风险：
  1. 回归风险（低）：_normalize_recipient 仅在显式添加的调用点生效，对正常合法收件人（如 to=function.name）无影响；若收件人意外包含 <|constrain|> 子串（极罕见），会错误截断。但从历史 vLLM 收件人格式看，此类包含几乎不可能发生。
  2. 兼容风险（低）：仅修改 HarmonyParser 内部逻辑，对外接口 parse / parse_delta 返回的 recipient 字段可能由原 '<|constrain|>json' 变为 None，下游 consumer（Responses API 等）需适应此变化。
  3. 性能风险（无）：字符串 find 操作时间复杂度 O(n)，收件人通常很短，对整体吞吐无影响。
  4. 测试覆盖：新增测试覆盖了典型的 <|constrain|>json 场景，但未覆盖 to=function.foo <|constrain|>... 的混合场景。
• 影响：
  1. 用户影响：当使用 openai-harmony 版本 <0.0.8 时，GPT-OSS Responses API 的约束输出将正确显示为内容而非 MCP 调用；Chat Completions 也可能受益于同一修复。
  2. 系统影响：仅影响 HarmonyParser 类，不影响其他解析器（如 ToolParser、ReasoningParser）。
  3. 团队影响：低。代码变更量小（+39/-2），逻辑清晰，review 流程规范。
  4. 影响程度：中等。修复一个实际生产 Bug，确保约束输出不被误分类，提升 GPT-OSS 用户体验。
     - 风险标记：第三方依赖行为, 下游消费者需适配

关联脉络

• PR #45571 [Bugfix][Frontend] Normalize constrained Harmony recipients in Responses API: 关联 Issue #45570 的另一个修复 PR，针对 Responses API 特定路径的约束标记处理；本 PR 则是共享 HarmonyParser 层的更通用修复。
• PR #35906 Responses API sanitization and malformed-control-token recovery: PR body 中提及的更大范围的 Responses API 清理提案，本 PR 是其中一部分的前置步骤。