v2.13.2
主文件瘦身：SKILL.md 691 行 / 35.8k 字 → 481 行 / 21.0k 字（-41%），每次加载少约 4k tokens。
- 「更新日志」全量迁到 changelog.txt（原占主文件 1/3）
- 「杂志排版内核」细节迁到 references/magazine-kernel.md，主文件只留决策要点与用法
- 顺带修掉原文两个重复的「### 5)」小节编号
功能与脚本零改动，5 个测试套件全过。

v2.11.0
缺陷修复（优化版）：
- 修复 --out 在 spec 模式完全失效（此前只认 spec 文件内 out，CLI --out 被静默忽略、产物落到 cwd）；改 spec.out || CLI --out 优先级。
- 修复 --copy-gate 占位符门禁形同虚设（此前先渲染后判定，磁盘留"被判定不该出"的图）；改渲染前纯文本预检，不合格跳过出图（退出码 2）。
- SKILL.md 去除写死本地绝对路径（指向过期安装目录）→ $SKILL_DIR 占位；修正 description"每套含四变体"虚标（handcraft 无 cover、spotlight 无 content，缺失变体自动回退）。
- 清理包内 assets/templates/.DS_Store。

v2.10.1
本次升级补充技能图标，提升在 SkillHub 技能市场的辨识度与专业展示；版本号同步递增。

v2.9.1
借鉴 xhs-cover-maker「文案铁律」，新增 copy-audit 文案质量自检 + qc.js 安全区检查。


# ===== 以下为原 SKILL.md「更新日志」全量迁移（v1.0.0 起主文件只留指针）=====

### v2.13.1
- **把 `promptcard` 的适用前提变成可执行判断**（这套版式的记忆点是「封面满版图压字 + 正文以图为主体」，**手上没有能当封面的成图时它不成立**）：
  - `catalog.json` 新增机器可读字段 `requires`（要什么图 / 没有怎么办），`bestFor` 前置写明「已有可作封面的成图时」——选风格与画廊预览都能看到这个前提。
  - `slots.json` 三个含图变体的 `img.hint`、`content.panels.itemHint` 直接写清「要什么样的图 + 无图时的出路」，agent 用 `--describe` 就能读到，不必翻文档。
  - **运行期兜底 `imagePreconditionWarnings()`**：`promptcard` 的封面/单图/对比变体一个配图字段都没传时，打印一条警告（同进程去重，`--article` 拆 12 张不会刷屏），结果 JSON 附带 `warnings`。**只提示不拦截**——占位版仍是「先定稿排版、后补图」的合法用法；`table` 变体不吃图、不触发。
  - SKILL.md 新增「选风格前先过这三问」（有成图吗 / 能裁竖向吗 / 能压白字吗），任一为「不」就换风格。
  - 测试扩到 115 项：`requires` 与 hint 的存在性、警告函数四类分支（无图报警 / 有图不报 / 空数组报警 / table 与其它风格不误报）、`template` 直连也要识别。
  - 端到端实测：无图 spec 出图 exit 0 且警告只打一次；同一批里 `table` 与 `compare` 均未误报。

### v2.13.0
- **新增第 14 套模板 `promptcard`（AI 生图实测卡）**：把「原图 + 完整提示词 + 真实耗时」摆进同一张卡，五个变体成套——`universal`（单图+提示词）/ `cover`（满版压字封面）/ `content`（原图→结果对比）/ `table`（模型参数速度表）/ `coverH`（横版封面）。
  - **调用契约新增图片字段类型**：`type: "image"`（单图 `src`）与 `type: "imageList"`（多图，逐项 `{label, img}`），值支持本地绝对路径（自动转 `file://` URL）/ `data:` URI / `http(s)`；`rich` 列表新增第三个文本列 `sub.note`（参数表的「耗时」列）。
  - **模板零位图**：配图位默认内联 `data:image/svg+xml` 占位图，未传图也能出成品样张，符合 SkillHub 禁独立位图规则；真实配图运行时注入。
  - **对比卡自适应 2/3 张**：箭头用 `.panel + .panel::before` 画在面板缝隙里，不占位，2 张（换装/换背景）与 3 张（双参考图换脸）都自动等分。
  - `--article` 拆条新增 `promptcard` 字段映射（文案可拆，配图仍需 spec 显式给）。
  - 新增 `tests/promptcard.test.js`（97 项）：catalog 五变体登记、slots 与模板选择器逐段对齐（**只扫 `<body>`**——CSS 里必然写着 `.kicker{}`，扫全文会让断言恒真）、图片值解析、`--article` 字段不漂移、零位图约束。
  - 实测：五变体各出一张（含 2 图 / 3 图对比）QC **0 严重项**，剩余 warn 均为设计上故意的小字（已用 `data-qc-minfont` 标注）。

