@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/docx-author/scripts/docx_doc.py

@@ -1,161 +1,21 @@
-# Word 文档生成助手（经 run_python 执行）。核心入口 md_to_docx()：
-#   Markdown（#/##/### 标题、-/1. 列表、| 表格、**粗体**、普通段落）→ 成品 docx，
-#   自动带：封面（题目/作者/日期）、目录域（Word 内 F9 更新）、页脚"第 X 页 共 Y 页"、
-#   中文字体（正文宋体/标题黑体，经 w:eastAsia 正确设置）。
-# 直接执行本文件 = 自测：产出 docx_doc_check.docx 并重读校验。
-import datetime
-import re
+# 兼容垫片：老入口 md_to_docx() / verify() 保留，实现已迁到 docx_build.py + docx_check.py。
+#
+# 为什么保留而不是直接删：外部脚本与历史会话里可能还 read_skill_file 到这个文件名。
+# 新代码请直接用 create_doc 工具，或 import docx_build。
+import os
+import sys
 
-from docx import Document
-from docx.enum.text import WD_ALIGN_PARAGRAPH
-from docx.oxml.ns import qn
-from docx.oxml import OxmlElement
-from docx.shared import Pt
-
-
-def _set_ea(style, west, east, size=None, bold=None):
-    """中文字体必须同时设 w:eastAsia，只设 font.name 中文不生效。"""
-    style.font.name = west
-    style.element.rPr.rFonts.set(qn('w:eastAsia'), east)
-    if size is not None:
-        style.font.size = Pt(size)
-    if bold is not None:
-        style.font.bold = bold
-
-
-def _field(run, instr, placeholder=''):
-    """在 run 上插入 Word 域（TOC/PAGE/NUMPAGES…）。"""
-    begin = OxmlElement('w:fldChar')
-    begin.set(qn('w:fldCharType'), 'begin')
-    it = OxmlElement('w:instrText')
-    it.set(qn('xml:space'), 'preserve')
-    it.text = instr
-    sep = OxmlElement('w:fldChar')
-    sep.set(qn('w:fldCharType'), 'separate')
-    t = OxmlElement('w:t')
-    t.text = placeholder
-    end = OxmlElement('w:fldChar')
-    end.set(qn('w:fldCharType'), 'end')
-    for el in (begin, it, sep, t, end):
-        run._r.append(el)
-
-
-def new_doc():
-    """建空文档并配好中英文字体样式。"""
-    doc = Document()
-    _set_ea(doc.styles['Normal'], 'Calibri', '宋体', size=11)
-    for lvl, size in (('Heading 1', 16), ('Heading 2', 14), ('Heading 3', 12)):
-        _set_ea(doc.styles[lvl], 'Calibri', '黑体', size=size, bold=True)
-    return doc
-
-
-def add_cover(doc, title, author='', subtitle=''):
-    for _ in range(6):
-        doc.add_paragraph()
-    p = doc.add_paragraph()
-    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
-    r = p.add_run(title)
-    r.font.size = Pt(28)
-    r.font.bold = True
-    r.font.name = 'Calibri'
-    r._element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
-    if subtitle:
-        p2 = doc.add_paragraph()
-        p2.alignment = WD_ALIGN_PARAGRAPH.CENTER
-        p2.add_run(subtitle).font.size = Pt(14)
-    meta = doc.add_paragraph()
-    meta.alignment = WD_ALIGN_PARAGRAPH.CENTER
-    meta.add_run(f"{author + '　' if author else ''}{datetime.date.today().strftime('%Y年%m月%d日')}").font.size = Pt(12)
-    doc.add_page_break()
-
-
-def add_toc(doc):
-    doc.add_paragraph('目录', style='Heading 1')
-    _field(doc.add_paragraph().add_run(), 'TOC \\o "1-3" \\h \\z \\u', '（在 Word 中右键→更新域，或按 F9 生成目录）')
-    doc.add_page_break()
-
-
-def add_page_footer(doc):
-    p = doc.sections[0].footer.paragraphs[0]
-    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
-    p.add_run('第 ')
-    _field(p.add_run(), 'PAGE', '1')
-    p.add_run(' 页 共 ')
-    _field(p.add_run(), 'NUMPAGES', '1')
-    p.add_run(' 页')
-
-
-def _add_runs(par, text):
-    """按 **粗体** 拆 run。"""
-    for i, seg in enumerate(re.split(r'\*\*(.+?)\*\*', text)):
-        if seg:
-            par.add_run(seg).bold = (i % 2 == 1)
-
-
-def _flush_table(doc, rows):
-    cells = [[c.strip() for c in r.strip().strip('|').split('|')] for r in rows]
-    cells = [r for r in cells if not all(re.fullmatch(r':?-{2,}:?', c or '---') for c in r)]  # 去分隔行
-    if not cells:
-        return
-    tb = doc.add_table(rows=len(cells), cols=len(cells[0]))
-    tb.style = 'Table Grid'
-    for i, row in enumerate(cells):
-        for j, val in enumerate(row[:len(tb.columns)]):
-            par = tb.cell(i, j).paragraphs[0]
-            _add_runs(par, val)
-            if i == 0:
-                for r in par.runs:
-                    r.bold = True
-
-
-def md_to_docx(md_path, out_path, title='', author='', subtitle='', toc=True):
-    """Markdown → Word。返回 out_path。"""
-    doc = new_doc()
-    add_page_footer(doc)
-    if title:
-        add_cover(doc, title, author, subtitle)
-    if toc:
-        add_toc(doc)
-    lines = open(md_path, encoding='utf-8').read().splitlines()
-    table = []
-    for line in lines + ['']:  # 末尾哨兵，冲刷表格
-        s = line.rstrip()
-        if s.lstrip().startswith('|'):
-            table.append(s)
-            continue
-        if table:
-            _flush_table(doc, table)
-            table = []
-        if not s.strip():
-            continue
-        m = re.match(r'^(#{1,3})\s+(.*)', s)
-        if m:
-            doc.add_paragraph(m.group(2).strip(), style=f'Heading {len(m.group(1))}')
-        elif re.match(r'^\s*-\s+', s):
-            _add_runs(doc.add_paragraph(style='List Bullet'), re.sub(r'^\s*-\s+', '', s))
-        elif re.match(r'^\s*\d+[.、]\s*', s):
-            _add_runs(doc.add_paragraph(style='List Number'), re.sub(r'^\s*\d+[.、]\s*', '', s))
-        else:
-            _add_runs(doc.add_paragraph(), s)
-    doc.save(out_path)
-    return out_path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from docx_build import DocBuilder, build, md_to_blocks, md_to_docx   # noqa: F401,E402
 
 
 def verify(path):
