next-tjwater-server/docs/mcp-analysis-tools.md

Agent 业务分析 MCP

Agent 原生工具统一使用 mcp_tjwater_ 前缀。Server目录共35项：25项查询、下表10项分析；合并6项宿主查询后共41项。工具参数来自Server实际MCP schema，不维护第二套参数契约。

工具名（不含前缀）	能力与边界	必要权限
run_simulation	在线模拟：按水力步长直接计算业务库，不复制数据库；更新模型条件和实时基线，返回指定节点/管段，不创建方案或正式分析运行	simulation.run + scada.view
run_burst_detection	指定时刻的15天压力异常侦测，至少5个完整监测节点；不定位	burst.run + scada.view
run_burst_location	异常/正常压力、可选流量及漏水量假设的候选管段排序	burst.run + 对应数据的 scada.view 或 simulation.view
analyze_valve_isolation	拓扑隔离边界、候选关阀及影响节点；不是水力计算或真实关阀	simulation.run
run_leakage_identification	SCADA压力约束下的DMA漏损分配估计；需总漏损量依据	burst.run + scada.view
run_contaminant_simulation	已假设污染源的正向浓度传播；不是源头反演	simulation.run + scada.view
analyze_valve_closure	给定关阀组合的水力影响	simulation.run + scada.view
analyze_flushing	指定排放节点和流量的冲洗水力影响；不证明消毒合格	simulation.run + scada.view
analyze_pressure_regulation	给定调泵序列、水箱初始水位的压力影响；不自动优化调度	simulation.run + scada.view
optimize_sensor_placement	灵敏度或K-means压力监测点建议；不保存正式布点方案	optimization.run，项目成员角色

执行与证据

标准水力模拟示例（只展示参数，不执行）：

{"start_time":"2026-10-08T12:00:00+08:00","duration":3600,"output_node_ids":["<已核实节点ID>"],"output_link_ids":["540672"]}

工具完整 ID 为 mcp_tjwater_run_simulation。开始时间必须带时区，时长为60至86400秒， 默认900秒；至少指定一个节点，节点和管段各最多20个。项目与身份由宿主绑定。 输出沿用场景结果信封，包含 node_results、link_results、单位、时间和覆盖范围。 它复用 REST /api/v1/simulation-runs 的在线计算服务：REST 时长仍为分钟，MCP 时长为秒。 每个水力步长执行一次 realtime 快照，更新在线模型条件和该时刻的实时基线；不复制模型数据库。 结果中的 times.sample_times 对齐采样点，窗口不包含结束时刻；例如一步长15分钟、时长3600秒时返回4个采样点。 persisted_baseline=true 表示在线基线已重算，persisted_scheme=false 表示没有创建方案。 该工具的 MCP annotation 为 readOnlyHint=false、destructiveHint=true，因为重算会替换对应时刻的基线。 它不会创建 analysis.run_id，不能将本次计算冒充已有爆管事件运行；调查调用仍可保存证据。 计算读取现有模型和对应SCADA条件，不从摘要虚构观测，也不自动补齐数据或执行现场操作。

爆管定位 run_burst_location 默认使用 data_source="monitoring"。pressure_scada_ids 可省略，由后端从当前项目SCADA配置自动获取压力测点对应的模型节点；显式指定时仍限制为1至20个不同节点。正常对照时间窗 scada_normal_start / scada_normal_end 可成对省略，沿用后端默认的前一天同时间段；返回结果中的 pressure_scada_ids 和 scada_window 说明实际测点和时间窗。默认对照不等于已确认该时段正常。正常窗无有效压力数据或两窗没有共同有效测点时计算失败，不补造数据、不自动换窗。正常窗只有部分测点缺数时，沿用服务逻辑使用两窗共同有效测点，结合返回测点范围解释结果。

仅提供异常时段和有依据的漏水量即可使用上述默认值，例如：

{"scada_burst_start":"2026-10-08T12:00:00+08:00","scada_burst_end":"2026-10-08T13:00:00+08:00","burst_leakage":0.0274}

data_source="simulation" 仍须提供已有 simulation_run_id，使用同窗模型基线作正常对照，不填写正常时间窗；在线 run_simulation 不创建该运行UUID，不能替代已有分析运行。

