# AI 读图意见不能直接交付：用 Python 给舞台工艺审图清单建三道机器闸门（六列结构 · 复核列留空 · R17 禁词拦截）

## 一、先算一笔账：为什么"结构对"这件事必须交给机器判

AI 读图正在把舞台工艺审图意见的生产门槛拉得很低。给一张舞台机械布置图 or 电气点位图，几分钟就能吐出几十条"疑似问题 + 整改建议"。但交付链路真正的成本，从来不在生成那几分钟，而在生成之后：

- **清单列数不对**——六列模板被压成五列，"复核"列直接消失。审图意见是给业主方签字用的，缺复核列意味着整份清单要逐条人工回填，再重新生成 docx 与 md。
- **复核列被"顺手填上"**——AI 极爱在最后一列写上"已核对""经复核"，这句话没有任何人签过字，等于伪造签字。格式铁律 R4 要求这一列出稿时**必须留空**，签字是人的动作，不是机器的动作。
- **过程词泄漏进结论**——"文字层未见异常""坐实为强电桥架冲突""疑为检修门净宽不足"这类读图过程语，一旦混进正式意见，业主方会追问"你凭什么坐实"。R17 禁词闸门就是拦这个。

这三类问题的共同特征是：**它们不影响文档"看起来完整"，但会让文档在流程上直接失效**。人工检查时肉眼极易放过——列数少一列在长表格里几乎察觉不到，复核列有内容也只是"看起来更充实"。

所以本文不谈怎么用 AI 读图，只谈更冷的一层：**如何用 python-docx 把格式铁律编译成机器闸门，让"看起来对"变成"退出码为 0"。**

下面的三道闸门，全部以 fail-fast 方式串成一个主入口，唯一判据是进程退出码。

## 二、把格式铁律翻译成可执行断言原始约束是自然语言，人读得懂、机器读不懂：

- R4：审查意见清单固定六列，末列"复核"出稿留空，由主理人签字。
- R17：正文与表格中不得出现读图过程词与自证语。

要变成代码，第一步是**形式化**：把自然语言拆成"作用对象 + 判据 + 违例后果"三段。

**R4 → 断言 A：**对文档中每张表，网格列数必须等于 6。不等于即违例。

**R4 → 断言 B：**对已确认 6 列的表，索引 5 的单元格文本去空白后必须为空串。非空即违例。

**R17 → 断言 C：**对文档**全部文本域**做禁词表子串匹配，命中任一即违例。

三条断言的"作用对象"分别是：`w:tblGrid`、末列 `w:tc`、全文 `w:t` 节点集合。这里有一个关键判断——**断言 A 必须先于断言 B 执行**，这是后面要展开的依赖顺序问题。

再明确一个工程原则：**闸门只允许读文档、只允许报错，不允许修文档。**自动补列、自动清空复核列看起来更"贴心"，但会让铁律从"约束"退化成"建议"，一旦上游生成逻辑退化，闸门会静默地把缺列的文档"修好"并放行，缺陷被永久掩盖。闸门必须 fail-fast、必须让人看见退出码。

## 三、第一层断言：列数必须从 gridCol 读，不能从 row.cells 推

这一层看起来是三行代码的事，但它是整个闸门最容易写错、也最难排查的一层。

### 3.1 OOXML 里的"列"到底存在哪

一个 Word 表格在 XML 里是两层结构：

- `<w:tblGrid>` 里的一串 `<w:gridCol w:w="1701"/>` —— **网格列**，定义表格有几列、每列多宽。**这一层才代表"表格设计上的列数"。**
- `<w:tr>` 里的一串 `<w:tc>` —— **单元格**。当横向合并发生时，一个 `<w:tc>` 可以带 `w:gridSpan="2"`，也就是"我一个人占两列"。

于是出现了一个致命的不等式：

**合并单元格存在时，该行的 `w:tc` 数量 < 网格列数量。**

python-docx 把这两层暴露成了两个不同的 API：

- `table.columns` —— 来自 `w:tblGrid`，长度恒等于网格列数，与合并不关。
- `table.rows[i].cells` —— 来自该行的 `w:tc` 序列。它的 `__len__` 反映的是**单元格个数**（合并后偏少），而 `__getitem__` 会按 `gridSpan` 做网格位置映射，导致**同一个 `_Cell` 对象被重复返回**。

