# 通防平台网页指引 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 三条铁律

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

### 5.2 新增一个页面

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

```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 换部署环境（换矿 / 换服务器）

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

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

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

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

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

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

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

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

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

输出三样东西：
1. **菜单新增清单**（菜单有、注册表无的页面，含可见/隐藏标记与所属分组）；
2. **疑似下线清单**（注册表可见但菜单已无，提示权限/部署变化）；
3. **`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 待办（按优先级）：

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

## 9. 版本记录

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