docxnote 0.1.0__tar.gz

docxnote-0.1.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.3
+Name: docxnote
+Version: 0.1.0
+Summary: Lightweight DOCX comment engine based on text view API
+Author: touken
+Author-email: touken <touken928@foxmail.com>
+Requires-Dist: lxml>=5.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Docxnote
+
+**docxnote** 是一个轻量级 **DOCX 批注引擎**，仅依赖 lxml，用于自动化添加 Word 批注。
+
+该库直接操作 **WordprocessingML**，将 DOCX 视为 **ZIP + XML** 文档，并提供一个 **基于文本视图的 API**。
+
+与传统 DOCX 库不同，docxnote **完全隐藏 Word 的 Run 结构**，所有操作都基于 **段落字符串**。
+
+---
+
+## 安装
+
+```
+pip install git+https://github.com/touken928/docxnote.git
+```
+
+使用 [uv](https://github.com/astral-sh/uv)：
+
+```
+uv add git+https://github.com/touken928/docxnote.git
+```
+
+---
+
+## 快速开始
+
+```python
+from docxnote import DocxDocument, Paragraph, Table
+
+# 读取文档
+with open("document.docx", "rb") as f:
+    # 默认不保留原有批注（会清空）
+    doc = DocxDocument.parse(f.read())
+
+    # 如需保留原有批注并继续添加：
+    # doc = DocxDocument.parse(f.read(), keep_comments=True)
+
+# 遍历文档块
+for block in doc.blocks():
+    if isinstance(block, Paragraph):
+        # 为段落添加批注
+        if block.text:
+            block.comment("请检查表述", end=5, author="reviewer")
+    
+    elif isinstance(block, Table):
+        # 处理表格
+        rows, cols = block.shape()
+        for r in range(rows):
+            for c in range(cols):
+                cell = block[r, c]
+                # 为单元格内容添加批注
+                for inner in cell.blocks():
+                    if isinstance(inner, Paragraph) and inner.text:
+                        inner.comment("需复核", end=3, author="reviewer")
+
+# 生成新文档
+output = doc.render()
+with open("output.docx", "wb") as f:
+    f.write(output)
+```
+
+---
+
+## API
+
+### DocxDocument
+
+DOCX 文档对象。
+
+#### parse
+
+```python
+DocxDocument.parse(docx_bytes, *, keep_comments=False)
+```
+
+解析 DOCX 并构建文档对象。
+
+- **keep_comments**: 是否保留原有批注。默认 `False`（清空所有原有批注）。如果你需要在“已有批注的 docx 上继续添加批注”并保留旧批注，请传 `True`。
+
+---
+
+#### blocks
+
+```python
+doc.blocks()
+```
+
+返回文档中的块级元素：
+
+```python
+(Paragraph | Table, ...)
+```
+
+顺序与 Word 文档一致。
+
+---
+
+#### render
+
+```python
+doc.render()
+```
+
+生成新的 DOCX 并返回 `bytes`。
+
+所有批注在此阶段写入文档。
+
+#### 多线程
+
+同一 `DocxDocument` 实例可在多线程中安全使用（内部使用可重入锁串行化访问）；不同实例可并行处理。多进程请各自 `parse` 得到独立实例。
+
+---
+
+### Paragraph
+
+表示 Word 段落。
+
+#### text
+
+```python
+text = paragraph.text
+```
+
+返回段落完整文本，保留换行符（`\n`）和制表符（`\t`）。
+
+---
+
+#### comment
+
+```python
+paragraph.comment(
+    text,           # 批注内容
+    start=0,        # 起始字符位置
+    end=None,       # 结束字符位置（None 表示到末尾）
+    *,
+    author="docxnote"  # 批注作者
+)
+```
+
+为段落文本范围添加批注。
+
+**示例：**
+
+```python
+paragraph.comment("需要修改", start=3, end=8, author="张三")
+```
+
+docxnote 会自动处理：
+
+- Run 分割
+- 批注锚点
+- comments.xml 写入
+- 文档关系更新
+
+---
+
+### Table
+
+表示 Word 表格。
+
+#### shape
+
+```python
+rows, cols = table.shape()
+```
+
+返回表格尺寸 `(行数, 列数)`。
+
+---
+
+#### 单元格访问
+
+```python
+cell = table[row, col]
+```
+
+返回 `Cell` 对象。支持访问所有坐标，包括合并单元格覆盖的区域。
+
+---
+
+### Cell
+
+表示表格单元格。
+
+#### blocks
+
+```python
+cell.blocks()
+```
+
+返回单元格中的块级元素：
+
+```python
+(Paragraph | Table, ...)
+```
+
+顺序与 Word 文档一致。
+
+---
+
+#### bounds
+
+```python
+top, left, bottom, right = cell.bounds()
+```
+
+返回单元格边界 `(top, left, bottom, right)`，使用左闭右开区间 `[top, bottom)` 和 `[left, right)`。
+
+对于未合并的单元格，返回 `(r, c, r+1, c+1)`。
+
+---
+
+## 高级用法
+
+### 处理嵌套表格
+
+```python
+for block in doc.blocks():
+    if isinstance(block, Table):
+        rows, cols = block.shape()
+        for r in range(rows):
+            for c in range(cols):
+                cell = block[r, c]
+                # 遍历单元格内的块（可能包含嵌套表格）
+                for inner_block in cell.blocks():
+                    if isinstance(inner_block, Table):
+                        # 处理嵌套表格
+                        inner_rows, inner_cols = inner_block.shape()
+                        # ...
+```
+
+### 多个批注
+
+```python
+# 为同一段落的不同位置添加多个批注
+paragraph.comment("批注1", start=0, end=5, author="张三")
+paragraph.comment("批注2", start=10, end=15, author="李四")
+paragraph.comment("批注3", start=20, end=25, author="王五")
+```
+
+### 处理合并单元格
+
+```python
+table = [b for b in doc.blocks() if isinstance(b, Table)][0]
+
+# 访问合并单元格
+cell = table[0, 0]
+top, left, bottom, right = cell.bounds()
+
+# 如果单元格跨越多行或多列
+if bottom - top > 1 or right - left > 1:
+    print(f"合并单元格：跨越 {bottom-top} 行，{right-left} 列")
+```
+
+---
+
+## 测试
+
+所有测试文档使用 python-docx 动态生成，不依赖外部文件，详见 [tests/README.md](tests/README.md)。
+
+---
+
+## 开发环境与提交规范
+
+### 克隆与依赖安装
+
+- **克隆仓库**：
+
+```bash
+git clone git@github.com:touken928/docxnote.git
+cd docxnote
+```
+
+- **同步开发依赖**（测试 + pre-commit 等）：
+
+```bash
+uv sync --group dev
+```
+
+### 预提交钩子（pre-commit）
+
+- **安装 pre-commit 钩子**（确保提交前自动格式化、lint、跑测试）：
+
+```bash
+uv run pre-commit install
+```
+
+之后每次 `git commit` 会自动运行：
+
+- `uv-lock`（保持 uv 依赖锁文件同步）
+- `ruff` / `ruff-format`（代码风格与静态检查）
+- `pytest via uv`（自动化测试）
+
+如需手动在本地检查所有文件，可以运行：
+
+```bash
+uv run pre-commit run --all-files
+```
+
+### 本地测试
+
+- 单次运行所有测试：
+
+```bash
+uv run pytest
+```
+
+### 发布到 PyPI
+
+使用 [Trusted Publisher（OIDC）](https://docs.pypi.org/trusted-publishers/) 时无需 PyPI API token；PyPI 中 **Environment name 留空** 即可，也无需在 GitHub 仓库里创建 `Environment`。推送形如 `v0.1.0` 的标签会触发 [`.github/workflows/publish.yml`](.github/workflows/publish.yml) 构建并上传。发布前请将 `pyproject.toml` 中的 `version` 与标签一致。
+
+---
+
+## SKILL
+
+- 本仓库附带 `SKILL.md`，用于指导对话型 / coding Agent 正确调用 `docxnote`。
+- 建议下载到本地并放置在（根据所用工具选择其一）：
+  - `.cursor/docxnote/SKILL.md`
+  - `.claude/docxnote/SKILL.md`
+- 在对话环境中使用本库时，让 Agent 优先参考该文件中的安装方式、推荐代码骨架与注意事项。

docxnote-0.1.0/README.md

@@ -0,0 +1,320 @@
+# Docxnote
+
+**docxnote** 是一个轻量级 **DOCX 批注引擎**，仅依赖 lxml，用于自动化添加 Word 批注。
+
+该库直接操作 **WordprocessingML**，将 DOCX 视为 **ZIP + XML** 文档，并提供一个 **基于文本视图的 API**。
+
+与传统 DOCX 库不同，docxnote **完全隐藏 Word 的 Run 结构**，所有操作都基于 **段落字符串**。
+
+---
+
+## 安装
+
+```
+pip install git+https://github.com/touken928/docxnote.git
+```
+
+使用 [uv](https://github.com/astral-sh/uv)：
+
+```
+uv add git+https://github.com/touken928/docxnote.git
+```
+
+---
+
+## 快速开始
+
+```python
+from docxnote import DocxDocument, Paragraph, Table
+
+# 读取文档
+with open("document.docx", "rb") as f:
+    # 默认不保留原有批注（会清空）
+    doc = DocxDocument.parse(f.read())
+
+    # 如需保留原有批注并继续添加：
+    # doc = DocxDocument.parse(f.read(), keep_comments=True)
+
+# 遍历文档块
+for block in doc.blocks():
+    if isinstance(block, Paragraph):
+        # 为段落添加批注
+        if block.text:
+            block.comment("请检查表述", end=5, author="reviewer")
+    
+    elif isinstance(block, Table):
+        # 处理表格
+        rows, cols = block.shape()
+        for r in range(rows):
+            for c in range(cols):
+                cell = block[r, c]
+                # 为单元格内容添加批注
+                for inner in cell.blocks():
+                    if isinstance(inner, Paragraph) and inner.text:
+                        inner.comment("需复核", end=3, author="reviewer")
+
+# 生成新文档
+output = doc.render()
+with open("output.docx", "wb") as f:
+    f.write(output)
+```
+
+---
+
+## API
+
+### DocxDocument
+
+DOCX 文档对象。
+
+#### parse
+
+```python
+DocxDocument.parse(docx_bytes, *, keep_comments=False)
+```
+
+解析 DOCX 并构建文档对象。
+
+- **keep_comments**: 是否保留原有批注。默认 `False`（清空所有原有批注）。如果你需要在“已有批注的 docx 上继续添加批注”并保留旧批注，请传 `True`。
+
+---
+
+#### blocks
+
+```python
+doc.blocks()
+```
+
+返回文档中的块级元素：
+
+```python
+(Paragraph | Table, ...)
+```
+
+顺序与 Word 文档一致。
+
+---
+
+#### render
+
+```python
+doc.render()
+```
+
+生成新的 DOCX 并返回 `bytes`。
+
+所有批注在此阶段写入文档。
+
+#### 多线程
+
+同一 `DocxDocument` 实例可在多线程中安全使用（内部使用可重入锁串行化访问）；不同实例可并行处理。多进程请各自 `parse` 得到独立实例。
+
+---
+
+### Paragraph
+
+表示 Word 段落。
+
+#### text
+
+```python
+text = paragraph.text
+```
+
+返回段落完整文本，保留换行符（`\n`）和制表符（`\t`）。
+
+---
+
+#### comment
+
+```python
+paragraph.comment(
+    text,           # 批注内容
+    start=0,        # 起始字符位置
+    end=None,       # 结束字符位置（None 表示到末尾）
+    *,
+    author="docxnote"  # 批注作者
+)
+```
+
+为段落文本范围添加批注。
+
+**示例：**
+
+```python
+paragraph.comment("需要修改", start=3, end=8, author="张三")
+```
+
+docxnote 会自动处理：
+
+- Run 分割
+- 批注锚点
+- comments.xml 写入
+- 文档关系更新
+
+---
+
+### Table
+
+表示 Word 表格。
+
+#### shape
+
+```python
+rows, cols = table.shape()
+```
+
+返回表格尺寸 `(行数, 列数)`。
+
+---
+
+#### 单元格访问
+
+```python
+cell = table[row, col]
+```
+
+返回 `Cell` 对象。支持访问所有坐标，包括合并单元格覆盖的区域。
+
+---
+
+### Cell
+
+表示表格单元格。
+
+#### blocks
+
+```python
+cell.blocks()
+```
+
+返回单元格中的块级元素：
+
+```python
+(Paragraph | Table, ...)
+```
+
+顺序与 Word 文档一致。
+
+---
+
+#### bounds
+
+```python
+top, left, bottom, right = cell.bounds()
+```
+
+返回单元格边界 `(top, left, bottom, right)`，使用左闭右开区间 `[top, bottom)` 和 `[left, right)`。
+
+对于未合并的单元格，返回 `(r, c, r+1, c+1)`。
+
+---
+
+## 高级用法
+
+### 处理嵌套表格
+
+```python
+for block in doc.blocks():
+    if isinstance(block, Table):
+        rows, cols = block.shape()
+        for r in range(rows):
+            for c in range(cols):
+                cell = block[r, c]
+                # 遍历单元格内的块（可能包含嵌套表格）
+                for inner_block in cell.blocks():
+                    if isinstance(inner_block, Table):
+                        # 处理嵌套表格
+                        inner_rows, inner_cols = inner_block.shape()
+                        # ...
+```
+
+### 多个批注
+
+```python
+# 为同一段落的不同位置添加多个批注
+paragraph.comment("批注1", start=0, end=5, author="张三")
+paragraph.comment("批注2", start=10, end=15, author="李四")
+paragraph.comment("批注3", start=20, end=25, author="王五")
+```
+
+### 处理合并单元格
+
+```python
+table = [b for b in doc.blocks() if isinstance(b, Table)][0]
+
+# 访问合并单元格
+cell = table[0, 0]
+top, left, bottom, right = cell.bounds()
+
+# 如果单元格跨越多行或多列
+if bottom - top > 1 or right - left > 1:
+    print(f"合并单元格：跨越 {bottom-top} 行，{right-left} 列")
+```
+
+---
+
+## 测试
+
+所有测试文档使用 python-docx 动态生成，不依赖外部文件，详见 [tests/README.md](tests/README.md)。
+
+---
+
+## 开发环境与提交规范
+
+### 克隆与依赖安装
+
+- **克隆仓库**：
+
+```bash
+git clone git@github.com:touken928/docxnote.git
+cd docxnote
+```
+
+- **同步开发依赖**（测试 + pre-commit 等）：
+
+```bash
+uv sync --group dev
+```
+
+### 预提交钩子（pre-commit）
+
+- **安装 pre-commit 钩子**（确保提交前自动格式化、lint、跑测试）：
+
+```bash
+uv run pre-commit install
+```
+
+之后每次 `git commit` 会自动运行：
+
+- `uv-lock`（保持 uv 依赖锁文件同步）
+- `ruff` / `ruff-format`（代码风格与静态检查）
+- `pytest via uv`（自动化测试）
+
+如需手动在本地检查所有文件，可以运行：
+
+```bash
+uv run pre-commit run --all-files
+```
+
+### 本地测试
+
+- 单次运行所有测试：
+
+```bash
+uv run pytest
+```
+
+### 发布到 PyPI
+
+使用 [Trusted Publisher（OIDC）](https://docs.pypi.org/trusted-publishers/) 时无需 PyPI API token；PyPI 中 **Environment name 留空** 即可，也无需在 GitHub 仓库里创建 `Environment`。推送形如 `v0.1.0` 的标签会触发 [`.github/workflows/publish.yml`](.github/workflows/publish.yml) 构建并上传。发布前请将 `pyproject.toml` 中的 `version` 与标签一致。
+
+---
+
+## SKILL
+
+- 本仓库附带 `SKILL.md`，用于指导对话型 / coding Agent 正确调用 `docxnote`。
+- 建议下载到本地并放置在（根据所用工具选择其一）：
+  - `.cursor/docxnote/SKILL.md`
+  - `.claude/docxnote/SKILL.md`
+- 在对话环境中使用本库时，让 Agent 优先参考该文件中的安装方式、推荐代码骨架与注意事项。

docxnote-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "docxnote"
+version = "0.1.0"
+description = "Lightweight DOCX comment engine based on text view API"
+readme = "README.md"
+authors = [
+    { name = "touken", email = "touken928@foxmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "lxml>=5.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.11,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    # 测试与开发工具
+    "pytest>=8.0.0",
+    "python-docx>=1.0.0",
+    "pre-commit>=4.5.1",
+]

docxnote-0.1.0/src/docxnote/__init__.py

@@ -0,0 +1,7 @@
+"""docxnote - 轻量级 DOCX 批注引擎"""
+
+from .document import DocxDocument
+from .paragraph import Paragraph
+from .table import Table, Cell
+
+__all__ = ["DocxDocument", "Paragraph", "Table", "Cell"]

docxnote-0.1.0/src/docxnote/document.py

@@ -0,0 +1,340 @@
+"""DOCX 文档解析和渲染"""
+
+import io
+import threading
+import zipfile
+from lxml import etree
+
+from .paragraph import Paragraph
+from .table import Table
+from .namespaces import NS
+
+
+class DocxDocument:
+    """DOCX 文档对象
+
+    同一 ``DocxDocument`` 实例可在多线程环境下安全使用（内部使用可重入锁串行化访问）。
+    不同实例之间无共享可变状态，可并行使用。多进程请各自持有独立实例。
+    """
+
+    def __init__(self, zip_data: bytes):
+        self._zip_data = zip_data
+        self._zip = zipfile.ZipFile(io.BytesIO(zip_data))
+        self._document_xml = None
+        self._body = None
+        self._comments = []
+        self._comment_id_counter = 0
+        self._lock = threading.RLock()
+
+    @classmethod
+    def parse(cls, docx_bytes: bytes, *, keep_comments: bool = False) -> "DocxDocument":
+        """解析 DOCX 并构建文档对象
+
+        Args:
+            keep_comments: 是否保留原有批注。默认 False（清空所有原有批注）。
+        """
+        doc = cls(docx_bytes)
+        doc._load_document(keep_comments=keep_comments)
+        return doc
+
+    def _load_document(self, *, keep_comments: bool):
+        """加载 document.xml，并按需保留/清空原有批注"""
+        doc_xml = self._zip.read("word/document.xml")
+        self._document_xml = etree.fromstring(doc_xml)
+        self._body = self._document_xml.find(".//w:body", NS)
+
+        if keep_comments:
+            # 加载已有的批注
+            self._load_existing_comments()
+        else:
+            # 默认不保留：清空 comments 列表，并移除 document.xml 中的批注标记
+            self._comments = []
+            self._comment_id_counter = 0
+            self._strip_all_comment_markers()
+
+    def _strip_all_comment_markers(self) -> None:
+        """移除 document.xml 中所有批注相关标记，避免残留引用。"""
+        if self._document_xml is None:
+            return
+
+        # commentRangeStart / commentRangeEnd
+        for tag in ("commentRangeStart", "commentRangeEnd"):
+            for el in self._document_xml.findall(f".//w:{tag}", NS):
+                parent = el.getparent()
+                if parent is not None:
+                    parent.remove(el)
+
+        # commentReference 位于 w:r 内；移除后若 run 为空则一并移除
+        for ref in self._document_xml.findall(".//w:commentReference", NS):
+            run = ref.getparent()
+            if run is None:
+                continue
+            run.remove(ref)
+            if (
+                len(run) == 0
+                and (run.text is None)
+                and (run.tail is None or run.tail == "")
+            ):
+                parent = run.getparent()
+                if parent is not None:
+                    parent.remove(run)
+
+    def _load_existing_comments(self):
+        """加载已有的批注"""
+        try:
+            comments_xml = self._zip.read("word/comments.xml")
+            comments_tree = etree.fromstring(comments_xml)
+
+            max_id = -1
+            for comment in comments_tree:
+                comment_id_str = comment.get(f"{{{NS['w']}}}id")
+                if comment_id_str:
+                    comment_id = int(comment_id_str)
+                    max_id = max(max_id, comment_id)
+
+                    # 提取批注内容
+                    author = comment.get(f"{{{NS['w']}}}author", "")
+                    text = self._extract_comment_text(comment)
+
+                    self._comments.append((comment_id, text, author))
+
+            # 设置下一个批注 ID
+            self._comment_id_counter = max_id + 1
+        except KeyError:
+            # 没有 comments.xml 文件
+            pass
+
+    def _extract_comment_text(self, comment_element: etree._Element) -> str:
+        """从 w:comment 中提取完整文本（按 w:p 插入换行）。"""
+        parts: list[str] = []
+        first_para = True
+
+        # comments.xml 内部结构通常是多个 w:p
+        for p in comment_element.findall(".//w:p", NS):
+            if not first_para:
+                parts.append("\n")
+            first_para = False
+
+            for run in p.findall(".//w:r", NS):
+                for child in run:
+                    tag = etree.QName(child.tag).localname
+                    if tag == "t":
+                        if child.text:
+                            parts.append(child.text)
+                    elif tag == "br":
+                        parts.append("\n")
+                    elif tag == "tab":
+                        parts.append("\t")
+
+        return "".join(parts)
+
+    def blocks(self) -> tuple[Paragraph | Table, ...]:
+        """返回文档中的块级元素（元组）"""
+        with self._lock:
+            if self._body is None:
+                return ()
+
+            blocks: list[Paragraph | Table] = []
+            for child in self._body:
+                tag = etree.QName(child.tag).localname
+                if tag == "p":
+                    blocks.append(Paragraph(child, self))
+                elif tag == "tbl":
+                    blocks.append(Table(child, self))
+            return tuple(blocks)
+
+    def add_comment(self, text: str, author: str = "docxnote") -> int:
+        """添加批注并返回 ID"""
+        with self._lock:
+            comment_id = self._comment_id_counter
+            self._comment_id_counter += 1
+            self._comments.append((comment_id, text, author))
+            return comment_id
+
+    def render(self) -> bytes:
+        """生成新的 DOCX 并返回 bytes"""
+        with self._lock:
+            return self._render_unlocked()
+
+    def _render_unlocked(self) -> bytes:
+        output = io.BytesIO()
+
+        with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as out_zip:
+            # 准备 rels 和 content types（如果有批注）
+            rels_data = None
+            content_types_data = None
+            if self._comments:
+                rels_data = self._prepare_rels()
+                content_types_data = self._prepare_content_types()
+
+            # 复制所有原始文件
+            for item in self._zip.namelist():
+                if item == "word/document.xml":
+                    continue
+                if item == "word/comments.xml":
+                    continue
+                if item == "word/_rels/document.xml.rels" and rels_data is not None:
+                    continue
+                if item == "[Content_Types].xml" and content_types_data is not None:
+                    continue
+                out_zip.writestr(item, self._zip.read(item))
+
+            # 写入修改后的 document.xml
+            doc_bytes = etree.tostring(
+                self._document_xml,
+                xml_declaration=True,
+                encoding="UTF-8",
+                standalone=True,
+            )
+            out_zip.writestr("word/document.xml", doc_bytes)
+
+            # 写入 comments.xml、rels 和 content types
+            if self._comments:
+                comments_xml = self._build_comments_xml()
+                out_zip.writestr("word/comments.xml", comments_xml)
+                out_zip.writestr("word/_rels/document.xml.rels", rels_data)
+                out_zip.writestr("[Content_Types].xml", content_types_data)
+
+        return output.getvalue()
+
+    def _build_comments_xml(self) -> bytes:
+        """构建 comments.xml"""
+        root = etree.Element(f"{{{NS['w']}}}comments", nsmap=NS)
+
+        for comment_id, text, author in self._comments:
+            comment = etree.SubElement(
+                root,
+                f"{{{NS['w']}}}comment",
+                attrib={
+                    f"{{{NS['w']}}}id": str(comment_id),
+                    f"{{{NS['w']}}}author": author,
+                    f"{{{NS['w']}}}date": "2024-01-01T00:00:00Z",
+                    f"{{{NS['w']}}}initials": author[0].upper() if author else "D",
+                },
+            )
+
+            # 按换行拆分为多个段落，尽量保留原批注的多段结构
+            lines = text.split("\n")
+            if not lines:
+                lines = [""]
+
+            for line in lines:
+                p = etree.SubElement(comment, f"{{{NS['w']}}}p")
+                r = etree.SubElement(p, f"{{{NS['w']}}}r")
+
+                # 处理 tab：用 w:tab 表示
+                if "\t" in line:
+                    buf: list[str] = []
+                    for ch in line:
+                        if ch == "\t":
+                            if buf:
+                                t = etree.SubElement(r, f"{{{NS['w']}}}t")
+                                seg = "".join(buf)
+                                if seg[:1] == " " or seg[-1:] == " ":
+                                    t.set(
+                                        "{http://www.w3.org/XML/1998/namespace}space",
+                                        "preserve",
+                                    )
+                                t.text = seg
+                                buf.clear()
+                            etree.SubElement(r, f"{{{NS['w']}}}tab")
+                        else:
+                            buf.append(ch)
+                    if buf or line == "":
+                        t = etree.SubElement(r, f"{{{NS['w']}}}t")
+                        seg = "".join(buf)
+                        if seg[:1] == " " or seg[-1:] == " ":
+                            t.set(
+                                "{http://www.w3.org/XML/1998/namespace}space",
+                                "preserve",
+                            )
+                        t.text = seg
+                else:
+                    t = etree.SubElement(r, f"{{{NS['w']}}}t")
+                    if line[:1] == " " or line[-1:] == " ":
+                        t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+                    t.text = line
+
+        return etree.tostring(
+            root, xml_declaration=True, encoding="UTF-8", standalone=True
+        )
+
+    def _prepare_rels(self) -> bytes:
+        """准备 document.xml.rels 数据以包含 comments.xml 关系"""
+        rels_path = "word/_rels/document.xml.rels"
+
+        try:
+            rels_data = self._zip.read(rels_path)
+            rels_xml = etree.fromstring(rels_data)
+        except KeyError:
+            # 创建新的 rels
+            rels_xml = etree.Element(
+                "Relationships",
+                nsmap={
+                    "": "http://schemas.openxmlformats.org/package/2006/relationships"
+                },
+            )
+
+        # 检查是否已有 comments 关系
+        has_comments = False
+        for rel in rels_xml:
+            if (
+                rel.get("Type")
+                == "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
+            ):
+                has_comments = True
+                break
+
+        if not has_comments:
+            # 添加 comments 关系
+            max_id = 0
+            for rel in rels_xml:
+                rel_id = rel.get("Id", "")
+                if rel_id.startswith("rId"):
+                    try:
+                        num = int(rel_id[3:])
+                        max_id = max(max_id, num)
+                    except ValueError:
+                        pass
+
+            etree.SubElement(
+                rels_xml,
+                "Relationship",
+                attrib={
+                    "Id": f"rId{max_id + 1}",
+                    "Type": "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments",
+                    "Target": "comments.xml",
+                },
+            )
+
+        return etree.tostring(rels_xml, xml_declaration=True, encoding="UTF-8")
+
+    def _prepare_content_types(self) -> bytes:
+        """准备 [Content_Types].xml 数据以包含 comments.xml"""
+        ct_data = self._zip.read("[Content_Types].xml")
+        ct_xml = etree.fromstring(ct_data)
+
+        # 获取命名空间
+        ns = ct_xml.nsmap.get(
+            None, "http://schemas.openxmlformats.org/package/2006/content-types"
+        )
+
+        # 检查是否已有 comments.xml 的 Override
+        has_comments_override = False
+        for override in ct_xml:
+            if override.get("PartName") == "/word/comments.xml":
+                has_comments_override = True
+                break
+
+        if not has_comments_override:
+            # 添加 comments.xml 的 Override
+            override_elem = etree.Element(
+                f"{{{ns}}}Override",
+                attrib={
+                    "PartName": "/word/comments.xml",
+                    "ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml",
+                },
+            )
+            ct_xml.append(override_elem)
+
+        return etree.tostring(ct_xml, xml_declaration=True, encoding="UTF-8")

docxnote-0.1.0/src/docxnote/namespaces.py

@@ -0,0 +1,7 @@
+"""XML 命名空间定义"""
+
+NS = {
+    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+    "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+}

docxnote-0.1.0/src/docxnote/paragraph.py

@@ -0,0 +1,143 @@
+"""段落处理"""
+
+from lxml import etree
+from .namespaces import NS
+
+
+class Paragraph:
+    """表示 Word 段落"""
+
+    def __init__(self, element, document):
+        self._element = element
+        self._document = document
+        self._text_cache = None
+
+    @property
+    def text(self) -> str:
+        """返回段落完整文本"""
+        with self._document._lock:
+            if self._text_cache is not None:
+                return self._text_cache
+
+            text_parts = []
+            for run in self._element.findall(".//w:r", NS):
+                # 遍历 run 的所有子元素，保持顺序
+                for child in run:
+                    tag = etree.QName(child.tag).localname
+                    if tag == "t":
+                        # 文本节点
+                        if child.text:
+                            text_parts.append(child.text)
+                    elif tag == "br":
+                        # 换行符
+                        text_parts.append("\n")
+                    elif tag == "tab":
+                        # 制表符
+                        text_parts.append("\t")
+
+            self._text_cache = "".join(text_parts)
+            return self._text_cache
+
+    def comment(
+        self,
+        text: str,
+        start: int = 0,
+        end: int | None = None,
+        *,
+        author: str = "docxnote",
+    ):
+        """为段落文本范围添加批注"""
+        with self._document._lock:
+            if end is None:
+                end = len(self.text)
+
+            # 获取批注 ID
+            comment_id = self._document.add_comment(text, author)
+
+            # 在段落中插入批注标记
+            self._insert_comment_markers(comment_id, start, end)
+
+    def _insert_comment_markers(self, comment_id: int, start: int, end: int):
+        """在指定位置插入批注起止标记"""
+        runs = list(self._element.findall(".//w:r", NS))
+        if not runs:
+            return
+
+        # 计算字符位置到 run 的映射
+        run_positions = []
+        current_pos = 0
+
+        for run in runs:
+            run_start = current_pos
+            run_text = ""
+            for t in run.findall(".//w:t", NS):
+                if t.text:
+                    run_text += t.text
+            run_end = current_pos + len(run_text)
+            run_positions.append((run, run_start, run_end, run_text))
+            current_pos = run_end
+
+        # 找到需要分割的 run
+        start_run_idx = None
+        end_run_idx = None
+
+        for idx, (run, run_start, run_end, run_text) in enumerate(run_positions):
+            if start_run_idx is None and run_start <= start < run_end:
+                start_run_idx = idx
+            if end_run_idx is None and run_start < end <= run_end:
+                end_run_idx = idx
+
+        if start_run_idx is None or end_run_idx is None:
+            return
+
+        # 分割 run 并插入标记
+        self._split_and_mark(
+            run_positions, start_run_idx, end_run_idx, start, end, comment_id
+        )
+
+    def _split_and_mark(
+        self, run_positions, start_idx, end_idx, start, end, comment_id
+    ):
+        """分割 run 并插入批注标记"""
+        # 简化实现：在第一个 run 前插入开始标记，在最后一个 run 后插入结束标记
+        start_run, start_pos, _, _ = run_positions[start_idx]
+        end_run, _, end_pos, _ = run_positions[end_idx]
+
+        # 创建批注范围开始标记
+        comment_start = etree.Element(
+            f"{{{NS['w']}}}commentRangeStart",
+            attrib={f"{{{NS['w']}}}id": str(comment_id)},
+        )
+
+        # 创建批注范围结束标记
+        comment_end = etree.Element(
+            f"{{{NS['w']}}}commentRangeEnd",
+            attrib={f"{{{NS['w']}}}id": str(comment_id)},
+        )
+
+        # 创建批注引用
+        comment_ref_run = etree.Element(f"{{{NS['w']}}}r")
+        etree.SubElement(
+            comment_ref_run,
+            f"{{{NS['w']}}}commentReference",
+            attrib={f"{{{NS['w']}}}id": str(comment_id)},
+        )
+
+        # 插入标记
+        parent = self._element
+
+        # 查找 run 在父元素中的位置
+        try:
+            children = list(parent)
+            start_run_pos = children.index(start_run)
+            end_run_pos = children.index(end_run)
+        except ValueError:
+            # run 不是直接子元素，跳过
+            return
+
+        # 在开始 run 之前插入开始标记
+        parent.insert(start_run_pos, comment_start)
+
+        # 在结束 run 之后插入结束标记和引用（注意索引偏移）
+        parent.insert(end_run_pos + 2, comment_end)
+        parent.insert(end_run_pos + 3, comment_ref_run)

docxnote-0.1.0/src/docxnote/table.py

@@ -0,0 +1,194 @@
+"""表格和单元格处理"""
+
+from __future__ import annotations
+
+from lxml import etree
+from .namespaces import NS
+
+
+class Table:
+    """表示 Word 表格"""
+
+    def __init__(self, element, document):
+        self._element = element
+        self._document = document
+        self._grid = None
+        self._build_grid()
+
+    def _build_grid(self):
+        """构建表格网格，处理合并单元格"""
+        # 只查找直接子行，不包括嵌套表格的行
+        rows = self._element.findall("./w:tr", NS)
+        if not rows:
+            self._grid = []
+            return
+
+        # 构建一个“展开到坐标”的网格：同一合并区域的所有坐标都指向起始 Cell
+        self._grid = []
+        row_maps: list[dict[int, Cell]] = []
+        active_vmerge: dict[
+            int, Cell
+        ] = {}  # col -> origin cell (for current/next rows)
+        max_cols = 0
+
+        for r_idx, row in enumerate(rows):
+            # 只查找直接子单元格
+            tcs = row.findall("./w:tc", NS)
+
+            row_map: dict[int, Cell] = {}
+            col_idx = 0
+
+            for tc in tcs:
+                # 跳过被上方 vMerge 占用的列位置
+                while col_idx in row_map:
+                    col_idx += 1
+
+                colspan = 1
+                vmerge_val: str | None = None
+
+                tc_pr = tc.find("./w:tcPr", NS)
+                if tc_pr is not None:
+                    gridspan = tc_pr.find("./w:gridSpan", NS)
+                    if gridspan is not None:
+                        val = gridspan.get(f"{{{NS['w']}}}val")
+                        if val:
+                            colspan = int(val)
+
+                    vmerge = tc_pr.find("./w:vMerge", NS)
+                    if vmerge is not None:
+                        vmerge_val = vmerge.get(f"{{{NS['w']}}}val")
+
+                is_vmerge_continue = vmerge_val is None and (
+                    tc_pr is not None and tc_pr.find("./w:vMerge", NS) is not None
+                )
+                if vmerge_val is not None:
+                    is_vmerge_continue = vmerge_val != "restart"
+
+                if is_vmerge_continue:
+                    origin = active_vmerge.get(col_idx)
+                    if origin is None:
+                        origin = Cell(tc, self._document, r_idx, col_idx, colspan)
+                    else:
+                        origin._grow_rowspan_to(r_idx + 1)
+                else:
+                    origin = Cell(tc, self._document, r_idx, col_idx, colspan)
+                    # 新单元格覆盖同列：意味着上方 vMerge 在该列结束
+                    for i in range(colspan):
+                        active_vmerge.pop(col_idx + i, None)
+
+                    # 如果当前单元格是 vMerge restart，则开启纵向合并跟踪
+                    if vmerge_val == "restart" or (
+                        tc_pr is not None
+                        and tc_pr.find("./w:vMerge", NS) is not None
+                        and vmerge_val == "restart"
+                    ):
+                        for i in range(colspan):
+                            active_vmerge[col_idx + i] = origin
+
+                for i in range(colspan):
+                    row_map[col_idx + i] = origin
+
+                col_idx += colspan
+
+            # 将本行未显式出现但仍在 vMerge 中的列补齐
+            for c, origin in active_vmerge.items():
+                if c not in row_map:
+                    origin._grow_rowspan_to(r_idx + 1)
+                    row_map[c] = origin
+
+            if row_map:
+                max_cols = max(max_cols, max(row_map.keys()) + 1)
+            row_maps.append(row_map)
+
+        # 生成最终 grid：每行是“实际出现过的 Cell（去重）”列表（用于 bounds/shape 辅助）
+        for r_idx, row_map in enumerate(row_maps):
+            seen: set[int] = set()
+            grid_row: list[Cell] = []
+            for c in range(max_cols):
+                cell = row_map.get(c)
+                if cell is None:
+                    continue
+                if id(cell) in seen:
+                    continue
+                seen.add(id(cell))
+                grid_row.append(cell)
+            self._grid.append(grid_row)
+
+        # 另外保存一个坐标展开矩阵，供 __getitem__ 精确返回合并起点单元格
+        self._matrix: list[list[Cell]] = []
+        for r_idx, row_map in enumerate(row_maps):
+            matrix_row: list[Cell] = []
+            for c in range(max_cols):
+                matrix_row.append(
+                    row_map.get(c) or Cell(None, self._document, r_idx, c, 1)
+                )
+            self._matrix.append(matrix_row)
+
+    def shape(self) -> tuple[int, int]:
+        """返回表格尺寸 (rows, cols)"""
+        if not self._grid:
+            return (0, 0)
+        rows = len(self._grid)
+        cols = (
+            len(getattr(self, "_matrix", [[]])[0])
+            if getattr(self, "_matrix", None)
+            else 0
+        )
+        return (rows, cols)
+
+    def __getitem__(self, key: tuple[int, int]) -> "Cell":
+        """返回 Cell 对象"""
+        row, col = key
+        matrix = getattr(self, "_matrix", None)
+        if (
+            matrix is not None
+            and 0 <= row < len(matrix)
+            and 0 <= col < len(matrix[row])
+        ):
+            return matrix[row][col]
+        return Cell(None, self._document, row, col, 1)
+
+
+class Cell:
+    """表示表格单元格"""
+
+    def __init__(self, element, document, row: int, col: int, colspan: int = 1):
+        self._element = element
+        self._document = document
+        self._row = row
+        self._col = col
+        self._colspan = colspan
+        self._rowspan = 1
+
+    def _grow_rowspan_to(self, bottom_exclusive: int) -> None:
+        """将 rowspan 扩展到指定 bottom（左闭右开）"""
+        self._rowspan = max(self._rowspan, bottom_exclusive - self._row)
+
+    def blocks(self) -> tuple:
+        """返回单元格中的块级元素（元组）"""
+        with self._document._lock:
+            if self._element is None:
+                return ()
+
+            from .paragraph import Paragraph
+
+            blocks: list = []
+            for child in self._element:
+                tag = etree.QName(child.tag).localname
+                if tag == "p":
+                    blocks.append(Paragraph(child, self._document))
+                elif tag == "tbl":
+                    blocks.append(Table(child, self._document))
+            return tuple(blocks)
+
+    def bounds(self) -> tuple[int, int, int, int]:
+        """返回单元格边界 (top, left, bottom, right)"""
+        if self._element is None:
+            return (self._row, self._col, self._row + 1, self._col + 1)
+
+        return (
+            self._row,
+            self._col,
+            self._row + self._rowspan,
+            self._col + self._colspan,
+        )