@lark-apaas/coding-steering 0.1.18-dev.4aa21f4 → 0.1.18-dev.4e64c13

package/steering/design-html/skills/{visual-exposure → visual-report}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: visual-exposure
+name: visual-report
 description: 用于制作可视化报告、专题视觉页、信息图、视觉长图、概念可视化、产品能力曝光、方案亮点展示等内容型 HTML 视觉作品。适合用户想把材料、数据或观点组织成可阅读、可展示、可传播的视觉化表达，但不希望做成 PPT、传统 dashboard 或纯 ECharts 图表的场景。触发词：可视化报告, 视觉报告, 可视化曝光, 视觉化曝光, 信息图, 长图, infographic, 视觉表达, 概念可视化, 亮点展示, 能力曝光
 metadata:
   display-names:
@@ -45,6 +45,23 @@ metadata:
 
 不要为了“丰富”而乱放装饰。变化应该来自内容关系和阅读任务，而不是从组件清单里凑满页面。
 
+## 移动端适配
+
+可视化报告的产物（长页报告、专题页、信息图）经常在手机上被打开和转发。桌面端的多列版式、满版图文和精细间距到了 390px 宽度上会挤碎。写完桌面布局后，必须为窄屏补充响应式处理：
+
+**页面基础**：HTML 必须包含 `<meta name="viewport" content="width=device-width, initial-scale=1">`。
+
+**版式折叠**：
+
+- **多列章节**（并排图文、对比矩阵、左右证据栏）：移动端折叠为单列堆叠。用 `auto-fit + minmax(320px, 1fr)` 自动折叠，或 `@media (max-width: 768px)` 显式切换。
+- **满版主视觉 / 封面**：桌面端的固定高度大图在移动端改为 `aspect-ratio` 或 `min-height` + `max-height` 约束，避免图片撑满整屏看不到内容。
+- **数字/指标区**：横排的 KPI 或关键数字在移动端折叠为 2 列或纵向排列，每个数字块至少 160px 宽。
+- **图表**：图表容器的窄屏处理由 charts skill 的「窄屏适配」规则覆盖。
+- **宽表格 / 时间线 / 矩阵**：加 `overflow-x: auto` 容器让内容可横向滚动，不要压缩到不可读。
+- **大字标题**：桌面端 48px+ 的展示字体在移动端用 `clamp()` 或 `@media` 缩到合理范围（如 `clamp(24px, 6vw, 48px)`），避免单词撑出视口。
+
+**字号底线**：移动端正文不低于 14px，标注 / 图注不低于 12px。
+
 ## 视觉原则
 
 - 优先清楚，其次好看。读者应该先理解结构，再感受到风格。
@@ -54,6 +71,7 @@ metadata:
 - 风格跟随内容、受众和品牌：可以正式、温和、技术、编辑化、品牌化或实验感，但不要从某个样例场景继承固定颜色、固定目录或固定组件。
 - 每份报告应有一个可解释的签名元素。签名元素要从用户主题、材料质感和阅读任务中生成，而不是复用固定手法；它可以是任何能组织内容、建立记忆点并保持一致性的视觉规则。
 - 真实素材优先：用户给的截图、logo、图片、图标、数据片段要优先使用。没有素材时，用清楚的占位结构和可替换文案。
+- 数据忠实度：页面中展示的每个数值必须可溯源到用户提供的数据或可验证的计算过程。源数据不含的派生指标（同比/环比、完成率等缺少基准数据的）不编造——用"—"占位或省略。确需补充示例数据时，必须用视觉标记（虚线边框、"示例数据"标签、灰色斜体）明确区分。
 - 允许少量动效，但只用于进入、强调或引导阅读，不做干扰理解的持续动画。
 - 可以包含数字、图表和表格，但它们服务于报告叙事；不要为了“可视化”而把所有内容都做成图。
 - 深色区域可以用于封面、结论、行动区或整篇报告的主视觉；只要它服务主题气质和阅读体验，而不是作为无依据的装饰。
@@ -77,4 +95,8 @@ metadata:
 - 文字密度可读，没有小字堆叠。
 - 图标、线条、颜色和卡片样式属于同一套视觉语言。
 - 明暗选择能解释为什么适合这个主题；无论浅色还是暗色，都保证长文、图表和表格可读。
-- 事实性内容没有编造；不确定内容用中性描述或占位说明。
+- 事实性内容没有编造；不确定内容用中性描述或占位说明。
+- 页面中每个数值可溯源到用户提供的数据；缺少基准数据的派生指标（同比/环比/完成率等）没有编造数值，而是用"—"占位或省略。
+- HTML 包含 `<meta name="viewport" content="width=device-width, initial-scale=1">`。
+- 多列版式在 390px 视口下折叠为单列且无横向滚动；宽表格 / 矩阵有 `overflow-x: auto` 包裹。
+- 移动端字号达到底线（正文 ≥14px、图注 ≥12px），大标题没有撑出视口。