### v2.12.2
- **新增第 13 套模板 `handlist`（手绘卡通清单）**：笔记本纸质感（点状纹理+横格线+纸张投影）+ 粉马克笔高亮标题 + 5 色循环编号圆（奇偶微旋转）+ 每条目手绘 SVG 图标 + 底部黄高亮结语条 + 角落涂鸦，**装饰全内联 SVG 零 emoji**。
  - **内置卡通手绘字体**：站酷快乐体（默认）/站酷小薇体/马善政毛笔楷三款 woff2 以 base64 内联进 `handlist/handlist-fonts.css`（约 7.5MB，仍在 10MB 包上限内），模板经 `<link>` 引用、data URI 不受 file:// 字体 CORS 限制，`render.js` 与 `gen.js` 两条路径实测均正常加载（`document.fonts` 确认 loaded 且字宽异于回退字）。
  - **字体一键切换**：`:root` 的 `--font-hand` 单变量控制全局，注释内附切换示例——除三款卡通字外还兼容思源黑体（Source Han Sans SC/Noto Sans SC）与阿里巴巴体（Alibaba PuHuiTi）系统字体栈（需本机已装，缺失回退 PingFang）。
  - 四变体齐备：通用/cover/content/cover-h（横版流式适配），`slots.json` 登记 rich 列表契约（kicker/title/items×6/footer），`catalog.json` 已登记；`--article` 拆条实测出封面+内容+结语整套。
  - 修复模板源尾部溢出（`.paper` 高度不足裁掉底条涂鸦 4px）。

### v2.12.0
- **工艺升级（借鉴 `canvas-design` 的设计纪律，提升审美下限 + 字体可靠性）**：
  - **打包拉丁 display 字体**：从 canvas-design 引入 6 款 OFL 字族（Gloock/Italiana/Bricolage×2/DMMono/EricaOne，共 384K，远低于 10MB 包上限）入 `assets/fonts/`，`render.js` 渲染前以 base64 内联注入（避开 headless Chrome 的 file:// 字体 CORS 限制），`document.fonts.load` 等就绪再截；`magazine.css --mz-font-display` 首顺位改 `CD Gloock`，标题/刊头英文数字更精致，中文自动回退系统字。
  - **CJK 字体探测门禁**：`resolve-browser.js` 新增 `detectCJKFont()`（fc-list → macOS 系统字体文件 → Linux 文件系统扫描，三级纯本地探测）；`render.js --check` 输出中文可用性报告，新增 `--cjk-gate` 中文缺失直接退出、不出空白废图（根治此前 Linux headless 静默出废图的痛点）。CJK 整字库因 10MB 包上限不打包，走系统字体 + 探测告警。
  - **精致度复检 `--craft`**：`qc.js` 新增 `craftChecklist` 与 `--craft` 开关，把质检硬信号翻译成"布局基础/留白/强调色/装饰/层级"自查清单，每次出图提醒先稳结构再美化。
  - **设计纪律沉淀**：SKILL.md 新增「出图前先定调」（视觉层级/唯一强调色/钩子落点）、「系列视觉贯穿线」（强调色+母题跨封面/内容/结语贯穿）、「布局纪律」（绝对定位只给装饰、文字块走流内、footer 用 `margin-top:auto`），并补排版坑点 #4（字体）#9（布局）。新增 `assets/templates/_shared/motifs.html` 母题画廊（祥云/网格/账本格/叶脉/双线）。

