feishu-doc-scraper

用途

Feishu Doc Scraper 的用途是把飞书/Lark 的来源内容忠实地提取为本地 Markdown。它的契约是「每个来源的忠实 Markdown + 一份提取记录」，并不决定产出文件如何命名、索引、与既有笔记去重或组织进知识库——那属于宿主 PKM 或用户自己的约定。当用户希望把产出归档进知识库时，应先完成提取，再把干净的 Markdown 交给其整理工作流。

主要能力

提取飞书/Lark Docs、Wiki、Sheets 和 Minutes（妙记）转写文本为忠实的本地 Markdown。
优先使用 lark-cli API：程序化地提取正文（无模型改写），跟随集合的引用图，并根据错误码读取权限边界而非猜测。
对每个被读取或归档的文档，加载评论和反馈。
拥有正文加讨论的工作流、选定范围、仅正文例外、快照命令、解释和覆盖率检查。
对集合/枢纽文档，按广度优先（BFS）递归跟随引用图，直到不再有新引用（叶子节点）。
提供捆绑的提取器脚本 scripts/feishu_extract_refs.py，用于避免遗漏引用。
支持导出白板（whiteboard）预览图并以视觉方式阅读。

使用方式

选择路径：

来源是飞书/Lark URL（wiki / docx / sheets / minutes / base）？
- 是 → lark-cli 是否已安装并认证到该租户？
  - 是 → PATH A：lark-cli API 提取（主要，从此开始）；若命中 code 131006 / 99991679（权限被拒）→ PATH B：所有者导出的 .docx → 忠实 Markdown。
  - 否 → 先安装/认证 lark-cli；只有在确实不可能时才 → PATH D：浏览器 DOM 兜底。
- URL 是 Minutes / 妙记链接，或文档引用了妙记 → PATH C：妙记转写。
- 收到的是导出的 .docx（不是 URL）→ PATH B。

PATH A 要点：

对飞书国内域名禁用代理：

export LARK_CLI_NO_PROXY=1

分类 URL，再解析为可抓取的文档 token。wiki 节点 token 不是文档 token，需先解析：

lark-cli wiki spaces get_node --params '{"token":"<node_token>"}'
# → .data.node.obj_token  and  .data.node.obj_type  (e.g. "docx")

程序化抓取正文，切勿经由模型：

lark-cli docs +fetch --doc <obj_token> --format json > /tmp/fetch.json 2> /tmp/fetch.err
# ≤1.0.32: clean Markdown in .data.markdown.
# 1.0.55: body moved to .data.document.content as HTML (.data.markdown is null).
if jq -e -r '.data.markdown // empty' /tmp/fetch.json > "<sanitized-title>.md" && [ -s "<sanitized-title>.md" ]; then
  : # got clean Markdown directly
else
  jq -r '.data.document.content' /tmp/fetch.json > "<sanitized-title>.html"
  pandoc -f html -t gfm "<sanitized-title>.html" > "<sanitized-title>.md"
fi

正文必须通过 jq/pandoc 落盘，绝不由模型重新输入或总结。

若是集合/枢纽，跟随引用图（BFS）。对每个新抓取的文档运行：

python3 scripts/feishu_extract_refs.py "<sanitized-title>.html"   # → JSON list of {type, ref, title, dispatch}

白板块不是可跟随的引用，需就地导出并阅读：

lark-cli whiteboard +export --whiteboard-token <token> --output-type preview --output <path>.jpg --overwrite

最终残留标签检查（验收门），对工作目录递归执行：

grep -rlE '<(lark-table|lark-tr|sheet token=|mention-doc|cite doc-id=|whiteboard token=|view type=)' . \
  && echo "UNRESOLVED — keep recursing" || echo "clean"

PATH B：lark-cli wiki spaces get_node 返回 code 131006（节点权限被拒）是飞书侧的硬边界，唯一正确做法是请权限持有者导出 .docx 并在带外发送，然后忠实地转换（字号→标题、w:shd→高亮的还原，再做视觉验证）。

PATH C：lark-cli minutes 只返回元数据并可下载音视频，无法导出文本转写。转写来自通过 lark-cli api 调用的原生端点，需要一次 device-flow 登录授予额外 scope。原生 AI 转写远优于下载媒体再跑 ASR。

适用场景与限制

适用：将飞书文档、知识库、表格、妙记转写忠实地提取到本地 Markdown；抓取带引用关系的集合/枢纽文档；归档时记录来源定位、修订/权限状态、字节数、MIME 类型和哈希。

限制与重要说明：

base（Bitable）在 Path A 中尚未真正可操作化——提取器只记录 token（DISPATCH["url-base"]: "Bitable API (outside this skill) — record token"），Path A 并不端到端提取 Bitable 内容。
--format markdown 不是合法值（lark-cli 会警告并回落到 json）。
在 pandoc 转换分支，pandoc -f html -t gfm 会静默剥离飞书的一些自定义内嵌标签：whiteboard 零痕迹消失；mention-doc 的真实原始标签是 <cite doc-id="…" file-type="wiki|docx" title="…" type="doc"></cite>，也会零痕迹消失，连裸标题文本都不保留；sheet 未确认；image 不会消失（pandoc 基本原样传递 <img> 元素）。因此该分支下提取与残留标签检查必须基于 source.html，而非 source.md。
提取与持久化存储是两个独立决定。下载的 MP4/XLSX/DOCX/图片是工作副本，不代表该文件应进 Git 或 Git LFS。知识库归档默认建议：Git 保存忠实 Markdown 加结构化 CSV/JSON/HTML、来源定位、修订/权限状态、字节数、MIME 类型和哈希；平台原件在稳定 token 仍可检索时由飞书作为原始二进制附件的记录来源；OSS/对象存储仅在需要独立持久副本或平台来源不可靠长期检索时使用。上传是单独的授权操作。
剩余细节（完整命令目录、递归引擎、跨租户与个人空间细节）在 references/lark-cli-api-extraction.md 中。

技能介绍

用途

主要能力

使用方式

适用场景与限制