249 lines
22 KiB
Markdown
249 lines
22 KiB
Markdown
# 从爆管上报到处置闭环
|
||
|
||
本文定义爆管调查的完整业务路线，供维护者审阅和验收。运行时指令位于 [burst-report/SKILL.md](../resources/work-order-skills/burst-report/SKILL.md)，由 Server 根据绑定任务的 `workflow=burst_report` 经 MCP 分发。
|
||
|
||
重点成果是有依据的事故候选位置、隔离阀门清单和影响范围，以及经审批执行、反馈核验后的闭环记录。Agent 根据证据选择、跳过或重做分支，不按图逐节点机械调用工具。工程图覆盖多轮调查和人工业务；每轮发布的进度图只标注实际进行的工作，不复制整图冒充执行记录。
|
||
|
||
## 完整工程图
|
||
|
||
```mermaid
|
||
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` 与空证据引用表示它们不可用于实际报告或审批，不包含真实分析结果：
|
||
|
||
```jsonl
|
||
{"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](mcp-analysis-tools.md)、[调查展示](investigation-progress-and-presentation.md)、[报告契约](investigation-report-contract.md)、[任务与多轮反馈](operational-tasks.md)、[后台工作进程](operational-task-workers.md)。
|