sync: 鍚屾灞€鍩熺綉鏈€鏂颁唬鐮?(source master @ b69568e4)

This commit is contained in:
gozeros committed 2026-10-21 14:51:31 +08:00
1 parent 4f7f07504a
commit 8bc8b0e082
1651 files changed
+278599 -11416

No files matched your search

@@ -0,0 +1,61 @@
# 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)。