vent_skills

煤矿通风 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 技能目录即可，例如：

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 为准。