变更方案自动审核助手

SKILL.md

---
name: deploy-plan-review
description: 变更方案自动审核助手 — 必要条件：变更方案(docx)+部署表(xlsx)；可选：纳管表(xlsx)。三文档交叉核验，按P0-P3风险分级输出Word审核报告
version: 3.1.0
author: Hermes
created: 2026-04-30
updated: 2026-05-09
---

# 变更方案自动审核助手 v3.1

必要条件：**变更方案 .docx + 部署表 .xlsx**。可选：**纳管表 .xlsx**。自动交叉核验，找出不一致信息和明显错误，按 P0-P3 风险分级生成 Word 审核报告并直接发送到聊天窗口。过程文件自动归档。

---

## 触发条件

| 触发方式 | 判定标准 |
|----------|---------|
| **关键词** | 审核部署方案 / 帮我看下部署方案 / 帮我审核方案 / 部署方案有问题 / 帮我检查方案 / 帮我审一遍 |
| **文件上传** | 用户上传 .docx 方案 + .xlsx 部署表（可选 + .xlsx 纳管表） |
| **路径指定** | 用户指明文件路径，如"审核 /path/to/方案.docx 和 /path/to/部署表.xlsx" |

### 必要条件（硬性约束）

> ⚠️ **部署方案 .docx + 部署表 .xlsx 缺一不可。** 仅收到单个文件时不做任何解读，直接回复提示缺少文件。

| 收到的文件 | 行为 |
|-----------|------|
| 只有 1 个文件 | ❌ 拒绝，提示用户补齐缺失的必要文件 |
| 方案+部署表（无纳管表） | ⚠️ 询问用户是否有纳管表（见 Step 0.2） |
| 方案+部署表+纳管表 | ✅ 直接进入全量审核 |

---

## 核心流程（6步）

### Step 0 — 输入校验（必须执行）

在处理任何文档内容之前，必须完成输入检查。

#### Step 0.1 必要条件校验

> **部署方案 .docx + 部署表 .xlsx 二者缺一不可。**

| 场景 | 行为 |
|------|------|
| 只收到 1 个文件 | **拒绝，不做任何解析**。回复示例见下方 |
| 只收到纳管表 | 同上，告知纳管表是辅助材料，需配合方案+部署表使用 |
| 方案+部署表齐全 | 继续 Step 0.2 |
| 三件齐备 | 跳过 Step 0.2，直接进入 Step 1 |

**单文件拒绝回复模板：**
```
⚠️ 审核需要至少两份必要文件：变更方案(.docx) + 部署表(.xlsx)

当前仅收到：{文件名}
缺少：{缺失项}

请补充后重新提交。
```

#### Step 0.2 纳管表可选检查

当方案+部署表齐全但**无纳管表**时，**必须使用 `clarify` 工具询问用户**：

> "收到变更方案和部署表，但未提供纳管表。纳管表用于核验服务器纳管状态（C类检查）。请问："
> 
> 选项：
> - **A. 稍后提供** — 等你发送纳管表后再继续
> - **B. 没有纳管表，需要找项目经理要** — 回复获取建议
> - **C. 跳过纳管表校验** — 仅执行 A/B/D 类审核（不检查纳管状态）

用户选 C 后，将 `manage_path` 传 `None`，仅执行 A/B/D 类审核。
用户选 A/B 后，等待用户补充或回复。

### Step 1 — 保存原始输入

**任何输入在处理前必须先存档**，防止后续覆盖：

```python
from pathlib import Path
import shutil
from datetime import datetime

SKILL_DIR = Path.home() / '.hermes/skills/openclaw-imports/deploy-plan-review'
RAW_DIR = SKILL_DIR / 'data' / 'raw'
RAW_DIR.mkdir(parents=True, exist_ok=True)

ts = datetime.now().strftime('%Y-%m-%d_%H%M%S')
for label, src in [('plan', plan_path), ('deploy', deploy_path), ('manage', manage_path)]:
    if src and Path(src).exists():
        shutil.copy2(src, RAW_DIR / f'{ts}_{label}_{Path(src).name}')
```

### Step 2 — 识别方案类型并确定模板

根据文件名和内容判断方案类型，确定对应模板：

