Skip to content

HANDOFF.md

Latest commit

 

History

History
464 lines (360 loc) · 37.2 KB

HANDOFF.md

File metadata and controls

464 lines (360 loc) · 37.2 KB
Raw

Handoff — guizang-social-card-skill

最后更新：2026-07-01 · 版本：v0.15（Live Photo 生产规则：3s/5s 平台限制、拼图版式、长视频处理、发布提醒、可见文案与不自造规则）

这份文档只记录事实：当前 skill 由哪些文件组成、每个文件管什么、本轮更新改了什么、怎么验证它还能跑。想读"为什么这样做"或"未来要怎么走"，去看 PRODUCT.md。

v0.13 路径约定：本文件 v0.12 及更早版本历史段落里的 demo-* / social-card-* / smoke-* / test-* 目录已统一搬入 local-tests/。读历史时请在脑中前缀 local-tests/。

1. 目录结构（事实版）

guizang-social-card-skill/
├── SKILL.md                   # 7 步工作流入口
├── HANDOFF.md                 # 本文件
├── PRODUCT.md                 # 产品思考
├── assets/
│   ├── template-editorial-card.html   # 杂志风种子
│   ├── template-swiss-card.html       # 瑞士风种子
│   ├── magazine-bg-webgl.js           # WebGL 墨流背景
│   └── screenshot-backgrounds/        # 9 张 WebP 截图舞台底（v0.14 从 PPT skill port）
│       ├── style-a/                   #   5 张 Editorial（dune / forest-ink / indigo-porcelain / kraft-paper / monocle-classic）
│       └── style-b/                   #   4 张 Swiss（ikb-dot / lemon-green-dot / lemon-grid / safety-orange）
├── references/                # 子规范，按需读取
│   ├── platform-specs.md      平台 × 分辨率 × 命名
│   ├── style-system.md        两种风格的硬规则与反模式
│   ├── theme-presets.md       6 套杂志 palette（含 Midnight Ink）+ 4 套 Swiss accent
│   ├── layout-recipes.md      版式骨架（M01-M16 + S01-S12 + WeChat）
│   ├── components.md          字体 / 卡片 / 间距 / 图标 / 标题字数表
│   ├── background-systems.md  墨流 / 网格 / 纸纹层
│   ├── portrait-fill.md       3:4 板的留白对策
│   ├── content-planning.md    钩子 / 拆页 / 文案压缩
│   ├── production-workflow.md 渲染管线与命令
│   ├── image-overlay.md       文字压图：选图 / 局部 tint / 主体映射
│   ├── screenshot-treatment.md 截图处理
│   ├── map-component.md       Mapbox / OSM / schematic 地图
│   ├── title-shortener.md     公众号 1:1 短标题
│   ├── category-cookbook.md   小红书 11 个品类的版式路由
│   ├── live-photo-production.md Live Photo 生产、拼图、长视频与发布规范
│   └── qa-checklist.md        交付前 checklist
├── agents/
│   └── openai.yaml            # 子代理配置（备用）
├── scripts/
│   ├── check-skill-docs.mjs       # Skill 文档约束测试
│   ├── make-video-contact-sheet.py # Live Photo 视频抽帧 contact sheet
│   ├── package-live-photo.py      # JPG+MOV 打包为 .pvt 的入口
│   └── *.swift                    # Apple Live Photo metadata helper
├── validate-social-deck.mjs   # R1-R9 渲染后校验器
├── package.json / package-lock.json / node_modules   # 仅 playwright
├── .gitignore                 # v0.13 新增
└── local-tests/               # 本地测试与素材（git 忽略，不随 skill 分发）
    ├── demo-*                 # 各次设计案例（kyoto / yading / wukong / kit-* / zzz-* / m16-camping / eyeliner / showcase / smoke-editorial-travel / map-component / screenshot-treatment / multi-platform）
    ├── social-card-*          # 历史与 Codex 外部测试产物（含 codex-remote-* / wukong-breakout / kyoto-guide / moon-eyes-lip-mud）
    ├── smoke-ai-tools/        # v0.6 冒烟测试样例
    ├── test-dark-theme-elden-ring/  # v0.12 Midnight Ink 验证
    ├── Image/                 # 用户上传的测试图
    ├── 全图封面参考/           # v0.10 杂志封面参考图
    ├── .codepilot-uploads/    # 历史上传缓存
    └── *.cjs                  # 旧的 debug / probe / render 脚本

v0.13 起：git 仓库。local-tests/ 整目录在 .gitignore 中，commit 只跟踪 skill 内容。

2. 数据规模与覆盖面

维度 数量
工作流步骤 7 步（Intake → Extract → Style → Plan → Seed → Build → Image → Deliver）
风格模式 2 个（Editorial Magazine × E-ink / Swiss International）
主题色 Editorial 6 套（5 浅 + 1 暗 Midnight Ink）+ Swiss 4 套 = 10 套
版式骨架 Editorial 16 个（M01-M16）+ Swiss 12 个（S01-S12）= 28 个
平台 × 比例 小红书 3:4 / 1:1，微信 21:9 + 1:1 配对，方封面 1:1
小红书品类覆盖 11 个品类中 7 个完整支持，4 个需用户提供素材，4 个明确不接
种子模板 2 份（Editorial / Swiss），单文件即含全部 class 与字体
已交付案例 7 个 demo（2 个 image-cover + 5 个 kit）
Live Photo 支持 小红书 5s / 微信公众号 3s；单视频、二宫格、三宫格、四宫格、三连拼图、长视频低成本诊断

