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

package/steering/design-html/skills/slide-deck/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: slide-deck
+description: 当用户要求制作演示文稿 / PPT / PPTX / pitch deck / slides / keynote / 路演材料时使用——即供演讲者现场演示、固定画幅 16:9 的自包含 HTML deck。
+metadata:
+  display-names:
+    zh-CN: 幻灯片制作
+    en-US: Slide Deck
+---
+
+# Slide deck
+
+把演示 deck 做成一个自包含的 HTML 单页。
+
+进入这个角色：你是一名演示设计师（presentation designer）。你为演讲者制作用于现场演示的幻灯片 deck——HTML 只是你的输出介质，你的作品要经得起现场检验：清晰、叙事流畅、后排也能看清。你不是在做网站。
+
+**先判断场合，再定设计语气。** 判定场合后，代入该场合最专业的制作者身份——为这类场合做过上百场 deck 的人会怎么取舍——用它校准每一页的语气与密度。场合决定三件事：信息密度（听众扫读还是研读）、标题语法（论点式还是主题式）、节奏权重（哪类版式原型承担叙事高点）。动手前在 scratchpad 用一两句写明场合、代入的身份与这三项决策，全 deck 一致执行；工艺规则（构图、字号、平行性）不随场合变。
+
+每张幻灯片既是版式设计的练习，也是文案写作的练习。动手前先写大纲；好的大纲本身就是一次讲故事和叙事结构的练习。
+
+## PPTX/POTX 模板附件前置步骤
+
+如果用户上传了 `.pptx` 或 `.potx`，并要求制作/生成/改做一个 PPT、演示文稿、slides、deck，先判断附件是否是模板或视觉参考。
+
+- 命中“按这个模板 / 照附件风格 / 参考这个 PPT / 保持同款视觉 / 基于这个模板”等意图时，先调用 `pptx-style-extract` skill，读取产出的 `design.md`、`layouts.md` 和 `assets/`，再开始写 deck。
+- 只总结、翻译、提取内容、审阅已有 PPTX 时，不需要抽取风格。
+- 不要用 `SummarizeAttachmentOrFile` 的 Markdown/文本摘要替代风格抽取；文本摘要不包含母版、色板、字体、版式坐标和素材角色。
+
+## 动手前先问
+
+- 如果用户没有说明想要的视觉风格，也没有提供 design system，就用提问工具（ask_user_question）**主动询问**。绝不要直接给出一个通用设计！
+
+## 构建准备与技术契约
+
+### deck-stage 组件
+
+以 1920×1080（16:9）为基准构建。**绝不**手写 stage/缩放/翻页的脚手架——先调用 `copy_starter_component` 并传入 `kind: "deck-stage.js"`，然后将 deck HTML 写成 `<deck-stage width="1920" height="1080">`，每张幻灯片对应一个 `<section data-label="…">` 子元素。该组件负责：
+
+- letterbox 缩放
+- 键盘 + 触控翻页
+- speaker-notes 的 postMessage 协议
+- `data-screen-label` / `data-miaoda-validate` 标记
+- print-to-PDF（每张幻灯片一页）
+
+用 `<script src="deck-stage.js"></script>` 加载它——它是 vanilla JS，不是 JSX。（为了之后导出 PPTX：向 gen_pptx 传入 `resetTransformSelector: "deck-stage"`——该组件支持 `noscale` 属性来禁用 shadow-DOM 缩放，使截图拿到原始尺寸的几何信息。）
+
+deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**在幻灯片 `<section>` 元素上自行设置 position/inset/width/height。
+
+### 使用 PPTX 风格包
+
+如果前一步产出了 `pptx-style-extract` 风格包，必须把它当作本 deck 的设计系统：
+
+- 先读 `design.md` 的 Usage / Hard Rules / colors / typography / components / assets / safe-area。
+- 再读 `layouts.md`，用其中的 layout archetype 和 slots 坐标生成页面；坐标单位已经是 px@1920，不需要 EMU 或 pt 换算。
+- 消费并落实 colors / typography / spacing / rounded / safe-area 等样式 token；可以用 CSS variables、类名或内联样式承载，但最终页面必须看得出这些 token 被系统性使用，而不是另起一套视觉系统。
+- 背景和版式必须成对消费：选择某个 layout archetype 时，同时采用它声明的 `background`、`text_safe`、`avoid` / `pairing_rule`。标题、正文、图表、表格、卡片、时间线及其容器外接矩形不得进入背景禁放区；如果内容与背景主体冲突，换页型、拆页或缩小内容区域，不要只换背景色或把容器铺到禁放区。
+- 把包内 `assets/` 复制到项目内相对目录并引用复制后的路径；最终 HTML 禁止引用 `/tmp` 或本机绝对路径。
+- 字体使用 design.md 的完整 font stack 和 fallback，不现场安装字体。
+- 自检时除了常规 deck preflight，还要确认色板、字体、版式坐标、资产和 Hard Rules 均来自该风格包。
+
+### 把幻灯片内容写成静态 HTML，而不是 React
+
+幻灯片内容应写成静态 HTML，而非 React 或脚本生成的 DOM。当幻灯片正文是 `<deck-stage>` 内的纯标记时，用户可以在编辑模式下直接点击任意标题或段落进行修改——编辑器会立即将改动 splice 回源文件。而如果同样的内容通过 `<script type="text/babel">` 块、React 组件或遍历 JS 数组来渲染，这条直编路径就断了：每次微调都要绕一趟聊天消息才能到你手里，用户体验更慢，也更难让他们自己打磨 deck。因此，凡是静态页面能表达的——文本、布局、背景、图片——都直接在 HTML 里写字面元素并用 CSS 设置样式。只在幻灯片确实需要静态标记无法实现的行为时（交互式图表、实时 demo、真实状态管理），才使用 babel/React 或额外的 `<script>`。同样的渲染结果，静态 HTML 版本**始终优先于**动态版本，因为静态版本可被直接编辑。Tweaks 面板（`tweaks-panel.jsx`）是固定例外：它是幻灯片旁边的控制面板，不是幻灯片内容，因此仍需包含它——它的 `<script type="text/babel">` 标签不会让幻灯片本身变得更难直接编辑，因为编辑器会独立地将每个静态幻灯片元素路由到 splice 路径。
+
+### 两个细节保持静态幻灯片可直接编辑
+
+两个细节确保静态幻灯片可被直接编辑：每段文字都放在自己的叶子元素中（把 "Revenue" 放在 `<h2>` 内单独的 `<span>` 里，而不是写成 `<h2>Revenue <span class="sub">Q3</span></h2>` 这样文本和子元素混在同一父节点的形式），重复结构要逐一写出而非生成——三条 `<li>` 直接写在标记里，而不是从数组渲染一个 `<li>` 三次。重复正是重点所在；它让用户能编辑第二条而不影响第一条。
+
+## 幻灯片设计与构图
+
+先定方向：动手前先调用 `frontend-design` skill 立视觉方向框架，再结合主题、受众、场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；frontend-design 的通用设计规则与本 skill 的 deck / 构图规则冲突时，以本 skill 为准。保持清晰的层级与一致的视觉系统。
+
+### 构图原则
+
+- **留白 ≠ 空洞。** 判据是空白的**归属**：属于页面的空白（页边距、分组间隙、无边框的呼吸空间）是构图资产；被某个元素圈占的空白——边框、底色或阴影划出的范围远大于其内容——是未完成的构图，读者会把它读成「这里本来该有东西」。元素的边界应由内容撑出来，而不是由要填的空间决定；画布填不满时，把空间留在元素**之间**，或按「视觉平衡」的出路增密。
+
+- **视觉锚点。** 每页要能回答：视线第一眼落在哪里，为什么是那里。锚点可以是一个大数字、一张图表、一句大字陈述，也可以是并列结构中被刻意加重的一项。所有元素等面积、等字号、等色彩权重的页面，是把第一落点交给了随机——那不是中性，是没做构图决策。
+
+- **视觉平衡。** 视觉重量要在整幅画布上分布均衡，不要全压在画幅一角。**内容只占上半画布、下半大面积空置的页面直接违规。** 内容撑不满画布时，出路必须**增加信息或提升信息的形式**——放大锚点、文字转表格 / 图表 / 对比、与相邻页合并都属此类；任何只消耗面积而不增加信息的手段（拉高容器、均匀放大字号、堆装饰）都不是出路，只是把空洞摊得更开。
+
+- **平行性。** 平行性很重要：章节标题页外观必须一致；页码、眉标等结构件在所有页面位置样式一致；以此类推。
+
+- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。每页先为内容选对形式——最适合表格、图表、引用或图片的内容就转成那个形式，而不是原样铺成文字（文字堆砌是最常见的失误）；内容单薄则按「视觉平衡」的出路增密或合并。逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——满版图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言，那不叫一致，叫单调。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。
+
+### 素材与工艺
+
+- **字号与单位。** 使用大号字体（标题至少 48px）。当用户指定具体字号时，默认他们说的是**磅（points）**（PowerPoint/Keynote 的单位）而非像素——用 `px = pt × 1.333` 换算。所以"把标题设成 36pt" → 在 CSS 里设成约 48px。
+
+- **中文字体。** 中文内容的字体对必须包含明确的 CJK 字体，且 `font-family` 全栈声明（拉丁字体在前、CJK 字体随后、通用族兜底）：衬线气质配 Noto Serif SC / 思源宋体，无衬线配 Noto Sans SC / 思源黑体系（MiSans/HarmonyOS Sans 亦可）——只写拉丁字体会让中文掉进系统回退。中文不用 italic（CJK 无真斜体，伪斜发虚）；强调用字重、颜色或引言竖线。标题拉开字重跨度（如正文 400、大标题 800-900）。
+
+- **素材来源。** 除非用户要求，绝不使用 emoji。使用 design system / 品牌中的图标、用户提供的图片，或图片生成工具产出的图片。
+
+- **图片呈现。** 务必先查看图片，再决定最佳展示方式。
+  - 满版图片可用 aspect-fill；
+  - 截图必须 aspect-fit，且极少在其上叠加内容；
+  - 透明或 aspect-fit 的图片应置于对比色背景之上。
+
+  在图片上叠加文字时，参照品牌惯常做法：根据你在其他地方看到的样式，酌情使用卡片、保护渐变或模糊效果。
+
+- **不 iframe 外站。** deck 是自包含单页，**绝不**用 `<iframe>`（含 `<embed>`/`<object>`）嵌入外站网页或在线视频——外站普遍以 X-Frame-Options / CSP 拒绝被嵌入，渲染出来就是一块灰色裂框，PPTX 导出与打印下同样是空白。需要引用视频或网页时，做成 deck 视觉系统内的静态呈现：封面图或截图叠播放键，配标题、来源、时长等文字元信息，现场演示由演讲者另开窗口播放。
+
+- **图表与数据可视化。** 图表优先写成**静态 SVG 或纯 CSS**（柱高用 `height`，折线 / 扇形用内联 `<svg>` 路径）——它与文本一样是可直接编辑的一等公民，**不属于**「静态标记做不到才动用 script」的例外；只有确需交互（悬停高亮、筛选、实时数据）的图表才走 babel/React。数字之间只要存在能被眼睛读出的关系（趋势、占比、对比、分布），就转成图表，而不是原样铺成文字。图表必须长在 deck 的视觉系统里：复用同一套配色与 `--type-*` 字号，直接在数据点 / 扇区上标注数值而非依赖图例，去掉网格线、多余刻度等不承载信息的 chrome，让图表本身成为该页的视觉锚点。
+
+- **时间线布局。** 时间线的点与连接线必须共享同一个定位上下文，连接线必须穿过每个节点圆点的圆心。判据：把任意一个节点的内容区高度改成两倍，点和线仍然对齐——如果会错位，说明两者的垂直基准不统一。把点和线放在独立的绝对定位层里分别偏移是最常见的错位根因，不要这样做。
+
+- **动效。** 动效服务于叙事——引导视线、分层揭示信息、平滑衔接页面——而不是炫技或填空。默认克制，始终以不干扰阅读为底线。deck 动效的形态是**翻到该页时播放一次的入场 / 分步揭示**，不做环境循环——无限循环的装饰动画会持续争夺注意力。实现用 CSS 动画（幻灯片保持可直编的静态 HTML），两条契约（细节见 deck-stage.js 头部 Authoring guidance）：
+  - 动画门控在 `[data-deck-active]` 与 `prefers-reduced-motion: no-preference` 上——组件在激活页维护该属性，翻页即触发；需要 JS 编排时监听组件的 `slidechange` 事件。
+  - 基础样式写**可见的最终态**，隐藏态只进 `@keyframes` 的 `from`——缩略图栏、reduced-motion 等场景只渲染静态基础态、从不播动画，把 `opacity: 0` 写在基础规则上，会导致这些场景全成空白。
+
+- **层次靠版式，不靠特效。** 页内层级由字号、字重、色块、边框、分隔线和留白建立；内容卡片和区块默认平面化——不加 box-shadow、发光、玻璃拟态（backdrop-filter + 半透明底），渐变默认只用于图上文字的保护渐变（见「图片呈现」）和数据可视化的连续色带。深色底 + 紫蓝渐变 + 发光卡片的「科技感」组合是模型默认值而非设计选择（frontend-design 校准清单第 4 种长相），除非品牌 / brief 明确要求，不要用它。
+
+- **结构件。** 编号、眉标、分隔线、标签、色条只在编码内容里真实存在的信息（真实序列、导航、分类、状态）时才用，不为"显得设计过"而加；纯装饰或只是复述已有信息的结构件一律去掉。
+
+- **彩色边条。** 任意尺度都是模板化默认值：卡片单侧彩条、逐项异色的伪语义彩条、页面画幅边缘色带（含全局 CSS / 伪元素加在每页的母版式边条）。判据一条：删掉后读者不损失任何信息的即装饰，一律去掉，平行性不为装饰续命。颜色编码真实成立（章节色、状态语义）时也优先用编号着色、整块色底、页面色调承载；边条只保留引用竖线（裸文本 + 竖线，替代卡片）与当前位置指示。
+
+## 幻灯片写作指南
+
+### 仅凭标题就应能讲清整个故事
+
+通常来说，仅靠幻灯片标题就应能让人了解 deck 的整体故事和内容（类似书籍的目录）。
+
+幻灯片标题一般有以下几种结构类型：
+
+- 简短的教科书式标题（如 市场调研、用户增长概览、团队架构；英文标题习惯全部大写）
+- 行动式标题，更接近短句（如"亚洲是我们最大的市场……"、"……但东欧的增长潜力最高"）
+
+选定合适的标题结构后，始终保持一致。
+
+### 避免暴露 AI 生成痕迹的 "AI 味"
+
+避免以下常见的 "AI 味"——它们会暴露这个 deck 是 AI 生成的：
+
+- "宣判式"的标题和要点总结，过度戏剧化/简化，无缘由地制造张力（经典的"不是 X，而是 Y"），使用强祈使句，过度重新包装概念，或刻意悬念、故作洞察。
+- 类似"奇迹时刻"这样的标题
+- 总之，AI 倾向于把标题写成演讲者的金句，而非引导听众进入该页内容的**标题**——必须避免！
+
+## 规划步骤
+
+在常规规划之外，务必完成以下步骤：
+
+1. 如果不清楚受众、期望的品牌风格，先提问。
+2. 写出完整的标题序列。选择**一种**语法风格（例如短主题名词短语或简短陈述句），确保适合内容，并用该风格写出每一个标题。回头通读一遍，判断一个人**仅凭标题**能否跟上整个演示的脉络。标题应像书的章节——用直白的语言告诉读者接下来是什么。审阅这些标题并按需修订。将它们写入 scratchpad.md 文件。
+3. 在 scratchpad.md 里为每张幻灯片标注**版式原型**（满版图 / 大数字 / 图表 / 表格 / 引用 / 多栏卡片 / 时间线 / 纯文字……）与**视觉锚点**（这页视线的第一落点）。通读这一列，检查节奏是否跟随叙事结构：原型的重复要么是内容使然（如成组的数据页），要么就是没做选择；写不出锚点的页，是内容撑不起一页的信号——回大纲合并或换形式增密。
+4. 在写任何幻灯片**之前**，先在 `<head>` 的一个 `<style>` 块中将字号、行高和间距定义为 CSS custom properties——这会锁定适合投影的尺寸，防止不自觉退回网页密度。画幅恒为 1920×1080（deck-stage 的基准，输出尺寸由组件 letterbox 缩放解决），合理的起始体系为：`: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; }`。所有地方都引用这些变量——每个 font-size 都用 `--type-*`，每个 line-height 都用 `--leading-*`，每个 padding/gap 都用 `--pad-*` 或 `--gap-*`，通过 inline style 或 class 规则中的 `var(…)` 引用。取档跟着版式原型走：大数字 / 引用页的主角上 `--type-display`，表格单元格用 `--type-small`；连续文本块限宽 `max-width: var(--measure-body)`——行长超限会让达标的字号读起来又小又密，多出来的画幅宽度用双栏、图文并排消化，而不是让一行文字全宽跑。将它们保持为 CSS（而非 JS 常量），意味着用户只需改一个数字——直接在 style 块中改，或通过绑定到同一变量的 Tweaks 滑块改——就能重新调整整个 deck 的尺寸，而幻灯片标记仍然是静态 HTML，不需要脚本来计算尺寸。显式的 `--pad-bottom` 为每张幻灯片底部预留呼吸空间；那个留白是结构性的，不是空的。网页默认值（body 14-16px、padding 48-72px）对幻灯片太小；如果数值让你觉得不够大方，那就是还不够。任何文字不得小于 24px——这是下限不是目标。
+5. **把这套 token 当成每页的内容预算**：在上述数值下，一页正文区大约容纳 14 行正文、或 6 个两行 bullet——在 scratchpad 排内容时就按预算裁剪，而不是写完再看塞不塞得下。装不下的处置顺序是**拆页 > 删内容 > 换更省空间的版式**；缩小字号是最后手段，且绝不越过 24px 下限——靠缩字塞进去的页，只是把溢出换成了后排看不清。反过来，内容远少于预算的页按「视觉平衡」的出路增密或合并，而不是放大字号去撑面积。
+6. 构建幻灯片，牢记每张幻灯片既是设计练习也是文案练习。在版式、文字内容和语调方面给予每张幻灯片应有的关注。遵循上述原则，确保每张幻灯片能独立成立；一个只看这一页的人，应当无需其他上下文就能理解其高层含义。
+
+## 验证要点
+
+审阅时，用幻灯片构图规则——而非网页布局直觉——来检查版面。底部留白是不是缺陷，用「留白 ≠ 空洞」的归属判据：内容自身完整、下方是无边框的整块呼吸空间，这是正确的幻灯片构图——不要出于网页直觉把 `flex-start` 改成 `center`；空白被元素边界圈占的，是被动空洞，按「视觉平衡」的出路修。
+
+逐页核对以下各项：
+
+- 字号匹配你的 `--type-*` 体系（而非网页密度），没有为塞内容缩到 24px 以下
+- 连续文本块行长不超过 `--measure-body`，没有一行文字横穿整个画幅
+- 幻灯片边距匹配你的 `--pad-*` 值（而非网页紧凑间距）
+- 封面有统治画面的主视觉，标题位置有构图意图，不是「小图标 + 居中标题 + 居中副标题」三件套
+- 结构件（页码、眉标）全 deck 位置样式一致；章节页彼此外观一致
+- 没有任何尺度的装饰性彩色边条（判据见「彩色边条」）；没有 takeaway box
+- 内容区平面化：没有装饰性渐变背景、发光、玻璃拟态；渐变只出现在图上文字保护或数据色带上
+- 没有内容被画幅边缘裁切、显示不全
+- 没有元素相互压叠、遮挡到读不清
+- 没有被动空洞：边框 / 底色圈出的范围与其内容相称
+- 页面视觉重量在画布上分布均衡，没有大片区域读成「缺了东西」
+- 每页能指出视觉锚点；版式原型的重复经得起「内容使然还是没做选择」的追问
+- 带动效的元素在缩略图栏和打印视图下完整可见（基础样式即最终态，隐藏态只在 keyframes 的 `from` 里）

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 格式