@huicai/cli 2026.814.0 → 2026.1021.0

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

@@ -0,0 +1,995 @@
+# Word 技术文档建版器：结构化 blocks / Markdown → 成品 docx。
+#
+# 与 pptx_deck 同一条纪律：**模型只给「这一节讲什么」，尺寸由引擎算**。
+# 人手写 python-docx 会犯的四类错，这里从写法上就不可能发生：
+#   · 中文字体只设 font.name 不设 w:eastAsia（换台电脑就变字体）→ _set_font 一次设齐三处；
+#   · 图片同时给宽和高把图拉变形 → 只给一个维度，另一维交给 Word 按原比例算；
+#   · 表格列宽拍脑袋，宽出版心右边一列被裁掉 → fit_table_widths 压进版心；
+#   · 首行缩进用全角空格顶（改字号就错位）→ 一律真缩进，且随字号走。
+#
+# 落盘后自动跑一遍 docx_check 体检，报告随返回值给出——「生成完就说做好了」是最常见的谎报。
+
+import datetime
+import json
+import os
+import re
+import sys
+
+from docx import Document
+from docx.enum.section import WD_ORIENT, WD_SECTION
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_BREAK, WD_LINE_SPACING
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Cm, Pt, RGBColor
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import docx_layout as L          # noqa: E402
+
+ALIGN = {'left': WD_ALIGN_PARAGRAPH.LEFT, 'center': WD_ALIGN_PARAGRAPH.CENTER,
+         'right': WD_ALIGN_PARAGRAPH.RIGHT, 'justify': WD_ALIGN_PARAGRAPH.JUSTIFY}
+
+
+def _set_font(obj, west, east, size=None, bold=None, color=None):
+    """把西文/东亚字体一次设齐。**只设 font.name 中文不生效**——这是 Word 生成脚本第一坑。"""
+    font = obj.font
+    font.name = west
+    el = obj.element if hasattr(obj, 'element') else obj._element
+    rpr = el.get_or_add_rPr() if hasattr(el, 'get_or_add_rPr') else el.rPr
+    rf = rpr.get_or_add_rFonts()
+    rf.set(qn('w:ascii'), west)
+    rf.set(qn('w:hAnsi'), west)
+    rf.set(qn('w:eastAsia'), east)
+    if size is not None:
+        font.size = Pt(L.pt_of(size))
+    if bold is not None:
+        font.bold = bold
+    if color is not None:
+        font.color.rgb = RGBColor(*color)
+
+
+def _field(run, instr, placeholder=''):
+    """插入 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 _para_fmt(para, style, prof):
+    pf = para.paragraph_format
+    rule = style.get('line_rule', prof['body'].get('line_rule', 'multiple'))
+    val = style.get('line', prof['body'].get('line', 1.5))
+    if rule == 'exact':
+        pf.line_spacing_rule = WD_LINE_SPACING.EXACTLY
+        pf.line_spacing = Pt(float(val))
+    else:
+        pf.line_spacing_rule = WD_LINE_SPACING.MULTIPLE
+        pf.line_spacing = float(val)
+    pf.space_before = Pt(float(style.get('space_before', 0)))
+    pf.space_after = Pt(float(style.get('space_after', 0)))
+    ind = style.get('first_indent_chars', 0)
+    pf.first_line_indent = Pt(L.pt_of(style.get('size', prof['body']['size'])) * ind) if ind else Pt(0)
+    para.alignment = ALIGN.get(style.get('align', 'justify'), WD_ALIGN_PARAGRAPH.JUSTIFY)
+    pf.widow_control = True          # 防孤行寡行：一段的最后一行不落单在下一页页首
+
+
+BOLD_RE = re.compile(r'\*\*(.+?)\*\*')
+
+
+def _runs(para, text, style, prof):
+    """按 **粗体** 拆 run，每个 run 都设齐字体（漏一个 run 就漏一处中文字体）。"""
+    east = style.get('east', prof['body']['east'])
+    west = style.get('west', prof['body']['west'])
+    size = style.get('size', prof['body']['size'])
+    base_bold = style.get('bold', False)
+    for i, seg in enumerate(BOLD_RE.split(str(text or ''))):
+        if not seg:
+            continue
+        r = para.add_run(seg)
+        _set_font(r, west, east, size, base_bold or (i % 2 == 1))
+    if not para.runs:
+        r = para.add_run('')
+        _set_font(r, west, east, size, base_bold)
+
+
+class DocBuilder:
+    """技术文档建版器。所有尺寸走 docx_layout，调用方不需要（也不应该）自己算。"""
+
+    def __init__(self, profile='tech', *, numbering=None, caption_by_chapter=None):
+        self.prof = L.profile(profile)
+        if numbering:
+            self.prof['numbering'] = numbering
+        if caption_by_chapter is not None:
+            self.prof['caption_by_chapter'] = caption_by_chapter
+        self.doc = Document()
+        self.counters = [0, 0, 0, 0]
+        self.fig_n, self.tab_n = 0, 0
+        self.fig_by_chap, self.tab_by_chap = {}, {}
+        self.labels = []          # [(图/表, '图 1', 题注)]——正文引用要和它对得上
+        self.warnings = []
+        self.body_started = False
+        self._setup()
+
+    # ── 页面与样式 ────────────────────────────────────────────────────────
+    def _setup(self):
+        p, s = self.prof, self.doc.sections[0]
+        s.page_width, s.page_height = Cm(p['page_w_cm']), Cm(p['page_h_cm'])
+        m = p['margin_cm']
+        s.left_margin, s.right_margin = Cm(m['left']), Cm(m['right'])
+        s.top_margin, s.bottom_margin = Cm(m['top']), Cm(m['bottom'])
+        st = self.doc.styles
+        _set_font(st['Normal'], p['body']['west'], p['body']['east'], p['body']['size'])
+        _para_fmt_style(st['Normal'], p['body'], p)
+        for i, h in enumerate(p['headings'][:4], start=1):
+            name = f'Heading {i}'
+            if name not in [x.name for x in st]:
+                continue
+            style = st[name]
+            _set_font(style, h.get('west', p['body']['west']), h['east'], h['size'], h.get('bold', False))
+            style.font.color.rgb = RGBColor(0, 0, 0)     # Word 默认标题是蓝色，中文正式文档要黑
+            _para_fmt_style(style, h, p)
+        for name, spec in (('Caption图表题注', p['caption']),):
+            try:
+                cs = st.add_style(name, 1)               # 1 = WD_STYLE_TYPE.PARAGRAPH
+                _set_font(cs, spec.get('west', p['body']['west']), spec['east'], spec['size'])
+                _para_fmt_style(cs, spec, p)
+            except Exception:
+                pass
+
+    def body_width_cm(self):
+        return L.body_width_cm(self.prof)
+
+    # ── 封面 / 目录 / 页眉页脚 ────────────────────────────────────────────
+    def add_cover(self, title, subtitle='', org='', author='', date=None, doc_no='',
+                  fields=None, fields_as_table=False):
+        """封面。fields = [['项目名称','…'],['编制单位','…']] 会排成对齐的信息栏。
+
+        fields_as_table=True 时排成**无框线两列表**——正式归档件的封面信息栏历来是表格，
+        而且只有表格形态才能被工具按「键→值」读出来核对（写成居中段落，
+        跨文档一致性检查就形同虚设：读不到字段，自然永远「没有不一致」）。"""
+        p = self.prof
+        if doc_no:
+            r = self._blank(0)
+            r.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+            _runs(r, doc_no, {**p['body'], 'size': '四号', 'first_indent_chars': 0, 'align': 'right'}, p)
+        for _ in range(4 if doc_no else 5):
+            self._blank()
+        t = self.doc.add_paragraph()
+        t.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        _runs(t, title, {'east': '黑体', 'west': p['body']['west'], 'size': '小初',
+                         'bold': False, 'align': 'center'}, p)
+        t.paragraph_format.space_after = Pt(18)
+        t.paragraph_format.first_line_indent = Pt(0)
+        if subtitle:
+            s = self.doc.add_paragraph()
+            s.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            _runs(s, subtitle, {'east': '楷体', 'west': p['body']['west'], 'size': '三号', 'align': 'center'}, p)
+            s.paragraph_format.first_line_indent = Pt(0)
+        for _ in range(4):
+            self._blank()
+        rows = list(fields or [])
+        if org and not any(k in ('编制单位', '单位') for k, _ in rows):
+            rows.append(['编制单位', org])
+        if author and not any(k == '编制人' for k, _ in rows):
+            rows.append(['编制人', author])
+        today = datetime.date.today()
+        # 用「编制时间」而不是「编制日期」：真实模板体例是前者，
+        # 两边用词不一致会让档案体检提取不到这个字段（提取不到就等于永远没问题）。
+        rows.append(['编制时间', date or f'{today.year} 年 {today.month} 月 {today.day} 日'])
+        if fields_as_table and rows:
+            tb = self.doc.add_table(rows=len(rows), cols=2)
+            tb.alignment = WD_TABLE_ALIGNMENT.CENTER
+            tb.autofit = False
+            for i, (k, v) in enumerate(rows):
+                for j, (val, w, align) in enumerate(((f'{k}：', 4.2, 'right'),
+                                                     (str(v), 8.0, 'left'))):
+                    cell = tb.cell(i, j)
+                    cell.width = Cm(w)
+                    par = cell.paragraphs[0]
+                    par.alignment = ALIGN[align]
+                    par.paragraph_format.first_line_indent = Pt(0)
+                    par.paragraph_format.space_before = par.paragraph_format.space_after = Pt(3)
+                    _runs(par, val, {**p['body'], 'size': '四号', 'first_indent_chars': 0}, p)
+                    _vcenter(cell)
+            _no_borders(tb)
+            grid = tb._tbl.tblGrid
+            if grid is not None:
+                for gc, w in zip(grid.findall(qn('w:gridCol')), (4.2, 8.0)):
+                    gc.set(qn('w:w'), str(int(w * L.CM_PT * 20)))
+        else:
+            for k, v in rows:
+                line = self.doc.add_paragraph()
+                line.alignment = WD_ALIGN_PARAGRAPH.CENTER
+                line.paragraph_format.first_line_indent = Pt(0)
+                line.paragraph_format.space_after = Pt(6)
+                _runs(line, f'{_pad(k)}：{v}', {'east': p['body']['east'], 'west': p['body']['west'],
+                                               'size': '四号', 'align': 'center'}, p)
+        self.add_page_break()
+        return self
+
+    def add_toc(self, title='目 录', levels=None):
+        h = self.doc.add_paragraph()
+        h.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        h.paragraph_format.first_line_indent = Pt(0)
+        h.paragraph_format.space_after = Pt(12)
+        _runs(h, title, {'east': '黑体', 'west': self.prof['body']['west'], 'size': '三号', 'align': 'center'}, self.prof)
+        n = levels or self.prof.get('toc_levels', 3)
+        para = self.doc.add_paragraph()
+        para.paragraph_format.first_line_indent = Pt(0)
+        _field(para.add_run(), f'TOC \\o "1-{n}" \\h \\z \\u', '（右键→更新域，或按 F9 生成目录）')
+        self.add_page_break()
+        return self
+
+    def start_body(self, restart_page_numbers=True):
+        """正文另起一节：页码从 1 重新起算（封面与目录不计页）。正式交付件的标配。"""
+        sec = self.doc.add_section(WD_SECTION.NEW_PAGE)
+        p, m = self.prof, self.prof['margin_cm']
+        sec.page_width, sec.page_height = Cm(p['page_w_cm']), Cm(p['page_h_cm'])
+        sec.left_margin, sec.right_margin = Cm(m['left']), Cm(m['right'])
+        sec.top_margin, sec.bottom_margin = Cm(m['top']), Cm(m['bottom'])
+        if restart_page_numbers:
+            pg = OxmlElement('w:pgNumType')
+            pg.set(qn('w:start'), '1')
+            sec._sectPr.append(pg)
+        self.body_started = True
+        return self
+
+    def set_header_footer(self, header='', footer='', page_numbers=True, all_sections=True):
+        secs = self.doc.sections if all_sections else self.doc.sections[-1:]
+        for i, sec in enumerate(secs):
+            if i:
+                sec.header.is_linked_to_previous = False
+                sec.footer.is_linked_to_previous = False
+            if header:
+                hp = sec.header.paragraphs[0]
+                hp.alignment = WD_ALIGN_PARAGRAPH.CENTER
+                hp.paragraph_format.first_line_indent = Pt(0)
+                for r in list(hp.runs):
+                    r.text = ''
+                _runs(hp, header, {'east': self.prof['body']['east'], 'west': self.prof['body']['west'],
+                                   'size': '五号', 'align': 'center'}, self.prof)
+                _bottom_border(hp)
+            fp = sec.footer.paragraphs[0]
+            fp.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            fp.paragraph_format.first_line_indent = Pt(0)
+            for r in list(fp.runs):
+                r.text = ''
+            if footer:
+                _runs(fp, footer + ('　　' if page_numbers else ''),
+                      {'east': self.prof['body']['east'], 'west': self.prof['body']['west'],
+                       'size': '五号', 'align': 'center'}, self.prof)
+            if page_numbers:
+                for txt, instr in (('第 ', None), (None, 'PAGE'), (' 页 共 ', None), (None, 'NUMPAGES'), (' 页', None)):
+                    r = fp.add_run(txt or '')
+                    _set_font(r, self.prof['body']['west'], self.prof['body']['east'], '五号')
+                    if instr:
+                        _field(r, instr, '1')
+        return self
+
+    # ── 内容块 ────────────────────────────────────────────────────────────
+    def add_heading(self, text, level=1, numbered=None):
+        level = max(1, min(int(level), 4))
+        text = str(text or '').strip()
+        auto = self.prof.get('numbering', 'cn') != 'none' if numbered is None else numbered
+        if auto and L.parse_number(text):
+            auto = False                       # 文本自带编号就不再叠一层
+        if auto:
+            self.counters[level - 1] += 1
+            for i in range(level, 4):
+                self.counters[i] = 0
+            text = L.heading_number(self.prof, level, self.counters) + text
+        elif level == 1:
+            self.counters[0] += 1
+            for i in range(1, 4):
+                self.counters[i] = 0
+        para = self.doc.add_paragraph(style=f'Heading {level}')
+        st = self.prof['headings'][level - 1]
+        _para_fmt(para, {**st, 'first_indent_chars': 0}, self.prof)
+        _runs(para, text, st, self.prof)
+        para.paragraph_format.keep_with_next = True     # 标题不落单在页底
+        return self
+
+    def add_para(self, text, style=None, indent=True):
+        para = self.doc.add_paragraph()
+        st = {**self.prof['body'], **(style or {})}
+        if not indent:
+            st = {**st, 'first_indent_chars': 0}
+        _para_fmt(para, st, self.prof)
+        _runs(para, text, st, self.prof)
+        return self
+
+    def add_bullets(self, items, ordered=False, level=0):
+        for i, it in enumerate(items, 1):
+            text, subs = (it, []) if not isinstance(it, dict) else (it.get('text', ''), it.get('sub', []))
+            mark = f'{i}.' if ordered else '·'
+            para = self.doc.add_paragraph()
+            st = {**self.prof['body'], 'first_indent_chars': 0}
+            _para_fmt(para, st, self.prof)
+            para.paragraph_format.left_indent = Pt(L.pt_of(st['size']) * (2 + level * 2))
+            para.paragraph_format.first_line_indent = Pt(-L.pt_of(st['size']) * (1 if ordered else 1))
+            _runs(para, f'{mark} {text}', st, self.prof)
+            for s in subs:
+                self.add_bullets([s], ordered=False, level=level + 1)
+        return self
+
+    def add_table(self, rows, caption='', note='', header=True, style='grid', align='center'):
+        """表格：列宽按内容算并压进版心，表头加粗+跨页重复，题注排在表**上方**（中文出版惯例）。"""
+        rows = [[('' if c is None else str(c)) for c in r] for r in rows if r is not None]
+        if not rows:
+            return self
+        cols = max(len(r) for r in rows)
+        rows = [r + [''] * (cols - len(r)) for r in rows]
+        if caption:
+            self.tab_n += 1
+            ch = self.counters[0] if self.prof.get('caption_by_chapter') else None
+            lab = L.caption_label(self.prof, 'tab', self._cap_idx('tab'), ch)
+            self.labels.append(('表', lab, caption))
+            self.last_label = lab
+            self._caption(f'{lab}  {caption}')
+        tb = self.doc.add_table(rows=len(rows), cols=cols)
+        tb.alignment = WD_TABLE_ALIGNMENT.CENTER
+        tb.autofit = False
+        try:
+            tb.style = 'Table Grid'
+        except Exception:
+            pass
+        widths = L.fit_table_widths(rows, self.prof, self.prof['table']['size'])
+        tspec = self.prof['table']
+        for i, row in enumerate(rows):
+            for j, val in enumerate(row):
+                cell = tb.cell(i, j)
+                cell.width = Cm(widths[j])
+                par = cell.paragraphs[0]
+                par.alignment = ALIGN.get(tspec.get('align', 'center') if (i == 0 or j == 0) else 'left',
+                                          WD_ALIGN_PARAGRAPH.LEFT)
+                pf = par.paragraph_format
+                pf.first_line_indent = Pt(0)
+                pf.space_before, pf.space_after = Pt(1.5), Pt(1.5)
+                pf.line_spacing_rule = WD_LINE_SPACING.SINGLE
+                _runs(par, val, {**tspec, 'bold': bool(header and i == 0 and tspec.get('head_bold', True))}, self.prof)
+                _vcenter(cell)
+        grid = tb._tbl.tblGrid
+        if grid is not None:
+            for gc, w in zip(grid.findall(qn('w:gridCol')), widths):
+                gc.set(qn('w:w'), str(int(w * L.CM_PT * 20)))
+        if header and len(rows) > 1:
+            trpr = tb.rows[0]._tr.get_or_add_trPr()
+            th = OxmlElement('w:tblHeader')
+            th.set(qn('w:val'), 'true')
+            trpr.append(th)
+        if style == 'three-line':
+            _three_line(tb)
+        h = L.est_table_height(rows, self.prof, widths, self.prof['table']['size'])
+        if h > L.body_height_pt(self.prof) * 0.92:
+            self.warnings.append(f'表「{caption or rows[0][0]}」估算高 {h/L.CM_PT:.1f}cm 会跨页，'
+                                 f'已设跨页重复标题行；行数很多时建议拆表或改附件')
+        if note:
+            self._caption(f'注：{note}', align='left')
+        self.doc.add_paragraph().paragraph_format.space_after = Pt(0)
+        return self
+
+    def _new_section(self, landscape):
+        """另起一节并定方向（横排插图用）。页码接续；页眉页脚在 set_header_footer 里统一套到每一节。"""
+        p, m = self.prof, self.prof['margin_cm']
+        sec = self.doc.add_section(WD_SECTION.NEW_PAGE)
+        W, H = Cm(p['page_w_cm']), Cm(p['page_h_cm'])
+        sec.orientation = WD_ORIENT.LANDSCAPE if landscape else WD_ORIENT.PORTRAIT
+        sec.page_width, sec.page_height = (H, W) if landscape else (W, H)
+        sec.left_margin, sec.right_margin = Cm(m['left']), Cm(m['right'])
+        sec.top_margin, sec.bottom_margin = Cm(m['top']), Cm(m['bottom'])
+        return sec
+
+    def add_figure(self, image, caption='', width_cm=None, note='', landscape=False):
+        """插图：**只给一个维度**，另一维由 Word 按原比例算——从写法上杜绝变形。
+        landscape=True：图单独占一个横排页（版心宽 23.4cm），前后自动切回纵向——大架构图放纵向版心里字会小到看不清。"""
+        path = str(image)
+        if not os.path.exists(path):
+            self.warnings.append(f'插图不存在：{path}（已在正文留占位提示）')
+            self.add_para(f'［插图缺失：{path}］', {'align': 'center', 'size': '五号'}, indent=False)
+            return self
+        if landscape:
+            p, m = self.prof, self.prof['margin_cm']
+            self._new_section(True)
+            width_cm = width_cm or (p['page_h_cm'] - m['left'] - m['right'])
+            self._landscape_max_h = (p['page_w_cm'] - m['top'] - m['bottom']) * 0.82
+            try:
+                return self._add_figure_body(path, caption, width_cm, note)
+            finally:
+                self._landscape_max_h = None
+                self._new_section(False)
+        return self._add_figure_body(path, caption, width_cm, note)
+
+    def _legibility(self, path, w_cm):
+        """同名 SVG（render_diagram / render_chart 都会出）里的字号 × 插入后的缩放 = 纸上的实际字号。"""
+        svg = os.path.splitext(path)[0] + '.svg'
+        if not os.path.exists(svg):
+            return None
+        try:
+            text = open(svg, encoding='utf-8', errors='replace').read(4_000_000)
+        except OSError:
+            return None
+        m = re.search(r'viewBox="\s*[-\d.]+\s+[-\d.]+\s+([\d.]+)\s+[\d.]+', text)
+        sizes = sorted(float(x) for x in re.findall(r'font-size="([\d.]+)(?:px|pt)?"', text) if float(x) > 0)
+        if not m or not sizes:
+            return None                                   # matplotlib 的 SVG 把字转成了路径：按版心出的图本就不用查
+        k = (w_cm / 2.54 * 72) / float(m.group(1))
+        return sizes[0] * k, sizes[len(sizes) // 2] * k
+
+    def _add_figure_body(self, path, caption, width_cm, note):
+        px_w = px_h = 0
+        try:
+            from docx.image.image import Image as DocxImage
+            img = DocxImage.from_file(path)
+            px_w, px_h, dpi = img.px_width, img.px_height, img.horz_dpi or 96
+        except Exception as e:
+            self.warnings.append(f'插图无法解析：{path}（{e}）')
+            dpi = 96
+        w_cm, h_cm = L.image_box(px_w, px_h, self.prof, max_w_cm=width_cm, target_dpi=max(dpi, 96),
+                                 max_h_cm=getattr(self, '_landscape_max_h', None))
+        para = self.doc.add_paragraph()
+        para.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        para.paragraph_format.first_line_indent = Pt(0)
+        para.paragraph_format.space_before = Pt(6)
+        para.paragraph_format.space_after = Pt(3)
+        run = para.add_run()
+        max_h = L.body_height_pt(self.prof) * L.PT_CM * 0.8
+        try:
+            if h_cm <= max_h:
+                run.add_picture(path, width=Cm(w_cm))       # 只给宽 → 高度自动等比
+            else:
+                run.add_picture(path, height=Cm(max_h))     # 只给高 → 宽度自动等比
+        except Exception as e:
+            self.warnings.append(f'插图插入失败：{path}（{e}）')
+            _runs(para, f'［插图失败：{os.path.basename(path)}］', {**self.prof['body'], 'size': '五号'}, self.prof)
+            return self
+        leg = self._legibility(path, w_cm)
+        if leg and leg[0] < 5.5:
+            name = os.path.basename(path)
+            if getattr(self, '_landscape_max_h', None):
+                self.warnings.append(f'插图 {name} 横排插入后图中最小字号仍只有约 {leg[0]:.1f} 磅、多数文字约 {leg[1]:.1f} 磅，'
+                                     f'打印看不清：这张图对纸面来说太密，精简节点或拆成两张')
+            else:
+                # 横排后能放多大：与横排插入时同一套尺寸算法（竖长的图横排反而更小，就别建议了）
+                p_, m_ = self.prof, self.prof['margin_cm']
+                w_land, _h = L.image_box(px_w, px_h, p_, max_w_cm=p_['page_h_cm'] - m_['left'] - m_['right'],
+                                         max_h_cm=(p_['page_w_cm'] - m_['top'] - m_['bottom']) * 0.82,
+                                         target_dpi=max(dpi, 96))
+                land = leg[0] * (w_land / w_cm) if w_cm else 0
+                tail = (f'；实在要整张放就横排插入——Markdown 写 ![图题](图){{#fig:x .landscape}}，横排后最小约 {land:.1f} 磅'
+                        if land > leg[0] + 0.5 else '（这张图竖长，横排也放不大）')
+                self.warnings.append(f'插图 {name} 按版心宽插入后，图中最小字号约 {leg[0]:.1f} 磅、多数文字约 {leg[1]:.1f} 磅，'
+                                     f'打印看不清（正文插图要 ≥5.5 磅）：精简节点或拆成两张重画' + tail)
+        dpi_eff = L.effective_dpi(px_w, w_cm) if px_w else 0
+        if dpi_eff and dpi_eff < 120:
+            self.warnings.append(f'插图 {os.path.basename(path)} 有效分辨率仅 {dpi_eff:.0f}dpi，'
+                                 f'打印会发虚（建议用 render_diagram 出矢量或提高导出分辨率）')
+        if caption:
+            self.fig_n += 1
+            ch = self.counters[0] if self.prof.get('caption_by_chapter') else None
+            lab = L.caption_label(self.prof, 'fig', self._cap_idx('fig'), ch)
+            self.labels.append(('图', lab, caption))
+            self.last_label = lab
+            self._caption(f'{lab}  {caption}')
+        if note:
+            self._caption(f'注：{note}', align='left')
+        return self
+
+    def resolve_refs(self, refs):
+        """把正文里的 @fig:xxx / @tbl:xxx 换成真实题注编号（图 3-1 / 表 5）。
+
+        编号由引擎按版式算（按章或全文连续），模型写「如图 3-2 所示」时要自己数——
+        插一张图、挪一节，后面的引用就全错了，而且「引用了一个存在但不对的图」体检查不出来。
+        标签引用把这件事交还给引擎：写的是「哪张图」，编号永远对。"""
+        missing = []
+
+        def sub(m):
+            key = m.group(1)
+            if key in refs:
+                return refs[key]
+            missing.append('@' + key)
+            return m.group(0)
+
+        paras = list(self.doc.paragraphs)
+        for t in self.doc.tables:
+            for row in t.rows:
+                for cell in row.cells:
+                    paras.extend(cell.paragraphs)
+        for para in paras:
+            if '@fig:' not in para.text and '@tbl:' not in para.text:
+                continue
+            for run in para.runs:
+                if '@' in run.text:
+                    run.text = XREF_RE.sub(sub, run.text)
+            if XREF_RE.search(para.text) and para.runs:      # 标签被加粗等格式拆进了两个 run：合并后再换
+                full = XREF_RE.sub(sub, para.text)
+                for r in para.runs[1:]:
+                    r.text = ''
+                para.runs[0].text = full
+        for k in dict.fromkeys(missing):
+            self.warnings.append(f'引用了不存在的图表标签 {k}：检查对应图/表题注末尾是否写了 {{#{k[1:]}}}')
+
+    def add_kv_table(self, pairs, caption='', label_cm=4.0):
+        """表单式两列表（验收申请表、任务书封面信息栏这类）。左列固定宽、右列吃满剩余。"""
+        rows = [[str(k), str(v)] for k, v in pairs]
+        if caption:
+            self.tab_n += 1
+            self.last_label = L.caption_label(self.prof, "tab", self._cap_idx("tab"), None)
+            self._caption(f'{self.last_label}  {caption}')
+        tb = self.doc.add_table(rows=len(rows), cols=2)
+        tb.alignment = WD_TABLE_ALIGNMENT.CENTER
+        tb.autofit = False
+        try:
+            tb.style = 'Table Grid'
+        except Exception:
+            pass
+        right = self.body_width_cm() - label_cm
+        for i, (k, v) in enumerate(rows):
+            for j, (val, w, bold) in enumerate(((k, label_cm, True), (v, right, False))):
+                cell = tb.cell(i, j)
+                cell.width = Cm(w)
+                par = cell.paragraphs[0]
+                par.alignment = WD_ALIGN_PARAGRAPH.CENTER if j == 0 else WD_ALIGN_PARAGRAPH.LEFT
+                par.paragraph_format.first_line_indent = Pt(0)
+                par.paragraph_format.space_before = par.paragraph_format.space_after = Pt(2)
+                _runs(par, val, {**self.prof['table'], 'size': self.prof['body']['size'], 'bold': bold}, self.prof)
+                _vcenter(cell)
+        grid = tb._tbl.tblGrid
+        if grid is not None:
+            for gc, w in zip(grid.findall(qn('w:gridCol')), (label_cm, right)):
+                gc.set(qn('w:w'), str(int(w * L.CM_PT * 20)))
+        self.doc.add_paragraph().paragraph_format.space_after = Pt(0)
+        return self
+
+    def add_signature(self, roles=('编制', '审核', '批准'), org='', date=True):
+        """签字栏：右对齐的「编制：____　审核：____」+ 落款单位与日期。"""
+        for _ in range(2):
+            self._blank()
+        line = self.doc.add_paragraph()
+        line.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+        line.paragraph_format.first_line_indent = Pt(0)
+        _runs(line, '　　'.join(f'{r}：{"_" * 8}' for r in roles), self.prof['body'], self.prof)
+        if org:
+            o = self.doc.add_paragraph()
+            o.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+            o.paragraph_format.first_line_indent = Pt(0)
+            _runs(o, org, {**self.prof['body'], 'align': 'right'}, self.prof)
+        if date:
+            d = self.doc.add_paragraph()
+            d.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+            d.paragraph_format.first_line_indent = Pt(0)
+            _t = datetime.date.today()
+            _runs(d, f'{_t.year} 年 {_t.month} 月 {_t.day} 日',
+                  {**self.prof['body'], 'align': 'right'}, self.prof)
+        return self
+
+    def add_page_break(self):
+        p = self.doc.add_paragraph()
+        p.paragraph_format.first_line_indent = Pt(0)
+        p.add_run().add_break(WD_BREAK.PAGE)
+        return self
+
+    # ── 内部 ──────────────────────────────────────────────────────────────
+    def _cap_idx(self, kind):
+        if not self.prof.get('caption_by_chapter'):
+            return self.fig_n if kind == 'fig' else self.tab_n
+        ch = self.counters[0] or 1
+        d = self.fig_by_chap if kind == 'fig' else self.tab_by_chap
+        d[ch] = d.get(ch, 0) + 1
+        return d[ch]
+
+    def _caption(self, text, align='center'):
+        para = self.doc.add_paragraph()
+        st = {**self.prof['caption'], 'align': align, 'first_indent_chars': 0}
+        _para_fmt(para, st, self.prof)
+        _runs(para, text, st, self.prof)
+        para.paragraph_format.keep_with_next = (align == 'center')
+        return para
+
+    def _blank(self, size=None):
+        p = self.doc.add_paragraph()
+        p.paragraph_format.first_line_indent = Pt(0)
+        p.paragraph_format.space_after = Pt(0)
+        if size is not None:
+            p.paragraph_format.line_spacing = 1.0
+        return p
+
+    def save(self, path, inspect=True):
+        self.doc.save(path)
+        res = None
+        if inspect:
+            try:
+                import docx_check
+                res = docx_check.inspect(path, self.prof['name'])
+            except Exception as e:
+                self.warnings.append(f'体检未能运行：{e}')
+        return path, res
+
+
+def _para_fmt_style(style, spec, prof):
+    pf = style.paragraph_format
+    rule = spec.get('line_rule', prof['body'].get('line_rule', 'multiple'))
+    val = spec.get('line', prof['body'].get('line', 1.5))
+    if rule == 'exact':
+        pf.line_spacing_rule = WD_LINE_SPACING.EXACTLY
+        pf.line_spacing = Pt(float(val))
+    else:
+        pf.line_spacing_rule = WD_LINE_SPACING.MULTIPLE
+        pf.line_spacing = float(val)
+    pf.space_before = Pt(float(spec.get('space_before', 0)))
+    pf.space_after = Pt(float(spec.get('space_after', 0)))
+    ind = spec.get('first_indent_chars', 0)
+    pf.first_line_indent = Pt(L.pt_of(spec.get('size', prof['body']['size'])) * ind) if ind else Pt(0)
+    if spec.get('align'):
+        style.paragraph_format.alignment = ALIGN.get(spec['align'])
+
+
+def _pad(s, width=5):
+    """封面信息栏标签右对齐到统一宽度，让冒号成一条竖线。
+
+    **必须左填充**：右填充会写出「编制单位　：」——全角空格顶在冒号前面，
+    这是标点前留白，中文排版里属于硬伤（本项目的 docx_check 会直接判「标点前多了空格」）。"""
+    s = str(s)
+    return '　' * max(0, width - len(s)) + s
+
+
+def _vcenter(cell):
+    tcPr = cell._tc.get_or_add_tcPr()
+    va = OxmlElement('w:vAlign')
+    va.set(qn('w:val'), 'center')
+    tcPr.append(va)
+
+
+def _bottom_border(para):
+    pPr = para._p.get_or_add_pPr()
+    bd = OxmlElement('w:pBdr')
+    b = OxmlElement('w:bottom')
+    for k, v in (('w:val', 'single'), ('w:sz', '6'), ('w:space', '1'), ('w:color', '808080')):
+        b.set(qn(k), v)
+    bd.append(b)
+    pPr.append(bd)
+
+
+def _no_borders(tb):
+    """去掉全部框线（封面信息栏用）。"""
+    for row in tb.rows:
+        for cell in row.cells:
+            tcPr = cell._tc.get_or_add_tcPr()
+            bd = OxmlElement('w:tcBorders')
+            for edge in ('top', 'bottom', 'left', 'right'):
+                e = OxmlElement(f'w:{edge}')
+                e.set(qn('w:val'), 'none')
+                e.set(qn('w:sz'), '0')
+                bd.append(e)
+            tcPr.append(bd)
+
+
+def _three_line(tb):
+    """三线表：只留顶线、表头下线、底线，去掉所有竖线与中间横线（科技报告惯例）。"""
+    n = len(tb.rows)
+    for i, row in enumerate(tb.rows):
+        for cell in row.cells:
+            tcPr = cell._tc.get_or_add_tcPr()
+            for old in tcPr.findall(qn('w:tcBorders')):
+                tcPr.remove(old)
+            bd = OxmlElement('w:tcBorders')
+            for edge, on, sz in (('top', i == 0, '12'), ('bottom', i in (0, n - 1), '12' if i == n - 1 else '6'),
+                                 ('left', False, '0'), ('right', False, '0')):
+                e = OxmlElement(f'w:{edge}')
+                e.set(qn('w:val'), 'single' if on else 'none')
+                e.set(qn('w:sz'), sz if on else '0')
+                e.set(qn('w:color'), '000000')
+                bd.append(e)
+            tcPr.append(bd)
+
+
+# 交叉引用：题注末尾写 {#fig:arch} / {#tbl:invest}，正文写 @fig:arch / @tbl:invest，成稿时换成真实编号。
+# id 只许 ASCII——允许中文的话「@fig:arch所示」会把「所示」也吃进 id。
+XREF_ID_RE = re.compile(r'\s*\{#((?:fig|tbl):[A-Za-z0-9_\-]+)\}\s*$')
+# 前面顺手多写了「图 / 表」（「如图 @fig:x 所示」）也要认：一并吃掉，免得成稿变成「如图 图 3-1 所示」
+XREF_RE = re.compile(r'(?:[图表]\s*)?@((?:fig|tbl):[A-Za-z0-9_\-]+)')
+
+
+def _split_xref(caption):
+    m = XREF_ID_RE.search(caption or '')
+    return (caption[:m.start()].rstrip(), m.group(1)) if m else (caption or '', None)
+
+
+# ── Markdown → blocks ──────────────────────────────────────────────────────
+def md_to_blocks(md_text):
+    """Markdown 中转的解析端。约定：#/##/### 标题、- 列表、1. 有序、| 表格、![题注](图) 插图、
+    > 引注、--- 分页、普通行=正文段落。表格上一行若是 `表：xxx` 则作为题注。"""
+    # 吃掉 BOM：Windows 编辑器保存的 .md 常带 \ufeff，留着会让首行的 `# 标题`
+    # 变成 `\ufeff# 标题`，标题正则匹配不上，整份文档的第一个标题就此消失。
+    md_text = str(md_text or '').lstrip('\ufeff')
+    blocks, tbuf, lbuf, obuf, pending_cap = [], [], [], [], ''
+
+    def flush_list():
+        nonlocal lbuf, obuf
+        if lbuf:
+            blocks.append({'type': 'bullets', 'items': lbuf})
+            lbuf = []
+        if obuf:
+            blocks.append({'type': 'ordered', 'items': obuf})
+            obuf = []
+
+    def flush_table():
+        nonlocal tbuf, pending_cap
+        if not tbuf:
+            return
+        cells = [[c.strip() for c in r.strip().strip('|').split('|')] for r in tbuf]
+        cells = [r for r in cells if not all(re.fullmatch(r':?-{2,}:?', c or '---') for c in r)]
+        if cells:
+            blocks.append({'type': 'table', 'rows': cells, 'caption': pending_cap})
+        tbuf, pending_cap = [], ''
+
+    for raw in str(md_text).splitlines() + ['']:
+        s = raw.rstrip()
+        if s.lstrip().startswith('|'):
+            flush_list()
+            tbuf.append(s)
+            continue
+        flush_table()
+        if not s.strip():
+            flush_list()
+            continue
+        m = re.match(r'^(#{1,4})\s+(.*)', s)
+        if m:
+            flush_list()
+            blocks.append({'type': f'h{len(m.group(1))}', 'text': m.group(2).strip()})
+            continue
+        img = re.match(r'^\s*!\[(.*?)\]\(([^)]+)\)\s*(\{[^}]*\})?\s*$', s)
+        if img:
+            flush_list()
+            # pandoc 属性块：{#fig:x .landscape}——#id 作交叉引用标签，.landscape 表示横排插入
+            attrs = (img.group(3) or '').strip('{} ').split()
+            rid = next((a[1:] for a in attrs if a.startswith('#')), '')
+            cap = img.group(1).strip() + (f' {{#{rid}}}' if rid else '')
+            blk = {'type': 'figure', 'image': img.group(2).strip(), 'caption': cap}
+            if '.landscape' in attrs:
+                blk['landscape'] = True
+            blocks.append(blk)
+            continue
+        if re.match(r'^\s*(---|\*\*\*|===)\s*$', s):
+            flush_list()
+            blocks.append({'type': 'pagebreak'})
+            continue
+        cap = re.match(r'^\s*表\s*[:：]\s*(.+)$', s)
+        if cap:
+            flush_list()
+            pending_cap = cap.group(1).strip()
+            continue
+        if re.match(r'^\s*[-*+]\s+', s):
+            if obuf:
+                flush_list()
+            lbuf.append(re.sub(r'^\s*[-*+]\s+', '', s))
+            continue
+        if re.match(r'^\s*\d+[.、]\s*', s):
+            if lbuf:
+                flush_list()
+            obuf.append(re.sub(r'^\s*\d+[.、]\s*', '', s))
+            continue
+        if s.lstrip().startswith('>'):
+            flush_list()
+            blocks.append({'type': 'note', 'text': s.lstrip('> ').strip()})
+            continue
+        flush_list()
+        blocks.append({'type': 'p', 'text': s.strip()})
+    flush_table()
+    flush_list()
+    return blocks
+
+
+def _load_templates():
+    """按需取 tech-doc 的模板库（同源技能，缺席不影响建版——只是少了必备章节核对）。"""
+    here = os.path.dirname(os.path.abspath(__file__))
+    cand = os.path.join(os.path.dirname(os.path.dirname(here)), 'tech-doc', 'scripts')
+    if cand not in sys.path:
+        sys.path.insert(0, cand)
+    try:
+        import doc_templates
+        return doc_templates
+    except Exception:
+        return None
+
+
+def _template_audit(spec, blocks):
+    """按文档类型核对必备章节。**在建版这一步就报缺节**，比出片后靠人翻目录靠谱。"""
+    name = spec.get('template')
+    T = _load_templates() if name else None
+    if not T:
+        return [], spec.get('profile', 'tech')
+    key = T.find(name)
+    if not key:
+        return [f'未收录文档类型「{name}」，已按通用技术文档处理；'
+                f'可选类型：{"、".join(list(T.TEMPLATES)[:8])}…'], spec.get('profile', 'tech')
+    t = T.TEMPLATES[key]
+    heads = [str(b.get('text', '')) for b in (blocks or []) if str(b.get('type', '')).startswith('h')]
+    joined = ' '.join(heads)
+    # 走 sections_for：有自家归档体例就以它为准，否则用通用库。
+    # 两边各判各的，会让「按 create_doc 补齐」的文档在档案体检里照样报缺章节。
+    secs = T.sections_for(key) if hasattr(T, 'sections_for') else \
+        [(x[0], x[1], x[2]) for x in t.get('sections', [])]
+    missing = [title for title, _subs, must in secs
+               if must and title not in joined and not any(_overlap(title, h) for h in heads)]
+    warns = []
+    if missing:
+        warns.append(f'【{key}】缺必备章节：{"、".join(missing)}'
+                     f'——评审是按章节核对的，缺一节就是缺一项')
+    if t.get('form') and not any(str(b.get('type')) == 'kv' for b in (blocks or [])):
+        warns.append(f'【{key}】是表单式文档，主体应为字段表（blocks 里用 type:"kv"），'
+                     f'当前没有任何 kv 表')
+    return warns, spec.get('profile') or t['profile']
+
+
+def _overlap(a, b):
+    """标题近似匹配：去掉编号与标点后有 3 个以上连续汉字重合即认为是同一节。"""
+    import re as _re
+    ca = _re.sub(r'[^\u4e00-\u9fff]', '', a)
+    cb = _re.sub(r'[^\u4e00-\u9fff]', '', b)
+    if not ca or not cb:
+        return False
+    return any(ca[i:i + 3] in cb for i in range(max(len(ca) - 2, 1)))
+
+
+def build(spec, out_path):
+    """spec（dict）→ docx。spec 见 create_doc 工具说明；返回 (path, 体检结果, warnings)。"""
+    blocks0 = spec.get('blocks')
+    if blocks0 is None and spec.get('markdown'):
+        blocks0 = md_to_blocks(spec['markdown'])
+        base = spec.get('_md_dir')
+        if base:
+            for blk in blocks0:
+                if blk.get('type') == 'figure' and not os.path.isabs(blk.get('image', '')):
+                    cand = os.path.join(base, blk['image'])
+                    # 草稿在 docs/ 下、图路径却按项目根写（docs/charts/x.png）是最常见的写法：两种都认
+                    if not os.path.exists(cand) and os.path.exists(blk['image']):
+                        cand = os.path.abspath(blk['image'])
+                    blk['image'] = cand
+    # 标题层级归一：Markdown 习惯把「#」留给文档标题，章从「##」起——全文没有一级标题时整体上提一级，
+    # 否则目录、导航窗格、按章编号的题注（图 3-1）都会错一级（实测一份可研通篇 ## / ###，题注成了全文连续编号）
+    hl = [int(str(b.get('type'))[1]) for b in (blocks0 or []) if re.fullmatch(r'h[1-4]', str(b.get('type', '')))]
+    if hl and min(hl) > 1:
+        shift = min(hl) - 1
+        blocks0 = [({**b, 'type': f"h{int(str(b['type'])[1]) - shift}"} if re.fullmatch(r'h[1-4]', str(b.get('type', ''))) else b)
+                   for b in blocks0]
+    # 父目录不存在就建——直接调 API 的场景（如归档生成器批量落盘到子目录）
+    # 拿不到工具层的 resolveOut 兜底，漏了这一句就会在第一个子目录上炸。
+    d = os.path.dirname(os.path.abspath(out_path))
+    if d:
+        os.makedirs(d, exist_ok=True)
+    tpl_warns, prof_name = _template_audit(spec, blocks0)
+    spec = {**spec, 'profile': prof_name}
+    b = DocBuilder(spec.get('profile', 'tech'),
+                   numbering=spec.get('numbering'),
+                   caption_by_chapter=spec.get('caption_by_chapter'))
+    if spec.get('cover', True) and spec.get('title'):
+        b.add_cover(spec['title'], spec.get('subtitle', ''), spec.get('org', ''),
+                    spec.get('author', ''), spec.get('date'), spec.get('doc_no', ''),
+                    spec.get('cover_fields'),
+                    # 封面信息栏默认排成无框线两列表：冒号天然对齐，**而且机器读得出来**。
+                    # 写成居中段落的话，跨文档一致性核对拿不到字段，整类检查静默失效。
+                    spec.get('cover_table', True))
+    if spec.get('toc', True):
+        b.add_toc()
+    if spec.get('cover', True) or spec.get('toc', True):
+        b.start_body(spec.get('restart_page_numbers', True))
+    blocks = blocks0
+    refs = {}
+    for blk in (blocks or []):
+        t = str(blk.get('type', 'p')).lower()
+        if t in ('table', 'figure', 'kv'):
+            cap, rid = _split_xref(blk.get('caption', ''))
+            blk = {**blk, 'caption': cap}
+            rid = rid or blk.get('id')
+            b.last_label = None
+        else:
+            rid = None
+        if t in ('h1', 'h2', 'h3', 'h4'):
+            b.add_heading(blk.get('text', ''), int(t[1]), blk.get('numbered'))
+        elif t == 'p':
+            b.add_para(blk.get('text', ''))
+        elif t == 'bullets':
+            b.add_bullets(blk.get('items', []))
+        elif t == 'ordered':
+            b.add_bullets(blk.get('items', []), ordered=True)
+        elif t == 'table':
+            b.add_table(blk.get('rows', []), blk.get('caption', ''), blk.get('note', ''),
+                        style=blk.get('style', 'grid'))
+        elif t == 'kv':
+            b.add_kv_table(blk.get('pairs', []), blk.get('caption', ''))
+        elif t == 'figure':
+            b.add_figure(blk.get('image', ''), blk.get('caption', ''), blk.get('width_cm'), blk.get('note', ''),
+                         landscape=bool(blk.get('landscape')))
+        elif t == 'note':
+            b.add_para(blk.get('text', ''), {'size': '五号', 'east': '楷体'})
+        elif t == 'signature':
+            b.add_signature(blk.get('roles', ('编制', '审核', '批准')), blk.get('org', spec.get('org', '')))
+        elif t == 'pagebreak':
+            b.add_page_break()
+        if rid and getattr(b, 'last_label', None):
+            refs[str(rid)] = b.last_label
+    b.resolve_refs(refs)
+    b.set_header_footer(spec.get('header', ''), spec.get('footer', ''),
+                        spec.get('page_numbers', True))
+    path, res = b.save(out_path, inspect=spec.get('inspect', True))
+    return path, res, tpl_warns + b.warnings, b.labels
+
+
+def md_to_docx(md_path, out_path, title='', author='', subtitle='', toc=True,
+               profile='tech', org='', header='', footer='', **kw):
+    """Markdown 文件 → 成品 docx（向后兼容的老入口，内部已换成新引擎）。"""
+    text = open(md_path, encoding='utf-8-sig').read()      # utf-8-sig 对无 BOM 文件是无害的
+    base = os.path.dirname(os.path.abspath(md_path))
+    blocks = md_to_blocks(text)
+    for blk in blocks:
+        if blk.get('type') == 'figure':
+            src = blk['image']
+            if not os.path.isabs(src):
+                blk['image'] = os.path.join(base, src)
+    spec = {'profile': profile, 'title': title, 'subtitle': subtitle, 'author': author,
+            'org': org, 'toc': toc, 'cover': bool(title), 'header': header, 'footer': footer,
+            'blocks': blocks}
+    spec.update(kw)
+    path = build(spec, out_path)[0]
+    return path
+
+
+def main(argv):
+    if len(argv) < 2:
+        print('用法：python docx_build.py spec.json 输出.docx   |   python docx_build.py --demo')
+        return 2
+    if argv[0] == '--demo':
+        return _demo(argv[1])
+    spec = json.load(open(argv[0], encoding='utf-8'))
+    try:
+        path, res, warns, labels = build(spec, argv[1])
+    except Exception as e:
+        print(json.dumps({'error': f'{type(e).__name__}: {e}'}, ensure_ascii=False))
+        return 1
+    out = {'path': path, 'warnings': warns, 'labels': labels}
+    if res:
+        import docx_check
+        out['check'] = {'counts': res['counts'], 'stats': res['stats']}
+        out['report'] = docx_check.report(res, show_info=False)
+    print(json.dumps(out, ensure_ascii=False, default=str))
+    return 0
+
+
+def _demo(out):
+    b = DocBuilder('tech')
+    b.add_cover('智能运维平台研发项目', '项目研发实施计划', org='数字技术研究院', doc_no='YF-2026-014')
+    b.add_toc().start_body()
+    b.add_heading('项目概述', 1)
+    b.add_para('本项目围绕设备故障的**提前发现**展开，目标是把平均故障发现时间从 42 分钟压到 8 分钟以内。')
+    b.add_heading('建设目标', 2)
+    b.add_bullets(['告警准确率 ≥ 92%', '单节点接入成本 ≤ 1.2 人日'])
+    b.add_para('三项考核指标的现状、目标与验证方式如表 1 所示，全部写入合同附件三。')
+    b.add_table([['指标', '现状', '目标值', '验证方式'],
+                 ['平均故障发现时间', '42 分钟', '≤ 8 分钟', '生产环境连续 30 天采样'],
+                 ['告警准确率', '61%', '≥ 92%', '与工单系统比对'],
+                 ['单节点接入成本', '3.5 人日', '≤ 1.2 人日', '实施记录统计']],
+                caption='关键考核指标', note='口径以合同附件三为准')
+    b.add_heading('实施计划', 1)
+    b.add_para('分三个阶段推进，里程碑与交付物见下表。')
+    b.add_signature(org='数字技术研究院')
+    b.set_header_footer('智能运维平台研发项目 · 研发实施计划', '数字技术研究院')
+    p, res = b.save(out)
+    print(f'demo → {p}')
+    if res:
+        import docx_check
+        print(docx_check.report(res))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))