3. 版本历史

仅记录"什么时候新增/变更了哪些可见资产"，不记录文风调整。

v0.15 · 2026-07-01（本轮）

主题：Live Photo 从一次测试能力收口成 Skill 规则。本轮把两天聊天里关于平台限制、拼图版式、长视频处理、品类判断、发布路径和执行失误的结论写回文档，并补上文档测试。

新增

  • references/live-photo-production.md：Live Photo 生产规范。覆盖 .pvt 打包、AirDrop/iPhone 测试、小红书 5s、微信公众号 3s、信息量判断、三连拼图、material-first 拼图、长视频低成本诊断、contact sheet、平台发布提醒和常见故障。
  • scripts/check-skill-docs.mjs：文档约束测试。当前卡住根目录产物、Live Photo 拼图能力、M16 图片压字规则、可见文案规则、非模板装饰禁令、平台发布提醒、产品复盘和交接记录。
  • scripts/make-video-contact-sheet.py：把视频按少量时间点抽成 contact sheet，用于长视频或 Live Photo 视觉检查，避免默认密集抽帧。
  • scripts/package-live-photo.py 及 Swift helper：把 JPG + MOV 写入 Apple Live Photo metadata 并打包成 .pvt，用于 iPhone/AirDrop 测试。

修改

  • SKILL.md 增加 Live Photo 支持范围：短 motion card、三连 Live Photo、material-first 单视频/二宫格/三宫格/四宫格拼图、长视频 intake。明确用户提供视频是正常路径，网页素材只用于 demo / promo / 测试。
  • SKILL.md 加硬规则：生成产物必须在任务文件夹，默认 local-tests/<slug>/；禁止把结果放在 Skill 根目录。
  • SKILL.md 加可见文案规则：卡面文案必须描述用户真实场景，不能把 3s、5s、Live Photo、三连拼图、信息量、长视频处理、倍速、高光检测 等内部制作词写成标题或正文。
  • SKILL.md 加 material-first 规则：单视频加字必须走 M16 / image-overlay 的图片压字逻辑；如果只有一个标题，就用断行、字号、字重、字距、对齐和位置做排版，不发明 kicker、meta、hairline、线条、刻度、徽章、字幕或说明文字。
  • references/category-cookbook.md 加 Live Photo Scene Library。它不是固定模板清单，而是判断素材在 3s / 5s 内能承载多少信息，以及适合单视频、三连、拼图、修剪还是不做 Live Photo。
  • references/platform-specs.md 加小红书 / 微信公众号 Live Photo 平台说明：小红书 5s，微信文章内 3s，发布路径以手机端为准。
  • PRODUCT.md 加 Live Photo 复盘（2026-07-01），记录这次需求、产品判断、执行问题和验收标准。

本轮测试素材与输出

  • 用户素材目录：local-tests/live-photo-best-suite/视频素材/
  • 统一测试目录：local-tests/live-photo-best-suite/puzzle-layouts/
  • 四个测试视频输出：
    • IMG_XHS_PUZZLE_SINGLE_TEXT_5S_LIVE.MOV
    • IMG_XHS_PUZZLE_TWO_STACK_5S_LIVE.MOV
    • IMG_XHS_PUZZLE_THREE_STACK_5S_LIVE.MOV
    • IMG_XHS_PUZZLE_FOUR_GRID_5S_LIVE.MOV
  • 规格：全部 1080x1440 / 5s / 24fps / 120 frames。本地测试目录被 .gitignore 忽略，不随 Skill 分发。

线程里暴露的问题，已转成规则

  • 不要把制作要求当成观众可见内容。之前错误例子包括把"三连拼图"、"5 秒看完完整幅度"、"别硬塞"写到画面上。
  • 不要自造主题、背景色、线条、刻度字或装饰组件。没有在 theme-presets.md / layout-recipes.md / image-overlay.md 出现，就不能为了"显得设计过"而加。
  • 不要为了通过密度警告给 material-first 拼图加字。二宫格、三宫格、四宫格可以无字；单视频也只能加用户场景需要的短标题。
  • 长视频不要默认做精准高光检测。只能先做稀疏抽帧和候选段诊断，再让用户选择修剪、倍速、拆成三连或指定时间段。
  • 网页下载视频不是用户工作流。那只服务我们自己的测试和宣传案例。

v0.14 · 2026-05-28（本轮）

主题：截图美化素材从 PPT skill 迁移。v0.11 当时只 port 了规则文档（references/screenshot-treatment.md 154 行）和工具类（.frame-shot.* + .device-browser / .device-phone），但 PPT skill 的真实材质 WebP 背景整目录没拷过来，导致 .bg-paper / bg-grid / bg-dot 这些舞台底全是纯 CSS 实色，截图密度高的卡片视觉偏薄。本轮把素材补齐。

