guizang-social-card-skill/PRODUCT.md

# Product — guizang-social-card-skill

这份文档讲**为什么**。事实在 `HANDOFF.md`。

---

## 1. 这个 skill 解决什么问题

**真正的问题不是"画图"，是"把一篇文章变成一组能打的小红书图"。**

普通用户的现实链路：

1. 写完一篇文章（笔记 / 影评 / 攻略 / 周记 / 教程）。
2. 想把它发小红书或公众号，需要 5-9 张图 + 1 张封面。
3. 没有设计师，没有时间在 Canva / Figma 里逐张拉。
4. 用模板套，又被几百个相似封面挤掉点击。
5. 让 AI 生成，结果大部分 AI 出图就是"题目放正中 + 渐变背景 + 一个 emoji"。

我们要在第 2-5 步之间插一个东西，让产出不像 AI，又不需要用户懂排版。

### 核心矛盾

- **质量**：要像 Guizang 这种磁带、墨水、左对齐网格的杂志感，不能像 PPT 模板。
- **效率**：要 30 分钟内能拿到可发布的图，不能让用户在 prompt 上反复打磨。
- **不假**：数据、报价、版本号不能编。文字压图不能压到人脸上。

三者之中**质量是分水岭**。Canva 模板已经解决了效率。AI 出图已经解决了速度。但都没解决"看一眼就知道是用心做的"这件事。

---

## 2. 产品定位（一句话）

> 把一篇文章交给 Claude，30 分钟内拿到一组可以直接发的小红书图或公众号封面，**长得像一本被偏爱的杂志**，而不是套模板。

这里"被偏爱的杂志"是一个具体的视觉锚点：

- 上海译文社的封面
- The New Yorker 的内文版式
- Apartamento / Kinfolk 的留白节奏
- Massimo Vignelli / Helmut Schmid 的瑞士网格

不是"能看"或"好看"，是**能让人停下手指**。

---

## 3. 目标用户与典型场景

主要画像是 **"内容创作者 + 工程师 / 产品 / 设计师 / 自由职业者"**。共同点：自己有内容，没有"组里专门做封面的人"。

| 场景 | 用户类型 | 输入 | 期望输出 |
| --- | --- | --- | --- |
| 周报 / 工具周记 | 工程师 / 产品 | 一段 Markdown + 数字（小时数 / 价格） | 5-7 张小红书 3:4，数据图 + 总结 |
| 旅行 / outdoor | 摄影爱好者 / 旅人 | 一组照片 + 文字日志 | 一张公众号封面对（21:9 主图 + 1:1 方图，同一篇文章的两个尺寸）+ 5-9 张小红书组图 |
| AI / 产品 release | 创业者 / DevRel | 一段更新说明 + 截图 | 一组 Swiss 风的 release deck |
| 影视 / 游戏笔记 | 影评 / 游戏播客 | 一段评论 + 主视觉 | 1 张大图压字封面 + 数据榜单 + 总结页 |
| 美食 / 食谱 | 美食博主 | 文字步骤 + 成品照 | 3:4 教程卡（用户提供照片） |
| 健身 / 家居 / 穿搭精选 | 生活方式博主 | 推荐清单 + 产品图 | 推荐卡 + 单品图 |

**反向画像**（这个 skill 不服务他们）：

- 想做 OOTD / 日常自拍：我们不生成人像照片。
- 想做菜品大片摆盘：我们不替代专业美食摄影。
- 想做"梦核 / Y2K / kawaii"：和我们的两套视觉系统正面冲突，硬接出来一定难看。

这些在 `references/category-cookbook.md` 里写明了"不接"，是产品决策，不是技术缺口。

---

## 4. 用户视角的核心思考

整个工作流是按"用户脑子里的步骤"组织的，不是按"代码模块"组织的。

| 用户脑子里 | Skill 对应步骤 |
| --- | --- |
| "我有这篇东西，想发小红书" | Step 1 Intake |
| "我该出几张？写什么标题？" | Step 2 Extract Story + Step 4 Plan Pages |
| "我要这种感觉的图，不要那种" | Step 3 Choose Style Mode |
| "随便先出一版我看看" | Step 4.5 Seed + Step 5 Build |
| "这张图有问题，再改改" | Step 5 重渲染 + Step 7 Deliver |

