Imported from YinsenWANG/feishu-ppt-skill (SKILL.md). Install upstream with npx skills add YinsenWANG/feishu-ppt-skill. Copyright stays with the author (MIT).

Cherry Studio 设计语言 v1.0

⭐ 默认模板（2026-08-19 定稿，2026-08-20 更新定位）：本 skill 是 Cherry Studio 相关 PPT 的默认设计系统。

80/20 使用策略（2026-08-20 用户定稿，原 70/30 收紧）：

• 80% 遵循模板：优先使用模板库（templates/）的页面骨架、布局模式、设计令牌与组件样式——保证跨页一致性（页眉/标题区/页脚稳定，翻页不跳动）；标题断行、卡片布局、间距必须贴住模板结构，不自行发明
• 20% 自由发挥：内容与模板版式不贴合时，允许在内容区内做有限组合调整（卡片数量/密度/装饰），但骨架、标题区、页脚、对齐方式保持模板原样；调整后必须 lint + 截图目检，确认无溢出/错位

标准骨架（2026-08-20 用户定稿）：内容页默认必须用统一骨架——标题一行 @(40,76) fs30 粗黑 + 副标题 @(40,121) fs13 灰 + 内容区从 y≥166 开始（P19/P25 等标准模板即此结构）；只有特殊模板（slide16 步骤编号卡、slide17 三支柱等）才保留其专属标题区。套用前先确认模板标题区类型，内容属于"能力/指标/清单"类时优先选标准骨架模板（P19/P25/P26），不要套 slide16 的两行大标题骨架（实战：P3/P4 能力总览套 slide16 被否，改 P19 四宫格通过）

• 底线（100% 必须满足）：排版准确——对齐、居中、不重叠、不溢出、不越界；自由只发生在内容区，骨架（页眉/标题/页脚）不动；任何改动必须过三级校验 + 截图目检
• 判断标准：模板是默认选项，自由是有理由的例外；拿不准先用模板，内容确实塞不下再微调

模板优先流程（2026-08-20 用户定稿，制作 PPT 必走）：

1. 先搜索模板，再想布局：接到任何一段内容，先翻 templates/INDEX.md 的场景索引，找有没有贴合或稍加改造可用的模板页（如"四步流程"找 P26、"问题方案"找 P13/P35、"数据对比"找 P25/P36）
2. 匹配就用/改造，不新建：找到了就用该模板页，只做内容替换 + 必要微调；不要从零新建一套布局（51 页模板覆盖了绝大多数场景）
3. 没有匹配才新建：只有 INDEX.md 里找不到贴合场景时，才允许用组件库自由组合新建页面
4. Lucide 图标尺寸规范：Lucide 只做小尺寸装饰 icon（≤40px，用于卡片标题/列表项/标签），禁止放大做主视觉（线条风格放大后细节不足、显呆板）；大尺寸视觉用 <img>（生图）或 <chart>（图表）

• 模板描述即场景：INDEX.md 每页的「适用/适合内容」就是搜索依据——内容与描述匹配 = 用该页

模板严格场景规则（2026-08-20 用户定稿）：

1. 目录模板有严格应用场景：P07（编号列表）只用于 5 章节目录、P08（卡片网格）只用于 6 章节/主题、P09（进度条）只用于长 deck 分节定位——必须严格遵守页数要求，不要往目录模板硬塞不同数量的章节（如 P07 塞 8 个 = 误用）
2. 套模板必须清理全部模板文字：交付前把每页 <p> 全部列出，检查有无模板原话残留（如「结论：先明确希望听众记住什么。」「每一步都有明确输入、负责人和可验证输出。」）——正文、结论条、统一原则、底部说明都要换干净，只留品牌名/页脚
3. 编号列表 ≠ 内容卡（2026-08-20 用户定稿）：P16/P26 等编号列表模板只用于流程/步骤/要点；表达「痛点/机会/对比」等内容时用卡片墙/双栏对照/2×2 网格（卡片化表达），不要用编号列表（视觉上像目录，不贴合内容）
4. 必须有封底（2026-08-20 用户定稿）：任何 PPT 交付前检查最后一张必须是封底（P51 谢谢观看模板），缺少则用 P51 补页（替换副标题/联系方式/年份，lint + 截图验证）；封面 + 内容页 + 封底是完整结构
5. 禁止空文本框（2026-08-20 用户定稿）：交付前必须扫描删除所有空文本框（<shape type="text"><content...><p></p></content> 或无 <p> 的 content）——飞书渲染时会在空文本框显示「点击添加正文」占位符，很丑；模板右上角标注（如「封面 · 左对齐大标题」）替换后若留空框，必须整体删除该 shape（不是清空文字） 在线预览：https://mcnnox2fhjfq.feishu.cn/slides/Tm0as9VdtlFknLdYX4BcOJdin4b

