Local Deep Research 开发者指南从环境搭建到测试、构建与排障的完整实战手册【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本指南以项目官方开发者文档 docs/developing.md 为核心骨架系统讲解 Local Deep Research 的本地开发全流程架构文档导航、前后端环境初始化、开发/生产模式运行、预发布镜像测试、包与前端资产构建、测试体系、加密数据库备份恢复以及高频故障的排查思路。读者读完将掌握一套可直接复制的开发工作流并能结合源码定位配置、线程与安全相关的关键机制。一、架构文档导航先读懂再动手在开始写代码前建议先通读项目沉淀的架构类文档它们分别覆盖了系统设计、数据模型、扩展点和工程化约束四个维度文档相对路径覆盖内容架构总览docs/architecture/OVERVIEW.md系统组件、研究执行流程、模块职责数据库模型docs/architecture/DATABASE_SCHEMA.md数据库模型与关系扩展指南docs/developing/EXTENDING.md如何新增自定义搜索引擎、策略与 LLM Provider测试与 CIdocs/CI_CD_INFRASTRUCTURE.mdGitHub Actions 工作流、pre-commit 钩子、安全扫描提交邮箱与署名docs/developing/commit-email-attribution.mdgit 邮箱如何影响 squash-merge 署名、如何避免私人邮箱进入仓库历史其中 架构总览 值得重点精读它用 Mermaid 图清晰刻画了ldr-webFastAPI 应用、REST API/api/v1、核心研究引擎SearchSystem→StrategyFactory→ReportGenerator、搜索层32 个搜索策略、30 搜索引擎、自适应限流、数据层每用户独立的 SQLCipher 加密库以及 LLM 层Provider/Embedding/Reranker之间的调用关系并给出了研究状态机QUEUED → IN_PROGRESS → COMPLETED / FAILED / SUSPENDED与线程模型。二、开发环境准备前置依赖一览根据 docs/developing.md 的 Prerequisites 小节本地开发需要以下工具链依赖版本要求用途Python3.12后端运行时pyproject.toml 中声明requires-python 3.12,3.15Node.js24.0.0前端 Vite 构建与 Puppeteer 测试Docker最新版生产镜像构建与运行PDM最新版Python 包管理项目锁文件为pdm.lockSQLCipher见下加密数据库底层库必装注意pyproject.toml的构建后端是pdm-backend依赖项里同时声明了sqlcipher3-binaryLinux x86_64与sqlcipher3ARM64/非 Linux两套绑定PDM 会按平台自动选择。SQLCipher 按平台安装SQLCipher 是每个用户数据含 API Key、研究成果静态加密的关键依赖详细步骤见 docs/SQLCIPHER_INSTALL.mdUbuntu/Debiansudo apt update sudo apt install sqlcipher libsqlcipher-dev随后pdm installmacOSbrew install sqlcipher必要时导出LDFLAGS-L$(brew --prefix sqlcipher)/lib与CPPFLAGS-I$(brew --prefix sqlcipher)/include再pdm installWindowssqlcipher30.6.2 提供预编译自包含 wheelx86/x64/ARM64Python 3.9–3.14pip install sqlcipher3即可无需编译。三、初始设置一键拉起后端 前端 Git Hooks按以下顺序完成首次开发环境初始化# 1. 克隆并进入仓库 git clone gitgithub.com:LearningCircuit/local-deep-research.git # 或 HTTPShttps://github.com/LearningCircuit/local-deep-research.git cd local-deep-research # 2. 后端创建虚拟环境并安装依赖 python -m venv .venv source .venv/bin/activate pip install pdm pdm install --no-self # 3. 前端安装 npm 依赖 npm install # 4. 安装 Git Hookspre-commit 框架 pre-commit install pre-commit install-hooks其中第 4 步很关键仓库通过pre-commit框架管理钩子除了ruff、eslint、gitleaks等标准检查外还挂载了位于 .pre-commit-hooks/ 的大量自定义本地钩子如check-env-vars强制环境变量走SettingsManager、check-deprecated-db-connection禁止共享ldr.db、check-pathlib-usage强制使用pathlib.Path等提交前会自动拦截常见问题。四、运行应用开发模式与生产模式4.1 开发模式热更新# 终端 1启动后端 source .venv/bin/activate ldr-web # 方式 A已安装的命令入口 # 或 python -m local_deep_research.web.app # 方式 B直接用 Python 模块 # 终端 2启动前端 Vite 开发服务器 npm run dev # 访问 http://localhost:5173从 入口文件 的源码可以看到ldr-web实际做了三件事安装全局线程异常钩子避免后台队列/调度线程静默崩溃、执行遗留 RAG docstore 的一次性清理迁移、再以workers1启动 uvicorn 加载 web/fastapi_app.py 中的 ASGI 应用——单 worker 是 Socket.IO 在无 Redis 消息队列下的硬性要求源码注释明确标注了这一约束。4.2 开发环境变量完整配置清单见 docs/CONFIGURATION.md。日常开发调试最常用的三个变量变量默认值说明LDR_DATA_DIR平台默认覆盖数据/数据库存储位置LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDfalse允许未加密数据库仅限开发CI或TESTING未设置开启测试模式绕过部分安全检查⚠️ 警告切勿在生产环境设置LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue否则用户数据将以明文存储。4.3 Docker类生产环境docker build -t localdeepresearch/local-deep-research:dev . docker run -p 5000:5000 -e LDR_DATA_DIR/data -v ldr_data:/data localdeepresearch/local-deep-research:dev4.4 测试预发布镜像RC 版每次发版时.github/workflows/prerelease-docker.yml会向 Docker Hub 发布两种标签prerelease-vX.Y.Z-sha不可变、精确锁定单个构建适合复现 Bug 时使用的确定测试目标prerelease浮动的别名始终指向最新 RC适合快速尝鲜下一版。推荐的隔离测试姿势在docker-compose.yml中追加一个独立 service使用不同端口和独立卷避免 RC 的迁移脚本破坏生产库local-deep-research-pre: image: localdeepresearch/local-deep-research:prerelease container_name: local-deep-research-pre networks: - ldr-network extra_hosts: - host.docker.internal:host-gateway ports: - 5001:5000 # 生产仍占用 5000 environment: - LDR_WEB_HOST0.0.0.0 - LDR_WEB_PORT5000 - LDR_DATA_DIR/data - LDR_LLM_OLLAMA_URLhttp://ollama:11434 - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://searxng:8080 volumes: - ldr_data_pre:/data # ← 与生产的 ldr_data 隔离 - ldr_scripts_pre:/scripts restart: unless-stopped volumes: ldr_data_pre: ldr_scripts_pre:记得从主local-deep-researchservice 复制ulimits、security_opt、cap_drop、cap_add等加固块——它们不是可选项而是正确启动的前置条件。启动与升级 RCdocker compose pull local-deep-research-pre docker compose up -d local-deep-research-pre # UI 地址http://localhost:5001 # 新版 RC 发布后重复执行上面的 pull up -d 即可升级五、构建Python 包与前端资产5.1 构建 Python 发行包pdm build生成 wheel 与源码分发包。项目的ldr-web与ldr-mcp两个 console script 入口在 pyproject.toml 中声明分别指向local_deep_research.web.app:main和local_deep_research.mcp:run_server。5.2 构建前端资产从源码开发 Web UI 时需要手动构建 Vite 前端npm install npm run build产物输出到src/local_deep_research/web/static/dist/。对 pip 用户无需此步——PyPI 发布的包已内置预构建资产。5.3 依赖锁文件管理pdm.lock项目用PDM与pdm.lock精确锁定依赖版本保证可复现构建。若 Docker 构建时出现WARNING: Lockfile hash doesnt match pyproject.toml, packages may be outdated说明pyproject.toml已变更但锁文件未重新生成执行修复pdm lock务必把pdm.lock与pyproject.toml的改动一并提交确保构建可复现。六、测试体系三种测试模式怎么选6.1 后端隔离测试默认推荐无需起服务基于 FastAPI 的TestClient底层为 Starlettemock 服务器是日常单元/集成测试的首选source .venv/bin/activate pytest tests/ # 运行全部隔离测试 pytest tests/api_tests/ # 指定 API 测试 pytest tests/auth_tests/ # 指定认证测试仓库测试目录 tests/ 结构清晰除api_tests/、auth_tests/外还包括security/、database/、llm_providers/、connected/真实每用户加密 SQLCipher 库的联通测试、infrastructure_tests/等专项目录conftest.py提供了统一的 mock 与 fixture。6.2 在线系统测试需真实运行的服务对运行中的应用实例发起真实 HTTP 请求# 前提先在终端 1 启动后端 ldr-web或 Docker python tests/ui_tests/test_simple_research_api.py6.3 前端与 E2E 测试Puppeteer项目用 Puppeteer 做 UI 与端到端测试cd tests # 进入测试目录 npm install # 安装测试依赖 # 前提应用已在本地 5000 端口或 Docker运行 node tests/ui_tests/run_all_ui_tests.js # 全部 UI 测试 node tests/ui_tests/test_simple_auth.js # 单个测试关于测试标记pyproject.toml 定义了requires_llm、integration、slow、asyncio、serial、nonroot、connected、lifespan等 pytest marker其中serial/nonroot涉及进程全局状态与权限断言CI 中需要在专门的容器步骤里以非 root 用户执行本地跑全量测试时留意这些约束即可。七、数据库管理备份与恢复创建备份docker run --rm \ -v ldr_data:/from \ -v ldr_data-backup:/to \ debian:latest \ bash -c cd /from ; tar -cf - . | (cd /to ; tar -xpf -)从备份恢复⚠️ 警告以下操作会覆盖现有数据docker run --rm \ -v ldr_data:/target \ -v ldr_data-backup:/source \ debian:latest \ bash -c rm -rf /target/* /target/.[!.]* ; \ cd /source ; tar -cf - . | (cd /target ; tar -xpf -)关于加密数据库的安全设计docs/architecture/DATABASE_SCHEMA.md 描述了每用户独立 SQLCipher 库的模型关系docs/security/database-backup.md 提供了更细粒度的备份安全说明。八、故障排查速查表8.1 SQLCipher 相关错误见 docs/SQLCIPHER_INSTALL.md#troubleshooting 的排障小节覆盖各类平台下的编译/加载失败场景。8.2 Docker 卷权限拒绝报错PermissionError: [Errno 13] Permission denied: /app/.config/...原因卷可能由不同属主创建。解决docker volume rm ldr_data # 重新运行容器以创建全新卷8.3 服务重启后会话丢失原因应用使用密钥签名会话 Cookie。解决密钥在首次运行时自动生成并持久化到数据目录由LDR_DATA_DIR控制下的.secret_key文件中。只有删除该文件才会丢会话。若用 Docker请确保数据卷ldr_data:/data持久化。8.4 后台线程报 NoSettingsContextError报错NoSettingsContextError: No settings context available原因后台线程不继承线程本地的设置上下文见 config/thread_settings.py该上下文按线程而非按请求建立。解决应用已自动处理此场景开发中如遇此类报错请先在 Web UI 设置页确认 LLM 设置已配置。这也是 架构总览 中每个研究线程持有独立设置快照、避免配置变更竞态这一线程模型的直接体现。8.5 PDM 锁文件不同步报错Lockfile hash doesnt match pyproject.toml解决pdm lock git add pdm.lock九、开发最佳实践小结贯穿整份开发者指南的几个工程化要点值得沉淀为团队约定提交前检查靠钩子pre-commit install后标准钩子ruff/eslint/gitleaks与 .pre-commit-hooks/ 中 50 个自定义钩子共同构成质量红线其中安全类钩子check-sensitive-logging、check-safe-requests、check-image-pinning直接对齐 docs/CI_CD_INFRASTRUCTURE.md 描述的供应链与运行时安全策略。锁文件是构建契约任何pyproject.toml变更都必须同步pdm lock否则 Docker 与 CI 都会告警。数据隔离是安全底线开发期可用LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue加速迭代但生产环境必须保持加密数据库SQLCipher与独立卷ldr_data配置LDR_DATA_DIR统一管理数据落盘位置。测试分层执行日常用隔离 pytest涉及真实 HTTP 与浏览器行为时切到在线脚本与 Puppeteer E2E尊重serial/nonroot等特殊 marker 的运行前提。如需继续深入推荐依次阅读 docs/developing/EXTENDING.md自定义搜索/策略/LLM 提供方、docs/architecture/DATABASE_SCHEMA.md数据模型与 docs/CONFIGURATION.md全量环境变量清单把能跑起来升级为能按需扩展。【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Local Deep Research 开发者指南：从环境搭建到测试、构建与排障的完整实战手册
Local Deep Research 开发者指南从环境搭建到测试、构建与排障的完整实战手册【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本指南以项目官方开发者文档 docs/developing.md 为核心骨架系统讲解 Local Deep Research 的本地开发全流程架构文档导航、前后端环境初始化、开发/生产模式运行、预发布镜像测试、包与前端资产构建、测试体系、加密数据库备份恢复以及高频故障的排查思路。读者读完将掌握一套可直接复制的开发工作流并能结合源码定位配置、线程与安全相关的关键机制。一、架构文档导航先读懂再动手在开始写代码前建议先通读项目沉淀的架构类文档它们分别覆盖了系统设计、数据模型、扩展点和工程化约束四个维度文档相对路径覆盖内容架构总览docs/architecture/OVERVIEW.md系统组件、研究执行流程、模块职责数据库模型docs/architecture/DATABASE_SCHEMA.md数据库模型与关系扩展指南docs/developing/EXTENDING.md如何新增自定义搜索引擎、策略与 LLM Provider测试与 CIdocs/CI_CD_INFRASTRUCTURE.mdGitHub Actions 工作流、pre-commit 钩子、安全扫描提交邮箱与署名docs/developing/commit-email-attribution.mdgit 邮箱如何影响 squash-merge 署名、如何避免私人邮箱进入仓库历史其中 架构总览 值得重点精读它用 Mermaid 图清晰刻画了ldr-webFastAPI 应用、REST API/api/v1、核心研究引擎SearchSystem→StrategyFactory→ReportGenerator、搜索层32 个搜索策略、30 搜索引擎、自适应限流、数据层每用户独立的 SQLCipher 加密库以及 LLM 层Provider/Embedding/Reranker之间的调用关系并给出了研究状态机QUEUED → IN_PROGRESS → COMPLETED / FAILED / SUSPENDED与线程模型。二、开发环境准备前置依赖一览根据 docs/developing.md 的 Prerequisites 小节本地开发需要以下工具链依赖版本要求用途Python3.12后端运行时pyproject.toml 中声明requires-python 3.12,3.15Node.js24.0.0前端 Vite 构建与 Puppeteer 测试Docker最新版生产镜像构建与运行PDM最新版Python 包管理项目锁文件为pdm.lockSQLCipher见下加密数据库底层库必装注意pyproject.toml的构建后端是pdm-backend依赖项里同时声明了sqlcipher3-binaryLinux x86_64与sqlcipher3ARM64/非 Linux两套绑定PDM 会按平台自动选择。SQLCipher 按平台安装SQLCipher 是每个用户数据含 API Key、研究成果静态加密的关键依赖详细步骤见 docs/SQLCIPHER_INSTALL.mdUbuntu/Debiansudo apt update sudo apt install sqlcipher libsqlcipher-dev随后pdm installmacOSbrew install sqlcipher必要时导出LDFLAGS-L$(brew --prefix sqlcipher)/lib与CPPFLAGS-I$(brew --prefix sqlcipher)/include再pdm installWindowssqlcipher30.6.2 提供预编译自包含 wheelx86/x64/ARM64Python 3.9–3.14pip install sqlcipher3即可无需编译。三、初始设置一键拉起后端 前端 Git Hooks按以下顺序完成首次开发环境初始化# 1. 克隆并进入仓库 git clone gitgithub.com:LearningCircuit/local-deep-research.git # 或 HTTPShttps://github.com/LearningCircuit/local-deep-research.git cd local-deep-research # 2. 后端创建虚拟环境并安装依赖 python -m venv .venv source .venv/bin/activate pip install pdm pdm install --no-self # 3. 前端安装 npm 依赖 npm install # 4. 安装 Git Hookspre-commit 框架 pre-commit install pre-commit install-hooks其中第 4 步很关键仓库通过pre-commit框架管理钩子除了ruff、eslint、gitleaks等标准检查外还挂载了位于 .pre-commit-hooks/ 的大量自定义本地钩子如check-env-vars强制环境变量走SettingsManager、check-deprecated-db-connection禁止共享ldr.db、check-pathlib-usage强制使用pathlib.Path等提交前会自动拦截常见问题。四、运行应用开发模式与生产模式4.1 开发模式热更新# 终端 1启动后端 source .venv/bin/activate ldr-web # 方式 A已安装的命令入口 # 或 python -m local_deep_research.web.app # 方式 B直接用 Python 模块 # 终端 2启动前端 Vite 开发服务器 npm run dev # 访问 http://localhost:5173从 入口文件 的源码可以看到ldr-web实际做了三件事安装全局线程异常钩子避免后台队列/调度线程静默崩溃、执行遗留 RAG docstore 的一次性清理迁移、再以workers1启动 uvicorn 加载 web/fastapi_app.py 中的 ASGI 应用——单 worker 是 Socket.IO 在无 Redis 消息队列下的硬性要求源码注释明确标注了这一约束。4.2 开发环境变量完整配置清单见 docs/CONFIGURATION.md。日常开发调试最常用的三个变量变量默认值说明LDR_DATA_DIR平台默认覆盖数据/数据库存储位置LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDfalse允许未加密数据库仅限开发CI或TESTING未设置开启测试模式绕过部分安全检查⚠️ 警告切勿在生产环境设置LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue否则用户数据将以明文存储。4.3 Docker类生产环境docker build -t localdeepresearch/local-deep-research:dev . docker run -p 5000:5000 -e LDR_DATA_DIR/data -v ldr_data:/data localdeepresearch/local-deep-research:dev4.4 测试预发布镜像RC 版每次发版时.github/workflows/prerelease-docker.yml会向 Docker Hub 发布两种标签prerelease-vX.Y.Z-sha不可变、精确锁定单个构建适合复现 Bug 时使用的确定测试目标prerelease浮动的别名始终指向最新 RC适合快速尝鲜下一版。推荐的隔离测试姿势在docker-compose.yml中追加一个独立 service使用不同端口和独立卷避免 RC 的迁移脚本破坏生产库local-deep-research-pre: image: localdeepresearch/local-deep-research:prerelease container_name: local-deep-research-pre networks: - ldr-network extra_hosts: - host.docker.internal:host-gateway ports: - 5001:5000 # 生产仍占用 5000 environment: - LDR_WEB_HOST0.0.0.0 - LDR_WEB_PORT5000 - LDR_DATA_DIR/data - LDR_LLM_OLLAMA_URLhttp://ollama:11434 - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URLhttp://searxng:8080 volumes: - ldr_data_pre:/data # ← 与生产的 ldr_data 隔离 - ldr_scripts_pre:/scripts restart: unless-stopped volumes: ldr_data_pre: ldr_scripts_pre:记得从主local-deep-researchservice 复制ulimits、security_opt、cap_drop、cap_add等加固块——它们不是可选项而是正确启动的前置条件。启动与升级 RCdocker compose pull local-deep-research-pre docker compose up -d local-deep-research-pre # UI 地址http://localhost:5001 # 新版 RC 发布后重复执行上面的 pull up -d 即可升级五、构建Python 包与前端资产5.1 构建 Python 发行包pdm build生成 wheel 与源码分发包。项目的ldr-web与ldr-mcp两个 console script 入口在 pyproject.toml 中声明分别指向local_deep_research.web.app:main和local_deep_research.mcp:run_server。5.2 构建前端资产从源码开发 Web UI 时需要手动构建 Vite 前端npm install npm run build产物输出到src/local_deep_research/web/static/dist/。对 pip 用户无需此步——PyPI 发布的包已内置预构建资产。5.3 依赖锁文件管理pdm.lock项目用PDM与pdm.lock精确锁定依赖版本保证可复现构建。若 Docker 构建时出现WARNING: Lockfile hash doesnt match pyproject.toml, packages may be outdated说明pyproject.toml已变更但锁文件未重新生成执行修复pdm lock务必把pdm.lock与pyproject.toml的改动一并提交确保构建可复现。六、测试体系三种测试模式怎么选6.1 后端隔离测试默认推荐无需起服务基于 FastAPI 的TestClient底层为 Starlettemock 服务器是日常单元/集成测试的首选source .venv/bin/activate pytest tests/ # 运行全部隔离测试 pytest tests/api_tests/ # 指定 API 测试 pytest tests/auth_tests/ # 指定认证测试仓库测试目录 tests/ 结构清晰除api_tests/、auth_tests/外还包括security/、database/、llm_providers/、connected/真实每用户加密 SQLCipher 库的联通测试、infrastructure_tests/等专项目录conftest.py提供了统一的 mock 与 fixture。6.2 在线系统测试需真实运行的服务对运行中的应用实例发起真实 HTTP 请求# 前提先在终端 1 启动后端 ldr-web或 Docker python tests/ui_tests/test_simple_research_api.py6.3 前端与 E2E 测试Puppeteer项目用 Puppeteer 做 UI 与端到端测试cd tests # 进入测试目录 npm install # 安装测试依赖 # 前提应用已在本地 5000 端口或 Docker运行 node tests/ui_tests/run_all_ui_tests.js # 全部 UI 测试 node tests/ui_tests/test_simple_auth.js # 单个测试关于测试标记pyproject.toml 定义了requires_llm、integration、slow、asyncio、serial、nonroot、connected、lifespan等 pytest marker其中serial/nonroot涉及进程全局状态与权限断言CI 中需要在专门的容器步骤里以非 root 用户执行本地跑全量测试时留意这些约束即可。七、数据库管理备份与恢复创建备份docker run --rm \ -v ldr_data:/from \ -v ldr_data-backup:/to \ debian:latest \ bash -c cd /from ; tar -cf - . | (cd /to ; tar -xpf -)从备份恢复⚠️ 警告以下操作会覆盖现有数据docker run --rm \ -v ldr_data:/target \ -v ldr_data-backup:/source \ debian:latest \ bash -c rm -rf /target/* /target/.[!.]* ; \ cd /source ; tar -cf - . | (cd /target ; tar -xpf -)关于加密数据库的安全设计docs/architecture/DATABASE_SCHEMA.md 描述了每用户独立 SQLCipher 库的模型关系docs/security/database-backup.md 提供了更细粒度的备份安全说明。八、故障排查速查表8.1 SQLCipher 相关错误见 docs/SQLCIPHER_INSTALL.md#troubleshooting 的排障小节覆盖各类平台下的编译/加载失败场景。8.2 Docker 卷权限拒绝报错PermissionError: [Errno 13] Permission denied: /app/.config/...原因卷可能由不同属主创建。解决docker volume rm ldr_data # 重新运行容器以创建全新卷8.3 服务重启后会话丢失原因应用使用密钥签名会话 Cookie。解决密钥在首次运行时自动生成并持久化到数据目录由LDR_DATA_DIR控制下的.secret_key文件中。只有删除该文件才会丢会话。若用 Docker请确保数据卷ldr_data:/data持久化。8.4 后台线程报 NoSettingsContextError报错NoSettingsContextError: No settings context available原因后台线程不继承线程本地的设置上下文见 config/thread_settings.py该上下文按线程而非按请求建立。解决应用已自动处理此场景开发中如遇此类报错请先在 Web UI 设置页确认 LLM 设置已配置。这也是 架构总览 中每个研究线程持有独立设置快照、避免配置变更竞态这一线程模型的直接体现。8.5 PDM 锁文件不同步报错Lockfile hash doesnt match pyproject.toml解决pdm lock git add pdm.lock九、开发最佳实践小结贯穿整份开发者指南的几个工程化要点值得沉淀为团队约定提交前检查靠钩子pre-commit install后标准钩子ruff/eslint/gitleaks与 .pre-commit-hooks/ 中 50 个自定义钩子共同构成质量红线其中安全类钩子check-sensitive-logging、check-safe-requests、check-image-pinning直接对齐 docs/CI_CD_INFRASTRUCTURE.md 描述的供应链与运行时安全策略。锁文件是构建契约任何pyproject.toml变更都必须同步pdm lock否则 Docker 与 CI 都会告警。数据隔离是安全底线开发期可用LDR_BOOTSTRAP_ALLOW_UNENCRYPTEDtrue加速迭代但生产环境必须保持加密数据库SQLCipher与独立卷ldr_data配置LDR_DATA_DIR统一管理数据落盘位置。测试分层执行日常用隔离 pytest涉及真实 HTTP 与浏览器行为时切到在线脚本与 Puppeteer E2E尊重serial/nonroot等特殊 marker 的运行前提。如需继续深入推荐依次阅读 docs/developing/EXTENDING.md自定义搜索/策略/LLM 提供方、docs/architecture/DATABASE_SCHEMA.md数据模型与 docs/CONFIGURATION.md全量环境变量清单把能跑起来升级为能按需扩展。【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考