sdpy-kit 0.1.7__tar.gz → 0.1.9__tar.gz

{sdpy_kit-0.1.7 → sdpy_kit-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.7
+Version: 0.1.9
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -24,6 +24,7 @@ Requires-Dist: sqlmodel>=0.0.39
 Provides-Extra: ai
 Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Provides-Extra: all
+Requires-Dist: docxtpl>=0.20.2; extra == 'all'
 Requires-Dist: fastmcp>=4.0.3; extra == 'all'
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
 Requires-Dist: httpx>=0.28.1; extra == 'all'
@@ -40,6 +41,8 @@ Provides-Extra: doc
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'doc'
 Requires-Dist: markdown-it-py>=3.0; extra == 'doc'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'doc'
+Provides-Extra: docx
+Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=4.0.3; extra == 'mcp'
 Provides-Extra: mineru
@@ -50,9 +53,9 @@ Provides-Extra: pg
 Requires-Dist: psycopg2-binary>=2.9.12; extra == 'pg'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0.0; extra == 'redis'
-Provides-Extra: sqliteai-vector
-Requires-Dist: numpy>=2.0; extra == 'sqliteai-vector'
-Requires-Dist: sqliteai-vector>=1.1.0; extra == 'sqliteai-vector'
+Provides-Extra: sqliteai
+Requires-Dist: numpy>=2.0; extra == 'sqliteai'
+Requires-Dist: sqliteai-vector>=1.1.0; extra == 'sqliteai'
 Provides-Extra: zvec
 Requires-Dist: zvec>=0.6.0; extra == 'zvec'
 Description-Content-Type: text/markdown

{sdpy_kit-0.1.7 → sdpy_kit-0.1.9}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.1.7"
+__version__ = "0.1.9"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.1.7 → sdpy_kit-0.1.9}/kit/ai/model_client.py

@@ -219,18 +219,26 @@ class ModelClient:
                 json=payload,
                 timeout=None,
             ) as resp:
-                resp.raise_for_status()
+                if resp.is_error:
+                    # 错误响应体必须在流上下文内读取；离开后访问 .text 会抛
+                    # ResponseNotRead 并掩盖真实状态码（0.1.7 缺陷）
+                    body = (await resp.aread()).decode("utf-8", errors="replace")[:200]
+                    retry_after = (
+                        _parse_retry_after(resp.headers.get("Retry-After"))
+                        if resp.status_code == 429
+                        else None
+                    )
+                    raise AIRequestError(
+                        f"流式 HTTP 错误 {resp.status_code}: {body}",
+                        status_code=resp.status_code,
+                        retry_after=retry_after,
+                    )
                 async for line in resp.aiter_lines():
                     parsed = await self._parse_sse_line(line)
                     if parsed is not None:
                         yield parsed
         except httpx.TimeoutException as exc:
             raise AITimeoutError(f"流式请求超时: {exc}") from exc
-        except httpx.HTTPStatusError as exc:
-            raise AIRequestError(
-                f"流式 HTTP 错误 {exc.response.status_code}: {exc.response.text[:200]}",
-                status_code=exc.response.status_code,
-            ) from exc
         except httpx.HTTPError as exc:
             raise AIRequestError(f"流式请求失败: {exc}") from exc
 

sdpy_kit-0.1.9/kit/docx_kit.py