• 身份、项目路由、任务和运行由宿主绑定；模型不能提供network、username、凭据、文件路径、原始观测数组或方案保存名称。
• 依赖时序数据的8项计算通过权限校验后，先从项目元数据解析并激活 BizDB 与 TimescaleDB 完整路由，再启动计算线程；时序库未配置时在修改模型前失败。普通业务查询、纯拓扑隔离及监测点选址不强制要求时序库路由。
• 普通项目会话、任务协作和调查主Agent可调用；个人会话、学习复盘和只读reader不能调用分析。Server每次同时校验当前权限与绑定时的权限上限；任务数据读取scope不能替代计算权限。管理员显式deny继续生效。
• 复用现有业务函数。在线模拟直接调用业务库；定位关闭共享候选CSV输出；识别不保存方案；选址使用不持久化模式。其余四项场景模拟复用项目专用<业务库>_template及唯一临时模型库，校验模板同步就绪，沿用临时库并发限制和清理；不是复制在线业务库。模板复制仍会短暂停止模板连接/订阅工作进程，不能称为完全没有基础设施副作用。
• 场景persist_results=False仅允许隔离临时模型，跳过正式analysis运行、Timescale结果和基线写入；既有REST默认保存行为不变。仅返回请求的最多20个节点及20个管段，包含单位、时间和缺失对象；不能用局部结果断言全网无影响。
• 数据源和计算假设必须有依据。定位漏水量和DMA总漏损约束使用m³/s；冲洗使用服务实际接收的m³/h，不沿用旧REST误标的L/s。工频泵序列0/1，变频泵序列为Hz；每项对应模型水力步长。冲洗当前限LPS/CMH模型。选址当前推荐压力点，不冒充污染溯源优化。
• 调查结果经现有快照/证据/回执链保存，只有返回evidence_id后才引用为系统证据；普通聊天不自动保存调查证据。模拟结果始终是analysis而非实测。已知模拟事件源管段是输入背景，不是算法定位准确性的证明。

资源边界与发布

10项计算工具均提供 timeout_seconds，由Agent根据模型规模、模拟步数及已有耗时按次选择；它表示实际等待预算，与 duration 表示的模拟时间不同。未填写默认120秒。服务端上限由 TJWATER_MCP_MAX_CALCULATION_TIMEOUT_SECONDS 控制，默认3600秒，管理员可设120至86400秒；tools/list schema 发布实际有效上限，超限在计算前拒绝。

例如 duration=3600, timeout_seconds=900 表示模拟1小时、允许等待15分钟。Agent的上游HTTP/SDK预算为所选预算加5秒，整个宿主调用另留60秒处理认证、上下文绑定和清理；OpenCode连接上限从工具目录计算并写入宿主连接文件。本地MCP请求关闭Bun空闲断连，仍受上述调用截止时间控制。普通查询继续使用原30秒Server预算与35秒宿主预算。

计算在线程执行，不阻塞事件循环，单Server进程最多两项计算。超时不能杀死底层原生计算，槽位一直保留到计算真正退出；超时结果不会补写为调查成功结果，不自动反复重试。本次未增加后台计算作业队列。普通聊天大结果仍受现有12KB内联限制，调查结果可经证据分页读取。

在线重算逐个时刻写入基线，超时或中途失败可能已有部分时刻更新，不能把工具失败解释为整个窗口已回滚；不要自动重试整个窗口。

无需新增数据库迁移或模型配置。须同步发布Server、Agent和前端证据枚举；先更新Server目录，再重启Agent，client模式还需重载原生连接。保持既有OAuth、MCP开关及数据库路由配置，不自动更改权限或重启调查。

本次验证限schema、权限、协议目录和mock业务函数，不运行真实模拟、优化或付费模型。真实项目的模板同步状态、运算耗时、SCADA覆盖和结果准确性仍需另行验收。

2026-10-19 修复：EPANET 2 导出省略阀门默认 ACTIVE 状态行并保留数值设置，EPANET 3 导出保留原表达；覆盖文件和文本导出。MCP 在线模拟改为共用在线计算服务，方案模拟继续隔离。回归验证包含原生 EPANET 输入校验及 mock 在线基线写入，不重算真实项目历史数据。

标准水力模拟接入已通过后端schema/权限/隔离适配测试、Agent目录与权限测试、前端证据解析测试；Agent和前端类型检查、前端改动文件ESLint通过。隔离HTTP smoke使用真实两端SDK发现34项Server工具及40项合并工具，并核对 run_simulation 输入schema和上下文绑定/查询；身份服务及数据执行为fixture，不等同生产验收。测试启动器剔除宿主MCP环境配置，避免私有issuer覆盖测试的loopback设置。运行中的服务仍需同步重载后确认新目录，未启动真实模拟。