next-tjwater-server/docs/burst-response-workflow.md

从爆管上报到处置闭环

本文定义爆管调查的完整业务路线，供维护者审阅和验收。运行时指令位于 burst-report/SKILL.md，由 Server 根据绑定任务的 workflow=burst_report 经 MCP 分发。

重点成果是有依据的事故候选位置、隔离阀门清单和影响范围，以及经审批执行、反馈核验后的闭环记录。Agent 根据证据选择、跳过或重做分支，不按图逐节点机械调用工具。工程图覆盖多轮调查和人工业务；每轮发布的进度图只标注实际进行的工作，不复制整图冒充执行记录。

完整工程图

flowchart TB
  subgraph intake[工单进入与后台任务]
    order[用户或外围系统提交爆管上报工单]
    source[保存原工单及来源版本、发生时间、位置和描述]
    sync[同步器按来源关联调查及工单投影]
    queue[Server 保存调查任务和 queued run]
    claim[Worker 投递，Agent 领取并维持租约]
    context[读取任务摘要、业务 Skill、历史报告和既有动作]
    order --> source --> sync --> queue --> claim --> context
  end

  subgraph investigation[Agent 调查与工程分析]
    scope[确定事件时刻、地点、调查目标和真实或演练来源]
    location[核对已有资产编号；必要时解析地点和查询附近管段]
    monitor[核对相关测点映射、异常窗口、正常对照和数据质量]
    cover{查询是否实际覆盖事件与对照窗口}
    more[缩小对象和窗口，按需补页，核对缺测及零值]
    hypothesis{是否具备定位所需观测和漏水量依据}
    locate[计算爆管候选排序，保留假设、覆盖范围与证据]
    candidate[整合上报、资产关联、算法与现场反馈得到候选集合]
    usable{是否存在可用于隔离评估的候选资产}
    isolation[逐候选分析拓扑隔离边界、必关阀及受影响节点]
    isolateok{可隔离且阀门可用性有可核验依据}
    alternate[纳入已知不可关闭阀门，重新评估替代隔离方案]
    hydraulic[按需模拟候选关阀组合的压力和流量影响]
    impact[区分拓扑停水区、水力影响区和有资料支持的用户范围]
    findings[形成候选位置、阀门清单、影响对比和建议方案]
    fieldbasis{是否已有足以支持具体现场核验的结论}
    fielddraft[形成有位置、核验目标及回执要求的现场核验建议]
    gap[真实关键数据缺失：发布 final insufficient_data 并结束本轮]
    error[接口、权限或配置异常：记录具体失败并由宿主结束失败运行]
    scope --> location --> candidate
    scope --> monitor --> cover
    cover -->|未覆盖且可补齐| more --> monitor
    cover -->|已覆盖或确认实际缺失| hypothesis
    hypothesis -->|具备依据| locate --> candidate
    hypothesis -->|条件不具备，明确原因| candidate
    candidate --> usable
    usable -->|候选有效，标明待现场确认| isolation --> isolateok
    isolateok -->|有可评估方案| hydraulic --> impact --> findings
    isolateok -->|已知存在不可关阀| alternate --> isolation
    isolateok -->|无法形成方案| fieldbasis
    usable -->|尚无候选| fieldbasis
    fieldbasis -->|可形成具体核验建议| fielddraft
    fieldbasis -->|当前判断所需证据确实缺失| gap
    monitor -->|不可恢复的查询异常| error
    location -->|不可恢复的必要查询异常| error
  end

  subgraph approval[报告、审批与现场处置]
    interim[保存本轮 interim concluded 阶段报告]
    proposals[创建具体待审批草稿，关联证据和执行前置条件]
    finalround[保存本轮 final 报告，由宿主结束本轮 run]
    review[有权限人员审核当前草稿版本]
    decision{审批结果}
    revise[驳回理由保存并触发原调查新一轮]
    submit[Server 通过配置的适配器幂等提交]
    receipt{外部提交结果}
    reconcile[使用同一执行请求号核对回执，不重复下发]
    unsupported[未配置或明确失败：记录原因并重新分析]
    workkind{本次获批的是核验还是处置}
    fieldcheck[现场核验准确位置、漏水迹象及资产，回传实际记录]
    notice[人工实施获批的通知、供水保障和应急安排]
    isolatefield[现场核验阀门及实际隔离结果]
    repair[现场定位、止水和抢修，回传实际故障管段及修复记录]
    clean[按现场风险及获批方案清洗、消毒或冲洗]
    restore[核验修复与适用复测，按批准方案恢复供水]
    follow[记录恢复后压力流量、漏水复查及用户回访]
    findings --> interim
    fielddraft --> interim
    interim --> proposals --> finalround --> review --> decision
    decision -->|驳回| revise
    decision -->|批准| submit --> receipt
    receipt -->|结果不明或仍在执行| reconcile --> receipt
    receipt -->|明确失败或不支持| unsupported
    receipt -->|工单已创建或设备动作有回执| workkind
    workkind -->|现场核验事项| fieldcheck
    workkind -->|有依据的处置事项| notice
    notice --> isolatefield --> repair --> clean --> restore --> follow
  end

  subgraph closure[现场反馈、复核与原事件闭环]
    feedback[外围系统保存关联工单的新反馈和单调版本]
    requeue[Server 校验来源并为原调查排队新 generation]
    reread[重新读取现场事实、执行回执和最新监测证据]
    verify[对照预测与现场结果，复核修复、恢复和风险]
    faultstate{复核结果支持故障、误报还是尚待核验}
    falsealarm[核对排除故障的证据及人工确认]
    closed{处置及闭环证据是否齐全}
    remaining[列出未完成事项及对应已有或待审批动作]
    sourceclosed{原上报工单已结案且版本已核对}
    readyreport[发布具备结案条件报告并结束本轮]
    closedreport[发布闭环复核 final 报告并结束本轮]
    closeowner[有权限人员在原工单系统核对并完成原事件结案]
    closedcase[报告与来源事实一致，确认业务闭环]
    follow --> feedback --> requeue
    fieldcheck --> feedback
    reread --> verify --> faultstate
    faultstate -->|已确认故障| closed
    faultstate -->|有依据排除故障| falsealarm --> sourceclosed
    faultstate -->|尚需核验| remaining
    closed -->|尚未齐全或复测异常| remaining --> interim
    closed -->|证据齐全| sourceclosed
    sourceclosed -->|是| closedreport --> closedcase
    sourceclosed -->|否| readyreport --> closeowner --> feedback
    reread -->|现场位置或阀门条件改变| candidate
  end

  subgraph presentation[贯穿调查的地图、图表与数据整理]
    progress[发布真实调查进展和 Mermaid 状态]
    map[高亮候选管段、闪烁建议关阀、展示已有证据覆盖层]
    chart[打开异常与对照曲线，展示候选及影响对比表]
    filepermit{会话是否已有文件写入权限}
    jsonl[按权限整理有来源引用的 JSONL 调查数据]
    reportui[通过报告 ui_blocks 发布 json-render 结构化界面]
    sourceview[展示保持证据来源，失败不阻断业务调查]
    progress --> map --> chart --> filepermit
    filepermit -->|已获准且需要导出| jsonl --> reportui
    filepermit -->|未获准或无需导出| reportui
    reportui --> sourceview
  end

  context -->|首次或需要重新分析| scope
  context -->|已有新反馈待复核| reread
  revise --> requeue
  unsupported --> requeue
  requeue --> queue
  gap -->|补充事实被 Server 接受后才重开| requeue
  findings -->|无须新增动作| finalonly[无需新增动作时保存 final 报告并结束本轮]
  scope -.-> progress
  candidate -.-> map
  impact -.-> chart
  verify -.-> reportui

