核心分析¶

用户体验预期：将书籍转换为技能后，代理在被询问时会按需加载相关章节并基于真实章节内容给出回答，降低幻觉并提升查询速度和可引用性。对日常开发/研究查询来说，体验明显优于直接搜索 PDF 或让模型凭记忆回答。

实际体验亮点¶

• 直接引用原文：代理能从特定章节读取并回答，而不是返回页码或凭模型生成非事实性回答。
• 低上下文成本：因为章节按需加载，大多数查询避开一次性大规模上下文注入的代价。
• 跨宿主兼容：输出遵循 Agent Skills 布局，可被 Copilot CLI、Amp、Claude Code 等读取。

常见挑战¶

1. 初始设置与学习曲线：需安装抽取器（poppler、Calibre 等）并选择合适抽取器（docling vs pdftotext）。
2. 扫描件/OCR 问题：原始为图像的 PDF 需要先做 OCR，否则抽取为空或错位。
3. 抽取质量不稳：多栏、复杂排版或不规则 TOC 可能导致章节错位或缺失，需要人工 spot-check。
4. 模型或宿主受限：若宿主不支持 Agent Skills 或无法访问 Claude，功能受限。

实用建议¶

1. 先在一两章上做完整抽取+生成验证，检查 SKILL.md 的章节索引与心智模型。
2. 对关键示例/代码段采用人工抽样校验，特别是技术实现细节。
3. 为扫描文档插入 OCR 步骤（e.g. Tesseract），再运行抽取流程。

重要提示：虽然常规查询更可靠，但不能把生成的决策表或模式视为无需验证的法律/安全级依据。

总结：用户将获得更直接、确定的查询体验，但需要负责前期配置与质量校验以确保技能的准确性与可用性。

核心分析¶

能力概述：本项目明确关注保留技术细节——代码块、表格与决策表是设计目标之一。通过抽取器优先策略（技术书推荐 docling）和把章节原文写成单文件，该工具在多种情况下能较好保真技术内容。

保真优势¶

• 抽取器选择：docling 被推荐用于保留代码/表格的结构，能比通用文本抽取器提供更高的格式保真度。
• 逐章存储：原文以章节文件保留，LLM 的结构化输出可引用原始段落以避免仅凭摘要回答。
• 结构化产物并存：保留 glossary、patterns 与 cheatsheet，便于把原始细节和抽象化规则并列使用。

限制与风险¶

1. 源文件质量依赖：电子原生文档（有文本层的 PDF/EPUB）保真最好；扫描件需先 OCR。
2. 复杂排版问题：多栏、嵌套表格或不规则 TOC 可能导致抽取错位或丢失表格边界。
3. 抽取器性能权衡：docling 更保真但速度慢；在大规模批量处理中需考虑时间成本。
4. LLM 抽象化风险：LLM 在生成决策表或心智模型时会抽象信息，关键技术细节仍需与章节原文交叉核对。

实用建议¶

• 对关键代码示例与表格做抽样对比，必要时保留章节中的原始片段作为引用证据。
• 对大书先做小批量抽取与人工校验，再扩展到全书处理流程。
• 为扫描文档构建 OCR 预处理步骤（推荐 Tesseract 或商用 OCR）。

重要提示：该工具大幅提高保真可能性，但不能保证在所有复杂排版与扫描场景下 100% 无误。

总结：对电子原生、排版规整的技术书，项目能高保真提取代码与表格；对扫描件或复杂排版需要 OCR 和人工校验来确保准确性。

核心分析¶

增量更新原则：由于技能是由 SKILL.md 和逐章文件构成，最佳的 fold-in 策略是以章节/文件为最小更新单元，结合自动化差异检测与人工审核实现安全、可控的生产级更新。

推荐的生产级 fold-in 流程¶

1. 预处理与抽取（隔离环境）：在独立分支或临时目录运行抽取器并生成新章节与 SKILL.md，包含 metadata 与生成日志。
2. 自动差异检测：比对原技能与新产物：检查新增/修改的章节、术语表变更、patterns/cheatsheet 差异（可用文本 diff +结构化对比）。
3. 人工审查：对关键变更（代码示例、决策表、版权相关段落）进行人工审核并留痕批准。
4. 渐进合并：按章节逐步替换或追加文件，先在测试环境中部署并运行典型查询回归测试。
5. 版本控制与回滚：将每次 fold-in 作为独立提交/release，并保留回滚点。
6. 合规/权限检查：对新增材料的版权和合规性做审批（尤其是外部书籍）。

工具建议¶

• 使用 Git 管理技能目录，利用 PR 流程实现审查与审批。
• 自动化脚本执行差异检测与回归查询样本（确保 SKILL.md 索引与章节内容一致）。
• 对抽取失败或 OCR 问题设置报警与人工介入流程。

重要提示：fold-in 看似简单，但若跳过差异审查或合规检查，可能引入错误或版权风险。把增量更新纳入 CI/CD 和审查流程是关键。

总结：以章节为最小单元、在隔离环境生成并通过自动差异检测+人工审核、使用版本控制与渐进合并，可以在生产环境安全且可控地 fold-in 新资料。

核心分析¶

问题识别：扫描件（图像型 PDF）和多语言混排会显著降低抽取器的正确率，导致空文本、错位章节或丢失表格/代码。

改造工作流的关键步骤¶

1. 高质量 OCR 预处理：在抽取前对扫描文档运行 OCR。推荐：
   - 开源：Tesseract（配置相应语言包）
   - 商用/云服务：Google Vision OCR、AWS Textract、Azure OCR（更好表格识别）
2. 保留版面位置信息：选择能输出坐标/布局信息的 OCR，以便后续重建表格、代码块和多栏布局。
3. 按语言分段处理：对混合语言文档先做语言检测并按语言段落化处理，确保 OCR/后续 LLM 使用匹配的语言模型与编码。
4. 预处理排版问题：用脚本剔除页眉页脚、合并断行、修复列合并错误；对复杂 TOC 做手工或半自动校正。
5. 选择合适抽取器与校验：OCR 后使用 docling 提取技术内容或 pdftotext 提取纯文本，并对重要章节做人工抽样校验。

实用建议¶

• 对关键书籍先做小批量实验以调参 OCR 与抽取器设置。
• 如果表格复杂，优先选用商用 OCR（例如 Textract）以提高结构化表格识别率。
• 在生成技能后做针对性回归查询，验证代码片段与表格数据的可引用性。

重要提示：加入 OCR 与后处理会增加时间成本与复杂度，但这是处理扫描件与混合语言内容的必经步骤。

总结：为扫描件或多语言文档，把 OCR、语言检测与排版预处理纳入流水线，并结合合适的抽取器与人工校验，可以显著提升提取的准确性与保真。