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

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

## 一、三种接入方式

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

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

```python
# 伪代码示意
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"`：
```js
// 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 + 知识注入（降级方案）

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

1. 把 `SKILL.md` 正文（YAML 头以下）作为系统提示词片段注入；
2. 把 `pages.json` 中 `visible:true` 的条目压缩成文本注入（保留 name/aliases/keywords/path/desc/usage；51 页全量约 8-10K tokens，若超限可去掉 usage 只留 desc，操作问题让用户进页面后看提示）；
3. 把 `config.yaml` 的 `base_url` 值注入（部署时写死当前环境地址）；
4. **限制**：换前缀仅会话内生效（模型记住新前缀，本轮对话内使用），新会话回落到注入的默认值——SKILL.md 流程 C 已包含该降级话术；
5. **限制**：无权限接口可调，权限过滤退化为 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 新增/修改页面
1. 编辑 `references/pages.yaml`：在对应分类/子类下按字段模板添加条目（字段说明见文件头注释）；
2. 运行 `python references/build_pages.py` 重新生成 `pages.json` 并校验；
3. 若新增页面需权限过滤，`menu_key` 填权限接口返回的菜单 path（打开平台对应页面，从浏览器地址栏取基础路径即可）。

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

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

### 2.4 menu_key 对齐方法
```bash
# 用当前账号 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 会被下次生成覆盖）。
```bash
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 人工维护）；
- **页面自动打开**：智能体返回链接的同时调平台前端路由事件直接跳转（当前按需求只给链接，用户点击跳转）。