人工智能AI 应用AI Agent多智能体RAG教育后端前端【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址https://gitcode.com/GitHub_Trending/dee/DeepTutor点击查看免费下载DeepTutor 是一个开源的生命周期个性化辅导项目Lifelong Personalized Tutoring仓库由deeptutorPython 后端、webNext.js 前端、deeptutor_cli命令行客户端等多个模块构成。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合.pre-commit-config.yaml、pyproject.toml、scripts/下的卫生检查脚本、.gitattributes以及.github/workflows/tests.yml等真实源码与配置逐层讲解分支策略、贡献流程、开发环境搭建、代码质量门禁、编码规范、提交信息格式与安全基线。读完本文你将掌握向 DeepTutor 提交高质量 PR 的完整链路从选对目标分支到本地校验通过再到通过 CI 的严格检查。分支策略与 PR 目标分支DeepTutor 采用多分支开发模型CONTRIBUTING.md 中明确维护两条面向贡献者的开发分支分支用途稳定性dev常规开发可能包含缺陷或破坏性变更multi-user多用户/多租户场景开发实验性聚焦多租户特性IMPORTANT禁止直接向main提交 PR。所有贡献应瞄准dev或multi-user。选择目标分支的判据非常清晰瞄准dev新功能或功能增强、可能影响现有行为的重构、API 或配置变更、常规 Bug 修复。瞄准multi-user多用户/多租户相关功能、会话隔离、用户管理与权限变更、协作或共享工作区功能。不确定时默认选dev它是默认开发分支。这一策略不仅写在文档里仓库还提供了强制性的代码级保障。scripts/hooks/pre-commit中的无依赖钩子会调用python3 scripts/check_branch_policy.py后者见 check_branch_policy.py会在当前分支为main且未显式放行时直接拒绝提交if current_branch() main and not allows_main_commit(): print(Direct commits to main are forbidden...) return 1也就是说连本地在main上直接 commit 都会被钩子拦截发布维护者如需在本地main上提交可用git config deeptutor.allowMainCommit true单次放行提交后必须立即移除该配置。快速上手贡献者启动流程CONTRIBUTING.md 给出了一条六步启动路径配合仓库脚本可以完全照做Fork Clone仓库。同步目标分支后再开始开发git checkout dev git pull origin dev从目标分支创建特性分支git checkout -b feature/your-feature-name按编码规范开发见下文编码规范一节。运行 pre-commit 校验pre-commit run --all-files向正确的目标分支提交 PRmain仅限 hotfix 或纯文档变更。关于找任务入口可以在仓库 Issues 中检索带good first issue标签的任务并在 issue 下留言认领避免与他人重复开发。开发环境搭建创建虚拟环境并安装依赖CONTRIBUTING.md 推荐使用 venv 隔离环境python -m venv venv source venv/bin/activate # Windows 下为 venv\Scripts\activate随后以可编辑模式安装完整依赖pip install -e .[all]这里[all]是 pyproject.toml 中定义的聚合 extra包含partners、matrix、math-animator、dev、video-learning五组能力。其中devextra 明确包含pytest、pytest-asyncio、pre-commit3.0.0、bandit、import-linter以及测试夹具构建所需的python-docx、openpyxl、python-pptx、pypdf、defusedxml等库。如果只需要轻量环境也可以直接按 requirements/cli.txt 或 requirements/server.txt 安装。安装 pre-commit首次一次性配置pip install pre-commit # 或: conda install -c conda-forge pre-commit pre-commit install初始化 Secrets Baseline如果本地扫描出现误报的敏感信息例如 API hash 占位符可以更新基线文件detect-secrets scan .secrets.baseline基线文件.secrets.baseline正是.pre-commit-config.yaml中detect-secrets钩子读取的白名单依据args: [--baseline, .secrets.baseline]。常用命令速查CONTRIBUTING.md 将贡献过程中最高频的命令汇总成一张速查表任务命令检查干净工作区 受跟踪文件卫生python3 scripts/check_workspace_hygiene.py检查仓库卫生python3 scripts/check_repo_hygiene.py检查全部文件pre-commit run --all-files静默检查pre-commit run --all-files -q更新工具pre-commit autoupdate紧急跳过不推荐git commit --no-verify -m message这两条卫生检查脚本值得展开说明check_repo_hygiene.py 通过git ls-files -z枚举全部受跟踪文件检查其中是否混入了本应再生成的产物FORBIDDEN_PARTS覆盖.DS_Store、.next、.next-deeptutor、.turbo、__pycache__、htmlcov、node_modules、playwright-report、test-resultsFORBIDDEN_SUFFIXES覆盖.pyc、.pyo并额外拦截web/out、web/dist等前端构建输出以及路径中的异常空白字符。发现违规时脚本建议用git rm --cached将其移出索引、保留本地文件而不是删除运行所需的本地产物。check_workspace_hygiene.py 更进一步要求git status --porcelain工作区完全干净含未跟踪文件否则提示先迁移到任务 worktree 再继续随后再委托执行check_repo_hygiene.py。这两条脚本同时被挂进了 pre-commit 的deeptutor-repo-hygiene本地钩子entry: python3 scripts/check_repo_hygiene.py保证每次提交都会触发。生成文件与 Worktree 管理构建产物必须留在 Git 之外。web/.next、node_modules、测试报告与字节码缓存都是可再生资源必须保持未跟踪状态若已误跟踪用git rm --cached移出索引不要删除应用运行所需的本地文件。新克隆的仓库可以启用零依赖的安全钩子git config core.hooksPath scripts/hooks该钩子scripts/hooks/pre-commit只依赖系统python3在完整安装 pre-commit 环境之前就能拒绝生成文件入库并拦截对main的直接提交。贡献者还应使用独立的 Git worktree进行特性开发保持主检出干净git worktree add ../DeepTutor-task -b branch dev这样构建、测试和长时间运行的 Agent 可以互不干扰地并行执行不会互相覆盖输出。移除 worktree 前必须提交或明确保留其变更不要把git reset --hard或git clean当作常规清理手段。代码质量与安全工具链CONTRIBUTING.md 声明仓库使用自动化工具维持高标准全部配置在pyproject.toml与.pre-commit-config.yaml中工具用途RuffPython 代码检查与格式化Prettier前端与配置文件格式化detect-secrets硬编码密钥扫描pip-audit依赖漏洞扫描Bandit安全问题分析MyPy静态类型检查InterrogateDocstring 覆盖率报告IMPORTANT本地 pre-commit 钩子可能只显示警告但CI 会执行严格检查并自动拒绝未通过的 PR。本地钩子的实际配置查看 .pre-commit-config.yaml 可以看到真实启用的钩子明细通用检查trailing-whitespace对 markdown 换行做了适配、end-of-file-fixer、check-yaml、check-json、check-added-large-files阈值--maxkb6144即约 6 MB 新增文件报警、check-merge-conflict、check-case-conflict、check-toml。Pythonruff--fix --quiet与ruff-format版本固定在 v0.16.0与 CI 安装版本保持一致避免本地格式化与 CI 的ruff format --check .因版本漂移产生分歧。前端本地prettier钩子prettier3.9.6仅作用于web/下的 CSS/SCSS/JSON/YAML/MD/TS/TSX/JS 等文件。安全detect-secrets基线.secrets.baseline排除package-lock.json、bandit读取pyproject.toml配置排除tests/。pip-audit因 pip-api 上游在 Windows 非 ASCII 路径下的缺陷中文用户名会触发 UnicodeDecodeError被暂时注释停用注释中记录了 issue 编号。pyproject.toml 中的工程化细节pyproject.toml 里的工具配置对贡献者同样重要Ruff目标 Python 3.11行宽 100lint 只启用基础规则Epycodestyle 错误、Fpyflakes、Iisort并额外开启B006禁止可变默认参数其余规则刻意保持宽松formatter 使用双引号、空格缩进、自动探测行尾。MyPyPython 3.11采用渐进式类型接管策略——disallow_untyped_defsfalse、ignore_missing_importstrue测试目录与deeptutor.tools.*单独配置忽略错误。Bandit跳过B101、B311、B110、B104、B603等规则每条跳过项都注释了理由例如B603是受控执行、B104是服务端绑定所需。Pytesttestpaths [tests, deeptutor/learning/tests]启用--strict-markers、--strict-config内置integration、redis_integration、real_llm_resolver等 marker。CI 严格门禁.github/workflows/tests.yml 展示了 PR 将被哪些环节严格把关Lint 与格式ruff check .ruff format --check .外加import-linter依赖边界检查和python scripts/check_architecture.py架构约束检查。前端npm run check完整确定性门禁 Playwright Chromium 交互/无障碍/视觉矩阵审计。导入检查Python 3.11–3.14 × Linux/macOS/Windows 矩阵验证关键模块可导入、工具实现保持冷加载惰性导入、隔离 Worker 协议可用。Python 测试3.11/3.12/3.13/3.14 四版本矩阵拉起 Redis 服务运行pytest -q tests deeptutor/learning/tests。本地钩子与 CI 的差异是设计使然本地宽松、CI 严格因此本地能过不等于PR 能过提交前请务必跑一遍完整的pre-commit run --all-files。编码规范CONTRIBUTING.md 对 Python 与文档分别给出硬性要求Python所有函数签名使用类型标注type hints。字符串格式化优先使用f-strings。遵循PEP 8由 Ruff 强制执行。函数保持短小聚焦只承担单一职责。Ruff 配置中mccabe复杂度上限为 10max-complexity 10这是小函数的量化约束B006的开启则提醒开发者不要使用可变数据结构作为参数默认值。文档每个新模块、类、公开函数都应有docstring格式遵循Google Python Style Guide。如果变更引入新功能或新配置必须同步更新README.md。提交信息格式DeepTutor 采用 Conventional Commits 风格格式为type: short description [optional body]各类型与版本语义对应如下类型描述feat新功能MINOR 版本号递增fix缺陷修复PATCH 版本号递增docs仅文档变更style格式调整无逻辑变更refactor代码重构无新功能或修复test新增或修正测试chore构建过程、工具链或依赖更新版本递增语义与仓库的发布节奏一致feat触发次版本号提升fix触发补丁号提升说明提交类型直接影响版本发布策略。安全最佳实践文件上传CONTRIBUTING.md 记录的上传安全基线为普通文件上限 100 MB、PDF 上限 50 MB采用多层验证扩展名 MIME 类型 内容净化所有文件名均做净化以防范路径穿越。需要说明的是文档记录的是较早的边界约定。以当前仓库源码为准DocumentValidator 中的实现已将上限统一为# Maximum file size in bytes (200MB), applied uniformly to every format. MAX_FILE_SIZE: ClassVar[int] 200 * 1024 * 1024即当前代码对所有格式统一按200 MiB执行大小检查在validate_upload_safety中file_size MAX_FILE_SIZE时抛出ValueError。knowledge.py 上传路由直接复用该常量并在流式写入时逐块累计字节数、超限即返回 400配合safe_extract_zip抵御 Zip Slip / zip-bomb 攻击。扩展名白名单覆盖 PDF、TXT、MD、DOC/DOCX、RTF、HTML、XML、JSON、CSV、XLS/XLSX、PPT/PPTX、EPUB 等常见文档格式MIME 类型白名单与之对应。净化逻辑在validate_upload_safety中完成先做 Unicode NFC 归一化剥离 POSIX 与 Windows 路径成分rsplit(/, 1)[-1]删除空字节与控制字符将 : / \ | ? *替换为下划线并统一小写扩展名。tests/utils/test_document_validator.py中的测试用例印证了这些行为中文资料/数学 讲义#1(最终版).PDF→数学 讲义#1(最终版).pdf保留 Unicode、统一扩展名大小写rC:\Users\frank\资料\报告.MD→报告.md剥离 Windows 路径成分METS Export.TAR.GZ→METS Export.tar.gz保留复合扩展名空扩展名策略allowed_extensionsset()用于由解析器做内容检测的场景.hidden这类隐藏文件会被拒绝开发规范子进程始终使用shellFalse以防范命令注入。仓库中deeptutor/runtime/isolated_worker.pysubprocess.Popen(..., shellFalse)、deeptutor/reading/ingestion.py、deeptutor/capabilities/audio_overview/pipeline.py等处的调用均以固定 argv 列表方式执行并辅以# nosec B603/B607注释说明受控执行原因。路径处理使用pathlib.Path保证跨平台兼容。行尾通过.gitattributes强制关键脚本使用LFUnix行尾防止 CRLF 在 Docker 容器和 shell 脚本中引发安全问题。查看 .gitattributes 可见*.py、*.yaml、*.yml、*.md、*.sh、Dockerfile、docker-compose*.yml等均被设置为text eollf。结语DeepTutor 的贡献体系是文档约定 本地钩子 CI 严格门禁三层协同分支策略由check_branch_policy.py强制兜底仓库卫生由check_repo_hygiene.py与check_workspace_hygiene.py双脚本把关代码质量由 Ruff/Prettier/detect-secrets/Bandit/MyPy 的本地 pre-commit 钩子与 CI 的ruff format --check .、import-linter、架构检查、跨版本测试矩阵共同守护。贡献者只需要记住核心动作目标分支选dev多租户特性选multi-user、从目标分支切特性分支、提交前跑pre-commit run --all-files、遵守 Conventional Commits 类型、按文档与源码中的安全基线处理上传与子进程。遇到问题可在仓库 Communication.md 中获取微信/飞书讨论群二维码与社区一起共建下一代智能辅导工具。赞分享人工智能AI 应用AI Agent多智能体RAG教育后端前端【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址https://gitcode.com/GitHub_Trending/dee/DeepTutor点击查看免费下载相关推荐贡献指南解读Kun 开源项目的分支策略、PR 规范与质量门禁实战贡献指南解读Kun 开源项目的分支策略、PR 规范与质量门禁实战 Kun 是一个 Local first 的 AI Agent 工作台 README.md人工智能AI Agent自主智能体桌面应用MCP Clientsopencodex 贡献指南分支策略、Pull Request 质量契约与 pre-push 门禁实战opencodex 贡献指南分支策略、Pull Request 质量契约与 pre push 门禁实战 opencodex 是一个面向 OpenAI Code人工智能LLM 网关API网关后端开发工具Kun 贡献指南全解析从分支策略到 CI 质量门禁的完整协作规范Kun 贡献指南全解析从分支策略到 CI 质量门禁的完整协作规范 Kun 是一个 Local first 的 AI Agent 工作空间一套运行时同时驱动桌人工智能AI Agent自主智能体桌面应用MCP Clients上一篇如何快速部署Open Notebook隐私优先笔记工具的完整指南下一篇Automa浏览器自动化扩展实战指南从问题诊断到高效解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考