每个步骤都有一个明确的"用户在意什么"：

- **Step 1 不要审讯式提问**。能从已有信息推断就推断，只问真的会改变结果的问题（平台、比例、必须出现的元素）。
- **Step 2 是产品差异**。一篇 1000 字的笔记，应该是 5 张图还是 9 张？哪些段落该被丢进文案区不放进图？大部分 AI 工具不做这一步——这是为什么它们出的图像"被切碎的文字"。
- **Step 3 不让用户选"主题色"**。让用户选"感觉"：是杂志感的人文叙事，还是瑞士的工程冷感。色板是结果，不是入口。
- **Step 4.5 是体力活的拐点**。v0.4 之前每次任务都要从零写 HTML，能写出来，但一致性差。种子模板把"杂志的形"固化下来，让 AI 把精力花在"内容如何变形"上。
- **Step 6 文字压图**是最常翻车的位置。v0.5 之前 AI 经常把标题压在人脸上，看起来不假但很难看。`image-overlay.md` 强制三步走（读图 / 写主体映射 / 选 object-position）后才把这块兜住。

---

## 5. 关键设计决策（为什么这样做）

### 决策 1：拆两套视觉系统，不做"一站式"

更通用 = 更平庸。我们决定**只做两件事**：

- **Editorial Magazine × E-ink**：serif + 墨水 + 杂志结构（ledger / marginalia / pull quote / photo well）
- **Swiss International**：Inter + 一种 accent + 工程结构（matrix / KPI tower / h-bar / 编号 statement）

不做"卡通 IP 风"、"少女风"、"国潮"、"Y2K"。一个 skill 同时维护 5 种风格的结果一定是 5 种都做不好。

**注意**（v0.10 起明确）：两套系统是**视觉立场**，不是**内容类型门**。一篇 AI 笔记可以走 Editorial（如果你想要它读起来慢、像专栏），一组旅行支出也可以走 Swiss（如果你想要它读起来像数据报表）。我们曾在 v0.9 之前在文档里把"Editorial = 人文 / Swiss = 工程"写得过死，结果出现"美食教程一定要塞进 Editorial 哪怕用户想要 step 数据感"这种错误路由。v0.10 解绑：选风格按"你想要这篇内容读起来什么节奏"，不按"这篇是哪个品类"。代价是用户多一道选择题，收益是别再让风格绑架内容。

代价：用户如果想要的"梦核氛围"在我们能力圈外，要在 Intake 时直接告知，不能硬接。这是产品边界，不是 bug。

### 决策 2：种子模板 = 不可见的设计师

v0.4 之前，每次任务 AI 都从空文件开始写 CSS。结果是：

- 字体栈每次都重新写，偶尔忘记加 fallback。
- 间距 token 每次都重新发明，导致两张图之间间距不一致。
- 卡片填充逻辑混乱，Swiss 的"四类卡片互斥"规则形同虚设。

种子模板把这些**藏在用户看不见的地方**。用户拿到的产出依然是"一份 HTML"，但 AI 不用再每次重新决定"是用 `--gap-7` 还是 24px"。这是为"质量上限"和"一致性"花的成本。

### 决策 3：components.md 的硬上限是"产品承诺"

`.h-xl` 在小红书 3:4 板上 96px、最多 2 行、单行最多 8 个汉字。这不是技术上限——CSS 当然允许写 120px、3 行、12 个字。这是**产品承诺**：

> 我们承诺出的图不会让你尴尬。
> 如果你的标题撞破这个上限，AI 会主动建议你压缩文案，而不是悄悄把图拉变形。

很多 AI 工具的失败模式是"用户说什么就硬塞什么"。我们选择反过来——**告知用户文案太长，比交付一张丑图更礼貌**。

### 决策 4：图片来源"先取后说"

