ADAPTATION.md —— 跨架构接入指南与维护手册

本 skill 采用"数据与逻辑分离"设计：SKILL.md（行为指令）+ references/pages.yaml（人工维护权威数据）+ references/pages.json（机器读取版）+ config.yaml（部署前缀）。任何智能体框架只要能读到这些内容即可运行。

一、三种接入方式

方式 A：Function calling 架构（推荐，平台智能助手适用）

在后端实现 4 个工具，数据源为 pages.json + 后端配置存储：

# 伪代码示意
TOOLS = [
  query_page(query, top_n=3)    # 加载 pages.json → 按 name精确>aliases精确>包含 匹配
                                 # → menu_key 权限过滤 → 拼 base_url → 返回页面
  get_page_map(category=None)   # 返回权限过滤后的 分类→子类→页面 树
  set_base_url(url)             # 校验 http(s)://host[:port] → 去尾斜杠 → 持久化 → 记录history
  get_visible_menus()           # 调平台权限接口 → 返回当前用户可见菜单 path 集合
  sync_pages(token=None)        # 权限菜单树 ↔ pages.yaml 差集 → 新增/下线清单+草稿
                                 #（参考实现 references/sync_pages.py，可直接封装为工具）
]

权限接口对接（实测事实，182 环境）：

GET {base_url}/modelreq/sys/permissionNew/getUserPermissionByToken?token=<JWT>
Header: X-Access-Token: <JWT>
返回 result.menu[] 递归树：
  每项 { path, meta.title, hidden, children, component, id }

递归收集所有节点（含 hidden:true 与 children）的 path 得到可见集合；
页面 menu_key（去查询参数后的基础路径）命中集合 → 可展示；
menu_key: null → 不做权限过滤，默认展示；
当前登录用户的 JWT 从平台会话获取（智能体嵌在平台内，可直接取当前请求的 token）。

持久化存储：set_base_url 写入后端配置（数据库或配置文件均可），同时把旧值/新值/时间追加到 history——所有用户所有会话生效。

与现有实现的替换：实测平台智能助手现有"帮我打开风门监测页面"回答的链接点击后跳到首页模型页（指向错误）。接入本 skill 后，工具直接返回 pages.json 中实测正确的 path，替换旧知识/旧 prompt 中关于页面导航的部分。

新标签页打开（链接行为，两轮实测结论 2026-09-07）

目标：用户点击智能体给出的链接在新标签页打开，不覆盖当前页面、不关闭 AI 面板。

实测事实（182 环境平台聊天面板）：

✅ Markdown 链接 [名](url) 正常渲染为蓝色可点击链接；
❌ HTML 标签被转义为文本显示（<a href=...> 以等宽字体原样出现），skill 侧输出 HTML 锚点不可行；
❌ Markdown 渲染出的链接无 target 属性 → 普通浏览器中点击同窗跳转覆盖当前页（用户实测报告的行为）；
⚠️ 让智能体转述 URL 会把端口写错（8092→6092），因此 SKILL.md 规定 URL 必须逐字符来自 base_url+path 拼接。

修复方案（平台前端必改项，一行配置）：在 AI 面板的消息渲染器中给所有链接统一加 target="_blank"：

// markdown-it：所有链接统一新标签页
const defaultLink = md.renderer.rules.link_open ||
  ((t, i, o, e, s) => s.renderToken(t, i, o));
md.renderer.rules.link_open = (t, i, o, e, s) => {
  t[i].attrSet('target', '_blank'); t[i].attrSet('rel', 'noopener');
  return defaultLink(t, i, o, e, s);
};
// marked 等价写法
// renderer.link = (href, title, text) => `<a href="${href}" target="_blank" rel="noopener">${text}</a>`;

改完无需动 skill——skill 默认输出 Markdown 链接，前端加 target 后即全量生效。

备注：若未来面板升级为支持 HTML 渲染（验证方法：让 AI 输出一个 HTML 锚点看是否渲染成蓝色链接而非代码文本），可切换 skill 为 <a target="_blank"> 输出模式（见 SKILL.md 链接输出格式）。某些嵌入式 webview（应用内嵌浏览器）会拦截弹窗/新窗口，属宿主环境策略，不影响 Chrome/Edge 等普通浏览器。

