Xhs Crafter

将MD文章排版为3:4比例的精美图片+压缩文字稿，用于公众号/小红书贴图发布。核心能力是本地HTML模板填充+Puppeteer截图渲染（启动本地127.0.0.1 HTTP server加载预存HTML模板，非MD→HTML编译管道）。可选外部能力（每项需用户独立明确同意）：(1)Pexels/Pixabay/Unsplash图库API搜索（发送搜索关键词到外部API）；(2)AI生图API（发送prompt到trae-api-cn，仅限TRAE内部环境）；(3)飞书云盘上传（上传生成的PNG+txt到飞书服务器）。Invoke when用户明确说'xhs-crafter排版'、'用xhs-crafter转图片'、'公众号贴图排版'、'小红书图文卡片'。Do NOT use for原创写作、纯文字排版、视频制作、用户只提到MD文件路径但未明确要求图片排版。

XHS Crafter — 文章转图片卡片

任务

将用户提供的MD文章内容，排版为多张3:4比例(1080×1440)的精美HTML页面，截图为PNG，压缩为≤1000字文字稿，文件夹交付。不做原创写作，不做视频，不做纯文字排版。

隐私与数据流声明（用户须知）

本技能的数据流边界：

• 本地处理（默认）：MD文本→HTML组装→PNG截图→本地文件夹交付。所有文章内容、图片素材、生成产物默认仅在本地处理，不上传任何外部服务
• 可选外部能力（需用户明确同意）：
  • 图片搜索：调用Pexels/Pixabay API搜索免费图库照片（仅搜索词和图片下载，不上传文章内容）
  • 飞书云盘同步：将生成PNG+文字稿上传到用户飞书云盘（需用户明确同意，且文章内容可能包含未发布素材）
• 外部网络依赖：v7.6 已移除 Google Fonts CDN 引用，模板使用系统字体回退栈（Noto Serif SC / Source Han Serif SC / Songti SC / PingFang SC / Consolas 等），完全本地渲染，无外部字体加载

用户警告：

• ⚠️ 如果文章包含未发布/敏感/专有内容，请谨慎使用飞书云盘同步功能——上传即意味着内容离开本地
• ⚠️ 图片搜索会将搜索关键词发送到Pexels/Pixabay服务器，但不会发送文章原文
• ⚠️ 飞书云盘同步需要用户已登录lark-cli，且目标文件夹由用户飞书账号持有

权限声明（v7.7 完整披露所有行为）：

能力类别	是否使用	说明
网络访问	✅	核心行为：启动本地 127.0.0.1 HTTP server 加载预存 HTML 模板供 Puppeteer 截图（不出局域网）。可选外部访问（每项需用户独立同意）：Pexels/Pixabay/Unsplash 图库 API 搜索；trae-api-cn AI 生图 API（仅限 TRAE 内部环境）；飞书云盘上传
文件读写	✅	读 MD 文章 + 预存 HTML 模板（assets/template-*.html）；写 output/ 目录 PNG+txt；写 $env:TEMP 交付文件夹；可选下载外部图片到 assets/ 目录（受 ALLOWED_HOSTS 白名单限制）
环境变量	✅	PEXELS_API_KEY、PIXABAY_API_KEY（图库搜索，可选）；CHROME_PATH（可选，浏览器路径）
subprocess	✅	python -m http.server --bind 127.0.0.1（本地回环 HTTP server，截图用）；node assets/screenshot.js（Puppeteer 截图）；node assets/validate.js（自动验证）；curl.exe（可选，下载外部图片）；explorer.exe（打开交付文件夹）
外部 API	✅	Pexels/Pixabay/Unsplash 图片搜索 API（可选，发送搜索关键词）；trae-api-cn.mchost.guru AI 生图 API（可选，发送 prompt，仅限 TRAE 内部环境）；飞书 lark-cli drive API（可选云盘同步，上传 PNG+txt）

⚠️ 核心行为说明：本技能的核心能力是 本地 HTML 模板填充 + Puppeteer 截图渲染，不是 MD→HTML 编译管道。MD 内容由 AI 读取后填入预存的 HTML 模板（assets/template-editorial-card.html 或 template-swiss-card.html），然后启动本地 HTTP server 加载该 HTML 供 Puppeteer 截图为 PNG。核心流程不涉及外部网络访问。

输出格式

text

