DeepTutor v1.4.3 版本深度解读：TutorBot 升级为 Partners、统一 Agent 循环与真实多用户隔离落地

导读：本篇文章围绕 DeepTutor v1.4.3（发布于 2026.06.12，被认为是 v1.4.0 之后最大的一个版本）的官方 Release Notes 展开，逐条解析"TutorBot 成长为 Partners、Chat 收敛为单一 Agent 循环、多用户从'多账户'走向'真实隔离'"三条主线，并结合仓库当前源码给出实现级佐证。读完你将掌握该版本的升级路径、/api/v1/partners API 变更、data/users/<uid> 目录布局、Dockerfile.runner 沙箱机制，以及如何安全地完成从 TutorBot 到 Partners 的非破坏式迁移。

一、版本定位：v1.4.0 之后的一次架构级更新

v1.4.3 的定位非常明确——"The biggest release since v1.4.0"（ver1-4-3.md）。它不是一次小修小补，而是横跨多个子系统的结构性重构：

变化领域	核心动作
TutorBot → Partners	独立的 nanobot 引擎被移除，IM 机器人统一跑在产品级 Chat 的 Agent 循环上
Chat	两阶段 targeting/respond 管线废除，收敛为单一 exploring agent loop
多用户	从共享数据目录走向 data/users/<uid> + data/system 的真实逐用户隔离
Visualize	全量 LLM review 改为本地 validate + 定向 repair，更快更省
日常工具	Co-writer、文件预览、MinerU 云端解析、Office 技能、CLI chat 全面升级

这一版本同时重建了官方文档站（deeptutor.info），为每一个 Partner 渠道提供了英文与中文双语专属 setup 指南，并将 CLI 与服务器 API 参考同步更新。

下文各节按 Release Notes 的骨架展开，并在源码中找到对应实现与配置，说明这些"发布说明"如何在仓库中落地、持续生效。

二、TutorBot → Partners：同一套 Agent 循环驱动全部 IM 机器人

2.1 架构动机：告别"独立引擎"，统一到产品 Chat 的 Agent 循环

v1.4.3 之前，IM 机器人（TutorBot）运行在一套独立的 nanobot 引擎上，产品 Chat 则是另一套逻辑——两套引擎意味着产品侧每优化一次 Agent 能力，IM 机器人并不能自动受益。

v1.4.3 将两者合并：Partners 直接运行在与产品 Chat 相同的 Agent 循环上，独立的 nanobot 引擎从此消失。这意味着产品 Chat 的每一次改进（工具调用、上下文管理、流式输出）都会自动传导到所有 IM 机器人。

这一点在当前源码中依然清晰可见。deeptutor/partners/__init__.py 的包文档明确写道：

This package hosts the channel (IM) layer: the chat-platform integrations, the message bus that decouples them from the agent runtime, and their configuration schema. The agent runtime itself lives in deeptutor.services.partners and reuses the chat capability's agent loop (ChatOrchestrator → AgenticChatPipeline) — there is no separate partner engine.

即：Partners 包只承载渠道层（IM 平台 SDK、解耦消息总线、配置 schema），真正的 Agent 运行时复用聊天能力的 ChatOrchestrator → AgenticChatPipeline，不存在独立的 Partner 引擎。对应代码位于 deeptutor/agents/chat/agent_loop.py、deeptutor/agents/chat/agentic_pipeline.py 等文件中。

2.2 面向生产的消息管线与直播流式回复

Release Notes 提到 Partners 获得了一整套"生产级消息管线"能力：

• 发送重试（send retries）、去重（dedup）、合并/聚合（coalescing）；
• per-channel delivery matrix（逐渠道投递矩阵）；
• 在 Telegram、Discord、Feishu 上支持直播流式回复——答案边生成边渲染，而不是等到整段结束才发出。

这部分由 deeptutor/partners/channels/ 目录下的渠道实现与 deeptutor/partners/bus（消息总线）共同承担。总线模式将各 IM 渠道的监听任务与 Agent 运行时解耦，从而实现跨渠道一致的投递语义。

2.3 新增 WeCom AI Bot，渠道连接器扩展