与其他 skill 的关系（重要）：本 skill 是 Cherry 品牌设计语言与 51 页模板库。当用户要求 Cherry 风格/套用本库模板时，本 skill 优先于 lark/lark-slides 的通用设计原则（如"信息密度极高""禁止装饰线条"等通用规则，本库按品牌需求采用极简+留白+彩线）。但必须继续遵守 lark-slides 的硬性技术规则：960×540 画布边界、fontSize 显式设置、<img> 元素、lineSpacing 写法、图表用 <chart>、表格行高合计=表格高度。技术排障以 lark/lark-slides 官方为准，本 skill 的排障表是实战备忘。

依据 20 张官网与桌面端截图 + 官方 Logo 提炼。所有视觉产出（PPT/海报/封面/招商材料）应遵循本规范。

设计理念

以温和的中性色构建专业秩序，用克制而多元的色彩表达 AI 的开放、友好与创造力。

• 现代：系统无衬线字体、模块化网格、真实产品界面
• 极简：暖白画布、细边框、大留白、少装饰
• 友好：柔和圆角、浅彩色图标底、珊瑚红品牌色
• 专业：黑色主 CTA、清晰层级、稳定对齐、真实数据

核心不是"科技炫酷"，而是"可信赖的日常 AI 工作台"。中性色负责结构，彩色负责识别和引导。

色彩系统

核心中性色

模板实际色板（追认，2026-08）

模板库（51 页）经深度 review 后实际用色，与上方规范兼容但更精确，agent 套模板时以模板实际色值为准，不要按上方规范"纠正"模板：

品牌色：珊瑚红

规则：品牌红不承担全部交互；不做大面积红色渐变；与 AI 多元色不同时大量出现。

AI 多元色

用法：2-4px 关键词下划线、8-10px 状态圆点、48-64px 图标浅色底座、选中卡片 1px 彩色描边。 避免：六色同时大面积填充、混用两种强调色于同一组件。

色彩比例

• 82-88%：白/暖白/极浅灰
• 9-14%：黑灰文字/边框/黑按钮
• 3-5%：品牌色 + AI 多元色

深色页禁用：整页深色背景 / 大面积深色填充块均禁用（黑仅用于文字与图标线条）。

字体排版

字体栈

font-family: Inter, "SF Pro Display", "PingFang SC", "HarmonyOS Sans SC", "Microsoft YaHei", sans-serif;

• macOS 中文：PingFang SC
• 跨平台：HarmonyOS Sans SC / 思源黑体
• 英文数字：Inter / SF Pro
• 不用衬线、圆体、艺术字、未来主义字体

PPT 字号映射（16:9, 1920×1080）

飞书 SML 模板（960×540 画布）实际字号（模板库为准，字号即 pt）： 封面标题 36-40 / 章节标题 40 / 内容页标题 28-30 / 数据数字 42-64 / 卡片标题 16-18 / 正文 12-14 / 标签 10-11 / 页脚 10。 套模板时用实际字号，不按 1920 表缩放；替换文字后以 xml_lint 溢出检查为准。

间距

• 大标题行高 1.05-1.15；正文 1.5-1.65；卡片标题 1.25-1.35
• 标题-副标题 16-24px；副标题-主体 40-64px；卡片标题-正文 12-16px
• 8px 基础间距单位：4/8/12/16/24/32/48/64/96

文案原则

• 一页一个观点、一卡一个概念
• 标题一行；副标题一句话或用中点连 3-4 短语
• 正文每卡 ≤3 行，不靠缩小字号
• 数字前置："50+ AI 服务商"
• 关键词用粗体 + 彩色短下划线（3-4px 厚），不整段变色
• 外链用 ↗ 箭头，不另放冗余按钮