<桌面>/<slug>公众号素材/
├── p1-cover.png
├── p2-xxx.png
├── ...
├── pN-finale.png
└── <slug>-文字稿.txt   # ≤1000字压缩文字

工作流：5步（默认本地全自动，外部能力需用户同意）

核心原则：用户给MD，直接出本地文件夹。Step 1-2在脑内完成（不输出长文规划），Step 3-5连续执行不等待用户确认。

外部能力同意门控（2道，仅在触发外部网络/云盘时询问，本地渲染不询问。每道门控独立询问，不批量授权）：

1. 图片搜索门控（Step 1，用户无图且需背景图时）：询问是否调用Pexels/Pixabay API搜索
2. 飞书同步门控（Step 5，本地交付完成后）：询问是否上传到飞书云盘

⚠️ 同意门控铁律：每道门控必须独立询问，不得因用户说"按流程走一遍"、"全流程"、"都行"等模糊措辞而批量授权多个外部能力。用户必须对每个外部能力单独明确同意（"是"或具体指定）。

Step 1: Intake — 识别品类（脑内完成，不输出）

从MD内容自动推断：

• 内容品类: 读 references/category-cookbook.md 路由。13个品类：商业/科技分析、职场/干货、旅行/生活方式、教程/工具、影视/读书、游戏、美食、彩妆、穿搭、家居、健身、情感、推荐。超出范围的品类（梦核/氛围感装饰风、Y2K/千禧辣妹、纯摄影展示）必须在设计前明确告知用户
• 目标平台: 默认小红书3:4（除非用户指定公众号）
• 用户图片: (a)用户指定截图文件夹路径；(b)解析MD中 ![描述](路径) 和 [🖼️配图建议：xxx] 标记
• 图片三选一门控（仅在用户无图时触发，一次性提问不反复追问）：

  text

  这篇我需要 1-2 张图。三种走法：
  A. 你自己有照片/截图，传给我（推荐——最不"AI感"，完全本地处理）
  B. 我去 Pexels/Pixabay 帮你找（⚠️ 会将搜索词发送到外部API，但不上传文章原文）
  C. 用 AI 生成（⚠️ 会将生图prompt发送到trae-api-cn.mchost.guru生图API，prompt可能含文章主题/场景描述，仅限TRAE内部环境）
  

  推荐 A。用户必须明确选择 A/B/C 之一（如"用B"、"搜图"、"AI生成"）；若用户说"都行"/"你看着办"等模糊回答，默认走 A（完全本地，无外部数据流），不再追问
• 仅在品类无法推断时才问用户，否则直接进入Step 2

Step 2: Content Plan — 内容规划（脑内完成，不输出）

读 references/content-planning.md，完成：

• 压缩阶梯：核心论点1句 → 读者承诺 → 4-8个分论点 → 页面钩子 → 正文片段
• 页面角色分配：7页组图至少5种不同形态
• 页面节奏规划：为每页标注明暗(Light/Dark)、氛围强弱(Strong/Subtle)、版式类型，读 references/portrait-fill.md 的"Three-Layer Rhythm System"
• 封面钩子：用具体承诺而非空洞口号
• 页数指导：600-1000字→5-7图，1000-1800字→7-9图
• 5页及以上：封面和封底都必须有图片背景

Step 3: Compose — 组装HTML（直接执行）

• 拷贝种子模板：Editorial→ assets/template-editorial-card.html；Swiss→ assets/template-swiss-card.html
• 设置 data-theme 或 data-accent 属性切换主题
• 在 <!-- POSTERS_HERE --> 处添加页面

字号速查表（必须严格遵循，不得自行调整）：

Role	Class	Size	Weight	Family	用途
Display	.h-display	136px	500	serif-zh	封面/封底主标题
Section title	.h-xl	110px	500	serif-zh	内容页主标题（必须统一）
Mid title	.h-md	60px	500	serif-zh	次级标题/数据页标题
Subtitle	.h-sub	46px	400 italic	serif-en	英文副标题
Pull quote	.pullquote	80px	500 italic	serif-zh	引言页大字引语
Lead	.lead	34px	400	serif-zh	导语/段落首句
Body	.body	32px	400	serif-zh	正文段落
Kicker	.kicker	26px	500	mono	页面顶部标签
Meta	.meta	24px	500	mono	页面底部注释
Label	.label	24px	500	mono	数据标签
Stat number	.stat-nb	72px	500	serif-zh	大数字
Step title	.step-title	34px	500	serif-zh	流程步骤标题
Step desc	.step-desc	28px	400	serif-zh	流程步骤描述
Ledger title	.ledger-title	30px	500	serif-zh	表格行标题
辅助文字	—	22px	500	mono	stat-label/stat-unit/ledger-note/step-nb/callout-src/issue-strip

