Merge remote master docs

offline-backend-20260512/backend/CLAUDE.md

@@ -566,6 +566,7 @@ See `docs/` directory for detailed documentation:
 - [API.md](docs/API.md) - API reference
 - [SETUP.md](docs/SETUP.md) - Setup guide
 - [FILE_UPLOAD.md](docs/FILE_UPLOAD.md) - File upload feature
-- [PATH_EXAMPLES.md](docs/PATH_EXAMPLES.md) - Path types and usage
-- [summarization.md](docs/summarization.md) - Context summarization
-- [plan_mode_usage.md](docs/plan_mode_usage.md) - Plan mode with TodoList
+- [PATH_EXAMPLES.md](docs/PATH_EXAMPLES.md) - Path types and usage
+- [summarization.md](docs/summarization.md) - Context summarization
+- [plan_mode_usage.md](docs/plan_mode_usage.md) - Plan mode with TodoList
+- [BACKEND_RUN_STOP_ZH.md](docs/BACKEND_RUN_STOP_ZH.md) - Windows-first backend start/stop and troubleshooting guide

offline-backend-20260512/backend/README.md

@@ -408,10 +408,11 @@ uv run pytest
 - [Architecture Details](docs/ARCHITECTURE.md)
 - [API Reference](docs/API.md)
 - [File Upload](docs/FILE_UPLOAD.md)
-- [Path Examples](docs/PATH_EXAMPLES.md)
-- [Context Summarization](docs/summarization.md)
-- [Plan Mode](docs/plan_mode_usage.md)
-- [Setup Guide](docs/SETUP.md)
+- [Path Examples](docs/PATH_EXAMPLES.md)
+- [Context Summarization](docs/summarization.md)
+- [Plan Mode](docs/plan_mode_usage.md)
+- [Backend Run/Stop Guide (ZH)](docs/BACKEND_RUN_STOP_ZH.md)
+- [Setup Guide](docs/SETUP.md)
 
 ---
 

offline-backend-20260512/backend/docs/BACKEND_RUN_STOP_ZH.md

@@ -0,0 +1,126 @@
+# 后端启动与停止说明（Windows 优先）
+
+本文档用于 `offline-backend-20260512/backend` 目录下 DeerFlow 后端的日常启动、停止与排障。
+
+## 1. 前置条件
+
+- 已安装 Python 3.12+
+- 已安装 `uv`
+- 已在项目中准备好配置文件（通常是项目根目录 `config.yaml`）
+
+## 2. 进入后端目录
+
+```powershell
+cd F:\react\deeflow-code\deerflow-server-master\offline-backend-20260512\backend
+```
+
+## 3. 首次安装依赖
+
+### 方案 A（优先，跨平台）
+
+```powershell
+uv sync
+```
+
+### 方案 B（如果你的环境里 `make` 可用）
+
+```powershell
+make install
+```
+
+> Windows 上部分 `make.exe` 与 GNU Make 不兼容，若报错请直接使用 `uv sync`。
+
+## 4. 启动后端
+
+### 4.1 生产样式（无热重载）
+
+```powershell
+$env:PYTHONPATH='.'
+uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+```
+
+### 4.2 开发样式（热重载）
+
+```powershell
+$env:PYTHONPATH='.'
+uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
+```
+
+如果你的 `make` 可用，也可以：
+
+```powershell
+make gateway   # 无热重载
+make dev       # 热重载
+```
+
+## 5. 验证是否启动成功
+
+启动后可访问：
+
+- 文档页：`http://127.0.0.1:8001/docs`
+- OpenAPI：`http://127.0.0.1:8001/openapi.json`
+- 健康检查：`http://127.0.0.1:8001/health`
+
+PowerShell 快速检查：
+
+```powershell
+(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8001/health).StatusCode
+```
+
+返回 `200` 即正常。
+
+## 6. 停止后端
+
+### 6.1 前台启动时
+
+在运行窗口按 `Ctrl + C`。
+
+### 6.2 后台或端口占用时（Windows）
+
+按 8001 端口查进程并强制结束：
+
+```powershell
+Get-NetTCPConnection -LocalPort 8001 -State Listen | Select-Object OwningProcess
+Stop-Process -Id <PID> -Force
+```
+
+一键方式（自动停止 8001 的监听进程）：
+
+```powershell
+$procIds = @(Get-NetTCPConnection -LocalPort 8001 -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess -Unique)
+foreach ($oneId in $procIds) { Stop-Process -Id $oneId -Force -ErrorAction SilentlyContinue }
+```
+
+## 7. 常见问题
+
+### 7.1 `make gateway` 报 unknown action keyword
+
+说明当前 `make` 不是预期版本（Windows 常见）。直接改用：
+
+```powershell
+$env:PYTHONPATH='.'
+uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+```
+
+### 7.2 PowerShell 报 `&&` 语法错误
+
+PowerShell 5 不支持 Bash 风格 `&&`。请改成分号：
+
+```powershell
+uv sync; $env:PYTHONPATH='.'; uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+```
+
+### 7.3 Git 切分支时 `.deer-flow/data/*.db-wal|*.db-shm` 无法删除
+
+通常是后端进程仍占用 SQLite 文件。先停掉 8001 端口进程，再执行 Git 操作。
+
+## 8. 推荐日常流程（Windows）
+
+```powershell
+cd F:\react\deeflow-code\deerflow-server-master\offline-backend-20260512\backend
+uv sync
+$env:PYTHONPATH='.'
+uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
+```
+
+停止时按 `Ctrl + C`。