apecloud · weicao · May 3, 2026 · May 3, 2026
diff --git a/docs/addon-bootstrap-role-publish-guide.md b/docs/addon-bootstrap-role-publish-guide.md
@@ -1,5 +1,11 @@
 # Addon Bootstrap Role Publish 指南
 
+> **Audience**: addon dev / test 工程师，需要排查 primary 角色 / endpoint / VIP 误判时
+> **Status**: stable
+> **Applies to**: 任何 KB addon（HA topology 含 primary/secondary 角色概念的引擎）
+> **Applies to KB version**: any（role truth vs publish chain 是 K8s addon 通用问题，跨 KB 版本一致）
+> **Affected by version skew**: 不受 KB 版本影响 — bootstrap 初期 role truth 发布与 KB controller / endpoint controller 的相对 ordering 是 K8s 通用契约
+
 本文面向 Addon 开发与测试工程师，聚焦一个经常被混读的问题：当 primary service、pod role label、EndpointSlice 或 VIP reachability 表现异常时，问题不一定先出在 service 或 controller publish 链路，也可能更早出在 bootstrap 初期的 role truth 发布。
 
 正文只写通用方法论，不绑定某一个引擎。

diff --git a/docs/addon-componentdefinition-upgrade-guide.md b/docs/addon-componentdefinition-upgrade-guide.md
@@ -1,5 +1,11 @@
 # Addon ComponentDefinition 升级与 Immutable Spec 指南
 
+> **Audience**: addon dev / test 工程师，遇到 cluster 卡 Creating / component Unavailable / 升级 OpsRequest 卡住时
+> **Status**: stable
+> **Applies to**: 任何 KB addon（ComponentDefinition immutable spec 是 KB API 通用契约）
+> **Applies to KB version**: KB 1.0.x / 1.1.x / main（CmpD 不可变字段在 1.x 演进中保持，跨版本契约稳定）
+> **Affected by version skew**: KB 升级时 CmpD spec 字段集会随版本扩展（见 [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md)），但"已 immutable 的字段不能改"这条原则跨版本不变
+
 本文面向 Addon 开发与测试工程师，聚焦一个很容易被误判的问题：Addon 升级失败时，表面看起来像 cluster 卡在 `Creating`、component 不可用，甚至像 runtime 没起来，但 first blocker 其实可能更早地卡在 live `ComponentDefinition` 自身。
 
 正文只写通用方法论，不绑定某一个引擎。

diff --git a/docs/addon-control-plane-election-guide.md b/docs/addon-control-plane-election-guide.md
@@ -1,5 +1,11 @@
 # Addon 控制面选主收口指南
 
+> **Audience**: addon dev / test / TL，特别是设计或重构 HA 选主路径的工程师
+> **Status**: stable
+> **Applies to**: 任何 KB addon（HA topology 含 primary/secondary 选主语义的引擎）
+> **Applies to KB version**: any（control-plane 收口是设计原则，与 KB 版本解耦）
+> **Affected by version skew**: 不受 KB 版本影响 — role truth / publication truth / fencing truth 三类 truth 的单点收口是设计原则，跨 KB 版本一致
+
 本文面向 Addon 开发与测试工程师，聚焦一个通用主题：当实例角色判断、对外发布、fencing、failover / switchover 分散在多个脚本或组件里时，如何把选主职责收口到单一 control-plane。
 
 正文只写通用方法论，不绑定某一个引擎。具体引擎实现、命令、案例结论应放在独立案例材料中。

diff --git a/docs/addon-ops-restart-troubleshooting-guide.md b/docs/addon-ops-restart-troubleshooting-guide.md
@@ -1,6 +1,12 @@
 # Addon Ops Restart 排障分流指南
 
-本文面向 Addon 开发与测试工程师，聚焦一个常见但容易被混读的问题：当 restart / rolling restart / pod rolling update 看起来“卡住”时，先不要立刻进入 Pod 级进度分析，而要先判断这条 `OpsRequest` 是否已经真正进入执行体。
+> **Audience**: addon dev / test / 排障工程师，遇到 OpsRequest restart 看起来卡住时
+> **Status**: stable
+> **Applies to**: 任何 KB addon（OpsRequest queue/execute 分层是 KB 通用控制流）
+> **Applies to KB version**: KB 1.0.x / 1.1.x / main（OpsRequest queue 入口与执行体内部状态机契约跨 1.x 稳定）
+> **Affected by version skew**: 不受 KB 版本影响 — 'queue 入口未放行' vs '执行体内部' 的两段式排障逻辑跨版本一致
+
+本文面向 Addon 开发与测试工程师，聚焦一个常见但容易被混读的问题：当 restart / rolling restart / pod rolling update 看起来"卡住"时，先不要立刻进入 Pod 级进度分析，而要先判断这条 `OpsRequest` 是否已经真正进入执行体。
 
 正文只写通用方法论，不绑定某一个引擎。引擎相关实现、现场、样本结论放在独立案例材料中。
 

diff --git a/docs/addon-probe-script-fork-and-zombie-guide.md b/docs/addon-probe-script-fork-and-zombie-guide.md
@@ -1,5 +1,11 @@
 # Addon Probe 脚本 fork 与 zombie 进程指南
 
