# 煤矿通风 AI 技能库（Vent Skills）

面向煤矿 **「一通三防」/通风** 业务的 Agent 技能（ZCode Skills）集合。仓库内每个子目录是一个独立技能，内含 `SKILL.md`（技能描述、触发条件、执行流程、红线规则），部分技能附带 `scripts/`、`references/`、`sample/` 等资源文件。这些技能将通风日常工作中依赖经验的环节——配风计划审查、通风监测数据解读、需风量计算、报表台账汇总、通风系统阻力检查等——封装为可供 AI 助手稳定复用的工作流。

## 技能清单

| 目录 | 定位 | 典型触发 | 主要依赖 |
|---|---|---|---|
| `knowledge-base` | 煤矿安全知识库检索：《煤矿安全规程》/ AQ、MT 标准条款原文、重大事故隐患判定等 | "风速限值是多少""AQ 1056 参数""什么构成重大隐患" | `query_knowledge_base` |
| `dialog-interpret` | 对话式通风数据解读：自然语言提问 → 选巷道与指标 → 比对阈值/计划风量 → 结构化结论与建议 | "XX巷道风速风量怎么样""XX回风巷瓦斯为什么报红""近7天XX工作面温度趋势" | 平台注册工具 12+（巷道/设备/数据/知识四类）、`references/regulation-thresholds.md` |
| `click-interpret-device` | 前端点选单条**设备** → 合规校验、风险定级、固定格式解读报告 | 在平台界面点击/选中某设备数据行 | `query_device_data_by_id`、`query_knowledge_base` |
| `click-interpret-tun` | 前端点选单条**巷道** → 风速风量合规校验、四级风险细分、固定格式报告 | 在平台界面点击/选中某巷道数据行 | `query_tun_data_by_id`、`query_knowledge_base`、`query_tunnels_by_model` |
| `needq-calc` | 需风量/配风量交互式计算：采煤/备用/掘进/硐室/其他地点及多地点汇总 | "计算XX工作面需风量""帮我算硐室需风量""配风量计算" | `calc_*` 系列 16 个 MCP 工具、`get_needq_all_data`、子智能体 `needq_calc_expert` |
| `vent-device-daily-report` | 设备设施在线率统计与设备管理日报（按类型分组，🔴/🟠/🟢 告警） | "给我设备管理日报""统计设备在线率""主通风机在线情况" | TF-MCP `execute_sql_query`（vent 库）、`scripts/device_online_report.py` |
| `vent-operation-daily-report` | 通风设备与传感器**运行日报**导出：前一日 7 类真实设备 max/min/avg、风门开闭次数、异常明细 | "帮我导出通风设备与传感器运行日报""昨天主通风机运行怎么样" | 平台 MCP（:8071/mcp）、`scripts/vent_daily_report.py`、fastmcp |
| `vent-monthly-summary-product` | **公司端**通风月报汇总：各矿《通风月报表》xlsx → 《公司通风月报汇总表》并自动合计、入库 | "汇总通风月报""把各矿月报汇总到公司表""生成公司X月通风月报汇总表" | 函数工具链、子智能体 `monthly-report-extractor`、沙箱资产（提取契约 + 模板 xlsx） |
| `vent-plan-review` | 配风计划 PDF 审查**顶层总流程**：并行委派三个子智能体审查，汇总输出 + 六节 Word 报告下载 | "审查/研判/审核这份配风计划"（上传 PDF） | `extract_uploaded_pdf_text`、`save_word_report`、`task` 委派 |
| `vent-plan-review-form` | 配风计划**基本形式审查**（子技能）：版本月份、签字、编制时间、计算过程完整性、语病逻辑 | 由上级 task 委派（plan-review-form） | `get_current_time`、`write_todos` |
| `vent-plan-review-data` | 配风计划**数据一致性审查**（子技能）：用风地点完整性、瓦斯/CO₂ 双重交叉验证、工作面参数与作业规程、风速温度匹配 | 由上级 task 委派（plan-review-data） | `query_mining_plan`、`query_face_procedure`、`query_gas_report`、`query_wind_report`、`calc_gas_emission_from_wind` |
| `vent-plan-review-calc` | 配风计划**计算核验**（子技能）：逐用风地点核验需风量公式/参数/结果（偏差分级） | 由上级 task 委派（plan-review-calc） | `calc_*` 15 个工具、`write_todos` |
| `vent-resistance-check` | 矿井通风系统阻力检查：回风系统最大阻力路线与总阻力解算、核验、隐患分析报告 | "计算某回风井/回风系统的关键阻力路线及总阻力""通风阻力检查" | TF-MCP 解算引擎、vent 库 SQL、云通防知识库、`scripts/mcp_call.js`、`references/capability-map.md` |
| `wind-hazard-diagnosis` | 风速风量监测与隐患判识：超限/风量不足/重大事故隐患（需风量 <75% 红线），固定格式 md 报告 | "查询当前风速风量""测风数据有没有问题/隐患" | TF-MCP（:8071）、云通防知识库（:8067）、`get_needq_all_data` |
| `vent-web-nav` | 通防平台**网页指引**：口语找页面→可点击链接+功能简介+分步操作指引；全量树状网页地图（按类/主题筛选）；部署前缀一键切换；新功能发布后菜单差集自动同步注册表 | "帮我打开风门监测页面""给我网页地图/只看瓦斯类""罗列防灭火相关页面""风门怎么远程开""将网址换成 http://xx""我部署了新功能，请更新网页指引" | `references/pages.yaml` 页面注册表（84条：别名/关键词/menu_key/路径/简介/操作指引）、`sync_pages.py` 菜单差集、`build_pages.py`/`query.py` 校验与匹配工具、平台权限接口（按账号动态过滤） |