`SKILL.md` Step 6 的 web-sourced 部分写得很明确：

> Policy: 先取，后告知，让用户决定。不要靠猜版权预先过滤。

理由：

1. 大多数 AI 工具的"版权安全"逻辑实际是"假装版权安全"。在 Unsplash / Wallhaven 取图本身不构成侵权，**是否在终稿署名是用户的判断**。
2. 用户是终稿的所有人。把决策权交给他，附上 `SOURCES.md` 留痕，是更尊重也更准确的做法。
3. 等"完美的免版权图库 API"会饿死。先解决"小红书今天能发"，慢慢解决"版权完美"。

### 决策 5：暗色 Editorial 只开一套——Midnight Ink

v0.12 之前 Editorial 只有 5 套浅色 palette。Codex 在测试黑神话主题时自造了 `wukong-night`，事后看是合理外推（游戏 key art 强行套浅色 paper 会塌），但 skill 文档当时还在写"用 5 套之一不要改"，造成"规则太死 vs. 视觉合理"两难。

v0.12 解法：**新增官方暗色 Midnight Ink，但只开一套**。

- 开一套的理由：游戏 / 夜景 / 影调封面这类内容确实需要暗背景，硬塞浅色 palette 是质量塌方。
- 不开多套的理由：暗色 palette 的差异（金辉 / 冷蓝 / 紫罗兰 / 血红）很容易滑向"游戏宣传海报"的廉价感。一套金辉（`#d4a04a`）作为默认 accent，既呼应黄金树 / 神道 / 唐宋夜画这类经典暗调，也守住"杂志感不是游戏感"的底线。
- 用户想要其他暗色 accent → 优先建议改用 Swiss 暗变体（未来可考虑）或回退选最接近的浅色 palette 重新构图。

这是和"决策 1：拆两套视觉系统不做一站式"同一类思路——**少而准 > 多而平庸**。

### 决策 6：交付前不自动跑 validator，问用户再决定

v0.6-v0.11 都把 validator（`validate-social-deck.mjs`）写成"渲完必须自动跑"。v0.12 改成"渲完先把图给用户看，问一句要不要核查，用户说要才跑"。

起因是真实工作流里的两件事：

1. **校验耗时**。一份 5 张图的 deck 跑一遍 R1-R6 + 重渲修补，常常 5-10 分钟。多数情况用户的眼睛在 30 秒内就能扫出"哪张需要改"。
2. **校验的盲区**。Validator 测的是溢出 / 字号下限 / 行 cap，**测不出** "这张图气质塌了 / 这个 ledger 第三条没说人话 / 这个 accent 在暗背景上太蜡黄"——这些是用户最在意的、也是 AI 最容易翻车的位置。

所以让用户做第一道审查、自动校验作为兜底的可选项，而不是反过来。代价是"完全自动化"的承诺降级——但这个 skill 的目标从来不是无人工，是**30 分钟内出图**。校验时间从默认路径里抠出来，能直接让平均交付时间从 8-12 分钟压到 3-5 分钟。

### 决策 7：所有图必须是静态 PNG，没有动效

社交平台导出后只显示静态图。任何 motion / animation / WebGL 交互在最终产物里**不可见**。所以：

- 不引入 Motion One / Framer Motion
- 不写翻页 / 键盘导航 / ESC 索引（这些是 PPT skill 的需求）
- WebGL 背景只用于一次性渲染纹理，不真的"动起来"

这条决策让 skill 比同等复杂度的"PPT 网页"轻一个数量级。

---

## 6. 反模式（我们主动拒绝的事）

文档里散落着多处 anti-pattern。这里集中归一下：

1. **不可读的小字**：正文低于 26px on 1080×1440 → 拒绝。
2. **重字号 + 重字重的标题**：Swiss 80-120px 配 weight 700 → 拒绝。"越大越细"是 Swiss 的内核。
3. **任意装饰 SVG**：blob、雨滴、kawaii 贴纸、随手画的圈 → 拒绝。
4. **嵌套卡片 / SaaS 拼盘**：默认布局不应该是"卡片里再放卡片" → 拒绝。
5. **裸跑图片压字**：照片占 ≥60% 画面但没加蒙版 → 拒绝。
6. **假数据 / 假版本号 / 假报价** → 拒绝。
7. **一图复用到所有比例**：把 21:9 直接裁成 1:1 → 拒绝。两个比例必须分别构图。
8. **图上加教程说明**：键盘快捷键、操作步骤压在卡上 → 拒绝（教程内容写在 caption / 文案区）。

