feat: extend operational investigation workflows

app/mcp/analysis_models.py

@@ -9,13 +9,13 @@ from pydantic import Field, model_validator
 from app.mcp.models import Id, StrictInput
 
 
-MAX_CALCULATION_TIMEOUT_SECONDS = 86400
+MAX_REQUEST_TIMEOUT_SECONDS = 240
 
 
 class CalculationInput(StrictInput):
     timeout_seconds: int = Field(
-        default=120, ge=1, le=MAX_CALCULATION_TIMEOUT_SECONDS, strict=True,
-        description="本次计算等待预算，秒；由Agent按模型规模和任务时长选择，受工具目录中的服务端上限约束；与模拟duration不同，超时不保证已启动的计算停止或回滚",
+        default=120, ge=1, le=MAX_REQUEST_TIMEOUT_SECONDS, strict=True,
+        description="本次HTTP请求响应等待预算，秒，默认120秒；不是后台计算执行时限，受工具目录中的请求上限约束；后台任务通过状态和结果工具查询",
     )
 
 
@@ -38,7 +38,7 @@ class BurstDetectionInput(CalculationInput):
 class BurstLocationInput(CalculationInput):
     data_source: Literal["monitoring", "simulation"] = "monitoring"
     simulation_run_id: UUID | None = Field(default=None, description="已有分析运行UUID，不是方案名称；simulation模式只读取已有异常结果及模型基线")
-    burst_leakage: float = Field(gt=0, allow_inf_nan=False, description="有依据的假定漏水流量，WNTR SI单位m³/s；不是已知爆管管段，不能随意猜测")
+    burst_leakage: float = Field(gt=0, allow_inf_nan=False, description="当前爆管定位算法必需的假定漏水流量，WNTR SI单位m³/s；可用有数据和方法依据的估计或明确给定的情景假设，说明来源与不确定性，不要求现场实测确认；不能任填数值")
     pressure_scada_ids: list[Id] | None = Field(default=None, min_length=1, max_length=20, description="压力监测设备关联的模型节点ID，不是设备查询编号；省略时自动读取当前项目SCADA配置中的压力测点，不需要猜测节点ID")
     flow_scada_ids: list[Id] | None = Field(default=None, min_length=1, max_length=20, description="流量监测设备关联的模型要素ID，不是设备查询编号")
     scada_burst_start: datetime
@@ -69,6 +69,7 @@ class BurstLocationInput(CalculationInput):
 
 class ValveIsolationInput(CalculationInput):
     accident_element: list[Id] = Field(min_length=1, max_length=20, description="经核实或明确作为候选的事故管段/节点ID")
+    accident_element_type: Literal["auto", "link", "node"] = Field(default="auto", description="事故要素类型；auto优先识别管段，再识别节点；节点与管段重号时，节点分析须指定node，纯管段分析可指定link")
     disabled_valves: list[Id] = Field(default_factory=list, max_length=200, description="已知无法关闭的阀门；未提供不代表现场确认全部可用")
 
 

app/mcp/application.py

@@ -203,7 +203,11 @@ class McpQueryApplication:
             return None
         schema = tool.model.model_json_schema()
         if tool.computation or tool.mutating:
-            schema["properties"]["timeout_seconds"]["maximum"] = self.settings.max_calculation_timeout_seconds
+            schema["properties"]["timeout_seconds"]["maximum"] = self.settings.max_request_timeout_seconds
+            schema["properties"]["timeout_seconds"]["default"] = min(
+                self.settings.query_timeout_seconds,
+                self.settings.max_request_timeout_seconds,
+            )
         return schema
 
     async def list_tools(self, ctx, params):
@@ -213,6 +217,10 @@ class McpQueryApplication:
         for name in sorted(TOOLS):
             tool = TOOLS[name].protocol_tool()
             tool.input_schema.update(self.tool_input_schema(name))