+> **Audience**: addon dev 写 probe / lifecycle 脚本时；addon test 在 idle / soak 阶段做 zombie 验证时；reviewer 检查 fork pattern 时
+> **Status**: stable
+> **Applies to**: 任何 KB addon（fork-from-probe / pipeline-with-timeout 模式跨引擎适用）
+> **Applies to KB version**: any（PID 1 reap 行为是 K8s 容器模型 / 内核契约，与 KB 版本解耦）
+> **Affected by version skew**: 不受 KB 版本影响 — kbagent SIGKILL probe 行为 + Go binary PID 1 不 reap 跨 KB 版本一致
+
 本文面向 Addon 开发与测试工程师，聚焦一类会被 5290 case 测试 0 product fail 都掩盖、但放到生产长寿 pod 上几小时就把集群打挂的问题：**addon probe / lifecycle 脚本里在 kbagent 容器内产生的 orphan 子进程，会以 zombie 形式累积，最终撞 pod PID 上限**。
 
 orphan 来源有两类：

diff --git a/docs/addon-reconfigure-guide.md b/docs/addon-reconfigure-guide.md
@@ -1,5 +1,11 @@
 # Addon Reconfigure 开发与排障指南
 
+> **Audience**: addon dev / TL，需要实现或排查参数 reconfigure 路径
+> **Status**: stable
+> **Applies to**: 任何 KB addon 的参数变更能力（含 dynamic 与 static 参数路径）
+> **Applies to KB version**: KB 1.0.x / 1.1.x（reload Action / dynamicParameters 契约稳定）；KB main / 1.2 reconfigure interface 重构跨版本演化与排障详见 `addon-reconfigure-version-skew-guide.md`（PR #13 待 land）
+> **Affected by version skew**: 是 — reconfigure interface 在 KB 1.0/1.1 vs KB main/1.2 不同（PR #10100 / #10109）；本 guide 主体写 1.0/1.1 路径，跨版本演化见 reconfigure-version-skew
+
 本文面向 KubeBlocks Addon 开发者，例如 MariaDB、PostgreSQL、Redis、Valkey 等 Addon 的维护者。
 
 目标是说明 Addon 在实现参数变更能力时，如何区分动态参数和静态参数，如何声明 `dynamicParameters` 与对应的 live-apply 执行路径，以及当 reconfigure 行为不符合预期时如何排查。

diff --git a/docs/addon-switchover-guide.md b/docs/addon-switchover-guide.md
@@ -1,5 +1,11 @@
 # Addon Switchover 开发与幂等性指南
 
+> **Audience**: addon dev / TL，需要实现 switchover / failover lifecycle action
+> **Status**: stable
+> **Applies to**: 任何 KB addon（HA topology 含 primary 切换语义的引擎）
+> **Applies to KB version**: any（lifecycle action 幂等性契约跨 KB 版本一致）
+> **Affected by version skew**: 不受 KB 版本影响 — switchover 幂等性原则、命名约定、错误处理跨 KB 版本稳定
+
 本文面向 KubeBlocks Addon 开发者，重点总结 switchover / failover 生命周期动作中的设计原则、幂等性语义、常见坑。引擎相关内容只放在案例附录中。
 
 ## 先用白话理解这篇文档

diff --git a/docs/addon-test-environment-gate-hygiene-guide.md b/docs/addon-test-environment-gate-hygiene-guide.md
@@ -1,5 +1,11 @@
 # Addon 测试环境 Gate 卫生指南
 
+> **Audience**: addon test 工程师 / TL，配置 runner / cleanup gate / pre-restart 验证流程时
+> **Status**: stable
+> **Applies to**: 任何 KB addon 测试工作流（cluster-level gate 是测试 hygiene 通用要求）
+> **Applies to KB version**: any（环境就绪契约与 KB 版本解耦）
+> **Affected by version skew**: 不受 KB 版本影响 — environment gate hygiene 跨 KB 版本一致
+
 本文面向 Addon 测试工程师与技术负责人，重点解决"机器/容器重启之后、跑测试之前，测试环境本身能不能用"的问题。它不是关于产品 / addon 的成功语义，而是关于**让 first blocker 不要落在测试环境本身**。
 
 ## 适用场景

diff --git a/docs/addon-test-host-stress-and-pollution-accumulation-guide.md b/docs/addon-test-host-stress-and-pollution-accumulation-guide.md
@@ -3,6 +3,8 @@
 > **Audience**: addon test engineer / TL、host 运维、值班工程师
 > **Status**: draft（cell-4 evidence pending；chapter 7 N=2 对账 pending）
 > **Applies to**: 任何在共享单 host k3d 环境跑 addon 全量回归的场景；具体引擎实现细节放案例附录
+> **Applies to KB version**: any（host stress / cascade reactive overload 是 K8s 平面通用现象）
+> **Affected by version skew**: 不受 KB 版本影响 — cleanup gate / cell-2 cascade / pollution accumulation 跨 KB 版本一致
 
 ## 先用白话理解这篇文档
 

diff --git a/docs/addon-tls-guide.md b/docs/addon-tls-guide.md
@@ -1,5 +1,11 @@
 # Addon TLS 开发与验证指南
 
+> **Audience**: addon dev / TL，需要实现或排查 TLS 能力（cert rotation / mTLS / cert-manager 集成）
+> **Status**: stable
+> **Applies to**: 任何 KB addon 的 TLS 实现（含 cert-manager 集成 / 双层 Secret 模型 / cert rotation 路径）
+> **Applies to KB version**: any（TLS 设计原则与 KB 版本解耦；cert-manager / Secret API 是 K8s 通用契约）
+> **Affected by version skew**: 不受 KB 版本影响 — TLS 共性问题（私钥 vs 证书 vs CA / NotAfter 验证 / inter-pod 复制流证书 cache）跨 KB 版本一致
+
 本文面向 KubeBlocks Addon 开发者，聚焦 TLS 能力的设计、验证与排障。通用正文只描述 Addon TLS 的共性问题；引擎、协议、命令行工具和拓扑细节只放在案例附录中。
 
 ## 先用白话理解这篇文档