改动事实：

  • 新增 assets/screenshot-backgrounds/，整目录 1.8 MB / 9 张 WebP：
    • style-a/ 5 张 Editorial：dune.webp / forest-ink.webp / indigo-porcelain.webp / kraft-paper.webp / monocle-classic.webp
    • style-b/ 4 张 Swiss：ikb-dot-gradient.webp / lemon-green-dot-shadow.webp / lemon-grid.webp / safety-orange-halftone.webp
  • assets/template-editorial-card.html 加 5 条 .frame-shot.bg-asset-* 规则，指向 style-a/ 五张图（带 fallback 实色防止素材未加载时透明）
  • assets/template-swiss-card.html 加 4 条 .frame-shot.bg-asset-* 规则，指向 style-b/ 四张图
  • references/screenshot-treatment.md 加 "Solid bg-* vs asset bg-asset-*" 小节：两张对照表 + 4 条 rules of thumb（不混 accent / 不叠 shadow-ed / 一致使用 / 高比例板不用）+ 路径说明
  • 同文件 Style cheat-sheet 加两条 recipe：Editorial hero with real texture / Swiss hero with brand-aligned stage
  • HANDOFF.md 目录结构段加 screenshot-backgrounds/ 子目录视图

重要约定：

  • 素材路径用相对 URL ../assets/screenshot-backgrounds/style-{a|b}/{name}.webp，假设 deck 的 index.html 在 local-tests/<task>/ 下（比 assets/ 低一层）。放别处需要在 deck 里本地 override 路径
  • Swiss 资产强 accent 绑定：bg-asset-ikb-dot 只能在 data-accent="ikb" 的 deck 用，不允许混色
  • 不要在 asset 背景上叠 shadow-ed——1px 描边会和材质冲突，读起来像 SaaS 框
  • r-3x4 / r-1x1 高比例板仍优先用 solid bg-*，asset 材质在过裁切时会变怪
  • 这是素材迁移，不是规则迁移：PPT skill 原版 screenshot-framing.md 的 7 参数语义系统未引入（本 skill 走 CSS 工具类路线，决策更轻）

v0.13 · 2026-05-27（上一轮）

主题：git 初始化 + 仓库瘦身。把所有本地测试 / demo / 上传图 / 旧脚本统一搬到 local-tests/，写 .gitignore 忽略整个测试目录与 node_modules/。skill 本身只保留：SKILL.md / HANDOFF.md / PRODUCT.md / assets/ / references/ / agents/ / validate-social-deck.mjs / package.json 与锁文件。

改动事实：

  • 新建 local-tests/，搬入 28 个测试目录（demo-* 16 个 / social-card-* 6 个 / smoke-* 1 个 / test-* 1 个 / Image / 全图封面参考 / .codepilot-uploads）以及 3 个旧脚本（render.cjs / debug-bg.cjs / probe-webgl.cjs）
  • 新增 .gitignore：忽略 local-tests/ / node_modules/ / .DS_Store / *.log / .vscode/ / .idea/
  • HANDOFF.md 目录结构段同步更新，列入 local-tests/ 子目录视图
  • skill 自身文件结构未变，模板与规则文档一律未改

重要约定：local-tests/ 不进 git，不分发，不放入 skill 包。demo-showcase/editorial.html 和 demo-showcase/swiss.html 仍然是字号/字距/版式还原的 source-of-truth——它们移到了 local-tests/demo-showcase/，路径变了但作用未变。所有后续 demo / 冒烟测试都应在 local-tests/ 下新建子目录。

v0.12 · 2026-05-27

主题：Editorial 美学回退 + 第 6 个杂志主题 Midnight Ink + 图片裁切策略 + 交付工作流调整。本轮起因是用户对 v0.11 冒烟测试的"质量回退"反馈——v0.10/v0.11 在把 showcase 模板化进 seed 的过程中，把 Editorial 的字重/字距/正文字族无意中改成了"信息图横幅"风（900 字重 / 负字距 / sans 正文），与 demo-showcase/editorial.html 的"克制磁带感"完全偏离。同时 Codex 外部测试 social-card-wukong-breakout 暴露了缺暗色主题、自造 wukong-night 不合规的问题。

新增

  • assets/template-editorial-card.html 增加 [data-theme="midnight-ink"] 暗色 palette + 三段必随覆盖（.grain 翻成 screen-mode 暖光斑 / .paper-wash 改成金辉 + 阴影 vignette / .frame-img 加深底色 + 1px 暖边）。Editorial palette 从 5 套变 6 套。
  • references/theme-presets.md 增 Midnight Ink 段，含色值 + 必随覆盖代码 + 使用场景（游戏 key art / 夜景 / 影调封面）。明确"暗色 Editorial 只有这一套，不要自造第二套"。
  • test-dark-theme-elden-ring/ — Midnight Ink 验证 deck（4 张 1080×1440，《艾尔登法环》新手指南）。图源 Steam 官方 8 张截图，记录在 assets/。验证 P1 全幅 hero-bleed + 黄金 accent、P2 M14 pipeline 4 步 + 21:9 atmosphere、P3 M07 ledger 4 行 + 战斗 atmosphere、P4 quote-card + 4:3 静态时刻。