图中的现场处置由实际审批、工单与回执推进；顺序按现场紧迫性和获批方案调整。必要的紧急通知、现场核验和供水保障不应等待可选的完整模型计算。clean 为按风险适用的步骤，不能把每次爆管都判断为污染。hydraulic 在缺少模型、时序输入或权限时记录具体限制，仍可保留已完成的拓扑隔离结果。

requeue 表示 Server 接受了新业务事实后分配下一轮，不是 Agent 复活旧会话或自行循环等待。原工单结案由原系统有权限人员处理，后台 Agent 目前没有直接关闭原工单的工具。completed、concluded、动作 succeeded 和“业务闭环”分别核对，不能互相推导。

将业务步骤映射为现有能力

以下产品查询与计算均使用 mcp_tjwater_ 前缀。参数以本轮实际发现的工具 schema 为准。

业务动作	已有入口	必须形成的结果
接续原任务	get_task_context，依次读取 summary、skill 及所需分节；get_task_run_history	原工单来源、事件时刻、调查代次、流程版本、既有动作与现场反馈
查找地点和资产	geocode / search_project_places、query_nearby_elements、get_element_properties、get_node_connections	实际候选管段或节点、位置来源、匹配理由；邻近不代表故障确认
核对监测	list_scada_devices、get_scada_device、query_scada_readings、query_element_history	设备和模型节点的映射、异常及对照窗口、单位、缺测、分页覆盖
压力异常侦测	run_burst_detection	至少 5 个完整压力测点及此前 15 天数据满足时才调用；不把侦测当作定位
爆管候选定位	run_burst_location	候选排序、算法实际返回的评价值、观测范围、漏水量假设及来源
逐候选隔离	analyze_valve_isolation	accident_elements、isolatable、must_close_valves、optional_valves、affected_nodes、affected_node_count 及已知 disabled_valves
水力影响	analyze_valve_closure	指定关阀组合、时间窗、输出对象和模拟压力流量；参数不足时保留明确原因
用户影响	已授权资产属性、区域及外围资料查询	受影响对象、关联依据和覆盖限制；没有用户资料不估造户数
发布和提议	publish_task_progress、publish_task_report、propose_task_action	持久化报告、证据引用和待审批动作；动作不是执行事实
反馈接续	Server external-feedback / human-evidence 及 worker	同一任务的新轮次、真实来源版本、修复和复测证据