-    """重读校验（验收步骤用）：打印标题树与段落/表格数。"""
-    doc = Document(path)
-    heads = [(p.style.name, p.text) for p in doc.paragraphs if p.style.name.startswith('Heading')]
-    print(f'[verify] 段落 {len(doc.paragraphs)} · 表格 {len(doc.tables)} · 标题 {len(heads)}')
-    for style, text in heads:
-        print('  ' * (int(style[-1]) - 1) + f'- [{style}] {text}')
-    return heads
+    """重读校验（老接口）。新代码用 docx_check.inspect() —— 它查的远不止标题树。"""
+    import docx_check
+    res = docx_check.inspect(path)
+    print(docx_check.report(res))
+    return res
 
 
 if __name__ == '__main__':
-    md = 'docx_doc_check.md'
-    open(md, 'w', encoding='utf-8').write(
-        '# 一、背景\n项目**按期**推进。\n\n## 1.1 目标\n- 目标甲\n- 目标乙\n\n'
-        '# 二、数据\n| 地区 | 销售额 |\n|---|---|\n| 华东 | 1200 |\n| 华南 | 950 |\n\n1. 结论一\n2. 结论二\n')
-    p = md_to_docx(md, 'docx_doc_check.docx', title='自测报告', author='Work Twin', subtitle='docx_doc.py 冒烟')
-    verify(p)
-    print('OK', p)
+    print(__doc__)

package/skills/docx-author/scripts/docx_layout.py

