62 lines
3.9 KiB
Markdown
62 lines
3.9 KiB
Markdown
# 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）。
|