+            tool.meta = {**(tool.meta or {}), "io.tjwater/request-timeout": {
+                "defaultSeconds": self.settings.query_timeout_seconds,
+                "maxSeconds": self.settings.max_request_timeout_seconds,
+            }}
             tools.append(tool)
         return types.ListToolsResult(
             tools=tools,
@@ -291,11 +299,13 @@ class McpQueryApplication:
             return tool_error(
                 "INVALID_QUERY", "Query parameters do not match the tool schema"
             )
+        if (tool.computation or tool.mutating) and "timeout_seconds" not in args.model_fields_set:
+            args.timeout_seconds = min(self.settings.query_timeout_seconds, self.settings.max_request_timeout_seconds)
         timeout_seconds = (
             args.timeout_seconds if tool.computation or tool.mutating else self.settings.query_timeout_seconds
         )
-        if (tool.computation or tool.mutating) and timeout_seconds > self.settings.max_calculation_timeout_seconds:
-            return tool_error("INVALID_QUERY", "Calculation timeout exceeds the server limit")
+        if (tool.computation or tool.mutating) and timeout_seconds > self.settings.max_request_timeout_seconds:
+            return tool_error("INVALID_QUERY", "HTTP request timeout exceeds the server limit")
         request = ctx.request
         project = request.headers.get("x-project-id", "") if request else ""
         meta = ctx.meta or {}
@@ -349,7 +359,10 @@ class McpQueryApplication:
                 else:
                     from app.mcp.calculation_jobs import should_queue, submit_calculation
                     if should_queue(tool, args):
-                        result = await submit_calculation(scope, binding, tool, args, call_id)
+                        result = await submit_calculation(
+                            scope, binding, tool, args, call_id,
+                            job_timeout_seconds=self.settings.max_calculation_timeout_seconds,
+                        )
                     else:
                         result = (
                             await self.executor(
@@ -463,6 +476,7 @@ class McpQueryApplication:
                 403: "QUERY_CONTEXT_DENIED",
                 404: "NOT_FOUND",
                 409: "QUERY_CONTEXT_STALE",
+                410: "RESULT_EXPIRED",
                 413: "RESULT_TOO_LARGE",
                 422: "INVALID_QUERY",
                 503: "SOURCE_UNAVAILABLE",
@@ -471,7 +485,7 @@ class McpQueryApplication:
                 codes.get(exc.status_code, "QUERY_FAILED"),
                 str(exc.detail)
                 if isinstance(exc.detail, str)
-                and exc.status_code in {403, 404, 409, 413, 422}
+                and exc.status_code in {403, 404, 409, 410, 413, 422}
                 else "Query is unavailable",
             )
         except (UndefinedTable, InvalidSchemaName):
@@ -480,7 +494,7 @@ class McpQueryApplication:
                 "MCP project storage has not been provisioned",
             )
         except TimeoutError:
-            return tool_error("QUERY_TIMEOUT", "Query execution timed out")
+            return tool_error("QUERY_TIMEOUT", "HTTP request timed out")
         except ValueError:
             return tool_error(
                 "INVALID_QUERY", "Invalid query value or incompatible source data"

app/mcp/calculation_jobs.py

@@ -39,12 +39,15 @@ def envelope(source: str, data, *, job_id="list", page=None) -> QueryResult:
 
 
 def public_job(row: dict) -> dict:
-    fields = {"job_id", "status", "tool", "created_at", "started_at", "finished_at", "updated_at", "error"}
+    fields = {"job_id", "status", "tool", "created_at", "started_at", "finished_at", "updated_at", "error", "queue_expires_at", "result_expires_at"}
     from fastapi.encoders import jsonable_encoder
-    return {**jsonable_encoder({key: row[key] for key in fields if key in row}), "poll_after_ms": 1500}
+    expiry = row.get("result_expires_at")
+    available = row.get("status") == "succeeded" and (expiry is None or expiry > datetime.now(timezone.utc))
+    return {**jsonable_encoder({key: row[key] for key in fields if key in row}),
+            "result_available": available, "poll_after_ms": 1500}
 
 
-async def submit_calculation(scope, binding, tool, args, call_id: str) -> QueryResult:
+async def submit_calculation(scope, binding, tool, args, call_id: str, *, job_timeout_seconds: int = 3600) -> QueryResult:
     from app.mcp.query_service import authorize_query
     await authorize_query(scope, binding, tool, args)
     if binding.purpose == "task_reader":
@@ -68,7 +71,7 @@ async def submit_calculation(scope, binding, tool, args, call_id: str) -> QueryR
                 if not retryable_capacity_rejection(previous["result"]):
                     raise HTTPException(409, "Operation already started; inspect the existing calculation or mutation status")
         check_digest(args, await preview_change(scope, binding, tool.name, args))
-    parameters = args.model_dump(mode="json", exclude={"context_handle"})
+    parameters = args.model_dump(mode="json", exclude={"context_handle", "timeout_seconds"})
     request_id = str(args.request_id) if tool.mutating else call_id
     key = str(uuid5(NAMESPACE_URL, ":".join([binding.subject, binding.client_id, binding.native_session_id, str(binding.task_id), str(binding.run_id), request_id])))
     repo = CalculationJobRepository(scope.connection, scope.project.project_id)
@@ -84,12 +87,12 @@ async def submit_calculation(scope, binding, tool, args, call_id: str) -> QueryR
             await verify_task(scope, binding)
             row = await repo.enqueue(
                 owner_user_id=scope.project.user_id, request_key=key, tool=tool.name,
-                parameters=parameters, binding=durable_binding(binding), timeout_seconds=args.timeout_seconds,
+                parameters=parameters, binding=durable_binding(binding), timeout_seconds=job_timeout_seconds,
             )
     else:
         row = await repo.enqueue(
             owner_user_id=scope.project.user_id, request_key=key, tool=tool.name,
-            parameters=parameters, binding=durable_binding(binding), timeout_seconds=args.timeout_seconds,
+            parameters=parameters, binding=durable_binding(binding), timeout_seconds=job_timeout_seconds,
         )
     await scope.connection.commit()
     return envelope(tool.name, public_job(row), job_id=row["job_id"])
@@ -107,7 +110,9 @@ async def authorize_original(scope, row):
     from app.mcp.contexts import verify_task
     original = restore_binding(row["binding"])
     tool = TOOLS[row["tool"]]
-    args = tool.model.model_validate({**row["parameters"], "context_handle": "durable-calculation-context-handle"})
+    # Legacy queue rows stored the old HTTP timeout. It does not govern durable execution.
+    parameters = {key: value for key, value in row["parameters"].items() if key != "timeout_seconds"}
+    args = tool.model.model_validate({**parameters, "context_handle": "durable-calculation-context-handle"})
     if (str(scope.project.user_id) != str(row["owner_user_id"])
             or str(scope.project.project_id) != str(original.project_id)):
         raise HTTPException(403, "Calculation owner is no longer authorized")
@@ -125,7 +130,8 @@ async def read_calculation_job(scope, binding, tool, args) -> QueryResult:
         })
         rows = await repo.list(owner_user_id=scope.project.user_id, binding=identity_scope, limit=args.limit + 1, offset=args.offset, status=args.status)
         return envelope(tool.name, [public_job(row) for row in rows[:args.limit]], page=PageInfo(limit=args.limit, offset=args.offset, has_more=len(rows) > args.limit))