v1.4.3 新增 WeCom（企业微信）AI Bot 渠道。在仓库中对应 deeptutor/partners/channels/wecom.py，其类定义中 name = "wecom"，并在缺依赖时报错提示 pip install deeptutor[wecom]。

按 Release Notes 的描述，该版本总计提供 15 个渠道连接器，覆盖 Slack、Discord、DingTalk、QQ、WhatsApp 等主流 IM。从当前源码目录看，渠道连接器的实现集已经进一步扩展，包括：telegram、discord、feishu、slack、dingtalk、qq、wecom、weixin、whatsapp、zulip、matrix、mattermost、mochat、msteams、napcat、email 等（deeptutor/partners/channels/），每个连接器以统一的 name 注册，便于通过 registry.py 完成渠道发现。

渠道依赖通过可选的 pip extra 安装。在 pyproject.toml 中：

• partners extra 打包了主要 IM SDK（telegram、lark-oapi、dingtalk-stream、slack-sdk、qq-botpy、wecom-aibot-sdk 等）；
• matrix / matrix-e2e extra 单独承载 Matrix 渠道及其端到端加密选项；
• tutorbot 作为遗留别名保留一个发布周期：tutorbot = ["deeptutor[partners]"]，因此老用户 pip install deeptutor[tutorbot] 依然可用，但语义上等价于安装 [partners]。

2.4 Web 聊天附件与 Soul 模板库

• Web 聊天附件：用户可以把图片或文件直接拖入 Partner 对话，附件会被转入对应用户的媒体目录处理；
• Soul 模板库重写 + 应用内编辑器：每个 Partner 的"灵魂设定"以 SOUL.md 形式落在其独立工作区中（对应 deeptutor/services/partners/manager.py 中的 read_soul/write_soul 与 DEFAULT_SOUL），并支持在应用内可视化编辑。

2.5 Partner 的配置模型与敏感信息掩码

当前源码中，单个 Partner 的配置集中在 data/partners/<partner_id>/config.yaml，由 PartnerConfig dataclass 承载（见 deeptutor/services/partners/manager.py）。从 v1.4.3 演化而来的字段包括：

字段	说明
name / description	展示名称与描述，name 会参与生成 URL-safe 的 partner id
channels	各 IM 渠道的启用配置（含 token/secret 等凭据）
llm_selection / backup_llm_selection	首选模型选择与失败回退模型
model	遗留 TutorBot 的单字符串模型覆盖（legacy 字段）
language / emoji / color / avatar	展示层的语言与外观
soul_origin	Soul 来源追踪（{"type","id"}，记录是否从模板库继承）
enabled_tools	用户可开关的系统工具白名单（None=全部，[]=无，list=白名单）
builtin_tools	内置自动挂载工具（rag / read_memory / web_fetch 等）的门控
mcp_tools	可加载的 MCP 工具白名单，默认 []（关闭）

值得注意的安全设计：渠道凭据在序列化回非编辑界面时会被掩码为 ***（manager.py 中通过 token/secret/password/api_key 等字段名特征判定并 mask_channel_secrets），避免在管理界面或审计响应中泄露明文密钥。

三、从 TutorBot 到 Partners：非破坏式自动迁移与破坏性变更

3.1 迁移是自动且非破坏式的

Release Notes 对升级路径给出明确承诺：

• 首次启动时，旧机器人的渠道配置（含密钥）、模型选择、Soul 库自动迁移成为 Partners；
• 每个 bot 的 persona 变更为其 SOUL.md；
• 旧 data/tutorbot/ 目录原样保留、不做删除，因此随时可以安全回滚；
• 所有迁移操作都是幂等的（idempotent），重复执行不会产生副作用。

这一逻辑在当前源码 PartnerManager._migrate_legacy_tutorbot()（deeptutor/services/partners/manager.py）中仍有完整实现：它会在首次发现 data/tutorbot/ 树时，将旧 _souls.yaml 复制为新的 Soul 库文件、把每个 bot 目录下的配置与 persona 转写为 Partner 形态，同时对遗留树保持只读不改。_discover_partner_ids() 每次扫描都会先触发一次该迁移，且通过 self._migrated_legacy 标记保证单次执行。