后果非常具体：如果你用 `len(table.rows[0].cells) == 6` 做判据，那么一个"首行做了横向合并的 6 列表"会给你返回 5，你会误判它缺列；反过来，如果你用 `table.cell(0, 5)` 去探测末列，合并偏移会让它**静默返回另一个位置的单元格内容**——不抛异常，只是答案错了。这比崩掉更危险。

**结论：列数判据唯一正确来源是 `len(table.columns)`。**

### 3.2 还要注意一个坑：`doc.tables` 不是全部表格

`doc.tables` 只返回 body 的**直接子级**表格。如果清单里嵌了一个"分项说明"表格（表格套表格），内层表格会整体漏检——闸门静默放过，属于最坏的失败模式（假阴性）。

正确做法是直接遍历 XML，把 `w:tbl` 全量捞出来：

```python
from docx import Document
from docx.oxml.ns import qn

EXPECTED_COLUMNS = 6
REVIEW_COLUMN_INDEX = 5


def all_tables(doc):
    """全量表格：包含嵌套表格，不依赖 doc.tables 的直接子级语义。"""
    body = doc.element.body
    return list(body.iter(qn('w:tbl')))


def check_column_count(doc):
    """断言 A：每张表的网格列数必须为 6。返回违例明细列表。"""
    violations = []
    for idx, tbl in enumerate(all_tables(doc)):
        cols = len(tbl.columns)  # ← 唯一正确的列数来源（w:tblGrid/gridCol）
        if cols != EXPECTED_COLUMNS:
            violations.append({
                "table_index": idx,
                "actual_columns": cols,
                "row0_tc_count": len(tbl.rows[0].cells) if tbl.rows else 0,
            })
    return violations


def main(path):
    doc = Document(path)
    bad = check_column_count(doc)
    for item in bad:
        print(
            f"[列数违例] 表#{item['table_index']} 网格列={item['actual_columns']}"
            f"（期望 {EXPECTED_COLUMNS}）；首行单元格数={item['row0_tc_count']}"
        )
    return 1 if bad else 0


if __name__ == "__main__":
    import sys
    sys.exit(main(sys.argv[1]))
```

`row0_tc_count` 那一行是刻意打印的：当它小于网格列数时，说明这张表**存在横向合并**，可以立刻提醒使用者"这张表即使列数对，末列定位仍需人工确认"。

## 四、第二层断言：复核列的"空"怎么判，以及为什么必须排在列数闸门之后

### 4.1 "空"是一个精确判定，不是视觉判定

复核列留空的判据是 `cell.text.strip() == ""`。这里不能偷懒用"看起来是空白"——docx 里空格、全角空格、换行符、不可见控制字符都是 `.strip()` 覆盖不到的边缘情形，而它们恰好是"AI 手滑写了东西"的高发区（比如填了一个零宽空格或一个 `—`）。

加固版判据（按需使用）：

```python
ZERO_WIDTH = dict.fromkeys(map(ord, "\u200b\u200c\u200d\ufeff"), None)


def is_visually_empty(text):
    """把零宽字符与全角空格一并归一后，再判空。"""
    return text.translate(ZERO_WIDTH).replace("\u3000", "").strip() == ""


def check_review_column_blank(doc):
    """断言 B：已确认 6 列的表，末列每格必须为空。"""
    violations = []
    for idx, tbl in enumerate(all_tables(doc)):
        if len(tbl.columns) != EXPECTED_COLUMNS:
            continue  # 依赖顺序：不处理列数不合规的表
        for r, row in enumerate(tbl.rows):
            cell = row.cells[REVIEW_COLUMN_INDEX]
            raw = cell.text
            if not is_visually_empty(raw):
                violations.append({
                    "table_index": idx,
                    "row": r,
                    "content": raw.strip()[:40],
                })
    return violations
```

注意那个 `continue`——它就是**依赖顺序**的物理实现。

### 4.2 为什么顺序不能反

假设先跑复核列校验，而这张表只有 5 列：

```python
row.cells[5]   # IndexError: list index out of range
```

你会拿到一个 `IndexError` 栈回溯，而不是一条可读的违例信息。批量场景下更糟：脚本在第一份文档就崩掉，剩下的文档根本没被检查，你会误以为"跑通了"。

更隐蔽的版本是有人为了"保险"把判据写成 `if len(row.cells) > REVIEW_COLUMN_INDEX:`——看起来做了防护，实际上把"缺复核列"这个最严重的缺陷降级成了静默跳过。**缺列必须由第一关拦下，不允许由第二关沉默。**

所以顺序被写死为：

- 第 1 关：列数（退出码 1）
- 第 2 关：复核列（退出码 2）
- 第 3 关：禁词（退出码 3）

