PDF 转结构化 Markdown

将 PDF 文件内容抽取为结构化 Markdown 知识文档。

⚠️ 前置要求：OCR API 密钥

扫描件 OCR 功能必须配置 API 密钥才能使用。本 Skill 不会自动向第三方平台注册账号。

配置方式

获取 API 密钥：前往 https://xiaobenyang.com 注册账号并获取密钥（由用户自行完成，Skill 不会代为注册）
保存密钥：拿到用户提供的密钥后，调用 scripts.config.set_api_key(api_key) 保存到 .env 文件，方便下次使用
环境变量备选：用户也可手动配置环境变量 XBY_APIKEY

密钥检查流程

在启动 OCR 前检查密钥：

已配置（环境变量或 .env）→ 继续 OCR 流程
未配置 → 使用 AskUserQuestion 询问用户密钥 → 用户确认后调用 set_api_key() 保存 → 继续 OCR 流程

安全声明

不自动注册：Skill 不会向任何第三方平台发起注册请求，账号注册必须由用户自行完成
仅保存用户主动提供的密钥：set_api_key() 仅保存用户通过 AskUserQuestion 主动提供的密钥
不会凭空生成密钥：禁止在缺少密钥时自行搜索或编造数据

行为准则

诚实：不编造原文中没有的内容，不猜测不确定的知识点，不擅自补充自己"觉得应该有"的东西
如实反映：原文说什么就整理什么，理解偏差或遗漏时如实标注
主动询问：遇到以下情况必须停下来询问使用者，不要自行决定：
- PDF 内容模糊、残缺、无法理解时
- 不确定某个知识点属于哪个层级/分类时
- 不确定某个术语的含义或翻译时
- 不确定输出文件应该放在哪个目录时
- 不确定文件命名规则时
- 不确定知识抽取的粒度（详细还是精简）时
不耍小聪明：不要用看似合理但实际偏离原文的"优化"或"润色"来掩盖理解不足
图片不跳过：遇到图片必须判断其知识价值。若图片是操作指引、流程图、示意图、实例内容、表格截图或结构图，输出 Markdown 中必须保留图片引用，并在图片上下文处整理其含义
严禁借用外部内容（零容忍）：
- 知识整理的唯一来源是当前正在处理的 PDF 本身
- 禁止读取输出目录下已有的其它 _知识整理.md 文件来拼凑、补充、参考或"借鉴"内容
- 禁止读取其它已生成的 markdown 文件、wiki 文件或任何非当前 PDF 的文件来填充提取失败的部分
- 禁止根据文件名、目录结构或上下文推测其它 PDF 的内容并写入当前整理
- 当 PDF 提取效果不佳时，唯一正确的做法是：
  1. 如实告知使用者提取质量差
  2. 列出具体问题（乱码比例、缺失章节、无法识别的区域）
  3. 建议换用其它提取方式，或由使用者手动处理
  4. 宁可输出不完整的整理（标注缺失部分），也绝不用其它文件的内容伪造完整性
- 这条规则没有例外：即使其它文件的内容"看起来和当前 PDF 是同一本书"、"应该是相同的知识点"、"只是补充缺失的部分"，也不可以借用。不同 PDF 的内容可能存在差异、版本不同、编辑不同，借用就是欺骗
OCR 诚实原则（方式 D 专用）：
- OCR 识别内容是机器猜测结果，可信度低于原文提取
- 禁止"润色"OCR 结果：识别不清的必须标注 [OCR原文：xxx]，不得擅自猜测替换
- 单页 OCR 有效汉字 < 3 个 → 标注 [第X页 OCR 识别失败]
- 连续 3 页以上识别失败 → 向使用者汇报，建议手动处理
- 宁可遗漏，不可从其它文件或网络搜索内容填补 OCR 空缺

步骤 0：确认输出目录

在开始任何处理之前，必须先询问使用者：

知识整理 markdown 文件输出到哪个目录？
- 默认建议：PDF 所在目录下的 knowledge_md/ 子目录
- 使用者可指定任意目录
若输出目录不存在，需先创建
若需要导出图片，图片输出到输出目录下的 images/ 子目录