### v2.11.0
- **缺陷修复（优化版）**：
  - 修复 `--out` 在 spec 模式完全失效：此前只认 spec 文件内的 `out`，CLI `--out` 被静默忽略、产物落到 cwd；现改为 `spec.out || CLI --out` 优先级（已端到端验证）。
  - 修复 `--copy-gate` 占位符门禁形同虚设：此前先渲染后判定，磁盘留下「被判定不该出」的图；现改为渲染前纯文本预检，不合格直接跳过出图（退出码 2）。
  - SKILL.md 去除写死的本地绝对路径（指向过期安装目录），改为 `$SKILL_DIR` 占位；修正 description「每套含四变体」虚标（handcraft 无 cover、spotlight 无 content，缺失变体由 gen.js 自动回退）。
  - 清理包内 `assets/templates/.DS_Store`。

### v2.10.1
- 补充技能图标（icons/icon.jpg），提升 SkillHub 市场辨识度；版本号同步递增（同阶段的 v2.10.0 为小步版本，无独立变更日志）。

### v2.9.1
- **借鉴 `xhs-cover-maker` 的「文案铁律」经验，新增两层零模板改动的能力**（A 文案点击率 + B 质检漏检）：
  - **文案质量自检 `copy-audit.js`**：纯文本扫描主标题/强调/正文，断言 6 条规则（占位符门禁/主标题≤14字/结果>过程/绝对化词/语义重叠/缺钩子）。`gen.js` 出图后自动跑（warn/info 不阻断；`--copy-gate` 时残留占位符阻断出图，`--no-copy-audit` 关闭）。
  - **qc.js 新增「安全区」检查**：核心文案中心落在画布安全边距外时 warn（信息流 UI/裁切会遮挡），仅竖直信息流平台启用、自动豁免页脚/署名等边角装饰件，避免 46 模板误报。新增 CLI `--safe-zone` / `--crop` 调试开关。

### v2.9.0
- **预置 8 类常用 SVG 图形模板**：新增 `assets/templates/_shared/svg-presets.html` 可渲染速查画廊——流程步骤 process、时间轴 timeline、对比条 comparison、漏斗 funnel、循环图 cycle、金字塔层级 pyramid、环形占比 donut、2×2 矩阵 matrix。每类自包含复制即用，统一 magazine 调色板 hex + 衬线/黑体字族角色差，含「适用场景 + 容量上限 + 改图三步」提示。
- **回归测试补 2 条**：断言 svg-presets.html 存在且含 8 类 preset 与 ≥8 个 SVG；断言 SVG presentation 属性不出现 `var()`（防再踩「fill="var(...)" 不生效」的坑）。

### v2.8.1
- **约定：示意图优先用内联 SVG 生成**（零素材、矢量任意放大、改 HTML 即改图、批量重渲风格 100% 一致，先看效果再决定是否换真图）。
  - **新增 `.mz-fig-svg` 容器**（`magazine.css`）：内联 SVG 示意图的正式主场，替代原来的空占位色块 `.mz-plate`，已自动 `break-inside: avoid`（多栏流里不会被劈开）。
  - **两个骨架图位换成真实 SVG 示例**：`skeleton-split.html` 的「配图三段法：网格 → 层级 → 细节」流程、`skeleton-broadsheet.html` 的「双线刊头 + 栏线」版面关系。此前这两处是空占位块，渲出来是空白。`fullbleed` 保持 `.mz-plate--occlude`（满版照片位，非示意图），不受影响。
  - **qc.js 豁免修正**：小字豁免判定从 `el.matches()` 改为 `el.closest()`，使 `.mz-fig-svg` 容器内的 SVG `<text>` 标注能被正确豁免（此前容器内后代元素匹配不到，导致示意图标注被误报「字号过小」）。
  - **回归测试补 3 条**：断言 split/broadsheet 图位用内联 SVG 且无空占位块、断言 qc 豁免 `.mz-fig-svg`。
  - **避坑提示已写进文档**：SVG 里不能写 `fill="var(--mz-accent)"`（`var()` 只认 CSS 上下文，写在 XML presentation 属性上不生效），用 hex 或 `style="fill:var(...)"`。

