feat(scripts): 新增本地调试与示例启动脚本，并登记进 apps/README

新增 4 个脚本，统一子命令风格（start/stop/restart/status/logs/run）： - scripts/dev-gateway.sh：方式 B，只起 Gateway(:8001)，用 backend/.venv 虚拟环境，自动加载 .env、释放端口、等待就绪；带 PID/日志文件，可查状态与跟随日志。 - scripts/dev-full.sh：方式 A，复用 serve.sh 守护模式起全量栈(Gateway+前端+nginx)，补齐 serve.sh 缺失的 status 与 logs；restart 默认跳过依赖安装，统一入口 :2026。 - apps/examples/http-chat/run.sh：自动探测网关(:2026 优先，回退 :8001)，优先 uv 临时环境带 requests(--no-project，不污染系统)，无 uv 时回退 venv+pip。 - apps/examples/embedded-chat/run.sh：自动定位 backend、加载 .env 后用 uv run 运行，内嵌 SDK 模式无需起服务。 apps/README.md 增加「本地调试脚本」与「运行示例」两节，说明上述脚本用法。全部脚本均已本地实跑验证：全量栈三服务 HTTP 200，两个示例多轮对话正常。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-27 22:47:30 +08:00
parent 7dfc9968fe
commit dd1d40368d
5 changed files with 455 additions and 0 deletions
@@ -23,6 +23,20 @@ apps/                                ← 你的应用（消费 deerflow，不反

 > 还有第三种：LangGraph SDK（`langgraph_sdk.get_client(url=".../api")`，graph id `lead_agent`），用于接入 LangGraph 生态工具链。需要的话照 HTTP 示例的鉴权流程拿 cookie 即可。

+### 运行示例（每个示例自带 run.sh）
+
+```bash
+# ① HTTP 模式：需要先起 Gateway（dev-gateway 或 dev-full 都行）
+#    run.sh 会自动探测网关地址：优先 :2026，回退 :8001
+./apps/examples/http-chat/run.sh
+DF_BASE=http://localhost:8001 ./apps/examples/http-chat/run.sh   # 也可手动指定
+
+# ② 内嵌模式：不需要起任何服务，run.sh 自动进 backend uv 环境运行
+./apps/examples/embedded-chat/run.sh
+```
+
+http-chat 的 `run.sh` 优先用 `uv run --no-project --with requests`（临时环境，不污染系统），没有 uv 才回退到本地 `.venv` + pip；可用 `DF_BASE` / `DF_EMAIL` / `DF_PASSWORD` 覆盖。embedded-chat 的 `run.sh` 自动定位 `backend/`、加载 `.env` 后用 `uv run` 启动，依赖 `config.yaml` 里有可用模型。
+
 ## 前置：先把 DeerFlow 跑起来

 在**仓库根目录**：
@@ -33,6 +47,29 @@ make dev          # 起 Gateway(8001) + 前端(3000) + nginx(2026)，统一入

 确保 `config.yaml` 里至少配了一个可用模型 + API key。