修改：Editorial 美学回退（核心）

  • assets/template-editorial-card.html 全部 Editorial 排版默认值恢复 showcase 美学：
    • .h-display 124px weight 500 letter-spacing +.04em（v0.10/v0.11 误改为 900 / −.01em）
    • .h-xl 88px weight 500 +.03em（曾经 700 / −.01em）
    • .h-md 56px weight 500 +.02em
    • .lead 28px font-family: var(--serif-zh)（曾经被切到 sans-zh，是塌掉杂志感的主因）
    • .body 24px serif-zh（同上）
    • .kicker 21px letter-spacing +.22em
    • .meta / .label 18px +.20em
    • .ledger-row .ledger-title 42px weight 500，.ledger-note 22px serif-zh
    • .pipeline-v .step-title 40px weight 500，.step-desc 24px serif-zh
  • references/components.md Editorial 字号表完整改写为上述值，加一段 Restored 2026-05-27 警示，写明"v0.10/v0.11 错改值是什么，为何会塌掉，showcase 是 source-of-truth"。
  • references/style-system.md Mode A 加 Typography stance — "the larger, the lighter" 段：Editorial display 必须 500、serif body、宽字距；反模式（700-900 + sans + 负字距）= "infographic banner" 塌方。

修改：图片裁切策略

  • assets/template-editorial-card.html .frame-img img 默认 object-position 从 center top 改为 center 50%。Editorial 之前的 center top 是默认值意外，导致竖图主体被切掉；showcase 实际上是逐图 inline 覆盖。
  • references/components.md Image Containers 段加 主体感知裁切表（主体位置 → object-position 取值）+ 硬规则"每张图都要 inline 写 object-position，默认值是 fallback 不是推荐"。
  • SKILL.md Step 6 Image and Screenshot Handling Crop discipline 改写为强制每张图 inline 写 object-position，带具体取值示例（center 25% 天空多 / center 50% 居中 / center 62% 半身 / center 70% 前景物）。

修改：交付工作流（"show user first, ask before validating"）

  • SKILL.md Step 7 Deliver 重写：
    • 默认 不再 渲完自动跑 validator。
    • 渲完先把图给用户看，问一句"先你自己看，还是我先自动核查一遍？"。
    • 用户说"自己看"→ 停下来等反馈；说"你查吧"→ 才跑 validate-social-deck.mjs。
  • 起因：用户反馈每次渲完自动跑 validator 让交付窗口变得很长，用户大多数时候眼睛比脚本更快。
  • 代价：自动校验的"安全网"被撤掉一格——但脚本仍然可用、用户随时可调。

修改：已有 demo 同步

  • demo-kyoto-trip/index.html — 字号回退到 showcase 值，P4 ledger 去掉 03（岚山）解决 3:4 溢出，title 改"四条建议"。
  • demo-smoke-editorial-travel/index.html — 字号回退到 showcase 值。P1 hero 从 r-16x10 改 r-3x2 + object-position:center 62%（hero-grassland 主体在画面中下）。P5 camp-tarp 加 center 55%。两份 demo 都 4-5 张 1080×1440 重渲过，无溢出。

Codex social-card-wukong-breakout 诊断

  • 状态：未由本 skill 修复。Codex 在 v0.11 规则下做的测试。
  • 根因：Codex 实际遵守了规则——错的是规则本身。components.md 当时还在写 900/700/sans-body 默认值，Codex 照搬出来必然塌；Codex 自造的 wukong-night 是"规则没暗色"的合理外推。
  • 修复路径：v0.12 已落地 Midnight Ink 官方暗色 + 美学回退；后续 Codex 任务直接 data-theme="midnight-ink" 即可，无需自造。

未做

  1. 截图美化资产 port（仍在短期清单）
  2. 地图组件（同上）
  3. 1:1 短标题生成器（同上）
  4. 多平台一次出包（同上）
  5. social-card-wukong-breakout 未重新生成——v0.12 是规则修复，不回灌历史 Codex 测试

v0.11 · 2026-05-27

主题：短期规划 Phase A 收口 — validator + Editorial 冒烟测试。短期规划 6 件事完成第 1、2 件，把 v0.10 留下的 Editorial 长内容欠债（M11/M14 在 3:4 上从未单独验证）也清掉。

新增

  • validate-social-deck.mjs — 单文件 Node 脚本，接受 task-dir 或 index.html，对每个 <section class="poster …"> 跑 6 条规则：R1 overflow / R2 footer 碰撞 / R3 Swiss 粗体 display / R4 字号下限 / R5 4 横带密度（pixel-row union 覆盖率）/ R6 .h-xl 行/字 cap。--style=swiss|editorial 可显式指定，默认按 data-theme/data-accent 或 serif 字族 fallback 自动判断。退出码 1 仅在 FAIL 时；WARN 是 advisory。
  • package.json scripts.validate — 把 node validate-social-deck.mjs 包到 npm run validate <task-dir>。
  • demo-smoke-editorial-travel/ — Editorial 冒烟测试 5 张 1080×1440：M01 cover + M11 Marginalia Essay（3 段正文 + 7 行 marginalia）+ M07 Field Ledger（5 行账本）+ M14 Vertical Pipeline（5 步）+ M16 Image-Led Cover 收束。全部 PASS validator。
  • references/components.md § Editorial .h-xl Hard Caps — 实测表：xhs 92px / square 78px / wide 96px；附 M11/M14/M07 各自的 ledger / paragraph / step 数硬上限。

