# geo_flow **Repository Path**: being_xyk/geo_flow ## Basic Information - **Project Name**: geo_flow - **Description**: 一体化 GIS 数据流平台:数据处理(CesiumLab exe / GDAL)→ 数据发布(GeoServer)→ 数据可视化(CesiumJS / osgearth 3.8),以声明式管线为骨架、DataSet 领域对象为数据载体、薄 Agent 层负责意图理解与异常诊断。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-22 - **Last Updated**: 2026-11-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GeoFlow 一体化 GIS 数据流平台:原始数据 → 处理 → 发布 → 可视化验证 → 客户端可直接使用的服务地址。 GeoFlow 把 GIS 工程里最常见的三段路——数据处理(GDAL / XSCesiumLab exe)、数据发布(GeoServer / XSMapServer)、可视化验证(CesiumJS / MapLibre / osgearth)——串成一条可复现、可回放、按环分段确认的流水线。一条数据任务跑完,拿到的是能在 Cesium 或 MapLibre 里直接加载的服务地址,而不是一堆需要人工拼接的中间文件。 ## 这是什么 - **flow 模板库**:覆盖栅格上链、区域 OSM 发布、OSM POI 标注、地形瓦片服务、建筑白膜 3D Tiles、DEM 等高线、RRIM 地形判读、S-57 OGC 海图发布、Tile57/MLT/MapLibre 专业海图看图、外部数据源双侧渲染验证等场景。 - **场景化 Flow 目录**:首页按「通用数据生产与发布、地形与三维场景、海图专业应用、已有服务接入与验证」组织模板,并提供 XSMapServer 平台系列交叉视图;支持按名称、数据类型、服务与平台搜索。分类只属前端展示契约,不进入 Flow 执行与版本语义。 - **XSMapServer 领域能力扩展**:`xsmapserver-矢量` 将本地单个 SHP/GeoJSON/GPKG 发布为 WMS/WFS,`xsmapserver-影像` 直发单个 GeoTIFF,`xsmapserver-三维` 发布本地现成 3D Tiles;`xsmapserver-osgb`(active 1.0.0)发布 `metadata.xml+Data/Tile_*` 原始 OSGB,在正式 Three.js+WASM Viewer 验证多根 PagedLOD 与整树缺失引用,首版为局部 ENU 场景,不做格式转换或 Cesium/osgEarth 双端验证;`xsmapserver-建筑下载`(active 1.0.0)按小范围 bbox 经 GeoFlow 内部能力下载 Google 建筑,full inline 为真实 `root.json+GLB` 后发布并在 Cesium 验证。`xsmapserver-地形` 将原始 DEM/GeoTIFF 数据集目录先在 Run 工作目录经 XsTerrainBuilder 加工为 quantized-mesh,再经 XSMapServer Cesium 静态服务发布,以地形服务根地址派生真实 `layer.json` 和 maxzoom,做 Cesium/osgEarth 双端验证。下载与收口分步,面积受本机预算硬限制,不经过 SHP 白膜或 OSGB 转换。XSMapServer 与 GeoServer 并存,Agent 只负责模板匹配和填参,写操作复用 GeoFlow 的确定性校验、确认闸与 FlowRun。后续数据形态按「新增或复用 Capability+稳定场景 Flow」扩展,不为每个原生参数组合穷举模板。 - **RRIM 地形判读**:单波段 DEM 经米制重投影、Horn 坡度与正负开阔度计算生成 RRIM,保留中间层和固定参数并发布 WMS。flow 1.1.0 新任务默认搜索半径 300 米、`difference_max=15`;Cesium 提供二维北向上判读视图、固定图例、范围/原生尺度定位、尺度状态、底图和不透明度控制,osgearth 承担三维验证。既有 run 与数据集不因模板默认值变化而回写。 - **确定性 flow 引擎**:模板实例化后经过结构校验、能力参数校验、路径边界校验、探测轮,再按环推进;每一步状态变化都来自真实执行,不是人工标注。 - **Goal Contract 目标与验收**:dsh 提议目标与排除范围,系统从最终 flow 确定性派生验收项;对话与手动载入共用同一确认链。任务完成状态与验收结果分离,跳过渲染验证只形成显式豁免;版本升级提供目标对齐报告,不自动改约。 - **环级决策与认证证据链**:confirm/resume/skip/unskip/rollback 自动记录 `ring_decisions`,冻结 Flow/环/Goal 哈希并按 `decision_id` 回填执行结果;回退不删历史,Goal 验收与 Flow 认证可追溯到具体决策。Flow active 认证绑定同发布版本的成功 Run 与验收摘要,完整证据仍属于 FlowRun。 - **Flow 版本质量摘要**:所有 active 模板均可从「版本概况」按 `template_release.id + version` 实时汇总现存 Run 的执行状态、Goal 验收与环级决策,列出最近 5 个任务并下钻完整证据;有认证证据时同屏显示认证快照,无证据也可直接查看。新认证同时冻结当前 Flow 引用 Capability 的实现模块指纹,打开概况时比较并提示变化;模块级指纹只用于建议复核,不证明行为等价,也不改变 active 或阻止执行。摘要只读重算,删除 Run 会改变计数但不改认证时快照;无 Goal 与存量无来源 Run 明确区分,不评分、不自动降级。 - **内置 Agent 薄层**:只做意图理解、草案生成、操作建议和异常诊断,**永不直接执行动作**——所有产出都是建议物,经你确认后才调用既有 REST 触发。 - **样式体系**:发布即绑定 profile 预设样式(SLD 逐层物化);发布后可对话式配色调优(3 候选并排对照、点选应用、多会话历史可回放),定稿可回流为样式档案,新发布或存量数据集重跑 style_materialize 步骤时选用;MVT 数据集另有 style.json 换肤体系。 - **知识沉淀与消费闭环**:执行经验沉淀为知识卡片(`knowledge/`)与错误规则表,同类问题可在诊断中命中。命中只记 `recommended`,同一 run 恢复成功后才记 `applied`;S6 工作项通过显式 `knowledge_used` 声明在 verify 后自动结算,空声明也纳入覆盖率。`/api/knowledge/stats` 提供推荐、采用与遥测统计,治理建议只在证据充分时生成并由人拍板。 更详细的设计决策见 `Document/` 目录: | 文档 | 内容 | | --- | --- | | `Document/constitution.md` | 骨架、统一语言、核心域 | | `Document/spec.md` | 需求真相源与验收标准 | | `Document/design/domain-model.md` | DataSet / Flow / FlowRun / AgentAdvice / GoalContract / RingDecisionEvidence / CertificationEvidence 领域模型 | | `Document/design/flow-domain-view.html` | Flow 域物理落点、生命周期主链路与扩展动线(HTML) | | `Document/plan-server.md` / `plan-web.md` / `plan-render.md` / `plan-execserver.md` | 各模块设计 | | `Document/plan-integration.md` | 集成测试断言口径 | ## 环境要求 - Windows(当前开发与运行环境) - [Conda](https://docs.conda.io/)(Python 环境) - [Node.js](https://nodejs.org/) ≥ 18(前端 + execserver + dsh 运行时) - [Docker](https://www.docker.com/)(GeoServer 容器) - [Go](https://go.dev/)(仅首次装配或重建 tile57-service 时需要;Zig 0.16.0 由装配脚本准备) - Git Bash(执行 `.sh` 脚本) ## 拉取与安装 ```bash # 1. 克隆仓库 git clone <仓库地址> GeoFlow cd GeoFlow # 2. 创建 Python 环境 conda env create -f SourceCode/server/environment.yml conda activate gis-agent # 3. 安装前端依赖 npm --prefix SourceCode/web install # 4. execserver 零依赖,可跳过;如需单独安装: npm --prefix SourceCode/execserver install # 5. 装配运行时二进制(换机/首次) # runtime/ 目录体积大、平台相关,已写入 .gitignore,不会随仓库拉取。 # 首次使用需执行装配脚本,或从已有机器复制整个 runtime/ 目录。 bash scripts/assemble-cesiumlab.sh bash scripts/assemble-osgearth.sh bash scripts/assemble-tile57.sh ``` > **关于 `runtime/`**:`runtime/cesiumlab/`、`runtime/osgearth/` 与 `runtime/tile57/` 分别是 GeoFlow 的执行、三维渲染与海图 MLT 底座,包含 XSCesiumLab exe、GDAL 依赖、osgearth 3.8、Tile57 0.4.0+项目补丁及常驻 tile57-service 等。它们**不入 git**,克隆后目录为空是正常的。如果你已有老仓或备份机,直接拷贝整个 `runtime/` 目录过来即可;否则执行上面的 `assemble-*.sh` 脚本装配。 > > Tile57 不再直接取用未修改的发布二进制。`scripts/assemble-tile57.sh` 准备 Zig,`scripts/build-tile57-engine.sh` 按 `SourceCode/tile57-service/patches/tile57-0.4.0/upstream.env` 锁定上游与 IHO Portrayal Catalogue 提交、应用项目补丁并重建 CLI/libtile57/Go 服务;`runtime/tile57/build-provenance.json` 保留构建指纹。修改引擎补丁后须重新 bake 海图,存量 MLT 不会自动更新。完整引擎与 NOAA/中国样本审计入口为 `bash scripts/check-tile57-portrayal.sh`。 ## 配置 复制模板并填入真实值: ```bash cp SourceCode/config/config.json.template SourceCode/config/config.json ``` 必须修改的项: | 配置项 | 说明 | | --- | --- | | `llm.api_key` | Anthropic 兼容接口的 API key(默认用 DeepSeek 的 anthropic 端点) | | `geoserver.password` | GeoServer 管理员口令 | | `geoserver.path_map.host` | 本机 `SourceCode/geoserver/data` 的**绝对路径** | | `geoserver.data_dir` | GeoServer 数据目录本机路径(通常即 `SourceCode/geoserver/data_dir`) | | `cesiumlab.install_dir` | CesiumLab 安装目录,默认 `runtime/cesiumlab/Product` | | `cesiumlab.setenv_bat` | 对应 `setenv.bat`,默认 `runtime/cesiumlab/Product/setenv.bat` | 可选配置: - `dsh` 节:Agent LLM 通道默认走 `dsh` headless,失败自动回退 `llm` 节直连。 - `postgis` 节:海图 `s57-chart` 与 POI `poi` 模板需要本机 PostGIS。`SourceCode/config/config.json.template` 未预置该节,使用这两个模板时请从 `dist/config.json.template` 复制 `postgis` 段到 `config.json` 并填入真实连接参数。 - `tile57` 节:仅 `s57-chart-maplibre` 使用,整节可省略;`service_url` 默认 `http://127.0.0.1:17858`,对应常驻 Go/libtile57 服务,不是每瓦片启动的 CLI。 - `xsmapserver` 节:仅 `xsmapserver-矢量/影像/三维/osgb/建筑下载/地形` 使用,整节可省略;`url` 指向本机 XSMapServer Express 管理面(默认 `http://127.0.0.1:3000`),`name` 是 GeoFlow 产物中的实例标识。发布只由确认后的 FlowRun 执行,XSMapServer 由用户独立启动。 - `3dtiles_download` 节:仅 `xsmapserver-建筑下载` 使用;下载、空间筛选与 full inline 已内置,无需外部工程或 `home` 配置。`api_key` 只存本机配置,`max_area_m2` 是强制下载面积预算,`timeout_s` 缺省 3600;旧配置中的 `home` 可保留但会被忽略。不接 PostgreSQL 队列,下载耗时应保持巴黎城区等目标内尽可能小的 bbox。 ## 启动 ### 1. 启动 GeoServer ```bash cd SourceCode/geoserver && docker compose up -d ``` 默认端口 `18900`,首次健康检查约 1-2 分钟。 ### 2. 启动 GeoFlow 四进程 ```bash # 后台运行(推荐) bash scripts/dev-up.sh --detach # 前台运行(Ctrl+C 统一退出) bash scripts/dev-up.sh ``` `dev-up.sh` 会: 1. 清理 server / execserver / tile57-service / web 四端口旧进程; 2. 检查 GeoServer 是否可达; 3. 依次拉起 execserver(11002)、tile57-service(默认 17858)、server(`config.json` 中 `server.port`,默认 11001)、web dev(`SourceCode/web/vite.config.js` 的 `WEB_PORT`,固定 11010)。 开发页面统一访问:http://127.0.0.1:11010 。不要另起临时 Vite 端口或配置;server 端口仅用于 API 和生产托管。 ### 3. 停止 ```bash # 停止 GeoFlow 四进程 bash scripts/dev-down.sh # 停止 GeoServer cd SourceCode/geoserver && docker compose down ``` ## 验证 ```bash # 端到端冒烟:合成 GeoTIFF 全链路 verified bash scripts/smoke.sh # osgearth 真实运行时冒烟(缺运行时自动 SKIP) bash scripts/smoke-earth-load.sh # 后端测试 C:/Users/PC/.conda/envs/gis-agent/python.exe -m pytest SourceCode/server/tests -q # 前端测试与构建 npm --prefix SourceCode/web test npm --prefix SourceCode/web run build # execserver 测试 node --test "SourceCode/execserver/test/*.test.js" # 原始 OSGB 真实三环、同源资源、WASM 整树与截图(先 dev-up 并启动 XSMapServer) C:/Users/PC/.conda/envs/gis-agent/python.exe scripts/xsmapserver-osgb-e2e.py node scripts/verify-xsmapserver-osgb-cdp.mjs # RRIM 真实三环与 Cesium 二维交互(先 dev-up,GeoServer 与双端运行时可用) C:/Users/PC/.conda/envs/gis-agent/python.exe scripts/rrim-e2e.py node scripts/verify-rrim-2d-cdp.mjs [nonRrimDatasetId] [legacyRrimDatasetId] # Google 建筑小范围真实下载、发布与 Cesium(先配置 3dtiles_download,并启动 XSMapServer) C:/Users/PC/.conda/envs/gis-agent/python.exe scripts/xsmapserver-building-download-e2e.py node scripts/verify-xsmapserver-building-download-cdp.mjs # 都江堰 DEM 经 XSMapServer 发布标准地形并做 Cesium/osgEarth 验证(先启动 XSMapServer) C:/Users/PC/.conda/envs/gis-agent/python.exe scripts/xsmapserver-terrain-e2e.py node scripts/verify-xsmapserver-terrain-cdp.mjs ``` ## 目录速览 | 目录 | 内容 | | --- | --- | | `SourceCode/server/` | FastAPI 后端:flow 引擎、能力矩阵、Agent 层、REST API | | `SourceCode/web/` | Vue3 + CesiumJS + MapLibre GL JS 前端 | | `SourceCode/execserver/` | Node exe 执行服务(拉起 CesiumLab exe) | | `SourceCode/tile57-service/` | Go+libtile57 C ABI 常驻服务:MLT 动态合成与海图物标查询 | | `SourceCode/geoserver/` | GeoServer 2.28.4 Docker Compose 与数据目录 | | `runtime/cesiumlab/` | XSCesiumLab 执行产物;**不入 git**,由 `scripts/assemble-cesiumlab.sh` 装配 | | `runtime/osgearth/` | osgearth 3.8 运行时;**不入 git**,由 `scripts/assemble-osgearth.sh` 装配 | | `runtime/tile57/` | Tile57 0.4.0+项目补丁、tile57-service 二进制与校验清单;**不入 git**,由 `scripts/assemble-tile57.sh` 装配 | | `flows/` | flow 模板库 | | `styles/` | 样式资产(profile + 图标) | | `knowledge/` | 知识卡片库 | | `evals/` | Agent 评测集 | | `warehouse/` | 运行时产物:上传文件、run 工作目录、渲染预览图 | | `Document/` | 正式设计文档;`Document/research/` 为调研底稿,不入 git | ## 常用命令 ```bash node .b_workflow/bin/bwf.js status # 查看 BWorkflow 当前阶段 bash scripts/dev-up.sh --detach # 拉起四进程 bash scripts/dev-down.sh # 停止四进程 bash scripts/smoke.sh # 端到端冒烟 bash scripts/assemble-cesiumlab.sh # 装配 CesiumLab 运行时 bash scripts/assemble-osgearth.sh # 装配 osgearth 运行时 bash scripts/assemble-tile57.sh # 装配 Tile57 并构建常驻服务 bash scripts/check-tile57-portrayal.sh # 引擎、NOAA/中国样本与 MLT 双通道审计 ``` ## 技术栈 - 后端:Python 3.11 + FastAPI + GDAL 3.13 - 前端:Vue 3 + Vite + CesiumJS + MapLibre GL JS - 执行底座:XSCesiumLab exe - 渲染验证:CesiumJS + MapLibre GL JS(MVT/MLT 矢量瓦片形态)+ osgearth 3.8 - RRIM 判读链:NumPy/GDAL 分块计算 Horn 坡度与正负开阔度 + RGBA GeoTIFF + WMS + Cesium 二维判读工作视图 - 海图专业链:Tile57 0.4.0+项目补丁 + Go/libtile57 C ABI 常驻服务 + 独立 MapLibre 6 Viewer;旧 OGC 海图链与 MapLibre 4.7.1 保持兼容 - 发布底座:GeoServer 2.28.4(Docker)+ XSMapServer Express(原生 HTTP 能力适配,外部可选服务) - Agent LLM 通道:dsh headless / Anthropic 兼容协议 ## 许可与声明 详见 `Notice.md`。