277 lines
18 KiB
Python
277 lines
18 KiB
Python
"""One finite query catalog; names, schemas and permissions come from this registry."""
|
||
|
||
from dataclasses import dataclass
|
||
from pydantic import BaseModel
|
||
from mcp import types
|
||
from app.mcp import models as m
|
||
from app.mcp import calculation_models as jobs
|
||
from app.mcp import extended_models as e
|
||
from app.mcp.analysis_models import BurstDetectionInput, BurstLocationInput, ValveIsolationInput, LeakageIdentificationInput, NodeCoverageInput
|
||
from app.mcp.analysis_models import ScenarioInput, ContaminantSimulationInput, ValveClosureInput, FlushingInput, PressureRegulationInput, SensorPlacementInput
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class QueryTool:
|
||
name: str
|
||
description: str
|
||
model: type[BaseModel]
|
||
permission: str
|
||
semantics: str
|
||
task_only: bool = False
|
||
computation: bool = False
|
||
mutating: bool = False
|
||
|
||
def protocol_tool(self) -> types.Tool:
|
||
if self.mutating:
|
||
suffix = "。默认dry_run只预览；执行必须携带预览摘要、相同request_id并通过宿主原生许可。由项目成员的普通聊天执行写入；失败或超时先核实状态，再按原请求接续。"
|
||
elif self.name == "run_simulation":
|
||
suffix = "。任务调用复用证据留存。"
|
||
elif self.computation:
|
||
suffix = "。返回分析建议并留存任务证据；正式方案与现场操作按各自业务流程执行。"
|
||
elif self.name == "query_nearby_elements":
|
||
suffix = "。仅查询当前已授权项目的模型管网，按距离和元素ID稳定排序；按核查目标分页；连接与供水关系由拓扑分析核验。"
|
||
elif self.name == "list_scada_devices":
|
||
suffix = (
|
||
"。默认每页100个，最多500个；page.has_more=true时继续递增offset读取后续页面。"
|
||
"大目录内联保留本页全部设备的编号、类型和单位，模型映射及坐标用get_scada_device核验。"
|
||
)
|
||
else:
|
||
suffix = (
|
||
"。先限定对象和时间范围，再读取明细；集合默认20条，按需逐页扩大，"
|
||
"按当前目标读取必要页面，并说明截断和分页覆盖范围。"
|
||
)
|
||
return types.Tool(
|
||
name=self.name,
|
||
description=self.description + suffix + (
|
||
"。返回queued/running和job_id时，使用get_calculation_job查询状态、get_calculation_result读取成功结果，排队回执用于跟踪；直接返回分析结果时立即读取。"
|
||
if self.name in {"run_burst_location", "run_leakage_identification", "run_burst_detection", "run_simulation", "run_burst_simulation", "run_contaminant_simulation", "analyze_valve_closure", "analyze_flushing", "analyze_pressure_regulation", "optimize_sensor_placement", "save_simulation_scenario", "create_sensor_placement"}
|
||
else ""
|
||
),
|
||
inputSchema=self.model.model_json_schema(),
|
||
outputSchema=m.QueryResult.model_json_schema(),
|
||
annotations=types.ToolAnnotations(
|
||
readOnlyHint=not (self.computation or self.mutating or self.name == "cancel_calculation_job"), destructiveHint=self.mutating or self.name == "run_simulation", openWorldHint=self.name in {"search_project_places", "reverse_geocode"}
|
||
),
|
||
)
|
||
|
||
|
||
_specs = [
|
||
("run_simulation", "按水力步长在在线业务模型上执行指定时间段的实时模拟；更新该时段的模型条件及实时基线，返回指定节点和管段结果；duration单位为秒，输出为在线模型结果，正式分析成果通过方案工具保存", ScenarioInput, "simulation.run", "analysis", False, True),
|
||
("run_contaminant_simulation", "在隔离模型中模拟假设污染源的浓度传播；返回指定节点/管段结果，结果标注假设来源及模型预测范围", ContaminantSimulationInput, "simulation.run", "analysis", False, True),
|
||
("analyze_valve_closure", "在隔离模型中模拟关阀的水力影响，返回指定节点/管段结果；现场阀门操作按业务审批执行", ValveClosureInput, "simulation.run", "analysis", False, True),
|
||
("analyze_flushing", "在隔离模型中评估指定排放节点、冲洗流量和关阀组合的水力结果；现场效果由执行回执和复测核验", FlushingInput, "simulation.run", "analysis", False, True),
|
||
("analyze_pressure_regulation", "在隔离模型中评估给定调泵序列和水箱初始水位的压力影响；输出为给定方案评估，现场调度按审批执行", PressureRegulationInput, "simulation.run", "analysis", False, True),
|
||
("optimize_sensor_placement", "使用灵敏度或K-means算法推荐压力监测点；返回候选节点，正式部署另行保存并核验观测能力", SensorPlacementInput, "optimization.run", "analysis", False, True),
|
||
("run_leakage_identification", "基于SCADA压力与模型进行DMA漏损分配识别，需有依据的总漏损流量和时间对齐；返回待现场核验的区域估计。内部执行遗传算法与水力计算", LeakageIdentificationInput, "burst.run", "analysis", False, True),
|
||
("run_burst_detection", "爆管异常侦测：使用至少5个完整压力传感器此前15天数据；返回压力异常信号，候选管段由定位工具分析", BurstDetectionInput, "burst.run", "analysis", False, True),
|
||
("run_burst_location", "爆管候选定位：对比异常与正常压力，可辅助流量；依据现有异常形成候选，水力算法使用有依据的burst_leakage作为输入。任务上下文location_demo.available=true时可省略漏量，Server直接返回候选管段与相似度，随后继续地图展示、隔离边界与影响分析。压力节点可省略，自动读取项目配置；monitoring正常窗省略时默认前一天同时间段，须说明假设；回放必须显式提供冻结正常窗。simulation须有已有分析运行UUID及同窗模型基线，结果标注模型来源", BurstLocationInput, "burst.run", "analysis", False, True),
|
||
("analyze_valve_isolation", "按事故候选要素分析拓扑隔离边界、建议关闭阀门和受影响节点；候选分析无需等待现场确诊。输出为拓扑隔离与供水失源范围；水力影响另用关阀模拟评估，现场操作前核实阀门映射及可用性", ValveIsolationInput, "simulation.run", "analysis", False, True),
|
||
("generate_node_coverage", "为当前项目已核实的模型节点集合生成空间覆盖示意，适用于候选分布、监测覆盖比较、区域成员、隔离或模拟结果节点等，支持各类项目分析。支持最多8组、合计10000个唯一节点，从真实GIS查询坐标；监测设备、投诉或地址须先关联模型节点。可按连接分组，记录凹包/缓冲参数、缺失节点和display_only；结果为节点空间覆盖示意，保留分组及几何覆盖范围。返回result.map_payload及coverage，任务中用set_overlay引用本次evidence_id、省略data展示；地图通过展示工具发布", NodeCoverageInput, "webgis.view", "analysis", False, True),
|
||
(
|
||
"get_element_properties",
|
||
"读取当前项目的单个管网元素属性",
|
||
m.ElementInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"list_elements",
|
||
"按查询目标分页读取管网元素",
|
||
m.ElementPageInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"query_nearby_elements",
|
||
"查询坐标附近的模型元素，默认pipe；center为EPSG:4326 [经度,纬度]，可直接使用geocode.center；radius_m默认200米、最大10000米，limit默认5、最大100，支持offset。按点到完整几何的WGS84椭球最短距离筛选并排序，返回element_id、distance_m和属性；查询范围为当前模型管网；原始GIS、范围调整与歧义地点按各自入口核验",
|
||
m.NearbyElementsInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"get_network_options",
|
||
"读取模型时间、能源或网络选项",
|
||
m.OptionsInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"get_network_schema",
|
||
"读取当前支持的元素、SCADA和选项结构",
|
||
m.SchemaInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"list_scada_devices",
|
||
"分页读取SCADA设备和物理单位",
|
||
m.ScadaDeviceListInput,
|
||
"scada.view",
|
||
"asset",
|
||
),
|
||
("get_scada_device", "读取一个SCADA设备", m.DeviceInput, "scada.view", "asset"),
|
||
(
|
||
"query_scada_readings",
|
||
"查询带时区且最多24小时的原始或清洗监测数据",
|
||
m.ScadaInput,
|
||
"scada.view",
|
||
"observed",
|
||
),
|
||
(
|
||
"query_model_baseline_series",
|
||
"读取最多20个元素的模型基线，结果标注模型来源",
|
||
m.BaselineSeriesInput,
|
||
"simulation.view",
|
||
"model_baseline",
|
||
),
|
||
(
|
||
"get_model_baseline_at_time",
|
||
"读取单个元素指定时刻的模型基线",
|
||
m.BaselineAtTimeInput,
|
||
"simulation.view",
|
||
"model_baseline",
|
||
),
|
||
(
|
||
"query_model_baseline_field",
|
||
"分页读取指定时刻的模型字段",
|
||
m.BaselineFieldInput,
|
||
"simulation.view",
|
||
"model_baseline",
|
||
),
|
||
(
|
||
"query_analysis_series",
|
||
"读取指定分析运行和元素字段时序",
|
||
m.AnalysisSeriesInput,
|
||
"simulation.view",
|
||
"analysis",
|
||
),
|
||
(
|
||
"query_analysis_values",
|
||
"分页读取指定分析运行某时刻的元素字段",
|
||
m.AnalysisValuesInput,
|
||
"simulation.view",
|
||
"analysis",
|
||
),
|
||
(
|
||
"list_analysis_runs",
|
||
"分页读取持久分析运行",
|
||
m.RunsInput,
|
||
"webgis.view",
|
||
"analysis",
|
||
),
|
||
("get_analysis_run", "读取单个持久分析运行", m.RunInput, "webgis.view", "analysis"),
|
||
(
|
||
"list_analysis_results",
|
||
"分页读取分析成果，可筛选result_type",
|
||
m.ResultsInput,
|
||
"webgis.view",
|
||
"analysis",
|
||
),
|
||
(
|
||
"list_sensor_placement_runs",
|
||
"分页读取已有监测点选址运行",
|
||
m.PageInput,
|
||
"optimization.run",
|
||
"analysis",
|
||
),
|
||
(
|
||
"get_sensor_placement_run",
|
||
"读取已有监测点选址成果",
|
||
m.RunInput,
|
||
"optimization.run",
|
||
"analysis",
|
||
),
|
||
(
|
||
"query_element_history",
|
||
"比较实测与模型基线或分析结果；analysis_comparison要求run_id；limit/offset按序列、时间排序的数据点分页",
|
||
m.HistoryInput,
|
||
"scada.view",
|
||
"observed",
|
||
),
|
||
(
|
||
"get_element_gis_properties",
|
||
"读取元素关联GIS台账",
|
||
m.ElementInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"get_source_gis_properties",
|
||
"读取指定图层源要素台账",
|
||
m.SourceGisInput,
|
||
"webgis.view",
|
||
"asset",
|
||
),
|
||
(
|
||
"get_workbench_runtime",
|
||
"读取工作台已有运行态",
|
||
m.StrictInput,
|
||
"simulation.view",
|
||
"task",
|
||
),
|
||
(
|
||
"get_task_context",
|
||
"读取绑定任务的有界摘要及handling_skill元数据；section=skill读取Server按任务workflow分发的业务处置Skill正文与版本，属于流程指引而非事件证据；其他section选择task/report/evidence/actions/progress/access_requests/plan/run，data_path按返回路径读取嵌套字段，limit/offset分页；report_revision保留选定报告版本",
|
||
m.TaskContextInput,
|
||
"operational_task.view",
|
||
"task",
|
||
True,
|
||
),
|
||
(
|
||
"query_peripheral_data",
|
||
"查询外围业务工单及监测数据；外围工单属于系统数据，监测数据按实际来源保留来源信息",
|
||
m.PeripheralInput,
|
||
"simulation.view",
|
||
"peripheral",
|
||
),
|
||
(
|
||
"get_task_evidence",
|
||
"读取当前绑定任务已保存的证据快照",
|
||
m.EvidenceInput,
|
||
"operational_task.view",
|
||
"task",
|
||
True,
|
||
),
|
||
]
|
||
_specs += [
|
||
("list_regions", "分页查询当前项目区域/DMA列表", m.PageInput, "webgis.view", "asset"),
|
||
("get_region", "查询当前项目区域边界，返回EPSG:4326几何；供水关系按拓扑核验", e.RegionInput, "webgis.view", "asset"),
|
||
("get_region_nodes", "分页查询区域配置的成员节点，未配置时使用区域几何筛选", e.RegionInput, "webgis.view", "asset"),
|
||
("get_node_connections", "按目标节点分页查询直接连接的管线", e.NodeConnectionsInput, "webgis.view", "asset"),
|
||
("query_network_extent", "按EPSG:4326矩形范围分页查询当前项目模型几何；GIS缺失时返回当前项目的具体缺口", e.ExtentInput, "webgis.view", "asset"),
|
||
("list_major_nodes", "按关联管道最小管径查询骨干节点，经纬度EPSG:4326", e.MajorNodesInput, "webgis.view", "asset"),
|
||
("get_model_configuration", "读取模式、曲线、控制规则、需水量、水质及反应等模型配置；集合按页返回", e.ModelConfigurationInput, "webgis.view", "asset"),
|
||
("list_model_configurations", "分页读取模式或曲线ID", e.ConfigurationListInput, "webgis.view", "asset"),
|
||
("search_project_places", "按项目配置的行政区搜索地名，最多10个候选，依赖天地图配置", e.PlaceSearchInput, "webgis.view", "asset"),
|
||
("reverse_geocode", "把EPSG:4326地图取点转为项目范围内地名，保留输入坐标", e.ReverseGeocodeInput, "webgis.view", "asset"),
|
||
("get_project_info", "读取当前项目概况与地图范围，公开字段限于项目业务概况", m.StrictInput, "webgis.view", "asset"),
|
||
("export_project_model", "从当前项目数据库导出INP或ChangeSet压缩文件，由宿主保存到会话文件", e.ProjectExportInput, "webgis.view", "asset"),
|
||
("get_sensor_placement_candidate", "读取监测点候选节点工程属性", e.SensorCandidateInput, "optimization.run", "asset"),
|
||
("export_sensor_placement", "导出已有监测点方案的Excel工程清单，由宿主保存到会话文件", e.SensorExportInput, "optimization.run", "analysis"),
|
||
("list_task_schedules", "分页读取当前项目定时任务配置，执行状态由调度系统管理", m.PageInput, "operational_task.view", "task"),
|
||
("get_task_run_history", "分页读取指定项目任务的运行历史", e.TaskHistoryInput, "operational_task.view", "task"),
|
||
("get_mutation_status", "读取当前身份和会话内的写入执行状态；started只表示已启动，超时后先核实目标数据，再按原请求接续", e.MutationStatusInput, "webgis.view", "task"),
|
||
("calculate_demand_allocation", "按管长权重分配总需水量到节点、区域或全网，返回分配建议，模型变更通过业务写入执行，按页返回", e.DemandAllocationInput, "webgis.view", "analysis", False, True),
|
||
("run_burst_simulation", "在隔离模型中模拟假设管道破口面积的水力影响；返回给定情景的模拟结果，正式方案通过方案工具保存", e.BurstSimulationInput, "simulation.run", "analysis", False, True),
|
||
("edit_model_element", "预览或增删改模型节点、管段、泵阀、水池和区域；变更范围为业务模型，现场设备操作按对应流程执行", e.ModelElementMutationInput, "webgis.edit", "asset", False, False, True),
|
||
("edit_model_configuration", "预览或修改模型需水量、模式、曲线、控制规则、水质及模拟选项", e.ConfigurationMutationInput, "webgis.edit", "asset", False, False, True),
|
||
("clean_scada_readings", "预览或清洗明确设备与24小时内时间窗的数据，写入cleaned_value", e.ScadaCleaningInput, "scada.clean", "observed", False, False, True),
|
||
("write_scada_readings", "预览或补录/修正SCADA数据，要求真实来源依据；观测来源按真实记录核验", e.ScadaWriteInput, "scada.clean", "observed", False, False, True),
|
||
("delete_scada_readings", "预览或删除明确设备与24小时内时间窗的SCADA记录", e.ScadaDeleteInput, "scada.clean", "observed", False, False, True),
|
||
("save_simulation_scenario", "预览或重新计算并保存正式隔离场景成果；有真实计算开销，观测数据按真实来源记录", e.SavedScenarioInput, "simulation.run", "analysis", False, False, True),
|
||
("create_sensor_placement", "预览或计算并保存正式压力监测点选址方案", e.SensorCreateInput, "optimization.run", "analysis", False, False, True),
|
||
("update_sensor_placement", "预览或修改本人有权编辑的监测点方案，保留旧点位乐观校验", e.SensorUpdateInput, "optimization.run", "analysis", False, False, True),
|
||
("create_operational_task", "预览或创建项目任务，Agent运行终态由执行系统管理", e.TaskCreateInput, "operational_task.write", "task", False, False, True),
|
||
("create_task_schedule", "预览或创建定时任务配置", e.ScheduleCreateInput, "operational_task.write", "task", False, False, True),
|
||
("update_task_schedule", "预览或启停定时任务配置，校验版本", e.ScheduleUpdateInput, "operational_task.write", "task", False, False, True),
|
||
("retry_operational_task", "预览或重新入队已终止任务；后续会话由任务调度系统创建", e.TaskRetryInput, "operational_task.write", "task", False, False, True),
|
||
("cancel_task_run", "预览或取消指定任务运行，校验运行版本", e.TaskCancelInput, "operational_task.write", "task", False, False, True),
|
||
]
|
||
_specs += [
|
||
("get_calculation_job", "读取当前身份与会话的持久计算状态；排队回执用于跟踪，分析依据读取成功结果", jobs.CalculationJobInput, "webgis.view", "task"),
|
||
("get_calculation_result", "读取成功计算的原始结果；data_path选择嵌套集合，limit/offset按需分页", jobs.CalculationResultInput, "webgis.view", "task"),
|
||
("cancel_calculation_job", "请求取消本人当前会话的计算；运行中取消由独立计算进程处理，须继续核实最终状态", jobs.CalculationJobInput, "webgis.view", "task"),
|
||
("list_calculation_jobs", "分页读取本人当前会话及任务范围的计算状态", jobs.CalculationJobsInput, "webgis.view", "task"),
|
||
]
|
||
TOOLS = {row[0]: QueryTool(*row) for row in _specs}
|