布局系统

• 12 栏网格，左右边距 96px，栏间距 24px，单栏约 122px（1920 宽）
• 顶部安全边距 64-72px，底部 56-72px
• 内容占画布 55-70%，其余留白
• 对齐：官网标题居中、产品界面左对齐；一页一个主对齐轴
• 层级顺序：留白 > 字号字重 > 背景差 > 细边框 > 局部色彩 > 阴影

页面结构模板

• 封面：品牌 → 主张 → 行动 → 产品证明（上下结构）
• 章节页：居中大标题 + 编号 + 一行浅灰说明 + 彩线（留白 60%）
• 内容页：3×2 功能卡 / 2×2 长卡 / 左截图右说明卡 / 徽章+Logo 矩阵
• CTA 页：一个结论 + 一个黑色主按钮 + 二维码/联系入口

卡片系统

组件规范

按钮

主按钮：黑底 #0A0A0A、白字 16-18px/600、高 48-54px、圆角 14-16px、无阴影。 次按钮：白底/透明、1px #DEDEDC 描边、文字 #55555B、高 38-42px、圆角 10-12px。 一组按钮只允许一个黑色实心。

标签与徽章

属性标签：高 30-34px、圆角 15-17px、#F6F6F4 底、文字 14-16px #77777E。 荣誉徽章：高 64-72px、白底、第三方品牌色描边、保留原始标志。

图标

• 默认 20-24px、大功能 26-32px、线宽 1.5-2px、圆角端点
• 容器 56-64px、圆角 14-18px、AI 色浅底 + 对应主色图标
• 统一线性或简化面性，不混 3D/拟物/插画

产品截图展示

• 桌面壳层：macOS 三色圆点 + 顶部标签栏 + 左侧 72-76px 图标栏
• 窗口圆角 24-30px、边框 1px #E5E5E3
• 保留窗口顶部 56-68px 壳层，周围留 ≥32px 空白
• 聚焦弹窗时外围降至 30-45% 不透明度
• 多图统一缩放/圆角/阴影方向

状态元素

• 状态圆点：8-10px 直径，绿色 #22C76A 表示在线/成功
• 彩线下划线：3-4px 厚、距基线 3-5px、覆盖关键词 70-100%、每行 ≤3 处、关键词保持黑色

阴影体系

规则：中性黑灰、不带蓝紫；不叠加厚边框+重阴影；同页阴影一致；静态卡片优先无阴影。

反模式（17 条）

1. 大面积蓝紫渐变、霓虹光晕、"赛博 AI"背景
2. 珊瑚红铺满整页、所有按钮做成品牌红
3. 同页大量高饱和彩色填充
4. 每卡重阴影、玻璃拟态、发光描边
5. 小圆角硬矩形或全胶囊
6. 纯黑大面积背景作为常规内容页
7. 艺术字、科技字体、斜体中文、过宽字距
8. 无意义粒子/网格/波纹/装饰球填满页面
9. 卡片正文超 4 行或缩小字号硬塞
10. 一页多个核心观点 + 多个黑色 CTA
11. 产品截图裁掉窗口特征或透视倾斜
12. 混用线性/3D/照片/卡通图标
13. 用彩色文字替代关键词下划线
14. 统一重绘第三方荣誉徽章
15. 只靠颜色传达状态
16. 粗黑边框、强烈分割线、高对比棋盘区块
17. 原样引用截图里时效性数字/模型名，不重新核实

PPT 落地规范（1920×1080, 16:9）

全局

• 背景 #FAFAF9；安全区左右 96px、顶 64px、底 56px
• 12 栏网格，栏距 24px
• 页标题左边线 X=96；页脚基线 Y=1024
• Logo 左上角：X=96、Y=64、宽 150-190px
• 每页只有一个黑色主行动元素

封面母版

• Logo X=96 Y=64 W≈180 H≈44
• 主标题 X=96 Y=240 W=850-1050 H=150（48-60pt）
• 副标题 X=96 Y=420 W=780 H=70
• CTA X=96 Y=520 W=210-260 H=56
• 产品窗口 X=880 Y=185 W=920 H=720
• 或居中版：主标题 X=260 Y=190 W=1400 居中；产品截图 X=280 Y=560 W=1360 底部可裁切

