Paper2xhs

paper2xhs — 论文转小红书（你主导的协调式）

把一篇论文 PDF 转成小红书帖子。你是主笔：这份文件是配方，不是全自动脚本—— 没有 main.py。机械步骤（解析 / 封面 / 发布）调用 scripts/ 下的小工具；论文理解、 选题角度、文案撰写由你亲自完成（用 Read 看材料、用 Write 落产物），并在关键点用 AskUserQuestion 与用户确认。

PDF
 → 解析            (parse_pdf.py：MinerU → parsed/ + figures/)
 → 你读懂论文       (读 parsed/ + 看 figures/) → understanding/paper_understanding.json   [确认选题角度]
 → 你写小红书文案    (标题/正文/标签/封面文字) → xhs_post.json + xhs_post.md            [确认文案]
 → 封面+配图        (cover.py 封面：默认 API 生图 gpt-image-2、无 key 回退本地合成；
                    post_images.py 配图：把你选的论文主图/主实验图按序复制成图集，原图直出)
 → 半自动发布       (publish.py：封面+配图多图帖，可选)
 → 小红书帖子

运行方式

1. 一步步来：机械步骤用 Bash 调脚本，创作步骤你自己用 Read / Write 做。不要试图一条命令跑完。
2. 每个 Bash 块开头就地算 WORKDIR——各 Bash 调用是独立 shell、不共享变量，所以别指望 export 跨步存活：

   WORKDIR="$(dirname "$pdf_path")/.paper2anything/xhs/$(basename "${pdf_path%.*}")"

   其中 $pdf_path 是用户给的论文 PDF 路径（每个块都重新设一次）。脚本在 ${SKILL_DIR}/scripts——SKILL_DIR 是本 skill 的目录（见本 skill 顶部注入的 "Base directory for this skill: …"）；各 Bash 块独立 shell， 用到它的块开头按需 export SKILL_DIR=<那个目录> 一次（和 WORKDIR 一样每块现设）。
3. 在两个决策点用 AskUserQuestion 暂停：① 读懂论文后确认“选题角度”；② 文案成稿后确认。用户想改，可直接改产物 JSON/MD 或告诉你改。
4. 小红书是“准确、不夸大的科普”：忠实反映论文贡献，口语化、有钩子，但绝不编造数据或夸大结论。

Step 0：环境与凭据

统一环境：所有 python 命令都在 paper2anything 的统一 conda 环境里（顶层 environment.yml 创建），命令以 conda run -n paper2anything --no-capture-output 为前缀。

凭据集中在 paper2anything 包根的 .env（从 .env.example 复制，已 gitignore）。每个新 shell 先导出一次：

set -a; source <paper2anything 包根>/.env; set +a

本 skill 用到的 key（理解与文案由你亲自做，不调用任何 LLM API）：

• MINERU_API_TOKEN — 解析 PDF（必填）
• OPENAI_API_KEY(+ OPENAI_BASE_URL) — 封面默认走它生图（gpt-image-2）；无 key 或 key 不可用时回退本地合成（复用论文原图）
• XHS_MCP_BIN — 可选：自定义 xiaohongshu-mcp 二进制位置；不设则发布时 skill 自动按平台下载到 ~/.paper2anything/xhs/。另可选 XHS_MCP_URL（自定义服务地址/端口，默认 http://localhost:18060）。

依赖自检（缺啥按提示装；依赖统一在 environment.yml）：

conda run -n paper2anything --no-capture-output python -c "import requests, rich, dotenv" 2>&1

Step 1：解析 PDF（脚本）

pdf_path="/path/to/paper.pdf"          # ← 用户的论文 PDF
WORKDIR="$(dirname "$pdf_path")/.paper2anything/xhs/$(basename "${pdf_path%.*}")"
conda run -n paper2anything --no-capture-output \
  python "${SKILL_DIR}/scripts/parse_pdf.py" "$pdf_path" --workdir "$WORKDIR"

产出（$WORKDIR 下）：

