在线文档本地化

解决的问题

抓取在线内容的真正麻烦不在"下载"，而在三层失真：

• 登录墙与 JS 渲染：沙箱里 curl 拿到的常常是空壳 HTML，正文藏在 window.__INITIAL_STATE__ 或需要交互后才注入的 DOM 里。
• 签名与时效：抖音类站点的视频直链带签名且限时失效；飞书图片链接的 authcode 过期后全部变成死链。
• 结构塌陷：直接把网页转 Markdown，导航栏、引用卡、评论区会一起涌进来，原本的 H1 层级被打散，表格和代码块对齐丢失。

这个技能要做的是系统化转换，而不是简单的格式另存。

核心能力

管道固定为四段：输入适配 → 结构化解析 → 格式转换 → 质量校验。前半段由 agent 按源类型路由，后半段由 scripts/convert.py 统一处理，输出到 stdout，校验报告走 stderr。

输入侧覆盖了常见的"难抓"场景：

• 飞书：feishu_fetch.py 走 lark-cli 连接器取单篇或整空间正文；feishu_img_localize.py 重抓全文抽取 file_token 把图片落到本地，配合 build_static_html.py --embed-images 生成图片永不失效的单文件。
• 小红书 / X：混合策略——先零依赖解析 SSR 状态，遇登录墙回退 Playwright 渲染；X 长文靠 browser-skill 驱动已登录浏览器，只保留 article 主节点，剔除嵌套引用卡与评论区，并把 pbs.twimg.com 图片真实下载后 base64 内嵌。
• 视频：video_to_md.py 串联渲染截流直链 → curl 下载 → ffmpeg 抽音频 → faster-whisper 转写 → opencc 繁转简 → 按章节分组生成 MD，预留「观点 / 论述 / 建议」占位由 agent 提炼。
• 知识库整库导出：lark_kb_crawl / download / receiver / build 四件套，内容驱动 BFS 递归全量页面，附件绕过 drive:file:download scope 缺失走浏览器转发落盘到 files/。

转换后统一过校验：标题层级连续性、代码围栏奇偶、表格列数、链接图片计数，结论写进 validation 块。

适用边界

• 引擎 convert.py 仅依赖 Python 标准库；装了 trafilatura 只提升 HTML 抽取质量，不是必需项。
• X 与知识库附件的下载环节必须有 browser-skill 和已登录会话，这是整条流程里唯一的联网依赖。
• 视频转写是机器识别，同音错别字难免，交付物须标注"仅供参考"。
• MD 是中间产物而非终点：两段式设计的意义就在于一旦 MD 落地，转 HTML 可反复重跑、不再触碰浏览器。