1. 顶层目录全景先看仓库根目录我按核心 vs 工程分两类标注DeepTutor-main/ ├── deeptutor/ ★★★ 核心引擎Python 后端590个.py ├── deeptutor_cli/ ★★ CLI 入口Typer20个.py ├── deeptutor_web/ ☆ Web 入口占位1个.py ├── web/ ☆ 前端工程Next.js247个.tsx 129个.ts ├── tests/ ☆ 测试285个.py ├── packaging/ ☆ 打包配置 ├── requirements/ ☆ 依赖清单7个.txt ├── scripts/ ☆ 辅助脚本7个.py 2个.bat ├── assets/ ☆ 文档图片资源 ├── 2604.26962v3.pdf ☆ 论文 ├── SKILL.md ★ Agent 交接文档给其他 LLM 读的 ├── AGENTS.md ★ 架构说明你在看的这份 ├── README.md ☆ 用户文档 ├── pyproject.toml ☆ Python 包配置 ├── Dockerfile*3 ☆ 容器化 ├── docker-compose*3 ☆ 容器编排 └── 其他 .md ☆ 文档标记说明★★★ 绝对核心★★ 核心入口★ 重要文档☆ 工程支撑。关键结论真正要读懂 DeepTutor只需看deeptutor/这一个目录。其他都是工程外壳。2.deeptutor/内部目录拆解deeptutor/下有 17 个子目录我按职责分成四圈第一圈核心骨架必须读这四个目录定义了整个系统的协议层和运行时层——所有东西都长在这上面。deeptutor/ ├── core/ ★★★ 协议定义层 │ ├── context.py ← UnifiedContext 数据类所有请求的统一载体 │ ├── tool_protocol.py ← BaseTool ToolDefinitionTool 的接口契约 │ ├── capability_protocol.py ← BaseCapability CapabilityManifestCapability 的接口契约 │ ├── stream.py ← StreamEvent 协议流式输出的数据结构 │ ├── stream_bus.py ← StreamBus事件总线async fan-out │ ├── trace.py ← 调用追踪 │ ├── errors.py ← 错误类型 │ ├── i18n.py ← 国际化 │ └── agentic/ ← agentic loop 的基础抽象 │ ├── runtime/ ★★★ 运行时层 │ ├── orchestrator.py ← ChatOrchestrator唯一入口路由到 Capability │ ├── launcher.py ← 后端前端生命周期管理 │ ├── home.py ← workspace 路径发现 │ ├── mode.py ← 运行模式CLI/API/full │ ├── request_contracts.py ← 请求契约定义 │ ├── banner.py ← 启动 banner工程代码 │ ├── bootstrap/ ← 启动时注册所有 Tool 和 Capability │ └── registry/ ← ToolRegistry CapabilityRegistry注册表 │ ├── agents/ ★★★ Agent 实现真正的业务逻辑在这里 │ ├── base_agent.py ← 所有 Agent 的基类 │ ├── _shared/ ← Agent 共享工具 │ ├── chat/ ← chat capability 的 Agent7.py 4.yaml │ ├── research/ ← deep_research 的 Agent9.py 2.yaml │ ├── question/ ← deep_question 的 Agent9.py 8.yaml │ ├── visualize/ ← visualize 的 Agent9.py 8.yaml │ ├── math_animator/ ← math_animator 的 Agent16.py 12.yaml │ ├── notebook/ ← notebook 相关 Agent │ └── vision_solver/ ← 视觉解题 Agent │ ├── tools/ ★★★ Tool 实现 │ ├── builtin/ ← 内置 tool 的注册入口 │ ├── prompting/ ← Tool 的 prompt 模板36个.yaml │ ├── question/ ← 出题相关 tool │ ├── vision/ ← 视觉相关 tool │ ├── rag_tool.py ← RAG 检索 tool │ ├── web_search.py ← 网页搜索 tool │ ├── reason.py ← 深度推理 tool │ ├── brainstorm.py ← 头脑风暴 tool │ ├── ask_user.py ← 向用户提问 tool会暂停 turn │ ├── exec_tool.py ← 代码执行 tool │ └── ... 其余每个文件一个 tool为什么这样拆核心骨架遵循一个清晰的三层分离层目录职责依赖关系协议层core/定义接口契约不含实现被所有人依赖运行时层runtime/装配和调度不含业务逻辑依赖 core被 agents/tools 依赖业务层agents/tools/真正干活的人依赖 core runtime这是经典的依赖倒置——core/定义BaseTool和BaseCapability接口agents/和tools/实现这些接口runtime/通过 registry 动态装配。新增一个 Tool 不需要改 orchestrator新增一个 Capability 也不需要改 tool。第二圈服务层支撑业务的基础设施deeptutor/services/ ├── llm/ ★★ LLM 调用封装35个.py——最底层的基础设施 ├── memory/ ★★ 三层 Memory 系统28.py 14.yaml——论文核心 ├── rag/ ★★ RAG 检索引擎46个.py——多引擎支持 ├── search/ ★ 网页搜索封装15个.py ├── embedding/ ★ 向量嵌入12个.py ├── parsing/ ★ 文档解析29个.py——Text/MinerU/Docling/markitdown/PyMuPDF4LLM ├── config/ ★ 配置管理12个.py ├── sandbox/ ★ 代码执行沙箱9个.py ├── session/ ★ 会话管理9个.py ├── subagent/ ★ 子 Agent 调用13个.py——consult Claude Code/Codex ├── partners/ ★ Partner IM 通道 ├── skill/ ★ Skill 管理 ├── persona/ ★ 人格预设 ├── prompt/ ★ Prompt 模板管理 ├── notebook/ ★ 笔记本服务 ├── cron/ ★ 定时任务 ├── model_selection/★ 模型选择策略 ├── mcp/ ★ MCP 客户端 ├── imagegen/ ★ 图片生成 ├── videogen/ ★ 视频生成 ├── voice/ ★ 语音 ├── storage/ ★ 存储 ├── settings/ ★ 设置 ├── setup/ ★ 初始化向导 ├── auth.py ★ 认证 └── 其他零散文件这一圈是基础设施——不直接面向用户但被 agents 和 tools 调用。重点标注三个论文核心目录services/memory/——论文的 Hybrid Personalization Engine 落地在这里。28个.py 14个.yaml说明 Memory 系统的复杂度远超普通存历史对话。services/rag/——论文的 “static knowledge grounding” 落地在这里。46个.py 说明支持多引擎LlamaIndex/PageIndex/GraphRAG/LightRAG/Obsidian的工程量。services/llm/——35个.py 封装了所有 LLM 调用。这个目录的大小暗示了 DeepTutor 支持的模型 provider 数量。第三圈功能模块面向特定场景的业务包deeptutor/ ├── capabilities/ ★★ Capability 注册和路由逻辑 │ ├── protocol.py ← Capability 的注册协议 │ ├── registry.py ← CapabilityRegistry 实现 │ ├── explore_context/ ← chat capability 的子模块 │ ├── mastery/ ← mastery_path capability │ ├── solve/ ← deep_solve capability │ ├── subagent/ ← subagent capability │ └── obsidian/ ← Obsidian 集成 capability │ ├── book/ ★ Book Engineliving book 编译器 ├── co_writer/ ★ Co-WriterMarkdown 协作编辑 ├── learning/ ★ Learning Space技能/人格/掌握路径 ├── knowledge/ ★ Knowledge CenterKB 管理界面 ├── partners/ ★ Partner 生命周期管理 ├── skills/ ★ Skill 系统 └── multi_user/ ★ 多用户隔离这一圈是功能包——每个目录对应一个用户可见的功能模块。第四圈工程外围deeptutor/ ├── api/ ★★ FastAPI 路由37个.py——WebSocket REST ├── events/ ★ 事件总线全局 EventBus ├── i18n/ ★ 国际化资源 ├── logging/ ★ 日志系统11个.py ├── utils/ ★ 工具函数 └── config/ ★ 默认配置这一圈是系统支撑——不承载业务逻辑但让系统跑起来。3. 关键发现capabilities/和agents/的关系这是第二层最重要的一个发现也是读代码容易踩坑的地方。看 AGENTS.md 里列的 Capability 表格CapabilityStageschatexploring → respondingdeep_solveplanning → reasoning → writingdeep_researchrephrasing → decomposing → researching → reporting……你会以为这些 Capability 的实现在deeptutor/capabilities/目录下。但看目录结构deeptutor/capabilities/ ← 只有注册逻辑 空的占位子目录 deeptutor/agents/ ← 真正的 Agent 实现在这里为什么会这样这是 DeepTutor 架构演进留下的痕迹早期v1.4.0-beta 之前Capability 直接在capabilities/下实现每个 capability 是一个多阶段流水线类。v1.4.0 重构把每个 Capability 的内部逻辑拆成了独立的 Agent在agents/下capabilities/退化为注册层。agents/chat/下有 7 个 .py 4 个 .yaml——说明 chat capability 内部不是一个简单的函数而是有多个 Agent 协作exploring agent、responding agent 等每个 Agent 有自己的 prompt.yaml 文件。这个设计的意义Capability 是流程编排Agent 是执行单元。一个 Capability 可以调度多个 Agent每个 Agent 有独立的状态和 prompt。4. 哪些是真正核心代码哪些只是工程代码我用一个表格做最终判定核心代码读懂这些 读懂 DeepTutor目录文件数为什么是核心deeptutor/core/16.py整个系统的协议层——所有接口定义在这里deeptutor/runtime/orchestrator.py1.py唯一入口127行但决定整个系统怎么跑deeptutor/runtime/registry/~5.pyTool 和 Capability 的注册机制deeptutor/agents/60.py 38.yaml所有 Agent 的业务实现 promptdeeptutor/tools/30.py 36.yaml所有 Tool 的实现 promptdeeptutor/services/memory/28.py 14.yaml三层 Memory 系统——论文核心创新deeptutor/services/rag/46.pyRAG 多引擎——论文的 static groundingdeeptutor/services/llm/35.pyLLM 调用层——所有 Agent 的底层依赖总计约 220 个 .py 90 个 .yaml 约 310 个文件。工程代码让系统可用但不影响理解设计目录文件数为什么是工程web/436文件前端 UI和核心架构无关deeptutor/api/37.pyHTTP/WebSocket 路由只是传输层deeptutor/services/parsing/29.py文档解析基础设施deeptutor/services/embedding/12.py向量嵌入基础设施deeptutor/services/search/15.py搜索封装基础设施deeptutor/services/sandbox/9.py代码沙箱基础设施deeptutor/services/session/9.py会话持久化deeptutor/services/config/12.py配置管理deeptutor/multi_user/13.py多用户隔离deeptutor/partners/30.pyIM 通道集成deeptutor/book/58文件Book Engine独立功能模块deeptutor/co_writer/~10文件Co-Writer独立功能模块tests/285.py测试scripts/9文件辅助脚本packaging/2文件打包各种 Docker/CI 文件~10文件部署总计约 1000 文件但都是工程支撑。比例核心代码 ~310 文件占 deeptutor/ 的 ~43% 工程代码 ~1000 文件占整个仓库的 ~75%DeepTutor 仓库有 1400 文件但真正承载设计思想的只有约 310 个。这也是为什么 AGENTS.md 只列了 15 个 Key Files——那 15 个文件就是核心中的核心。5. 为什么这样拆设计哲学原则 1协议先行Protocol-Firstcore/目录里全是*_protocol.py——tool_protocol.py、capability_protocol.py。这意味着 DeepTutor 把接口契约和实现严格分离。好处第三方可以写自己的 Tool 或 Capability只要实现BaseTool或BaseCapability接口注册到 registry 就能用。这就是 README 说的extensible tools and skills的底层支撑。原则 2注册表驱动Registry-Drivenruntime/registry/下有两个 registryToolRegistry和CapabilityRegistry。所有 Tool 和 Capability 在启动时通过runtime/bootstrap/注册进去。orchestrator 不 hardcode 任何 Tool 或 Capability——它只查 registry。这意味着增删功能不改 orchestrator符合开闭原则。原则 3Prompt 外置Prompt-as-Configagents/下每个子目录都有大量 .yaml 文件chat 有 4 个research 有 2 个question 有 8 个。这些是 Agent 的 prompt 模板不是硬编码在 .py 里。好处调 prompt 不用改代码非程序员也能调比如教育专家调教学策略 prompt。这也是论文说的personalized tutoring能快速迭代的基础——教学策略在 yaml 里不在代码里。原则 4服务层下沉Service Layerservices/目录承载了所有和外部世界交互的逻辑——LLM 调用、RAG 检索、Memory 存储、文档解析、搜索、沙箱。Agent 和 Tool 只调用 service不直接碰外部系统。这使得换 LLM provider 只改services/llm/不动 Agent换 RAG 引擎只改services/rag/不动 Tool换 Memory 后端只改services/memory/不动 Agent原则 5Prompt 和代码同目录Co-locationagents/chat/下同时有 .py 和 .yaml——代码和它用的 prompt 放在一起。这比所有 prompt 放一个统一目录更好因为改一个 Agent 时所有相关文件都在一处。第二层小结问题答案仓库怎么组织四圈核心骨架 → 服务层 → 功能模块 → 工程外围每个目录负责什么core/协议runtime/调度agents/业务tools/原子能力services/基础设施为什么这样拆协议先行 注册表驱动 Prompt外置 服务层下沉 代码与prompt同目录哪些是核心代码core/runtime/orchestrator.pyagents/tools/ services/memory哪些是工程代码web/api/ 大部分services/子目录 tests/ 部署文件 ≈ 1000文件capabilities/vsagents/capabilities 是注册层空壳agents 是真正的业务实现v1.4重构后