字号铁律：

1. 内容页主标题必须统一用 .h-xl 110px——不得混用 .h-md，标题太长拆行而非降级
2. 封面/封底主标题用 .h-display 136px——比内容页大24%，形成"书挡"层级
3. 满铺图页标题颜色必须 #ffffff + text-shadow——禁止 #ece2cf（与暖调背景太接近）
4. 字重"越大越轻"：≥110px用500，60-80px用500，32-46px用400，24-26px用500
5. 任何文字不得低于18px

节奏速查表（必须严格遵循）：

规则	要求	违反后果
暗色页数量	5页+至少1页Midnight Ink，7页+至少1-2页	全light=单调
暗色页位置	引言页或结尾页最佳	中间也行，但不可相邻
暗色页相邻	禁止！2个暗色页必须隔至少1个light页	相邻=对比抵消
氛围强度	封面/引言/封底=strong，数据/清单=subtle，正文=medium	全同一强度=死板
版式重复	禁止连续2页用同一种版式骨架	密集ledger后接宽松essay
首尾图框	5页+封面和封底都必须有图片背景	无图=缺"书挡"
连续同色	连续3页相同主题色=P0错误	第3页必须插入暗色/氛围变化

密度速查表（必须严格遵循）：

规则	要求
活跃构图	≥78%画布高度（≈1123px of 1440px）
4横带密度	1440px切4段(360px)，每段有内容或主动留白理由
纯空白带	>216px必须有设计理由（如atmospheric hero页）
最少元素	每页至少3种内容元素（标题+正文+数据/图/引言）
表格行高	不足45%画布时加左侧大数字列或转M08 Tall Ledger
重复模式	避免"标题+lead+3行"重复超过2次

图片规则速查（必须严格遵循）：

规则	要求
图片下载	必须下载到本地assets/，禁止引用外部URL
唯一性验证	下载后用buf1.equals(buf2)验证，相同则换源
跨项目去重	下载后手动用buf1.equals(buf2)验证图片内容不同（文件级校验，不依赖跨项目 registry）
满铺图页	选图→无遮罩构图→局部色调遮罩→缩略图检查
满铺图标题色	必须#ffffff+text-shadow，禁止#ece2cf
主体感知裁切	根据object-position确保主体完整可见
截图展示	用.frame-shot包壳，给45-65%页面高度
图源优先级	用户图>Pexels/Pixabay(API)>Unsplash(直链)>AI生成
accent面积	Swiss≤30%，Lemon Green≤20%

• 封面/封底图片下载：
  1. 优先用户提供的图片（最真实，无"AI感"）
  2. 用户无图时，询问是否调用 Pexels/Pixabay API 搜索（需用户同意，见 Step 1 图片三选一门控）
  3. 用户同意后，用 curl.exe -L -o "assets/cover.jpg" "URL" 手动下载（URL 来自 Pexels/Pixabay API 返回）
  4. Unsplash 直链备选：https://images.unsplash.com/photo-{id}?w=1080&h=1440&fit=crop&auto=format&q=85
• 满铺图页必须遵循 references/image-overlay.md：选图→无遮罩构图→局部色调遮罩→缩略图检查
• 密度保障：每页活跃构图≥78%画布高度，读 references/portrait-fill.md
• 节奏保障：暗色页插入、氛围强弱交替、版式不重复
• 背景系统：Editorial 必须使用三层背景（paper→wash→grain），禁止纯平背景。读 references/background-systems.md。氛围强度按页面角色分级：封面/引言/封底用 strong，数据/清单用 subtle
• 图片必须下载到本地（关键！Puppeteer headless无法可靠加载外部API图片）：
  1. 用户同意后，用 curl.exe -L -o "assets/cover.jpg" "URL" 手动下载
  2. HTML中用本地相对路径引用：src="assets/cover.jpg"
  3. 禁止直接引用外部URL（trae-api-cn.mchost.guru 仅限TRAE内部环境可用 / unsplash / pexels等），一律先下载再引用
