通防平台网页指引 Skill · 使用与维护手册

版本 v1.0 ｜ 2026-09-07 ｜适用包：vent-web-nav/ 本手册面向两类角色：接入开发者（把 skill 接入智能体）与运维维护者（日常更新页面数据）。更深的架构级接入细节见 ADAPTATION.md，需求背景见 REQUIREMENTS.md。

1. 这个 skill 是什么

一句话：让平台用户用一句话直达任何页面——返回页面名、功能简介、可点击链接；顺带教会基本操作、支持全量网页地图和部署地址切换。

五类能力（用户怎么说 → 智能体怎么做）：

意图	用户说	智能体输出
A 打开页面	帮我打开风门监测页面 / 我要看主扇数据	页面名+简介+🔗链接（多候选时并列给出让用户点选）
B 网页地图	给我网页地图 / 只看瓦斯类 / 罗列防灭火相关页面	分类树状地图（可按类、按主题词筛选）
C 换前缀	将网址换成 http://10.120.3.15:8092	校验→持久化→示例链接确认
D 打不开	点了链接 404	"未开通或无权限，联系管理员"话术
E 怎么操作	风门怎么远程开 / 怎么一键测风	页面链接 + 分步操作指引

2. 文件包结构

vent-web-nav/
├── SKILL.md               # 行为指令（智能体读：意图路由、匹配规则、输出模板）
├── config.yaml            # 部署前缀 base_url + 变更历史
├── ADAPTATION.md          # 三种架构接入的实现细节 + 维护手册（本手册的工程版）
├── REQUIREMENTS.md        # 需求文档（九项已确认决策、验收场景）
├── GUIDE.md               # 本手册
└── references/
    ├── pages.yaml         # ★ 页面注册表（人工维护的唯一权威数据源）
    ├── pages.json         # 机器读取版（脚本生成，不要手改）
    ├── build_pages.py     # 校验 + 生成脚本（改完 yaml 必跑）
    ├── sync_pages.py      # 新功能发布后：菜单树差集同步
    ├── query.py           # 命令行快速匹配测试
    └── simulate_output.py # 四类场景输出效果模拟

核心原则：数据和逻辑分离。 改页面 → 只动 pages.yaml；改部署地址 → 只动 config.yaml（或对智能体说一句话）；SKILL.md 基本不用动。

3. 快速开始（接入开发者）

接入方式	适用	前缀持久化	权限过滤	详细步骤
A 工具封装（推荐）	有 function calling 的智能体（平台智能助手）	✅ 全局生效	✅ 动态（调权限接口）	ADAPTATION.md §一A
B prompt 注入	纯对话智能体	❌ 仅会话内	❌ 静态（visible 裁剪）	ADAPTATION.md §一B
C 目录挂载	ZCode / Claude Code 等	✅ 改 config 文件	❌ 静态	ADAPTATION.md §一C

方式 A 的四个工具签名：query_page / get_page_map / set_base_url / get_visible_menus，权限接口为平台自带： GET {base_url}/modelreq/sys/permissionNew/getUserPermissionByToken（JEECG Boot 架构，token 走 X-Access-Token 头）。

替换现有实现时：删除旧 prompt/知识中关于页面导航的部分，避免新旧并存给错链接（实测旧实现"风门"链接误跳首页模型页）。

4. 用户话术速查（接入后即可用）

实测通过的问法（2026-09-07，182 环境逐条验证）：

你说	得到
帮我打开风门监测页面	【风门监测与控制】链接直达 monitor-gate 详情页
帮我打开网络解算页面	两个候选并列（实时网络解算 / 首页3D模型），带区分说明，点选即达
帮我打开需风量分析页面	【需风量计算与分析】直达 /micro-need-air/
罗列出所有防灭火相关监测、控制、分析界面	按监测/控制/预警分析/联动场景/综合页五组列出 17 个页面
风门怎么远程开	风门页链接 + 5 步操作指引 + 置灰原因提示
将网址换成 http://xxx:port	前缀切换确认 + 示例链接（工具架构下全局生效）
给我网页地图 / 只看瓦斯类	全量树状地图 / 按类筛选地图