+### 本地调试脚本（推荐）
+
+`make dev` 是前台阻塞运行。日常调试更顺手的是仓库根 `scripts/` 下两个生命周期脚本，子命令统一为 `start / stop / restart / status / logs / run`：
+
+| 脚本 | 起什么 | 入口 | 适合 |
+|---|---|---|---|
+| `scripts/dev-gateway.sh` | 只起 Gateway | `http://localhost:8001` | 调后端 API / 接入示例，起得快 |
+| `scripts/dev-full.sh` | Gateway + 前端 + nginx | `http://localhost:2026` | 连前端一起调，完整体验 |
+
+```bash
+./scripts/dev-gateway.sh start          # 后台启动，等就绪后返回
+./scripts/dev-gateway.sh status         # PID / 端口 / HTTP 健康检查
+./scripts/dev-gateway.sh logs           # tail -f 跟随日志（不影响服务）
+./scripts/dev-gateway.sh stop
+
+./scripts/dev-full.sh start             # 全量栈后台启动（首次装依赖）
+SKIP_INSTALL=1 ./scripts/dev-full.sh start   # 跳过依赖安装，重启更快
+./scripts/dev-full.sh status            # 三服务一览
+./scripts/dev-full.sh run               # 前台运行（= make dev，gateway 带热重载）
+```
+
+环境变量：`PORT=`(换端口)、`NO_RELOAD=1`(关热重载，断点更稳)、`SKIP_INSTALL=1`(全量栈跳过装依赖)。
+
 ## 鉴权（HTTP 模式必读）

 Gateway 是 **fail-closed** 的——除少数公开路径外所有请求都要带会话 cookie：
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# embedded-chat 示例启动脚本
+# ------------------------------------------------------------------
+# 内嵌 SDK 模式：进程内直接 import deerflow.*，不需要起任何服务。
+# 必须在 backend 的 uv 虚拟环境里跑（才能解析 deerflow-harness / app 包），
+# 本脚本自动 cd 到 backend 并用 uv run 启动。
+#
+# 用法：
+#     ./run.sh
+#
+# 前提：
+#     - 已 `cd backend && uv sync`（或跑过任意一个 dev 脚本，venv 已建好）
+#     - config.yaml 里配好至少一个可用模型 + API key
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+APP="$SCRIPT_DIR/app.py"
+BACKEND="$REPO_ROOT/backend"
+
+# ── 前置检查 ──────────────────────────────────────────────────────
+command -v uv >/dev/null 2>&1 || { echo "✗ 未找到 uv。安装：curl -LsSf https://astral.sh/uv/install.sh | sh" >&2; exit 1; }
+[ -f "$REPO_ROOT/config.yaml" ] || echo "⚠ 未找到 $REPO_ROOT/config.yaml —— 没有可用模型会启动失败" >&2
+
+if [ ! -d "$BACKEND/.venv" ]; then
+    echo "→ 未发现 backend/.venv，执行 uv sync"
+    (cd "$BACKEND" && uv sync)
+fi
+
+# ── 加载 .env（模型 key / 数据库等）──────────────────────────────
+if [ -f "$REPO_ROOT/.env" ]; then
+    set -a
+    # shellcheck disable=SC1091
+    source "$REPO_ROOT/.env"
+    set +a
+fi
+
+# ── 在 backend uv 环境里运行（config.yaml 解析依赖运行目录为 backend/）──
+echo "→ 在 backend uv 环境中运行 embedded-chat"
+cd "$BACKEND"
+exec env PYTHONPATH=. uv run python "$APP"
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+#
+# http-chat 示例启动脚本
+# ------------------------------------------------------------------
+# - 自动探测网关地址：优先 :2026(nginx 全量栈)，回退 :8001(只起 Gateway)
+# - 优先用 uv 临时虚拟环境带上 requests（--no-project，不污染系统/项目）
+#   没有 uv 时回退到本地 .venv + pip
+#
+# 用法：
+#     ./run.sh                      # 自动探测网关并运行
+#     DF_BASE=http://localhost:8001 ./run.sh   # 手动指定网关
+#     DF_EMAIL=a@b.com DF_PASSWORD=xxxx ./run.sh
+#
+# 前提：先起好 Gateway
+#     ../../../scripts/dev-gateway.sh start   # → :8001
+#     ../../../scripts/dev-full.sh   start   # → :2026
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# ── 探测可用网关 ──────────────────────────────────────────────────
+_alive() { curl -s -o /dev/null -w "%{http_code}" "$1/api/v1/auth/setup-status" 2>/dev/null | grep -qE "200|429"; }
+
+if [ -z "${DF_BASE:-}" ]; then
+    if   _alive "http://localhost:2026"; then DF_BASE="http://localhost:2026"
+    elif _alive "http://localhost:8001"; then DF_BASE="http://localhost:8001"
+    else
+        echo "✗ 没探测到运行中的网关（:2026 / :8001 都不通）。" >&2
+        echo "  先启动：scripts/dev-gateway.sh start  或  scripts/dev-full.sh start" >&2
+        echo "  或手动指定：DF_BASE=http://your-host:port ./run.sh" >&2
+        exit 1
+    fi
+fi
+export DF_BASE
+echo "→ 使用网关: $DF_BASE"
+
+# ── 运行：优先 uv，回退 venv+pip ─────────────────────────────────
+if command -v uv >/dev/null 2>&1; then
+    echo "→ uv 临时环境运行（--with requests）"
+    exec uv run --no-project --with "requests>=2.31" python app.py
+else
+    echo "→ 未找到 uv，使用本地 .venv + pip"
+    if [ ! -d .venv ]; then
+        python3 -m venv .venv
+        ./.venv/bin/pip install -q -r requirements.txt
+    fi
+    exec ./.venv/bin/python app.py
+fi