Question 1

如何修复安装 python-docx 后 DOCX 表格被移动到提取文本末尾的问题？

Accepted Answer

当解析器先读取 `document.paragraphs`、再读取 `document.tables` 时就会发生这种情况，这会丢失它们在 Word 正文中的交错顺序。请将 `book-to-skill` 升级到包含 DOCX 顺序修复的版本；修复后的解析器会按文档顺序遍历正文块，通常使用 `document.iter_inner_content()`，按 `Paragraph` 和 `Table` 对象出现的顺序处理它们。在不支持有序块遍历的旧版 `python-docx` 上，它会回退到标准库的 ZIP/XML 解析器。作为即时变通方案，可以在你的虚拟环境中运行 `pip uninstall python-docx` 来强制启用回退路径，或者直接调用 `extract_docx_with_zipfile("document.docx")`。请验证出现在第 2 章之前的表格是否在 `Chapter 2` 标题之前被提取出来。

Question 2

如何修复 pytest 在 CI 中显示 bs4 和 trafilatura 的 5 个测试被跳过的问题？

Accepted Answer

这些测试被跳过是因为它们使用 `pytest.importorskip` 来要求可选包。在专用的 CI 作业中安装仅用于测试的依赖项：

```yaml
optional-deps:
  name: test (optional deps installed)
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: "3.12"
    - run: pip install pytest beautifulsoup4 trafilatura
    - run: pytest tests/ -q
```

保持现有的无依赖项作业不变。要在本地验证：

```bash
pip install pytest beautifulsoup4 trafilatura
python3 -m pytest tests/ -q
```

安装这两个包后，结果从 `698 passed, 5 skipped` 变为 `703 passed, 0 skipped`。受影响的测试是 `tests/test_html_block_boundaries.py` 中由 `bs4` 门控的测试，以及 `tests/test_html_boilerplate_extraction.py` 中四个由 `trafilatura` 门控的测试。

Question 3

为什么 metadata.json 中每个来源的 chapter_headings_sample 都缺失？

Accepted Answer

`book_to_skill/utils.py` 中的 CLI 元数据投影复制了 `chapters_detected` 和 `chapters_method`，但遗漏了按来源的 `chapter_headings_sample`；只有合并后的顶层示例被序列化。请升级到包含 PR #245（提交 `b27360ccfc2f92e0a6571dac03e32389a6e4cfe4`）的构建版本：

```sh
pip install git+https://github.com/virgiliojr94/book-to-skill.git@b27360ccfc2f92e0a6571dac03e32389a6e4cfe4
```

然后重新运行提取，例如：

```sh
BOOK_SKILL_WORKDIR="$PWD/repro-output" python3 scripts/extract.py alpha.md beta.md --mode text --install-missing no
```

如果在本地修补 1.4.0 版本，请在 `main()` 中将现有的提取结果添加到每个来源对象中，置于其他章节字段旁边，使用保存 `extract_single_file()` 输出的变量：

```python
"chapter_headings_sample": source.get("chapter_headings_sample", []),
```

不要重新计算示例，也不要分配合并后的顶层示例，因为这可能会把第一个来源的标题附加到后续的来源上。必须保留空列表和 Unicode 标题。使用 `pytest -q` 和 `ruff check .` 进行验证。

Question 4

如何修复当 OPF manifest 的 href 包含片段或百分号编码的文件名时,stdlib EPUB fallback 静默跳过章节的问题?

Accepted Answer

升级到包含 PR `fix(epub): resolve encoded manifest hrefs` 的版本；该 bug 存在于提交 `f08d343` 中。修补 fallback 时，不要将原始的 OPF `href` 直接传递给 `ZipFile.read()`。首先相对于 OPF 目录解析它，移除 query/fragment 部分，并解码百分号转义：

```python
import posixpath
from urllib.parse import urlsplit, unquote

def manifest_member_name(opf_path, href):
    href_path = urlsplit(href).path  # drops ?query and #fragment
    href_path = unquote(href_path)  # Chapter%201.xhtml -> Chapter 1.xhtml
    return posixpath.normpath(posixpath.join(posixpath.dirname(opf_path), href_path))
```

然后调用 `zf.read(manifest_member_name(opf_path, href))`。诸如 ElementTree 之类的 XML 解析器已经会解码属性值中的 XML 实体。因此，`chapter.xhtml#section-2` 会解析为 `chapter.xhtml`，而来自 `OEBPS/content.opf` 的 `Text/Chapter%201.xhtml` 会解析为 `OEBPS/Text/Chapter 1.xhtml`。

Question 5

如何修复不可见的 Unicode Default_Ignorable 字符（如蒙古文 FVS、高棉语固有元音和 Shorthand format controls）未被去除或检测到的问题？

Accepted Answer

修补 `book_to_skill/sanitize.py::is_invisible_codepoint()`，使其包含完整缺失的已分配 `Default_Ignorable_Code_Point=Yes` 码点集合：`U+17B4`、`U+17B5`、`U+180B`、`U+180C`、`U+180D`、`U+1BCA0`、`U+1BCA1`、`U+1BCA2` 和 `U+1BCA3`。例如，将它们的标量值添加到共享的不可见码点集合中：`0x17B4, 0x17B5, 0x180B, 0x180C, 0x180D, 0x1BCA0, 0x1BCA1, 0x1BCA2, 0x1BCA3`。不要维护单独的扫描器列表：`tools/scan_generated_skill.py` 导入的是同一个谓词，因此更新该谓词即可让提取过程去除这些字符，并让扫描器一致地报告相同的集合。该问题已在 Python 3.9.5（Unicode 13.0.0）环境下验证；全部九个码点在该版本中均已分配。修补完成后，重新运行测试套件，并重新生成/重新扫描受影响的技能。

book-to-skill

项目简介

README 预览

常见问题 (5)

同类型项目

hermes-agent

firecrawl

go

markitdown