口语别名都可用：主扇、局扇、甲烷、束管、抽放、压风、空压机、大屏、文件、台账……完整别名表就在 pages.yaml 每条的 aliases 字段。

5. 日常维护（运维维护者）

5.1 三条铁律

只改 YAML，不改 JSON：pages.json 永远由脚本生成，手改会被覆盖；
改完必跑：python references/build_pages.py（校验数据 + 重新生成 JSON，红了先修再交付）；
上线前用 query.py 抽测：python references/query.py "口语词"，确认匹配结果符合预期。

5.2 新增一个页面

在 pages.yaml 对应分类/子类下加条目（字段模板）：

- id: my-new-page            # 唯一英文标识
  name: 页面中文名             # 匹配优先级最高
  aliases: [口语说法1, 口语说法2]  # 用户会怎么说就写什么
  keywords: [功能关键词]
  menu_key: /菜单路由path      # 权限对齐用；不接菜单权限则 null
  path: /页面相对路径?参数      # 打开平台该页，从浏览器地址栏复制 base_url 之后的部分
  desc: 一句话功能简介（≤60字）
  usage:                     # 操作指引（步骤逐条；没实测就写 null，不要编造）
    - 第一步…
    - 第二步…
  # visible: false           # 未开通/未验证时加此行隐藏
  # note: 维护备注

加完跑 build_pages.py，再用 query.py 验证新别名能命中。

5.3 启用 / 停用页面

启用未验证页（注册表里 11 个 visible: false 的菜单页）：浏览器直接访问确认能打开 → 删掉该条目的 visible: false 行和 note → 重跑脚本；
停用页面（该环境未部署/下线）：加一行 visible: false → 重跑脚本；
彻底删除：整个条目删掉 → 重跑脚本（docx 覆盖性校验会提示少了哪页，确认是有意删除即可忽略）。

5.4 换部署环境（换矿 / 换服务器）

改 config.yaml 的 base_url（或接入后直接对智能体说"将网址换成 xxx"）；
换设备实例 ID：设备详情页的 ?id=长数字 与矿井绑定——进新环境平台打开目标设备页，从地址栏复制更新到对应条目的 path；
权限核对：用管理员账号 token 调权限接口拉菜单树（curl 命令见 ADAPTATION.md §2.4），与 menu_key 比对，缺的补、错的改；
按 5.1 重跑脚本 + 抽测。

5.5 歧义词维护经验（实测踩坑）

用户口语与页面名经常错位。遇到"匹配错了/匹配不到"时：

症状	修法
匹配到了，但用户说"不是这个页"	该词是歧义词：把它同时加到两个页面的 `aliases`（同层并列命中会自动触发双候选呈现），如"网络解算"案例
匹配不到	把用户的说法加进目标页 `aliases`
想固定某个候选排第一	调整 pages.yaml 中条目顺序（并列呈现按注册表顺序输出）

5.6 新功能发布后：一句话更新指引（Intent F）

对智能体说"我部署了新功能，请帮我更新网页指引"即可，两种情况：

① 你能提供新页面网址（最好）：把网址给智能体，它直接打开页面阅读内容、拟写简介与操作指引、生成条目草稿，你确认后写入 pages.yaml。

② 提供不了网址（自动同步）：智能体运行 sync_pages.py 做菜单差集——不是爬页面，而是调平台权限接口一次拉取全量菜单树（权威路由清单），与 pages.yaml 比对：

# token 获取：登录平台 → F12 → 任意请求的请求头 X-Access-Token 复制
python references/sync_pages.py <JWT_TOKEN>

输出三样东西：

菜单新增清单（菜单有、注册表无的页面，含可见/隐藏标记与所属分组）；
疑似下线清单（注册表可见但菜单已无，提示权限/部署变化）；
sync_draft.yaml 草稿（每个新页面的条目骨架，desc/usage 标 TODO）。

