junyi-doc-reader

大文档归档与检索管线。将大文档安全地转为结构化 Markdown，生成分块索引，可选 LLM 提炼摘要。

使用场景

• - 用户要求归档/阅读/索引一个大文档（Word、PDF、TXT、Markdown）
• 用户要求把文档存到 Obsidian
• 文档超过上下文窗口限制，需要分块处理

支持的格式

格式	转换工具	备注
.docx	pandoc	推荐格式，需安装 pandoc
.pdf

pdftotext | 需安装 poppler，扫描件暂不支持 | | .txt | 直接读取 | 自动检测编码（UTF-8/GBK） | | .md | 跳过转换 | 直接进入分块 |

飞书云文档：不直接支持飞书链接。请先在飞书中导出为 Word 或 PDF 再处理。

三种模式

模式	说明	需要 API
archive-only	转换 + 分块 + 原文归档	否
archive+index

上述 + 结构化索引 | 否 | | archive+index+insights | 上述 + LLM 摘要/关键词/分类 | 是 |

自动降级规则：

• - 未设置 DOCREADERAPIKEY → archive-only
• DOCREADERALLOWEXTERNAL=false（默认）→ 不外发文档给 LLM
• API 失败 → 保留已完成产物，降级继续

使用方法

单条命令

bash
python3 scripts/pipeline.py <输入文件> --output <输出目录> \
[--mode archive-only|archive+index|archive+index+insights] \
[--split-by year|topic|chapter|none]

脚本路径相对于技能目录： ~/.openclaw/workspace/skills/junyi-doc-reader/

示例

bash

基础归档

python3 ~/.openclaw/workspace/skills/junyi-doc-reader/scripts/pipeline.py \
/path/to/document.docx \
--output /path/to/obsidian/vault/文档名/

带 LLM 增强 + 按章节分文件

DOCREADERAPIKEY=sk-xxx DOCREADERALLOWEXTERNAL=true \ python3 ~/.openclaw/workspace/skills/junyi-doc-reader/scripts/pipeline.py \ /path/to/document.pdf \ --output /path/to/obsidian/vault/文档名/ \ --mode archive+index+insights \ --split-by chapter

环境变量

变量	说明	默认值
DOCREADERAPIKEY	LLM API 密钥	(无)
DOCREADERAPIURL

API 端点 | https://api.openai.com/v1/chat/completions | | DOCREADERMODEL | 模型名称 | claude-haiku-4-5-20251001 | | DOCREADERALLOW_EXTERNAL | 是否允许外发文档 | false |

输出结构

output_dir/
├── manifest.json # 任务元数据
├── source.md # 完整原文 Markdown
├── ROOT_INDEX.md # 全局导航目录
├── chunks.jsonl # 分块数据（机器可读）
├── processing_report.md # 处理报告
├── converted.md # 中间转换结果
├── state.json # 状态文件（用于断点恢复）
├── parts/ # 分文件（仅 --split-by 时生成）
│ ├── 2024.md
│ └── 2025.md
└── indexes/ # 分层索引（仅 insights 模式）
├── by-year.md
└── by-topic.md

供代理使用的关键文件

• - ROOT_INDEX.md — 先读这个了解文档结构
• chunks.jsonl — 精确检索定位，每行一个 JSON 块
• source.md — 需要全文搜索时使用
• manifest.json — 查看处理状态和警告

chunks.jsonl 格式

json
{chunkid: ch-0001, headingpath: [第一章, 引言], charstart: 0, charend: 4500, text: ...}

增强后的块额外包含：summary、key_points、keywords、classification、confidence。

崩溃恢复

管线自动保存进度到 state.json。如果中断，重新运行相同命令即可从上次完成的步骤恢复。

依赖项

• - Python 3.9+
• pandoc（处理 .docx，brew install pandoc）
• poppler（处理 .pdf，brew install poppler）
• 无第三方 Python 包依赖（使用 stdlib urllib）

代理工作流程

1. 1. 确认用户要处理的文件路径和目标目录
2. 检查文件格式是否支持
3. 根据是否配置了 API 密钥确定模式
4. 运行 python3 scripts/pipeline.py 一次完成所有步骤
5. 检查 manifest.json 确认状态
6. 向用户报告：处理了多少块、生成了哪些文件、有无警告
7. 如需写入 Obsidian，将 output_dir 内容复制到 vault 目标路径