任何一关失败立即返回，后续不执行。

## 五、第三层断言：R17 禁词必须扫全文文本域，只扫段落等于没扫

R17 的禁词分两类，性质不同但同等致命。

**第一类：读图过程词。**文字层、文本层、坐实、疑为、疑是、自检表。
这些词的共同问题是**它们描述的是"我怎么看到的"，不是"图纸上是什么"**。正式意见里出现"文字层未见异常"，等于告诉业主方"我只是读了图上的字"；出现"坐实"，则是把不确定的推断写成了确定结论。

**第二类：自证语。**经复核、已逐条、逐页核对、我方。
这类词是 AI 生成文本的高频残留，它们**伪装成合规声明**，实际是未经授权的签字与背书。

### 5.1 最容易写废的实现：只扫 paragraph

绝大多数人一上手会这么写：

```python
for para in doc.paragraphs:
    if "坐实" in para.text: ...
```

这是错的。`doc.paragraphs` **只包含 body 下的顶层段落，不含表格单元格内的段落**。而审图意见的核心内容——问题描述、整改建议、等级判定——**全都在表格单元格里**。只扫段落，等于闸门对着空气生效，真实命中率是 0。

正确做法是直接在 XML 层的 `w:p` 上迭代。表格单元格里的段落本身就是 `w:tc/w:p`，会被一并捞到：

```python
READ_PROCESS_BANNED = ("文字层", "文本层", "坐实", "疑为", "疑是", "自检表")
SELF_PROOF_BANNED = ("经复核", "已逐条", "逐页核对", "我方")
BANNED_TERMS = READ_PROCESS_BANNED + SELF_PROOF_BANNED


def iter_body_text_lines(doc):
    """遍历 body 内全部段落的可见文本：顶层段落 + 表格单元格段落 + 嵌套表格。"""
    for p_el in doc.element.body.iter(qn("w:p")):
        yield "".join(node.text or "" for node in p_el.iter(qn("w:t")))


def check_banned_terms(doc):
    """断言 C：全文文本域禁词匹配。返回 (行号, 禁词, 摘要) 列表。"""
    hits = []
    for lineno, line in enumerate(iter_body_text_lines(doc), start=1):
        for term in BANNED_TERMS:
            if term in line:
                hits.append({
                    "line": lineno,
                    "term": term,
                    "category": "读图过程词" if term in READ_PROCESS_BANNED else "自证语",
                    "excerpt": line.strip()[:50],
                })
    return hits
```

两个实现细节值得强调：

- **逐段落而非整篇拼接。** 逐段落命中能给出行号级定位，使用者可以直接跳到出错句子；整篇 concat 虽然命中更彻底，但报出来是一坨长文本，定位价值归零。
- **穿透 run 边界。** Word 会把一句话拆进多个 `<w:r>`（不同字体、不同语言、拼写检查标记都会触发拆分）。如果直接对 `w:r` 逐个匹配，"坐实"两字被拆成两个 run 就永远抓不到。按 `w:p` 聚合 `w:t` 再匹配，才能保证不漏。

### 5.2 一个必须承认的边界：图片里的字扫不到

文本域匹配对**表格内嵌图片、扫描件截图、CAD 导出的图框说明**完全无效。AI 读图流程里，"把图纸截图贴进表格当证据"是常见做法，这意味着 R17 在这些区域是失效的。诚实处理方式只有两条：要么在流程上禁止贴图，要么把这一步单独交给 OCR 校验。**不要假装闸门覆盖了它没覆盖的域**——闸门一旦给出虚假安全感，比没有闸门更危险。

## 六、三关串联：以退出码为唯一契约的主入口

现在把三道闸门编排放进 `audit_delivery_gate.py`。核心约束只有一句：**"通过"的定义是进程退出码 0，不接受任何形式的口头声称。**