package/steering/nestjs-react-fullstack/skills_common/trigger-guide/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: trigger-guide
+description: 自动化任务触发器代码开发指南，支持 cron 定时触发器、record_change 数据变更触发器和 webhook 触发器，包含 @Automation/@BindTrigger 装饰器用法、handler 入参解析和 Crontab 表达式规范。Use when 需要：(1) 为已创建的自动化任务/定时任务编写业务 handler，(2) 编写 automation 代码绑定触发器，或其他自动化任务相关开发
+steering: true
+steering-topic: trigger_guide
+match-template-name: nestjs-react-fullstack
+---
+
+## 自动化任务配置与代码编写指引
+
+### 自动化任务配置
+
+1. 新建自动化任务触发器时无需 enable（激活），将任务创建好然后开发完代码即可。触发器随后交由用户主动操作、要求开始。
+
+### 目录结构
+
+```text
+server
+└── modules
+    └── xxx
+        ├── xxx.automation.ts
+        ├── xxx.module.ts // 必须在 module 中注册自动化任务类，并且在 app.module.ts 中引用并注册该 module，否则代码将不会生效。
+        └── 其他文件（如有的话）
+```
+
+文件命名规则：{模块名}.automation.ts
+
+注意：
+
+1. 每个模块只应该有一个存放自动化任务逻辑的文件，业务逻辑需要聚合到该文件中。
+2. 如果该模块只有对应的自动化任务，无需编写 Controller
+
+### 触发器类型
+
+触发器类型（`triggerType`）有三种：
+
+- `record_change`：记录变更触发器，**有入参**
+- `cron`：定时触发器，**无入参**
+- `webhook`：Webhook 触发器，**有入参**
+
+各触发器 handler 的入参类型定义（`TaskHandlerArgs`、`DataChangeEventInput`、`WebhookEvent`）见 [触发器入参类型与代码示例](references/trigger-lifecycle.md)。
+
+### 指定值限制
+
+1. Webhook 触发器不可以设置指定值，并且告知用户。
+
+### 代码绑定
+
+你需要根据触发器创建后确定的自动化任务名字（应用内唯一），编写并绑定到对应的方法上：`@BindTrigger('<任务名字>')` 中的名字必须与创建触发器时确定的名字逐字相同，不能用 trigger ID 或方法名代替。`@Automation()` 标记的类需注册为对应 `<module>.module.ts` 的 provider，且该 module 必须被 `server/app.module.ts` 直接或传递 import，否则装饰器不会生效。完整代码示例见 [触发器入参类型与代码示例](references/trigger-lifecycle.md)。
+
+### 任务代码实现约束
+
+1. 执行自动化任务时无法获取用户信息。依赖用户信息的场景，实现路径如下：
+   - 需要查询数据库中的特定数据，给用户发消息：数据库中需要存储用户 id，使用从数据库中查询到的用户 id 进行后续操作
+   - 需要调用飞书能力给用户发消息：飞书能力不应该接受用户信息作为参数，而是应该在飞书能力配置里要求用户自己预先指定
+
+2. 入参解析规范（仅 record_change 和 webhook 触发器）：
+   - 有入参的触发器方法签名为 `async methodName(event: TaskHandlerArgs)`，`cron` 触发器无入参
+   - `content.input` 是 JSON 字符串，先用 `typeof input === 'string'` 检查类型，再用 `JSON.parse()` 解析，需添加 try-catch 错误处理
+   - `record_change`：根据操作类型获取数据：INSERT/UPDATE 使用 `after` 字段，DELETE 使用 `before` 字段
+   - `webhook`：从 `method`、`path`、`query`、`headers`、`body` 中按需取用；`body` 本身也是 JSON 字符串，需要时再次 `JSON.parse()` 解析；`query` 和 `headers` 的值均为 `string[]`
+
+### 技术实现路径参考
+
+以下常见需求的推荐实现路径，帮助你在平台能力限制下找到合理的技术方案；完整代码见 [触发器入参类型与代码示例](references/trigger-lifecycle.md)。
+
+- **场景一：管理页面控制定时任务启停** —— 平台侧不支持通过 API 动态启停触发器；定时触发器始终保持开启，在任务执行时查询数据库中的开关状态决定是否执行。
+- **场景二：定时任务通知特定用户** —— 任务执行时无法获取用户上下文；在数据库预存目标用户 ID，执行时查询再调用飞书插件发送。
+- **场景三：记录变更触发器防抖/去重** —— 利用数据库记录最近一次处理时间戳，对比 event 时间戳进行去重。
+- **场景四：自定义定时任务触发时间** —— cron 创建后不可动态改；平台设固定高频定时器（如每 30 分钟），执行时读数据库配置判断是否命中。
+
+## Crontab 表达式规范
+
+### 基本结构
+
+Crontab 表达式由 5 个字段组成：`<minute> <hour> <day> <month> <week>`
+
+### 字段说明
+
+1. **minute（分钟）**：0-59 的整数
+2. **hour（小时）**：0-23 的整数
+3. **day（日期）**：1-31 的整数，或大写字母 `L` 表示月份的最后一天
+4. **month（月份）**：1-12 的整数
+5. **week（星期）**：0-6 的整数，其中 0 表示星期天
+
+### 特殊字符
+
+- **星号 `*`**：表示所有可能的值（每）
+  - 例：`* * * * *` 表示每分钟
+- **逗号 `,`**：表示列表范围
+  - 例：`1,2,3 * * * *` 表示每小时的第 1、2、3 分钟
+- **中杠 `-`**：表示数值范围
+  - 例：`1-10 * * * *` 表示每小时的第 1 到 10 分钟
+- **正斜线 `/`**：表示间隔频率
+  - 例：`0 10-18/2 * * *` 表示每天 10 点到 18 点，每隔 2 小时执行
+
+## 输出要求
+
+1. 必须以 JSON 格式输出
+2. JSON 包含两个字段：
+   - `expression`：Crontab 表达式字符串
+   - `explanation`：中文说明，简要描述执行时间
+3. 如果用户描述不清晰，请询问具体细节
+
+## 示例
+
+**用户输入**：每天早上 8 点执行
+
+**输出**：
+
+```json
+{
+  "expression": "0 8 * * *",
+  "explanation": "每天早上 8:00 执行"
+}
+```
+
+**用户输入**：每周一到周五的上午 9 点和下午 6 点执行
+
+**输出**：
+
+```json
+{
+  "expression": "0 9,18 * * 1-5",
+  "explanation": "每周一至周五的 9:00 和 18:00 执行"
+}
+```
+
+**用户输入**：每隔 30 分钟执行一次
+
+**输出**：
+
+```json
+{
+  "expression": "*/30 * * * *",
+  "explanation": "每隔 30 分钟执行一次"
+}
+```
+
+**用户输入**：每月最后一天的晚上 11 点执行
+
+**输出**：
+
+```json
+{
+  "expression": "0 23 L * *",
+  "explanation": "每月最后一天的 23:00 执行"
+}
+```
+
+**用户输入**：每个工作日的每小时第 15 和 45 分钟执行
+
+**输出**：
+
+```json
+{
+  "expression": "15,45 * * * 1-5",
+  "explanation": "每周一至周五，每小时的第 15 和 45 分钟执行"
+}
+```
+
+**用户输入**：每天上午 10 点到下午 6 点，每隔 2 小时执行
+
+**输出**：
+
+```json
+{
+  "expression": "0 10-18/2 * * *",
+  "explanation": "每天 10:00、12:00、14:00、16:00、18:00 执行"
+}
+```
+
+## 注意事项
+
+- 星期字段：0 和 7 都可以表示星期天（但本规范使用 0）
+- 时间采用 24 小时制
+- 月份和星期都从较小的数字开始计数
+- 确保生成的表达式符合实际日历逻辑
+- 由于技术限制，最小间隔为 30 分钟，如用户要求有误请直接拒绝用户并给出原因
+- 输出必须是有效的 JSON 格式

