- 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 项关键信息
如果用户未提供完整信息，先补齐，再继续：
- 当前版本，例如
v7.0.4 - 目标版本，例如
v7.2.0 - 部署模式：
单机模式或集群模式 - 架构：
AMD64或ARM64 - 服务器是否可访问互联网
这 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. 命令与内容来源
生成命令时，优先顺序如下：
- 当前抓取到的官方升级详情页原文
references/command-library.md- 模板中的固定结构
如果三者出现冲突，以官方实时页面为准；但不要擅自拼接出官网没有表达过的新命令逻辑。
5. 针对不同部署模式的硬规则
- 集群模式不能生成“存储组件升级”步骤，除非官方实时页面明确要求
- 单机模式不能生成
kubectl、crictl、ctr命令 - 集群模式不能生成
docker exec、service.sh restartall这类单机命令 - ARM64 时，涉及镜像名或更新命令时，必须检查是否需要
-arm64
仅做咨询答复时的要求
如果用户只是咨询，不一定要输出完整升级指南，但仍要遵循：
- 先补齐缺失信息，或明确指出因为哪些信息缺失暂时无法下结论
- 涉及具体版本结论时，必须先抓取官方页面再回答
- 回答里要明确区分“已确认事实”和“基于缺失信息的待确认项”
- 如果判断结果依赖架构支持或是否联网，要把这一点直接说清楚
禁止事项
禁止出现以下行为：
- 凭训练记忆回答具体版本是否支持某架构
- 直接使用
references/site-structure.md中的兼容性快照当作结论 - 杜撰官网未出现的升级步骤、版本路径、下载地址或脚本命令
- 在最终文档中保留模板占位符、AI 推理说明、合并逻辑说明
- 在信息不完整时伪造缺失参数
最终检查清单
在输出前，自检以下项目：
- 已确认 5 项前置信息
- 版本号已同时规范化为应用版本和显示版本
- 已抓取
/version实时页面 - 已按目标架构完成兼容性校验
- 已收集跨越路径中的含附加操作版本
- 已按
merge-rules.md合并 - 需要生成文档时，已读取正确模板
- 已按网络场景裁剪模板中的可选段落
- 已把升级详情页或其跳转链接中的实际附加操作完整展开到正文
- 最终内容中无占位符、无逻辑注释、无残留条件标记
- 文末已追加声明
固定声明
无论输出咨询答复还是升级指南，只要给出与升级执行相关的正式结论，末尾都附加以下声明：
---
💡 声明：内容由 AI 生成。尽管已努力确保信息的合理性，但 AI 模型仍可能产生不准确、过时或存在偏差的内容。请在执行关键操作前，务必对照[官方文档](https://docs-pd.mingdao.com)进行核实校验。