@@ -0,0 +1,490 @@
+# Word 技术文档排版度量与规范内核（docx_build 建版 / docx_check 体检 共用同一套度量）。
+#
+# 为什么必须共用：建版时算「这张表放不放得下版心」和体检时算「这张表有没有超出版心」，
+# 只要用两套度量，就一定会出现「生成端说没事、体检端说超宽」的自相矛盾。
+# 一份度量、两个方向用——这是本模块存在的唯一理由（与 pptx_layout 同一条纪律）。
+#
+# 度量口径（Word 渲染，中文宋体/黑体 + 西文 Times New Roman）：
+#   · 字宽按 em 表逐字累加（中日韩全角 1.0em，Times 数字 0.5em，小写 0.50em…）；
+#   · 单倍行高 1.32×字号（SimSun ascent+descent≈1.32em）；
+#   · 版心宽 = 纸宽 − 左右页边距，**所有「会不会超宽」的判断都以它为准**。
+# 估算不可能与 Word 逐像素一致，所以留了 TOL 容差，且报告一律带出
+# 「估算值 vs 可用值」的具体数字，让人能自己判断，而不是只丢一个结论。
+
+import re
+
+# ── 单位 ───────────────────────────────────────────────────────────────────
+CM_PT = 28.3464567          # 1 厘米 = 28.35 磅
+PT_CM = 1.0 / CM_PT
+EMU_PT = 12700              # 1 磅 = 12700 EMU
+EMU_CM = 360000             # 1 厘米 = 360000 EMU
+PT_IN = 72.0
+
+LINE_H = 1.32               # 单倍行距 ≈ 1.32 × 字号（宋体 ascent 1060 + descent 380 / 1000 ≈ 1.44 排版实测取 1.32）
+WRAP_SAFETY = 0.98          # 折行留 2% 余量：字宽估窄一点就会少算一行，少算一行就是「说放得下、实际挤出去」
+TOL = 1.02                  # 超限容差：估算超出可用空间 2% 以内不报（度量误差带）
+
+# ── 中文字号 → 磅 ──────────────────────────────────────────────────────────
+SIZE_PT = {
+    '初号': 42, '小初': 36, '一号': 26, '小一': 24, '二号': 22, '小二': 18,
+    '三号': 16, '小三': 15, '四号': 14, '小四': 12, '五号': 10.5, '小五': 9,
+    '六号': 7.5, '小六': 6.5, '七号': 5.5, '八号': 5,
+}
+PT_SIZE = {v: k for k, v in SIZE_PT.items()}
+
+
+def pt_of(size):
+    """'小四' / 12 / '12' → 12.0 磅。"""
+    if isinstance(size, str):
+        s = size.strip()
+        if s in SIZE_PT:
+            return float(SIZE_PT[s])
+        try:
+            return float(s)
+        except ValueError:
+            return 12.0
+    return float(size)
+
+
+def size_name(pt):
+    """12.0 → '小四'；非标准字号返回 '12pt'（体检报告里要说人话）。"""
+    for v, n in PT_SIZE.items():
+        if abs(v - pt) < 0.26:
+            return n
+    return f'{pt:g}pt'
+
+
+# ── 字宽表（em）────────────────────────────────────────────────────────────
+# 取值不是拍脑袋：中文按全角 1.0em（宋体/黑体/仿宋均为等宽全角，这一条是确定的）；
+# 西文按 Times New Roman（Word 中文文档的默认西文字体，unitsPerEm 2048）实测 advance /2048，
+# 并统一向上取一档——**宁可估宽，不可估窄**：估宽了最多是提前折一行留白多一点，
+# 估窄了就是「说这列放得下、实际把表挤出版心」，那才是要命的。
+W_CJK = 1.0
+W_DIGIT = 0.52      # Times 数字 1024/2048 = 0.500
+W_UPPER = 0.73      # Times 'A' 0.72 / 'M' 0.89 / 'I' 0.33，取常见上沿
+W_LOWER = 0.50      # Times 'a' 0.44 / 'm' 0.78 / 'i' 0.28
+W_SPACE = 0.27      # Times space 512/2048 = 0.250
+W_NARROW = 0.28
+W_WIDE = 0.88
+
+NARROW = set(".,;:!|'`iIljtf()[]{}-·")
+WIDE = set("@%&WMmw#—…")
+
+
+def _full_width(cp):
+    """全角判定：CJK 汉字、假名、谚文、全角标点、CJK 兼容形。"""
+    return (
+        0x1100 <= cp <= 0x115F or 0x2E80 <= cp <= 0xA4CF or 0xAC00 <= cp <= 0xD7A3
+        or 0xF900 <= cp <= 0xFAFF or 0xFE10 <= cp <= 0xFE6F or 0xFF00 <= cp <= 0xFF60
+        or 0xFFE0 <= cp <= 0xFFE6 or 0x3000 <= cp <= 0x303F
+    )
+
+
+def char_em(ch):
+    """单字符宽度（em）。"""
+    cp = ord(ch)
+    if ch == ' ':
+        return W_SPACE
+    if ch == '\t':
+        return W_SPACE * 4
+    if _full_width(cp):
+        return W_CJK
+    if cp > 0xFFFF:
+        return 1.15
+    if ch in NARROW:
+        return W_NARROW
+    if ch in WIDE:
+        return W_WIDE
+    if '0' <= ch <= '9':
+        return W_DIGIT
+    if 'A' <= ch <= 'Z':
+        return W_UPPER
+    if 'a' <= ch <= 'z':
+        return W_LOWER
+    if cp < 0x2E80:
+        return W_LOWER
+    return W_CJK
+
+
+def measure(text, size, bold=False):
+    """估算一段文本的渲染宽度（磅）。size 可传 '小四' 或 12。"""
+    if not text:
+        return 0.0
+    pt = pt_of(size)
+    w = sum(char_em(ch) for ch in str(text)) * pt
+    return w * (1.06 if bold else 1.0)      # 加粗按 6% 加宽（宋体加粗是合成粗体，会变宽）
+
+
+def wrap_count(text, size, width_pt, first_indent_pt=0.0):
+    """这段文字在给定宽度里要占几行（首行可另设缩进）。空文本算 1 行——Word 里空段也占一行。"""
+    s = str(text or '')
+    if not s.strip():
+        return 1
+    pt = pt_of(size)
+    avail_first = max(width_pt - first_indent_pt, pt)
+    avail = max(width_pt, pt)
+    lines, cur, limit = 1, 0.0, avail_first * WRAP_SAFETY
+    for ch in s:
+        if ch == '\n':
+            lines += 1
+            cur, limit = 0.0, avail * WRAP_SAFETY
+            continue
+        w = char_em(ch) * pt
+        if cur + w > limit:
+            lines += 1
+            cur, limit = w, avail * WRAP_SAFETY
+        else:
+            cur += w
+    return lines
+
+
+# ── 排版规范档位 ───────────────────────────────────────────────────────────
+# 三档规范都是「有出处的」，不是审美偏好：
+#   tech   —— 企业技术/项目管理文档通行做法（A4、左右 3.17cm、正文宋体小四、1.5 倍行距、首行缩进 2 字符）；
+#   gov    —— GB/T 9704《党政机关公文格式》：正文仿宋_GB2312 三号，每面 22 行、每行 28 字，
+#             一级「一、」黑体三号、二级「（一）」楷体三号、三级「1.」仿宋三号加粗；
+#   report —— 科技报告/学术稿：小四宋体、固定 20 磅行距、十进制编号 1 / 1.1 / 1.1.1。
+# 改这里=改全局排版，建版与体检同时跟着变，不会各改各的。
+
+_BASE = {
+    'page': 'A4',
+    'page_w_cm': 21.0,
+    'page_h_cm': 29.7,
+    'margin_cm': {'top': 2.54, 'bottom': 2.54, 'left': 3.17, 'right': 3.17},
+    'body': {'east': '宋体', 'west': 'Times New Roman', 'size': '小四',
+             'line_rule': 'multiple', 'line': 1.5, 'first_indent_chars': 2,
+             'space_before': 0, 'space_after': 0, 'align': 'justify'},
+    'headings': [
+        {'east': '黑体', 'west': 'Times New Roman', 'size': '三号', 'bold': False,
+         'align': 'center', 'space_before': 18, 'space_after': 12, 'line': 1.5},
+        {'east': '黑体', 'west': 'Times New Roman', 'size': '四号', 'bold': False,
+         'align': 'left', 'space_before': 12, 'space_after': 6, 'line': 1.5},
+        {'east': '黑体', 'west': 'Times New Roman', 'size': '小四', 'bold': False,
+         'align': 'left', 'space_before': 6, 'space_after': 6, 'line': 1.5},
+        {'east': '楷体', 'west': 'Times New Roman', 'size': '小四', 'bold': True,
+         'align': 'left', 'space_before': 6, 'space_after': 0, 'line': 1.5},
+    ],
+    'caption': {'east': '黑体', 'west': 'Times New Roman', 'size': '五号',
+                'align': 'center', 'line': 1.0},
+    'table': {'east': '宋体', 'west': 'Times New Roman', 'size': '五号',
+              'head_bold': True, 'align': 'center', 'line': 1.0, 'style': '三线表'},
+    'numbering': 'cn',          # cn = 一、/（一）/1./（1）；decimal = 1/1.1/1.1.1；none = 不编号
+    'fig_prefix': '图',
+    'tab_prefix': '表',
+    'caption_by_chapter': False,  # True = 图 1-1（按章编号），False = 图 1（全文连续）
+    'toc_levels': 3,
+    'max_image_cm': None,       # None = 版心宽
+    'name': 'tech',
+    'label': '技术文档（A4/宋体小四/1.5 倍行距/首行缩进 2 字符）',
+}
+
+
+def _merge(base, over):
+    out = {}
+    for k, v in base.items():
+        if isinstance(v, dict) and isinstance(over.get(k), dict):
+            out[k] = _merge(v, over[k])
+        elif isinstance(v, list) and isinstance(over.get(k), list):
+            out[k] = [_merge(a, b) if isinstance(a, dict) and isinstance(b, dict) else b
+                      for a, b in zip(v, over[k])] + over[k][len(v):]
+        else:
+            out[k] = over[k] if k in over else v
+    for k, v in over.items():
+        if k not in out:
+            out[k] = v
+    return out
+
+
+_OVERRIDES = {
+    'tech': {},
+    'gov': {
+        'name': 'gov',
+        'label': '党政机关公文 GB/T 9704（仿宋三号/固定 28.8 磅行距/每面 22 行）',
+        'margin_cm': {'top': 3.7, 'bottom': 3.5, 'left': 2.8, 'right': 2.6},
+        'body': {'east': '仿宋_GB2312', 'west': 'Times New Roman', 'size': '三号',
+                 'line_rule': 'exact', 'line': 28.8, 'first_indent_chars': 2,
+                 'space_before': 0, 'space_after': 0, 'align': 'justify'},
+        'headings': [
+            {'east': '黑体', 'size': '三号', 'bold': False, 'align': 'left',
+             'space_before': 0, 'space_after': 0, 'line': 28.8, 'line_rule': 'exact'},
+            {'east': '楷体_GB2312', 'size': '三号', 'bold': False, 'align': 'left',
+             'space_before': 0, 'space_after': 0, 'line': 28.8, 'line_rule': 'exact'},
+            {'east': '仿宋_GB2312', 'size': '三号', 'bold': True, 'align': 'left',
+             'space_before': 0, 'space_after': 0, 'line': 28.8, 'line_rule': 'exact'},
+            {'east': '仿宋_GB2312', 'size': '三号', 'bold': True, 'align': 'left',
+             'space_before': 0, 'space_after': 0, 'line': 28.8, 'line_rule': 'exact'},
+        ],
+        'table': {'east': '仿宋_GB2312', 'size': '小四', 'head_bold': True},
+        'caption': {'east': '黑体', 'size': '五号'},
+        'numbering': 'cn',
+    },
+    'report': {
+        'name': 'report',
+        'label': '科技报告/学术（宋体小四/固定 20 磅行距/十进制编号）',
+        'margin_cm': {'top': 2.54, 'bottom': 2.54, 'left': 3.0, 'right': 3.0},
+        'body': {'line_rule': 'exact', 'line': 20, 'first_indent_chars': 2},
+        'headings': [
+            {'east': '黑体', 'size': '三号', 'align': 'center', 'space_before': 18, 'space_after': 12},
+            {'east': '黑体', 'size': '四号', 'align': 'left', 'space_before': 12, 'space_after': 6},
+            {'east': '黑体', 'size': '小四', 'align': 'left', 'space_before': 6, 'space_after': 6},
+            {'east': '黑体', 'size': '小四', 'bold': False, 'align': 'left', 'space_before': 6, 'space_after': 0},
+        ],
+        'numbering': 'decimal',
+        'caption_by_chapter': True,
+    },
+}
+
+PROFILES = {k: _merge(_BASE, v) for k, v in _OVERRIDES.items()}
+PROFILE_NAMES = list(PROFILES)
+
+
+def profile(name='tech'):
+    """取一份规范档位（深拷贝，调用方可以就地改而不污染全局）。"""
+    p = PROFILES.get(str(name or 'tech').strip(), PROFILES['tech'])
+    return _merge(p, {})
+
+
+# ── 版心几何 ───────────────────────────────────────────────────────────────
+def body_width_pt(prof):
+    """版心宽（磅）——所有「会不会超宽」的判断都用它。"""
+    m = prof['margin_cm']
+    return (prof['page_w_cm'] - m['left'] - m['right']) * CM_PT
+
+
+def body_height_pt(prof):
+    """版心高（磅）。页眉页脚在页边距内，这里按正文可用高度算。"""
+    m = prof['margin_cm']
+    return (prof['page_h_cm'] - m['top'] - m['bottom']) * CM_PT
+
+
+def body_width_cm(prof):
+    m = prof['margin_cm']
+    return prof['page_w_cm'] - m['left'] - m['right']
+
+
+def line_height_pt(prof, style=None):
+    """一行占多高（磅）。exact=固定值直接返回；multiple=倍数×单倍行高。"""
+    st = style or prof['body']
+    size = pt_of(st.get('size', prof['body']['size']))
+    rule = st.get('line_rule', prof['body'].get('line_rule', 'multiple'))
+    val = st.get('line', prof['body'].get('line', 1.5))
+    if rule == 'exact':
+        return float(val)
+    return size * LINE_H * float(val)
+
+
+def indent_pt(prof, style=None):
+    """首行缩进（磅）= 缩进字符数 × 字号。中文排版的「2 字符」是随字号变的，不是固定磅值。"""
+    st = style or prof['body']
+    return float(st.get('first_indent_chars', 0)) * pt_of(st.get('size', prof['body']['size']))
+
+
+def est_para_height(text, prof, style=None):
+    """一段文字的估算高度（磅），含段前段后。"""
+    st = style or prof['body']
+    size = st.get('size', prof['body']['size'])
+    n = wrap_count(text, size, body_width_pt(prof), indent_pt(prof, st))
+    return n * line_height_pt(prof, st) + float(st.get('space_before', 0)) + float(st.get('space_after', 0))
+
+
+# ── 表格列宽（先量后画的核心）───────────────────────────────────────────────
+def fit_table_widths(rows, prof, size=None, min_col_cm=1.2, pad_pt=8.0):
+    """按内容算列宽，总宽压进版心。返回每列宽度（厘米）。
+
+    做法：先按「每列最长单元格的自然宽度」分配，超版心时按超出比例压缩，
+    但每列不低于 min_col_cm（压到比这还窄，字会被逼成竖排，那还不如让它折行）。
+    压不下去的（列太多）会把 min 一起等比降，并由调用方决定是否横排页面。
+    """
+    if not rows:
+        return []
+    cols = max(len(r) for r in rows)
+    size = size or prof['table']['size']
+    avail = body_width_pt(prof)
+    nat = []
+    for j in range(cols):
+        w = 0.0
+        for r in rows:
+            if j < len(r):
+                cell = str(r[j] if r[j] is not None else '')
+                w = max(w, max((measure(seg, size) for seg in cell.split('\n')), default=0.0))
+        nat.append(min(w + pad_pt, avail * 0.62))     # 单列上限 62% 版心，防一列吃掉整张表
+    total = sum(nat) or 1.0
+    if total <= avail:
+        # 有富余就把剩下的按自然宽比例摊回去，让表格铺满版心（半张表宽的表格很难看）
+        extra = avail - total
+        nat = [w + extra * (w / total) for w in nat]
+        return [round(w * PT_CM, 3) for w in nat]
+    floor_pt = min_col_cm * CM_PT
+    if floor_pt * cols > avail:
+        floor_pt = avail / cols * 0.8
+    slack = [max(w - floor_pt, 0.0) for w in nat]
+    over, slack_sum = total - avail, sum(slack)
+    if slack_sum <= 0:
+        return [round(avail / cols * PT_CM, 3)] * cols
+    ratio = min(over / slack_sum, 1.0)
+    out = [w - s * ratio for w, s in zip(nat, slack)]
+    scale = avail / sum(out) if sum(out) > avail else 1.0
+    return [round(w * scale * PT_CM, 3) for w in out]
+
+
+def est_table_height(rows, prof, widths_cm=None, size=None, cell_pad_pt=4.0):
+    """表格估算高度（磅）：逐格算折行数取每行最大。用于判断「这张表会不会顶出页底」。"""
+    if not rows:
+        return 0.0
+    size = size or prof['table']['size']
+    widths_cm = widths_cm or fit_table_widths(rows, prof, size)
+    lh = pt_of(size) * LINE_H
+    h = 0.0
+    for r in rows:
+        rows_lines = 1
+        for j, cell in enumerate(r):
+            w = (widths_cm[j] if j < len(widths_cm) else widths_cm[-1]) * CM_PT - cell_pad_pt * 2
+            rows_lines = max(rows_lines, wrap_count(str(cell or ''), size, max(w, pt_of(size))))
+        h += rows_lines * lh + cell_pad_pt * 2
+    return h
+
+
+# ── 图片 ───────────────────────────────────────────────────────────────────
+def image_box(px_w, px_h, prof, max_w_cm=None, max_h_cm=None, target_dpi=150):
+    """按原比例算插图显示尺寸（厘米）：先按 target_dpi 折算自然尺寸，超版心/超高再等比缩。
+
+    **不存在把图拉变形的写法**——宽高永远同一个 scale，这与 pptx 侧同一条纪律。
+    """
+    if not px_w or not px_h:
+        return (body_width_cm(prof) * 0.8, body_width_cm(prof) * 0.5)
+    max_w = max_w_cm or prof.get('max_image_cm') or body_width_cm(prof)
+    max_h = max_h_cm or (body_height_pt(prof) * PT_CM * 0.78)   # 留出题注与上下文
+    w_cm = px_w / float(target_dpi) * 2.54
+    h_cm = px_h / float(target_dpi) * 2.54
+    scale = min(max_w / w_cm, max_h / h_cm, 1.0)
+    return (round(w_cm * scale, 3), round(h_cm * scale, 3))
+
+
+def effective_dpi(px, length_cm):
+    """图片实际打印分辨率：像素数 ÷ 显示英寸。<120 在 A4 上肉眼可见发虚。"""
+    if not px or not length_cm:
+        return 0.0
+    return px / (length_cm / 2.54)
+
+
+# ── 标题编号 ───────────────────────────────────────────────────────────────
+_CN_DIGITS = '零一二三四五六七八九'
+
+
+def cn_num(n):
+    """1→一，11→十一，21→二十一（技术文档章节到不了三位数，够用）。"""
+    n = int(n)
+    if n <= 0:
+        return str(n)
+    if n < 10:
+        return _CN_DIGITS[n]
+    if n < 20:
+        return '十' + (_CN_DIGITS[n % 10] if n % 10 else '')
+    if n < 100:
+        return _CN_DIGITS[n // 10] + '十' + (_CN_DIGITS[n % 10] if n % 10 else '')
+    return str(n)
+
+
+def heading_number(prof, level, counters):
+    """按规范给出第 level 级标题的编号文本（counters 为 1..4 级计数器列表）。"""
+    style = prof.get('numbering', 'cn')
+    if style == 'none':
+        return ''
+    if style == 'decimal':
+        return '.'.join(str(counters[i]) for i in range(level)) + ' '
+    # cn：一、/（一）/1./（1）
+    if level == 1:
+        return f'{cn_num(counters[0])}、'
+    if level == 2:
+        return f'（{cn_num(counters[1])}）'
+    if level == 3:
+        return f'{counters[2]}.'
+    return f'（{counters[3]}）'
+
+
+# 体检端要能反过来认出这些编号，判断「编号连不连续」——正则与上面的生成规则同源。
+NUM_PATTERNS = [
+    ('cn1', re.compile(r'^\s*([一二三四五六七八九十]+)\s*[、.．]\s*')),
+    ('cn2', re.compile(r'^\s*[（(]\s*([一二三四五六七八九十]+)\s*[)）]\s*')),
+    ('ar1', re.compile(r'^\s*(\d+)\s*[、.．]\s*(?!\d)')),
+    ('ar2', re.compile(r'^\s*[（(]\s*(\d+)\s*[)）]\s*')),
+    ('dec', re.compile(r'^\s*(\d+(?:\.\d+)+)\s*[、.．]?\s+')),
+    ('chap', re.compile(r'^\s*第\s*([一二三四五六七八九十\d]+)\s*[章节部分篇]\s*')),
+]
+
+
+def parse_number(text):
+    """从标题文本里认出编号：返回 (kind, 序号元组, 去掉编号后的正文) 或 None。"""
+    s = str(text or '')
+    for kind, pat in NUM_PATTERNS:
+        m = pat.match(s)
+        if not m:
+            continue
+        raw = m.group(1)
+        if kind == 'dec':
+            try:
+                seq = tuple(int(x) for x in raw.split('.'))
+            except ValueError:
+                continue
+        elif raw.isdigit():
+            seq = (int(raw),)
+        else:
+            seq = (cn_to_int(raw),)
+            if seq[0] <= 0:
+                continue
+        return kind, seq, s[m.end():].strip()
+    return None
+
+
+def cn_to_int(s):
+    """一→1，十一→11，二十→20。认不出返回 0。"""
+    s = str(s or '').strip()
+    if not s:
+        return 0
+    if s.isdigit():
+        return int(s)
+    if '十' not in s:
+        return _CN_DIGITS.find(s[0]) if s[0] in _CN_DIGITS else 0
+    head, _, tail = s.partition('十')
+    h = _CN_DIGITS.find(head) if head else 1
+    t = _CN_DIGITS.find(tail) if tail else 0
+    if h < 0 or t < 0:
+        return 0
+    return h * 10 + t
+
+
+def caption_label(prof, kind, index, chapter=None):
+    """题注编号文本：图 3 / 图 2-3（按章编号）/ 表 1。"""
+    prefix = prof['fig_prefix'] if kind == 'fig' else prof['tab_prefix']
+    if prof.get('caption_by_chapter') and chapter:
+        return f'{prefix} {chapter}-{index}'
+    return f'{prefix} {index}'
+
+
+CAPTION_RE = re.compile(r'^\s*(图|表|Figure|Fig\.?|Table)\s*([0-9]+(?:[-–.][0-9]+)*)\s*[.、：:]?\s*(.*)$', re.I)
+REF_RE = re.compile(r'(?:如|见|参见|详见)?\s*(图|表)\s*([0-9]+(?:[-–.][0-9]+)*)\s*(?:所示|所列|中)?')
+
+
+def self_test():
+    p = profile('tech')
+    assert abs(body_width_cm(p) - 14.66) < 0.01, body_width_cm(p)
+    assert wrap_count('中' * 40, '小四', body_width_pt(p)) >= 1
+    assert wrap_count('中' * 200, '小四', body_width_pt(p)) > 4
+    assert pt_of('小四') == 12 and size_name(16) == '三号'
+    assert cn_num(21) == '二十一' and cn_to_int('二十一') == 21
+    assert parse_number('一、项目背景')[1] == (1,)
+    assert parse_number('1.2.3 技术路线')[1] == (1, 2, 3)
+    assert parse_number('（三）预期成果')[1] == (3,)
+    w = fit_table_widths([['指标', '2025 年实际完成情况说明', '备注'], ['交付率', '98.2%', '—']], p)
+    assert abs(sum(w) - body_width_cm(p)) < 0.05, (w, sum(w))
+    g = profile('gov')
+    assert pt_of(g['body']['size']) == 16 and g['body']['line_rule'] == 'exact'
+    assert image_box(1600, 900, p)[0] <= body_width_cm(p) + 1e-6
+    a = image_box(4000, 1000, p)
+    assert abs(a[0] / a[1] - 4.0) < 1e-6, a       # 等比，永不变形
+    print('[docx_layout] self-test OK ·',
+          f"版心 {body_width_cm(p):.2f}cm / 行高 {line_height_pt(p):.1f}pt / 缩进 {indent_pt(p):.0f}pt")
+
+
+if __name__ == '__main__':
+    self_test()