修改

  • SKILL.md Step 5 Build And Render 加：每次 render 后必须跑 validator，FAIL 必修。Step 7 Deliver 加：交付前再跑一次；WARN 在交付消息里报告让用户决定。
  • validate-social-deck.mjs 修两轮 false positive：
    • R2 footer collision：原版把 .content 容器 + 全幅 .mag-bg 误判碰底；改成只看 leaf text/media + 跳过 ≥95% 全幅 absolute 节点。
    • R4 min font：原版按 class 选择器命中所有 .lead，但 Swiss .role-card .lead 是子组件文本。改成只查 leaf text 节点的角色。
  • references/components.md § Image Containers 加：figcaption 类名硬规则——Editorial 用 .img-cap、Swiss 用 .swiss-img-caption、没有共享 .cap。冒烟测试中我把它写成 .cap 触发 R4，已固化为警示。

回归测试（在 5 个 demo 上跑过 validator）

  • demo-smoke-editorial-travel：5 pass / 0 fail / 0 warn
  • demo-zzz-miyabi：4 pass / 1 R5 warn（p4 H-Bar 底部 trailing whitespace，可接受）
  • demo-eyeliner：3 pass / 1 R5 warn（xhs-03 底带 13%，可接受）
  • smoke-ai-tools：发现一处历史 R1 overflow（xhs-03 +101px）—— 之前漏看，已暴露
  • demo-showcase/swiss.html + editorial.html：共暴露 39 + 46 条 R4/R5/R6 warn，主要是 lead/body/caption 在数据密集页里被压到 18-22px、几条 h-statement 行数超 cap。下一轮可逐张回修。

未做（同短期规划清单）

  1. 截图美化资产 port（下一件）
  2. 地图组件
  3. 1:1 短标题生成器
  4. 多平台一次出包

v0.10 · 2026-05-26

主题：内容密度硬规则 + 风格-内容类型解绑 + 全版式 showcase。两件事并轨：(1) 解决 3:4 卡内容欠填——把"杂志留白逻辑"和"社交卡逐张刷"这两件事在文档层面拆清；(2) 把"Editorial 只接生活类 / Swiss 只接产品类"的隐含绑定明确解除，让用户用同一篇内容自由选风格。

新增

  • demo-eyeliner/ — 4 张 3:4 美妆类 Editorial 案例（kraft-paper），P1 M16 全幅产品图，P2 M03 翻车叙事，P3 M01 双头机制，P4 M07 收束。验证密度规则在"图+文+ledger"混合卡上的落地。
  • demo-showcase-editorial/ — 16 张 1080×1440 案例，逐张覆盖 M01-M16，循环用 5 套杂志 palette。
  • demo-showcase-swiss/ — 12 张 1080×1440 案例，逐张覆盖 S01-S12，循环用 4 套 Swiss accent。两套 showcase 演示「内容类型与风格脱钩」——美食内容也可走 Swiss、AI 工具也可走 Editorial。

修改

  • SKILL.md Step 3 重写："Editorial 用于 / Swiss 用于" 的硬绑定改成"两种风格是 visual stance，不是 content category；任何内容都可走任一风格；选风格按 editorial intent（feature story 还是 release note），不按 topic lookup。"
  • SKILL.md Non-Negotiables 增加 3:4 内容密度硬规则：内容 ≥75% 画布高度；>15% 空白带需"留白理由"；禁用 <div style="flex: 1"></div> 上下夹击；杂志留白逻辑不适用于社交卡。
  • references/style-system.md 顶部增 "Style ↔ content type are decoupled" 段；Mode A / Mode B 的"Use for"硬列表改成"Good fits"软建议（含明确反例：workplace essay 也可走 Editorial、travel ledger 也可走 Swiss）。
  • references/layout-recipes.md：
    • Editorial 和 Swiss recipe 总览段都加了"这些结构适用于任何 topic"的前言。
    • 新增 Content density rule (hard) 段，写在 Editorial recipe 列表前。
    • M03 / M04 / M07 / M13 各加 Minimum density 段：
      • M03：title + 3 段 或 title + 2 段 + 编号 footer 列表。title 单独是 M04 不是 M03。
      • M04：唯一允许 ≤60% 内容的 recipe，但必须有 3 个 anchor（source row / kicker / hairline）。
      • M07：title + ≥4 ledger items with sub-lines + closing block。"3 短 ledger 行"是已知失败模式。
      • M13：必备 anchor（top kicker + bottom prompt + bottom metadata + 可见 WebGL bg）。
  • references/qa-checklist.md：新增 4 横带密度检查（Filled / Justified empty / Under-filled 分类，>15% 画布的 under-filled 带判失败；通过门槛：Filled+Justified ≥100%、Filled ≥75%、相邻两带不能都 justified）。
  • PRODUCT.md 决策 1 重写：风格不再绑定内容品类。删除"Editorial × 人文/Swiss × 工程"的硬对应；明确"两种风格是视觉立场不是内容门"。