## 技能间协作关系

```
                        ┌─ vent-plan-review-form（形式审查）──┐
用户上传配风计划 PDF ──► vent-plan-review（编排）──task 并行──┼─ vent-plan-review-data（数据一致性）┼─► 六节报告 + Word
                        └─ vent-plan-review-calc（计算核验）──┘

knowledge-base ◄── 被 dialog-interpret / click-interpret-* 引用作为"依据"来源

needq-calc：由子智能体 needq_calc_expert 执行全部计算（主 Agent 不得自调工具）
vent-monthly-summary-product：逐矿委派 monthly-report-extractor 提取关键内容后批量填表
```

- **配风计划审查三件套**（`vent-plan-review` + `vent-plan-review-form/data/calc`）构成一条完整链路：审查输入为扫描/图片 PDF，技能内建 OCR 误识风险须知（排版错乱、数字误识、偏差 >50% 需人工核对）。
- `click-interpret-device` 与 `click-interpret-tun` 是"点选解读"姊妹技能，`dialog-interpret` 为其对话版超集；`needq-calc` 侧重"算多少风"，`vent-plan-review-calc` 侧重"核验计划算得对不对"。
- `vent-operation-daily-report`（运行日报）与 `vent-device-daily-report`（在线率/管理日报）刻意拆分，二者各自明示边界、不做合并。

## 通用约定（铁律）

各技能共享以下跨文件约束，新增技能请保持一致：

1. **绝不编造数据**：所有判定必须基于工具返回、平台数据或规程条款原文；数据缺失一律明示（"文档中未找到" / "外部数据查询失败"），缺失依赖时如实告知缺哪一环。
2. **规程依据统一**：《煤矿安全规程》以 **2025 版**为准，配风/需风计算配套 **AQ 1056-2008**；引用条款须给出具体条款来源。
3. **固定格式输出**：报告章节、表格列、判定用语与单位口径固定（风量 m³/min、风速 m/s、阻力/压差 Pa），禁止增删章节或改写固定用语；交付物含对话内 Markdown、落盘 md/json、可下载 xlsx、六节 Word 等多种形态。
4. **全程简体中文**；面向用户的输出不得暴露内部工具名 / 子智能体名 / 设备 ID（用名称代替）。
5. **优先并行委派**：编排类技能（plan-review、monthly-summary）要求同一轮并行 `task` 委派子智能体，禁止串行或跳过委派凭印象执行。

## 平台依赖

技能按取数方式分四层，运行前请确认对应依赖可用：

| 依赖 | 用途 | 相关技能 |
|---|---|---|
| 通防管控平台 MCP（TF-MCP / tf_mcp，:8071） | 设备/巷道/传感实时与历史数据、报警、需风量、解算引擎 | dialog-interpret、click-*、needq-calc、plan-review-data、resistance-check、wind-hazard-diagnosis |
| vent 库 SQL（`execute_sql_query`） | deviceinfo、sub_station、fan、ai_gate、tun/node 等表直查 | vent-device-daily-report、vent-resistance-check |
| 云通防知识库（:8067，Obsidian Vault Knowledge Service） | 规程条款佐证、隐患分析 | wind-hazard-diagnosis、vent-resistance-check、knowledge-base |
| 平台注册函数工具 + 沙箱资产 | PDF 提取、Word/Excel 处理、下载发布、入库登记 | vent-plan-review、vent-monthly-summary-product |
| 平台权限接口（JEECG `getUserPermissionByToken`） | 网页指引按账号动态过滤可见页面（menu_key 对齐）、新功能菜单差集同步 | vent-web-nav |

跨工具容错策略不统一，各技能自洽：`vent-resistance-check` 提供 `references/capability-map.md`（C1~C7 能力契约与降级表，C4 解算引擎不可降级）；`vent-operation-daily-report` 支持 Python 脚本直连平台实现宿主无关；`wind-hazard-diagnosis` 依赖写死、缺失只明示不静默降级。

## 安装

本仓库是技能的**源目录**，不直接运行。将所需技能目录（连同 `SKILL.md` 及该目录下全部附带文件）整体复制到 ZCode 技能目录即可，例如：

```bash
cp -r vent-plan-review vent-plan-review-form vent-plan-review-data vent-plan-review-calc \
      ~/.zcode/skills/
```

> 含 `scripts/`、`references/`、`sample/`、`assets/` 的技能必须整目录复制并保持相对结构，脚本路径依赖目录内文件。

## 技能内附文档

部分技能自带独立使用文档，包含安装、字段表、输出样例与踩坑记录：

- `vent-device-daily-report/README.md`（含 `scripts/device_online_report.py` 用法）
- `vent-web-nav/GUIDE.md`（使用与维护手册：三种架构接入、维护三铁律、歧义词维护经验、新功能发布一句话同步流程）
- `vent-operation-daily-report/README.txt`（含 `scripts/vent_daily_report.py` 两种安装方式、`sample/` 输出样例、`requirements.txt`）
- `vent-resistance-check/README.md`（含 `references/` 能力契约/隐患清单/报告模板、`scripts/mcp_call.js`）
- `wind-hazard-diagnosis/README.md`
- `dialog-interpret/references/regulation-thresholds.md`（2022 版阈值速查，正式判定以 2025 版规程为准）

## 说明

- 文中平台地址为部署示例，实际使用以现场环境为准；技能均以真实平台数据为唯一数据源。
- 仓库根目录 `README.md` 即本文档；各技能目录内可另带独立 `README`，两处描述如有出入以对应技能 `SKILL.md` 为准。