hap-upgrade

明道云 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)进行核实校验。