junyi-doc-reader

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

When to Use

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

Supported Formats

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

Three Modes

自动降级规则：

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

Usage

Single Command

python3 scripts/pipeline.py \x3Cinput_file> --output \x3Coutput_dir> \
  [--mode archive-only|archive+index|archive+index+insights] \
  [--split-by year|topic|chapter|none]

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

Example

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

# 带 LLM 增强 + 按章节分文件
DOC_READER_API_KEY="sk-xxx" DOC_READER_ALLOW_EXTERNAL=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

Environment Variables

Output Structure

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

Key Files for Agent Use

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

chunks.jsonl Format

{"chunk_id": "ch-0001", "heading_path": ["第一章", "引言"], "char_start": 0, "char_end": 4500, "text": "..."}

Enriched chunks additionally have: summary, key_points, keywords, classification, confidence.

Crash Recovery

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

Dependencies

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

Agent Workflow

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