3.2 破坏性变更：HTTP API 路径迁移

这是本版本唯一需要手动处理的破坏性变更：

• 旧路径：/api/v1/tutorbot/...
• 新路径：/api/v1/partners/...

所有调用旧 API 的脚本必须同步更新。在 deeptutor/api/main.py 中可以确认路由挂载方式已变为：

partners.router, prefix="/api/v1/partners", tags=["partners"], dependencies=_admin

3.3 升级命令与回滚

pip install -U deeptutor

首次启动时迁移自动运行，所有迁移均幂等。由于旧 data/tutorbot/ 树未被触碰，需要回滚时只需恢复到旧版本并保留旧数据目录即可。

四、Chat 统一为"单一 Agent 循环"

4.1 从两阶段管线到单循环

v1.4.3 之前，Chat 走的是"先 targeting（意图路由）再 respond（回复生成）"的两阶段管线，轮次（turn）容易被错误路由。v1.4.3 将其彻底删除，改为单一的 exploring agent loop：

• 原生工具调用贯穿端到端（native tool calling end to end）；
• 更少的移动部件（fewer moving parts），工具使用更智能；
• 不再出现"轮次被错误路由"的问题。

当前源码 deeptutor/agents/chat/ 下的 agent_loop.py、agentic_pipeline.py、chat_agent.py、session_manager.py 等即构成了这一统一循环。Partner 复用此循环的事实（见上文 deeptutor/partners/__init__.py）也印证了"一套循环服务所有对话场景"的设计目标。

4.2 Activity header：把状态钉在顶部

配合单循环重构，Web 端新增 Activity header：状态栏常驻顶部，答案落定后思考/工具调用轨迹（thinking/tool trace）会自动折叠收拢，避免把界面拉得冗长。它对应 Web 工作区聊天界面中的状态与轨迹展示（web/app/(workspace)) 下的聊天页面与 web/components/chat/ 组件实现），让用户既能感知 Agent 正在做什么，又不被中间过程刷屏。

4.3 CLI chat 同步重写

CLI 聊天也被重写以对齐新的循环协议：

• 支持在终端内进行交互式 ask_user 提问（向用户澄清问题）；
• Ctrl-C 取消正在进行中的轮次；
• 可折叠的 thinking 输出，只展示关键信息。

对应的命令实现在 deeptutor_cli/chat.py（deeptutor 的 CLI 入口之一）。

五、多用户"真实隔离"：从多账户到按用户隔离

5.1 Per-user grants v2

v1.4.3 之前的多用户更像"多账户共享一个工作区"。本版本引入真正的逐用户隔离：

• 管理员可在管理界面按用户分别控制 工具（tools）、MCP servers、exec 执行权限；
• 权限模型以 grant 为最小粒度，每个真实账号不再因为管理员在部署层面加了某个 MCP Server 就自动获得全部能力。

这在 deeptutor/multi_user/ 包中有完整落点：grants.py（授权模型）、tool_access.py / model_access.py / partner_access.py / knowledge_access.py / skill_access.py（各类资源的按用户门控）。授权语义在设计上刻意"默认拒绝"——例如 manager.py 的注释指出，用户侧 grant 的 mcp_tools=None 表示拒绝（因为缺失的 grant 不能让真实账户继承部署级服务器），而 Partner 侧的 None 则是所有者主动的"全部放行"，两侧极性相反。

5.2 目录布局迁移到 data/users/<uid> + data/system

工作区布局从旧的共享结构迁移为：

<runtime-home>/data/
├── user/                  # 管理员工作区（admin scope 根即 data/）
├── users/<uid>/           # 每个非管理员用户一个独立工作区
├── partners/<partner_id>/ # Partner（合成用户）工作区
└── system/                # 部署状态：账号、授权、审计、per-owner 密钥等

见 deeptutor/multi_user/paths.py。该模块还实现了 migrate_legacy_multi_user_tree()，将旧 multi-user/ 树就地迁移：multi-user/_system → data/system，其余子目录逐个成为 data/users/<uid>；目标路径已存在时绝不覆盖（留下日志由运维手工对账），整体幂等。