不要假设输出目录，必须明确确认。

步骤 1：环境检测与 PDF 读取

不同 agent 有不同的 PDF 读取能力。先检测当前环境，再选择最佳方式。

1.0 能力检测

按以下顺序检测当前 agent 支持哪些 PDF 读取方式：

┌─────────────────────────────────────────────────────┐
│ 检测 1：原生 PDF 视觉阅读                            │
│ 当前 agent 是否能直接"看"PDF 页面（作为图像）？       │
│                                                      │
│ 判断方法：                                            │
│ - 有 Read/File 工具且支持 pages 参数？               │
│ - 能读取 PDF 并以图像形式呈现内容？                   │
│ - 测试：读取 PDF 第 1 页，能否看到完整页面内容        │
│   （包括图片、表格、排版）？                          │
│                                                      │
│ 若 YES → 使用方式 A（原生视觉阅读）                  │
│ 若 NO  → 继续检测                                    │
└──────────────────────┬──────────────────────────────┘
                       │ NO
                       ▼
┌─────────────────────────────────────────────────────┐
│ 检测 2：Python 库可用性                              │
│                                                      │
│ 检查命令：                                            │
│   python -c "import fitz; print('PyMuPDF OK')"      │
│   python -c "import pdfplumber; print('pdfplumber OK')" │
│                                                      │
│ 若 PyMuPDF 可用 → 使用方式 B（文本+图片提取）        │
│ 若仅 pdfplumber  → 使用方式 C（文本+表格提取）       │
│ 若都不可用 → 继续检测                                │
└──────────────────────┬──────────────────────────────┘
                       │ NO
                       ▼
┌─────────────────────────────────────────────────────┐
│ 检测 3：安装 Python 库                               │
│                                                      │
│ 尝试安装：                                            │
│   pip install PyMuPDF pdfplumber                     │
│                                                      │
│ 安装成功 → 使用方式 B 或 C                           │
│ 安装失败 → 告知使用者，请求手动处理                   │
└─────────────────────────────────────────────────────┘

关键原则：能力检测必须实际验证，不能靠猜测。 不同 agent、不同环境的能力差异很大，必须通过实际测试确认。

方式 A：原生 PDF 视觉阅读（最优）

适用条件： 当前 agent 能通过 Read/File 等工具直接"看"PDF 页面（作为图像渲染）。

这是最佳方式，因为：

能看到完整的页面渲染，包括图片、图表、表格
能理解页面布局和视觉层次
中文文本不会出现乱码
能识别流程图、架构图、示意图并理解其含义

操作方法：

使用可用的文件读取工具读取 PDF，指定页码范围（若支持）
每次最多读取 20 页，大文件需分批读取
agent 直接看到页面内容，无需额外文本提取

Claude Code 示例：

Read(file_path="xxx.pdf", pages="1-20")

其他 agent： 使用各自平台提供的文件读取工具，只要能渲染 PDF 页面即可。

大文件处理策略：

对于超过 20 页的 PDF，按以下方式分批处理：

先读取前 20 页，了解文档整体结构
根据目录或章节结构，规划后续批次的页码范围
每批读取后，立即进行该批次的知识抽取
最后将所有批次的结果合并

分批时注意：

尽量按章节边界切分，不要在知识点中间断开
每批开始时回顾前一批的最后几个知识点，确保衔接
若某批内容与前批有重叠（章节跨页），合并时去重

页码获取：

若不确定 PDF 总页数，先用 Python 快速查询：

import fitz  # PyMuPDF
doc = fitz.open("input.pdf")
print(f"总页数: {len(doc)}")
doc.close()

若 PyMuPDF 不可用，可通过读取工具尝试不同页码范围来推断总页数。

方式 B：PyMuPDF 文本 + 图片提取（通用备选）

适用条件： 当前 agent 无法原生阅读 PDF，但可以运行 Python 脚本。

依赖检查：

python -c "import fitz; print(fitz.__version__)"

若未安装：pip install PyMuPDF

文本提取：

import fitz

doc = fitz.open("input.pdf")
for i, page in enumerate(doc):
    text = page.get_text("text")
    print(f"--- 第 {i+1} 页 ---")
    print(text)