package/steering/nestjs-react-fullstack/{skills/trigger-guide/SKILL.md → skills_common/trigger-guide/references/trigger-lifecycle.md}

@@ -1,36 +1,8 @@
----
-name: trigger-guide
-description: 自动化任务触发器配置与代码开发指南，支持 cron 定时触发器、record_change 数据变更触发器和 webhook 触发器，包含 @Automation/@BindTrigger 装饰器用法和 Crontab 表达式规范。Use when 需要：(1) 创建或配置自动化任务/定时任务，(2) 编写 automation 代码绑定触发器，或其他自动化任务相关开发
-steering: true
-steering-topic: trigger_guide
-match-template-name: nestjs-react-fullstack
----
+# 触发器入参类型与代码示例
 
-## 自动化任务配置与代码编写指引
+本 reference 承载 nestjs-react-fullstack 触发器 handler 的入参类型定义、完整代码示例与常见实现场景。先读主 [trigger-guide](../SKILL.md) 了解目录结构、绑定约束与配置要求。
 
-### 自动化任务配置
-
-1. 新建自动化任务触发器时无需 enable（激活），将任务创建好然后开发完代码即可。触发器随后交由用户主动操作、要求开始。
-
-### 目录结构
-
-```text
-server
-└── modules
-    └── xxx
-        ├── xxx.automation.ts
-        ├── xxx.module.ts // 必须在 module 中注册自动化任务类，并且在 app.module.ts 中引用并注册该 module，否则代码将不会生效。
-        └── 其他文件（如有的话）
-```
-
-文件命名规则：{模块名}.automation.ts
-
-注意：
-
-1. 每个模块只应该有一个存放自动化任务逻辑的文件，业务逻辑需要聚合到该文件中。
-2. 如果该模块只有对应的自动化任务，无需编写 Controller
-
-### 触发器类型与入参
+## 触发器类型与入参
 
 触发器类型（`triggerType`）有三种：
 