之后的固定动作：智能体或你逐个浏览器打开新页面（HTTP 状态码识别不了 SPA 的 404，必须看渲染结果）→ 补写 desc/usage/别名 → 合并进 pages.yaml（新页面先 visible: false，验证后启用）→ 删草稿文件 → 跑 build_pages.py → query.py 抽测。

实测效果（2026-09-07，182 环境）：一次同步即发现 31 个注册表未收录页面（各矿首页主题、外链系统、隐藏详情页、需风量子页等），疑似下线 0 误报。外链 outlink 类与测试菜单类建议保持不启用。

6. 测试工具箱

工具	命令	用途
校验+生成	`python references/build_pages.py`	YAML 合法性、条目完整性、docx 覆盖比对、URL 拼接，并生成 pages.json
匹配测试	`python references/query.py "网络解算"`	走与 SKILL.md 一致的层级匹配，看命中哪些页
输出预览	`python references/simulate_output.py`	渲染四类场景 + 歧义场景的完整回答效果

（需要 Python 3.8+ 与 PyYAML：pip install pyyaml）

7. 常见问题 FAQ

Q1：用户点链接 404？ 按流程 D 话术回复（未开通或无权限）。若多个用户反馈同一页面 404：核对该环境是否部署了该模块 → 未部署则 visible: false 下线该条目。

Q2：换了前缀但新会话还是旧地址？ 方式 B（纯 prompt）下前缀只在本会话生效，这是架构限制；需要全局生效请用方式 A（工具写后端配置）或人工改 config.yaml 后重新注入。

Q3：不同账号看到的页面应该不一样？ 方式 A 按 menu_key 动态过滤（调权限接口）；方式 B/C 只能静态裁剪——把该部署未开通的页面设 visible: false。

Q4：智能体回答里链接格式乱/不可点？ 确认宿主聊天面板支持 Markdown 链接（平台智能助手实测支持，蓝色可点击）；输出必须是 [名称](完整URL) 格式。

Q4b：怎么让链接在新标签页打开（不覆盖当前页面）？ 两轮实测结论：平台聊天面板会转义 HTML（<a target="_blank"> 显示为代码文本，不可用），但 Markdown 链接正常渲染且无 target 属性 → 同窗跳转。此问题 skill 侧无法单独解决，需平台前端在消息渲染器中给链接统一加 target="_blank"——一行配置代码见 ADAPTATION.md"新标签页打开"章节，改完 skill 所有链接即全量新标签页打开。另：智能体不得凭记忆转述 URL（实测会把端口 8092 写成 6092），链接必须逐字符来自注册表拼接。

Q5：怎么知道哪些页面还没操作指引？ pages.json 顶部 stats 里有 with_usage 计数；逐条看 usage: null 的就是待补页（素材参考《通防平台页面学习记忆.md》）。

8. 当前状态与待办

数据基线（2026-09-07，182 演示环境，lizuo 账号实测）：

84 条页面条目：51 可见（26 逐页实机详测 + 22 路由模式验证 + 3 实测补充）、25 条含操作指引、4 大分类；
禁用待验证 33 条：11 个菜单页未逐页实测、17 个设备台账页路径未实测、3 个系统配置页 404、机电硐室管控 182 未部署、2 个隐藏菜单页（火灾模拟/避灾路线）。

v1.1 待办（按优先级）：

用管理员账号核实系统配置三页真实路由（admin 接口明文登录被拒，疑前端加密；可改用浏览器登录后从地址栏复制）；
逐个验证 11 个 visible:false 菜单页并启用（一条命令流程见 §5.3）；
补写剩余 26 个可见页的 usage 操作指引；
设备台账 17 页验证启用；
新环境部署时按 §5.4 换前缀 + 换设备 ID + 权限对齐。

9. 版本记录

日期	版本	变更
2026-09-07	v1.0	初版交付；同日测试期迭代：网络解算歧义词双候选机制、主题词跨类检索规则（防灭火罗列场景）、实时网络解算 usage 实测回填

GUIDE.md 12 KB パーマリンク 履歴 Raw