gongwen-skill 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@
   Licensed under the MIT License. See the LICENSE file for details.
 -->
 
+## v2.4.0 (2026-09-01)
+
+### Added
+- **表格样式检测与修复全链路**：新增 8 条表格样式检查规则（CHK-C051~C058：表头字体/字号/加粗/对齐/底色、表体字体/字号、单元格左右边距）与 set_table_style 修复动作（FIX-C055），对齐 rules/official/_common.yaml table 配置块——此前该配置为死配置，无 CHK 规则也从不被检查
+- **模型新增表格样式字段**：TableCell.fill（表头底色 w:shd）、Table.cell_margin（单元格边距 w:tblCellMar），parser 解析、generator 原位更新/新建两路径写出
+- **md2docx 表格样式应用**：渲染时读取 table 配置块，表头写入 D9E2F3 底色 + 单元格边距 80twips + 数字列右对齐（与 optimize 智能对齐一致）
+
+### Fixed
+- **表格单元格解析丢失修复**：_parse_table 原用 id(cell._element) 去重，lxml 代理对象 id 被 GC 复用导致非合并表格也误丢约 58% 单元格（实测 88 个误丢 51 个），改用 lxml 元素对象做 key——修复后表格内容/样式修复可完整覆盖全部单元格
+- **署名与开头样式修复**：主送机关延迟插入（标题后、防误判标题）、recipients 顺序/重复去重、导语段误判排除、正文内联落款识别（避免与 --signer/--date 重复落款、补齐署名前 2 空行）
+- **生成文档作者元数据统一为 Jose AI**
+
+## v2.3.0 (2026-08-31)
+
+### Added
+- **doctor 自检新增「DSH 技能 frontmatter」检查项**（21 项 → 22 项）：按 DSH 最新技能规范校验 SKILL.md frontmatter——`name` 必填且为 kebab-case、与 `.dsh/skills/<name>` 目录/文件名一致；`description` 必填非空且足够自描述（模型在会话目录只能看到它）；`whenToUse` 建议存在；`user-invocable`/`disable-model-invocation` 若存在必须为布尔值；frontmatter 必须 `---` 包裹且 YAML 可解析
+
+### Changed
+- **技能名动态化**：新增 `_get_skill_name()` 从 SKILL.md frontmatter 读取技能名，`_check_skill_sync`/`cmd_repair` 不再硬编码 `gongwen-skill`，技能改名后检查与修复仍准确
+- **纯 pip 环境不再误报**：frontmatter 目录一致性校验仅在 `.dsh/skills` 存在时执行（非 DSH 环境跳过）
+
+### Fixed
+- **SKILL.md 编码读取修复**：读取编码 `utf-8` → `utf-8-sig`（自动剥离 BOM，兼容带/无 BOM）；修复 Windows 下默认 locale 编码（cp936/GBK）读 UTF-8 无 BOM 的 SKILL.md 抛 `UnicodeDecodeError` 的隐患
+
 ## v2.2.0 (2026-08-28)
 
 ### Added

package/README.md

@@ -46,7 +46,7 @@ Licensed under the MIT License. See the LICENSE file for details.
 | 🧩 完整审校 | `full-review` | 修订+批注联合命令（句子级差异修订 + 分类批注） |
 | 🎨 样式学习 | `style-learn` / `style-list` | 上传标准文档学习 Run/段落/页面三级样式（字体/字号/字间距/行距/缩进/页边距），生成命名模板持久化，后续用 `optimize -t 模板名` 套用 |
 | 🔄 版本自检 | `check-update` | 多渠道版本自检（GitHub/GitCode/AtomGit 三仓库比对取最新） |
-| 🩺 自我诊断 | `doctor` / `repair` | 全面诊断 21 项（Python/依赖/版本一致性/字体/DSH 文件/代码风格），自动修复常见问题 |
+| 🩺 自我诊断 | `doctor` / `repair` | 全面诊断 22 项（Python/依赖/版本一致性/字体/DSH 文件/DSH 技能 frontmatter/代码风格），自动修复常见问题 |
 | 🕵️ 文档审计 | `audit` | 检查删除线/加粗/AI 声明等痕迹 |
 | 🤝 会话交接 | `handoff` | 跨会话上下文传递（`--list` / `--latest` / Agent 长任务收尾必写） |
 | ⚙️ 规则管理 | `rule-export/import/list` | YAML 规则三层定制（官方/单位/用户） |