• 图片下载后必须验证唯一性：
  1. 下载多张图片后，用 buf1.equals(buf2) 验证图片文件内容不同
  2. 如果两张图完全相同，换用其他图源
  3. 禁止假设URL不同=内容不同
• 图源优先级: 用户图 > Pexels/Pixabay(API搜索) > Unsplash(直链) > AI生成(trae-api-cn.mchost.guru text_to_image，仅限TRAE内部环境)
• 截图用 .frame-shot 包壳

Step 4: Validate — 自检（自动执行，不等待）

截图前自动检查，不通过则自动修复：

密度检查：每页活跃构图≥78% | 每页≥3种内容元素 | 纯空白带>216px需理由 图片检查：封面1秒说清主题 | 文字未压主体 | 无broken image | 多张背景图文件内容不同（buf1.equals(buf2)===false） 标题一致性检查：所有内容页主标题使用同一字号class | 不得混用.h-xl和.h-md | 封面允许更大字号 节奏检查：5页+至少1暗色页 | 暗色页不相邻 | 氛围强弱交替 | 版式不重复 风格检查（读 references/style-system.md）：

• 全套风格统一（同一主题色+同一风格）
• Editorial身份测试：有atmosphere层 + serif标题 + 至少一个magazine结构元素
• Swiss身份测试：大标题字重≤300 + 无serif + 单一accent + 无卡片阴影
• 无文字溢出/footer碰撞

自动验证（读 assets/validate.js）：

• 运行 node assets/validate.js <项目目录> 执行 12 项自动检查
• R1 溢出检查 / R2 footer碰撞 / R3 Swiss粗体 / R4 最小字号 / R5 4横带密度 / R6 h-xl换行 / R7 figure margin / R8 标题一致性 / R9 满铺图页标题颜色 / R10 暗色页节奏 / R11 accent面积 / R12 封面封底图背景
• FAIL 项必须修复后才能交付，WARN 项为建议

Step 5: Screenshot & Deliver — 截图交付（直接执行）

• 用assets/screenshot.js截图（自动检测页面ID，无需手动配置）

  • 用法：先启动python -m http.server 8090 --bind 127.0.0.1（绑定本地回环，不暴露局域网），然后node assets/screenshot.js <项目目录>
  • puppeteer-core + 系统Chrome，deviceScaleFactor:2
  • 等待networkidle0 + fonts.ready + 6秒（确保图片加载）
  • Chrome路径: 自动检测$env:LOCALAPPDATA\ms-playwright\chromium-*\chrome.exe

• 截图大小异常检测（关键！文件过小说明图片未渲染）：

  • 带背景图的页面（封面/封底）PNG应 >1MB（2x分辨率下）
  • 纯文字页面 PNG 通常 800KB-1.5MB
  • 如果封面/封底截图 <500KB，大概率背景图未渲染，需检查图片文件是否有效

• 文字压缩：保留原话引言+场景描述+核心数据，≤1000字

  • 压缩模板：标题(1句) → 场景开场(1-2句，含人物/时间/地点) → 核心论点(1-2句) → 关键原话(1-2条，用「」包裹) → 数据支撑(3-5个关键数字) → 结尾原话(1条)
  • 必须保留：原文中的人物原话（用「」标记）、访谈/会议场景描述、关键数据
  • 可以删减：过渡句、重复论述、次要细节、纯背景铺垫

• 交付方式：本地文件夹（默认）+ 飞书云盘同步（可选，需用户同意）

  A. 本地文件夹（默认）

  ⚠️ 本地文件写入提示：将在 $env:TEMP 创建 <slug>公众号素材/ 文件夹并写入 PNG+txt 文件。截图完成后告知用户交付路径，再继续后续步骤。

  1. 截图完成后，告知用户：已生成 N 张 PNG + 文字稿，将保存到 $env:TEMP/<slug>公众号素材/
  2. 在$env:TEMP创建<slug>公众号素材/文件夹
  3. 将PNG+txt复制到该文件夹
  4. 用explorer.exe打开文件夹，用户可拖到桌面
  5. 完成本地交付后，询问是否上传到飞书云盘（不主动执行）

  B. 飞书云盘同步（可选，需用户明确同意——见下方门控）

  ⚠️ 数据外发提示：上传会将文章相关PNG和文字稿传输到飞书云服务器，离开本地环境。如果文章包含未发布/敏感/专有内容，请勿启用。需要用户已登录lark-cli。

  飞书同步同意门控（仅在本地交付完成后触发一次）：

  text

  本地文件夹已交付。是否需要同步到飞书云盘？
  - 是 → 执行下方上传步骤
  - 否 → 结束（本地文件夹已是完整交付物）
  

  用户同意后执行：

  1. 用lark-cli drive +create-folder创建<slug>公众号素材文件夹
  2. cd到output目录，用lark-cli drive +upload --file <filename> --folder-token <token>逐个上传PNG+txt
  3. 返回飞书云盘文件夹URL，用户手机飞书App打开即可逐张保存到相册
  4. 注意：lark-cli要求用相对路径，必须先cd到output目录再上传