@@ -85,12 +57,11 @@ interface WebhookEvent {
 }
 ```
 
-### 指定值限制
-1. Webhook 触发器不可以设置指定值，并且告知用户。
+`DataChangeEventInput.type` 只定义 `INSERT`、`UPDATE`、`DELETE`，不包含 `UPSERT`。
 
-### 代码示例
+## 代码示例
 
-你需要根据 `automation_trigger_manager` 工具返回的自动化任务名字，编写并绑定到对应的方法上。具体代码示例如下：
+根据触发器创建后确定的任务名字（应用内唯一），编写并绑定到对应的方法上。使用模板已有的 `@lark-apaas/fullstack-nestjs-core` 聚合入口导入 `Automation` / `BindTrigger`，不要求项目再感知底层 trigger 包。具体代码示例如下：
 
 ```typescript
 // 文件名：demo.automation.ts
@@ -184,23 +155,11 @@ export class DemoAutomationTasksService {
 }
 ```
 
-### 任务代码实现约束
-
-1. 执行自动化任务时无法获取用户信息。依赖用户信息的场景，实现路径如下：
-   - 需要查询数据库中的特定数据，给用户发消息：数据库中需要存储用户 id，使用从数据库中查询到的用户 id 进行后续操作
-   - 需要调用飞书能力给用户发消息：飞书能力不应该接受用户信息作为参数，而是应该在飞书能力配置里要求用户自己预先指定
-
-2. 入参解析规范（仅 record_change 和 webhook 触发器）：
-   - 有入参的触发器方法签名为 `async methodName(event: TaskHandlerArgs)`，`cron` 触发器无入参
-   - `content.input` 是 JSON 字符串，先用 `typeof input === 'string'` 检查类型，再用 `JSON.parse()` 解析，需添加 try-catch 错误处理
-   - `record_change`：根据操作类型获取数据：INSERT/UPDATE 使用 `after` 字段，DELETE 使用 `before` 字段
-   - `webhook`：从 `method`、`path`、`query`、`headers`、`body` 中按需取用；`body` 本身也是 JSON 字符串，需要时再次 `JSON.parse()` 解析；`query` 和 `headers` 的值均为 `string[]`
-
-### 技术实现路径参考
+## 技术实现路径参考
 
 以下是一些常见需求的推荐实现路径，帮助你在平台能力限制下找到合理的技术方案。
 
-#### 场景一：用户需要管理页面控制定时任务的启停
+### 场景一：用户需要管理页面控制定时任务的启停
 
 平台侧不支持通过 API 动态启停触发器。推荐方案：**平台定时触发器始终保持开启，在任务执行时查询数据库中的开关状态，决定是否真正执行业务逻辑。**
 
@@ -233,7 +192,7 @@ export class ReportAutomationService {
 }
 ```
 
-#### 场景二：定时任务需要将结果通知给特定用户
+### 场景二：定时任务需要将结果通知给特定用户
 
 自动化任务执行时无法获取当前用户上下文。推荐方案：**在数据库中预存需要通知的用户 ID，任务执行时从数据库查询目标用户，再调用飞书插件发送通知。**
 
@@ -267,7 +226,7 @@ export class NotifyAutomationService {
 }
 ```
 
-#### 场景三：记录变更触发器需要做防抖/去重
+### 场景三：记录变更触发器需要做防抖/去重
 
 高频数据变更场景下，同一条记录可能短时间内触发多次。推荐方案：**利用数据库记录最近一次处理时间戳，对比 event 时间戳进行去重。**
 
@@ -294,7 +253,7 @@ async handleOrderChange(event: TaskHandlerArgs) {
 }
 ```
 