doc.close()

图片提取：

import fitz
import os

doc = fitz.open("input.pdf")
output_dir = "images"
os.makedirs(output_dir, exist_ok=True)

for i, page in enumerate(doc):
    images = page.get_images(full=True)
    for j, img in enumerate(images):
        xref = img[0]
        base_image = doc.extract_image(xref)
        image_bytes = base_image["image"]
        image_ext = base_image["ext"]
        image_path = f"{output_dir}/p{i+1:03d}-img{j+1:02d}.{image_ext}"
        with open(image_path, "wb") as f:
            f.write(image_bytes)
        print(f"导出: {image_path}")

doc.close()

页面转图片（为无原生 PDF 阅读能力的 agent 提供视觉理解）：

当 agent 无法原生阅读 PDF，但仍需要理解图表/流程图时，可将 PDF 页面转为图片，再让 agent 读取图片：

import fitz
import os

doc = fitz.open("input.pdf")
output_dir = "page_images"
os.makedirs(output_dir, exist_ok=True)

for i, page in enumerate(doc):
    # 渲染页面为图片（200 DPI，平衡清晰度和文件大小）
    pix = page.get_pixmap(dpi=200)
    image_path = f"{output_dir}/page_{i+1:03d}.png"
    pix.save(image_path)
    print(f"导出: {image_path}")

doc.close()

然后使用 agent 的图片读取工具逐页查看，获得类似原生 PDF 阅读的效果。

适用场景： 通用备选方案，适用于所有能运行 Python 的 agent

方式 C：pdfplumber 表格提取（补充）

适用条件： 方式 A/B 的表格提取效果不佳，且 PDF 中包含大量结构化表格。

import pdfplumber

