变更方案自动审核助手

变更方案自动审核助手 — 全员开放；变更方案docx必须提供，部署表xlsx默认必须提供（除非用户明确不要部署表）；以/home/deploy_template下模板为基准，优先按方案文件名关键词定位模板；默认返回精简Markdown并保存Word报告

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

核心目标：基于 /home/deploy_template/ 下的标准变更方案模板，对用户提供的变更方案进行模板对比审核。默认直接返回精简 Markdown 审核报告，并同时生成 Word 审核报告落盘保存。变更方案和部署表是默认审核前提；只有用户明确强调不要部署表时，才跳过部署表一致性校验。

---

触发条件

触发方式	判定标准
关键词	审核部署方案 / 帮我看下部署方案 / 帮我审核方案 / 部署方案有问题 / 帮我检查方案 / 帮我审一遍
文件上传	用户上传 .docx 变更方案 + .xlsx 部署表；可选上传纳管表 .xlsx
路径指定	用户指明文件路径，如"审核 /path/to/变更方案.docx 和 /path/to/部署表.xlsx"；若只给方案路径，需补充部署表或明确不要部署表

输入前提

变更方案(.docx) — 必须提供，这是审核的核心材料。部署表(.xlsx) — 必须提供，除非用户强调不要部署表。

纳管表是可选增强材料；缺少纳管表时不阻塞审核。

收到的文件	行为
只有变更方案 .docx，且用户未说明不要部署表	❌ 暂不审核，提示用户补充部署表或明确确认不要部署表
只有变更方案 .docx，且用户明确说不要部署表	✅ 执行模板对比审核，并注明跳过部署表一致性校验
方案+部署表	✅ 执行模板对比 + 部署表一致性校验
方案+部署表+纳管表	✅ 执行全量审核
只有 xlsx 或非方案文件	❌ 提示缺少变更方案 .docx

---

核心流程（6步）

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

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

Step 0.1 必要输入校验

必须先确认存在变更方案 .docx 和部署表 .xlsx。仅当用户明确说不要部署表时，部署表可缺省。

场景	行为
未收到 .docx 方案	拒绝，不做解析。提示用户补充变更方案
仅收到 .docx 方案，用户未说明不要部署表	暂停审核。提示用户补充部署表，或明确回复"不要部署表/跳过部署表校验"
仅收到 .docx 方案，用户明确不要部署表	继续 Step 1，只执行模板对比审核，并在报告中注明部署表校验被用户要求跳过
收到 .docx + 部署表	继续 Step 1，执行模板对比和 B 类校验
收到 .docx + 部署表 + 纳管表	继续 Step 1，执行全量审核

缺少必要材料回复模板：

text

⚠️ 审核默认需要两份必要材料：变更方案(.docx) + 部署表(.xlsx)

当前仅收到：{文件名}
缺少：{变更方案(.docx) 或 部署表(.xlsx)}

请补充后重新提交；如果本次明确不需要部署表，请回复“不要部署表”或“跳过部署表校验”。

Step 0.2 可选材料处理

部署表和纳管表按以下规则处理：

• 无部署表且用户未明确不要部署表：暂停审核，要求补充部署表或确认跳过。
• 无部署表但用户明确不要部署表：只做模板结构、关键步骤、编辑质量审核；在报告"审核范围"中注明"按用户要求跳过部署表一致性校验"。
• 无纳管表：跳过 C 类纳管表校验；在报告"审核范围"中注明未做纳管状态校验。
• 用户明确要求全量审核时，必须要求补充纳管表后再执行 C 类校验。

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 — 识别方案类型并确定模板（必须优先执行）

模板选择是本技能的核心。必须先根据用户给出的方案文件名关键词，在 /home/deploy_template/ 下定位最相近模板，再以该模板为基准审核。

Step 2.1 模板发现

运行时递归扫描 /home/deploy_template/ 下所有 .docx 模板，构建候选模板清单。不得使用硬编码模板清单代替实际目录；目录新增模板时应自动参与匹配。

Step 2.2 关键词提取优先级

按以下顺序提取关键词并打分：

1. 方案文件名：最高优先级。示例：9月10日-青海西宁三区-x86+culinux-新建存储集群扩容变更方案.docx
2. 用户文字描述/路径：如用户说"行业云存储新建"、路径中包含"行业云"。
3. 方案正文首页/标题/前两级标题：仅在文件名信息不足时使用。
4. 反问用户：私有云/行业云或场景无法唯一确定时再问。

Step 2.3 关键词路由规则

识别维度	关键词	路由规则
云类型	行业云、双引擎、骨干、一区/二区/三区/四区 等行业云资源池命名	优先匹配 /home/deploy_template/行业云/
云类型	私有云、明确私有资源池描述	优先匹配 /home/deploy_template/私有云/
产品	存储集群、ceph、块存储、存储	匹配对应云类型下 存储/
产品	对象存储、RGW、YIG、hoss	匹配 对象存储/ 或 RGW&Dims&CSG/
产品	NAS	匹配 NAS/
产品	裸金属	匹配 裸金属/
产品	GPU、L型、云桌面、增强型、计算	匹配 计算/ 下对应子目录
网络	VLAN、VXLAN、vlan、vxlan	在计算/裸金属等多模板场景中继续缩小范围
场景	新建、新建AZ、新增AZ、新集群	优先匹配模板名含 新建、新增、新AZ 的模板
场景	原集群扩容、原AZ、扩容	优先匹配模板名含 原集群扩容、原AZ、扩容 的模板
架构/系统	x86、aarch64、arm、culinux	用于校验，不作为云类型决定依据

Step 2.4 指定示例的强制匹配

