# 能力映射层（跨工具适配指引）

本 skill 默认调用 TF-MCP（通防管控平台 MCP）。在其他智能体工具（Claude Code、Cursor、Dify、Coze、自研 Agent 等）中运行时，按下表把"能力"映射为本环境的等价工具（MCP 工具、HTTP API、CLI、内部函数均可），映射不到的能力按"降级策略"处理，并在报告"数据来源与局限"中声明。

## 能力清单

| 编号 | 能力 | TF-MCP 工具 | 输入 → 输出契约 | 降级策略 |
|---|---|---|---|---|
| C1 | 取默认通风模型 | `get_model_param_pub_list` | 无入参 → `param.records[0].defaultmodelid`（字符串） | 让用户直接提供模型ID；或从平台配置项 `defaultmodelid` / `homeModelid` 读取 |
| C2 | 取回风井巷道ID列表 | `get_out_shafts(model_id: 字符串)` | model_id → `{ cnt, ids: [巷道ID...] }` | SQL：`SELECT nTunID FROM tun WHERE nModelID={id} AND nConnectType='0'`（风硐类巷道，connectType=0 连接到地面）；或人工提供 |
| C3 | 单条巷道详情（仅用于定位节点/名称） | `query_wind_by_tunid(tun_id: 小整数)` | tun_id → `{ tunnelName, fromId, toId, fQ, connectType, ... }` | SQL：`SELECT ... FROM tun WHERE nModelID={id} AND nTunID={tunId}`。**警告：该接口不按模型过滤，返回值可能是其他模型同ID巷道的数据，报告取数一律用带 nModelID 过滤的 SQL** |
| C4 | 最大阻力路线解算（核心，不可降级） | `get_max_resistance_path(model_id: 字符串, node_id: 字符串)` | → `{ bSucced, fMaxH: Pa, path: [巷道ID有序序列], strRemark }` | 无解算引擎时本 skill 无法完成核心计算；可对接通防平台等价 HTTP 接口（入参模型ID+终点节点ID，出参最大阻力与路线） |
| C5 | 批量巷道属性（含大ID巷道） | `execute_sql_query(SQL)` | 见 SKILL.md 第 4 步 SQL | 逐条调 C3；> 2^53 的巷道ID经整数通道必失真，只能由 SQL/字符串通道取，取不到即在报告中标注缺失，禁止编造 |
| C6 | 档案/知识库检索 | `get_file_list_by_type(type)` / `get_file_base64_by_id(id)` | 业务类型/文件名 → 档案列表与结构化内容 | 换用本环境文档库/知识库检索"云通防知识库"；再无则仅用内置判据（hazard-checklist.md）并声明"未接入现场档案" |
| C7 | 诊断增强（可选） | `get_model_fault_diagnosis` / `check_model_connect_status` / `check_model_one_dir_cycle` / `check_model_one_dir_node` / `check_model_diagonal_structure` / `get_three_area_distribution` / `get_key_path_decision` / `query_device_realtime_data` | 见各工具描述 | 整体跳过，报告声明"拓扑级诊断未执行"，不得声称排除循环风/角联/连通性问题 |

## 精度与参数红线（所有环境通用）

1. **模型ID与后补录巷道ID均可能 > 2^53（JS Number.MAX_SAFE_INTEGER）**：任何经 JSON number 的通道都会舍入失真（实测 2012326636757958658 被舍为 2012326636757958700 导致查空）。
   - 字符串型参数：传字符串；
   - 整数型参数的工具：**不要**用来传模型ID或大巷道ID；
   - SQL：把 ID 作为数字字面量写进 SQL 文本，无精度问题。
2. **回风井巷道ID ≠ 节点ID**：解算终点用风硐巷道的 `toId`（connectType="0"/连接到地面一侧，主风机侧）。
3. **SQL 保留字**：`window` 表必须写反引号。
4. **路线顺序保持**：MySQL 用 `ORDER BY FIELD(nTunID, id1, id2, ...)`；其他数据库用 CASE WHEN 或取回后在应用层按 path 序重排。
5. **诊断类接口可能超时**（大模型计算重，实测 30s 超时并拖垮会话）：超时一次后不要无限重试，按降级策略处理并如实标注。
6. **TF-MCP 为 HTTP（streamable http）传输**："Session not found" 表示服务端重启导致客户端会话失效，客户端重试无效。恢复方式：宿主端重连（ZCode：Settings → MCP 重连或重启会话）；应急可用本 skill 自带的 `scripts/mcp_call.js`（相对 SKILL.md 所在目录，Node.js ≥18）直连端点取数：`node scripts/mcp_call.js <工具名> "参数"`，其内部完成 initialize → notifications/initialized → tools/call 的完整握手。
7. **数据库风量单位为 m³/s**（fQ/fFixQ）：能力契约与取数保持平台原始单位；**报告呈现前 ×60 转为 m³/min（保留 1 位小数）**，阻力类数值显示取整（Pa），风速保持 m/s。转换只发生在报告呈现层。

## C4 输出契约样例（自行实现解算对接时对齐此结构）

```json
{
  "bSucced": 1,
  "fMaxH": 1077.756085,
  "path": [37, 41, 43, "...", 3217, 3957],
  "strRemark": "成功获得最大阻力路线"
}
```

- `fMaxH`：单位 Pa，**含调节（风窗）阻力**的总阻力；
- `path`：从进风侧起点到回风井风硐的巷道ID有序序列。

## vent 库核心表速查

| 表 | 用途 | 关键字段 |
|---|---|---|
| `tun` | 巷道（属性+解算结果） | nTunID, nModelID, strName, nFromID, nToID, fLength, fQ, fV, fHFric, fHTotal, nWindowID, nConnectType, fCoff |
| `node` | 节点 | 节点ID 与 tun.nFromID/nToID 对应 |
| `doc_vent_report` | 测风报表主表 | mine_name, report_date, 矿井总进/排风量、有效风量率 |
| `file_server_info`（经 MCP 文件接口访问） | 文件中心 | fileName, fileContent（结构化档案数据）, deviceId 绑定 |