# 网页指引 Skill 需求梳理文档

> 版本：v2.0（经 brainstorming/grilling 拷问后修订）｜ 日期：2026-09-07 ｜ 状态：七项决策已与用户逐条确认

## 1. 背景与目标

矿井一通三防智能管控平台（通防管控平台）内嵌了智能助手（顶栏机器人图标，聊天面板形态）。平台页面多、层级深，用户记不住入口。需要一个"**网页指引**"skill，让用户用自然语言即可：

1. **快速直达**：说"帮我打开风门监测页面"→ 返回该页可点击链接 + 功能简介；
2. **全局地图**：说"给我网页地图"→ 聊天内输出全部页面树状地图，按需访问；
3. **换环境不换脑子**：部署地址变化时说"将网址换成 XXX"→ 所有链接前缀随之更换；
4. **会用页面**：说"风门怎么远程开"→ 给出页面内分步操作指引。

**总目标：把"找页面"从 3-5 次点击/检索降为 1 句话，把"学页面"从摸索降为一问。**

## 2. 实机验证事实（2026-09-07，182 演示环境，lizuo 测试账号）

| 事实 | 影响 |
| --- | --- |
| 智能助手面板支持 Markdown 蓝色可点击链接 | 链接直达方案可行 ✅ |
| 点链接后：AI 面板自动关闭 + 当前窗口路由跳转 | 链接即跳转，无需额外交互 ✅ |
| **现有实现给出的"风门监测与控制"链接点击后跳到了首页模型页而非风门页** | 现有实现链接指向有误 → 本 skill 替换它 |
| 现有回答格式已是"【页面名】+功能简介+🔗立即打开"，且快捷 chips 预置了"帮我打开风门监测页面" | 导航是智能助手预设场景，本次是固化+补全+纠错 |
| 智能助手每日配额 10 次 | 页面地图等一次回答要尽量全量，避免多次追问 |
| 权限外路由统一 404，无法区分"不存在/无权限" | 权限需前置过滤（动态感知） |
| 21 页详测 + 26 页路由模式验证 + 4 页 404 | 数据来源可靠，详见《通防平台页面学习记忆.md》 |

## 3. 已确认决策（与用户逐条对齐，共九项）

| # | 决策点 | 结论 |
| --- | --- | --- |
| D1 | 与平台现有实现关系 | **替换**：本 skill 成为智能助手网页指引能力的唯一权威源 |
| D2 | 智能体架构 | **有工具调用（function calling）**：skill 主形态为"数据文件+工具封装"，prompt 注入为降级方案 |
| D3 | 换前缀作用域 | **全局持久化**：工具写后端配置，所有用户所有会话生效，带变更历史 |
| D4 | 权限感知 | **按账号动态感知**：运行时调平台菜单/权限接口，按当前用户过滤页面 |
| D5 | 网页地图形态 | **聊天内树状图**（通用性优先，不做平台弹窗） |
| D6 | 能力边界 | **指路 + 操作指引**（"怎么操作"给页面内步骤；21 个实测页有素材） |
| D7 | 清单维护 | **人工维护 pages.yaml** + 运行时动态权限过滤（不做自动同步脚本） |
| D8 | 交付位置 | 仅工作区 `D:\ZCodeWorkspaces\web-nav-guide\`，不装用户级目录 |
| D9 | 数据格式 | **YAML（人工维护）+ JSON（机器读取）双份**，维护时改 YAML 后重新生成 JSON |

## 4. 功能需求

### F1 模糊页面导航（单页直达）【核心】
- **触发**："打开/进入/跳转/带我去/看一下 + 页面/系统/页面名"，如"帮我打开风门监测页面""打开风门操控""我要看主扇数据"。
- **匹配策略**（优先级）：① `name` 精确 → ② `aliases` 精确（主扇/局扇/甲烷等口语词）→ ③ name/aliases/keywords 包含匹配 → ④ 分类名命中（转 F2 按类输出）。
- **权限前置**：匹配结果先按当前用户可见菜单（D4）过滤；不可见=未找到。
- **输出**：页面名 + 一句话简介 + 完整可点击链接。
- **歧义**：多候选并列时列前 3（简介+链接）供选择，不猜。
- **未找到**："未找到此页面" + 最相近 3 个候选（权限过滤后）。
- **设备类页面**：path 已内置默认设备实例 ID，只说设备类型即可直达。

### F2 网页地图（树状全量导航）【核心】
- **触发**："网页地图/页面地图/都有哪些页面/平台功能一览/只看XX类页面"。
- **输出**：分类→子类→页面三级树，每页一句话简介+链接；标注当前部署地址；支持按大类筛选。
- **全量输出**（权限过滤后的全量），不省略条目——每日配额有限，一次给全。

### F3 部署前缀切换【核心】
- **触发**："将网址换成 XXX / 把前缀改为 XXX / 切换部署地址"。
- **校验**：`http(s)://host[:port]`；只有 `host:port` 时自动补 `http://` 并告知；去尾斜杠；非法格式向用户确认。
- **持久化（D3）**：调 `set_base_url` 工具写后端配置 + 追加 history；确认后用示例链接验证展示。
- **降级**：无工具环境仅会话内生效，明确告知"仅本会话有效"。

