DeepTutor v1.0.1 版本解析：Visualize 可视化三阶段管线、出题去重、o 系列模型令牌参数修正与服务端日志治理

本篇基于 DeepTutor v1.0.1（2026-04-10 发布）的发布说明，逐一拆解该版本交付的四项能力：把自然语言描述转成 Chart.js/SVG 交互图表的 Visualize 可视化管线、题目生成去重的 previous_questions 机制、面向 o4-mini 等 o 系列模型的 max_completion_tokens 参数修正，以及服务端日志降噪改造，并结合当前仓库源码印证其实现位置与关键设计。

版本概览

v1.0.1 是一个以"能力扩展 + 工程修复"为主题的增量版本，发布说明原文见 ver1-0-1.md。四项核心变更可归纳为：

主题	变更内容	影响面
Visualize 能力	新增自然语言 → Chart.js/SVG 可视化，后端三阶段 Agent 管线 + 前端两个新组件	后端 deeptutor/agents/visualize，前端 web/components/visualize
出题去重	引入 previous_questions 参数并通过 MAX_PREVIOUS_QUESTIONS=20 限制提示词规模	出题 Agent 管线与 YAML 提示词模板
o 系列模型支持	扩展 o 系列正则以识别 o4-mini 及未来模型，正确下发 max_completion_tokens	LLM 配置层（关闭 #274）
服务端日志	抑制 uvicorn WebSocket 噪音日志、仅记录非 200 访问日志、MiniMax 模型覆写	服务运行与日志输出

Visualize 能力：自然语言到可视化代码的三阶段管线

v1.0.1 新增的 Visualize 能力将"用一句话描述一个图表"变成可渲染的交互可视化：用户输入自然语言数据描述，系统最终产出 Chart.js 配置或内联 SVG。整个后端由一条三阶段 Agent 管线承担——分析（analysis）→ 代码生成（code generation）→ 评审（review），并支持中/英双语提示词。

后端管线结构

管线编排入口是 VisualizePipeline，它实例化并串联三个 Agent：

• AnalysisAgent（analysis_agent.py）：解析用户输入与历史上下文，产出结构化分析结果；
• CodeGeneratorAgent（code_generator_agent.py）：基于分析结果生成可视化代码；
• ReviewAgent（review_agent.py）：对代码做评审与修复（run_repair 阶段可携带错误信息重新生成）。

从 pipeline.py 的三个方法签名可以看到各阶段的输入契约：run_analysis 接收 user_input、history_context、render_mode（默认 "auto"）及可选附件；run_code_generation 在原始输入之外额外注入 analysis；run_repair 则接收 code 与 error 做定向修复。

分析阶段的输出由 models.py 中的 VisualizationAnalysis 模型约束。其中 render_type 是一个 Literal 枚举，取值包括 svg、chartjs、mermaid、html、manim_video、manim_image，即模型被强制要求从有限的渲染形态中做选择，而不是自由发挥；chart_type、visual_elements、visual_genre 等字段进一步约束了代码生成阶段的风格路由（例如按用户意图动词而非主题名词区分 flowchart/stepper/chart 等子类型）。评审阶段输出 ReviewResult，包含 optimized_code、changed 与 review_notes 三个字段。

提示词按语言分目录存放：prompts/en 与 prompts/zh 各含 analysis_agent.yaml、code_generator_agent.yaml、review_agent.yaml 和总控 visualize.yaml，与发布说明中"bilingual prompt support (en/zh)"一致。

前端组件与接入位置

前端新增两个组件，位于 web/components/visualize：

• VisualizeConfigPanel（VisualizeConfigPanel.tsx）：可视化请求的配置面板；
• VisualizationViewer（VisualizationViewer.tsx）：渲染结果查看器，配套 svg-theme.css 为 SVG 提供主题样式。

这两个组件被接入工作区首页与聊天输入框，可从 web/app/(workspace)/home/[[...sessionId]]/page.tsx 等页面文件确认其引用关系。

出题去重：previous_questions 与 20 条上限

针对"连续出题时题目重复"的问题，v1.0.1 通过 Generator 管线引入了独立的 previous_questions 参数，与对话侧的 history_context 干净分离——历史对话用于理解语境，历史题目仅用于去重，二者不再混流。

在当前仓库的 question/pipeline.py 中可以看到该机制的落地：管线在组装提示词时将历史问答对通过 _render_previous_questions 渲染为独立段落（约 L850 处传入、L1759 起负责渲染，空历史时回退到 empty.no_previous_questions 文案）。发布说明还提到两点约束：

• MAX_PREVIOUS_QUESTIONS=20 上限：最多携带 20 条历史题目，保证提示词规模有界，避免长会话下提示词膨胀；
• 语言标签迁入 YAML 模板：语言相关的标签文本移入 prompts/en/pipeline.yaml 与 prompts/zh/pipeline.yaml，避免不同语言环境下的措辞混杂。

o4-mini 与未来 o 系列模型支持

OpenAI 的 o 系列推理模型不接受传统 max_tokens 参数，而要求 max_completion_tokens。v1.0.1 扩展了 LLM 配置层的 o 系列正则，使 o4-mini 及未来 o 系列模型标识都能被正确识别（关闭 #274）。

当前仓库的实现位于 config.py：uses_max_completion_tokens 按小写化后的模型名匹配一组模式，其中 r"^o\d" 明确覆盖 o1、o3、o4-mini、o4 及后续 o 系列；gpt-4o、gpt-[5-9]、gpt-\d{2,} 也在覆盖范围内。匹配命中后，get_token_limit_kwargs 将令牌限额下发为 {"max_completion_tokens": value}，否则回退为 {"max_tokens": value}。这种"按模型名路由令牌参数"的设计保证了新增 o 系列模型时无需逐一点名、只靠前缀正则即可向前兼容。

服务端日志改进

v1.0.1 对服务端日志做了三项治理：

1. 抑制 uvicorn WebSocket 噪音：高频的 WebSocket 连接/断开日志会刷屏，本版本将其静默；
2. 选择性 HTTP 访问日志：新增仅记录非 200 响应的访问日志中间件，降噪的同时保留可操作的错误可见性；
3. MiniMax 模型覆写：为不支持结构化输出的提供方添加 supports_response_format: false 覆写，避免对这类模型下发 response_format 引发 400 错误。

第 3 项在当前仓库 capabilities.py 中有对应结构：各提供方默认能力表与 MODEL_OVERRIDES 中均包含 minimax 条目，覆写表按模式最长优先匹配生效。

社区贡献

v1.0.1 包含两项社区贡献：

• @kuishou68：o4-mini 与未来 o 系列模型的正则修复（PR #275，关闭 #274）；
• @Leadernelson：出题重复问题的初始修复（PR #281）。

小结

v1.0.1 的四个变更点分别落在可视化生成管线（deeptutor/agents/visualize）、出题去重（deeptutor/agents/question）、LLM 令牌参数路由（deeptutor/services/llm/config.py）与服务端日志治理上。若想深入验证，可对照 VisualizePipeline 的阶段契约、question 管线 的历史题目渲染逻辑，以及 uses_max_completion_tokens 的正则匹配实现逐一溯源。