升级提示：既有 multi-user/ 目录树会在部署中就地迁入 data/users/；由于迁移不覆盖已有目标且幂等，重复启动安全。

5.3 exec runner 只挂载调用者工作区：新的 Dockerfile.runner

隔离的关键在沙箱执行层：exec runner 只挂载当前调用用户的 workspace 子树，因此沙箱内运行的代码永远看不到其他用户的文件。

仓库根目录新增了 Dockerfile.runner，构建的是一个"刻意最小化、最低权限"的沙箱 runner sidecar 镜像——它只做一件事：在独立容器内代表主应用执行不可信 shell 命令。镜像说明明确指出：

A deliberately small, least-privileged image whose only job is to execute untrusted shell commands on behalf of the main app, isolated in its own container. The main app talks to it over HTTP via RunnerSidecarBackend … pointed here through DEEPTUTOR_SANDBOX_RUNNER_URL.

主应用通过 deeptutor/services/sandbox/backends.py 中的 RunnerSidecarBackend 与它通信，通常由 docker-compose 编排（compose.yaml 与 docker-compose.yml 均描述了该 sidecar 的挂载方式；data/system 等部署级目录不会挂进 runner）。也就是说，"沙箱代码只看得到自己的文件"这一目标由镜像最小化 + 按用户挂载 + HTTP 隔离协议三层共同保证。

六、Visualize 重建：本地校验 + 定向修复取代整轮 LLM review

v1.4.3 对可视化（图表生成）做了架构性优化：

• 行内、随主题感知的 SVG 渲染（inline, theme-aware SVG rendering）——图表直接嵌入答案，且跟随界面主题配色；
• 使用结构化 prompts；
• 用本地 validate + repair 通道取代过去"每次生成都跑一整轮完整 LLM review"的做法——更快、更省 token，且坏图率显著下降；
• 全屏查看对所有图表类型生效。

当前源码 deeptutor/agents/visualize/capability.py 的第 3 阶段正是这种"先本地校验、仅在失败时才定向修复"的策略：首先生成代码，随后调用本地 validate_visualization(code, analysis.render_type) 进行校验，只有校验失败才触发一次定向的 repair LLM 调用，而不是默认对所有输出都做整轮 review。对应的 repair agent 位于 deeptutor/agents/visualize/agents/review_agent.py，其职责注释为"Targeted repair pass — this agent's single job"（定向修复通道，只负责修）。

这是"用确定性校验兜底、用 LLM 只在必要时介入"的典型工程取舍，也解释了为何 v1.4.3 能同时改善速度与出图质量。

七、日常工具的精细化升级

7.1 Co-writer：Mermaid 图表 + 选区问答

• Co-writer 现在可以通过 Mermaid 渲染流程图（flowchart）与时序图（sequence diagram）；
• 选区范围的提问（selection-scoped questions）可以同时从知识库和网络拉取资料，实现"选中一段话 → 带着上下文提问 → 答案引用知识库与网页来源"。

Co-writer 的后端模块位于 deeptutor/co_writer/（edit_agent.py、storage.py、prompts/）；其富文本与 Mermaid 渲染能力则依赖 Web 端现有的 Mermaid 组件（web/components/Mermaid.tsx）。

7.2 文件查看器与文档解析：docx/xlsx 浏览器内预览 + MinerU 云端解析

• 文件查看器提供真正的浏览器内 docx/xlsx 预览、拖拽调整宽高，且 Activity 面板与已打开文件并排显示，方便边看文件边观察 Agent 活动；
• 文档解析新增 MinerU 云端解析作为本地后端之外的备选（入口 /settings/mineru），并保留本地 CLI 模式。

在解析引擎层，deeptutor/services/parsing/engines/mineru/config.py 中的 MinerUConfig 定义了 mode（"local" / "cloud"）双模式，cloud 分支额外使用 api_base_url（默认 https://mineru.net）与 API token；allow_local_model_download 默认 False（本地解析失败时快速失败，而不是自动下载模型，云端模式忽略该项）。设置接口见 deeptutor/api/routers/settings.py（MinerUSettingsUpdate 模型，且 api_token 在回传 UI 时会被脱敏为布尔值表示"是否已配置"）。

