架构与源代码所有者¶

手册 · 开发 · 事件

DeepTutor 1.7.0 是一个包含独立打包 Python 模块的源代码仓库。CLI、WebSocket 与 Python SDK 入口点会先汇聚到一个持久化应用服务，然后再执行某项能力。

flowchart TD
  CLI[Typer CLI] --> APP[TurnApplicationService]
  WS[WebSocket adapter] --> APP
  SDK[DeepTutorApp SDK] --> APP
  APP <--> STORE[Session store and runtime coordinator]
  APP --> ENGINE[TurnEngine]
  ENGINE --> ORCH[ChatOrchestrator]
  ORCH --> CAP[Selected capability]
  CAP --> LOOP[Agent loop or stage pipeline]
  LOOP --> TOOLS[Authorized tool registry]
  CAP --> BUS[Per-turn StreamBus]
  BUS --> STORE
  STORE --> REPLAY[Adapter replay to consumers]

跟踪请求¶

UnifiedContext 位于 core/context.py，是执行上下文。入口点应使用应用服务，而不是实例化编排器来绕过持久化状态。持久化、提交身份、重放、取消和恢复都属于共享的应用/运行时路径。在改变流行为之前，请参阅 事件。

工具、能力与模块¶

工具是模型选择的单个操作。能力拥有完整的回合，可以运行共享循环或多阶段流水线。chat 是默认能力；能力激活和上下文决定额外工具的可用性。每个能力都会发出通用的结果封装，包括使用成本。请参阅 扩展契约。

官方 模块清单 拥有包路径、依赖、能力、路由器、CLI 组、导航和生命周期回调。已安装、已启用和就绪是三种独立状态。元数据必须能够在不需要导入不可用功能包的情况下被读取。第三方 插件 会添加自己的审查和生命周期规则；它们与官方模块的 wheel 包不同。

配置与隔离¶

runtime/home.py 解析运行时主目录；services/config/runtime_settings.py 拥有设置和支持的进程覆盖项。运行时设置位于 data/user/settings/ 下；.env 不是应用程序配置来源。容器启动有自己的 JSON 到环境变量处理逻辑，详见 容器化。

账户授权和工作区选择是分开的检查。路径和服务通过 services/workspace/ 和 services/path_service.py 解析。所选工作区数据、账户凭据和共享资源授权具有不同的生命周期；在改动迁移或缓存之前，请参阅 存储 和 工作区契约。

前端边界¶

Next.js App Router 位于 web/app/，负责组合页面。领域、状态存储和传输层切片位于 web/features/ 下。可复用的 UI 和传输原语位于 web/shared/ 下。web/contracts/ 存放生成的 API 和回合契约。

依赖规则 禁止循环依赖、导入路由 page.tsx 模块、共享代码的向上依赖，以及功能领域/存储/传输代码被渲染层导入（指定的 settings-store 例外除外）。应优先使用现有的传输和存储所有者，而不是在组件本地实现 WebSocket、重试或持久化。

web/proxy.ts 将 API/WebSocket 流量转发到后端。浏览器设置和运行时服务器配置是不同的边界；不要将部署地址或密钥硬编码到客户端代码中。

实验性引擎路径¶

Python 调度器仍然是默认实现。DEEPTUTOR_CHAT_ENGINE 可以选择在 packages/chat-engine/ 和 runtime/ts_engine/ 中实现的实验性 TypeScript 路径。原生路径具有兼容性检查和 Python 集成点。旧的迁移计划并不能证明整个后端已经迁移到 TypeScript。这里的更改必须保留应用服务、存储和公共事件契约；请参阅 测试 中专门的引擎任务。