方式 B：纯 prompt + 知识注入（降级方案）

无工具调用的智能体（纯对话接口）：

把 SKILL.md 正文（YAML 头以下）作为系统提示词片段注入；
把 pages.json 中 visible:true 的条目压缩成文本注入（保留 name/aliases/keywords/path/desc/usage；51 页全量约 8-10K tokens，若超限可去掉 usage 只留 desc，操作问题让用户进页面后看提示）；
把 config.yaml 的 base_url 值注入（部署时写死当前环境地址）；
限制：换前缀仅会话内生效（模型记住新前缀，本轮对话内使用），新会话回落到注入的默认值——SKILL.md 流程 C 已包含该降级话术；
限制：无权限接口可调，权限过滤退化为 pages.yaml 的 visible 静态裁剪。

方式 C：Agentskills 目录挂载（ZCode / Claude Code 等）

直接把 vent-web-nav/ 整个目录复制到技能目录：

ZCode：工作区 .agents/skills/vent-web-nav/ 或用户级 ~/.agents/skills/vent-web-nav/
Claude Code：~/.claude/skills/vent-web-nav/

技能会按 SKILL.md 里的 description 触发词自动激活；宿主用文件读取能力替代方式 A 的工具（读 pages.yaml/config.yaml），换前缀通过编辑 config.yaml 持久化。

二、维护手册

2.1 新增/修改页面

编辑 references/pages.yaml：在对应分类/子类下按字段模板添加条目（字段说明见文件头注释）；
运行 python references/build_pages.py 重新生成 pages.json 并校验；
若新增页面需权限过滤，menu_key 填权限接口返回的菜单 path（打开平台对应页面，从浏览器地址栏取基础路径即可）。

2.2 启用未验证页面

带 visible: false 的条目（菜单存在但未实测/未部署）：用浏览器直接访问确认可用后，删掉该行的 visible: false 与 note，重跑生成脚本。

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

改 config.yaml 的 base_url（或对智能体说"将网址换成 http://新地址"）；
设备详情页的设备实例 ID 会随矿井变化：进平台打开目标设备页面，从地址栏复制 ?id=... 更新对应条目的 path；
按新环境账号权限核对 visible 与 menu_key（用权限接口拉一次菜单树比对）；
重跑生成脚本。

2.4 menu_key 对齐方法

# 用当前账号 token 拉菜单树（浏览器 F12 从任意请求头 X-Access-Token 复制）
curl "{base_url}/modelreq/sys/permissionNew/getUserPermissionByToken?token=<JWT>"
# 递归取所有 path，与 pages.yaml 的 menu_key 比对，缺的补、错的改

2.5 YAML ↔ JSON 同步

唯一原则：只改 YAML，JSON 永远由脚本生成（直接改 JSON 会被下次生成覆盖）。

python references/build_pages.py   # 校验 + 生成，两全

2.6 已知待办（v1.1 候选）

系统配置三页（用户/角色/项目配置）真实路由待管理员账号核实（admin 接口明文登录被拒，疑前端加密）；
机电硐室管控：菜单配置为 /chamber-home，182 环境未部署（404），新环境部署后验证；
11 个 visible:false 的菜单页（通风网络解算、防灭火/防尘系统监测、抽采综合管控、瓦斯管网管控、避灾路线等）逐个访问验证后启用；
17 个设备台账页路径未实测，启用前验证；
usage 操作指引：29 个可见页仍为 null，可参照《通防平台页面学习记忆.md》逐页补写。

三、未来可选升级（本次不做）

平台前端弹窗版网页地图：get_page_map 工具返回的 JSON 树可直接递归渲染为平台自绘弹窗组件（聊天树之外的增强体验）；
页面清单自动同步：用权限接口菜单树自动比对 pages.yaml 提醒新增页面（当前按决策 D7 人工维护）；
页面自动打开：智能体返回链接的同时调平台前端路由事件直接跳转（当前按需求只给链接，用户点击跳转）。

ADAPTATION.md 8.1 KB Pysyvä linkki Historia Raaka