章节页

• 编号 X=160 Y=250 14-18pt 彩色；主标题 X=160 Y=310 W=1600 40-48pt
• 副标题 X=160 Y=420 W=1200 18-22pt；标题关键词下 4px 彩线
• 深色章节页 ≤20%，深色背景 #111111、文字白、辅助 #A8A8AD

内容页

• 眉题 X=96 Y=64；标题 X=96 Y=105 W=1500 28-34pt；结论 X=96 Y=170 16-20pt；内容起始 Y=250
• 页码 X=1770 Y=1015 9-11pt #96969C
• 3×2 功能卡：内容区 X=96 Y=270 W=1728 H=680，单卡 W=560 H=318，间距 24px，内边距 32px，图标 60×60
• 2×2 优势卡：左卡 X=96 右卡 X=972，单卡 W=852 H=300，内边距 32-40px
• 左截图右卡：截图 X=96 Y=280 W=840 H=650；右侧 2-3 张纵向卡 X=984 W=840

数据卡

• 400-550×230-300px、圆角 18-20px、内边距 28-32px
• 大数字 44-60pt #171717 + 数字下 3px 彩线
• 标题 18-21pt/600、说明 13-15pt #77777E
• 不用饼状渐变或仪表盘装饰

对比卡

• 左右等宽、间距 24px、白底浅边框
• 推荐方案：1px 品牌红/AI 色描边 + "推荐"浅色标签
• 支持项用简洁勾选，不支持用浅灰短横线
• 最多 6-8 个维度，重要差异粗体+彩线

流程卡

• 水平 3-5 步：01 → 02 → 03...
• 每步 W=280-320 H=180-220 圆角 18px
• 编号 14-16pt 浅灰/彩色、图标容器 48-56px、步骤名 18-20pt/600
• 连接线 1-2px #DCDCD9；关键步用青/紫描边

章节编号/页码/页眉页脚

• 章节编号格式 01 / 市场机会，11-14pt，编号用 AI 色
• 页码右下 08 / 24 或单独 08，9-11pt #96969C，封面/章节页可隐藏
• 页眉左章节名/Logo，右材料属性"合作伙伴计划 · 2026"，9-11pt
• 页脚左来源，右页码；联系方式集中在 CTA 页

Review 能力（排版检查 + 设计护栏）

三级准出链（2026-08-20 升级）：

1. 官方 schema：xml_lint.py → error_count=0（技术合法性）
2. 排版检查：scripts/review_layout.py → errors=0, warnings=0（越界/溢出/重叠/错位）
3. 设计护栏：scripts/review_design.py → errors=0（颜色白名单/字号层级/结论条/CTA/深色页），warnings 人工裁决

python3 scripts/review_design.py --dir templates/    # 目录全检
python3 scripts/review_design.py --input slide.xml   # 单文件

设计护栏检查项（G1-G8）：

• G1 颜色白名单：所有颜色必须来自 tokens.yaml（单一来源），禁止自由近似色
• G2 强调色限量：每页高饱和强调色 ≤2 种（珊瑚红 + ≤1 个 AI 色）
• G3 字号层级：页标题 28-30 / 卡标题 16-18 / 正文 12-14 / 标签 10-11；正文 <10 报错
• G4 结论组件可选：如用结论，禁止页面底部（y>430）横贯式长胶囊条；结论可用内容区内短条/卡片（宽度 ≤420、圆角 ≤12）
• G5 CTA 唯一：每页行动按钮 ≤1，禁用黑色填充 CTA（白底 + 珊瑚红描边）
• G6 排版底检：越界/负坐标/溢出/重叠（沿用 review_layout）
• G7 密度与留白：内容区占画布 55-70%，单卡正文 ≤4 行
• G8 深色禁用：整页深色背景禁用；大面积深色填充块禁用（黑仅用于文字）

本 skill 自带排版 Review 脚本：scripts/review_layout.py，创建/修改模板后必须跑一遍，自动检查：

用法：