### v2.8.0
- **杂志排版内核（让叙事更「高级」）**：不再是「再加一套杂志风皮肤」，而是补一层排版机制。
  - **标题自动收缩 `data-autofit`**（render.js 默认开启，`--no-autofit` 可关；gen.js 卡片/长图自动跑）：截图前按「最大行数」二分收缩字号，治所有 46 个模板文案一长就撑破卡片的通病（思路源自 magazine-layout-editor 的 `AutoFitHeadline`）。
  - **`magazine.css` 排版内核**（`assets/templates/_shared/magazine.css`）：零图片的 `--mz-` 前缀排版件——三级字族角色差、五级字号阶梯、首字下沉、pull quote、图注/边注、分栏与跨栏标题、遮挡压字、刊头条线、出血。与现有 12 套模板 `:root` 变量零冲突，直接 `@import` 即用。
  - **三个可直接渲染的骨架样张**（`skeleton-split/fullbleed/broadsheet.html`）：已填示例文案，照改即可。适用面：小红书用 `fullbleed` 装饰向（不分栏，避免字号掉出 24px 被 qc 标黄）；公众号长图用 `split` 真双栏。
  - **editorial/content 模板升级挂载 magazine.css**：从「固定 px 字号编号清单」改成刊头/kicker/首字下沉/pull quote/栏线/角标/folio 的杂志正文页，作为 3:4 装饰向 magazine.css 的真实示例。
  - **qc.js 杂志小字豁免**：图注/边注/署名/页码/刊眉/竖排自动豁免字号检查；并支持 `data-qc-minfont` 局部自定义下限与 `--min-font` 全局阈值。
  - **回归测试** `tests/magazine.test.js`：覆盖 autofit 纯函数、magazine.css 关键类、骨架文件、qc 白名单，全量测试 4 套共 156 项全绿。

### v2.7.0
- **AI 辅助声明改为默认不加、可选项**：移除了 handcraft / spotlight / doodle-content 五处模板里写死的「AI 辅助生成」文案与 `slots.json` 的 `default` 自动填充。现在所有模板（含这五处）默认都不带 AI 标识；需要时在卡片 spec 的 `fields.foot`（或 doodle-content 的 `aiNote`）自行填写声明文案即可，页脚元素已预留、字段填了才显示（CSS 加了 `:empty{display:none}` 避免空页脚占位）。`long` 长图模板的 `footer` 字段同理默认空、可填。文档已同步修正此前"仅小红书下自动补"的错误描述。

### v2.6.0
- **新增单张长图模式 `--long`**：把整篇文章或结构化 spec 渲染成一张流式高度的长图（`assets/templates/_shared/long.html`），宽度固定 1080、高度自适应，fullPage 截图输出。适合公众号贴图、汇报长图、表格数据一图流。
- **新增多图确认门禁 `--multi` / `--long`**：内容较多（`--article` 自动拆条会生成 4 张及以上）时，若未指定 `--multi` 或 `--long`，gen.js 会输出决策提示并退出码 `3`，强制 agent/用户先确认发布形态，避免默认刷出一堆图。`--plan` 干跑不受此限制。
- **更新 SKILL.md / contract.md**：新增"多图轮播 or 单张长图"章节，明确 agent 必须先确认输出形态。`slots.json` 登记 `_shared/long.html` 模板。

### v2.5.0
- **新增 3 套原创模板（填风格缺口，零图片素材）**：`compare`（测评对比，红蓝双色 A/B 强对比 + VS 徽标 + 深色结论条，填补「横向测评 / 红黑榜 / 二选一」格式）、`editorial`（杂志分栏，暖纸底 + 砖红 + 衬线刊头 THE REVIEW，填补「美妆 / 穿搭 / 生活方式」精致赛道）、`guochao`（国潮新中式，宣纸米黄 + 中国红 + 金印章 + 矢量祥云，填补「国货 / 传统文化」赛道）。每套均补齐 `通用 / cover / content / coverH` 四变体，全部纯 CSS/SVG 装饰、零图片素材（符合 SkillHub 禁图规则，且跨机零依赖）。`catalog.json` 追加三 entry（各含 file/cover/content/coverH 四键 + 5 色调色板）、`slots.json` 登记全部 12 个模板路径（coverH 均含 title 字段），`gen.js` 的 `mapSectionToFields` 新增三 case 支持 `--article` 自动字段映射。
- **qc 0 严重项**：三套竖版模板经 `render.js --qc` 全绿（badge 字号与对比度已按 qc 阈值修正，如 compare badge 改 `#C0392B` 达 4.5:1、guochao 印章金字改白字）；横版 coverH 仅装饰性小字 warn（与既有 9 套 cover-h 行为一致，非 error）。新增 `tests/new-templates.test.js`（78 项：catalog 四变体键、resolveTemplatePath、slots 登记、coverH 含 title、content 含 rich items、4 HTML 物理存在）。
- 实测：3 张 spec 卡 + compare / guochao 各 6 张 `--article` 拆条卡，全部 **0 错误 0 警告**；模板总数 12 风格 × 4 变体 = 46 个真实模板 HTML（`slots.json` 为契约唯一数据源，零改动、不破坏已 QC 样张与画廊）。