当方案名类似 9月10日-青海西宁三区-x86+culinux-新建存储集群扩容变更方案.docx：

• 青海西宁三区 命中行业云资源池命名特征；
• 新建存储集群 命中行业云存储新建场景；
• 必须优先选择：

text

/home/deploy_template/行业云/存储/_存储集群新建融合模板-涵盖所有存储集群新建场景-模板.docx

并在报告中明确写出：本次审核基准模板：/home/deploy_template/行业云/存储/_存储集群新建融合模板-涵盖所有存储集群新建场景-模板.docx。

Step 2.5 模板不唯一时的反问

仅在无法判断私有云/行业云，或同一路径下多个模板得分接近且会影响审核结论时，才反问用户。反问必须说明原因，并告知用户审核是基于模板完成的。

反问示例：

text

我会根据 /home/deploy_template 下的标准模板进行对比审核，但当前文件名无法明确判断是“私有云”还是“行业云”场景。

请确认本次方案属于哪类：
1. 私有云
2. 行业云

用户确认后，继续定位模板并审核。不要在不确定云类型时擅自混用私有云和行业云模板。

Step 3 — 调用审核引擎

优先调用 scripts/generate_review_report.py，不要重复手写审核逻辑。调用时必须传入 Step 2 定位到的模板路径；如当前引擎尚未支持 template_path 参数，必须先按脚本现有能力完成审核，并在报告中单独补充模板对比结论。

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",  # 默认必须；仅用户明确不要部署表时可为 None
    manage_path="/path/to/纳管表.xlsx",  # 可选
    template_path="/home/deploy_template/行业云/存储/_存储集群新建融合模板-涵盖所有存储集群新建场景-模板.docx"
)

返回的 result 字典结构：

python

{
    "plan_name": "方案文件名（不含扩展名）",
    "template_path": "本次采用的模板路径",
    "plan": {...},        # 方案解析结果
    "deploy": {...},      # 部署表解析结果（用户明确不要部署表时可能为 None）
    "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 — 默认返回精简 Markdown，并保存 Word 报告

审核完成后，默认在聊天窗口直接返回 Markdown 审核报告。内容要精简，优先列出结论、基准模板、风险统计和必须修改项，避免长篇过程描述。

默认 Markdown 格式：

markdown

## 审核结论：{通过/条件通过/不通过}
方案：{plan_name}
基准模板：{template_path}
审核范围：{模板对比 + 部署表一致性 / 模板对比（按用户要求跳过部署表一致性校验）}{+纳管表校验}
跳过项：{无 / 按用户要求跳过部署表一致性校验 / 未提供纳管表，跳过纳管状态校验}
风险统计：🔴P0={p0}  🟡P1={p1}  🔵P2={p2}  ⚪P3={p3}

### 必须修改
- {只列 P0/P1，最多 5 条；无则写“无”}

### 建议优化
- {只列关键 P2/P3，最多 3 条；无则写“无”}

Word报告已保存：{docx_path}
问题跟踪表：{xlsx_path 或 “未生成”}

同时必须生成 Word 报告并保存到 output/，路径写入 Markdown。除非用户明确要求，不要把完整 Word 内容逐段贴到聊天中。

Step 5 — 结果留存

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

text

~/.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-10	全文搜索密码/口令关键字及疑似密码模式

---

风险等级体系（四级）

🔴 高危风险（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不一致
P0-10	明文密码泄露	方案全文出现疑似明文密码的具体凭证（如 ansible_ssh_pass="实际密码"、连接字符串含密码等），排除占位符模式（xxxxxx/替换为真实密码 等）
P0-10	明文密码泄露	方案全文出现疑似密码模式的明文凭证，包括但不限于：密码/口令关键字后跟≥8位字符串（如 ansible_ssh_pass="xxxxxx"、password: xxx、root密码 后接具体值、连接字符串中的明文密码等）；判定标准：① 方案正文中出现 ansible_ssh_pass、sshpass、password、passwd、secret 等关键字后直接跟有具体字符串值（非"xxxxxx"/"xxx"/"密码"等占位符），即触发P0；② 若关键字后跟的是占位符（如 xxxxxx、<password>、******），不触发；③ 部署表中的密码列不触发（部署表属于运维凭据清单，但方案文档中仍建议脱敏）

🟡 中危风险（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 \
    --template /home/deploy_template/行业云/存储/_存储集群新建融合模板-涵盖所有存储集群新建场景-模板.docx

# 如有纳管表，再追加 C 类纳管校验
python3 scripts/generate_review_report.py \
    --plan /path/to/变更方案.docx \
    --deploy /path/to/部署表.xlsx \
    --template /path/to/模板.docx \
    --manage /path/to/纳管表.xlsx

# 仅当用户明确不要部署表时，才允许只做模板对比审核
python3 scripts/generate_review_report.py \
    --plan /path/to/变更方案.docx \
    --template /path/to/模板.docx

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

---

边界情况

• 只有变更方案，且用户未明确不要部署表：暂停审核，提示补充部署表或确认跳过部署表校验
• 只有变更方案，且用户明确不要部署表：只审核模板结构和关键步骤，报告中注明"按用户要求跳过部署表一致性校验"
• 只有部署表或纳管表：拒绝解析，提示缺少变更方案 .docx
• 无法判断私有云/行业云：反问用户，说明审核将基于 /home/deploy_template/ 模板完成
• 模板候选不唯一：列出最可能的 2-3 个模板让用户选择，不要混用模板
• 无纳管表：跳过 C 类校验，并在审核范围中注明
• 无部署表：仅在用户明确不要部署表时才跳过 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