# 检查整个模板库
python3 scripts/review_layout.py --dir templates/
# 检查单个文件
python3 scripts/review_layout.py --input slide01.xml
# JSON 输出（供脚本解析）
python3 scripts/review_layout.py --dir templates/ --json

准出标准：errors=0, warnings=0 才算通过。warning 允许人工判断（如封底稀疏内容属预期）。

配合：官方 xml_lint.py（schema 语法）+ 本脚本（排版布局）+ 截图目检（渲染最终确认），三者为完整 Review 链。

组件库（2026-08-20 从 V3.0 合作方案 PDF + 51 页模板提炼）

制作 PPT 时按内容选组件自由组合，不必完整套用模板页。所有组件遵循白底设计语言（PDF 深色风格已转白底版）：

组合原则：每页 1 个主标题 + 1 类核心组件；高饱和色（珊瑚红/青）每页 ≤3 处；文字层级 主标题 30pt → 卡标题 18pt → 正文 13-14pt → 说明 10-11pt。

模板库（51 页布局，参考页）

templates/ 目录含 51 页完整布局 XML（960×540 飞书 slides 格式）+ INDEX.md（51 页场景索引与选择指南，每页标注适用场景/结构/示例/替换指引）。 在线预览：https://mcnnox2fhjfq.feishu.cn/slides/Tm0as9VdtlFknLdYX4BcOJdin4b （51 页完整版，可直接打开对照）

使用流程（6 步，不可跳过）

1. 读 templates/INDEX.md 按内容类型定位最合适布局（或用下方决策树）
2. 复制模板 + Logo 到工作目录（从 skill 根目录拷）：

   SKILL_ROOT=~/.hermes/skills/creative/cherry-studio-design-language
   cp $SKILL_ROOT/templates/slideXX.xml ./my-slide.xml
   cp $SKILL_ROOT/assets/cherry-logo.png ./cherry-logo.png
   test -f ./cherry-logo.png   # 门禁：图片必须到位（lint 不查图片存在性）

3. 替换内容（注意：模板是"示例内容"，不是 [占位] 占位符——按 INDEX.md 每页的"必换字段"清单定点替换：标题、数据、图片、邮箱、年份、右上版式名、页脚 Internal Template；禁止把示例数据/虚构客户/邮箱直接交付。版式可微调：内容多少与模板不符时，允许按上方"替换原则"调整卡片尺寸/间距/字号/模块数，以内容呈现最优为准，但保持品牌视觉规范）
4. 校验（官方准出）：xml_lint.py（当前环境 lark-slides skill 的 scripts/）→ error_count=0；再用 scripts/review_layout.py 检查排版（越界/溢出/重叠，errors=0）
5. 创建/更新：见下方 lark-cli 命令（+create 或 +update-slide）
6. 回读验证：+xml-get 断言页数、img 已变 file_token、关键标题已变；+screenshot 目检（不能出现 Internal Template 和版式标签）

布局覆盖

封面/转场×7（P1-P6、P51：P1 品牌 / P2 产品 / P3 章节 / P4 三栏方案 / P5 彩点 / P6 CTA / P51 谢谢）/ 目录导航×3（P7-P9）/ 文本论证×8（P10-P17）/ 数据图表×8（P18-P25）/ 流程架构×7（P26-P32）/ 产品方案×6（P33-P38）/ 规划组织×6（P39-P44）/ 生态社区×6（P45-P50）= 51 页

布局选择决策树

内容是什么？
├── 封面/收尾 → P1 品牌 / P2 产品 / P3 章节 / P4 三栏方案 / P5 彩点 / P6 CTA / P51 谢谢
├── 目录 → P7 列表 / P8 网格 / P9 进度
├── 文本/论证 → P10 单栏 / P11 分栏 / P12 金字塔 / P13 问题方案 / P14 引用 / P15 三支柱 / P16 编号要点 / P17 图标要点
├── 数据/图表 → P18 大数字 / P19 四指标 / P20 对比 / P21 柱状 / P22 折线 / P23 饼图 / P24 双图 / P25 表格
├── 流程/架构 → P26 横向 / P27 时间线 / P28 循环 / P29 层级 / P30 中心辐射 / P31 输入输出 / P32 泳道
├── 产品/方案 → P33 截图+要点 / P34 功能矩阵 / P35 问题解决 / P36 对比表 / P37 ROI / P38 客户故事
├── 规划/组织 → P39 路线图 / P40 组织架构 / P41 成员卡 / P42 RACI / P43 里程碑 / P44 甘特
└── 生态/社区 → P45 徽章 / P46 Logo墙 / P47 数字墙 / P48 评价墙 / P49 合作 / P50 总结

