# Web App 站点模板（templates/web-app-template）

DeerFlow「Web App 产物模式」的站点脚手架：智能体在沙箱里 `scaffold` 本模板到
`outputs/<site>/`，改 `site.json`、写 `src/pages/*.tsx`、放数据到 `public/`，
再由 `scripts/build_site.py build` 用**预置依赖**执行 vite build 产出 `dist/`，
经平台签名静态托管在「站点预览」工作台（前端路由 `#/sites/{threadId}/{siteName}`）打开。

## 目录约定

- `site.json` — 站点清单：`title` / `description` / `nav[]`（页面导航顺序）/
  `map`（可选底图：`tilesUrl` XYZ 模板或 `pmtiles` 单文件；都留空 = 无底图纯 GeoJSON 模式，离线可用）
- `src/pages/**/*.tsx` — 每个文件即一个页面，文件名（去扩展名）即路由（`overview.tsx` → `/#/overview`），自动注册
- `src/components/` — 内置组件：`AppShell`（导航壳）、`FlowCanvas`（@xyflow/react 交互流程图）、
  `GeoMap`（MapLibre 地图）、`ChartPanel`（ECharts）、`MermaidBlock`（Mermaid 静态图）
- `public/` — GeoJSON / 数据文件，页面内 `fetch("./data.geojson")` 相对加载
- `scripts/build_site.py` — 构建 CLI（check / scaffold / build / status，输出单行 JSON）

## 依赖预置与开启步骤（关键：默认完全关闭，离线环境不跑 npm install）

`node_modules/` 已 gitignore，**永远不要提交，也永远不要在沙箱里安装**：

- **开发机**：`make webapp-template`（即在本目录 `pnpm install && pnpm build`）一次性生成；
- **离线发版**：`deerflow-offline-deployment` 仓库的构建脚本需在有网的 CI 上执行
  `pnpm install --frozen-lockfile`（或 `npm ci`），把整个 `node_modules/` 随镜像预置到
  `/app/backend/templates/web-app-template/node_modules`。
  构建脚本会用 symlink（Linux）/ junction（Windows `mklink /J`，免管理员）把预置依赖
  链进各站点目录，多站点共享、零拷贝。

**开启功能 = config.yaml 里同时放开两处注释**（缺一不可）：

1. `sandbox.mounts` 里的模板挂载条目（沙箱技能经 `/mnt/web-app-template` 探测；
2. 文件末尾的 `web_app:` 段，`enabled: true`（开平台 API 与前端入口）。

`build_site.py check` 在宿主侧会读取 config.yaml 的 `web_app.enabled`（可用 env
`DEERFLOW_WEBAPP_ENABLED` / `DEERFLOW_WEBAPP_CONFIG` 覆盖）；沙箱内读不到配置文件，
"挂载即视为开"——所以挂载条目就是沙箱侧的开关。改挂载后需重启网关（provider 单例
启动时读取；uvicorn --reload 模式改任一 `app/` 下文件即可触发热重启）。

未开启或依赖未预置时整条链路**优雅降级**：capability 探测返回不可用，技能第 0 步
回退单页 HTML 产出，前端入口按钮不渲染，现有功能零影响。

## 构建链路速查

```bash
python scripts/build_site.py check                    # 能力探测（模板/依赖/node）
python scripts/build_site.py scaffold outputs/my-site # 脚手架（排除 node_modules/dist/scripts）
python scripts/build_site.py build   outputs/my-site  # 链接预置依赖 + vite build → dist/
python scripts/build_site.py status  outputs/my-site  # dist 状态 + 最近构建结果
```

环境变量：`DEERFLOW_WEBAPP_TEMPLATE`（模板目录）、`DEERFLOW_WEBAPP_NODE`（node 路径）、
`DEERFLOW_WEBAPP_TIMEOUT`（构建超时秒数，默认 180）。

## 模板自身的构建约束

- `vite.config.ts` 固定 `base: "./"`（嵌套托管路径下资源自适应）与 `target: "es2018"`
  （兼容 chrome100 老内核，与主前端基线一致）；不要改这两个配置。
- 样式是纯 CSS + design tokens（`src/styles.css`），**不引入 Tailwind**（oklch 在老内核失效）。
- HashRouter：静态托管无需服务端 SPA fallback。
- 不新增 npm 依赖；只用已内置库（react / react-router-dom / @xyflow/react / maplibre-gl /
  echarts / mermaid / pmtiles）。