定位的 burst_leakage 必须有依据，单位为 m³/s；pressure_scada_ids 是模型节点 ID，不能填设备查询编号，也可省略并使用服务的项目配置。monitoring 模式正常窗可成对省略，使用前一天同窗，但这只是一项对照假设，仍要核对数据有效性。simulation 模式必须引用已有分析运行 UUID，不把在线重算当成已有分析运行。已知事故管段可直接做候选隔离；不必先完成一次没有必要的定位计算，也不能把已知答案作为算法独立定位成功的证明。

隔离工具支持明确标注的候选管段，无须等到现场确认才评估方案。多个候选的比较优先分开调用；把多个 ID 一次传入表示联合事故场景，不等同于逐个比较。disabled_valves 仅填已有事实支持的不可关阀；空数组不证明现场阀门均可用。isolatable=false 不能解释为零影响，即使 affected_nodes 为空也须解释返回的计数和限制。

像调查员一样查询、查看、比较和复核

每一步先明确待回答的问题，再查小范围资料，观察实际结果后决定下一步。例如：核实地址，查附近管段并查看属性，关联压力点，比较事件前后及正常对照，检查候选，评估关阀影响。只把必要的查询、事实和判断依据写入进度及报告，不保存模型内部推理。

• 不满足于“查过 SCADA”：必须确认返回的时间实际覆盖事件。查询 24 小时而只返回当天前 45 分钟时，应缩到事件前后的小窗，按需补页，不直接进入最终判断。
• 正常基线、实测、模型模拟、外围演练和人工反馈分别标注；缺测不是零值，异常不是爆管确认，候选评分不是校准后的概率。
• 查不到事故管段时先检查地址解析、附近资产与上下游关联；能查询的字段先查询，不能直接全部交给现场。
• 既有证据通过 get_task_evidence 的有界分页读取，不重复拉取同一批事实。失败、权限拒绝和存储未配置不当作“无异常”或“无数据”。
• 可以用最多两个前台 investigation-reader 并行核对无依赖的问题。读取、计算、发布和文件权限仍按角色执行；reader 只返回查询事实及真实证据编号。

地图与图表操作

后台调查统一调用 publish_task_presentation，每个不同命令使用不同 UUID request_id，相同命令重试复用原编号。以下为工具已有能力，不需要浏览器自动化。