组合策略（常见场景推荐页）

占位符规范（诚实版）

重要：模板文件是示例内容（硬编码了演示文案/数据/邮箱/年份），不是 [占位] 占位符。替换时必须按 INDEX.md 每页的字段清单定点替换：

替换原则（2026-08-20 更新：模板是起点，允许合理调整）：

模板不是不可变的"死版式"，而是品牌视觉的骨架。在保持品牌核心规范（纯白底、粗黑标题、珊瑚红彩线、黑 CTA、16px 圆角、留白节奏）的前提下，允许根据实际内容和需求做细微调整：

不可破坏的品牌底线：纯白底（非暖白）、文字 #171717、边框 #D6D6D2、珊瑚红只作彩线/点缀、黑色唯一 CTA、圆角 16px、深色整页禁用。

调整后的验收：任何调整（尤其字号缩小/卡片改动）后，必须重新 xml_lint.py + review_layout.py + 截图目检，确保无溢出/重叠/越界。宁可缩小字号 + 增加行距，也不要让文字溢出卡片。

XML 结构铁律（2026-08-20 实战）： 0. 背景定义铁律（最高优先）：<slide> 的 <style> 第一个匿名 fill 必须是白色背景（<fill><fillColor color="rgba(255,255,255,1)"/></fill>），后续命名 fill（id=）才能放品牌色——否则整页底色会变成第一个 fill 的颜色（实战：P4/P5 整页变红）；新建/重建页面时对照模板库 slide04 的开头结构

1. <slide> 下只能有 <style>、<data>、<note>——所有 <img>/<shape>/<table> 必须在 <data> 内
2. <p> 内禁止字面换行符 \n（渲染被省略）——多行拆成多个 <p>
3. 表格 <td> 内的 <fill> 后必须跟 <content>（</fill>content 缺 < 会 mismatched tag）
4. 表格 cell 生成时 <td><{fill}content 当 fill 非空必须 <td><fill>...</fill><content...

设计护栏 G4 结论条识别：浅红底 + 珊瑚红边框 + 高度 28-44（对照卡 h=56 不误判）。

审美规范（2026-08-20 Codex 审美 review 定稿）： 0. 页面下方禁长胶囊条（用户定稿）：页面底部（y>430）禁止使用横贯式的浅红/珊瑚粉长胶囊条（圆角长条 + 结论文字）——用户明确觉得"不好看、抢眼"；结论性内容用内容区内的短条/卡片表达，或干脆省略

1. 深色填充块禁用：纯黑（#171717）只用于标题和正文文字，禁止用于大面积填充（卡片/表头/CTA 条）。深色元素用浅灰底（#F5F5F4）+ 深灰文字代替，或白底 + 珊瑚红/深灰描边
2. 红青语义固定：珊瑚红 = Cherry Studio / 价格核心 / 最终行动；科技青 = 硬件伙伴 / 渠道 / 进行中流程；深灰 = 正文与结构；浅灰 = 背景和次要信息；黑色 = 仅标题和最高层级文字
3. 视觉重量一致：全稿深色块数量控制——不要连续多页出现实色块；每页最多 1 个强视觉焦点
4. 留白 vs 空洞：内容组应占据有气场的面积（标题+内容整体居中或左对齐铺开），避免元素缩在角落造成"空洞感"；留白需要稳定对齐轴
5. 装饰克制：箭头/圆点/彩线等装饰元素数量适中，浅色可用但不要零碎抢眼；同类组件（编号、标签）颜色语义统一

页面骨架（2026-08-20 定稿，内容页默认骨架）：

