Skill: wuyanfeiwork/hap-upgrade (version 1.0.4)

--- name: hap-upgrade description: 明道云 HAP 私有部署版本升级专属 skill。只要用户提到 HAP 私有部署升级、跨版本升级、升级注意事项、升级前后附加操作、单机或集群升级步骤、升级文档生成、版本兼容性或架构镜像支持，就必须触发本 skill。即使用户没有明确说“用 hap-upgrade”，只要任务与 HAP 私有部署升级决策或升级执行有关，也要使用本 skill。 --- # HAP 私有部署升级帮助 用于两类任务： - 回答 HAP 私有部署升级相关咨询 - 生成可执行的升级指南 Markdown 文档 核心原则： - 只依据官方文档和实时页面内容回答，不能凭记忆补全版本细节 - 允许跨版本直接升级，但必须合并跨越路径中的附加操作 - 架构兼容性以 `https://docs-pd.mingdao.com/version` 总表实时标记为唯一准则 - 所有命令必须保持官方原意，不擅自改写命令逻辑 ## 何时使用 出现以下任一情形时，必须使用本 skill： - 用户询问某个 HAP 私有部署版本是否能升级到另一个版本 - 用户询问升级前要做什么、会跨过哪些附加操作、是否支持跨版本升级 - 用户要求输出升级步骤、升级 SOP、升级文档、升级手册 - 用户给出当前版本、目标版本、部署模式、架构、联网情况，请求生成文档 - 用户询问某一目标版本是否支持 `AMD64` 或 `ARM64` 如果任务不是 HAP 私有部署升级，而是一般部署、故障排查、功能使用说明，不使用本 skill。 ## 输出类型 根据用户意图，在以下两种输出之间选择： - 咨询答复：给出结论、依据、风险点、缺失信息 - 升级指南：输出完整 Markdown 文档，包含可执行步骤和末尾声明 如果用户明确要求“生成文档”“给我一份操作手册”“整理成升级指南”，按升级指南处理。否则默认先给咨询答复；当信息齐全时，也可以直接生成文档。 ## 执行顺序 严格按以下顺序执行，不要跳步。 ### Step 1. 先收集 5 项关键信息 如果用户未提供完整信息，先补齐，再继续： 1. 当前版本，例如 `v7.0.4` 2. 目标版本，例如 `v7.2.0` 3. 部署模式：`单机模式` 或 `集群模式` 4. 架构：`AMD64` 或 `ARM64` 5. 服务器是否可访问互联网 这 5 项不完整时，不得生成最终升级文档。 ### Step 2. 规范化版本号 在后续所有步骤中，同时维护两种版本号形态： - 应用版本：不带 `v`，用于命令、镜像标签、脚本参数、配置文件 - 显示版本：带 `v`，用于标题、正文说明 规范化规则： - 用户输入 `v7.1` 时，规范化为应用版本 `7.1.0`，显示版本 `v7.1.0` - 用户输入 `7.2.0` 时，应用版本保持 `7.2.0`，显示版本补成 `v7.2.0` - 任何命令、URL、镜像 tag 中都不要带 `v` ### Step 3. 先读取本地参考文件 开始抓取官网前，按需读取这些资源： - `references/site-structure.md` - 只用于了解 URL 规律、页面入口和部署文档位置 - 不能使用其中的兼容性快照替代实时校验 - `references/merge-rules.md` - 用于合并跨版本附加操作 - `references/command-library.md` - 用于生成联网 / 离线、单机 / 集群、AMD64 / ARM64 的示例命令 - `assets/upgrade-guide-template-standalone.md` 或 `assets/upgrade-guide-template-cluster.md` - 仅在需要生成升级指南时读取 - 必须先读取模板，再填充文档 ### Step 4. 抓取官方实时页面 必须抓取： - 版本总表：`https://docs-pd.mingdao.com/version` 从总表中识别： - 当前版本到目标版本之间所有被跨过的版本 - 不含当前版本 - 包含目标版本 - 按从旧到新排序 - 每个版本是否“含附加操作” - 目标版本在所选架构列中的实时标记 仅对“含附加操作”的版本，再抓取其详情页： - URL 规律：`https://docs-pd.mingdao.com/upgrade/{应用版本}/` 如果升级详情页中的附加操作只是一个超链接、跳转入口或“详见某文档”的简写，不能停在该页面文本。必须继续打开对应链接，提取实际执行步骤、命令、依赖资源和注意事项，再整理进最终文档。 ### Step 5. 做架构校验，必要时立即中止 架构校验是最高优先级。只以总表中的实时标记为准： - `✅` 才表示支持 - 空白、`❌`、缺失、无法确认，都视为不支持 - 不能因为详情页出现通用命令、arm64 标签页或相似内容，就推断该版本支持该架构 如果目标版本不支持用户指定架构，立即停止生成文档，并直接回复： `抱歉，目标版本 {显示版本} 官方尚未发布 {架构} 镜像（以发布历史总表为准），升级文档生成任务已中止。` ### Step 6. 提取附加操作并分类 仅从“含附加操作”的版本详情页提取实际需要的操作，分成两类： - HAP 微服务升级前操作 - HAP 微服务升级后操作 可能遇到的升级前操作示例： - 镜像命名变更 - 创建 MongoDB 数据库 - 存储组件升级（仅单机） - 文档预览服务升级 - 重新初始化预置文件 - MongoDB 预置数据更新 - 集群 `service.yaml` 新增服务配置 可能遇到的升级后操作示例： - 单机进入容器执行 MySQL DDL - 集群进入 config Pod 执行 MySQL DDL - 集群进入 config Pod 执行 MongoDB DDL - 集群进入 config Pod 执行文件初始化命令 这些只是示例，不是完整列表。不要根据“示例类型”虚构步骤，也不要把未列出的线上实际操作忽略掉。详情页没有的，不生成；详情页实际出现但此处未列出的，也必须纳入处理。 ### Step 7. 合并跨版本附加操作 如果跨越多个含附加操作的版本，必须读取并遵循 `references/merge-rules.md`。要把它理解为“合并原则文档”，不是“允许操作类型清单”。 特别注意： - 同类 MongoDB 建库应合并成一次登录和一次整理后的建库列表 - 存储组件只升级到跨越路径要求的最高版本 - MongoDB 预置数据只执行涉及该操作的最新版本命令 - 升级后脚本按版本从低到高顺序排列 - 集群新增服务配置需要把多版本新增项合并到同一节里 ## 生成升级指南时的要求 ### 1. 先选模板 根据部署模式读取模板： - 单机模式：`assets/upgrade-guide-template-standalone.md` - 集群模式：`assets/upgrade-guide-template-cluster.md` 禁止脱离模板凭记忆重写整个结构。 ### 2. 再填内容 填充文档时，遵守以下规则： - 文档顶部信息必须补全升级路径、部署模式、架构、网络情况、生成日期 - 备份步骤必须保留在最前面 - “提前准备”必须汇总**本次升级实际会用到的全部资源**，不限于 HAP 微服务镜像。只要升级步骤或附加操作中会用到镜像、离线包、脚本、预置数据、额外组件资源，都应提前列出 - 如果某一阶段完全没有步骤，删除整节，不保留占位提示 - 所有命令必须给出完整代码块，不能写“同上”“省略”“按前文类似处理” - 生成的是面向执行者的文档，不要把模型的推理过程写进正文 - 如果线上文档把附加操作写成超链接或跳转说明，最终输出时必须把超链接背后的实际步骤展开写入对应章节，不能只给一个链接让用户自己点进去 ### 3. 严格裁剪模板块 模板中的可选段落必须清理干净： - 联网场景：只保留联网版本的段落，删除离线版本的段落 - 离线场景：只保留离线版本的段落，删除联网版本的段落 - 最终输出中不得保留“以下二选一”“按场景保留其一”“删除不适用内容”之类模板提示，也不得保留 `{...}` 占位说明或模板注释语 ### 4. 命令与内容来源 生成命令时，优先顺序如下： 1. 当前抓取到的官方升级详情页原文 2. `references/command-library.md` 3. 模板中的固定结构 如果三者出现冲突，以官方实时页面为准；但不要擅自拼接出官网没有表达过的新命令逻辑。 ### 5. 针对不同部署模式的硬规则 - 集群模式不能生成“存储组件升级”步骤，除非官方实时页面明确要求 - 单机模式不能生成 `kubectl`、`crictl`、`ctr` 命令 - 集群模式不能生成 `docker exec`、`service.sh restartall` 这类单机命令 - ARM64 时，涉及镜像名或更新命令时，必须检查是否需要 `-arm64` ## 仅做咨询答复时的要求 如果用户只是咨询，不一定要输出完整升级指南，但仍要遵循： - 先补齐缺失信息，或明确指出因为哪些信息缺失暂时无法下结论 - 涉及具体版本结论时，必须先抓取官方页面再回答 - 回答里要明确区分“已确认事实”和“基于缺失信息的待确认项” - 如果判断结果依赖架构支持或是否联网，要把这一点直接说清楚 ## 禁止事项 禁止出现以下行为： - 凭训练记忆回答具体版本是否支持某架构 - 直接使用 `references/site-structure.md` 中的兼容性快照当作结论 - 杜撰官网未出现的升级步骤、版本路径、下载地址或脚本命令 - 在最终文档中保留模板占位符、AI 推理说明、合并逻辑说明 - 在信息不完整时伪造缺失参数 ## 最终检查清单 在输出前，自检以下项目： - 已确认 5 项前置信息 - 版本号已同时规范化为应用版本和显示版本 - 已抓取 `/version` 实时页面 - 已按目标架构完成兼容性校验 - 已收集跨越路径中的含附加操作版本 - 已按 `merge-rules.md` 合并 - 需要生成文档时，已读取正确模板 - 已按网络场景裁剪模板中的可选段落 - 已把升级详情页或其跳转链接中的实际附加操作完整展开到正文 - 最终内容中无占位符、无逻辑注释、无残留条件标记 - 文末已追加声明 ## 固定声明 无论输出咨询答复还是升级指南，只要给出与升级执行相关的正式结论，末尾都附加以下声明： ```md --- 💡 声明：内容由 AI 生成。尽管已努力确保信息的合理性，但 AI 模型仍可能产生不准确、过时或存在偏差的内容。请在执行关键操作前，务必对照[官方文档](https://docs-pd.mingdao.com)进行核实校验。 ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)