标题一致性铁律（非协商）

1. 内容页主标题统一字号：所有内容页（P02-P08）的主标题必须使用同一个 class（Editorial 用 .h-xl 110px，Swiss 用 .h-xl 128px）
2. 封面允许更大字号：封面用 .h-display（Editorial 136px）或 .h-hero/.h-statement（Swiss）
3. 通过拆行适配而非降级字号：标题太长时拆为两行，太短时加副标题增加视觉重量，不得降级到 .h-md
4. 不得混用不同级别标题 class：同一套卡片中，内容页主标题不得混用 .h-xl 和 .h-md

密度铁律（非协商）

1. 活跃构图 ≥78% 画布高度（≈1123px of 1440px）
2. 4横带密度：1440px切4段(360px)，每段有内容或主动留白理由
3. 纯空白带 >216px 必须有设计理由（如atmospheric hero页）
4. 每页至少3种内容元素（标题+正文+数据/图/引言）
5. 表格/ledger行高不足45%画布时：加左侧大数字列、加pull quote列、或转M08 Tall Ledger
6. 避免"标题+lead+3行"重复超过2次

节奏铁律（非协商）

1. 明暗节奏：5页以上组图至少1页暗色页(Midnight Ink)，7页以上至少1-2页。暗色页不是换主题，是同一主题内的明暗对比
2. 暗色页位置：最佳位置是引言页(Pull Quote)或结尾页(Closing)。2个暗色页不可相邻
3. 氛围节奏：封面/引言/结尾用强氛围(strong grain+wash)，数据/截图/清单用弱氛围(subtle grain only)。不可所有页同一氛围强度
4. 版式节奏：不可连续2页用同一种版式骨架。密集ledger后接宽松essay或pull quote
5. 首尾图框：5页及以上组图，封面和封底都必须有图片背景（满铺图或大图区），形成"书挡"效果。图片必须与主题适配——封面图抓主题，封底图收情绪
6. 连续3页相同主题=P0错误：连续3页以上使用相同主题色（全light或全dark）视为严重错误，必须在第3页插入暗色页或氛围变化页

必读参考文件

文件	用途
references/style-system.md	风格系统：Editorial vs Swiss视觉锚点+身份测试+反模式
references/category-cookbook.md	品类路由表：13个品类的风格/主题/版式/图源映射
references/content-planning.md	内容规划：压缩阶梯+页面角色+钩子模式+页数指导
references/portrait-fill.md	3:4密度规则：垂直分区+密度铁律+稀疏页修复
references/image-overlay.md	文字压图：选图→无遮罩→局部色调→缩略图检查+主体避让
references/theme-presets.md	10套主题色CSS变量
references/components.md	字体/字号/间距/图片容器/卡片/截图容器规范
references/layout-recipes.md	28种布局模板(M01-M16+S01-S12)
references/screenshot-treatment.md	截图美化：设备外壳+背景材质+风格默认
references/background-systems.md	背景系统：三层架构（paper→wash→grain）+ 氛围强度分级 + 满铺图页 + Swiss极简
references/image-sources.md	Pexels/Unsplash图库接入 + AI生图验证规则

示例

输入: SpaceX上市分析MD → 自动推断：商业/科技分析 → Editorial × Indigo Porcelain

输出: 7张PNG + spacex-文字稿.txt → SpaceX公众号素材/ 文件夹

输入: skill-forge教程MD+截图文件夹 → 自动推断：教程/工具 → Swiss × IKB Blue

输出: 6张PNG + skillforge-文字稿.txt → skillforge公众号素材/ 文件夹