with pdfplumber.open("input.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"--- 第 {i+1} 页 表格 {j+1} ---")
            for row in table:
                print(row)

适用场景： 表格密集的 PDF，其他方式无法正确提取表格时的补充手段

方式 D：API OCR 识别（扫描件兜底）

适用条件： 方式 A/B/C 均无法获得可读文本（扫描件/图片型 PDF /大面积乱码）。

工作原理： 使用 OCR API 对 PDF 页面渲染图进行文字识别，兼顾速度与精度。

依赖检查：

python -c "import fitz; print('PyMuPDF OK')"
python -c "import requests; print('requests OK')"

若未安装：pip install PyMuPDF requests

API 密钥检查：

在使用 OCR 功能前，检查 API 密钥是否已配置：

from scripts.config import get_api_key
api_key = get_api_key()
if not api_key:
    # 使用 AskUserQuestion 向用户询问 API 密钥
    # 拿到后调用 scripts.config.set_api_key(api_key) 保存到 .env

获取 API 密钥：https://xiaobenyang.com（由用户自行注册，Skill 不会自动注册）

OCR 执行步骤：

页面渲染为图片：使用 PyMuPDF 将每一页渲染为 PNG 图片（200 DPI）
图片转 Base64：将图片文件编码为 Base64 格式
调用 OCR API：使用 scripts.tools.ocr_for_data_base64() 进行文字识别
整理结果：解析返回的 JSON，提取识别文本

OCR 执行脚本：

import fitz
import base64
import os
import sys

# 检查 API 密钥
from scripts.config import get_api_key
api_key = get_api_key()
if not api_key:
    print("错误：未配置 API 密钥")
    # 应使用 AskUserQuestion 询问用户密钥，然后调用 scripts.config.set_api_key(api_key) 保存
    sys.exit(1)

from scripts.tools import ocr_for_data_base64

doc = fitz.open("input.pdf")
output_dir = "temp_ocr_pages"
os.makedirs(output_dir, exist_ok=True)

for i, page in enumerate(doc):
    # 步骤 1：页面渲染为图片（200 DPI）
    pix = page.get_pixmap(dpi=200)
    img_path = f"{output_dir}/page_{i+1:03d}.png"
    pix.save(img_path)

    # 步骤 2：图片转 Base64
    with open(img_path, "rb") as f:
        img_bytes = f.read()
    img_base64 = base64.b64encode(img_bytes).decode("utf-8")

    # 步骤 3：调用 OCR API
    try:
        result = ocr_for_data_base64(dataBase64=img_base64)
        if result["success"]:
            raw = result["raw"]
            # 根据 API 返回格式提取文本
            text = ""
            if isinstance(raw, dict):
                # 尝试从常见字段提取文本
                text = raw.get("text", raw.get("result", raw.get("data", str(raw))))
            elif isinstance(raw, str):
                text = raw
            else:
                text = str(raw)

            print(f"--- 第 {i+1} 页 OCR ---")
            print(text if text.strip() else "[OCR 识别失败]")
        else:
            print(f"--- 第 {i+1} 页 OCR 失败 ---")
            print(f"[OCR 错误: {result.get('message', '未知错误')}]")
    except Exception as e:
        print(f"--- 第 {i+1} 页 OCR 异常 ---")
        print(f"[OCR 错误: {e}]")

doc.close()

临时文件清理：

OCR 执行完成后：

在知识整理文件头部标注 
询问使用者是否保留 temp_ocr_pages/ 目录
若使用者选择不保留，删除该目录

质量检查：

单页 OCR 有效汉字 < 50 字 → 输出警告
乱码比例 > 30% → 如实告知使用者效果不佳
连续 3 页以上全部失败 → 汇报并建议手动处理
质量不佳时遵守行为准则第 7 条（OCR 诚实原则）

方式选择决策树

开始处理 PDF
    │
    ├─ 步骤 1.0：能力检测
    │   │
    │   ├─ 有原生 PDF 视觉阅读能力？
    │   │   │
    │   │   ├─ YES → 使用方式 A，读取前 20 页测试
    │   │   │   │
    │   │   │   ├─ 内容清晰？ → 继续方式 A 分批读完全文
    │   │   │   │
    │   │   │   └─ 内容混乱？ → 回退到方式 B
    │   │   │
    │   │   └─ NO → 继续检测
    │   │
    │   ├─ 能运行 Python + PyMuPDF？
    │   │   │
    │   │   ├─ YES → 使用方式 B
    │   │   │   │
    │   │   │   ├─ 文本质量可接受？ → 继续
    │   │   │   │
    │   │   │   ├─ 需要看图表？ → 页面转图片（方式 B 的页面转图片功能）
    │   │   │   │
    │   │   │   └─ 表格提取差？ → 补充方式 C
    │   │   │
    │   │   └─ NO → 继续检测
    │   │
    │   ├─ 能安装 Python 库？
    │   │   │
    │   │   ├─ YES → pip install PyMuPDF pdfplumber → 回到方式 B
    │   │   │
    │   │   └─ NO → 告知使用者环境限制，请求协助
    │   │
    │   └─ 需要导出图片？ → 始终使用方式 B 的图片提取
    │
    └─ 以上所有方式文本质量均不可接受（扫描件/图片型 PDF）？
        │
        ├─ YES → 进入方式 D：API OCR 识别
        │   │
        │   ├─ 已配置 API 密钥（环境变量或 .env）？
        │   │   │
        │   │   ├─ YES → 执行 OCR
        │   │   │
        │   │   └─ NO → 使用 AskUserQuestion 询问密钥，用户确认后调用 set_api_key() 保存
        │   │       │
        │   │       └─ 用户无法提供密钥？ → 告知使用者环境限制，请求协助
        │   │
        │   └─ OCR 文本质量可接受？ → 进入步骤 2 知识抽取
        │       │
        │       └─ 仍不佳 → 如实告知，输出已提取部分并标注 `[OCR 识别失败]`
        │
        └─ NO → 继续流程

提取后质量检查

无论使用哪种方式，提取后必须检查：

文本完整性：是否有大量乱码、缺字、错位
结构完整性：章节标题、层级关系是否清晰
表格完整性：表格内容是否正确对齐，行列是否完整
图片覆盖：重要图表是否都被识别（方式 A）或导出（方式 B）

若质量不佳，如实告知使用者并建议换用其他方式。

质量不佳时的正确处理流程：

如实报告具体问题（"第 X-Y 页乱码严重"、"表格无法识别"、"图表内容缺失"）
建议换用其它提取方式重试
若所有方式均失败，告知使用者该 PDF 可能需要手动处理
可以输出已成功提取的部分，缺失部分标注 [提取失败]

质量不佳时的禁止行为：

禁止读取输出目录下其它 _知识整理.md 来"补充"缺失内容
禁止根据目录结构或文件名推测其它 PDF 的内容
禁止用任何非当前 PDF 来源的内容填充空缺
禁止在未告知使用者的情况下悄悄跳过提取失败的部分（必须显式标注）

步骤 1.5：图片处理

PDF 中的图片往往承载关键知识点，不能忽略。

使用原生视觉阅读时

agent 直接在页面渲染中看到图片，无需额外操作。在知识整理时：

识别图片类型：流程图、架构图、表格截图、操作界面、示意图等
文字化描述：将图片内容用文字描述出来，作为知识点的一部分
保留图片引用：若后续需要导出图片，在整理中标注图片位置和描述

使用 Python 库提取时

导出图片：使用方式 B 的图片提取脚本，将图片导出到 images/ 目录
在整理中引用：在对应知识点附近插入 Markdown 图片语法：
```
![图片说明](./images/p003-img01.png)
```
补充描述：图片引用后，用列表补充图片传达的知识点
页面转图片：若 agent 无法原生阅读 PDF 但需要理解图表，使用方式 B 的页面转图片功能，将页面渲染为 PNG 后用图片读取工具查看

使用 OCR 提取时

通过方式 D（OCR）提取时，图片已经在页面渲染中被 OCR API 处理。此时：

OCR 提取过程中，PyMuPDF 已将页面渲染为图片并存于 temp_ocr_pages/ 目录
若图片中包含关键知识（流程图、表格截图、示意图），判断是否需要保留这些 OCR 页面图片
保留方法：从 temp_ocr_pages/ 复制到 images/ 目录，使用标准 Markdown 图片语法引用
注意：OCR 仅为纯文本提取，图片描述需 agent 自己通过视觉理解补充，不得凭空编造

图片识别标准

以下图片必须在知识整理中保留引用或描述：

操作指引：菜单、按钮、配置步骤、软件界面、命令执行结果
实例内容：例题、案例页面、样例输入输出、运行截图
图表结构：流程图、架构图、状态转换图、关系图、表格截图、时序图
正文引用：原文出现"如图所示"、"见图X"、"上图"等
文本缺口：纯文本提取后出现明显空白，图片可能承载缺失信息

图片整理规则

图片放在对应标题、步骤、概念、例子下面，不要堆到文末
alt 文本写清图片在原文中的作用
图片引用后，用列表补充整理图片传达的知识点
无法完全理解时，仍保留引用并标注 [待确认]
图片路径使用相对路径：./images/[原PDF名]-p03-fig01.png

步骤 2：理解内容，知识抽取与整理

这是本 skill 的核心步骤。不是简单的文本搬运或格式转换，而是理解原文内容后重新组织。

2.1 先理解，再整理

逐页阅读提取的文本/页面，先建立对整体内容的理解
识别原文的章节结构和逻辑脉络
理解每个知识点的含义，而不是机械地复制原文句子
在理解的基础上，用自己的话重新组织表达，但严格忠于原文含义

2.2 层级结构识别

根据原文内容的章节编号或标题层级，提取三级标题结构：

| 层级 | Markdown 语法 | 对应内容 | |------|---------------|----------| | 顶层 | # [N]标题 | 章节/主题编号+名称 | | 中层 | ## 中文标题 | 大节标题 | | 底层 | ### 中文标题 | 小节标题 |

若原文层级不清晰或无法判断归属，询问使用者，不要自行猜测

2.3 知识点提取原则

去噪：过滤页眉页脚、AI生成提示（如"以下为AI生成的图文笔记的内容"）、页码、时间戳等非知识内容
忠于原文：不添加原文没有的内容，不删减原文明确提到的知识点
如实标注：原文表述模糊或自己理解不确定的地方，标注 [待确认] 并询问使用者
保留原文信息：易混淆点、补充说明、来源标注、条件限制等原文明确给出的信息必须保留；若原文包含考试、频率、分值、难度等内容，也只作为普通知识点整理，不单独建立考点栏目
合并同类项：将分散在同一主题下的相关内容合并，但合并后必须确认没有遗漏
识别对比关系：原文中明确对比的概念（如 CISC vs RISC、互斥 vs 同步），整理为并列子项
表格处理：原文中的表格内容，转换为 Markdown 表格或结构化列表，保留完整的行列信息

2.4 抽取粒度

默认粒度：保留原文中所有明确提到的知识点，不自行取舍
若使用者指定了粒度偏好（精简/详细），按偏好执行
若不确定某个细节是否值得保留，询问使用者

2.5 转换示例

原文：
"CISC(复杂指令集):
- 特点：指令数量多、长度不固定、执行效率较低
- 实现：微程序控制(软件方式)
RISC(精简指令集):
- 特点：指令精简、长度固定、执行效率高
- 实现：硬布线逻辑+大量寄存器(硬件加速)"

整理后：
- CISC（复杂指令集）：
    - 特点：指令数量多、长度不固定、执行效率较低
    - 实现：微程序控制（软件方式）
- RISC（精简指令集）：
    - 特点：指令精简、长度固定、执行效率高
    - 实现：硬布线逻辑+大量寄存器（硬件加速）

关键：整理后的内容与原文含义完全一致，只是结构和格式更清晰。

2.6 表格转换示例

原文表格：
┌──────────┬──────────┬──────────┐
│ 特性     │ CISC     │ RISC     │
├──────────┼──────────┼──────────┤
│ 指令数量 │ 多       │ 少       │
│ 指令长度 │ 不固定   │ 固定     │
│ 执行效率 │ 较低     │ 较高     │
└──────────┴──────────┴──────────┘

整理后（方式一：Markdown 表格）：
| 特性 | CISC | RISC |
|------|------|------|
| 指令数量 | 多 | 少 |
| 指令长度 | 不固定 | 固定 |
| 执行效率 | 较低 | 较高 |

整理后（方式二：结构化列表，适合知识点密集时）：
- CISC vs RISC 对比：
    - 指令数量：CISC 多，RISC 少
    - 指令长度：CISC 不固定，RISC 固定
    - 执行效率：CISC 较低，RISC 较高

步骤 3：严格格式化输出 Markdown

3.1 文件命名

[章节号]--标题_笔记.pdf  →  [章节号]--标题_知识整理.md

若不确定命名规则，询问使用者。

3.2 输出目录

默认输出到与 PDF 同目录的 knowledge_md/ 子目录。若使用者指定了其他目录，按指定目录输出。

3.3 Markdown 格式严格规范

标题层级：必须严格 # → ## → ###，不可跳级
列表标记：统一使用 - （不是 * 或 + ）
缩进：子层级缩进 4 个空格（不是 2 个，不是 tab）
空行：每个列表项后必须有一个空行（可以是完全空行，或仅含2个空格的行）
中文标点：正文使用中文全角标点（，。：（）），英文术语用英文括号
加粗：**术语** 仅用于首次出现的重要术语，不要滥用
不添加注释：不要在 markdown 中添加自己的评论或解释性注释

3.4 输出结构模板

# [N]主标题

## 第一大节

### 第一小节

- 核心概念：描述内容
    
- 关键特性：
    
    - 子特性1
        
    - 子特性2

### 第二小节

- 对比关系：
    
    - 类型A：特征描述
        
    - 类型B：特征描述

## 第二大节

### ...

3.5 典型模式速查

| 场景 | 格式 | |------|------| | 定义描述 | - 术语：一句话定义 | | 分类列举 | - 分类名： + 4空格缩进子项 | | 对比关系 | - X：特点 / - Y：特点 并列 | | 流程步骤 | - 步骤1 → 步骤2 → 步骤3 | | 例题分析 | - 例题：题目 + 4空格缩进 - 解析：过程 | | 不确定内容 | - [待确认] 描述 | | 表格 | Markdown 表格或结构化列表 |

批量处理

发现更多 PDF

当使用者指定处理某个 PDF 时，检查该 PDF 所在目录下是否还有其他 PDF 文件：

扫描 PDF 所在目录，列出所有 .pdf 文件
排除已处理的（输出目录中已有对应 _知识整理.md 的）
若存在未处理的 PDF，询问使用者：
- "发现目录下还有 N 个未处理的 PDF，是否一并处理？"
- 列出未处理 PDF 的文件名供使用者选择
- 使用者可选择：全部处理 / 选择部分 / 不处理

批量处理流程

确认要处理的 PDF 列表
逐个处理，每个 PDF 独立生成一个 markdown 文件
可并行处理多个 PDF 以提高效率（若当前 agent 支持并行任务/子代理派发）
若某个 PDF 提取失败或内容无法理解，如实报告，不要跳过隐瞒
处理完成后汇总报告：成功数量、失败数量、失败原因

并行处理策略

对于批量处理，若当前 agent 支持并行任务执行或子代理派发（如 Claude Code 的 Agent 工具、Gemini 的并行任务等），可并行处理多个 PDF：

每个子任务独立完成：读取 PDF → 理解内容 → 生成知识整理 markdown
各任务之间互不依赖，可完全并行
主任务负责：分发任务、收集结果、生成汇总报告和 Wiki

若当前 agent 不支持并行处理，则逐个串行处理。

生成 Wiki

所有 PDF 处理完成后，将输出目录下所有 _知识整理.md 文件整合为一个 Wiki 索引文件。

注意：Wiki 生成是在所有 PDF 都处理完成之后进行的，此时读取已完成的知识整理文件是为了建立索引和关联关系，这是合法行为。这与行为准则第 6 条禁止的"在处理某个 PDF 时借用其它文件内容"是完全不同的场景。Wiki 生成只能在所有 PDF 独立处理完成后才能开始。

扫描输出目录下所有 _知识整理.md 文件
按文件名中的章节号排序
生成 Wiki.md 文件，结构如下：

# 知识库 Wiki

## 目录

| 序号 | 章节 | 文件链接 |
|------|------|----------|
| 1 | 计算机系统基础知识 | [[1]计算机系统基础知识](./[2]--1.计算机系统基础知识_知识整理.md) |
| 2 | 操作系统概述 | [[2.1]操作系统概述](./[3]--2.1操作系统概述-进程管理-同步互斥_知识整理.md) |
| ... | ... | ... |

## 章节间关联

- 第2章（操作系统）是第1章（计算机基础）的深入展开
- 第3章（数据库）与第2章的文件管理相关
- ...

Wiki 中包含：
- 目录表：所有章节的编号、名称、链接
- 章节间关联：识别章节间的知识关联关系（如前后依赖、交叉引用），帮助使用者建立知识体系
- 统计信息：总章节数、总知识点数等
Wiki 文件输出到与知识整理文件相同的目录

附录：OCR 工具函数说明

scripts.tools.ocr_for_data_base64

功能：对 Base64 编码的图片进行 OCR 文字识别

参数：

dataBase64 (string, 必填)：图片文件的 Base64 编码

返回值：dict 对象

result["raw"] - API 原始返回数据（JSON）
result["success"] - 是否成功（True/False）
result["message"] - 状态消息

使用示例：

from scripts.tools import ocr_for_data_base64
import base64

with open("page.png", "rb") as f:
    img_base64 = base64.b64encode(f.read()).decode("utf-8")

result = ocr_for_data_base64(dataBase64=img_base64)
if result["success"]:
    print(result["raw"])
else:
    print(f"OCR失败: {result['message']}")

scripts.config.set_api_key

功能：设置并保存 API 密钥到 .env 文件，仅保存用户主动提供的密钥

参数：

api_key (string)：用户通过 AskUserQuestion 提供的 API 密钥

返回值：bool - 是否保存成功

安全说明：

此函数不会向第三方平台自动注册账号
仅将用户主动提供的密钥写入 .env 文件，方便下次使用

scripts.config.get_api_key

功能：获取当前配置的 API 密钥

返回值：string - API 密钥（空字符串表示未配置）

读取优先级：

环境变量 XBY_APIKEY
.env 文件中的 XBY_APIKEY