### F4 权限与不可见页面（D4 动态感知）
- 页面注册表每页带 `menu_key`，与平台菜单/权限接口返回对齐；
- 所有输出（F1/F2/F6）先按当前用户可见 menu_key 集合过滤；
- 用户执意要未开通页面 → "该页面您当前无权访问或未开通，请联系管理员"。

### F5 通用性（跨智能体架构，D2/D9）
- 主形态：数据文件（pages.yaml/pages.json + config）+ 4 个工具封装（query_page / get_page_map / set_base_url / get_visible_menus）；
- 降级形态：SKILL.md 指令 + 数据可直接注入系统提示词；
- 兼容 Agentskills 目录规范（ZCode/Claude Code 直接挂载）；
- 数据与逻辑分离，维护只动 YAML。

### F6 页面操作指引【新增，D6】
- **触发**："XX怎么操作/怎么远程开风门/怎么一键测风/XX页面怎么用"。
- **输出**：页面链接 + 分步操作步骤（来自注册表 `usage` 字段）。
- **素材边界**：21 个实测页有完整步骤；未实测页 usage 标"待补充"，回答时如实说明并给链接。

## 5. 非功能需求

| 编号 | 要求 |
| --- | --- |
| N1 | 页面数据集中在 pages.yaml，运维人员无需懂代码即可增删改 |
| N2 | 所有输出链接完整可点击（base_url+path 拼接，无双斜杠） |
| N3 | 全中文；简介每页 ≤60 字；操作指引分步、每步一句 |
| N4 | 换矿部署：改 base_url + 换设备实例 ID + 对齐 menu_key 即可 |
| N5 | 不采集不上传用户数据；skill 只读平台路由知识 |

## 6. 交付物清单

```
vent-web-nav/
├── SKILL.md              # 技能定义：工具调用主路径 + prompt注入降级 + 意图A-F
├── config.yaml           # 部署前缀（base_url + 变更历史；工具或人工写入）
├── references/
│   ├── pages.yaml        # 页面注册表（84页：别名/关键词/menu_key/路径/简介/操作指引）
│   ├── pages.json        # 由 pages.yaml 生成，机器读取
│   ├── build_pages.py    # 校验+生成脚本
│   ├── sync_pages.py     # 新功能发布后菜单差集同步
│   ├── query.py          # 命令行匹配测试
│   └── simulate_output.py # 输出效果模拟
├── ADAPTATION.md         # 三种架构接入指南 + 维护手册
├── GUIDE.md              # 使用与维护手册
└── REQUIREMENTS.md       # 本文档
```

## 7. 边界与开放问题

1. 角色管理与用户管理在 docx 中共用同一 URL，暂按同址录入并注明，待管理员账号核实；
2. 设备实例 ID 与矿井/模型绑定，换矿需重新录入（维护流程见 ADAPTATION.md）；
3. menu_key 命名约定是本 skill 假设，接入时需与平台菜单接口实际返回对齐（对齐方法见 ADAPTATION.md）；
4. 404 无法区分"不存在/无权限"，统一按"未找到或无权限"话术；动态权限过滤上线后该场景大幅减少；
5. 平台智能助手每日 10 次配额属于平台侧配置，与本 skill 无关。

## 8. 验收场景（交付时逐项演示）

| # | 输入 | 期望输出 |
| --- | --- | --- |
| A1 | 帮我打开风门监测页面 | 【风门监测与控制】+简介+正确链接（指向 monitor-gate 而非首页） |
| A2 | 给我网页地图（瓦斯类） | 瓦斯类 5 页树状图+链接 |
| A3 | 将网址换成 http://10.120.3.15:8092 | 校验+持久化+示例链接确认 |
| A4 | 风门怎么远程开 | 风门页链接+分步操作（远程模式→开门按钮→操作历史） |