xhs-writer

xhs-writer 是一个面向小红书（RedNote）内容创作的技能，用于将主题或用户素材转化为可直接发布的图文卡片组或短视频脚本。

用途与核心理念

该技能面向小红书内容创作场景。其核心理念是：小红书读者消费的是卡片组或短视频，而不是长文。因此长文原稿只是中间产物，caption 只是发布配文。最终产出为图文帖或视频帖两种形态之一。

主要能力

图文帖

生成 3-9 张 9:16 竖版卡片，结构为 cover（第 1 张）+ content（中间若干）+ ending（最后 1 张），每张中文内容不超过 80 字。每张卡可选用不同的合成策略：img2img（有真实素材时图生图）、text_on_photo（照片叠加文字）、collage（多图拼贴）、pure_text（纯文字卡）、ai_generated（概念图/数据图）。

视频帖

生成一段 15-90 秒竖屏视频脚本，含 6-12 个分镜，每镜 2-8 秒，累计时长对齐用户预期。每个分镜包含 narration（口播，≤30 字）、on_screen_text（屏幕字，≤15 字）、visual（画面描述）、material_ref（可选素材引用）。此外产出一张 3:4 封面卡。视频本体由用户侧工具合成，该技能只产出脚本。

附加产出

配 caption（100-300 字）与 5-8 个 hashtags，并生成标题。标题提供 5 种公式：痛点+解决方案、提问式、发现式、热点词、身份共鸣。

内置方法论

包含 5 大核心原则：真实素材优先、聚焦核心卖点、素人感设计、痛点导向、快速迭代。卖点优先级通过公式判断：优先级 = 稀缺性(1-5) × 实用性(1-5) × 可感知(1-5)，取 Top 1-2 作为核心卖点。

使用方式

工作流按顺序执行，不可跳步：

Step 0 — Intake：向用户确认主题/目标读者/核心观点、输出形态（图文或视频，默认图文）、素材、风格（默认“简约清新”）、卡片数量或视频时长（图文默认 5-7 张，视频默认 30-60 秒）。
Step 0.5 — 卖点/亮点分析（推荐）：列出功能/特性/亮点，让用户按稀缺性、实用性、可感知三个维度打分，计算得分并排序，选 Top 1-2 核心卖点。
Step 1 — 素材清点（有素材才做）：运行 python3 scripts/analyze_material.py <path>... --out <work-dir>/reference/materials.json --frames-dir <work-dir>/reference/frames 生成清单，再由 AI 用多模态能力填充描述。素材按价值排序：对比图 > 功能演示 > 数据图表 > 品牌素材。
Step 2 — 采集外部参考（观点类/资讯类必做；纯素材驱动可跳过），核心数据需 ≥2 个来源交叉验证。
Step 3 — 写长文原稿（2000-4000 字），从 H2 开始，不写 H1，标题放入 meta.json.title；写完先给用户确认再继续。
Step 4 — 去 AI 化：读 references/humanizer-zh.md 五层原则，完整扫描重写原稿并给出质量评分（满分 50）。
Step 4.5 — 图生图处理（有真实素材时必做）：使用 gpt-image-2 图生图（需 OpenAI API key），代码示例：

import sys
sys.path.insert(0, '~/.claude/skills/xhs-writer-skill/scripts')
from image_generator import GptImage2Generator

generator = GptImage2Generator(aspect_ratio="9:16")

generator.generate_scene_image(
    scene_data={
        'index': 1,
        'image_prompt': """Based on the reference image, create a Xiaohongshu style card, 9:16 vertical.

Keep the original image visible.

Add overlays:
- Top: "{标题}"
- Bottom: "{引导文字}"

Style:
- Keep original clear
- Casual Xiaohongshu style
- Authentic feel"""
    },
    output_path='output.jpg',
    size='auto',
    reference_image_path='material.jpg'
)

失败处理为三级降级：重试 1 次 → 降低图片分辨率（max 1024px）→ 改用代码叠加文字（scripts/text_on_image.py）。

Step 5 — 分发：写图文（拆成 3-9 张卡片）或视频（写分镜脚本）。
Step 6 — 生成 caption + hashtags + 标题。hashtags 5-8 个，核心标签 4 个 + 辅助标签 4 个，只写进 meta.json。
Step 7 — 落盘：目录结构为 output/小红书/{YYYY-MM-DD}/{短标题}_{YYYYMMDDHHmm}/，含长文原稿 .md、meta.json、images/、reference/。目录短标题与时间戳必须走脚本标准化：python3 scripts/normalize_slug.py "原始长标题" --with-ts。
Step 8 — 校验（强制）：python3 scripts/validate_meta.py <work-dir>/meta.json，非 0 退出需修复后重跑，直到 clean。

适用场景

产品推广、好物分享、知识科普、经验总结、测评对比等各类小红书内容创作。

限制与注意事项

视频合成不由该技能完成，仅产出脚本。
图生图功能需 OpenAI API key（配置于 ~/.claude/skills/xhs-writer-skill/.env 的 OPENAI_API_KEY）；无 key 时只能生成纯文字卡片。
必需工具：Python 3.8+、PIL (Pillow)。
不写 H1，标题只放 meta.json.title；不在正文末尾写“参考来源/References”；不留【插入图片：...】占位符；不跳过 Step 4（去 AI 化）和 Step 8（validate）；不手算目录名/时间戳。
其他定价、平台支持范围等信息暂未提供。