feat(transit): 添加正文引用标记到书签超链接功能

- 新增 CITE_PATTERN 正则表达式匹配 [N] 引用格式
- 添加 base_dir 参数支持相对图片路径解析
- 实现书签创建和超链接替换功能
- 添加 link_body_citations 函数处理正文引用链接
- 在参考文献段落中添加书签标识
- 支持将 [N] 引用替换为指向参考文献的超链接

transit/body.py

@@ -7,6 +7,7 @@ Markdown 正文 → Word 段落转换。
 
 import re
 from copy import deepcopy
+from pathlib import Path
 
 from docx import Document
 from docx.oxml.ns import qn
@@ -15,12 +16,16 @@ from .images import make_image_paragraph, is_figure_caption, insert_image_paragr
 
 _PAT_HEADING = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
 
+# 匹配正文中的引用标记 [1] / [1,2,3]
+_CITE_PATTERN = re.compile(r"\[(\d+(?:[,，\s]*\d+)*)\]")
+
 
 def body_to_paragraphs(
     md_text: str,
     *,
     level_offset: int = 0,
     body_style: str = "Body Text Indent",
+    base_dir: str | Path | None = None,
 ) -> list[dict]:
     """将 Markdown 正文按标题和段落拆分为结构化列表。
 
@@ -32,6 +37,8 @@ def body_to_paragraphs(
         标题级别偏移量（正文从 ``##`` 开始时传 ``-1``，使其输出为 ``Heading 1``）。
     body_style : str
         正文段落的 Word 样式名。
+    base_dir : str | Path | None
+        Markdown 文件所在目录，用于解析图片相对路径。
     """
     paragraphs: list[dict] = []
     last_end = 0
@@ -41,7 +48,7 @@ def body_to_paragraphs(
         if not block:
             return
         # 图片段落
-        img = make_image_paragraph(block)
+        img = make_image_paragraph(block, base_dir)
         if img:
             paragraphs.append(img)
             return
@@ -103,6 +110,9 @@ def replace_placeholder(
 
             parent.remove(para._element)
 
+            # 为参考文献段落准备书签 ID
+            bm_id = _max_bookmark_id(doc) + 1
+
             for pd_data in reversed(paragraphs):
                 if pd_data.get("type") == "image":
                     insert_image_paragraphs(
@@ -134,12 +144,123 @@ def replace_placeholder(
                         new_pPr.append(deepcopy(numPr))
 
                     parent.insert(idx, new_p._element)
+
+                    # 为参考文献条目添加书签
+                    ref_id = pd_data.get("ref_id")
+                    if ref_id is not None:
+                        _add_bookmark(new_p, f"ref-{ref_id}", bm_id)
+                        bm_id += 1
             break
 
     if not placeholder_found:
         print(f"警告：未找到占位符 '{placeholder}'，正文段落未注入。")
 
 
+def link_body_citations(doc: Document):
+    """将文档中正文段落的 ``[N]`` 引用替换为指向对应书签的超链接。"""
+    for para in doc.paragraphs:
+        # 跳过已有超链接的段落（如目录页）
+        if para._element.findall(qn("w:hyperlink")):
+            continue
+        _link_paragraph(para)
+
+
+def _max_bookmark_id(doc: Document) -> int:
+    """扫描文档返回最大书签 ID。"""
+    max_id = 0
+    for para in doc.paragraphs:
+        for bm in para._element.iter(qn("w:bookmarkStart")):
+            try:
+                max_id = max(max_id, int(bm.get(qn("w:id"))))
+            except (ValueError, TypeError):
+                pass
+    return max_id
+
+
+def _add_bookmark(paragraph, name: str, bm_id: int):
+    """为段落添加书签。"""
+    bm_start = paragraph._element.makeelement(qn("w:bookmarkStart"), {})
+    bm_start.set(qn("w:id"), str(bm_id))
+    bm_start.set(qn("w:name"), name)
+
+    bm_end = paragraph._element.makeelement(qn("w:bookmarkEnd"), {})
+    bm_end.set(qn("w:id"), str(bm_id))
+
+    pPr = paragraph._element.find(qn("w:pPr"))
+    if pPr is not None:
+        paragraph._element.insert(1, bm_start)
+    else:
+        paragraph._element.insert(0, bm_start)
+    paragraph._element.append(bm_end)
+
+
+def _link_paragraph(para):
+    """将单个段落中的 ``[N]`` 替换为 HYPERLINK 域。"""
+    runs = list(para._element.findall(qn("w:r")))
+    if not runs:
+        return
+
+    full_text = ""
+    for r in runs:
+        t = r.find(qn("w:t"))
+        if t is not None and t.text:
+            full_text += t.text
+
+    matches = list(_CITE_PATTERN.finditer(full_text))
+    if not matches:
+        return
+
+    first_rPr = runs[0].find(qn("w:rPr"))
+    for r in runs:
+        para._element.remove(r)
+
+    pos = 0
+    for m in matches:
+        before = full_text[pos : m.start()]
+        if before:
+            _add_run(para._element, before, first_rPr)
+
+        nums = re.findall(r"\d+", m.group(1))
+        _add_hlink(para._element, f"ref-{nums[0]}", m.group())
+
+        pos = m.end()
+
+    after = full_text[pos:]
+    if after:
+        _add_run(para._element, after, first_rPr)
+
+
+def _add_run(parent, text: str, rPr):
+    r = parent.makeelement(qn("w:r"), {})
+    if rPr is not None:
+        r.append(deepcopy(rPr))
+    t = r.makeelement(qn("w:t"), {})
+    t.text = text
+    r.append(t)
+    parent.append(r)
+
+
+def _add_hlink(parent, anchor: str, text: str):
+    hl = parent.makeelement(qn("w:hyperlink"), {})
+    hl.set(qn("w:anchor"), anchor)
+
+    r = parent.makeelement(qn("w:r"), {})
+    rPr = r.makeelement(qn("w:rPr"), {})
+    rStyle = rPr.makeelement(qn("w:rStyle"), {})
+    rStyle.set(qn("w:val"), "Hyperlink")
+    rPr.append(rStyle)
+    vertAlign = rPr.makeelement(qn("w:vertAlign"), {})
+    vertAlign.set(qn("w:val"), "superscript")
+    rPr.append(vertAlign)
+    r.append(rPr)
+
+    t = r.makeelement(qn("w:t"), {})
+    t.text = text
+    r.append(t)
+    hl.append(r)
+    parent.append(hl)
+
+
 def _apply_style(paragraph, doc, style_name: str) -> bool:
     """尝试给段落应用样式，成功返回 ``True``。"""
     try: