feishu-wiki-to-xhs

name	feishu-wiki-to-xhs
description	从飞书Wiki/文档下载PDF并按逻辑内容块切分为小红书友好格式的竖版图片。触发场景：用户要把飞书文档发小红书、切图、做学习卡片、把文档拆成图片。当用户说'发小红书''切图''把文档切成图片''学习卡片'或提供飞书链接要求切分时使用。
description_zh	飞书文档→小红书切图
description_en	Feishu doc to XHS images
disable	false
agent_created	true

feishu-wiki-to-xhs

When to use

用户要把飞书 Wiki/云文档转成小红书风格的竖版切图。触发词：

• "发小红书""切图""切成图片""学习卡片"
• 提供飞书链接 + 要求切分/导出图片
• "把这个文档切成小红书格式"

Prerequisites

• lark-cli 已登录（lark-cli auth status）
• 系统 Python 有 PyMuPDF + Pillow（/usr/bin/python3 -c "import fitz; import PIL"）
  • 若缺依赖：/usr/bin/python3 -m pip install PyMuPDF Pillow
• ⚠️ 不要用 managed Python（~/.workbuddy/binaries/python/），原生 .so/.dylib 因 Team ID 签名不匹配会 ImportError，必须用系统 Python /usr/bin/python3

Steps

Step 1: 解包 Wiki URL 获取真实 token

Wiki 链接不能直接当 document token 用，必须先 inspect：

lark-cli drive +inspect "<wiki_url>"

从输出中获取 obj_token 和 obj_type（通常是 docx 或 sheet）。

Step 2: 导出 PDF

lark-cli doc +export --token <obj_token> --type pdf

等待导出完成，记录返回的 ticket 或 file_token。

Step 3: 下载 PDF

cd <目标目录>  # 通常是 ~/Downloads
lark-cli doc +export-download --token <obj_token> --type pdf --output-dir '.'

⚠️ +export-download 不接受绝对路径，必须先 cd 再用 --output-dir '.'。

Step 4: 分析 PDF 结构

在运行切图脚本前，先用系统 Python 快速查看 PDF 内容结构，确认能正确识别章节标题：

/usr/bin/python3 -c "
import fitz
doc = fitz.open('<pdf_path>')
print(f'Pages: {len(doc)}, Size: {doc[0].rect.width:.0f}x{doc[0].rect.height:.0f}pt')
for i in range(len(doc)):
    page = doc[i]
    td = page.get_text('dict')
    for b in td.get('blocks', []):
        if b.get('type') != 0: continue
        for line in b.get('lines', []):
            spans = line.get('spans', [])
            if not spans: continue
            max_fs = max(s.get('size', 0) for s in spans)
            text = ''.join(s.get('text','') for s in spans).strip()
            if max_fs >= 14 and text:
                print(f'  p{i+1} y={line[\"bbox\"][1]:.0f} fs={max_fs:.1f} | {text}')
"

• fs >= 14 的行被视为章节标题/分割点
• 如果自动检测结果不理想，调整 --min-split-font 参数

Step 5: 运行切图脚本

/usr/bin/python3 ~/.workbuddy/skills/feishu-wiki-to-xhs/scripts/split_pdf_for_xhs.py \
    "<pdf_path>" \
    "<output_dir>" \
    --dpi 200 \
    --min-split-font 14

参数说明：

• pdf_path: Step 3 下载的 PDF 文件路径
• output_dir: 输出目录（可选，默认在 PDF 同目录下创建 <文件名>_xhs/）
• --dpi: 渲染分辨率，200 适合小红书（默认 200）
• --min-split-font: 最小标题字号，>=此值的行作为分块起点（默认 14）

Step 6: 检查结果

ls -lh "<output_dir>/"

确认：

• 每张图是一个完整逻辑块，没有段落被截断
• 跨页内容已纵向拼接
• 图片宽度一致（默认 1656px @200DPI）

Automatic vs Manual mode

脚本会自动检测章节标题并分块。如果自动分块效果不理想（如标题字号太小未被识别、某些块太大或太小），可以：

1. 调小 --min-split-font：识别更多分割点（适合字号较小的文档）
2. 手动定义分块：直接写 Python 代码，用 clip 参数精确指定 y 坐标

手动分块模板（见 @references/manual-split-template.py）：

import fitz
from PIL import Image
from pathlib import Path

pdf_path = Path('<pdf_path>')
out_dir = Path('<output_dir>')
out_dir.mkdir(parents=True, exist_ok=True)

doc = fitz.open(str(pdf_path))
dpi = 200
scale = dpi / 72
page_w = doc[0].rect.width

# Define logical blocks: (label, [(page_idx, y_top, y_bottom), ...])
blocks = [
    ("01_封面",       [(0, 0, 633)]),
    ("02_第一章",     [(0, 640, 842), (1, 0, 600)]),  # cross-page
    # ... add more
]

for label, segments in blocks:
    segment_images = []
    for page_idx, y_top, y_bot in segments:
        page = doc[page_idx]
        clip = fitz.Rect(0, y_top, page_w, y_bot)
        mat = fitz.Matrix(scale, scale)
        pix = page.get_pixmap(matrix=mat, clip=clip, alpha=False)
        img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
        segment_images.append(img)

    total_w = max(img.width for img in segment_images)
    total_h = sum(img.height for img in segment_images)
    combined = Image.new("RGB", (total_w, total_h), (255, 255, 255))
    y_offset = 0
    for img in segment_images:
        combined.paste(img, (0, y_offset))
        y_offset += img.height

    out_path = out_dir / f"{label}.png"
    combined.save(str(out_path), optimize=True)

Pitfalls

• managed Python 原生库签名冲突：~/.workbuddy/binaries/python/ 下 PyMuPDF/pypdfium2 的 .so 因 Team ID 不匹配会 ImportError，必须用 /usr/bin/python3
• lark-cli 绝对路径限制：+export-download 的 --output-dir 只接受相对路径，先 cd 到目标目录
• Wiki URL ≠ document token：必须先 +inspect 解包，不能直接用 Wiki URL 里的 token
• 字号检测偏差：飞书导出 PDF 的标题字号取决于原文档排版，如果自动检测不准，用 Step 4 先检查实际字号再调 --min-split-font
• 小红书图片限制：单张图建议不超过 20MB；宽度 1242px 或 1656px 均可；200 DPI 下 A4 页宽约 1656px

Verification

1. 确认输出目录有 N 张 PNG（N = 逻辑块数量）
2. 用 sips 或 file 检查图片尺寸：sips -g pixelWidth -g pixelHeight <img>
3. 目视确认无段落截断、跨页拼接无缝