@@ -0,0 +1,896 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-09-14
+"""docx 模板动态填充工具类，基于 docxtpl 实现章节与内容全动态的模板渲染
+
+本模块封装 docxtpl，提供「Word 模板 + 结构化数据 → 成品 docx」的模板填充
+服务：章节数量、层级、标题、正文段落、多级列表、表格全部由运行时数据决定，
+模板只承载版式骨架（封面、页眉页脚、字体、编号绑定）。
+
+与 DocKit 的边界：DocKit 负责格式转换（含 Markdown → Word 整篇渲染），本模块
+负责模板填充，二者互不调用。
+
+设计要点：
+- 混合方案：章节循环由模板中的 ``{%p for %}`` 承载，非文本块（列表/表格）
+  以私有使用区字符组成的 marker 段落承载「位置 + 载荷」，渲染后由 python-docx
+  后处理原位转换，规避 docxtpl 无法表达动态层级与富内容的限制。
+- 章节标题段使用锚点样式（默认 ``DocxSectionTitle``），渲染后按 ``level``
+  重设为 ``Heading N``，使模板自身绑定的 Word 多级列表自动编号生效。
+- 模板渲染开启 ``autoescape``，正文文本中的 ``&`` / ``<`` / ``>`` 不会破坏 XML。
+- 变量值中的控制字符语义沿用 docxtpl 约定：``\\n`` 段内软换行、``\\a`` 新段落。
+- 全静态方法、无模块级可变状态（除常量），线程安全。
+- 路径参数统一支持 str 与 pathlib.Path。
+- 有序列表按「连续组」克隆独立编号定义，避免 Word 把多个列表串成一条编号序列。
+- 模板样式统一：:meth:`DocxKit.unify_font` 统一字体、:meth:`DocxKit.unify_heading_color`
+  统一标题颜色，产物继承模板样式；主标题段由 :meth:`DocxKit.create_template` 的
+  ``title`` 参数生成（居中、加粗）。
+"""
+
+import re
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+
+try:
+    from docx import Document
+    from docx.document import Document as DocxDocument
+    from docx.enum.style import WD_STYLE_TYPE
+    from docx.enum.text import WD_ALIGN_PARAGRAPH
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+    from docx.oxml.xmlchemy import BaseOxmlElement
+    from docx.shared import Pt
+    from docx.styles.style import BaseStyle, ParagraphStyle
+    from docx.table import Table as DocxTableElement
+    from docx.text.paragraph import Paragraph as DocxParagraphElement
+    from docxtpl import DocxTemplate
+except ImportError as e:
+    raise ImportError(
+        "docx_kit 需要可选依赖，请安装：pip install sdpy-kit[docx]"
+    ) from e
+
+from kit.config.log_config import get_default_logger
+
+logger = get_default_logger(__name__)
+
+# ---------------------------------------------------------------- 常量
+
+# marker 前缀：U+E000（Unicode 私有使用区），正常正文几乎不可能出现，
+# 用于在纯文本占位符中承载「非文本块」的类型、序号与载荷。
+_MARKER_KEY = "\ue000docxkit"
+_MARKER_SEP = "\ue000"
+_MARKER_RE = re.compile(
+    r"^\ue000docxkit:(?P<kind>table|list):(?P<index>\d+)\ue000(?P<payload>.*)$",
+    re.DOTALL,
+)
+
+_DEFAULT_ANCHOR_STYLE = "DocxSectionTitle"
+_DEFAULT_TABLE_STYLE = "Table Grid"
+_SECTION_VARIABLE = "sections"
+
+_MIN_LEVEL = 1
+_MAX_HEADING_LEVEL = 9
+_MAX_LIST_LEVEL = 3
+
+# 变量值中的控制字符语义（docxtpl 约定）
+_SOFT_BREAK = "\n"
+_PARAGRAPH_BREAK = "\a"
+
+
+# ---------------------------------------------------------------- 异常
+
+
+class DocxError(Exception):
+    """docx 模板填充异常
+
+    覆盖模板缺失锚点样式、数据非法、渲染失败、后处理失败，以及字体统一 /
+    标题颜色统一失败等场景；消息均为可直接定位问题的中文描述。
+    """
+
+
+# ---------------------------------------------------------------- 数据模型
+
+
+@dataclass(frozen=True, slots=True)
+class DocxParagraph:
+    """正文段落块
+
+    Attributes:
+        text: 段落文本；``\\n`` 为段内软换行，``\\a`` 为分段。
+    """
+
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class DocxListItem:
+    """列表项块
+
+    Attributes:
+        text: 列表项文本（``\\n`` 为项内软换行）
+        level: 列表层级 1..3，对应 List Bullet/List Number 的第 N 级样式
+        ordered: True 为有序列表（List Number），False 为无序列表（List Bullet）
+    """
+
+    text: str
+    level: int = 1
+    ordered: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class DocxTable:
+    """表格块
+
+    Attributes:
+        headers: 表头单元格文本，长度即列数（不可为空）
+        rows: 数据行，每行长度必须等于表头长度
+        style: 表格样式名，None 时使用 ``DocxKit.TABLE_STYLE``
+    """
+
+    headers: tuple[str, ...]
+    rows: tuple[tuple[str, ...], ...] = ()
+    style: str | None = None
+
+
+type DocxBlock = DocxParagraph | DocxListItem | DocxTable
+
+
+@dataclass(frozen=True, slots=True)
+class DocxSection:
+    """章节
+
+    Attributes:
+        title: 章节标题文本
+        level: 章节层级 1..9，对应 ``Heading N`` 段落样式
+        blocks: 章节内容块，按给定顺序输出（段落 / 列表 / 表格可任意交错）
+    """
+
+    title: str
+    level: int = 1
+    blocks: tuple[DocxBlock, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DocxReport:
+    """待渲染文档
+
+    Attributes:
+        sections: 章节序列，数量与层级完全动态
+        variables: 额外的模板静态变量（封面标题、单位、日期等），
+            与章节上下文合并后交给 docxtpl，键名勿与 ``sections`` 冲突
+    """
+
+    sections: tuple[DocxSection, ...] = ()
+    variables: Mapping[str, object] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------- 内部工具
+
+
+def _style_matches(style: ParagraphStyle | None, target: str) -> bool:
+    """样式匹配：同时接受样式名与样式 ID（Word 中二者可能不同）"""
+    if style is None:
+        return False
+    return style.name == target or style.style_id == target
+
+
+def _paragraph_styles(document: DocxDocument) -> dict[str, BaseStyle]:
+    """收集文档中的段落样式（样式名 + 样式 ID 双键，便于两种写法命中）"""
+    styles: dict[str, BaseStyle] = {}
+    for style in document.styles:
+        if style.type != WD_STYLE_TYPE.PARAGRAPH:
+            continue
+        styles[style.name] = style
+        if style.style_id:
+            styles.setdefault(style.style_id, style)
+    return styles
+
+
+def _require_docx_path(raw_path: str | Path, what: str) -> Path:
+    """校验并解析 .docx 文件路径"""
+    path = Path(raw_path).resolve()
+    if not path.exists():
+        raise DocxError(f"{what}不存在: {path}")
+    if not path.is_file():
+        raise DocxError(f"{what}路径不是有效文件: {path}")
+    if path.suffix.lower() != ".docx":
+        raise DocxError(
+            f"{what}必须为 .docx 文件，当前后缀: {path.suffix or '<无扩展名>'}"
+        )
+    return path
+
+
+def _require_dest_path(raw_path: str | Path) -> Path:
+    """校验并解析目标路径（父目录自动创建）"""
+    dest = Path(raw_path).resolve()
+    if dest.suffix.lower() != ".docx":
+        raise DocxError(
+            f"目标路径必须为 .docx 文件，当前后缀: {dest.suffix or '<无扩展名>'}"
+        )
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    return dest
+
+
+def _list_style_name(ordered: bool, level: int) -> str:
+    """列表样式名：level 1 → List Bullet/List Number，2/3 → 追加空格与层级"""
+    base = "List Number" if ordered else "List Bullet"
+    return base if level <= 1 else f"{base} {level}"
+
+
+def _resolve_heading_styles(available: Mapping[str, BaseStyle]) -> dict[int, str]:
+    """为 level 1..9 解析可用的 Heading 样式名（缺失时逐级向下回退）"""
+    resolved: dict[int, str] = {}
+    for level in range(_MIN_LEVEL, _MAX_HEADING_LEVEL + 1):
+        for candidate in range(level, 0, -1):
+            name = f"Heading {candidate}"
+            if name in available:
+                if candidate != level:
+                    logger.warning(
+                        f"模板缺少 Heading {level} 样式，层级 {level} 回退到 {name}"
+                    )
+                resolved[level] = name
+                break
+    return resolved
+
+
+def _resolve_list_style(
+    ordered: bool, level: int, available: Mapping[str, BaseStyle]
+) -> str:
+    """解析列表样式名（缺级时逐级向下回退，最终回退 List Paragraph）"""
+    base = _list_style_name(ordered, level)
+    candidates = [base]
+    candidates.extend(_list_style_name(ordered, lv) for lv in range(level - 1, 0, -1))
+    candidates.append("List Paragraph")
+    for name in candidates:
+        if name in available:
+            if name != base:
+                logger.warning(f"模板缺少 {base} 样式，列表样式回退到 {name}")
+            return name
+    raise DocxError(
+        "模板缺少列表样式（List Bullet / List Number / List Paragraph 均不存在），"
+        "请在模板中保留 Word 内置列表样式"
+    )
+
+
+def _set_paragraph_text(paragraph: DocxParagraphElement, text: str) -> None:
+    """重设段落文本：清空原 run，``\\n`` 重建为段内软换行"""
+    for run in list(paragraph.runs):
+        run._r.getparent().remove(run._r)
+    run = paragraph.add_run()
+    parts = text.split(_SOFT_BREAK)
+    run.add_text(parts[0])
+    for part in parts[1:]:
+        run.add_break()
+        run.add_text(part)
+
+
+# 字体统一涉及的 rFonts 属性：四项显式字体，以及需一并清除的主题引用
+_FONT_ATTRIBUTES: tuple[str, ...] = ("w:ascii", "w:hAnsi", "w:eastAsia", "w:cs")
+_THEME_FONT_ATTRIBUTES: tuple[str, ...] = (
+    "w:asciiTheme",
+    "w:hAnsiTheme",
+    "w:eastAsiaTheme",
+    "w:cstheme",
+)
+# 标题颜色统一需一并清除的主题颜色属性
+_THEME_COLOR_ATTRIBUTES: tuple[str, ...] = (
+    "w:themeColor",
+    "w:themeTint",
+    "w:themeShade",
+)
+
+
+def _unify_rfonts(rfonts: BaseOxmlElement, font_name: str) -> None:
+    """把单个 rFonts 的字体设为指定值，并移除主题引用
+
+    Word 中主题引用（如 ``w:asciiTheme``）优先于显式字体，故须一并删除，
+    否则文档仍会使用主题字体。
+    """
+    for attribute in _THEME_FONT_ATTRIBUTES:
+        if rfonts.get(qn(attribute)) is not None:
+            del rfonts.attrib[qn(attribute)]
+    for attribute in _FONT_ATTRIBUTES:
+        rfonts.set(qn(attribute), font_name)
+
+
+# ---------------------------------------------------------------- 数据校验
+
+
+def _validate_report(report: DocxReport) -> None:
+    """渲染前校验数据合法性（层级范围、表格形状）"""
+    for section_index, section in enumerate(report.sections, start=1):
+        if not _MIN_LEVEL <= section.level <= _MAX_HEADING_LEVEL:
+            raise DocxError(
+                f"第 {section_index} 个章节 level={section.level} 越界"
+                f"（允许 {_MIN_LEVEL}..{_MAX_HEADING_LEVEL}）"
+            )
+        for block_index, block in enumerate(section.blocks, start=1):
+            if not isinstance(block, DocxTable):
+                continue
+            if not block.headers:
+                raise DocxError(
+                    f"第 {section_index} 个章节第 {block_index} 个表格表头为空"
+                )
+            for row_index, row in enumerate(block.rows, start=1):
+                if len(row) != len(block.headers):
+                    raise DocxError(
+                        f"第 {section_index} 个章节第 {block_index} 个表格第 "
+                        f"{row_index} 行列数 {len(row)} 与表头列数 "
+                        f"{len(block.headers)} 不一致"
+                    )
+
+
+# ---------------------------------------------------------------- 上下文编译
+
+
+def _compile_sections(
+    report: DocxReport,
+) -> tuple[list[dict[str, str]], dict[int, DocxBlock]]:
+    """把章节树编译为模板上下文与「marker 序号 → 块对象」注册表
+
+    段落块直接写入正文文本；列表与表格块替换为 marker 段落，
+    其真实内容保留在注册表中供后处理使用。
+    """
+    registry: dict[int, DocxBlock] = {}
+    sections: list[dict[str, str]] = []
+    counter = 0
+    for section in report.sections:
+        parts: list[str] = []
+        for block in section.blocks:
+            match block:
+                case DocxParagraph(text=text):
+                    parts.append(text)
+                case DocxListItem():
+                    parts.append(
+                        f"{_MARKER_KEY}:list:{counter}{_MARKER_SEP}{block.text}"
+                    )
+                    registry[counter] = block
+                    counter += 1
+                case DocxTable():
+                    parts.append(f"{_MARKER_KEY}:table:{counter}{_MARKER_SEP}")
+                    registry[counter] = block
+                    counter += 1
+        sections.append({"title": section.title, "body": _PARAGRAPH_BREAK.join(parts)})
+    return sections, registry
+
+
+def _build_context(
+    report: DocxReport, sections: list[dict[str, str]]
+) -> dict[str, object]:
+    """合并静态变量与章节上下文（章节上下文优先级更高）"""
+    context: dict[str, object] = dict(report.variables)
+    if _SECTION_VARIABLE in context:
+        logger.warning(f"variables 中的 {_SECTION_VARIABLE!r} 将被章节数据覆盖")
+    context[_SECTION_VARIABLE] = sections
+    return context
+
+
+# ---------------------------------------------------------------- 后处理
+
+
+def _convert_list_item(
+    styles: Mapping[str, BaseStyle], paragraph: DocxParagraphElement, item: DocxListItem
+) -> int:
+    """marker 段 → 列表项：重写文本并按层级设置列表样式
+
+    Returns:
+        int: 实际生效的列表层级（越界时已回退），供编号定义设置使用
+    """
+    level = item.level
+    if not _MIN_LEVEL <= level <= _MAX_LIST_LEVEL:
+        logger.warning(f"列表层级 {level} 越界，回退到 {_MAX_LIST_LEVEL}")
+        level = _MAX_LIST_LEVEL
+    style_name = _resolve_list_style(item.ordered, level, styles)
+    _set_paragraph_text(paragraph, item.text)
+    paragraph.style = styles[style_name]
+    return level
+
+
+def _convert_table(
+    document: DocxDocument, paragraph: DocxParagraphElement, data: DocxTable
+) -> None:
+    """marker 段 → 表格：原位插入并把 marker 段删除
+
+    连续表格之间补一个空段落，避免 Word 把相邻表格合并渲染。
+    """
+    table: DocxTableElement = document.add_table(
+        rows=1 + len(data.rows), cols=len(data.headers)
+    )
+    style_name = data.style or _DEFAULT_TABLE_STYLE
+    try:
+        table.style = style_name
+    except KeyError as e:
+        raise DocxError(
+            f"模板缺少表格样式: {style_name}（可通过 DocxTable.style 指定其他样式）"
+        ) from e
+    for column_index, header in enumerate(data.headers):
+        table.cell(0, column_index).text = header
+    for row_index, row in enumerate(data.rows, start=1):
+        for column_index, value in enumerate(row):
+            table.cell(row_index, column_index).text = value
+
+    marker_element = paragraph._p
+    marker_element.addnext(table._tbl)
+    marker_element.getparent().remove(marker_element)
+    # 相邻表格之间补空段落，避免 Word 把两张表合并渲染：
+    # 后一张表插入时其 marker 段尚未转换，故插入后按前后兄弟双向检测
+    following = table._tbl.getnext()
+    if following is not None and following.tag == qn("w:tbl"):
+        table._tbl.addnext(OxmlElement("w:p"))
+    previous = table._tbl.getprevious()
+    if previous is not None and previous.tag == qn("w:tbl"):
+        table._tbl.addprevious(OxmlElement("w:p"))
+
+
+def _style_num_id(style: BaseStyle) -> str | None:
+    """取样式引用的 numId（编号定义 ID）"""
+    ppr = style.element.find(qn("w:pPr"))
+    if ppr is None:
+        return None
+    num_pr = ppr.find(qn("w:numPr"))
+    if num_pr is None:
+        return None
+    num_id = num_pr.find(qn("w:numId"))
+    return None if num_id is None else num_id.get(qn("w:val"))
+
+
+def _clone_ordered_numbering(
+    document: DocxDocument, styles: Mapping[str, BaseStyle]
+) -> int | None:
+    """为当前有序列表克隆一份独立编号定义，返回新 numId
+
+    Word 按 numId 连续计数：同一 numId 下的所有段落会串成一条编号序列，
+    因此文档中多个有序列表会连号（1..N）。每个有序列表组克隆一份 num
+    定义（引用同一 abstractNum 以保持编号格式），即可各自从 1 开始。
+    模板缺少编号定义时返回 None，保留 Word 默认行为。
+    """
+    list_number = styles.get("List Number")
+    base_num_id = _style_num_id(list_number) if list_number is not None else None
+    if base_num_id is None:
+        logger.warning("模板 List Number 样式未引用编号定义，有序列表可能连续编号")
+        return None
+
+    try:
+        numbering = document.part.numbering_part.element
+    except (AttributeError, KeyError, NotImplementedError, ValueError) as e:
+        logger.warning(f"文档缺少编号定义（numbering.xml），有序列表可能连续编号: {e}")
+        return None
+
+    existing = numbering.findall(qn("w:num"))
+    base = next(
+        (num for num in existing if num.get(qn("w:numId")) == base_num_id), None
+    )
+    if base is None:
+        logger.warning(f"编号定义中缺少 numId={base_num_id}，有序列表可能连续编号")
+        return None
+
+    new_id = max((int(num.get(qn("w:numId")) or 0) for num in existing), default=0) + 1
+    new_num = deepcopy(base)
+    new_num.set(qn("w:numId"), str(new_id))
+    numbering.append(new_num)
+    return new_id
+
+
+def _apply_numbering(paragraph: DocxParagraphElement, level: int, num_id: int) -> None:
+    """为段落写入段落级 numPr（指向独立编号定义，覆盖样式级编号）"""
+    ppr = paragraph._p.get_or_add_pPr()
+    num_pr = OxmlElement("w:numPr")
+    ilvl = OxmlElement("w:ilvl")
+    ilvl.set(qn("w:val"), str(max(level - 1, 0)))
+    num_id_element = OxmlElement("w:numId")
+    num_id_element.set(qn("w:val"), str(num_id))
+    num_pr.append(ilvl)
+    num_pr.append(num_id_element)
+    # pPr 子元素顺序有约束：numPr 须紧随 pStyle
+    style_element = ppr.find(qn("w:pStyle"))
+    if style_element is not None:
+        style_element.addnext(num_pr)
+    else:
+        ppr.insert(0, num_pr)
+
+
+def _post_process(
+    dest: Path,
+    sections: tuple[DocxSection, ...],
+    registry: Mapping[int, DocxBlock],
+    anchor_style: str,
+) -> None:
+    """渲染后处理：锚点标题段改 Heading N，marker 段转列表/表格
+
+    有序列表按「连续组」分配独立编号定义，避免 Word 把多个列表串成一条
+    编号序列（1..N）。
+    """
+    document = Document(str(dest))
+    styles = _paragraph_styles(document)
+    heading_styles = _resolve_heading_styles(styles)
+    if not heading_styles:
+        raise DocxError(
+            "模板中不存在 Heading 1..9 段落样式，无法设置章节标题层级，"
+            "请在模板中保留 Word 内置标题样式"
+        )
+
+    title_count = 0
+    block_count = 0
+    ordered_num_id: int | None = None
+    in_ordered_list = False
+    for paragraph in document.paragraphs:
+        text = paragraph.text
+        if text.startswith(_MARKER_KEY):
+            matched = _MARKER_RE.match(text)
+            if matched is None:
+                raise DocxError(f"无法解析的内容标记段: {text[:40]!r}")
+            index = int(matched.group("index"))
+            block = registry.get(index)
+            if block is None:
+                raise DocxError(f"内容标记引用了不存在的块序号: {index}")
+            match block:
+                case DocxListItem(ordered=True):
+                    level = _convert_list_item(styles, paragraph, block)
+                    if not in_ordered_list:
+                        ordered_num_id = _clone_ordered_numbering(document, styles)
+                    if ordered_num_id is not None:
+                        _apply_numbering(paragraph, level, ordered_num_id)
+                    in_ordered_list = True
+                case DocxListItem():
+                    _convert_list_item(styles, paragraph, block)
+                    in_ordered_list = False
+                case DocxTable():
+                    _convert_table(document, paragraph, block)
+                    in_ordered_list = False
+            block_count += 1
+            continue
+        # 标题、正文、模板静态段均视为打断有序列表组
+        in_ordered_list = False
+        if _style_matches(paragraph.style, anchor_style):
+            if title_count >= len(sections):
+                logger.warning(f"锚点标题段多于章节数据，忽略: {text[:30]!r}")
+                continue
+            level = sections[title_count].level
+            paragraph.style = styles[heading_styles[level]]
+            title_count += 1
+
+    if title_count < len(sections):
+        raise DocxError(
+            f"模板锚点标题段不足：章节数据 {len(sections)} 个，"
+            f"模板仅匹配到 {title_count} 个（锚点样式 {anchor_style!r}）"
+        )
+    document.save(str(dest))
+    logger.info(f"后处理完成：{title_count} 个章节标题、{block_count} 个富内容块")
+
+
+# ---------------------------------------------------------------- 工具类
+
+
+class DocxKit:
+    """docx 模板动态填充工具类
+
+    方法一览：
+
+    - :meth:`create_template`：生成标准模板骨架（可含居中主标题段）
+    - :meth:`unify_font`：统一文档字体（默认宋体）
+    - :meth:`unify_heading_color`：统一标题颜色（默认黑色）
+    - :meth:`inspect_template`：列出模板未声明变量，便于排查
+    - :meth:`render`：按数据渲染模板并落盘
+
+    使用方式：
+        # 1. 生成标准模板骨架（可继续在 Word 中美化样式）
+        DocxKit.create_template("templates/report.docx", title="{{ title }}")
+
+        # 2. 统一模板样式（可重复执行，幂等）
+        DocxKit.unify_font("templates/report.docx")
+        DocxKit.unify_heading_color("templates/report.docx")
+
+        # 3. 组织数据并渲染
+        report = DocxReport(
+            sections=(
+                DocxSection(
+                    title="第一章 概述",
+                    level=1,
+                    blocks=(
+                        DocxParagraph("本章介绍项目背景。"),
+                        DocxListItem("要点一"),
+                        DocxTable(headers=("名称", "数值"), rows=(("甲", "1"),)),
+                    ),
+                ),
+            ),
+            variables={"project": "SDPY"},
+        )
+        DocxKit.render("templates/report.docx", "out/report.docx", report)
+
+    模板约定（详见 docs/agents/modules/docx-kit.md）：
+        {%p for section in sections %}
+        [样式 DocxSectionTitle] {{ section.title }}
+        {{ section.body }}
+        {%p endfor %}
+
+    其中含 ``{%p %}`` 的两个段落会被 docxtpl 删除；章节标题段必须使用锚点
+    样式，渲染后由本模块按 level 改设为 ``Heading N``，模板自身把
+    ``Heading 1..9`` 绑定多级列表即可获得自动编号。
+    """
+
+    TITLE_ANCHOR_STYLE: str = _DEFAULT_ANCHOR_STYLE
+    TABLE_STYLE: str = _DEFAULT_TABLE_STYLE
+    TITLE_FONT_SIZE: int = 16  # 主标题字号（磅，约三号）
+
+    @staticmethod
+    def create_template(
+        dest_path: str | Path,
+        *,
+        title: str | None = None,
+        leading_paragraphs: Sequence[str] = (),
+        anchor_style: str | None = None,
+    ) -> str:
+        """生成标准模板骨架（含章节循环与锚点样式），供后续美化样式
+
+        生成内容：可选的主标题段（居中、加粗、三号字）、其余前置静态段落
+        （可写 ``{{ 变量 }}`` 占位符）、``{%p for %}`` 循环标签段、锚点样式
+        标题段、正文段、``{%p endfor %}`` 标签段。生成后可直接用 Word 调整
+        页面/页眉页脚等，或直接交给 :meth:`render` 使用。
+
+        Args:
+            dest_path: 目标 .docx 路径（父目录自动创建）
+            title: 文档主标题文本（可为 ``{{ 变量 }}`` 占位符）；传入时该段
+                居中、加粗、字号 :attr:`TITLE_FONT_SIZE`，并排在其余前置段落之前
+            leading_paragraphs: 其余前置静态段落文本列表，缺省为空
+            anchor_style: 章节标题锚点样式名，None 时使用
+                :attr:`TITLE_ANCHOR_STYLE`
+
+        Returns:
+            str: 实际写入的模板文件绝对路径
+
+        Raises:
+            DocxError: 目标后缀不是 .docx
+
+        Example:
+            >>> DocxKit.create_template("tpl.docx", title="{{ title }}")
+        """
+        dest = _require_dest_path(dest_path)
+        style_name = anchor_style or _DEFAULT_ANCHOR_STYLE
+
+        document = Document()
+        if title is not None:
+            title_paragraph = document.add_paragraph()
+            title_paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            title_run = title_paragraph.add_run(title)
+            title_run.bold = True
+            title_run.font.size = Pt(DocxKit.TITLE_FONT_SIZE)
+            title_paragraph.paragraph_format.space_after = Pt(12)
+        for text in leading_paragraphs:
+            document.add_paragraph(text)
+        styles = _paragraph_styles(document)
+        if style_name not in styles:
+            style = document.styles.add_style(style_name, WD_STYLE_TYPE.PARAGRAPH)
+            style.base_style = document.styles["Normal"]
+
+        document.add_paragraph(f"{{%p for section in {_SECTION_VARIABLE} %}}")
+        document.add_paragraph("{{ section.title }}", style=style_name)
+        document.add_paragraph("{{ section.body }}")
+        document.add_paragraph("{%p endfor %}")
+        document.save(str(dest))
+
+        logger.info(f"✅ 模板骨架已生成: {dest}")
+        return str(dest)
+
+    @staticmethod
+    def unify_font(docx_path: str | Path, *, font_name: str = "宋体") -> str:
+        """把文档默认字体与全部样式的字体统一为指定字体
+
+        设置范围：``docDefaults`` 与文档内**所有样式**的 ``w:rFonts``（含表格
+        样式条件格式 ``tblStylePr`` 内的），ascii、hAnsi、eastAsia、cs 四项
+        均设为 font_name，并移除主题字体引用（主题引用优先级高于显式字体）。
+        模板经此处理后，正文、标题、列表与表格单元格的中英文一致使用该字体；
+        渲染产物继承模板样式，无需重复处理。
+
+        Args:
+            docx_path: 待处理的 .docx 路径（模板或产物）
+            font_name: 统一后的字体名（Word 字体名），默认宋体
+
+        Returns:
+            str: 处理后的文件绝对路径（原地覆盖）
+
+        Raises:
+            DocxError: 路径非法或文档处理失败
+
+        Example:
+            >>> DocxKit.unify_font("tpl.docx")                     # 统一为宋体
+            >>> DocxKit.unify_font("tpl.docx", font_name="黑体")
+        """
+        path = _require_docx_path(docx_path, "文档")
+        try:
+            document = Document(str(path))
+            defaults = document.styles.element.find(qn("w:docDefaults"))
+            if defaults is not None:
+                rpr_default = defaults.find(qn("w:rPrDefault"))
+                default_rpr = (
+                    None if rpr_default is None else rpr_default.find(qn("w:rPr"))
+                )
+                if default_rpr is not None:
+                    rfonts = default_rpr.find(qn("w:rFonts"))
+                    if rfonts is None:
+                        rfonts = OxmlElement("w:rFonts")
+                        default_rpr.insert(0, rfonts)
+                    _unify_rfonts(rfonts, font_name)
+            for style in document.styles:
+                # 编号样式（_NumberingStyle）等无字体对象，仅处理其 rFonts
+                font = getattr(style, "font", None)
+                if font is not None:
+                    font.name = font_name
+                # 覆盖样式顶层 rPr 与表格样式条件格式（tblStylePr）内的全部 rFonts
+                style_fonts = list(style.element.iter(qn("w:rFonts"))) or [
+                    style.element.get_or_add_rPr().get_or_add_rFonts()
+                ]
+                for rfonts in style_fonts:
+                    _unify_rfonts(rfonts, font_name)
+            document.save(str(path))
+        except Exception as e:  # noqa: BLE001 - python-docx 异常统一包装
+            raise DocxError(f"字体统一失败: {path.name}: {e}") from e
+
+        logger.info(f"✅ 字体已统一为 {font_name}: {path}")
+        return str(path)
+
+    @staticmethod
+    def unify_heading_color(docx_path: str | Path, *, color: str = "000000") -> str:
+        """把 Heading 1..9 样式的字体颜色统一为指定色值
+
+        Word 内置标题样式默认使用主题蓝（``2F5496`` + ``themeColor="accent1"``），
+        本方法把 ``Heading 1..9`` 的 ``w:color`` 改为指定 RGB，并移除
+        ``themeColor`` / ``themeTint`` / ``themeShade`` 主题引用，使各层级标题
+        显示为同一颜色。模板经此处理后，渲染产物的标题同步生效。
+
+        Args:
+            docx_path: 待处理的 .docx 路径（模板或产物）
+            color: 6 位十六进制 RGB（不带 ``#``），默认 ``000000``（黑色）
+
+        Returns:
+            str: 处理后的文件绝对路径（原地覆盖）
+
+        Raises:
+            DocxError: 路径非法或文档处理失败
+
+        Example:
+            >>> DocxKit.unify_heading_color("tpl.docx")                  # 标题黑色
+            >>> DocxKit.unify_heading_color("tpl.docx", color="1F3864")  # 深蓝
+        """
+        path = _require_docx_path(docx_path, "文档")
+        try:
+            document = Document(str(path))
+            styles = _paragraph_styles(document)
+            changed = 0
+            for level in range(_MIN_LEVEL, _MAX_HEADING_LEVEL + 1):
+                style = styles.get(f"Heading {level}")
+                if style is None:
+                    continue
+                color_element = style.element.get_or_add_rPr().get_or_add_color()
+                color_element.set(qn("w:val"), color)
+                for attribute in _THEME_COLOR_ATTRIBUTES:
+                    if color_element.get(qn(attribute)) is not None:
+                        del color_element.attrib[qn(attribute)]
+                changed += 1
+            document.save(str(path))
+        except Exception as e:  # noqa: BLE001 - python-docx 异常统一包装
+            raise DocxError(f"标题颜色统一失败: {path.name}: {e}") from e
+
+        logger.info(f"✅ 标题颜色已统一为 #{color}: {path}（{changed} 个标题样式）")
+        return str(path)
+
+    @staticmethod
+    def inspect_template(
+        template_path: str | Path,
+        *,
+        context: Mapping[str, object] | None = None,
+    ) -> tuple[str, ...]:
+        """列出模板中未被上下文满足的变量（用于模板调试）
+
+        Args:
+            template_path: 模板 .docx 路径
+            context: 已有上下文；传入时仅返回未被满足的变量，None 时返回全部
+
+        Returns:
+            tuple[str, ...]: 按名称排序的变量名
+
+        Raises:
+            DocxError: 模板路径非法或解析失败
+
+        Example:
+            >>> DocxKit.inspect_template("tpl.docx")
+            ('project', 'sections')
+        """
+        tpl_path = _require_docx_path(template_path, "模板")
+        template = DocxTemplate(str(tpl_path))
+        try:
+            variables = template.get_undeclared_template_variables(context=context)
+        except Exception as e:  # noqa: BLE001 - Jinja/XML 解析异常统一包装
+            raise DocxError(f"模板解析失败: {tpl_path.name}: {e}") from e
+        return tuple(sorted(variables))
+
+    @staticmethod
+    def render(
+        template_path: str | Path,
+        dest_path: str | Path,
+        report: DocxReport,
+        *,
+        anchor_style: str | None = None,
+        strict: bool = True,
+    ) -> str:
+        """按数据渲染模板并落盘（核心方法）
+
+        流程：校验模板与数据 → 编译上下文 → docxtpl 渲染（autoescape）
+        → 后处理（锚点标题段改 ``Heading N``、marker 段转列表/表格、有序列表
+        按组分配独立编号）→ 落盘。
+
+        Args:
+            template_path: 模板 .docx 路径
+            dest_path: 目标 .docx 路径（父目录自动创建）
+            report: 文档数据（章节树 + 静态变量）
+            anchor_style: 章节标题锚点样式名，None 时使用
+                :attr:`TITLE_ANCHOR_STYLE`
+            strict: True 时模板存在未满足变量则抛错；False 时仅告警并按
+                空值渲染
+
+        Returns:
+            str: 实际写入的目标文件绝对路径
+
+        Raises:
+            DocxError: 模板非法、缺锚点样式、数据非法、变量未满足（strict）、
+                渲染或后处理失败
+
+        Example:
+            >>> DocxKit.render("tpl.docx", "out.docx", report)
+        """
+        tpl_path = _require_docx_path(template_path, "模板")
+        dest = _require_dest_path(dest_path)
+        style_name = anchor_style or _DEFAULT_ANCHOR_STYLE
+
+        _validate_report(report)
+
+        template_document = Document(str(tpl_path))
+        template_styles = _paragraph_styles(template_document)
+        if style_name not in template_styles:
+            raise DocxError(
+                f"模板缺少章节标题锚点样式 {style_name!r}："
+                "请用 DocxKit.create_template() 生成骨架，把章节标题段设为该样式，"
+                "或通过 anchor_style 参数指定模板中实际使用的样式名"
+            )
+
+        sections_context, registry = _compile_sections(report)
+        context = _build_context(report, sections_context)
+
+        template = DocxTemplate(str(tpl_path))
+        missing = tuple(template.get_undeclared_template_variables(context=context))
+        if missing:
+            message = f"模板存在未满足的变量: {', '.join(missing)}"
+            if strict:
+                raise DocxError(
+                    message + "（可通过 variables 提供，或传 strict=False）"
+                )
+            logger.warning(message + "（strict=False，将按空值渲染）")
+
+        logger.info(f"开始渲染模板: {tpl_path.name}（{len(report.sections)} 个章节）")
+        try:
+            template.render(context, autoescape=True)
+            template.save(str(dest))
+        except Exception as e:  # noqa: BLE001 - docxtpl/Jinja 异常统一包装
+            raise DocxError(f"模板渲染失败: {tpl_path.name}: {e}") from e
+
+        _post_process(dest, report.sections, registry, style_name)
+
+        logger.info(f"✅ 文档生成成功: {dest}")
+        return str(dest)

{sdpy_kit-0.1.7 → sdpy_kit-0.1.9}/pyproject.toml

@@ -43,18 +43,19 @@ dynamic = ["version"]
 # 全部可用，报错信息会提示安装命令：
 #   pg     → pg_kit（psycopg2）
 #   mysql  → mysql_kit（pymysql）
-#   sqliteai-vector → SQLiteKit 向量方法（numpy/sqliteai-vector，SQLite 向量扩展，业务按需）
+#   sqliteai → SQLiteKit 向量方法（numpy/sqliteai-vector，SQLite 向量扩展，业务按需）
 #   zvec   → zvec_kit（zvec，阿里独立向量库，与 SQLite 向量扩展完全独立）
 #   redis  → redis_kit
 #   mcp    → mcp_kit（fastmcp）
 #   ai     → kit/ai 服务池（httpx）
 #   doc    → doc_kit（firecrawl-anydoc/pimd/markdown-it-py，fpdf2 由 pimd[pdfa] 带入）
+#   docx   → docx_kit（docxtpl + python-docx，模板动态填充；与 doc 的格式转换能力独立）
 #   mineru → mineru_kit（requests）
 # 基础版 = config/log + kit.db 核心，SQLite 常规操作用标准库 sqlite3，零额外依赖。
 [project.optional-dependencies]
 pg = ["psycopg2-binary>=2.9.12"]
 mysql = ["pymysql>=1.2.0"]
-sqliteai-vector = [
+sqliteai = [
     "numpy>=2.0",
     "sqliteai-vector>=1.1.0",
 ]
@@ -67,6 +68,7 @@ doc = [
     "pimd[pdfa]>=2.2.5",
     "markdown-it-py>=3.0",
 ]
+docx = ["docxtpl>=0.20.2"]
 mineru = ["requests>=2.34.0"]
 all = [
     "psycopg2-binary>=2.9.12",
@@ -80,6 +82,7 @@ all = [
     "firecrawl-anydoc>=0.2.4",
     "pimd[pdfa]>=2.2.5",
     "markdown-it-py>=3.0",
+    "docxtpl>=0.20.2",
     "requests>=2.34.0",
 ]
 [tool.hatch.version]