每一条都对应了线上观察到的"AI 出图很糟"的具体形态。这些拒绝是 skill 的**护城河**。

---

## 7. 未来想做的事

按 ROI 排序。下面分两层：**短期已规划** 和 **中长期会做**。最末尾只有一条是真的不做。

### 短期已规划（下两轮内开工）

1. **Editorial 模板的冒烟测试**。v0.6 只在 Swiss 上跑了真实小例子，Editorial 模板尚未做同样的硬化。预计会暴露 M14 纵向 Pipeline 5 步在 3:4 上的溢出，以及 M11 Marginalia Essay 的字号上限。下一轮优先做。

2. **校验脚本 `validate-social-deck.mjs`**。在 Step 5 渲染后自动跑：
   - 检查每张图的 `scrollHeight` 是否超过 board 高度（v0.6 用 Playwright `evaluate` 验证过这个方法）
   - 检查正文字号是否低于平台最小值
   - 检查 `.poster.xhs` 上的 `.h-xl` 是否超过硬上限
   把 "渲染前看不出来 / 渲染后才发现溢出" 这种坑用脚本兜底。

3. **一次出多平台的"包"**。当前一篇文章如果同时要发小红书 + 公众号，要开两个任务文件夹各做一遍。可以做一个 `deck` 概念：一份 source content → 同时产出 **小红书 5-9 张 3:4 组图** + **公众号封面对（21:9 主图 + 1:1 方图，同一封面的两个尺寸）** → 一次渲染出全部 PNG。
   关键设计点：避免把 21:9 内容直接缩到 1:1（产品决策 7 已禁止）。需要在 plan 阶段就为 21:9 写长标题、为 1:1 写一版短标题。

4. **1:1 短标题生成器（公众号封面对的同源短标题）**。21:9 主图用 "一周的代码 · 我和五个 AI 工具的同居生活"，1:1 方图用 "AI 同居生活"。注意这是**同一篇文章的封面对**，不是组图——21:9 有水平空间放长标题，1:1 没有所以必须压短。当前两个尺寸的标题靠 AI 自由发挥，可以加一个明确的"6-8 字短标题"约束在 Step 2 的 plan 阶段。

5. **地图组件**。旅行类内容经常需要"路线图 + 关键节点"。Mapbox 静态 API 出图能用，但目前要 AI 现写代码调用。可以做成一个 `.map-block` class，传 GeoJSON 进去自动出。
   **执行路径**：用 Mapbox Static Images API（免费额度够冒烟测试），出 1080×720 或 1080×1440 PNG，限制底图为 `light-v11` / `dark-v11` 两种以匹配 Editorial / Swiss 的中性基调，禁用花哨色板。节点用 Swiss 编号风（黑底白数字）或 Editorial 墨点风，避开默认蓝针。GeoJSON 仅接 LineString + Point，复杂面/标注超出范围。
   **路由**：先接入 `category-cookbook.md` 的"旅行"路由，作为 M02 / S08 的可选 inset；不强推。

6. **截图美化资产（从 PPT skill 借现成的）**。Tutorial / News 类目最大的痛点是"截图本身不好看"——背景太杂、有阴影、文字太多。可以加一组工具：自动加圆角、自动模糊背景、自动裁安全区。
   **执行路径**：`~/.claude/skills/guizang-ppt-skill/` 已经有现成的截图处理资产，直接 port 过来即可（与 v0.4 拷 Swiss class 的方式一致——只搬截图美化相关的部分，不带 PPT 翻页 / 动效那一坨）。
   **范围控制**：只搬"加圆角 / 加阴影 / 加 device frame / 裁安全区"四件套，不带 PPT 那边的多窗格拼贴；社交卡是单屏阅读，截图最多并排两张。