修复路径（落到代码）

  • 杂志留白逻辑→社交卡的对策：用 flex-grow: 1 + justify-content: space-between 让"内容块本身撑开"，禁用空 <div style="flex:1"></div> 作为占位。demo-eyeliner P2/P4 两次重渲染后通过 4 横带检查。
  • M07 spec 从 "2-3 rules" 改成 "4-6 ledger items with sub-lines"，每行 100-140px 垂直。

未变动

  • Recipe 计数：仍是 M01-M16 + S01-S12 = 28 个。
  • Theme palette 计数：5 + 4 = 9 套。
  • 工作流步数仍 7 步；种子模板未动。
  • 小红书品类能力圈未变；只是不再把"风格-品类"硬绑定。

对比验证

  • 旧 P2/P4（v0.9 demo-eyeliner 第一版）：内容散在画布中段，底部 25%-35% 是空白带，缩略图刷过去像 PPT 漏排。
  • 新 P2/P4（v0.10）：内容撑满到 ~92% 画布高度，引语+footer 紧贴底缘；FALLOUT 四条 a-d 均匀分布到引语之上。
  • showcase 两套：28 个 recipe 每个出 1 张 1080×1440，全部通过 4 横带检查、覆盖全 9 调色、内容类型故意打散（户外 / AI / 食谱 / 数据 / 节气 / 影评等都既出现在 Editorial 也出现在 Swiss）。

v0.9 · 2026-05-26

主题：M16 编辑杂志化重写。v0.8 的 M16 借了"游戏 key art"那套（全幅黑色 vertical falloff + 132px 黑体感字 + 纯白文字），出来像旅游海报、不像 Kinfolk / Cereal。本轮按 8 张参考的共同语言推倒重来：选图是主要杠杆，遮罩是兜底；字小、字细、字色偏纸。

修改

  • references/image-overlay.md Rule 1 重写："选图先，遮罩后，禁全幅 falloff"四步法。Step 1 选图门（quiet-zone 测试 + light 测试），Step 2 默认不加 mask 直接验，Step 3 兜底用 localized + image-toned 软渐变（peak α ≤ 0.30），Step 4 缩略图测试。Banned 段把"全幅 vertical falloff"和"纯黑 mask 色"明确点名禁掉。
  • references/image-overlay.md Rule 2 增 Composition discipline 段：4 条编辑杂志构图硬规（非对称、≥60% 留白、标题只占一个 quiet zone、绝不跨越主体轮廓）。
  • references/image-overlay.md Checklist 重写：把"≥60% → 强制 mask"翻成"先看选图通不通过，mask 仅在 Step 4 失败时"。
  • references/layout-recipes.md M16 重写：
    • 顶部加 Photo qualification gate——quiet-zone test + light test 都过才能走 M16，否则退回 M01。
    • Modes A/B/C/D 表里"Mask"列改成"Tint (only if Step 4 fails)"，明确"先无 mask、不行再局部图调色软渐变"。
    • 字号字色字体彻底改：标题 88-108px（v0.8 是 108-132px），Noto Serif SC 400-500（v0.8 没限制字重，default 700+），色 #f5f1e8 纸米（v0.8 是 var(--paper) 容易跑成 #fff），letter-spacing 0.10-0.15em。
    • 加 Forbidden in M16 type 段：禁 inline 700+ 字重、禁纯白 #fff、禁标题 > 120px、禁拉丁 sans 作主标题、禁 D 模式标题居中。
    • HTML skeleton 两段重写：默认不加 mask、用 Noto Serif SC weight 500 + #f5f1e8，全 inline 字号（不依赖 .h-display，因为种子模板 .h-display 强制 color: var(--ink) 在暗背景上失效）。
  • demo-m16-camping/index.html P1 封面重做：Mode A（顶 kicker + 底标题），无全幅 mask，仅底部 22%x84% 苔绿色 (rgba(20,32,22,...)) 软 radial 在标题区，标题 92px Noto Serif SC weight 500 / tracking 0.12em / 色 #f5f1e8。HTML 注释加 photo qualification 记录。

未变动

  • Editorial recipe 计数：仍是 M01-M16。
  • Swiss recipe / theme / 工作流 / 种子模板没动。
  • demo-m16-camping P2 (ledger) / P3 (field notes) 没动——它们用的是 M05/M02 文字主导版式，没踩 M16 的坑。

对比验证

  • 旧 P1（v0.8）：黑色 78% 侧栏 scrim + 132px 字 + 整页压重。读起来像旅游打卡。
  • 新 P1（v0.9）：林荫透出、字小克制、底部苔绿软渐渍只够支撑标题对比。读起来像 Kinfolk camping 专题。
  • 缩略图测试（360px wide）：标题 / kicker / 底部 mono strip 全部可读，无糊。

v0.8 · 2026-05-26

主题：图先序列 + 满图封面 recipe。给"生活化、吃图片"的内容一个明确的 P1 图占满 + P2-3 数据的版式。

新增

  • references/layout-recipes.md 新增 M16 Image-Led Cover (Full-Bleed Hero)：填补 M01"图+文分块"到"图占满 + 文字压上"的空白。含 4 种文字位置（顶压底沉 / 侧栏立柱 / 角落徽章 / 下沉条带，按 subject map 选）、字号 spec 表、标题长度上限表、1:1 / 21:9 适配、两段完整 HTML 骨架（Mode A + Mode D）。Editorial 模式专用，Swiss 不用。Editorial recipe 数：15 → 16。
  • references/content-planning.md 新增 Image-Led Sequence 段：P1 M16 满图 → P2 文字数据卡（S11/M05/M10）→ P3 M02 副图 → … 硬规则"绝不连续两张 M16"。