| 方案类型 | 匹配关键词 | 对应模板目录 |
|----------|-----------|-------------|
| 私有云-计算扩容(VLAN) | 私有云 + 计算 + VLAN | /home/deploy_template/私有云/计算/普通计算/*VLAN* |
| 私有云-计算扩容(VXLAN) | 私有云 + 计算 + VXLAN | /home/deploy_template/私有云/计算/普通计算/*VXLAN* |
| 私有云-存储扩容 | 私有云 + 存储 | /home/deploy_template/私有云/存储/*存储扩容* |
| 私有云-裸金属扩容 | 裸金属 | /home/deploy_template/私有云/裸金属/* |
| 行业云-计算扩容(VLAN) | 行业云 + 计算 + VLAN | /home/deploy_template/行业云/计算/普通计算/*vlan* |
| 行业云-计算扩容(VXLAN) | 行业云 + 计算 + VXLAN | /home/deploy_template/行业云/计算/普通计算/*vxlan* |
| 行业云-存储扩容 | 行业云 + 存储 | /home/deploy_template/行业云/存储/*原集群扩容* |
| ... | （完整24种见原版） | |

匹配优先级：文件名 → 文件路径 → 正文第一段 → 让用户确认

### Step 3 — 调用审核引擎

**直接调用 `scripts/generate_review_report.py`**，不要再手动写 Python：

```python
import sys
sys.path.insert(0, str(Path.home() / '.hermes/skills/openclaw-imports/deploy-plan-review'))

from scripts.generate_review_report import run_audit

result = run_audit(
    plan_path="/path/to/变更方案.docx",
    deploy_path="/path/to/部署表.xlsx",
    manage_path="/path/to/纳管表.xlsx"  # 可选
)
```

返回的 `result` 字典结构：
```python
{
    "plan_name": "方案文件名（不含扩展名）",
    "plan": {...},        # 方案解析结果
    "deploy": {...},      # 部署表解析结果
    "manage": {...},      # 纳管表解析结果（可能为 None）
    "findings": [...],    # 全部审核发现列表
    "docx_path": "output/审核报告_xxx.docx",
    "xlsx_path": "output/问题跟踪_xxx.xlsx",
    "summary": {
        "p0": N, "p1": N, "p2": N, "p3": N,
        "total": N,
        "conclusion": "通过/条件通过/不通过",
        "timestamp": "2026-05-09_143025",
    },
    "raw_archived": "data/raw/",
}
```

### Step 4 — 发送报告到聊天窗口

审核完成后，**必须将 Word 报告发送到当前聊天窗口**：

```
报告已生成，请查收：
MEDIA:<docx_path>
```

同时发送一份文字摘要：
```
📋 审核完成 — {plan_name}

风险统计：🔴P0={p0}  🟡P1={p1}  🔵P2={p2}  ⚪P3={p3}
审核结论：{conclusion}

关键发现：
- {列举前3条最高风险问题}

详细报告请下载上方文件。
问题跟踪表：{xlsx_path}
```

### Step 5 — 结果留存

所有过程文件统一在 skill 目录下：

```
~/.hermes/skills/openclaw-imports/deploy-plan-review/
├── SKILL.md
├── scripts/
│   └── generate_review_report.py   # 审核引擎
├── output/                          # 审核报告输出
│   ├── 审核报告_方案名_2026-05-09_143025.docx
│   └── 问题跟踪_方案名_2026-05-09_143025.xlsx
├── data/
│   ├── raw/                         # 原始输入存档
│   │   ├── 2026-05-09_143025_plan_变更方案.docx
│   │   ├── 2026-05-09_143025_deploy_部署表.xlsx
│   │   └── 2026-05-09_143025_manage_纳管表.xlsx
│   └── 问题跟踪表.xlsx              # 全量历史问题库
```

---

## 审核基准

**核心原则：所有审核以 `/home/deploy_template/` 下的方案模板为基准，不主观判断。**

审核分四大类：

### A类 — 结构合规性（以模板为准）

| 检查项 | 风险ID | 审核方法 |
|--------|--------|---------|
| 章节完整性 | P1-07 | 匹配变更需求/变更安排/变更步骤/割接回退四章 |
| 表格完整性 | P1-06 | 版本修订记录表是否更新（非空白/非占位） |
| 人员表完整 | P1-03 | 实施/复核/审批/客户四角色是否齐全 |
| 占位符替换 | P2-01 | 搜索 `{XXX}` `[待补充]` `[填写]` `XXX资源池` |

### B类 — 数据一致性（方案 vs 部署表）

| 检查项 | 风险ID | 审核方法 |
|--------|--------|---------|
| 节点数量 | P0-02 | 方案标题"新建N台" vs 部署表行数 |
| CPU/OS架构 | P0-03 | 方案中 x86/aarch64 vs 部署表CPU列 |
| yum源架构 | P0-04 | repo URL架构 vs 部署表CPU架构 |
| mon IP | P0-05 | mon节点IP是否在存储IP段内 |
| AZ为空 | P0-06 | 方案说"新建AZ"但部署表az=NULL |
| 标题正文矛盾 | P1-01 | 标题数量 vs 正文数量 |
| 节点IP不一致 | P1-02 | 方案IP vs 部署表IP交叉比对 |

### C类 — 纳管表交叉核验（新增）

| 检查项 | 风险ID | 审核方法 |
|--------|--------|---------|
| 服务器缺失 | P0-08 | 部署表中IP是否全部在纳管表中 |
| IP不一致 | P0-09 | 同IP下部署表与纳管表的hostname是否一致 |
| 状态异常 | P3-01 | 纳管表中是否存在非"已纳管"状态 |
| AZ不一致 | P3-02 | 同IP下部署表AZ vs 纳管表AZ |

### D类 — 编辑质量

| 检查项 | 风险ID | 审核方法 |
|--------|--------|---------|
| 错别字 | P2-02 | 扩融→扩容、资原池→资源池 等8组检测 |
| 编号错误 | P2-04 | 章节编号是否跳跃 |
| 占位符 | P2-01 | 全文正则搜索 |
| 命名规范 | P2-06 | 文件名格式检查 |

---

## 风险等级体系（四级）

### 🔴 高危风险（P0 — 必须改，不改将导致部署失败或业务中断）

| ID | 风险项 | 判定标准 |
|----|--------|---------|
| P0-01 | IP地址冲突 | 多个节点使用同一IP，或与生产环境IP段重叠 |
| P0-02 | IP不连续/数量不符 | IP区间数量 ≠ 实际节点数 |
| P0-03 | CPU/OS架构矛盾 | 方案x86但部署表aarch64（或反之） |
| P0-04 | yum源架构不匹配 | repo URL架构(aarch64/x86_64)与节点不一致 |
| P0-05 | monitors数量/IP错误 | mon IP不在存储IP段，或数量<3 |
| P0-06 | AZ字段为NULL但方案说新建 | 新建AZ场景下部署表az列为空 |
| P0-07 | 关键步骤缺失 | 缺少模板中标记为「必须/必做」的操作步骤 |
| P0-08 | 纳管表服务器缺失 | 部署表中的服务器在纳管表中不存在 |
| P0-09 | 纳管IP不一致 | 部署表管理IP与纳管表管理IP不一致 |

### 🟡 中危风险（P1 — 建议改，不影响部署但影响正确性）

| ID | 风险项 | 判定标准 |
|----|--------|---------|
| P1-01 | 标题与正文矛盾 | 标题数量与正文数量不一致 |
| P1-02 | 节点信息不一致 | 方案节点列表与表格/部署表不一致 |
| P1-03 | 变更人员表不完整 | 实施/复核/审批/客户角色缺失 |
| P1-04 | 变更时间不合理 | 时间已过或窗口时长不合理 |
| P1-05 | 配置参数错误 | expand/config.json与部署表不一致 |
| P1-06 | 版本修订记录未更新 | 版本修订表为空白或占位符 |
| P1-07 | 章节缺失 | 缺少非关键章节（如割接回退） |
| P1-08 | 网络配置矛盾 | VLAN/VXLAN模式不一致 |

### 🔵 低危风险（P2 — 按需修改，规范性/编辑类问题）

| ID | 风险项 | 判定标准 |
|----|--------|---------|
| P2-01 | 占位符未替换 | 仍含 {XXX}、[待补充] 等模板占位符 |
| P2-02 | 文字错别字 | 「扩融」「资原池」「部暑」等 |
| P2-03 | 格式不一致 | 标题字号不统一 |
| P2-04 | 编号错误 | 章节编号跳跃 |
| P2-05 | 截图/图片缺失 | 「截图示例」未替换 |
| P2-06 | 文件命名不规范 | 缺少日期或资源池名 |
| P2-07 | 操作记录表格式错误 | 列名或格式与模板不一致 |

### ⚪ 提示信息（P3 — 仅供参考）

| ID | 风险项 | 判定标准 |
|----|--------|---------|
| P3-01 | 纳管表状态异常 | 存在非「已纳管」状态的服务器 |
| P3-02 | 纳管表AZ不一致 | 纳管表AZ与部署表AZ不匹配 |

---

## 审核结论判定

| 结论 | 判定规则 |
|------|---------|
| ✅ **通过** | 无 P0 项，且 P1+P2 ≤ 3 项 |
| ⚠️ **条件通过** | 无 P0 项，P1 项 ≤ 5 项，修改意见已明确标注 |
| ❌ **不通过** | 存在 P0 项，或 P1 项 > 5 项 |

---

## CLI 用法（可选）

审核引擎支持命令行独立运行：

```bash
cd ~/.hermes/skills/openclaw-imports/deploy-plan-review

python3 scripts/generate_review_report.py \
    --plan /path/to/变更方案.docx \
    --deploy /path/to/部署表.xlsx \
    --manage /path/to/纳管表.xlsx   # 可选

# JSON 输出（供程序调用）
python3 scripts/generate_review_report.py \
    --plan ... --deploy ... --manage ... \
    --json
```

---

## 边界情况

- **文件不全**（仅1个或仅有纳管表）：拒绝解析，直接提示缺失文件（Step 0.1）
- **无纳管表**：触发 `clarify` 询问，用户可选跳过（C类检查跳过，A/B/D类正常执行）
- **用户选A/B**：等待用户补充或回复后再继续，不尝试跳过
- **部署表sheet名称不标准**：自动搜索含"服务器"/"server"/"02"的sheet
- **纳管表列名不标准**：自动检测"管理IP"/"Management IP"/"主机名"/"AZ"/"状态"/"管理平台"等常见列名
- **方案无章节标题**：P1-07 判定为"缺少全部四章"
- **方案含多个方案**：仅审核主要方案，其他部分忽略

---

## 参考

- 模板目录：`/home/deploy_template/`
- 模板结构分析：`/root/模板结构分析报告.md`
- 配套技能：`deploy-fault-analyzer` — 部署故障分析
- 设计参考：`deploy-fault-analyzer` v2.0 的 Step 0 存档、多源输入、统一目录结构等模式
- **编写者注意**：Python 中文 f-string 引号陷阱见 `references/pitfalls.md`