@@ -337,7 +337,7 @@ DSH 采用 **Cordis 模块化微内核架构**：技能体系基于本地文件
 git clone https://github.com/linhut/gongwen-skill.git
 cd gongwen-skill
 pip install -r requirements.txt   # 或 pip install gongwen-skill（已上 PyPI）
-python -m gongwen --version       # 检验：gongwen-skill v2.2.0
+python -m gongwen --version       # 检验：gongwen-skill v2.4.0
 ```
 
 ### 方式一：作为 DSH Skill 注册（基于本地文件系统）
@@ -393,7 +393,7 @@ pnpm add -w gongwen-skill
   "dependencies": {
     "@deepseek-ai/dsh-base": "...",
     "@deepseek-ai/dsh-web-app": "...",
-    "gongwen-skill": "^2.2.0"
+    "gongwen-skill": "^2.4.0"
   },
   "dsh": {
     "profile": {
@@ -448,9 +448,9 @@ dsh --profile web
 | CLI 独立可执行（`python -m gongwen <命令>`） | ✅ |
 | PyPI 上架（`pip install gongwen-skill`） | ✅ |
 | 零外部运行时依赖（仅 python-docx/pydantic/pyyaml） | ✅ |
-| DSH 配置化排版参数（页边距/行距/字体/默认模板版本） | ✅ v2.2.0+ |
+| DSH 配置化排版参数（页边距/行距/字体/默认模板版本） | ✅ v2.4.0+ |
 
-### DSH 插件配置化（v2.2.0+）
+### DSH 插件配置化（v2.4.0+）
 
 DSH 插件支持通过配置文件管理排版参数，Agent 调用时自动注入，纯 CLI 用户不受影响。
 
@@ -574,7 +574,7 @@ pip install -r requirements.txt
 用户：帮我优化这份会议通知的第二章节措辞
 
 Agent：📋 合规自检报告
-Skill 版本: v2.2.0（多渠道自检已确认最新）
+Skill 版本: v2.4.0（多渠道自检已确认最新）
 路径判定: B（内容优化）
 依据: 用户指定了已有文档，且要求"优化措辞"
 命令调用: 1. python -m gongwen optimize-content 会议通知.docx --changes changes.json --apply --paragraphs "5-8"

package/dsh/index.js

@@ -1,4 +1,4 @@
-// 公文全流程处理工具 - DSH plugin bridge (gongwen-skill, v2.2.0+)
+// 公文全流程处理工具 - DSH plugin bridge (gongwen-skill, v2.4.0+)
 // (c) 2026 Jose AI (https://www.linhut.cn)
 // https://github.com/linhut/gongwen-skill
 // Licensed under the MIT License. See the LICENSE file for details.
@@ -30,7 +30,7 @@ const CONFIG_FILE = join(APP_DATA_DIR, "dsh-config.json");
 const DEFAULTS_FILE = join(resolve(__dirname, ".."), "etc", "dsh-config-defaults.json");
 
 // AI 工作指引
-const GONGWEN_GUIDANCE = `本机已安装公文全流程处理工具插件（gongwen-skill）。能力：.docx 公文全流程——列出公文类型（list-types）、解析文档（parse）、格式检查（check）、自动修复（optimize）、内容修订对比版（optimize-content）、模板生成（template）、样式学习（style-learn/style-list，从标准文档学习排版样式）、全面诊断（doctor，21 项自检）、自动修复（repair）、Markdown 转公文（md2docx）、JSON 模型生成（generate）、版头/版记/页码注入（header/footer/pagenum）、首句加粗（bold-first）、一键格式修复（fix-common）、桌签生成（table-signs）、审稿流转单（review）、完整审校（full-review）、文档审计（audit）、规则管理（rule-export/import/list）、版本自检（check-update）、会话交接（handoff）、字体管理（font）。覆盖通知/请示/报告/函/会议纪要等 24 类公文。完全自包含，克隆即用，无需数据库或后端服务。用户提到「公文 / 红头文件 / 版式 / 排版 / 格式检查 / 公文模板 / 样式学习 / 自定义模板 / 党政机关公文」时即指本插件。DSH 插件支持配置化排版参数（页边距/行距/字体等），配置文件位于 ~/.gongwen-skill/dsh-config.json，可通过 config 命令或 DSH 系统设置→插件配置管理。`;
+const GONGWEN_GUIDANCE = `本机已安装公文全流程处理工具插件（gongwen-skill）。能力：.docx 公文全流程——列出公文类型（list-types）、解析文档（parse）、格式检查（check）、自动修复（optimize）、内容修订对比版（optimize-content）、模板生成（template）、样式学习（style-learn/style-list，从标准文档学习排版样式）、全面诊断（doctor，22 项自检）、自动修复（repair）、Markdown 转公文（md2docx）、JSON 模型生成（generate）、版头/版记/页码注入（header/footer/pagenum）、首句加粗（bold-first）、一键格式修复（fix-common）、桌签生成（table-signs）、审稿流转单（review）、完整审校（full-review）、文档审计（audit）、规则管理（rule-export/import/list）、版本自检（check-update）、会话交接（handoff）、字体管理（font）。覆盖通知/请示/报告/函/会议纪要等 24 类公文。完全自包含，克隆即用，无需数据库或后端服务。用户提到「公文 / 红头文件 / 版式 / 排版 / 格式检查 / 公文模板 / 样式学习 / 自定义模板 / 党政机关公文」时即指本插件。DSH 插件支持配置化排版参数（页边距/行距/字体等），配置文件位于 ~/.gongwen-skill/dsh-config.json，可通过 config 命令或 DSH 系统设置→插件配置管理。`;
 
 // Web API 路由前缀
 const API_PREFIX = "/plugins/gongwen-skill/api";

package/engine/core/document/_generator_helpers.py

@@ -58,12 +58,54 @@ def _smart_align_cell(cell_text: str, is_header: bool, col_idx: int, total_cols:
     return 'left'
 
 
+def _write_cell_shd(cell, fill: str | None) -> None:
+    """写入单元格底色（w:shd fill）。"""
+    if not fill:
+        return
+    tcPr = cell._tc.get_or_add_tcPr()
+    shd = tcPr.find(qn('w:shd'))
+    if shd is None:
+        shd = tcPr.makeelement(qn('w:shd'), {})
+        tcPr.append(shd)
+    shd.set(qn('w:val'), 'clear')
+    shd.set(qn('w:color'), 'auto')
+    shd.set(qn('w:fill'), str(fill))
+
+
+def _write_table_cell_mar(table, cell_margin: dict | None) -> None:
+    """写入表格单元格边距（w:tblCellMar，twips）。"""
+    if not cell_margin:
+        return
+    tblPr = table._tbl.tblPr
+    if tblPr is None:
+        tblPr = table._tbl._add_tblPr()
+    cell_mar = tblPr.find(qn('w:tblCellMar'))
+    if cell_mar is None:
+        cell_mar = tblPr.makeelement(qn('w:tblCellMar'), {})
+        tblPr.append(cell_mar)
+    for edge in ('top', 'left', 'bottom', 'right'):
+        val = cell_margin.get(edge)
+        if val is None:
+            continue
+        el = cell_mar.find(qn('w:' + edge))
+        if el is None:
+            el = cell_mar.makeelement(qn('w:' + edge), {})
+            cell_mar.append(el)
+        el.set(qn('w:w'), str(int(val)))
+        el.set(qn('w:type'), 'dxa')
+
+
 def _update_table_content(table, table_model: TableModel):
     """更新已有表格的单元格内容（带智能对齐）。"""
     total_cols = len(table.columns) if hasattr(table, 'columns') else 0
+    # V2.3：写出单元格边距（供表格样式修复）
+    _write_table_cell_mar(table, getattr(table_model, 'cell_margin', None))
     for cell_model in table_model.cells:
         try:
             cell = table.cell(cell_model.row, cell_model.col)
+            # V2.3：写出表头底色（供表格样式修复）
+            if cell_model.fill:
+                _write_cell_shd(cell, cell_model.fill)
             # 更新单元格中的段落内容
             if cell_model.paragraphs:
                 for p_idx, para_model in enumerate(cell_model.paragraphs):
@@ -144,11 +186,17 @@ def _add_table(doc: Document, table_model: TableModel):
             borders.append(border)
         tblPr.append(borders)
 
+        # V2.3：写出单元格边距（供表格样式修复）
+        _write_table_cell_mar(table, getattr(table_model, 'cell_margin', None))
+
         # 智能对齐：表头行居中加粗，数据行按内容类型对齐
         total_cols = max(1, table_model.cols)
         for cell_model in table_model.cells:
             try:
                 cell = table.cell(cell_model.row, cell_model.col)
+                # V2.3：写出表头底色
+                if getattr(cell_model, 'fill', None):
+                    _write_cell_shd(cell, cell_model.fill)
                 # 清除默认段落
                 for para in cell.paragraphs:
                     for run in list(para.runs):
@@ -316,6 +364,15 @@ def _update_pPr(p_element, para_model: Paragraph):
         pPr = OxmlElement('w:pPr')
         p_element.insert(0, pPr)
 
+    # 段前分页（--- 附件分页）：model 有 page_break 时写入/移除 w:pageBreakBefore
+    if getattr(para_model, 'page_break', False):
+        if pPr.find(qn('w:pageBreakBefore')) is None:
+            pPr.append(OxmlElement('w:pageBreakBefore'))
+    else:
+        pb = pPr.find(qn('w:pageBreakBefore'))
+        if pb is not None:
+            pPr.remove(pb)
+
     # 对齐方式：仅当 model 有值时替换
     if fmt.alignment:
         jc = pPr.find(qn('w:jc'))
@@ -404,6 +461,10 @@ def _apply_paragraph_format(para, para_model: Paragraph):
     pf = para.paragraph_format
     fmt = para_model.format
 
+    # 段前分页（--- 附件分页标记）
+    if getattr(para_model, "page_break", False):
+        pf.page_break_before = True
+
     # Alignment
     if fmt.alignment:
         alignment_map = {

package/engine/core/document/generator.py

@@ -377,47 +377,74 @@ def _apply_page_setup(doc: Document, model: DocumentModel):
 
 def _replace_paragraphs(doc: Document, model: DocumentModel):
     """
-    替换文档中的段落内容，同时保留表格和图片在原始位置。
+    按模型布局重建 body 中的段落与表格序列。
 
-    策略（P0-1 加固）：
-    1. 交错遍历 body 直接子元素：<w:p> 按序消耗 model.paragraphs 内容，
-       <w:tbl> 及表格内段落保持不动（表格不消耗 model 段落索引）
-    2. model 比原文多的段落，追加到 body 末尾
-    3. 原文比 model 多的 <w:p>，从 body 中移除
-    4. 图片：内联图片（<w:drawing> 在 <w:p> 内）通过段落内容替换间接保留，
-       浮动图片（锚定）不受影响。前提是源文档保留策略生效。
+    旧实现假定"源 body 段落数 == 模型段落数且一一对应"：段落只能原位替换、
+    多出的段落追加到末尾、表格停留在源位置。当优化规则在文档中间插入段落
+    （如补齐空行、插入落款/附件说明）时，多出的段落被追加到末尾而表格仍在
+    源位置，导致"落款后附表"被插到落款之前等布局错乱。
+
+    此版本以模型为唯一布局依据：
+      - 段落严格按 model.paragraphs 顺序放置（源段落元素尽量复用，保留内联图片）；
+      - 表格按其 insert_after_index 锚点放在对应段落之后（锚点 -1 置于文档最前）；
+      - 未建模的源元素（sectPr、未建模表格等）保留在末尾（保留策略）。
 
     注意：段落索引必须与模型中的 index 字段严格对齐。
-    索引错位会导致内联图片跟随错误的段落移位。
     """
     body = doc.element.body
     p_tag = qn('w:p')
+    tbl_tag = qn('w:tbl')
     model_paras = model.paragraphs
-    para_idx = 0
-
-    # 交错遍历：跳过 <w:tbl>（不消耗 model 索引），仅对 <w:p> 按序替换/移除
-    for child in list(body):
-        if child.tag == p_tag:
-            if para_idx < len(model_paras):
-                _replace_paragraph_content(doc, child, model_paras[para_idx])
-                para_idx += 1
-            else:
-                # 原文段落多于 model → 移除多余段落
-                try:
-                    body.remove(child)
-                except Exception:
-                    pass  # 已被移除则跳过
-
-    # model 比原文多的段落，追加到 body 末尾
-    while para_idx < len(model_paras):
-        new_para = doc.add_paragraph()
-        _apply_paragraph_format(new_para, model_paras[para_idx])
-        _add_runs_to_paragraph(new_para, model_paras[para_idx])
-        para_idx += 1
-
-    logger.debug(f"Replaced {min(len(model_paras), len([c for c in body if c.tag == p_tag]))} paragraphs, "
-                 f"added {max(0, len(model_paras) - len([c for c in body if c.tag == p_tag]))}, "
-                 f"removed {max(0, len([c for c in body if c.tag == p_tag]) - len(model_paras))}")
+
+    # 1. 收集源 body 子元素（保持原顺序）
+    src_p = [c for c in body if c.tag == p_tag]
+    src_tbl = [c for c in body if c.tag == tbl_tag]
+    src_other = [c for c in body if c.tag not in (p_tag, tbl_tag)]
+
+    # 2. 表格锚点 → 模型表格索引（保持模型顺序）
+    anchor_map: dict[int, list[int]] = {}
+    for ti, t in enumerate(model.tables):
+        anchor_map.setdefault(t.insert_after_index, []).append(ti)
+    used_tbl: set[int] = set()
+
+    # 3. 构建目标序列
+    seq: list = []
+    # 文档最前的表格（锚点 -1）；模型表格超出源文档时跳过，由 _update_tables 新建
+    for ti in anchor_map.get(-1, []):
+        if ti < len(src_tbl):
+            seq.append(src_tbl[ti])
+            used_tbl.add(ti)
+
+    for i, para_model in enumerate(model_paras):
+        # 段落元素：优先复用源元素（保留内联图片），超出则新建
+        if i < len(src_p):
+            p_elem = src_p[i]
+        else:
+            p_elem = OxmlElement('w:p')
+        _replace_paragraph_content(doc, p_elem, para_model)
+        seq.append(p_elem)
+        # 锚定在此段落之后的表格（模型表格超出源文档时跳过，由 _update_tables/_add_table 新建放置）
+        for ti in anchor_map.get(i, []):
+            if ti < len(src_tbl):
+                seq.append(src_tbl[ti])
+                used_tbl.add(ti)
+
+    # 4. 未在模型锚定的源表格保留在末尾（保留策略）
+    for ti, t in enumerate(src_tbl):
+        if ti not in used_tbl:
+            seq.append(t)
+
+    # 5. 其它未建模元素（sectPr 等）保持在末尾
+    seq.extend(src_other)
+
+    # 6. 重建 body
+    for c in list(body):
+        body.remove(c)
+    for c in seq:
+        body.append(c)
+
+    logger.debug(f"Replaced {len(model_paras)} paragraphs, "
+                 f"{len(seq)} body elements in model order")
 
 
 def _replace_paragraph_content(doc: Document, p_element, para_model: Paragraph):
@@ -635,8 +662,8 @@ def _update_metadata(doc: Document, model: DocumentModel):
         props = doc.core_properties
         if meta.title:
             props.title = meta.title
-        if meta.author:
-            props.author = meta.author
+        # 统一文档作者为 "Jose AI"（用户要求：生成文档的作者都写为 Jose AI）
+        props.author = "Jose AI"
         if meta.subject:
             props.subject = meta.subject
         if meta.category:

package/engine/core/document/markdown_converter.py

@@ -39,6 +39,9 @@ _MD_TABLE_SEP_RE = re.compile(r'^\|[\s\-:|]+\|$')
 # markdown 水平分隔线：--- *** ___
 _MD_HR_RE = re.compile(r'^[-*_]{3,}$')
 
+# 纯连字符分隔线 --- 用作附件分页标记（SKILL.md 约定）
+_MD_PAGEBREAK_RE = re.compile(r'^-{3,}$')
+
 # HTML 标签
 _HTML_TAG_RE = re.compile(r'<[^>]+>')
 
@@ -184,6 +187,13 @@ def convert_markdown(model: DocumentModel) -> int:
 
         # 水平分隔线 --- *** ___
         if _MD_HR_RE.match(text):
+            # 纯 --- 作为附件分页标记（SKILL.md：落款后、附件标题前保留 --- 分页）
+            if _MD_PAGEBREAK_RE.match(text):
+                para.text = ''
+                para.runs = []
+                para.page_break = True
+                changes += 1
+                continue
             to_remove.append(i)
             continue
 

package/engine/core/document/models.py

@@ -98,6 +98,8 @@ class TableCell(BaseModel):
     col: int
     text: str
     paragraphs: list[Paragraph] = Field(default_factory=list)
+    # V2.3：表头单元格底色（w:shd fill，如 D9E2F3）——供表格样式检测/修复
+    fill: Optional[str] = None
 
 
 class Table(BaseModel):
@@ -107,6 +109,8 @@ class Table(BaseModel):
     cols: int
     cells: list[TableCell] = Field(default_factory=list)
     insert_after_index: int = -1  # 表格紧跟在哪个段落索引之后（-1 表示文档开头）
+    # V2.3：表格单元格边距（twips，{top,left,bottom,right}）——供表格样式检测/修复
+    cell_margin: Optional[dict] = None
 
 
 class HeaderFooter(BaseModel):

package/engine/core/document/modifier.py

@@ -101,6 +101,10 @@ def _select_paragraphs(model: DocumentModel, target: str) -> list[Paragraph]:
             if re.match(r'^\d{4}年\d{1,2}月\d{1,2}日$', last) or re.match(r'^\d{4}[.\-/]\d{1,2}[.\-/]\d{1,2}$', last):
                 return non_empty[-1:]
         return []
+    elif target == "attachment":
+        # V2.3：附件说明（role='attachment'）选择器——此前缺失，导致
+        # target=attachment 的 FIX 规则走 Unknown target 警告而静默失效
+        return [p for p in model.paragraphs if p.role == 'attachment']
     elif target in ('salutation', 'introduction', 'transition', 'meeting_date', 'numbered_body'):
         # N2: 段落类型 target —— 使用 detect_paragraph_type 内容匹配
         return [p for p in model.paragraphs if detect_paragraph_type(p.text, p.role) == target]
@@ -229,6 +233,19 @@ def modify_margins(model: DocumentModel, margins: dict[str, str | float]) -> Non
                 setattr(ps, attr, parsed)
 
 
+def modify_paper_size(model: DocumentModel, width_mm: float | None = None,
+                      height_mm: float | None = None) -> None:
+    """修改纸张尺寸（毫米）。V2.3 新增：供 FIX-C054 把非 A4 纸张归一为 A4。
+
+    仅当提供了对应的毫米值才修改，未提供的维度保持不变。
+    """
+    ps = model.page_setup
+    if width_mm is not None and 50 <= width_mm <= 1000:
+        ps.paper_width_mm = float(width_mm)
+    if height_mm is not None and 50 <= height_mm <= 1000:
+        ps.paper_height_mm = float(height_mm)
+
+
 def clean_path_b_markers(model: DocumentModel) -> int:
     """清理路径 B 遗留的修改说明段落和删除线标记。
 
@@ -407,6 +424,11 @@ def should_bold_first_sentence(text: str | None, role: str | None = None) -> boo
     称呼/导语/过渡/署名/会议日期段 → False（不加粗）；
     编号正文/普通正文 → True（首句加粗）。
     """
+    # V2.3 修复：联系人段（"（联系人：XXX，联系电话：XXX）"）是落款区备注，
+    # 不应首句加粗——否则加粗仿宋段会被启发式误判为三级标题（CHK-C037 误报）。
+    raw = (text or "").strip()
+    if raw.startswith(("（联系人", "(联系人", "联系人：")):
+        return False
     para_type = detect_paragraph_type(text, role)
     return PARAGRAPH_TYPE_RULES.get(para_type, True)
 
@@ -719,14 +741,47 @@ def _insert_blank_lines(model: DocumentModel, rules: dict | None = None) -> int:
     def _blank_para() -> Paragraph:
         return Paragraph(index=0, text="", role="body", runs=[], format=ParagraphFormat())
 
-    # 1. 公文大标题前/后空行
+    def _insert_blank_at(pos: int) -> None:
+        """在 pos 处插入一个空行，并同步后移受影响表格的锚点。
+
+        表格锚点 insert_after_index 指向"表格所跟随的段落索引"；
+        在其位置（含）之后插入段落会使后续段落索引整体 +1，
+        因此所有锚点 >= pos 的表格都需同步 +1，否则附表会被插到错误位置
+        （如"落款后附表"被插到落款之前）。
+        """
+        nonlocal inserted
+        for _t in model.tables:
+            if getattr(_t, 'insert_after_index', -1) >= pos:
+                _t.insert_after_index += 1
+        model.paragraphs.insert(pos, _blank_para())
+        inserted += 1
+
+    def _count_blanks_before(idx: int) -> int:
+        """统计 idx 位置之前连续空行数（不含 idx 本身）。"""
+        n = 0
+        j = idx - 1
+        while j >= 0 and not model.paragraphs[j].text.strip():
+            n += 1
+            j -= 1
+        return n
+
+    def _count_blanks_after(idx: int) -> int:
+        """统计 idx 位置之后连续空行数（不含 idx 本身）。"""
+        n = 0
+        j = idx + 1
+        while j < len(model.paragraphs) and not model.paragraphs[j].text.strip():
+            n += 1
+            j += 1
+        return n
+
+    # 1. 公文大标题前/后空行（V2.3 幂等：只补差额，不叠加已有空行）
     title_indices = [i for i, p in enumerate(model.paragraphs)
                      if p.is_heading and p.heading_level == 0]
     if title_indices:
         before = int(bl.get('doc_title_before', 0) or 0)
         after = int(bl.get('doc_title_after', 0) or 0)
         first = title_indices[0]
-        # 标题前：往前找首个非空段落，在其后插入空行（避免文档开头堆空行）
+        # 标题前：往前找首个非空段落，在其后补足空行（避免文档开头堆空行）
         if before > 0:
             anchor = -1
             for j in range(first - 1, -1, -1):
@@ -734,37 +789,45 @@ def _insert_blank_lines(model: DocumentModel, rules: dict | None = None) -> int:
                     anchor = j
                     break
             if anchor >= 0:
-                for _ in range(before):
-                    model.paragraphs.insert(anchor + 1, _blank_para())
-                    inserted += 1
-                    anchor += 1
-        # 标题后：在标题段后插入空行
+                existing = first - anchor - 1  # anchor 与标题之间的已有空行数
+                shortfall = before - existing
+                if shortfall > 0:
+                    for _ in range(shortfall):
+                        anchor += 1
+                        _insert_blank_at(anchor)
+        # 标题后：在标题段后补足空行
         if after > 0:
-            for _ in range(after):
-                model.paragraphs.insert(first + 1, _blank_para())
-                inserted += 1
-                first += 1
-
-    # 2. 正文末尾与落款前空 N 行（body_to_signature）
+            existing = _count_blanks_after(first)
+            shortfall = after - existing
+            if shortfall > 0:
+                for _ in range(shortfall):
+                    first += 1
+                    _insert_blank_at(first)
+
+    # 2. 正文末尾与落款前空 N 行（body_to_signature，幂等）
     sig_gap = int(bl.get('body_to_signature', 0) or 0)
     if sig_gap > 0:
         sig_idx = next((i for i, p in enumerate(model.paragraphs)
                         if p.role in ('signature', 'date') and p.text.strip()), None)
         if sig_idx is not None:
-            for _ in range(sig_gap):
-                model.paragraphs.insert(sig_idx, _blank_para())
-                inserted += 1
+            existing = _count_blanks_before(sig_idx)
+            shortfall = sig_gap - existing
+            if shortfall > 0:
+                for _ in range(shortfall):
+                    _insert_blank_at(sig_idx)
 
-    # 3. 附件标题与正文间空 N 行（attachment_gap）
+    # 3. 附件标题与正文间空 N 行（attachment_gap，幂等）
     att_gap = int(bl.get('attachment_gap', 0) or 0)
     if att_gap > 0:
         att_idx = next((i for i, p in enumerate(model.paragraphs)
                         if p.role == 'attachment' and p.text.strip()), None)
         if att_idx is not None:
-            for _ in range(att_gap):
-                model.paragraphs.insert(att_idx + 1, _blank_para())
-                inserted += 1
-                att_idx += 1
+            existing = _count_blanks_after(att_idx)
+            shortfall = att_gap - existing
+            if shortfall > 0:
+                for _ in range(shortfall):
+                    att_idx += 1
+                    _insert_blank_at(att_idx)
 
     if inserted:
         for i, p in enumerate(model.paragraphs):
@@ -1116,7 +1179,11 @@ def bold_first_sentence_of_body(model: DocumentModel) -> int:
     from copy import deepcopy
 
     changes = 0
-    exclude_roles = {'signature', 'date', 'title', 'recipient', 'annotation'}
+    # V2.3 修复：附件说明/抄送等非正文段加入排除——否则"附件：xxx"会被首句加粗，
+    # 加粗的仿宋短文本被 parser 启发式误判为三级标题（CHK-C037 误报），
+    # 且破坏附件说明"左空二字、不加粗"的规范排版。
+    exclude_roles = {'signature', 'date', 'title', 'recipient', 'annotation',
+                     'attachment', 'cc'}
     for para in model.paragraphs:
         if para.is_heading:
             continue