### 中长期会做

7. **品类专属配图 prompt 库**。`category-cookbook.md` 已经路由"什么品类 → 用哪些 recipe"，下一步是"什么品类的封面图应该用什么 prompt 去生成"。outdoor 需要"晨雾 / 冷调 / 35mm 胶片感"，AI 产品需要"keyshot 渲染 / 极少元素 / 单光源"——这些 prompt 现在散在每个任务里重写。

8. **小红书 1:1 图文（"小绿书"）的种子**。当前两份种子主打 3:4 + 21:9。1:1 是次要适配。如果"小绿书"格式起飞，需要一份独立的 1:1-first 种子。

9. **AI 出图后处理**。Gemini / Imagen 生成的图经常有"AI 印记"（多手指、变形字、不自然光照）。可以加一步"AI 出图 → 用 Read 工具读 → 标注问题 → 给用户决定要不要重出 / 局部重绘"。
   **执行逻辑**（重点，因为分析图片耗时）：
   - 默认**渲染完成后不自动分析**，避免每次任务多一次几十秒的等待。
   - 渲染完成后在交付消息里主动问一句："这页图里 AI 生成了 `assets/hero-xxx.png`，要我帮你检查一下有没有 AI 印记吗？需要几十秒。"
   - 用户说要 → 用 Read 工具读图、给出问题清单（多手指 / 文字变形 / 光照断裂）、按问题严重度建议"接受 / 局部重绘 / 整张重出"。
   - 用户说不要 → 跳过，正常交付。
   也允许在 Intake 阶段就指定"出图后默认帮我检查"，让需要严格质控的用户一次配置长期生效。

10. **视频 + 图组合包**。让 skill 出完 5 张图之后，调用独立的视频 skill（`seedance-prompt` / `video-wrapper`）顺手出一个 15s 短视频，作为小红书第一帧的"动态封面"。
    **执行边界**：本 skill 不自己做视频生成，只做**调度** —— 把 plan 阶段拿到的钩子、调色、文案传给视频 skill，避免重复一次内容理解。

11. **Web UI / 拖拽编辑**。Skill 的最终产物是 HTML+PNG，技术上可以做一个轻量的"出完图后让用户在浏览器里拖一下"的小编辑器（比如 React 包一层、改改文案/换图/调间距、再触发重渲染）。
    **执行边界**：不做"从零拼版"的 Canva 平替——那背离了"文本 → 设计"的核心链路。只做**渲染后微调**，作为最后一公里。

### 真的不做

12. **风格自定义 / 用户主题色**。诱惑很大，但一旦开放，质量会崩。当前 10 套 palette 是经过视觉验证的上限。让用户传一个 `#A3FF21` 进来，AI 配的衍生色大概率难看。除非有"色板生成器"先过一层，否则不开。
    这是一条**产品边界**：宁可让用户从 10 套里选一个最接近的，也不让用户精确指定。和"不接 OOTD / 梦核"是同一类决策。

---

## 8. 度量方向

目前没有自动度量，全靠看产出。如果未来要量化，三个方向：

- **完成率**：一个真实小例子（5-9 张图）的端到端用时。目标：30 分钟以内（v0.6 的冒烟测试在 ~25 分钟做完，含修两次 overflow）。
- **首版可用率**：第一次渲染出来的图，用户不需要任何修改就能发的比例。目标：> 60%。
- **品类匹配命中率**：用户说出小红书品类后，路由到的 recipe 用户接受的比例。目标：> 80%（不接受的需要进 `category-cookbook.md` 调整）。

这些都暂时是"心里的目标"，没有埋点。

---

## 9. 给接手者的两句话

> 当你拿到一份内容，先问"这是不是我们能力圈内的品类"。
> 当你出完一张图，先问"如果用户截屏发给朋友，朋友会不会愿意停下来看"。

前者管"不假"。后者管"能打"。两件事都做到，这个 skill 就值得继续存在。