• parsed/paper_meta.json（title / authors / abstract）、parsed/sections.json（[{title, content}]）、parsed/figures_index.json（[{figure_id, caption, image_path, page}]，image_path 已指向 figures/ 实体）、parsed/references.json
• figures/* 论文插图实体

解析完，先 Read parsed/sections.json 与 parsed/paper_meta.json 通读全文。

Step 2：读懂论文 → 写 understanding（你来做）[确认]

这是创作的地基，你自己做判断，不要交给脚本：

1. Read parsed/sections.json（全文）+ parsed/paper_meta.json；Read parsed/figures_index.json 看图注（个别图 caption 可能为空；多面板大图可能被解析器拆成两半、完整图注只挂在其中一半上，且拆缝处图例/轴标签可能被裁——一律以实际看图为准），并实际 Read 几张候选图片（figures/ 下）判断哪些清晰、适合做封面或配图——图注说“framework”的图在小图里未必好看，只有你的眼睛能判断。
2. 用 Write 落 understanding/paper_understanding.json，schema：

   {
     "paper_title": "...", "method_name": "方法简称（如 AccKV）",
     "one_sentence_summary": "一句话讲清这篇做了什么",
     "problem": "解决什么问题", "method": "怎么做的",
     "highlights": ["有数据支撑的亮点1", "创新点2", "应用价值3"],
     "experiment_results": ["关键数据1（含数字）", "..."],
     "keywords": ["领域关键词", "..."],
     "cover_palette": {"bg": "#F4F5F7", "accent": "#2E86AB"},
     "important_figures": [
       {"figure_id": "fig_1", "image_path": "<figures_index.json 里的真实路径>",
        "suitable_for_cover": true, "importance_score": 0.9, "description": "图说明"}
     ],
     "post_figures": [
       {"image_path": "<figures_index.json 里的真实路径>"}
     ]
   }

   • important_figures 必须含 image_path（取自 parsed/figures_index.json，指向真实存在的图）、suitable_for_cover、importance_score——封面默认走 API 生图（gpt-image-2），仅当 OPENAI_API_KEY 未配/不可用时回退本地合成、靠这几个字段复用原图；漏了则回退时无图 → 封面 skipped。
   • post_figures（多图帖正文配图，建议 2~4 张、按展示顺序排）：第一张放论文主图（框架/方法总览）， 其后放主实验结果图；只放你亲眼 Read 过、缩到手机宽度仍清晰可读的图。配图原图直出、 不做任何加工。发布时图集 = 封面 + 这些配图。
   • cover_palette（可选）：本地合成回退路径的配色，按论文领域选 bg(浅色打底) + accent(强调色)，标题字色会随底色深浅自动适配。参考浅色调：通用 #F4F5F7+#2E86AB、生物 #EEF6F0+#2D8A5F、物理数学 #F1ECF8+#6A30C2、工程 #FBF0EC+#D85A3C、社科 #F4EEF2+#8A5A78、化学 #EAF4F8+#0E86C0。
3. 用 AskUserQuestion 与用户确认选题角度：这篇论文发小红书主打哪个亮点 / 用什么钩子 / 面向哪类读者。带着确认结果再写文案。

Step 3：写小红书帖子（你来做）[确认]

按小红书风格亲自撰写，用 Write 落 xhs_post.json 和 xhs_post.md。

小红书文案规则（领域知识）：

• 标题 ≤20 字，吸睛：含核心价值、或数字、或对比、或悬念式提问。
• 正文 300–600 字，结构：
  1. 开头 1–2 句钩子，抓住注意力
  2. 这篇论文是什么、解决什么问题（2–3 句）
  3. 3–5 个核心亮点，每点用 emoji 开头，简洁有力
  4. 1–3 个关键实验数据，要具体
  5. 对读者有什么用（1–2 句）
  6. 结尾引导互动（如“你觉得这方法能用在哪？”）
• 风格：口语化、易读、不端学术腔，但忠实准确、不夸大、不编数据。
• 标签 8–12 个，写在正文末尾；hashtags 字段同步放这些标签（发布脚本读 hashtags）。
• 封面文字 cover_text ≤15 字（封面大字用）。

产物 schema —— xhs_post.json：

{"title": "...", "body": "含 emoji/换行，末尾带标签的完整正文",
 "hashtags": ["#标签1", "#标签2"], "cover_text": "≤15字封面词", "paper_title_zh": "论文中文标题"}

xhs_post.md：第一行 # {title}，然后正文；可在顶部放 ![封面](cover.png) 占位（封面在 Step 4 生成）。

写完用 AskUserQuestion 给用户看标题 + 正文摘要，确认或按反馈修改（可直接改 JSON/MD）。

Step 4：生成封面与配图（脚本，可选）

封面主/副标题此刻由你现拟（你已读透论文，比从 JSON 里捡更贴切），经 --title（主标题大字）/ --subtitle（副标题小字）传入：

pdf_path="/path/to/paper.pdf"
WORKDIR="$(dirname "$pdf_path")/.paper2anything/xhs/$(basename "${pdf_path%.*}")"
conda run -n paper2anything --no-capture-output \
  python "${SKILL_DIR}/scripts/cover.py" --workdir "$WORKDIR" \
  --title "你拟的封面主标题大字" --subtitle "你拟的副标题小字"

逻辑：默认用 OPENAI_IMAGE_MODEL（默认 gpt-image-2）生成竖版封面，主标题大字用你传入的 --title、副标题小字用 --subtitle（留空才分别回退 xhs_post.cover_text / 论文标题）；未配 OPENAI_API_KEY 或 key 不可用时回退本地合成——复用 understanding.important_figures 里 suitable_for_cover 最高分的论文原图（叠加 --title，配色取 cover_palette）；两者都不可用则 skipped（不阻断流程）。产出 cover.png。 生图 API 单次可能要好几分钟（经中转可达 6~7 分钟）——本命令的 Bash 超时设 ≥10 分钟（600000ms），别用默认 2 分钟，超时被杀时 logs/ 不会留 cover_result.json。

再生成正文配图（多图帖的第 2~N 张，纯本地排版、不调 API）：

conda run -n paper2anything --no-capture-output \
  python "${SKILL_DIR}/scripts/post_images.py" --workdir "$WORKDIR"

逻辑：读 understanding.post_figures，把选中的论文原图按序直接复制为 post_images/p1.png|jpg…（原图直出、不加工，后缀随原图）； understanding 没写 post_figures 时回退 important_figures 按分前 3； 一张可用图都没有则 skipped（不阻断）。生成后逐张 Read 亲眼确认——图缩到手机宽度后糊、 文字不可读，就回去调 post_figures（换图/删图）重跑本命令（重跑会清掉旧 p*）。