修改

  • references/category-cookbook.md：
    • 旅行 / 家居 / 美食（食谱）路由首选改为 M16 → S11/数据卡 → M02 的图先序列。
    • 情感不强推图先序列（M16 不适合 quiet documentary 的 "窗 / 椅 / 手"——继续走 M04/M09/M11 文字主导）。
  • SKILL.md Seed 引用范围 M01-M15 → M01-M16。

未变动

  • 工作流步数与种子模板。
  • Swiss 12 个 recipe / 9 套 palette / image-overlay 规则。
  • M16 强依赖既有 image-overlay.md（mask + subject map + crop），没有放宽任何安全检查。

v0.7 · 2026-05-26（上一轮）

主题：Editorial 图源扩展。没有新增 layout，没有改种子。

修改

  • SKILL.md Step 6 web-sourced 图源从 3 条扩到 5 条：新增 Pexels（#2，原生支持中文搜索，补 Unsplash 在国内场景的缺口）与 Flickr CC（#3，license=2,3,4,5,6,9 过滤，补"纪实感真实感"的缺口）。加了取图顺序：Pexels（中文/国内）→ Unsplash → Flickr CC（纪实）→ direct search。明确"全部免版权图库，不接 视觉中国 / Getty / 站酷海洛 等付费源"。Swiss 模式继续不走图库。
  • references/category-cookbook.md：
    • 旅行：Pexels 优先用于国内目的地（中文关键词）；Flickr CC 用于"真实旅程"的纪实质感。
    • 美食：Pexels 用于中式菜品 / 国内餐厅；Unsplash 标注为"西式 stock 感"，仅做兜底。
    • 情感：Flickr CC 升为主推（窗 / 椅 / 手这类纪实质感最契合）；Pexels 补国内语境；Unsplash 仍然可用但避开"moodcore" gradient-light stock。
  • references/qa-checklist.md：图源 checklist 改为枚举 Pexels / Unsplash / Flickr CC / Wallhaven / direct search，并提示 Flickr CC 在用户同意标注时要保留作者署名。

新增

  • SKILL.md Step 1 Intake 加"三选一"入口：用户只给文字时问一次（A. 自己提供照片 推荐 / B. 我帮你找 / C. AI 生成），按选择走 Step 6，不二次劝导。
  • SKILL.md Step 6 "When the user has no images" 改为依赖 Step 1 gate，明确不再自动跳到 B/C。

未变动

  • 工作流步数（仍为 7 步，三选一是 Step 1 内的子项）与种子模板。
  • 9 套 palette 与 27 个 recipe。
  • 不接付费图库（视觉中国 / Getty）是产品边界（见 PRODUCT.md 决策 4）。

v0.6 · 2026-05-26（上一轮）

主题：冒烟测试 + 种子模板硬化。没有新增 layout，没有改工作流。

新增

  • smoke-ai-tools/ — 完整冒烟测试样例。主题"程序员一周 AI 工具使用周记"。用 5 张 1080×1440 跑通 S01/S07/S10/S11/S12 五个 recipe。Klein Blue accent。
  • HANDOFF.md · PRODUCT.md（本文件 + 产品文档）

修改

  • assets/template-swiss-card.html：为 .poster.xhs 补全 display 字号 override。
    • .h-hero 168px · .h-statement 124px · .h-xl 96px · .num-mega 168px · .num-xl 120px
    • .matrix-fill 改为 grid-auto-rows: min-content、min-height: 0、gap: var(--sp-4)
    • .matrix-cell .cell-title 在 xhs 下降到 24px
    • .hero-stat-bottom 在 xhs 下紧凑 margin / padding，num-mega 128px
  • references/components.md：新增两张实测对照表。
    • "Swiss .h-xl Hard Caps per Board" — 每板最多几行、单行最多几字、超限会怎样
    • "Matrix + hero-stat-bottom on .poster.xhs" — cell 数对应的搭配建议

已知遗留

  • Editorial 模板（template-editorial-card.html）未做同样的冒烟测试。M14 纵向 Pipeline 5 步在 3:4 板上是否溢出，未验证。
  • 冒烟测试只覆盖 5 个 Swiss recipe（S01/S07/S10/S11/S12）。其余 S02-S06/S08/S09 未跑过真实小例子。

v0.5 · 2026-05-26 早些时候

主题：image-overlay 规则上线 + 文字压图验证。

新增

  • references/image-overlay.md — 文字压图规则：蒙版强制 + 多模态主体映射 + 缩略图测试
  • demo-image-02-wukong/ — 用《黑神话:悟空》主视觉验证 image-overlay 规则

修改

  • SKILL.md Step 6 加入文字压图小节
  • references/style-system.md 新增 Anti-Pattern D（封面照片裸跑无蒙版）

v0.4 · 之前

主题：模板种子 + 9 个新版式补全（对齐已成熟的 PPT skill）。

