变更摘要

本 PR 为 Agent 推理引入 AgentHint 特性，允许客户端通过请求体中的 agent_hint 字段传递会话管理、KV 缓存控制和上下文编辑等提示信息。核心变更包括：新增 AgentHintInfo 等 Pydantic 数据模型用于解析和规范化客户端输入；新增 block_offset_translator 模块将消息级索引转换为 PagedAttention 块坐标；在请求验证、分发和调度链路中集成 agent_hint 的解析与块偏移附加逻辑，使调度器能够感知会话亲和性和上下文编辑意图。

主要改动

• 新增 agent_hint.py 数据模型模块：定义 AgentHintInfo、CacheControl、ContextEdit、ContextManagement 等 Pydantic 模型，以及 parse_agent_hint() 解析函数和 _resolve_session_ids() 会话 ID 规范化逻辑，支持从请求体与 HTTP 头中联合解析 session 标识
• 新增 block_offset_translator.py 块偏移转换模块：实现 BaseBlockOffsetCalculator 抽象基类及 Dsv4BlockOffsetCalculator / StandardBlockOffsetCalculator 两个模型族计算器，通过 attach_block_offsets() 将 CacheControl.msg_offset 和 ContextEdit.start/end 转换为 PagedAttention 的 block_offset、intra_block_offset、token_offset 坐标
• 修改请求验证逻辑以支持 session-targeted 编辑：在 inference_server.py 中新增 _has_session_target_edit() 辅助函数，将 _validate_openai_request 的空消息列表校验拆分为两种错误信息，允许存在 session 目标编辑时消息列表为空
• 在请求分发链路中集成 agent_hint 解析：在 dispatch.py 的 __create_request_info 中调用 ensure_minimum_messages_for_session_edits() 和 parse_agent_hint()，将解析结果注入 RequestInfo.agent_hint_info 字段
• 在调度策略中集成块偏移附加：在 kv_cache_affinity.py 的 KvCacheAffinityPolicy 中于消息编码后调用 attach_block_offsets()，并在 TokenizerManager 中暴露 is_dsv4 属性以支持 tokenizer 类型判定

代码审查

Now let me write the closing summary.

审查总结

审查覆盖范围

已逐一审查全部 6 个变更文件：

按优先级统计

• P0: 0
• P1: 0
• P2: 2
  • _has_session_target_edit 未检查 manage_request，导致校验绕过与消息注入逻辑不一致，可能让空 messages 到达下游 apply_chat_template 引发崩溃
  • block_offset_translator.py 中 compute_edit_block_offset 及 _prefix_diff_block_offset 缺少 block_size ≤ 0 防护，配置异常时 ZeroDivisionError
• P3: 4
  • _parse_cache_control 日志范围写错 ([0, n] 应为 [1, n])
  • 未使用的导入 model_validator 和 Self
  • _validate_openai_request 错误消息不准确 ("non-empty array" 实际仅检查非 list)
  • TokenizerManager.is_dsv4 属性无外部调用方，死代码

整体风险评估

该 PR 新增 1780 行代码实现 AgentHint 特性，整体代码质量较高，解析与校验逻辑健壮，边界处理较完善。发现的 2 个 P2 问题均为边界场景（manage_request 校验缺口、配置异常时的除零保护），触发概率较低但影响可达请求级崩溃，建议在合入前修复。P3 问题均为代码整洁性改进，不影响功能正确性。

💬 仅评论

/approve