调查进展	command.action	取值及依据
找到实际候选资产	highlight_features	layer=pipes / junctions，feature_ids 为已核实的地图要素编号，effect=steady
正在核查候选或建议关阀	highlight_features	对应 pipes 或 valves，effect=pulse；闪烁只表示调查关注，不代表设备正在操作
查看异常与对照	open_chart	有限长度的时间和值，引用真实 evidence_refs；不同日期的对照对齐方式在标题或来源中说明
查看已有空间结果	set_overlay	提供 overlay_id/title/mode/evidence_id，Server 从证据提取几何，不接收手绘影响区
撤下旧的临时展示	close_chart / clear_overlay / clear_highlights	清理自己记录的临时展示；清理失败不修改业务结果

支持的图层为 junctions、pipes、valves、pumps、tanks、reservoirs、scada。先核实业务 ID 与地图 feature ID 的映射，不能把设备编号、节点编号与 GIS 编号混用。每次高亮最多 100 个要素，需要更多时说明所显示的子集；不要假定多次命令会累积成完整范围。没有几何时可以按已知 ID 高亮、用表格解释结果，不画包络多边形冒充影响范围。

图表最多 100 个横轴值和 8 组数值序列，单位须在系列名称或标题中明确。不能把 null 缺测填零以通过 schema；可以按有数据的区间分图，并保留缺测说明。recorded 仅表示请求保存。浏览器未开 Dev 跟随时仍继续调查，不能等待地图显示回执。后台接口目前没有摄像机缩放、平移、鼠标点击或任意图层开关命令；不要调用仅供聊天的 locate_features、zoom_to_map 或原生浏览器工具替代。

JSONL 调查数据与 json-render 展示

JSONL 用于整理已经取得的数据与分析结果，不补造监测、阀门、现场反馈或审批。推荐每行一个对象，记录 record_type/origin/source_evidence_refs，并按对象保留时间窗、单位、模型或假设、覆盖限制和实际结果。origin 沿用来源分类；本地派生记录引用输入证据，并说明转换方法。不要把 JSONL 文件自身当作 Server 已保存的业务证据。

按内容选择 event_context、monitoring_coverage、candidate、isolation、hydraulic_impact、field_feedback、closure_check，无需为没有结果的类别制造空壳文件。候选记录写实际排序及评价值；隔离记录保留建议必关阀、可选阀、已知不可关阀及受影响节点；闭环记录逐项保留已核验、待核验或不适用及原因。JSONL 是导出约定，不新增 MCP 输入字段或服务端数据协议。

以下两行只演示文件格式，synthetic、example_only 与空证据引用表示它们不可用于实际报告或审批，不包含真实分析结果：

{"record_type":"candidate","origin":"synthetic","example_only":true,"source_evidence_refs":[],"element_id":"DEMO-PIPE-01","rank":null,"evaluation_value":null,"status":"not_computed","limitations":["仅说明字段，未执行定位"]}
{"record_type":"closure_check","origin":"synthetic","example_only":true,"source_evidence_refs":[],"item":"repair_verified","status":"not_verified","observed_at":null,"limitations":["无现场反馈，不能声称闭环"]}

如果当前会话已获准使用原生文件写入，则在当前 workspace 下写 files/burst-investigation-<generation>.jsonl，保留原始证据不变；通过允许的读取工具逐行复核 JSON、行数、对象 ID、时间和单位。只引用宿主绑定的 generation，不能从用户文本自选。不得读取兄弟会话、业务数据库、宿主源码或凭据；需要本地转换时只使用已获准的原生工具及沙箱 Shell，不引入 HTTP、SQL 或自由命令查询桥。

当前没有专用的免审批 JSONL 导出工具。文件权限未授予时，不通过 Shell 绕过、不让后台无限等待批准、不声称已生成文件；继续完成报告内的结构化数据，并如实说明文件未保存。恢复写入授权须由有权限的人或宿主处理，Skill 不扩大权限。

图表、表格和指标使用 publish_task_report.report.ui_blocks，每块为 answer-ui@1，包含独立 block_id、fallback_text 和 json-render 的 spec.root/elements，外层附真实 evidence_refs。最多 8 块、总计 400 KB，单块还受现有 schema 限制。优先组织以下内容：