### v2.4.1
- **改名（展示名）**：`displayName` 由「HTML 转高清图片卡」改为「社交平台配图生成」，标题同步更新；`slug` 不变（URL、已发布版本均不受影响）。定位从「技术机制（HTML 渲染）」转向「用例（社交平台配图）」，更贴合目标人群搜索习惯，提升 SkillHub 点击 / 转化。

### v2.4.0
- **横版封面开箱即用（coverH）**：为全部 9 套风格新增横版封面变体 `cover-h/template.html`，catalog 登记 `coverH` 键、slots 登记字段（title 必填 + subtitle 可选）。gen.js 在检测到横版平台（宽高比 > 1.1）时，封面自动选用 `coverH`，竖版平台行为不变（`pickVariant` 对缺 `coverH` 的风格回退 `universal`，零回归）。横版封面采用 fluid 布局（100% 视口 + vw/vh 自适应），同一模板适配 bilibili(1146×717) / xtwitter(1200×675) / wechat(900×383) / slide(1920×1080)，含最极端的 2.35:1 超宽屏也 0 严重项。新增 `tests/horizontal-cover.test.js`（44 项：catalog/slots 登记、resolveTemplatePath、横竖平台判定全绿）。
- 实测：9 风格 × {bilibili, xtwitter} 共 18 张横版封面 QC 全部 `0 严重`（仅装饰字形对比度 warn）；出图尺寸精确命中平台预设 ×2（bilibili 2292×1434 / xtwitter 2400×1350 / wechat 1800×766 / slide 3840×2160）。

### v2.3.0
- **整篇文章自动拆条**：gen.js 新增 `--article <file>` 文件入口、spec 内 `article` 字段、`--stdin` 内联三种入口，启发式把 Markdown/纯文本拆成「封面 + 每章节一张内容卡 + 结语卡」的标准 spec 直接出图——内容生产者丢一篇稿子即出整套系列图。新增 `--plan` 干跑模式（只输出 cards spec，不渲染，便于无浏览器环境核对拆条结果）。拆条函数为纯函数并可 require 单测（`tests/article-split.test.js`，7 项全绿）；支持 dark-editor / binder / doodle / grid-notes / minimal / literary / notepad / handcraft 八种风格的自动字段映射。
- **新增平台预设**：`slots.json.platforms` 补充 `bilibili`(1146×717) / `zhihu`(1080×1440) / `xtwitter`(1200×675) / `douyin`(1080×1920)。注意：现有 9 套模板以竖版 3:4 为主，横版/异形平台（bilibili/xtwitter/wechat）需模板按比例适配，直接套用会触发 qc「内容被裁」警告——属预期行为（qc 价值即提醒需横版模板变体），横版开箱即用模板列为后续增强。
- 实测：dark-editor xhs 拆条出 5 张卡 QC 0 严重 / 0 警告；bilibili 尺寸预设生效（出图 2292×1434）。