```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""audit_delivery_gate.py —— 舞台工艺审图意见清单交付闸门

退出码契约（唯一判据，禁止口头声称通过）：
    0  = 三关全过
    1  = 列数违例（R4：非 6 列）
    2  = 复核列非空（R4：末列应留空待签字）
    3  = R17 禁词命中
    64 = 用法错误（命令行参数）
"""

import argparse
import sys

from docx import Document
from docx.oxml.ns import qn

EXPECTED_COLUMNS = 6
REVIEW_COLUMN_INDEX = 5

READ_PROCESS_BANNED = ("文字层", "文本层", "坐实", "疑为", "疑是", "自检表")
SELF_PROOF_BANNED = ("经复核", "已逐条", "逐页核对", "我方")
BANNED_TERMS = READ_PROCESS_BANNED + SELF_PROOF_BANNED

ZERO_WIDTH = dict.fromkeys(map(ord, "\u200b\u200c\u200d\ufeff"), None)

EXIT_OK = 0
EXIT_COLUMN_COUNT = 1
EXIT_REVIEW_NOT_BLANK = 2
EXIT_BANNED_TERM = 3
EXIT_USAGE = 64


def all_tables(doc):
    """全量表格（含嵌套）。不用 doc.tables：它只给 body 直接子级。"""
    return list(doc.element.body.iter(qn("w:tbl")))


def iter_body_text_lines(doc):
    """body 内全部段落文本：顶层段落 + 所有表格单元格段落。"""
    for p_el in doc.element.body.iter(qn("w:p")):
        yield "".join(node.text or "" for node in p_el.iter(qn("w:t")))


def is_visually_empty(text):
    return text.translate(ZERO_WIDTH).replace("\u3000", "").strip() == ""


def gate_column_count(doc):
    violations = []
    for idx, tbl in enumerate(all_tables(doc)):
        cols = len(tbl.columns)          # 必须来自 w:tblGrid/gridCol
        if cols != EXPECTED_COLUMNS:
            tc_cnt = len(tbl.rows[0].cells) if tbl.rows else 0
            violations.append(
                f"  表#{idx}：网格列数={cols}（期望 {EXPECTED_COLUMNS}）；"
                f"首行单元格数={tc_cnt}"
                + ("  ← 存在横向合并" if tc_cnt < cols else "")
            )
    return violations


def gate_review_column(doc):
    violations = []
    for idx, tbl in enumerate(all_tables(doc)):
        if len(tbl.columns) != EXPECTED_COLUMNS:
            continue                      # 依赖顺序：列数由第 1 关负责
        for r, row in enumerate(tbl.rows):
            cell = row.cells[REVIEW_COLUMN_INDEX]
            if not is_visually_empty(cell.text):
                violations.append(
                    f"  表#{idx} 第{r}行 复核列非空：{cell.text.strip()[:40]}"
                )
    return violations


def gate_banned_terms(doc):
    violations = []
    for lineno, line in enumerate(iter_body_text_lines(doc), start=1):
        for term in BANNED_TERMS:
            if term in line:
                cat = "读图过程词" if term in READ_PROCESS_BANNED else "自证语"
                violations.append(
                    f"  第{lineno}段 命中[{cat}]「{term}」：{line.strip()[:50]}"
                )
    return violations


def gate_file(path):
    doc = Document(path)

    v1 = gate_column_count(doc)
    if v1:
        print(f"[FAIL-1 列数违例] {path}")
        print("\n".join(v1))
        return EXIT_COLUMN_COUNT

    v2 = gate_review_column(doc)
    if v2:
        print(f"[FAIL-2 复核列非空] {path}")
        print("\n".join(v2))
        return EXIT_REVIEW_NOT_BLANK

    v3 = gate_banned_terms(doc)
    if v3:
        print(f"[FAIL-3 R17 禁词] {path}")
        print("\n".join(v3))
        return EXIT_BANNED_TERM

    print(f"[OK] {path}")
    return EXIT_OK


def main(argv):
    ap = argparse.ArgumentParser(description="审图意见清单交付闸门")
    ap.add_argument("files", nargs="+", help="待检 docx 路径")
    args = ap.parse_args(argv)

    for path in args.files:
        code = gate_file(path)
        if code != EXIT_OK:
            return code          # fail-fast：首份失败即中止整批
    return EXIT_OK


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
```

生成侧与之配对。`md_to_system_docx.py` 里的六列模板落表逻辑必须**显式声明 6 列**，并且**末列留空**，不依赖任何默认值：

```python
COLUMN_HEADER = ("编号", "位置", "问题", "建议", "等级", "复核")


def build_review_table(doc, rows):
    """rows: 每行为 5 元组（编号/位置/问题/建议/等级），复核列强制留空。"""
    table = doc.add_table(rows=1, cols=len(COLUMN_HEADER))  # 固定 6 列
    table.style = "Table Grid"

    for i, name in enumerate(COLUMN_HEADER):
        table.rows[0].cells[i].text = name

    for item in rows:
        cells = table.add_row().cells
        for i in range(len(COLUMN_HEADER) - 1):      # 只填前 5 列
            cells[i].text = item[i]
        cells[REVIEW_COLUMN_INDEX].text = ""           # R4：复核列留空待签
    return table
```

