vent_skills/vent-web-nav/REQUIREMENTS.md

网页指引 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	风门怎么远程开	风门页链接+分步操作（远程模式→开门按钮→操作历史）