66 lines
7.3 KiB
Markdown
66 lines
7.3 KiB
Markdown
# MCP 项目服务
|
||
|
||
当前 Server 有 67 项工具：42 项查询、12 项计算、13 项预览式写入。Agent 合并六项宿主查询后共 73 项。目录来自 `app/mcp/catalog.py`，Agent 使用独立的有限白名单并在启动时全等核对。工具前缀为 `mcp_tjwater_`。
|
||
|
||
## 新增能力
|
||
|
||
| 领域 | 工具（省略前缀） | 权限 |
|
||
| --- | --- | --- |
|
||
| 区域与连接 | `list_regions`, `get_region`, `get_region_nodes`, `get_node_connections` | `webgis.view` |
|
||
| 空间范围与骨干节点 | `query_network_extent`, `list_major_nodes` | `webgis.view` |
|
||
| 模型配置 | `get_model_configuration`, `list_model_configurations` | `webgis.view` |
|
||
| 项目地名 | `search_project_places`, `reverse_geocode` | `webgis.view` |
|
||
| 项目概况与导出 | `get_project_info`, `export_project_model` | `webgis.view` |
|
||
| 监测点交付 | `get_sensor_placement_candidate`, `export_sensor_placement` | `optimization.run` |
|
||
| 调度与运行历史 | `list_task_schedules`, `get_task_run_history` | `operational_task.view` |
|
||
| 需水量分配 | `calculate_demand_allocation` | `webgis.view` |
|
||
| 假设爆管水力模拟 | `run_burst_simulation` | `simulation.run` + `scada.view` |
|
||
| 模型编辑 | `edit_model_element`, `edit_model_configuration` | `webgis.edit` |
|
||
| SCADA 维护 | `clean_scada_readings`, `write_scada_readings`, `delete_scada_readings` | `scada.clean` |
|
||
| 正式分析成果 | `save_simulation_scenario` | `simulation.run` + `scada.view` |
|
||
| 正式监测点方案 | `create_sensor_placement`, `update_sensor_placement` | `optimization.run` |
|
||
| 任务与定时配置 | `create_operational_task`, `create_task_schedule`, `update_task_schedule`, `retry_operational_task`, `cancel_task_run` | `operational_task.write` |
|
||
| 写入状态核实 | `get_mutation_status` | `webgis.view`，仅当前身份与会话的执行记录 |
|
||
|
||
健康预测不在本次接入范围。报告发布、工单/设备动作的提议与审批、消息发送继续使用既有受控插件和业务动作流程。
|
||
|
||
## 数据与计算边界
|
||
|
||
- 所有查询使用当前授权项目连接。当前只有 TJWater 提供 GIS 信息；其他项目没有所需 GIS 数据或关系时返回空数据/明确不可用，不借用 TJWater 的图层或数据库。空页不能证明其他数据源没有对象。
|
||
- 范围查询直接用 PostGIS `ST_Intersects`，不调用旧的空占位服务。范围和输出坐标为 EPSG:4326，单轴范围最多一度。查询模型几何，不把空间邻近称为供水连通。
|
||
- 区域成员优先使用已配置节点关系，未配置时使用区域几何；配置、几何成员与真实供水拓扑需分别解释。
|
||
- 模型配置 `data_path` 选择嵌套字段，`limit/offset` 对选中集合分页。模式和曲线可单独列出 ID。编辑字段必须通过现有模型 schema 的可写属性校验；有限业务枚举不接受 SQL、任意路由、命令、身份、数据库地址或文件路径。
|
||
- 需水量分配按关联管长权重，只返回建议值，不修改节点需水量；输入输出沿用模型流量单位。区域或全网结果按节点 ID 稳定分页。
|
||
- 爆管模拟输入是已说明依据的破口面积（cm²），不是流量。复用隔离模型，`persist_results=False`；这与异常侦测和候选定位是不同工具。
|
||
- 保存正式场景会重新执行真实计算并持久化成果。压力调节和关阀正式成果使用宿主绑定的用户名。计算共用原有两项并发槽位，超时后槽位保留至原生线程退出。
|
||
- 新建任务限未绑定 Agent 的 operator/agent 事件调查；不能伪造外部工单或租约。重试只重新入队，实际执行仍由原有 Worker 领取。取消、启停和方案点位更新复用现有版本或旧值校验。
|
||
|
||
## 写入预览和原生许可
|
||
|
||
13 项新写入工具只对项目成员的 `ordinary_chat` 开放。任务执行、任务协作、只读 reader、个人会话和学习复盘均不能调用。每次校验当前权限及绑定时的权限上限；写入工具不加入只读自动许可名单，管理员拒绝继续优先。交互聊天遵循现有本轮 request/always 策略，always 不改变业务权限。
|
||
|
||
1. 为具体操作生成 UUID `request_id`，默认 `dry_run=true`，取得预览与 `expected_digest`。预览不运行模拟/优化，也不写业务数据。
|
||
2. 保持相同参数和 `request_id`，使用 `dry_run=false` 及返回的 `expected_digest` 请求执行，并经过宿主原生许可。
|
||
3. 服务重新读取目标并校验摘要。模型预览复核与修改共用模型变更锁；SCADA 操作在时序库串行化事务中复核相关数据。数据变化返回冲突，须重新预览。
|
||
4. 执行前在现有 `workbench.mcp_query_receipts` 保存 started 记录，完成后保存结果。同一会话、身份、项目和请求键的完成操作返回原结果，已启动但状态不明确的操作不会再次执行。可用 `get_mutation_status` 核实记录，并通过目标查询核实实际数据。超时/进程退出可能已有部分结果，不能解释为回滚，也不能自动换键重试。
|
||
|
||
计算容量已满且原生函数尚未调用时，返回 `CALCULATION_CAPACITY_EXCEEDED`。
|
||
这类明确未执行的请求记为 `rejected`、`retryable=true`；状态查询同时返回具体
|
||
错误。容量释放后可用原身份、会话、项目、参数和 `request_id` 重试，仍需通过
|
||
原生许可和预览摘要复核。重试时继续锁定请求记录，成功后的重复调用只返回
|
||
已保存结果。其他 503、算法异常、超时或取消仍保留 `started`，不能据此自动重试。
|
||
|
||
SCADA 维护必须明确列出设备，窗口最多 24 小时。清洗/删除最多 10000 条，补录/修正最多 500 条，来源依据必填；不开放 `all`。数据写入清洗值或实测表，不从模拟结果构造实测。涉及 BizDB 和 TimescaleDB 时不承诺跨库事务原子性，执行日志中的 started 与业务修改之间也不承诺分布式 exactly-once。
|
||
|
||
## 导出与会话下载
|
||
|
||
`export_project_model` 从数据库导出 ZIP（INP 或 ChangeSet，含顶点和 SCADA 元素），`export_sensor_placement` 导出已有方案 XLSX。单文件最多 5 MiB；模型通过 ZIP 压缩传输。Server 返回长度及 SHA-256；Agent 验证后只写当前会话 `workspace/files/`，返回相对路径和下载链接，模型消息不包含文件正文或宿主绝对路径。导出暂不支持超过该预算的文件分片。
|
||
|
||
下载接口为 Agent `GET /api/v1/session/{session_id}/files/{filename}`。它复用身份与项目校验，验证会话所有权，仅接受服务生成的文件名格式，拒绝符号链接和跨会话目录。前端通过已认证的 Agent client 下载；链接和磁盘文件均不是公开资源。文件随会话持久化和删除，不引入独立结果引用存储。
|
||
|
||
无需数据库迁移、新环境变量或新密钥。地名搜索沿用项目配置与已有天地图服务凭据。需同步发布 Server、Agent、前端，再重载 Server 与 Agent 工具目录；不要以代码目录一致代替线上重载验收。
|
||
|
||
## 验证
|
||
|
||
运行 focused pytest、Agent MCP/策略/导出测试及类型检查、前端协议与下载测试、浏览器下载覆盖及构建。另用隔离 MCP fixture 验证两端 SDK 目录、上下文绑定和原生工具调用。测试不运行真实项目模拟、优化、SCADA 清洗或任何业务写入；真实项目运算与数据效果仍须按项目验收。
|