# gis_supervisor_agent **Repository Path**: being_xyk/gis_supervisor_agent ## Basic Information - **Project Name**: gis_supervisor_agent - **Description**: GIS从数据处理、数据发布、数据可视化,这整个生态的三个Agent统一调度管理协作,完成生态层面的质量闭环。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-02 - **Last Updated**: 2026-09-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # gis_supervisor_agent GIS 数据渲染闭环的编排产品(proposal-0030 定位):以 LangGraph 确定性主干图调度三个 GIS 生态 Agent 工程(产品内部组件,proposal-0031 起以 git submodule 收编进根仓),把「人观测断点 → 判断抛给谁 → 下发需求 → 重跑验收」的手动循环自动化,提供统一入口、统一操作的出图闭环。 - 处理环:`xsces-lab-agent`(submodule) - 发布环:`mini_gis_server_agent`(submodule,GeoServer) - 渲染环:`osgearth_for_gis_server`(submodule,osgEarth) **clone 须知**:本仓含三个 submodule,克隆用 `git clone --recursive `;已克隆则 `git submodule update --init` 或一键 `powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1`(拉齐指针 + 核查三端非 git 资产,缺失逐项给人话提示)。三端托管于 gitee,若为私有库需先配好 gitee 凭证。 supervisor 经统一构建入口 `build_member_adapter` 构建成员调用面(proposal-0043 收敛为 dsh-sdk 单通道,无 invocation 分流)——一成员一 dsh runtime 子进程(JSON-RPC 行帧协议,session.event 转写事件流,ULID 锚点经 dsh-sdk-resume 插件续接,取消=杀 runtime)——下发工单(落文件传路径)、回收 result.json 契约、会话级 events.jsonl 全程记录,失败进闸口由人裁决;纯问询走 chat 通道直接对话(不派单不跑环)。运行中成员可单独停止(先写 cancel.json 协作信号再 taskkill 单成员,瞬时重试短路、run 记 aborted「人工停止」)。 ## 现状 二期逐项变更明细(proposal 级)见 `Document/archive/INDEX.md`(Type-C 修复见 `Document/changes/CHANGELOG.md`),此处只留人读摘要。 第一期已交付(2026-09-02,BWorkflow S0→S5 闭环):happy path 连续两次端到端真实打通——shp 建筑 → floor×3m 回填 height → GeoServer WFS 发布 → osgEarth 按 height 拉伸出图 → 截图目检闸口,单轮约 33 分钟。 二期经 S6 变更已交付: - **M9 run 工作台前端 + 薄 FastAPI 后端**(proposal-0005/0011/0015;proposal-0039 由群聊形态升级;proposal-0040 左列树形化;proposal-0045 中列泳道化):三栏 run 工作台——左列「会话为干、run 为子行」树形列表,中列选中 run 的三 Agent 泳道 × 时间线(固定等宽三列 = 三固定成员,工单卡/结果卡按成员分派落列,failure_review 归因折入结果卡,在跑列有实时过程条——最近进展 + 已运行时长 + 最后活动距今,run 头部心跳超 60s 无事件警示;闸口卡置顶横贯,验收拉通横条汇总各环结论并挂 accept 操作与截图目检),右栏会话常驻窄栏(问答类事件气泡,proposal-0042 分流),发起/新建/删除/停止会话与闸口决策均可在页面完成;CLI 保留为等价入口。 - **M10 意图路由两段式**(proposal-0008/0010/0011/0013/0014):自然话术 → LLM 生成 ExecutionPlan(kind: pipeline 三环流水线 / delegate 委派 / chat 纯对话 / clarify 澄清反问),dispatcher 退化为确定性 plan executor;支持**链式委派**(「先 publish 拿 URL 再交给 osgearth 渲染」→ 多 steps 串行,上游 result.json artifacts 接力进下游工单,闸口决出后 resume 自动续链);`@成员` = 确定性 chat 直达(零 LLM、不派单);路由 prompt 注入注册表 capabilities 与近 N 条会话上下文(追问指代可判);chat fan-out 意图转述(proposal-0025:@多成员时 LLM 按成员改写 step.goal 为专属转述问句,不再整句原文透传,成员仅就其负责范围作答)+ 并行下发(proposal-0029:成员问答无数据依赖,一成员一线程,汇总按 steps 原序)。 - **M11 成员注册表**(proposal-0010/0016/0017/0018/0027;proposal-0043 静态化):`SourceCode/config/members.json` 静态三成员配置(不再硬绑三环 id,入 git、改文件即生效、消费侧现读盘);成员管理收敛为只读(`GET /api/members` 清单 + 前端只读详情,注册/预览/更新/删除写口与前端管理入口全废——多成员平台能力主动废弃);无色成员 load 内存补色(前端配色读成员记录);pipeline 三环由 `config.pipeline_stages`「阶段→成员 id」映射并在 run 启动校验。 - **M13 dsh-sdk 调用形态**(proposal-0020/0021/0028/0032/0033;proposal-0043 起唯一调用通道):成员能力卡 schema v1(description/io/acceptance/permissions 四组字段,invocation 组随 cli-kimi 通道删除);成员调用统一由 dsh runtime 子进程执行(`dsh --profile sdk` + JSON-RPC 行帧协议,session.event 转写 stage_progress,sessionId ULID 锚点分层、同锚点经随仓 dsh-sdk-resume 插件续接,模型走 config `dsh` 段可配),adapter 构建统一收口 `build_member_adapter`(映射即换工程,config 三环路径字段废弃);dsh workspace-write 沙箱单根(= project_dir),凡工单指向 run 目录的契约路径(result.json / products / acceptance)经 project_dir 内镜像暂存树 `.supervisor-staging//` 搬回验收、消费即删(proposal-0032),成员临时工作文件统一走 `.supervisor-scratch//` 用完即删(proposal-0033)——成员仓库零污染由契约机制保证,产物 vs 研发扩展按二分规则 + 生长评审管理;permissions.writable 不被沙箱消费(proposal-0043 起仅作信息透出);proposal-0028 起 harness-loop(进程内最小 loop)退役删除;proposal-0043 起 cli-kimi 通道删除(adapters.py 收敛为纯契约模块)。 - **多仓结构与产物治理**(proposal-0031/0032/0033):三端以 git submodule 收编进根仓(目录名=仓库名,gitee 托管,各保独立流程),根仓指针=产品集成基线,契约面改动先根仓 proposal 再下发三端;处理环 flow_hint 引导成员先查 `Product/bin` 工具链与能力矩阵(轻量任务可脚本);三端真能力依赖的非 git 资产(Product/、osgearth install 树等)装配说明见 `AGENTS.md`「多仓管理」节。 - **会话模型**(S2 重新锁定第二刀):Conversation 持事件流(`conversations//events.jsonl`),Run 降为会话内执行单元(仅 pipeline/delegate 建 run);前端左列会话列表;CLI 新增 `resolve`(关会话级待决卡)与 `migrate`(存量 runs/ → conversations/)。chat/delegate 会话锚点按通道分键(任务线裸 id / 问答线 `:chat`)+ 跨进程文件锁(proposal-0022,治「同会话追问失忆」)。 - **停止能力**(proposal-0019/0024/0029):运行中会话可停止——server spawn 的 CLI pid 落 `processes.jsonl`,`POST /api/conversations/{cid}/stop` / CLI `stop` 杀进程树(taskkill /T /F)并把投影仍 running 的 run 补 `run_end(aborted)`,停止后回 idle 可删除;运行中成员可单独停止(proposal-0024)——adapter 执行期落 `active-member.json`(dsh-sdk 带真实 runtime pid;proposal-0029 起多成员 map,fan-out 并行期可同时多个在跑成员,全部写口锁内读-改-写),`POST /api/conversations/{cid}/stop-member` 先写 `cancel.json` 再 taskkill 单成员,瞬时重试短路、run 收尾 `run_end(aborted, 人工停止成员 X)` 不进闸口不派失败卡;前端 composer 上方「正在执行」条每在跑成员一枚(各带 ■停止成员,不再以会话 running 为拉取门槛,chat 通道可达)与会话级停止并存;事件流仍是唯一事实源。 - **工单与过程可视**(proposal-0023):order_dispatch 事件 enrich `order_path_url`,前端「查看工单」折叠面板渲染工单 prompt 原文(markdown 消毒后展示,重试工单带标注);过程要点提取同源兼容 OpenAI `tool_calls` 形态(修「下发工单后前端看似卡死」)。 - **事件流并发加固与前端渲染稳定化**(2026-09-07 Type-C):`EventLogger.append` 改跨进程文件锁内从文件末行续号(server 每消息一 CLI 并发写同一会话曾实证 seq 撞车,致前端消息覆盖/轮询吞事件);前端消息 key 改 `convId:index`,聊天区改贴底追踪滚动(上翻阅读历史不再被事件轮询拽回底部)。 - **M14 成员服务控制面**(proposal-0035/0036/0037):members.json 增 services 段(endpoint/health_path/start/stop/web_url),supervisor 自持 registry/probe/lifecycle/gate/status 五模块——pipeline 前置服务就绪门禁(缺服务早失败,无僵尸 run)、CLI `supervisor services`、API 与前端「成员服务」面板(按成员分组服务卡、start/stop 情境按钮、web_url 一键打开,统一界面渐进集成链接级入口);服务操作危险度分级(safe/caution/dangerous + stop_impact 影响面声明,dangerous 写口 409+confirm 强制、CLI 交互确认、面板弹窗)——「按可回退性分配智能」从纪律升级为运行时协议。 - **chat 会话记忆补强 + 输入解析泛化**(proposal-0038):澄清反问与 supervisor 自答注入会话近期上下文(与路由层同源同口径),不再连环追问用户已提供的路径/对象/目标;pipeline 输入解析扩展名从 .shp 泛化至处理端支持全集(shp/tif/dem/fbx/obj/osgb/las/gltf/pak 等 13 种),DEM/倾斜模型/点云任务可直接进管道。 - **架构收敛**(proposal-0043):成员调用通道收敛为 dsh-sdk 单通道(cli-kimi 全删,adapters.py 收敛为纯契约模块);成员注册表静态化(members.json 入 git 三成员固定,注册/预览/更新/删除写口全废,前端成员管理改只读);三端各切 `supervisor-integration` 分支承接 supervisor 改造,根仓基线随分支走(gitee 已推)。 - **会话级 goal + 失败评审层**(proposal-0044):一个会话绑一个 goal(首条目标型消息抽取落档,不可修改、新目标开新会话),工单头部注入全局目标、Run 主题名顶替 basename;成员失败回收后 LLM 结构化归因(verdict/reason/suggested_action),回填失败卡 attribution 节 + `failure_review` 事件,闸口卡展示归因与建议(只到人、不自动执行)。 - **渲染效率量化验收**(proposal-0046):result.json 顶层 `load_metrics`{ttfp_s, avg_fps} 契约(富细节并列 `detail` 键),config 阈值 `render_max_ttfp_s`(60s)/`render_min_fps`(25fps) 可配可关,RenderChecker 超限判败进闸口——「效率正常」从人眼变机判。 二期 S5 验收已通过(2026-09-15):Tokyo POI(30.7 万 OSM 点)发布→osgEarth 验证两环 delegate 真实闭环——GeoServer 聚合 MVT(z10-13 簇泡 + z14-18 分级标注)三版本(3.6/3.7/3.8)出图,city 60fps / street warm 45+fps 实证,泳道 UI 与过程可见性走查通过。 ![happy path 验收截图](SourceCode/runs/20260902-183024-826f63/acceptance/snapshot.png) (注:`conversations/` 不入库,截图为本机运行时产物;图中路径为迁移前 `runs/` 旧结构。) ## 快速开始 ```bash cd SourceCode python -m venv .venv && .venv/Scripts/python -m pip install -e . copy config\config.json.template config\config.json # 填入 LLM_API_KEY(路由/preview 用);eval 段可整段删除 # (llm 段 LLM_THINKING 可选:DeepSeek 端点默认开 thinking 与结构化输出冲突,须配 "disabled";Kimi 端点可整键删除) .venv/Scripts/python -m supervisor run D:\SGDownload\Testdata\shp\building.shp # 或自然语言入口(LLM 路由): .venv/Scripts/python -m supervisor run --message "我有一个 D:\data\building.shp 文件,请处理完成,通过 GeoServer 发布后,在 osgEarth 加载查看" # 停在闸口后: .venv/Scripts/python -m supervisor resume --approve # 停止运行中会话(杀进程树,running run 记 aborted): .venv/Scripts/python -m supervisor stop ``` run 工作台前端(推荐入口):双击根目录 `start-web.bat`(首次自动 npm install + build),浏览器开 http://127.0.0.1:18000 。前端工程在 `SourceCode/web/`(需 node/npm;dev 模式 `npm run dev`,/api 已代理到 :18000)。 前置:三端 submodule 已就位(见上文 clone 须知)且**非 git 资产已装配**(见下节);GeoServer docker 已起(本机 :18890)。使用 dsh-sdk 成员另需: ```bash # 1. 安装 dsh(0.1.5-rc.1,--allow-scripts 放开其原生依赖的安装脚本) npm install -g --allow-scripts=@deepseek-ai/dsh-subprocess-local,node-pty,@google/genai @deepseek-ai/dsh@0.1.5-rc.1 # 2. 配置模型端点密钥(dsh_provider 缺省 deepseek-official,只认 DEEPSEEK_API_KEY—— # 环境变量优先,缺省兜底读 %USERPROFILE%\.env;adapter 构建期自检,缺失人话报错) # 3. 安装随仓 resume 插件(dsh 0.1.5 无原生 resume,同锚点续接靠它)—— # 实测 `dsh plugin add` 在 Windows 上会生成坏软链(pnpm link 拼错盘符路径), # 推荐直接实体拷贝插件目录到 profile 的 node_modules: xcopy /E /I SourceCode\dsh-plugins\dsh-sdk-resume %USERPROFILE%\.dsh\profiles\sdk\node_modules\dsh-sdk-resume # (插件更新后需重新拷贝;也可改用 junction 代替拷贝:mklink /J ...\node_modules\dsh-sdk-resume <仓内插件目录>) # 然后把插件声明进 patch 层(缺则 adapter 自检人话报错)—— # 编辑 %USERPROFILE%\.dsh\profiles\sdk\cordis.patch.yml,内容改为: # - insert: # - { id: sdk-resume-fallback, name: dsh-sdk-resume, inject: [agents] } # 4. 验证(可选):任意会话里让 dsh-sdk 成员跑一轮后重发追问,同锚点答对即续接生效 ``` ## 运行环境装配(三端非 git 资产) 三端的真能力依赖「非 git 资产」(大体积构建产物/依赖,各仓 .gitignore 排除),clone 后须就地位否则成员只能 workaround(如处理环临时写 Python 脚本)。一键核查跑 `scripts/bootstrap.ps1`(缺失逐项给人话修复提示,退出码 1): - `xsces-lab-agent/Product/`(11 CesiumLab exe + DLL + GDAL 数据,构建法见其 AGENTS.md,或从旧目录 `E:\Developer\XSCesLab_Agent\Product` 整体拷贝,185M) - `osgearth_for_gis_server/SourceCode/osgearth_product/3.6|3.7|3.8`(install 树,各 ~50M)与 `osgearth_verify/snapshot/build*/`(截图工具编译产物,从旧目录 `E:\Developer\osgearth_for_gis` 对应路径拷贝) - `mini_gis_server_agent` 的 conda 环境 + `pip install -e ./SourceCode` 产物(`SourceCode/gis_agent.egg-info`,创建法见其 README 快速开始;**须验 `__editable___gis_agent_*_finder.py` 的 MAPPING 指向本仓**——2026-09-21 实证 stale editable 映射指向旧目录曾致 GeoServer 建 coverage 500);两个前端构建产物(`SourceCode/outputs/console/`、`style_editor/frontend/dist`)同为必查资产 - 另需(bootstrap 未覆盖):`xsces-lab-agent/SourceCode/Testdata/`(735M,从旧目录 `E:\Developer\XSCesLab_Agent` 整体拷贝)+ `SourceCode/UnitTest/node_modules`(npm install)+ `SourceCode/Agent/.venv`(按 Agent/README 创建) 注意:mini 旧目录 `E:\Developer\gis_server_agent` 仍在盘上(HEAD 为 submodule 基线的祖先,无未推送提交),内有未入库的 regions.yaml tokyo 增量与 `.agents/skills/supervisor-handshake/`——Being 2026-09-14 决定先不删、自行回头处理,处理前勿整体删除该目录。 ## 测试 ```bash .venv/Scripts/python -m pytest tests -m "not smoke" # 409 项单元/集成 .venv/Scripts/python -m pytest tests/smoke -m smoke # 真实三环端到端(最近几轮约 12-19 分钟) ``` ## 文档 - 架构(拓扑/编排/调用面/数据模型):`Document/architecture.md` - 设计与契约:`Document/`(constitution / spec / plan-* / domain-model / spike) - 变更历史:`Document/changes/`、`Document/archive/INDEX.md` - 排障积累:`SourceCode/knowledge/failures/` - Backlog 与二期候选:`AGENTS.md`「Backlog」节 - Agent 工作约定(含 BWorkflow 流程):`AGENTS.md`