### v2.2.0
- **agent 结构化调用契约（gen.js）**：消费者定位为 AI 工具（WorkBuddy 等 agent），不再要求人改 HTML。新增 `scripts/gen.js`——吃 JSON spec（style+variant 或 template 路径）→ 按 `assets/templates/slots.json` 的字段 schema 校验（必填/字数/条目上限）→ 用 puppeteer 按选择器填充 → 渲 PNG → 结构化 QC 回传；支持 `--describe`（自助查字段）、`--list`、`--stdin`、批量 `cards`、退出码 2 回传校验错误。新增 `contract.md` 详述 spec 形状、列表三模式、平台/合规、错误码。
- **修正 catalog.json 与实际文件不一致**：`handcraft` 无 `cover` 变体、`spotlight` 无 `content` 变体（仅 25 个真实模板，非 27）；`gen.js` 对缺失变体给出明确报错。
- `slots.json` 覆盖全部 25 个模板的字段→选择器映射（rich/simple/repeat 三列表模式），doodle/content 支持列表条数自动写回「NN 个」。
- 实测：doodle content（rich+badge+autoCount）、dark-editor content（simple+`**高亮**`）、literary（repeat+`**高亮**` 三卡）均 0 严重项，选择器全部命中。

### v2.1.1
- **9 套模板全部补齐封面/内容双变体**：每套风格现在都有 `template.html`（通用）+ `cover/template.html`（封面版：大标题钩子、少信息）+ `content/template.html`（内容版：清单/要点、高密度）。旧 7 套 `doodle / notepad / grid-notes / binder / literary / minimal / dark-editor` 各新增 cover/content 子目录；`handcraft` 补 content 清单版，`spotlight` 补 cover 封面版。
- **dark-editor content 版去品牌**：小红书向内容版 footer 不再出现具体自媒体署名，改中性署名。
- 全部 16 个新模板通过 `render.js --qc` 质检，**0 严重项**；warn 均为装饰性浅色小字/彩色背景白字，按规则可放过。
- `catalog.json` 每套增加 `cover` / `content` 字段；各 README 增加"封面版/内容版变体"说明与文案锚点。

### v2.1.0
- **新增 2 套去同质化模板**：`handcraft`（手写暖色首图，散落旋转卡片+楷体，刻意不像批量模板）与 `spotlight`（紫粉渐变聚光单焦点）。两者为天生一对——首图列手写清单、次图单讲一个工具/观点，专治小红书「N个神器合集 9 卡轮播」被判低质/同质化限流的问题（实测踩坑后沉淀）。
- 两套模板均内置**合规铁律**：不带品牌（小红书账号 ≠ 公众号，禁带公众号名/二维码/导流）、工具名须同时出现在标题+正文+图。**AI 辅助声明默认不加**——若发布到要求标识的平台（如小红书），在 `fields.foot` 自行填写声明文案即可（页脚元素已预留，字段填了才显示）。
- `catalog.json` 已登记两模板，总览选择器（gallery-html.js）可预览。

### v2.0.0
- **可靠性重写**：新增 `scripts/resolve-browser.js`，自动探测浏览器与 puppeteer 依赖（env → 缓存中**实测可执行**的最新版 → 系统 Chrome/Edge/Chromium），跳过"下载未完成的空版本目录"，彻底去除机器专属硬编码路径。换机 / 升级浏览器不再挂。
- **渲染 CLI 化**：`render.js` 支持 `--preset/--w/--h/--scale/--out/--only/--type/--quality/--qc/--check` 等参数；尺寸优先级修正为 **显式指令 > 卡片 meta > 默认**（原先卡片 meta 会覆盖用户显式指令）。
- **自动化质检**：`qc.js` 五项断言（页面溢出 / 元素越界 / 内容被裁 / 字号过小 / 对比度不足）+ 同类聚合，发布前替代肉眼逐张验收。
- **7 套设计模板**：`doodle / notepad / grid-notes / binder / literary / minimal / dark-editor`，全部纯文字 + CSS/SVG 装饰、零图片素材，每套含真实示例样张 `template.html` + `README.md` 变量表与文案锚点。
- **风格选择器**：`gallery-html.js` 一键生成可在浏览器放大查看的总览页（每个模板真实渲染预览 + 色板 + 复制命令），用户先看效果再选风格；另保留 `gallery.js` 拼单张 PNG 联系表。
- **缺陷修复**：base64 内联图片编码错误（新版 puppeteer 返回 Uint8Array 导致图裂）、grid-notes 白底白字误报、fullPage 尺寸误报。
- **发布前踩坑经验固化**：装饰性绝对定位元素一律用 `bottom` 从 footer 往上锚定到已知空白带，绝不压内容文字；右上角默认不放作者名（模板 `.brand` 改为可选，留空即不显示）。
