Junyi doc reader

junyi-doc-reader (v5)

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

When to Use

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

Supported Sources

源	输入	说明
local（默认）	文件路径	.docx/.pdf/.txt/.md
feishu（v5 新增）	飞书文档链接或 doc_token	通过 API 抓取

Source Auto-Detection

Agent 根据用户输入自动判断：

1. 包含 feishu.cn/docx/ → 提取 doc_token → --source feishu
2. 本地文件路径 → --source local
3. 用户同时要求"按日期拆分" → 追加 --split-by date
4. 无法判断 → 追问用户

Supported Local Formats

格式	转换工具	备注
.docx	pandoc	推荐格式，需安装 pandoc
.pdf	pdftotext	需安装 poppler，扫描件暂不支持
.txt	直接读取	自动检测编码（UTF-8/GBK）
.md	跳过转换	直接进入分块

Three Modes

模式	说明	需要 API
archive-only	转换 + 分块 + 原文归档	否
archive+index	上述 + 结构化索引	否
archive+index+insights	上述 + LLM 摘要/关键词/分类	是

自动降级规则：

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

Usage

Local File

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

Feishu Document (v5)

python3 scripts/pipeline.py --source feishu --doc-token XXX --account YYY \
  --output <output_dir> [--mode ...] [--split-by date] [--dry-run]

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

Examples

# 基础归档（本地文件）
python3 ~/.openclaw/shared-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/shared-skills/junyi-doc-reader/scripts/pipeline.py \
  /path/to/document.pdf \
  --output /path/to/obsidian/vault/文档名/ \
  --mode archive+index+insights \
  --split-by chapter

# 飞书文档归档（v5 新增）
python3 ~/.openclaw/shared-skills/junyi-doc-reader/scripts/pipeline.py \
  --source feishu --doc-token YOUR_DOC_TOKEN --account YOUR_ACCOUNT \
  --output /path/to/obsidian/vault/文档名/

# 飞书工作日志按日期拆分（v5 新增）
python3 ~/.openclaw/shared-skills/junyi-doc-reader/scripts/pipeline.py \
  --source feishu --doc-token YOUR_DOC_TOKEN --account YOUR_ACCOUNT \
  --output /path/to/obsidian/vault/日志/ \
  --split-by date

# 预览日期拆分（不写入）
python3 ~/.openclaw/shared-skills/junyi-doc-reader/scripts/pipeline.py \
  --source feishu --doc-token YOUR_DOC_TOKEN --account YOUR_ACCOUNT \
  --output /path/to/obsidian/vault/日志/ \
  --split-by date --dry-run

Parameter Validation Rules

条件	校验
source=local	必须提供 input_file
source=feishu	必须提供 --doc-token 和 --account
source=local + --doc-token	报错：参数冲突
--split-by date + source=local	报错：date 拆分仅支持飞书源
source=feishu + mode=insights	必须设置 DOC_READER_ALLOW_EXTERNAL=true

Environment Variables

变量	说明	默认值
DOC_READER_API_KEY	LLM API 密钥	(无)
DOC_READER_API_URL	API endpoint	https://api.openai.com/v1/chat/completions
DOC_READER_MODEL	模型名	claude-haiku-4-5-20251001
DOC_READER_ALLOW_EXTERNAL	是否允许外发文档	false

Output Structure

Local File / Feishu Standard Mode

output_dir/
├── manifest.json          # 任务元数据
├── source.md              # 完整原文 Markdown
├── source_meta.json       # 飞书版本锚点（仅飞书源）
├── 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

Feishu Daily Notes Mode (--split-by date)

output_dir/
├── manifest.json          # 任务元数据
├── source_meta.json       # 飞书版本锚点
├── converted.md           # normalize 后的完整 Markdown
├── _daily_index.md        # daily notes 索引
├── 2026-03-01.md          # 受管区块写入
├── 2026-03-02.md
└── ...

Daily notes 使用受管区块（<!-- doc-reader:start/end -->）写入，不覆盖用户已手写的内容。

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。如果中断，重新运行相同命令即可从上次完成的步骤恢复。

Security & Privacy

本 Skill 的两类「敏感能力」均为功能必需且用户授权，遵循最小权限原则：

1. 本地凭据访问（仅飞书源）

• 读取范围：仅 ~/.openclaw/openclaw.json 中指定 account 的 appId / appSecret 两个字段（兼容 plugins.entries.feishu.accounts[<account>] 与 channels.feishu.accounts[<account>] 两种布局，取先命中的）
• 触发条件：用户显式使用 --source feishu --account <name> 时
• 使用方式：仅在内存中用于换取 Feishu tenant_access_token，不落盘、不打日志、不外传
• 网络出口白名单：仅 open.feishu.cn（飞书官方 API），无任何第三方 endpoint
• 本地源（默认）：完全不读取 openclaw.json，纯本地文件处理

2. 外发文档内容到 LLM（默认关闭）

• 默认状态：DOC_READER_ALLOW_EXTERNAL=false，文档内容不会离开本机
• 基础管线（archive-only / archive+index 模式）完全离线运行
• 启用 LLM 增强需要用户主动设置全部四个环境变量：
  • DOC_READER_API_KEY（用户自己的 LLM API 密钥）
  • DOC_READER_API_URL（用户指定 endpoint，无硬编码生产 URL）
  • DOC_READER_MODEL（用户指定模型）
  • DOC_READER_ALLOW_EXTERNAL=true（显式同意外发）
• 传输内容：只发 chunk 文本到用户配置的 endpoint，不带凭据、文件路径或元数据
• 可审计：用户可在运行前检查 chunks.jsonl，明确知道会传输哪些内容

3. 文件系统写入

• 仅写入用户通过 --output 指定的目录
• 不修改用户其他文件，不读取无关路径
• Daily notes 模式使用受管区块（<!-- doc-reader:start/end -->）写入，不覆盖用户已手写内容

总结

能力	默认行为	启用方式
读 openclaw.json	仅 --source feishu 时读飞书凭据	用户显式选择飞书源
调用飞书 API	仅 --source feishu 时	用户显式选择飞书源
外发到 LLM	关闭	设置 4 个环境变量
写本地文件	仅 --output 指定目录	用户指定路径

Dependencies

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

Agent Workflow

Local File

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

Feishu Document (v5)

1. 从用户输入中提取 doc_token（从 feishu.cn/docx/XXX 链接中提取）
2. 确定 account 名（你在 ~/.openclaw/openclaw.json 里配置的飞书账号名）
3. 确定目标目录和 split 方式（用户要求按日期拆分→ --split-by date）
4. 运行 python3 scripts/pipeline.py --source feishu --doc-token XXX --account YYY -o <dir> [--split-by date]
5. 检查 manifest.json 确认状态
6. 向用户报告结果