开发 DeepTutor¶

手册 · 架构 · 测试

准备源代码环境¶

按照 Agent 设置 准备 Python 3.11–3.14、Node.js 22 LTS、provider 配置和就绪状态。源码检出会提供所有模块；先安装其外部依赖，再进行可编辑核心安装：

python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
python scripts/install_extras.py dev
cd web
npm ci --legacy-peer-deps
cd ..

使用 scripts/install_extras.py 安装可选源代码依赖。在可编辑安装之上安装功能 wheel 可能会掩盖源代码所有权；请使用独立环境进行 wheel 生命周期测试。FFmpeg 和 LaTeX 等系统可执行文件，仍然是需要这些可执行文件的功能的独立前置条件。

更新前请检查 git status、当前分支和远程仓库。针对 dev 分支进行开发；PR 目标请遵循 贡献政策。当并发工作需要隔离时，可复用合适的任务检出，或使用单独的工作树。保留不相关的编辑内容。不要将运行时数据和测试输出纳入 Git。

使用专用的运行时主目录¶

DEEPTUTOR_HOME 是拥有 data/ 的目录，而不是 data/ 本身。请选择一个明确且私有的开发主目录，并在每条命令中使用它。例如，在一个新的 shell 中：

export DEEPTUTOR_HOME="$HOME/.local/share/deeptutor-dev"
deeptutor init --non-interactive
deeptutor config show
deeptutor module list

不要将测试夹具指向现有学习者的运行时。Content Workspace 是独立的存储和授权范围；请参见 工作区。应用程序不会自动加载项目的 .env 文件。

运行与检查¶

对于组合启动器，请使用 deeptutor start，并阅读其输出中的实际 URL。对于单独的开发进程，请在两个终端中运行 API 和前端，并使用同一个选定的运行时主目录：

# Terminal 1: API, with reload
deeptutor serve --host 127.0.0.1 --port 8001 --reload

# Terminal 2: frontend, from web/
DEEPTUTOR_API_BASE_URL=http://127.0.0.1:8001 npm run dev

选择空闲端口；不要停止无关的服务。确认浏览器请求通过前端代理到达预期的 API。仅监听前端并不能表明 provider、模块或轮次已就绪。请使用 deeptutor doctor --format json 以及原始用户操作进行验证。

在属主处进行更改¶

1. 使用最小的合成夹具复现该行为。确定属主是适配器、共享运行时、能力、工具、功能存储、provider 还是前端投影。
2. 阅读最接近的实现及其测试。对于 API 更改，请追踪请求验证：身份验证、账户/工作区解析、持久化、事件和 UI 消费。
3. 更改该属主，而不是添加第二个运行时、路径解析器、provider 客户端或存储抽象。共享协议应保持导入轻量。
4. 在受影响时更新模块声明、请求契约、prompts 和本地化字符串。使用所属脚本重新生成派生文件。
5. 运行 适合该更改的检查，复现原始操作，并在 PR 中说明任何验证限制。

对子进程使用显式参数列表和 shell=False；在取消时保留进程树清理。通过现有账户和工作区上下文解析存储，而不是构造全局数据路径。绝不将凭据或私有 provider 回放元数据返回给浏览器响应。

生成的文件与文档¶

仓库有意跟踪生成的 API 契约、需求文件和依赖锁定。请更新它们的生成器或权威输入，然后重新生成。web/.next*、已安装依赖、字节码、日志和手动验收产物保持不被跟踪。

当公共行为发生变化时，更新相关的手册主题和 README 链接。将可复用的可执行示例放在本手册的 examples/ 下。保持命令示例可从仓库根目录使用，并避免包含个人机器路径。