新增

  • assets/template-editorial-card.html · assets/template-swiss-card.html 两份种子
  • references/components.md 字体/卡片/间距/Lucide token 表
  • layout-recipes.md 加 M12-M15（Editorial 缺失节奏型）+ S08-S12（Swiss 5 个 port from PPT）

修改

  • SKILL.md 加 Step 4.5（拷贝种子模板）
  • Required References 加 components.md

v0.3 及更早

SKILL.md + 9 份 reference 的初始体系。小红书品类能力圈（category-cookbook.md）。Editorial 11 个版式 + Swiss 7 个版式。

4. 如何验证 skill 还能跑

先跑文档层验证，确认 Skill Creator 基础格式和本仓库约束都还成立：

python3 /Users/guohao/.agents/skills/skill-creator/scripts/quick_validate.py .
npm run test:docs

quick_validate.py 只检查 Skill Creator 的基础结构：SKILL.md、frontmatter、name / description 合法性。npm run test:docs 检查本仓库新增的产品规则：根目录不产出、Live Photo 拼图、M16 图片压字、可见文案、发布提醒、产品复盘和交接记录。

最快的验证路径，不要发明新需求。

cd /Users/guohao/Documents/code/HyperFrames-test/guizang-social-card-skill/local-tests/smoke-ai-tools
node render.mjs
ls output/   # 应该看到 xhs-01.png ... xhs-05.png
sips -g pixelWidth -g pixelHeight output/xhs-01.png   # 应为 1080×1440

5 张图都能渲染、尺寸都对 → Swiss 种子模板 + 5 个 recipe 工作正常。

视觉验收：用 Read 工具读 output/xhs-04.png，确认大数字 "8" 在右下角完整可见、未被截断。

更全的 demo：local-tests/demo-image-02-wukong/index.html 用 Playwright 渲染，验证 image-overlay 规则下文字与人物未冲突。

Live Photo 视觉回归可以直接看本地测试目录：

cd /Users/guohao/Documents/code/HyperFrames-test/guizang-social-card-skill/local-tests/live-photo-best-suite/puzzle-layouts
ls output/

重点看 contact-sheet-*.jpg 和四个 IMG_XHS_PUZZLE_*_LIVE.MOV。不要重新开新目录，除非用户明确要新的测试集。

5. 工作流要点（给接手者的极简版）

按 SKILL.md 第 7 步走，不要跳步。最易踩坑的两步：

  • Step 3 不要混风格：Editorial 用 serif + ledger/marginalia；Swiss 用 Inter + card-fill/matrix。两套 class 命名空间隔离，模板间不能跨用。
  • Step 4.5 必须拷种子：从零写 HTML 是 v0.4 之前的工作流，已废弃。

文字压图的页（封面 / 大图位 / 全幅图）四步：先 Read 图、写 HTML 注释记录主体位置、选 object-position、做 360px 缩略图检查。默认先不加遮罩；只有缩略图不可读时才加局部、取自图片色调的 tint。

Live Photo 页先当静态社交卡做：先确认第一帧、裁切、字体、可见文案和模板匹配，再渲 MOV / .pvt。单视频加字走 M16 / image-overlay；二宫格、三宫格、四宫格默认无字；三连拼图只放能并行理解的三个短片段。

6. 已知风险与限制（事实层面）

  • 校验脚本是按需兜底。validate-social-deck.mjs 已可检查溢出、页脚碰撞、字号下限、密度、标题行数与 figure 默认 margin 漂移；默认交付流先给用户看，用户要求 auto-check 时再跑。
  • 没有跨平台一次出包工具。一篇文章要同时出小红书 3:4 + 微信 21:9+1:1 + 方封面 1:1，目前要手工开两个任务文件夹。
  • 品类能力圈未硬编码。category-cookbook.md 写明了 4 个不接的品类，但 skill 不会主动拒绝；需要执行者在 Step 1 自己读到并主动告知用户。
  • 图片来源签名机制是"用户决定"。SOURCES.md 总会写，但是否在图上加标注由用户回答。这不是技术限制是产品决策（见 PRODUCT.md）。
  • Live Photo 高光选择只是低成本诊断。默认只做稀疏抽帧 / contact sheet / 时间段建议，不承诺精准识别转场、空镜、黑场或最佳高光。
  • Live Photo 发布依赖手机端路径。交付时必须提醒小红书 5s、微信公众号 3s，并提醒 .pvt AirDrop 到 iPhone 后从对应 App / 手机端编辑路径发布。

7. 不要做的事

  • 不要改 PPT skill（在 ~/.claude/skills/guizang-ppt-skill/）。本 skill 借了它的视觉原则但独立维护。
  • 不要把 demo 文件夹删掉来"清理"。它们是回归测试样本。
  • 不要在两份种子模板里塞动效系统、键盘翻页、ESC 索引——那是 PPT 的需求，社交卡是静态 PNG。
  • 不要把 components.md 的硬上限表"调宽"以接更长的标题。先压文案。
  • 不要把内部制作词写到卡面上，例如 三连拼图、5 秒看完、信息量、Live Photo、长视频处理。这些词只能出现在计划、文件名、QA 或交付说明里。
  • 不要用自造背景色、线条、刻度、标签、徽章去"补排版"。先找既有模板和 reference；没有规则支持就不要加。