展示	建议组件	数据来源
候选管段及理由	Table、Evidence、MapLocation	地点、资产与定位证据；明确候选和已确认的区别
异常及正常对照	Chart	同单位的实际序列，说明时间对齐及缺测
关阀与隔离范围	Table、Metric、MapLocation	隔离证据、阀门属性及候选场景
水力与用户影响	Table、Chart	指定输出节点的模拟结果及真实用户关联资料
处置与闭环核对	Table、Evidence	动作回执、现场反馈、恢复监测和原工单版本

只用工具公布的组件属性。JSONL 可作为整理中间格式，但目前没有“把任意 JSONL 直接传给 json-render”的通道；需转换为已注册组件的 JSON 属性。后台不用 present_answer，不把原始 JSONL 输出到聊天正文，也不把表单提交当成已保存现场证据。小数据和简单结论可直接文字表达。

本轮成果与爆管闭环的验收

报告至少回答下列四类问题，逐项给出实际结果或经过查询证实的具体限制；无需固定排版或创建固定数量的动作。

1. 位置：事故已确认还是仅有候选？每个候选的模型/地图编号、匹配或定位依据、排名及未确认事项是什么？
2. 隔离：每个候选场景是否可隔离？应关、可选和已知不可关的阀门分别是什么？有无替代方案及现场前置核验？
3. 影响：拓扑受影响节点、水力压降或失供范围、用户关联分别有哪些实际结果？未覆盖什么？没有水力或用户资料时分别说明，不能推定为零。
4. 处置与闭环：当前可审批的工作是什么？已有哪些动作、审批、提交回执和现场事实？还缺什么反馈才具备结案条件？

有具体结论和动作建议时，先保存 interim/concluded，再 propose_task_action，最后保存 final。人工执行事项使用 work_order_type=general，保留原爆管事件。工单描述写位置、任务内容、依赖、执行前核验、需回传的事实和责任要求；propose_task_action 当前 payload 没有独立的 dependencies 或 feedback_requirements 字段，不发明字段。没有客户通知适配器时，将通知作为人工工单事项，不宣称已发送。

闭环复核至少核对实际故障资产及原因、隔离/阀门实施记录、抢修结果、适用的清洗及水质复测、恢复供水记录和恢复后监测、用户通知及回访、未决动作与遗留风险、原上报工单结案状态。不适用事项必须有事件依据；未收到结果写待核验，不把记录创建时间当现场完成时间。只齐备处置证据而原工单未结案时，结论为“具备结案条件，待原系统确认”，而非“已闭环”。误报或未发现故障的结案也要有支持排除的实际核查与人工确认。

必要查询失败、权限拒绝和存储未配置属于执行异常，按 schema 修正可纠正问题；仍无法取得当前判断必需的资料时交宿主记录失败。已通过有效查询确认关键数据确实缺失且无法补齐，才发布 final/insufficient_data，提供 blocking 缺口和查询依据，建议与待办为空，不在该退出分支再生成补数据工单。能够明确形成一项现场核验结论时可提议具体核验动作，但不能把“尚未开展定位”包装为“已完成定位调查”。

能力边界与验证

本次交付为工程图和运行时 Skill 文本，使用现有 MCP、发布、审批与反馈能力；不新增自动关单、鼠标自动化、摄像机操作、JSONL 导出接口或数据库字段。Server 目前没有按 Skill 检查定位/隔离成果的强制验收器，本文的业务验收要求仍由 Agent 执行并由人复核。

当前 Skill 仅通过 section=skill 整份分发，没有相对路径 reference 读取协议，因此运行时指令保持自包含，不能要求 Agent 读取本工程文档。内容需控制在既有内联预算内。Server 更新资源后，应按原发布方式让实际 Server 实例取得新文件；Agent 读取时核对 name/version/content_sha256，不把本地文件更新当成运行中实例已生效。

验证包含 Mermaid 语法解析、本地路径和工具 ID 核对、Skill 分发/权限/体积测试及 git diff --check。后续真实行为验收应分别覆盖：有效观测和漏水量依据下的定位；已知候选但缺漏水量时的候选隔离；不可关阀替代方案；SCADA 首屏未覆盖事件时继续读取；接口失败明确终止；文件权限缺失不绕过；无浏览器时照常调查；实际反馈触发新轮及最终闭环复核。没有真实模型计算或现场回执，不报告定位准确性或业务闭环已通过。

关联契约：分析 MCP、调查展示、报告契约、任务与多轮反馈、后台工作进程。