-#### 场景四：用户需要自定义定时任务的触发时间
+### 场景四：用户需要自定义定时任务的触发时间
 
 平台侧的 cron 表达式在触发器创建后无法由用户动态修改。推荐方案：**平台设置一个固定的高频定时器（如每 30 分钟执行一次），在任务执行时从数据库读取用户配置的触发时间，判断当前是否命中再决定是否执行。**
 
@@ -340,113 +299,3 @@ export class ScheduleAutomationService {
 ```
 
 > 注意：由于平台最小调度间隔为 30 分钟，用户可配置的时间精度也应限制为 30 分钟的整数倍（如 `09:00`、`09:30`），前端做好校验提示。
-
-## Crontab 表达式规范
-
-### 基本结构
-
-Crontab 表达式由 5 个字段组成：`<minute> <hour> <day> <month> <week>`
-
-### 字段说明
-
-1. **minute（分钟）**：0-59 的整数
-2. **hour（小时）**：0-23 的整数
-3. **day（日期）**：1-31 的整数，或大写字母 `L` 表示月份的最后一天
-4. **month（月份）**：1-12 的整数
-5. **week（星期）**：0-6 的整数，其中 0 表示星期天
-
-### 特殊字符
-
-- **星号 `*`**：表示所有可能的值（每）
-  - 例：`* * * * *` 表示每分钟
-- **逗号 `,`**：表示列表范围
-  - 例：`1,2,3 * * * *` 表示每小时的第 1、2、3 分钟
-- **中杠 `-`**：表示数值范围
-  - 例：`1-10 * * * *` 表示每小时的第 1 到 10 分钟
-- **正斜线 `/`**：表示间隔频率
-  - 例：`0 10-18/2 * * *` 表示每天 10 点到 18 点，每隔 2 小时执行
-
-## 输出要求
-
-1. 必须以 JSON 格式输出
-2. JSON 包含两个字段：
-   - `expression`：Crontab 表达式字符串
-   - `explanation`：中文说明，简要描述执行时间
-3. 如果用户描述不清晰，请询问具体细节
-
-## 示例
-
-**用户输入**：每天早上 8 点执行
-
-**输出**：
-
-```json
-{
-  "expression": "0 8 * * *",
-  "explanation": "每天早上 8:00 执行"
-}
-```
-
-**用户输入**：每周一到周五的上午 9 点和下午 6 点执行
-
-**输出**：
-
-```json
-{
-  "expression": "0 9,18 * * 1-5",
-  "explanation": "每周一至周五的 9:00 和 18:00 执行"
-}
-```
-
-**用户输入**：每隔 30 分钟执行一次
-
-**输出**：
-
-```json
-{
-  "expression": "*/30 * * * *",
-  "explanation": "每隔 30 分钟执行一次"
-}
-```
-
-**用户输入**：每月最后一天的晚上 11 点执行
-
-**输出**：
-
-```json
-{
-  "expression": "0 23 L * *",
-  "explanation": "每月最后一天的 23:00 执行"
-}
-```
-
-**用户输入**：每个工作日的每小时第 15 和 45 分钟执行
-
-**输出**：
-
-```json
-{
-  "expression": "15,45 * * * 1-5",
-  "explanation": "每周一至周五，每小时的第 15 和 45 分钟执行"
-}
-```
-
-**用户输入**：每天上午 10 点到下午 6 点，每隔 2 小时执行
-
-**输出**：
-
-```json
-{
-  "expression": "0 10-18/2 * * *",
-  "explanation": "每天 10:00、12:00、14:00、16:00、18:00 执行"
-}
-```
-
-## 注意事项
-
-- 星期字段：0 和 7 都可以表示星期天（但本规范使用 0）
-- 时间采用 24 小时制
-- 月份和星期都从较小的数字开始计数
-- 确保生成的表达式符合实际日历逻辑
-- 由于技术限制，最小间隔为 30 分钟，如用户要求有误请直接拒绝用户并给出原因
-- 输出必须是有效的 JSON 格式

package/steering/design-html/skills/make-a-deck/SKILL.md

@@ -1,193 +0,0 @@
----
-name: make-a-deck
-description: 当用户要求制作演示文稿、PPT、PPTX、pitch deck、slides、keynote 或路演材料时使用。产出适合现场演示的 16:9 HTML deck。
-metadata:
-  display-names:
-    zh-CN: 幻灯片制作
-    en-US: Slide Deck
----
-
-# Make a deck
-
-你是一名幻灯片设计师，为演讲者制作现场演示用的幻灯片。产物是一个 HTML 单页 deck：用 `<deck-stage>` 包住一组 1920×1080 的 `<section>`，一个 section 就是一页。
-
-这是用于演示的幻灯片，不是在做一个网页，也不是把报告原文分成几屏。最重要的事情是：内容清晰、叙事流畅。
-
-## 动手前先定方向
-
-先看用户给的主题、受众、场合、品牌和附件。能从这些信息判断风格，就直接判断；确实判断不了时，用提问工具主动问清楚。
-
-先想清楚：这是谁在什么场合讲、观众需要记住什么、哪些页是重点。用一两句话写进 `scratchpad.txt`，后面所有页面都按这个口径做。
-
-视觉方向先调用 frontend-design skill 搭框架，再从主题、受众和场景里提炼几个视觉关键词，用来决定配色、字体、图片类型和页面节奏。它和本 skill 冲突时，以本 skill 为准。
-
-## 第一步：规划幻灯片大纲
-
-必须先写 `scratchpad.txt`。这是本 skill 明确要求创建的工作文件，属于显式创建，不受「不主动创建文档文件」限制的约束。每页至少写清四件事：
-
-1. **标题。** 全篇统一用主题式标题，或者统一用直接给结论的标题。只看标题，也应该能跟上整个故事。
-2. **这页讲什么。** 一页只处理一个问题、一组关系或一个动作。如果这句话里出现“以及、同时、另外、并且”，通常就该拆页。
-3. **用什么形式。** 例如大数字、图表、表格、时间线、引用、图文并排或多栏对比。形式要跟内容的关系走，不要每页都铺成卡片。
-4. **装多少。** 写清条目数、表格行数、卡片数，并判断“放得下”还是“要拆页”。
-
-### 基于用户输入设计演讲内容
-
-不要把来源里的长段落原样塞进卡片。先把它改成适合台上讲的内容：数字、关键词、短标签、步骤、对比项或者一句话结论。
-
-一页最多放一个高密度结构。长表格、复杂时间线、详细列表、密集图表和大段回答，不能在同一页里两两叠加。
-
-用户给了页数范围时，优先用范围的上限。装不下就加页，不要为了守住较少的页数而挤内容。
-
-### 基于设计内容估算高度
-
-写 HTML 前，先做一次保守的高度预算，只拦住明显塞不下的页面。
-
-- 画布高 1080px。普通内容页把标题、上下边距和页码扣掉后，按 **700px 安全区** 来规划，最多不要超过 **820px**。
-- 内容块高度粗算为：`文字行数 × 行高 + 上下 padding + 和其他块之间的 gap`。
-- 表格、时间线、图表等结构，再留 15%–20% 余量。
-- 不用追求像素级准确。粗算已经接近 820px，就按放不下处理。
-
-这些上限用来快速拦风险：
-
-- 正文预计超过 12 行：优先拆页。
-- 表格最多 6 行；确有必要可以到 8 行，但要减少列和说明文字。
-- 时间线或步骤最多 4 个。
-- 一栏最多竖着放 2 张带多行说明的卡片。
-- 2×2 卡片阵里，每张最多放图标、标题和 2 行说明。
-- 并列项超过 6 个：分组或拆页。
-- 同时出现两个高密度结构：必须拆页。
-
-装不下时按这个顺序处理：**先删解释和重复内容，再换成更省空间的表达，最后拆页或加页。** 不要靠缩字号、压行距、缩 padding 或 `overflow: hidden` 把问题藏起来。
-
-章节页、引用页和大数字页本来就可以很疏，不需要为了填满画面硬加内容。
-
-## 第二步：生成幻灯片框架
-
-### 使用 deck-stage
-
-调用 `copy_starter_component`，传 `kind: "deck-stage.js"`，然后这样写：
-
-```html
-<deck-stage width="1920" height="1080">
-  <section data-label="封面">...</section>
-</deck-stage>
-<script src="deck-stage.js"></script>
-```
-
-不要手写 stage 组件。它已经处理了缩放、翻页、校验标记和打印，用 `<script src="deck-stage.js"></script>` 加载即可；它是 vanilla JS，不是 JSX。
-
-组件会给每个 section 做绝对定位，所以不要在 `<section>` 上再写 `position`、`inset`、`width` 或 `height`。需要导出 PPTX 时，给 `gen_pptx` 传 `resetTransformSelector: "deck-stage"`；需要按原始尺寸截图时，使用组件的 `noscale` 属性。
-
-### 先定字号和间距
-
-写页面前，先把字号、行高、页边距和间距放进 CSS 变量：
-
-```css
-:root {
-  --type-display: 120px;
-  --type-title: 64px;
-  --type-subtitle: 44px;
-  --type-body: 34px;
-  --type-small: 28px;
-  --leading-title: 1.15;
-  --leading-body: 1.4;
-  --measure-body: 40em;
-  --pad-top: 100px;
-  --pad-bottom: 80px;
-  --pad-x: 100px;
-  --gap-title: 52px;
-  --gap-item: 28px;
-}
-```
-
-这些是推荐变量，可以按版式小幅调整，但关键文字不能小于 24px，不能为了塞内容临时造一套小字号。页码、来源等辅助信息可以稍小，但不能承载关键结论。图表的轴标签、图例和数据标注也要显式设大，别用图表库的默认小字。
-
-大段文字用 `max-width: var(--measure-body)` 限宽。多出来的横向空间用双栏、图文并排或对比关系来组织，不要把一行文字拉满整页。
-
-### 正文用静态 HTML 实现
-
-静态 HTML 始终优先，因为用户可以直接编辑。文字、布局、背景和图片都写成 HTML + CSS，不要用 React、数组 `map` 或运行时脚本生成正文。只有确实需要交互的图表或 demo 才使用脚本。
-
-每段文字放在自己的元素里；重复结构也逐项写出来，方便用户单独修改。
-
-## 第三步：生成幻灯片内容
-
-### 页面要有重点
-
-每一页都要同时顾到版式和文案，不能只把其中一项做好。
-
-每页都要说得出第一眼看哪里，可以是一张图、一个大数字、一句大字或一项刻意加重的对比。所有元素一样大、一样重，就没有重点。
-
-普通内容页不要把所有东西挤在上半页，也不要用拉高空卡片来填下半页。可以放大真正的看点、换成图表或图文关系，也可以和邻页重新分配内容。
-
-但章节页、引用页和大数字页可以主动留出大片空白。空白是版式的一部分，不等于页面没做完。
-
-页码、眉标和章节页样式要统一；页面骨架要随着内容变化。数据用图表，对比用并列关系，步骤用流程，金句用引用页。丰富来自关系和版式，不来自堆更多文字。
-
-### 页面不能太空
-
-避免溢出的同时，也要保证普通内容页有足够的信息密度。内容只缩在页面一小块、其余地方大面积空着，通常说明内容或版式还没组织好。
-
-页面太空时，按这个顺序处理：**先放大真正的主视觉，再把短文字改成图文、对比、流程或数据展示，然后补充与本页结论直接相关的信息；内容仍撑不起一页，就和相邻页面合并。**
-
-不要靠拉高空卡片、统一放大所有字号、添加无意义图标或堆装饰来填空。章节页、引用页、大数字页和满版图片页可以主动留白，但留白必须在突出重点或帮助构图。
-
-### 封面要有设计感
-
-封面不是把标题、副标题和小图标居中摆好就结束。先选一个明确的主视觉，可以是图片、图形、超大文字、数字或有主题含义的留白构图，再围绕它安排标题和辅助信息。标题要一眼可见，作者、日期等信息退到次要层级。构图可以偏置、裁切、叠压或利用尺度反差，但不要同时堆很多装饰。封面的视觉语言要和内页一致，同时比普通内容页更大胆，让人第一眼就能感受到主题和气质。
-
-### 样式设计规则
-
-- **先清楚，再好看。** 读者应该先看懂结构，再感受到风格。
-- **明暗主题跟着内容选。** 根据品牌、素材、受众和演示环境选择浅色、深色、中性或局部深色。选完要保证对比度和信息层级。
-- **默认做平面设计。** 用有意义的分隔线、浅底色、色块、表格斑马纹、编号和标签建立层级。
-- **字号与单位。** 标题至少 48px。用户说具体字号时，默认指 PowerPoint/Keynote 的磅：`px = pt × 1.333`，所以 36pt 约等于 48px。
-- **中文字体。** `font-family` 要写拉丁字体、明确的 CJK 字体和通用兜底。衬线可用 Noto Serif SC / 思源宋体，无衬线可用 Noto Sans SC / 思源黑体、MiSans 或 HarmonyOS Sans。中文不用假斜体；强调靠字重、颜色或引用线。正文和标题要拉开字重。
-- **素材来源。** 除非用户要求，不用 emoji。图标跟随 design system 或品牌；图片使用用户提供的素材或图片工具生成的素材。
-- **图片呈现。** 先看图片，再决定怎么放。满版氛围图可以裁切填满；截图必须完整显示，尽量不在上面压内容；透明图和完整显示的图片要放在有对比度的背景上。需要在图片上放文字时，跟随品牌已有做法，选择保护渐变、模糊或必要的文字底板。
-- **不 iframe 外站。** deck 是自包含单页，**绝不**用 `<iframe>`（含 `<embed>`/`<object>`）嵌入外站网页或在线视频——外站普遍以 X-Frame-Options / CSP 拒绝被嵌入，渲染出来就是一块灰色裂框，PPTX 导出与打印下同样是空白。需要引用视频或网页时，做成 deck 视觉系统内的静态呈现：封面图或截图叠播放键，配标题、来源、时长等文字元信息，现场演示由演讲者另开窗口播放。
-- **图表优先静态实现。** 柱状图可以用 CSS，折线和扇形可以用内联 SVG；只有悬停、筛选或实时数据等真交互才用脚本。趋势、占比、对比和分布尽量画出来，不要铺成文字。图表沿用整套 deck 的颜色和字号，数值尽量直接标在图上，删掉无用网格线和刻度。轴标签、图例和数据标注也不能小于 24px。
-- **动效服务于讲述。** 只做翻到该页时播放一次的入场或分步揭示，不做循环装饰。用 CSS 动画，并遵守两条规则：
-  - 动画挂在 `[data-deck-active]` 和 `prefers-reduced-motion: no-preference` 上；需要 JS 编排时监听 `slidechange`。
-  - 基础样式就是完整的最终状态，隐藏态只写进 `@keyframes` 的 `from`，不要在基础规则里写 `opacity: 0`。
-- 默认不用阴影、发光、玻璃拟态和装饰性渐变。渐变只用于图片上的文字保护，或数据的连续色带。
-- 不要默认使用深色底、紫蓝渐变、发光卡片这套“科技感”。用户或品牌明确要时再用。
-- 不要把所有内容都装进“白底 + 1px 描边 + 圆角”的卡片。边框没有表达分组、状态或层级时，直接去掉。
-- 禁止“圆角卡片 + 单边彩色 border”，包括 `border-left`、`border-top` 和 `border-bottom`。颜色真有含义时，用编号、整块色底或整页色调表达。
-- 引用可以用一根直角竖线，但不要再套圆角卡片。
-- 编号、标签、分隔线只有在真的表示序号、分类或状态时才加。
-
-### 文案说人话
-
-标题的任务是告诉观众这页讲什么，不是替演讲者写金句。少用宣判腔、强行反转、故作悬念和 “It's not X. It's Y.” 这类句式，也别写 “The magic moment” 一类空泛标题。
-
-每页单独拿出来，也应该能看懂大意。
-
-## 自检：run_commit 的前置条件
-
-写完 HTML 不等于做完。调用 run_commit 之前，必须先做一次代码回读核对，并把结果写出来——核对表没有出现，就还没到提交这一步。
-
-具体做法
-
-1. 用 grep 找到每个 `<section` 的行号，挑出内容最满的两三页，加上所有含表格、时间线或卡片阵的页。
-2. read_file 回读这些页的代码，按第一步的公式逐页粗算高度。
-3. 在回复里输出核对表，每页一行：页名 / 内容组成（几行正文、几行表格、几张卡片） / 判定（通过或拆页）。有页超过 820px，先回去改，改完把这页重新核对一遍。
-
-两条纪律：
-
-- 建 todo 时，「回读核对页面高度」要单独一条，它的完成标准就是核对表已出现在回复里。没有对应的 read_file 调用和核对表就把它标成 completed，等于没做自检。
-- 截图是可选补充，不能替代代码回读；只截封面一张不算检查。
-
-核对高度之后，逐项过一遍下面的清单；重点仍是最满的两三页和所有表格、时间线、卡片阵：
-
-- 高度粗算没有超过 820px，各类高密度结构没有超过前面的上限。
-- 每页只讲一件事，没有把两个高密度结构塞在一起。
-- 关键文字不小于 24px，没有靠缩字、压间距或 `overflow: hidden` 掩盖溢出。
-- 页码、总页数和 `<section>` 数量一致。
-- 没有内容被画幅裁掉，也没有元素互相遮挡。
-- 没有无意义的描边圆角卡片、单边彩色圆角卡片、阴影、发光、玻璃拟态和装饰性渐变。
-- 封面有一个主视觉，不是“小图标 + 居中标题 + 居中副标题”的固定三件套。
-- 页码和眉标统一；相邻页面的骨架有变化，但变化跟内容有关。
-- 每页都看得出重点；疏页面是有意留白，不是忘了安排内容。
-- 普通内容页没有缩在一个角落或只占上半页；大面积留白能说清它在突出什么，否则要重组版式或合并页面。
-- 动效元素在不播放动画时也是完整可见的。