• 页眉：Logo 28×28@(44,24)、右上标注@(730,28)
• 标题区：主标题 30pt 粗黑@(40,76)、副标题 13pt@(40,121)、珊瑚红彩线 48×4@(40,152)
• 内容区：默认起点 y=190（图表/表格/特殊版式模板可按自身结构，但同一 PPT 内保持一致）
• 结论条：禁止页面底部（y>430）横贯式长胶囊条；如需结论用内容区内短条/卡片（宽度 ≤420）
• 页脚：@(40,510)、页码@(880,510)
• 翻页时骨架必须静止，只有内容区变化——这是"死模板一致性"的本质

内容区布局模式（有限集合，标准坐标）：

替换前必读（2026-08-20 实战教训）：

1. 先分析每个文本元素的语义角色（主标题/副标题/卡片标题/说明/页眉标注/页脚），再定点替换——同一页可能有多个「标题」角色（右上页眉标注 vs 主标题），漏改会重复；grep '<p>' 列出全部文本后逐个判断
2. 语义完整性 > 关键词替换：替换后整句/整卡必须语义闭环（如封底主标题「把一体机，变成」缺宾语 = 断裂）；替换后把每页 <p> 全文读一遍，检查是否有话说到一半
3. 表格是重灾区：按单元格替换时行数据容易串列（A 行内容跑到 B 行）；改表格后逐行回读验证（伙伴/背景/状态列对齐）；行数增减时表格 height 必须 = 行高合计
4. 数量对称：左右对照布局（问题/方案、对比）两侧条目数必须一致，塞入不同数量内容会失衡；内容多时用「灵活版式」调整卡片数/密度，不要硬塞
5. 替换后全库文本检查：把所有 <p> 拉出来读一遍（语义）+ 检查同页重复文字（除品牌名/页脚外不应重复）

lark-cli 命令速查（飞书 CLI）

环境要求（重要！）

• 必须用 terminal 工具跑（execute_code 子进程缺 gateway 环境会报错）
• 身份：默认显式 --as user（用户资源）；只有用户明确要求才用 --as bot
• profile：本机已通过 LARKSUITE_CLI_PROFILE 环境变量锁定本机默认 app profile（勿跨身份操作）。写操作前用 lark-cli auth status 确认当前身份与目标资源一致；跨机器使用时 profile 按本机配置，勿硬编码
• 相对路径：--content/--slide/--pages 只接受相对路径
• 图片占位符：<img src="@./cherry-logo.png"> 相对当前目录解析（不是 @file 的目录）——运行前确保当前目录有图片

命令

# 新建
lark-cli slides +create --title "标题" --as user
# 加页（图片自动上传）
lark-cli slides +add-slide --presentation $PID --slide @./slide01.xml --as user

批量建页（≤10 页/次，避免逐页循环重复上传图片）

# 一次性建多页（图片自动上传，去重）
lark-cli slides +create --title "标题" --slide @./s01.xml --slide @./s02.xml ... --as user
# 共用图片先传一次拿 file_token，模板 <img src> 换成 token 引用，再逐页 add-slide
lark-cli slides +media-upload --presentation $PID --file ./cherry-logo.png --as user

整页重写（保持 slide_id 不变）

lark-cli slides +update-slide --presentation $PID --slide-id $SID --content @./slide01.xml --as user

局部替换（block_insert / block_replace，其他 action 拒绝）

lark-cli slides +replace-slide --presentation $PID --slide-id $SID --parts '[{"action":"block_replace","block_id":"bXx","replacement":"<shape .../>"}]'

回读

lark-cli slides +xml-get --presentation $PID --as user

截图

lark-cli slides +screenshot --presentation $PID --slide-number 1 --slide-number 2 --slide-number 3 --as user

批量截图用逗号形式：--slide-number "1,2,3"

实际输出路径以返回 JSON 的 screenshots[].path 为准（默认 .lark-slides/screenshots/）

更新前必做：防覆盖用户手动修改（2026-08-20 用户定稿，最高优先）

任何 +update-slide / +replace-slide 批量操作前，必须先检查版本，用户手动改过必须妥善合并，禁止直接覆盖。

1. 先回读线上当前版本：lark-cli slides +xml-get --presentation $PID --as user，保存线上 XML
2. 对比线上 vs 本地（逐页）：
   • 文本差异：<p> 内容不同（含 <span> 内的用户编辑痕迹——飞书编辑器会把用户改过的文字包成 <span fontSize="...">）
   • 图片差异：<img> 数量/位置/src（file_token）不同（用户可能手动加/换图）
   • 页面顺序：slide_id 顺序与本地假设不符（用户可能重排页面）