-    row = await repo.get(args.job_id, owner_user_id=scope.project.user_id)
+    row = await repo.get(args.job_id, owner_user_id=scope.project.user_id,
+                         include_result=tool.name == "get_calculation_result")
     if row is None:
         raise HTTPException(404, "Calculation was not found")
     check_binding(binding, row)
@@ -137,6 +143,9 @@ async def read_calculation_job(scope, binding, tool, args) -> QueryResult:
         await scope.connection.commit()
     if tool.name != "get_calculation_result" or row["status"] != "succeeded":
         return envelope(tool.name, public_job(row), job_id=row["job_id"])
+    expiry = row.get("result_expires_at")
+    if row.get("result") is None or (expiry is not None and expiry <= datetime.now(timezone.utc)):
+        raise HTTPException(410, "Calculation result retention period has expired")
     result = QueryResult.model_validate(row["result"])
     result = await attach_calculation_evidence(scope, row, result)
     value = result.data

app/mcp/catalog.py

@@ -59,8 +59,8 @@ _specs = [
     ("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", "爆管候选定位：对比异常与正常压力，可辅助流量；需有依据的漏水量假设。压力节点可省略，自动读取项目SCADA压力测点；monitoring正常窗可成对省略，默认前一天同时间段，须说明该对照假设。simulation须有已有分析运行UUID并读取同窗模型基线，不是实测；定位内部会执行水力计算，不创建新的事件方案", BurstLocationInput, "burst.run", "analysis", False, True),
-    ("analyze_valve_isolation", "按事故候选要素分析拓扑隔离边界、建议关闭阀门和受影响节点；不是污染扩散或水力影响范围，不执行关阀，须现场核实", ValveIsolationInput, "simulation.run", "analysis", False, True),
+    ("run_burst_location", "爆管候选定位：对比异常与正常压力，可辅助流量；burst_leakage必需，可使用有依据的估计或明确给定的情景假设，不要求现场确诊；本工具不反演总漏水量。压力节点可省略，自动读取项目SCADA压力测点；monitoring正常窗可成对省略，默认前一天同时间段，须说明该对照假设。simulation须有已有分析运行UUID并读取同窗模型基线，不是实测；定位内部会执行水力计算，不创建新的事件方案", BurstLocationInput, "burst.run", "analysis", False, True),
+    ("analyze_valve_isolation", "按事故候选要素分析拓扑隔离边界、建议关闭阀门和受影响节点；候选分析无需等待现场确诊。输出不是污染扩散或水力影响范围；现场操作前须核实阀门映射及可用性，本工具不执行关阀", ValveIsolationInput, "simulation.run", "analysis", False, True),
     (
         "get_element_properties",
         "读取当前项目的单个管网元素属性",
@@ -213,7 +213,7 @@ _specs = [
     ),
     (
         "query_peripheral_data",
-        "查询有限外围数据源；synthetic是合成证据",
+        "查询外围业务工单及监测数据；外围工单属于系统数据，监测数据按实际来源保留来源信息",
         m.PeripheralInput,
         "simulation.view",
         "peripheral",

app/mcp/config.py

@@ -21,7 +21,8 @@ class McpSettings(BaseSettings):
     )
     allowed_origins: list[str] = Field(default_factory=list)
     context_ttl_seconds: int = Field(default=600, ge=30, le=600)
-    query_timeout_seconds: int = Field(default=30, ge=1, le=60)
+    query_timeout_seconds: int = Field(default=120, ge=1, le=240)
+    max_request_timeout_seconds: int = Field(default=240, ge=1, le=240)
     max_calculation_timeout_seconds: int = Field(default=3600, ge=120, le=86400)
     model_config = SettingsConfigDict(
         env_prefix="TJWATER_MCP_",
@@ -32,6 +33,8 @@ class McpSettings(BaseSettings):
 
     @model_validator(mode="after")
     def validate_resource(self):
+        if self.query_timeout_seconds > self.max_request_timeout_seconds:
+            raise ValueError("query timeout exceeds the HTTP request timeout limit")
         if self.dev_http_issuer_uri:
             dev_url = urlsplit(self.dev_http_issuer_uri)
             try:

app/mcp/models.py

@@ -22,7 +22,7 @@ class PageInput(StrictInput):
 
 
 class TaskContextInput(PageInput):
-    section: Literal["summary", "task", "report", "evidence", "actions", "progress", "access_requests", "plan", "run", "skill"] = "summary"
+    section: Literal["summary", "task", "report", "evidence", "actions", "progress", "access_requests", "plan", "run", "skill", "questions"] = "summary"
     report_revision: int | None = Field(default=None, ge=1)
     data_path: list[Id] = Field(default_factory=list, max_length=8)
 

app/mcp/peripheral.py

@@ -7,7 +7,12 @@ from app.infra.db.postgresql.read_queries import MAX_QUERY_BYTES, read_rows, sca
 from app.domain.schemas.operational_data import TaskDataSnapshot, TaskDataQuery
 from app.services.content_digest import digest
 from samples.peripheral.store import PostgresStore
-from app.infra.integrations.operational_data import _select_demo_observations
+from app.infra.integrations.operational_data import (
+    TaskDataError,
+    _select_demo_observations,
+    normalize_peripheral_work_orders,
+    peripheral_records_origin,
+)
 
 
 async def read_peripheral_query(scope, args):
@@ -37,17 +42,25 @@ async def read_peripheral_query(scope, args):
         truncated = len(rows) > args.limit
         if any(item.get("project_id") != project for item in items):
             raise HTTPException(502, "Peripheral project mismatch")
+        try:
+            if args.source == "peripheral_work_orders":
+                items = normalize_peripheral_work_orders(items)
+                origin = "system_data"
+            else:
+                origin = peripheral_records_origin(items)
+        except TaskDataError as exc:
+            raise HTTPException(exc.status, exc.detail) from exc
         data = {
             "items": items,
             "truncated": truncated,
             "limit": args.limit,
             "offset": args.offset,
         }
-        origin = (
-            "synthetic"
-            if items and any(item.get("origin") == "synthetic" for item in items)
-            else "system_data"
-        )
+        if args.source == "peripheral_test_data":
+            data.update(
+                provenance_scope="per_record",
+                source_origins=sorted({item["origin"] for item in items}),
+            )
     elif args.source == "peripheral_points":
         rows = await scada_devices(conn, limit=args.limit + 1, offset=args.offset)
         data = {

app/mcp/query_service.py

@@ -412,14 +412,14 @@ async def execute_query(
                 data["display_time_zone"] = "Asia/Shanghai"
                 data["approved_data_scopes"] = binding.task_scope_cap
                 data["bound_run_id"] = str(binding.run_id) if binding.run_id else None
-                data["available_sections"] = ["task", "report", "evidence", "actions", "progress", "access_requests", "plan", "run", "skill"]
+                data["available_sections"] = ["task", "report", "evidence", "actions", "progress", "access_requests", "plan", "run", "skill", "questions"]
                 truncated = True
                 gaps.append("Task context is a bounded summary; use section, data_path, limit and offset for detail. Previews are not complete reports.")
         else:
             projection = await reads.task_context_page(conn, project_id=binding.project_id, task_id=binding.task_id,
                 section=args.section, report_revision=args.report_revision, data_path=args.data_path, limit=args.limit, offset=args.offset)
             total = projection["total"]
-            if args.section in {"evidence", "actions", "access_requests"} and not args.data_path:
+            if args.section in {"evidence", "actions", "access_requests", "questions"} and not args.data_path:
                 total = projection["snapshot_metadata"].get("total", total)
             if projection["value_type"] in {"array", "object", "string"}:
                 page = PageInfo(limit=args.limit, offset=args.offset, total=total, has_more=args.offset + args.limit < total)