vent_skills/vent-resistance-check/references/capability-map.md

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

本 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 输出契约样例（自行实现解算对接时对齐此结构）

{
  "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 绑定