3. 发现差异 = 用户手动修改过：
   • 逐项列出差异给用户确认，或合并（把用户修改应用回本地版本，保留我的必要修复）
   • 绝不直接覆盖：不要用本地 XML 整体替换含用户修改的线上页面
4. 历史版本兜底：若已误覆盖，用 +history-list 找用户修改后的版本 → +history-revert 回滚 → +xml-get 保存用户版 → 合并修复 → 重新更新
5. 批量更新前风险自查：本地 XML 是否来自模板（缺用户加的主视觉图/产品图？）——用模板做整页替换时最容易丢图，先对比 img 清单

验证清单（创建/改写后必做）

1. ✅ 官方 xml_lint.py → error_count=0（唯一准出；注意 lint 不校验 @./ 图片存在性，缺失图片到 add-slide 才暴露，最终闸门是截图目检）
2. ✅ 回读 +xml-get → 页数正确、保存 revision_id
3. ✅ 截图 → 目检无空白/溢出（正常 40-90KB，纯色页可能更小，勿只看文件大小）
4. ✅ 写操作带 revision（乐观锁）：--revision-id 用回读值；冲突时重新回读合并，勿直接 -1
5. ✅ 无 fontSize=1（最小 6）/ border 小数（必须整数）/ 非法颜色格式
6. ✅ 文本不溢出（无孤字换行），替换内容后重新 lint（不是只 lint 原模板）

排障手册

已知坑（本库实战记录，2026-08）

1. <line> 元素 schema 合法，但本套模板在批量渲染时曾致空白页（历史 bug）→ 模板统一用 rect 细条，规避风险
2. border width 必须是整数（nonNegativeInteger）→ 1.5 非法，用 1 或 2
3. fontSize 最小 6（positiveInteger minInclusive=6）→ 1pt 隐形文本非法
4. 表格 height 必须等于行高合计（如 44+68+68+68=248）→ 否则服务端归一化产生漂移
5. img 占位符相对当前目录（不是 @file 目录）→ 运行前确保当前目录有图片
6. execute_code 不能跑 lark-cli → 必须 terminal
7. 更新后必须回读验证（可能返回 ok 但实际失败）
8. 颜色格式必须 rgba(r, g, b, a) 无多余引号/括号——曾出现 (3, 'rgba(...)') 污染
9. 整页替换会丢用户手动修改（2026-08-20 实战教训）：用模板/本地 XML +update-slide 整体替换页面时，会覆盖用户在飞书上手动改的文字（含 <span> 编辑痕迹）、手加的图片（如封面主视觉图）、重排的页面顺序——更新前必须先回读对比（见「更新前必做」），已误覆盖用 +history-list + +history-revert 恢复

Logo 使用

• Logo 文件：assets/cherry-logo.png（1024×1024，透明 PNG，官方提供）
• 形态：珊瑚红圆角方形底（#FF5757）+ 白色抽象樱桃/对勾图形，无文字
• 版本：红白双色（自带完整彩色底板，不是单色版）
• 适用背景：浅色 #FAFAF9 ✓ 深色 #111111 ✓（浅色更清爽）
• 位置：方标（1024×1024 等比）。页眉 28×28、封底 64×64；禁止拉成 180×44 横版（会变形）；按需放大时保持正方形等比
• 搭配文字：如需表达公司名，图标右侧补充 "Cherry Studio" 字样（当前图片无文字）
• 规则：
  • 保留透明四角，勿转成带黑底的 JPG
  • 不裁掉圆角外围透明区域
  • 不外加白色方框、不拉伸、不旋转、不加阴影、不改颜色
  • 避免尺寸过小（内部负空间细节会糊）
• 深色页：红底白图形在深色背景对比更强，可直接用

最终执行原则

1. 先做黑白层级，再加彩色识别
2. 每页只讲一个结论，每卡只讲一个概念
3. 大标题、大留白、真实产品截图是主要视觉资产
4. 黑色只用于最高优先级动作，珊瑚红只用于品牌识别
5. 多元色以线、点、图标底和细描边出现
6. 边框优先于阴影，留白优先于边框