批量校验时，把退出码判断交给 shell：

```bash
python scripts/audit_delivery_gate.py output/*.docx
rc=$?
if [ "$rc" -ne 0 ]; then
  echo "交付闸门拦截，退出码=$rc，禁止进入发布环节"
  exit "$rc"
fi
echo "闸门通过：退出码 0"
```

注意 `rc=$?` 必须紧跟命令，中间不能插入任何其他语句，否则拿到的不是闸门的退出码。

## 七、真实代价：8 份清单缺复核列的那一批

某批8 份舞台工艺审查意见清单，AI 读图生成后直接进入交付环节。拆开看，问题出在同一个地方：**生成侧的 md 模板只写了 5 列**（编号 / 位置 / 问题 / 建议 / 等级），"复核"列在手工整理 md 时被省略了。

后果是连锁的：

1. 8 份 docx 全部缺第 6 列；
2. 按格式铁律 R4，复核列必须留空供主理人签字，缺列意味着流程上无法签字，文档不可交付；
3. 只能逐份回填复核列（8份 × 平均 20 余行），再分别重生成 docx 与 md 两套产物；
4. 重生成后又需人工复核两套产物是否一致。

**如果当时挂了上面这套闸门**：第一关 `check_column_count` 直接返回 8 条违例，主入口在第一份就 `return1`，整批在生成后一分钟内被拦下，返工成本归零。更关键的是，拦截点从"交付前的体力劳动"前移到了"生成后的机器判定"。

这个案例也说明了一件事：**闸门的价值不在于抓到单个错别字，而在于把"结构性缺陷"的发现成本从人工通宵降到一次批处理。**

## 八、落地时最容易踩的六个坑

**1. 用 row.cells 推列数。**
第一节讲透了。这是本类闸门最高频的错误来源，且失败模式最恶劣——合并单元格下不报错，只是安静地给出错误答案。

**2. 用 doc.paragraphs 扫禁词。**
禁词命中率归零。必须下沉到 `w:p` 迭代。

**3. 按 `w:r` 逐个匹配禁词。**
run 边界会把词切碎，漏检。必须按段落聚合。

**4. 用 `if len(row.cells) > 5` 做防护。**
把最严重的"缺列"降级为静默跳过，让第 1 关形同虚设。

**5. 闸门自动修文档。**
自动补列、自动清空复核列，会把铁律从约束退化成建议，且永久掩盖上游生成逻辑的退化。闸门只报错。

**6. 用"我检查过了，没问题"替代退出码。**
只要判据是人的陈述，闸门就退化成装饰。脚本必须落进自动化流程，让 `非0` 阻断后续步骤，这一句是整套方案里唯一不能妥协的。


AI 读图正在把舞台工艺审图意见的生产门槛拉得很低。给一张舞台机械布置图 or 电气点位图，几分钟就能吐出几十条"疑似问题 + 整改建议"。但交付链路真正的成本，从来不在生成那几分钟，而在生成之后：

AI 读图意见不能直接交付：用 Python 给舞台工艺审图清单建三道机器闸门（六列结构 · 复核列留空 · R17 禁词拦截）

AI 生成的审图意见看着完整，流程上却可能直接失效：六列被压成五列、复核列被顺手填上、读图过程词漏进结论。本文用 python-docx 把格式铁律编译成三道机器闸门——列数从 gridCol 读、复核列强制留空、R17 禁词扫全文文本域，以退出码为唯一判据，附完整可运行代码与六个落地坑。

人工智能

编程语言

开发工具

用Python构建三道机器闸门，将舞台工艺审图清单的格式铁律编译为可执行断言，确保列数、复核列留空及禁词拦截均通过退出码判定，实现从"看起来对"到"退出码为0"的自动化交付校验，有效规避结构性缺陷与返工风险。

代码解释

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AI 读图意见不能直接交付：用 Python 给舞台工艺审图清单建三道机器闸门（六列结构 · 复核列留空 · R17 禁词拦截）-腾讯云开发者社区-腾讯云

AI 读图意见不能直接交付：用 Python 给舞台工艺审图清单建三道机器闸门（六列结构 · 复核列留空 · R17 禁词拦截）

AI 读图意见不能直接交付：用 Python 给舞台工艺审图清单建三道机器闸门（六列结构 · 复核列留空 · R17 禁词拦截）

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