DeepTutor v1.2.1 版本深度解析Chat 分阶段 Token 配额可配置化与 Regenerate 响应再生成机制【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutorv1.2.1发布于 2026.04.21是 DeepTutor agentic chat 管线走向“一等配置公民”的里程碑版本一方面把此前硬编码在代码里的聊天各阶段 Token 预算提升为agents.yaml中的capabilities.chat可调参数让长回答不再被中途截断另一方面实现了跨 CLI、WebSocket、Web UI 三端一致的“重新生成上一条回答”Regenerate完整流程并修复了暗色代码块可读性、None向量崩溃向量检索、Gemma 本地模型拒绝json_object三个真实缺陷。本文以该版本的 Release Notes 为骨架结合仓库源码deeptutor/、deeptutor_cli/、web/、tests/逐项还原其设计与实现细节。一、版本背景与能力总览v1.2.1 是一次“对话体验 健壮性”双轮驱动的发布核心变化集中在三块能力/修复编号一句话概述Chat 分阶段 Token 配额与温度可配置#348agentic chat 管线接入capabilities.chat配置深度合并默认值Regenerate 上一条回答三端统一#349CLI/regenerate、WebSocketregenerate消息、Web UI 按钮暗色代码块在亮色主题下不可读#352提高 CSS 优先级代码块文本固定为可读色None向量导致 LlamaIndex 崩溃#347嵌入响应解析与批量结果校验双层防护Gemma 模型被本地服务拒绝json_object#345关闭 Gemma 的response_format支持声明整个版本净新增约575 行测试覆盖了配置解析、再生成拒绝路径、模型能力覆盖与嵌入回归路径。二、capabilities.chat把聊天 Token 预算从硬编码升级为一等配置2.1 解决什么问题在 v1.2.1 之前agentic chat 管线中“正式作答”responding与“直接回答”answer_now两个阶段的预算被硬编码为1800token。当模型生成长回答时输出会在句子中间被强制截断体验很差。v1.2.1 把预算上限直接提升到8000并把整条管线变成了可配置的“一等公民”。2.2 配置入口agents.yaml的capabilities.chat块新增的配置块位于运行时设置目录下的agents.yaml该文件与main.yaml一同由deeptutor/services/config/capabilities_settings.py桥接作为/api/v1/capabilities/settings接口的数据源。结构示意如下capabilities: chat: temperature: 0.2 # 全循环共享的温度 max_rounds: 8 # 探索循环内单轮最大 LLM 轮数 responding: max_tokens: 8000 # 正式作答阶段预算原 1800 → 8000 answer_now: max_tokens: 8000 # 直接回答阶段预算同上 thinking: max_tokens: stage_budget observing: max_tokens: stage_budget acting: max_tokens: stage_budget react_fallback: max_tokens: stage_budgetv1.2.1 引入的配置面包含两类键依据 ver1-2-1 发布说明共享标量temperature整个 chat 循环共用一个温度值分阶段预算max_tokens按responding、answer_now、thinking、observing、acting、react_fallback六个 stage 分别设置。2.3 深度合并与默认值兜底配置读取的核心实现在deeptutor/services/config/loader.py。该文件先声明了内建默认值常量DEFAULT_CHAT_PARAMSDEFAULT_CHAT_PARAMS: dict[str, Any] { temperature: 0.2, max_rounds: 8, # 无工具调用的一轮会提前结束循环正常出口 exploring: {max_tokens: 1600}, responding: {max_tokens: 8000}, }随后get_chat_params()从agents.yaml读取capabilities.chat用known_keys过滤掉 targeting 旧版 schema 遗留下的键如max_iterations、max_explore_rounds等再调用_deep_merge(DEFAULT_CHAT_PARAMS, filtered_cfg)做深度合并。因此调用方可以不带任何空值判断直接索引每个 stage 键——这正是“已有安装无需改动 YAML 也能继续工作”的兼容性来源。读者也可以对比deeptutor/services/setup/init.py中初始化时写入的DEFAULT_AGENTS_SETTINGS其中 chat 块的出厂值为temperature: 0.2responding.max_tokens: 8000与 loader 兜底默认保持一致。值得说明的是当前仓库快照中的默认值结构已演进为exploring/responding两个子树的形态说明 v1.2.1 之后 stage 模型又经过了一轮整合如引入统一的 exploring 循环但 loader 的“深度合并 键过滤 默认值兜底”机制保持不变。2.4 兼容旧配置形态_ChatLimits.from_config的强制收敛为了让形形色色的历史配置缺失键、把 dict 写成标量、只覆盖部分 stage都能稳定工作发布说明记载了内部类型_ChatLimits.from_config它会把所有历史形态统一强制收敛coerce为一个稳定的 dataclass。当前代码中对应的韧性读取逻辑体现在deeptutor/agents/chat/agentic_pipeline.py管线构造时通过get_chat_params()加载配置加载失败则记录 warning 并回退空 dict随后用float(chat_cfg.get(temperature, 0.2))解析温度TypeError/ValueError时回退 0.2再用辅助函数_read_int(cfg, keymax_tokens, default...)逐段读取各 stage 预算。_read_int的容错语义可从 测试用例 中反推出来空 dict /None/ 非 dict 输入 → 回退默认值{max_tokens: 5000}→ 正常解析出 5000{max_tokens: 5000}字符串数字→ 强制转成 5000{max_tokens: abc}垃圾值→ 回退默认值。2.5 配套测试新增 10 条单测集中在tests/services/config/test_chat_params_config.py覆盖三个维度发布说明原文代码路径可在仓库中对应到 测试文件loader 解析无配置文件时返回DEFAULT_CHAT_PARAMS的完整默认含exploring1600、responding8000、temperature0.2深度合并优先级只覆盖单个 stage如只改temperature时其余 stage 仍保持默认8000dataclass 强制收敛上述_read_int对空值、字符串数字、垃圾值的回退与解析行为。三、Regenerate跨 CLI / WebSocket / Web UI 的“原地重跑上一条回答”3.1 功能语义“Regenerate”不再是前端简单地重发一遍消息而是一条**在原始用户消息位置上原地重跑in place**的真实后端流程先删除末尾那条 assistant 回答再以同一会话偏好重新触发一次 turn最终保证用户消息行不会重复_persist_user_messageFalse长期记忆刷新不会二次执行跳过memory_service.refresh_from_turn原始用户消息与其附件、引用等上下文保持不变。3.2 三个入口的使用方式CLI在deeptutor chatREPL 中输入/regenerate别名/retry详见deeptutor_cli/chat.py的命令分发与命令帮助文本命令表也记录在 CLI README。底层由deeptutor_cli/common.py的regenerate_and_render调用app.regenerate_last_turn(session_id)并对两种可预期拒绝分别给出友好提示“有别的 turn 在跑” / “还没有可重跑的消息”。WebSocket向/api/v1/ws发送type: regenerate消息可选携带overrides字段可覆盖capability、tools、knowledge_bases、language、config协议级描述可见deeptutor/api/routers/unified_ws.py的模块 docstring。后端拒绝时返回结构化错误码regenerate_busy或nothing_to_regenerate而非静默失败。Web UI对 chat-capability 的回复在最后一条 assistant turn 上提供 per-message 的 Regenerate 按钮RefreshCcw图标实现在web/components/chat/home/ChatMessages.tsx由onRegenerateMessage()触发最终汇入web/app/(workspace)/home/[[...sessionId]]/page.tsx中的regenerateLastMessage。3.3 后端主流程TurnRuntimeManager.regenerate_last_turn核心实现在deeptutor/services/session/turn_runtime.py流程可分五步理解前置检查校验 session 存在、没有活跃中的 turn否则抛regenerate_busy、存在历史上的 user 消息否则抛nothing_to_regenerate定位尾部 assistantget_last_message(session_id)取最新一条消息若它是 assistant 角色则从其events中反向找出上一轮turn_id_superseded_turn_id供前端做 superseded 标记随后delete_message删除该条——这一步依赖新增的会话存储助手方法SQLiteSessionStore.delete_message/get_last_messagedeeptutor/services/session/sqlite_store.pyPocketBase 后端也有等价实现deeptutor/services/session/pocketbase_store.py抽象方法声明于deeptutor/services/session/protocol.py还原请求上下文从原始 user 消息的metadata.request_snapshot或requestSnapshot中取出附带的llm_selection、book_references等快照作为重跑的默认上下文overrides 归并capability、tools、knowledge_bases、language、notebook_references、history_references优先取overrides否则回落到会话preferences再回落到原 user 消息以去重配置重启 turn向start_turn(payload)注入config._persist_user_messageFalse、config._regenerateTrue、config._regenerated_from_message_iduser 消息 id保证用户行不重复、记忆刷新不二次执行——facade 层透出该能力供各入口调用deeptutor/app/facade.py。此外v1.2.1 还给_stage_responding的 LLM 调用增加了空响应诊断当模型返回空内容时抛出结构化 warning而不是让前端拿到一段空回答。3.4 UI 打磨i18n 键与乐观回滚保护为了让新按钮融入既有聊天 UIv1.2.1 做了两处跟随调整国际化在 web/locales 的{en,zh}/app.json中新增Regenerate/重新生成键并将ChatMessages.tsx里原先硬编码的Regenerate字符串改为t(Regenerate)与同行的t(Copy)模式对齐乐观弹回Optimistic-pop rollback当服务端在前置检查阶段拒绝 regenerateregenerate_busy/nothing_to_regenerate时前端此前乐观执行的POP_LAST_ASSISTANTSTREAM_START占位会被新的RESTORE_ASSISTANTreducer action 还原——被弹出的消息保存在按会话 key 区分的pendingRegenerateRef中并在done或任何终态结果到达时清空从而保证对话记录永远不会悄然丢失用户的最后一条回答。3.5 测试契约18 条tests/services/session/test_regenerate.py测试文件覆盖三条拒绝路径regenerate_busy另一 turn 运行中、nothing_to_regenerate无 session / 无 user 消息删除后重启delete-then-restart的完整流程记忆刷新跳过契约memory-refresh-skip端到端“用户消息不重复”契约WebSocket 往返round-trip验证。四、Bug 修复详解4.1 #352暗色代码块在亮色主题下不可读根因链.prose pre强制了浅色背景#D6D3D1.prose code:not(.md-code-block__code):not(.md-inline-code)又把文字颜色覆盖为var(--foreground)亮色主题下接近黑色叠加代码中硬编码的#1f2937/#292524深色背景形成“黑字压黑底”。修复方案感谢DarkGenius分两层新增更高特异度的.md-renderer .md-code-block { ,pre,code }规则把代码块文本颜色固定为#e5e7eb不随主题变化给RichMarkdownRenderer与SimpleMarkdownRenderer兜底路径里的code元素补上已有的md-code-block__code类使:not()守卫生效。4.2 #347None向量导致 LlamaIndex 管线崩溃根因嵌入服务对某个 chunk 返回null向量后None被放进向量索引相似度计算时在np.dot(NoneType)处崩溃。两层修复感谢kagura-agent解析层_extract_embeddings_from_response改用or []而非get(key, default)从而捕获显式None值对应实现位于 deeptutor/services/embedding 下的 OpenAI 兼容适配器中模型层CustomEmbedding._get_text_embeddings在批量结果中逐个校验任一槽位为None就替换为零向量。CustomEmbedding是 DeepTutor 的 LlamaIndex 嵌入适配器定义于deeptutor/services/rag/pipelines/llamaindex/embedding_adapter.py。配套回归测试位于tests/services/embedding/test_extract_embeddings.py测试文件。4.3 #345Gemma 模型被本地服务拒绝json_object根因经 LM Studio 等本地 OpenAI 兼容服务托管的 Gemma在收到response_format{type: json_object}时会返回400 response_format.type must be json_schema or text。修复感谢octo-patch在模型能力覆盖表中为既有gemma条目增加supports_response_format: False当前仓库对应项为deeptutor/services/llm/capabilities.py中gemma: {supports_vision: False, supports_response_format: False}使 json_object 路径被跳过。由于 visualize 与 math-animator agent 中的extract_json_object工具本就支持从纯文本解析 JSON所有调用方无需额外改动即可继续工作。capabilities.py 还提供了运行时熔断能力当某个 provider 意外在运行期拒绝response_format时可动态把该模型标记为不支持后续调用直接返回False而不重复尝试见该文件的supports_response_format运行时说明。五、测试套件与社区贡献盘点5.1 测试净增分布575 行测试主题用例数对应文件chat 参数 loader /_ChatLimits强制收敛10tests/services/config/test_chat_params_config.pyregenerate 全流程3 条拒绝路径、原地删除重启、记忆跳过、去重契约、WS 往返18tests/services/session/test_regenerate.pysupports_response_format模型覆盖14tests/services/llm/test_capabilities.pyNone嵌入提取回归1tests/services/embedding/test_extract_embeddings.py5.2 社区贡献名单贡献者贡献内容DarkGenius通过agents.yaml使 chat 分阶段 Token 配额可配置#348CLI / WebSocket / Web UI 三端 Regenerate#349暗色代码块在亮色主题下的可读性修复#352kagura-agentLlamaIndex 管线中对None嵌入的防护#347octo-patch为 Gemma 模型关闭json_objectresponse_format#345六、小结与演进线索回看 v1.2.1三条技术主线值得在后续版本中持续跟踪配置化推进capabilities.chat只是 DeepTutor 把各能力 LLM 参数收敛进agents.yaml的一环——solve、research、question、co_writer、visualize及plugins.vision_solver、math_animator均拥有各自的temperature/max_tokens出厂默认见deeptutor/services/setup/init.py的DEFAULT_AGENTS_SETTINGS并在前端/api/v1/capabilities/settings中统一呈现三端一致的交互语义Regenerate 证明了一条“CLI REPL、WebSocket 协议、Web UI 按钮共享同一后端状态机”的实现路径其_superseded_turn_id/_regenerated_from_message_id记录方式也为会话追踪、分支管理打下基础面向真实世界模型的韧性本地 OpenAI 兼容服务、异构嵌入服务的行为差异拒绝json_object、返回null向量正在被系统性地纳入模型能力元数据与数据校验层。如果你正在调优 DeepTutor 的长回答质量或自建客户端接入重跑能力v1.2.1 的这两项核心机制分阶段预算 原地再生成就是最直接的切入点。【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考