配套地，题目抽取（question extraction）现在会捕获题型、难度与参考答案，让从试卷/文档抽取的题目自带元数据（相关实现涉及 deeptutor/agents/question/capability.py 等）。

7.3 Office 技能开箱即用：docx/pdf/pptx/xlsx

v1.4.3 之前，生成 Office 文档可能需要在沙箱里手动打开某个开关；本版本起 Office 技能默认开箱即用——docx/pdf/pptx/xlsx 生成不再要求翻转沙箱开关。

这一行为的默认值沉淀在系统设置中：deeptutor/services/config/runtime_settings.py 的 DEFAULT_SYSTEM_SETTINGS 中 "sandbox_allow_subprocess": True，其注释说明这是承载 office 技能（docx/pdf/pptx/xlsx）的受限子进程执行沙箱开关，默认开启以便文档生成在所有部署形态下立即可用；若存在更强的后端（runner sidecar / bwrap）则优先使用更强后端。环境变量形式为 DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS（布尔解析）。

如果你在意"exec 类技能必须放行子进程"这一行为的旧默认值，可以像升级注意事项里写的那样，在系统设置中把 sandbox_allow_subprocess 设回 false 以恢复旧行为。

7.4 其余日常改进

• Web 聊天附件：图片/文件直接拖入 Partner 对话（见 2.4）；
• CLI：chat 重写（见 4.3）。

八、值得记录的 Bug 修复与配套文档

Release Notes 列出的一批"Fix That Matter"包括：

• Qwen 模型不再把 JSON wrapper 泄漏进回答——修复了部分 Qwen 系列模型在工具调用后残留 JSON 包装内容的问题；
• Windows 安装的 UTF-8 编码问题得到正确处理；
• Zulip 机器人的 @提及（mention）能可靠捕获；
• 修复了**文件描述符耗尽（file-descriptor exhaustion）**缺陷；
• 移除了健康检查的误报（false-positive health checks）。

配套地，deeptutor.info 文档站在本版本被整体重建：每个 Partner 渠道都有独立的 setup 指南（英文 + 中文双语）、全站截图刷新、CLI 与服务器 API 参考同步更新。

九、升级检查清单（快速上手）

综合 Release Notes 的升级注意事项与上文源码证据，从 v1.4.2 及更早版本升级到 v1.4.3 时的操作顺序为：

1. 更新安装包：pip install -U deeptutor（使用 IM 渠道能力的用户，依赖会随 [partners] 安装；旧 [tutorbot] extra 仍可作为别名工作）。
2. 处理破坏性 API 变更：把所有调用 /api/v1/tutorbot/... 的外部脚本迁移到 /api/v1/partners/...（对应 deeptutor/api/main.py 中的路由前缀）。
3. 首次启动自动迁移：旧 data/tutorbot/ 树与 multi-user/ 树会被就地、幂等、非破坏式地迁移——旧目录保留，回滚安全。
4. 沙箱默认值变化确认：sandbox_allow_subprocess 默认为 True，Office 技能（docx/pdf/pptx/xlsx）默认可用；若需严格旧行为，在系统设置中将其设为 false（环境变量 DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=false）。
5. 体验验证：在 Web 端验证 Activity header、附件上传、图表本地校验修复链路；在 CLI 中验证 Ctrl-C 取消与交互式 ask_user。

如果你想查看该版本与此前的完整差异，可对照仓库内的历史发布记录 assets/releases/past_releases/ver1-4-0.md 及同一目录下更早版本的 release notes。需要说明的是，本文所引用的仓库源码反映了 v1.4.3 之后的持续演进状态（例如 deeptutor/partners/__init__.py 的 __version__ = "2.0.0"、渠道连接器在 15 个基础上继续扩展），但本文描述的架构方向——Partners 复用 Chat 单一循环、data/users/<uid> 目录隔离、Dockerfile.runner 最小权限沙箱、Visualize 本地校验+定向修复——均在该版本确立并延续至今，可作为理解 v1.4.3 设计意图及其后续演进的可靠起点。