@lark-apaas/coding-steering 0.1.18-dev.6de99aa → 0.1.18-dev.7f786ca

package/README.md

@@ -2,23 +2,21 @@
 
 Stack-specific steering content for [miaoda coding](https://code.byted.org/apaas/miaoda-coding) templates.
 
-Consumed by [miaoda-cli](https://code.byted.org/apaas/miaoda-cli) at `app init` time and synced into the user project's `.agent/steering/`. **Not a runtime dependency** — no entry in user `package.json`.
+Consumed by [miaoda-cli](https://code.byted.org/apaas/miaoda-cli) during `miaoda skills sync` (including `app init`). It is **not a runtime dependency** — no entry in the user project's `package.json`.
 
 ## Layout
 
 ```
 steering/
-├── _common/
-│   └── skills/                    # cross-stack shared skills
 ├── <stack>/
-│   ├── tech.md                    # always-loaded, injected into agent system prompt
-│   ├── skills/<id>/SKILL.md       # progressive disclosure, triggered by description match
-│   └── skills_local/<id>/SKILL.md # local-only variant; overrides skills/<id> when syncing
-│                                  #   to a local-dev project (e.g. via lark-cli)
+│   ├── tech.md                    # optional, stack overview
+│   ├── skills_common/<id>/SKILL.md # both local and sandbox; copied first
+│   ├── skills/<id>/SKILL.md        # sandbox-only; copied after common
+│   └── skills_local/<id>/SKILL.md  # local-only; copied after common
 └── ...
 ```
 
-Top-level directory names (other than `_common`) ARE the stackId — discovery is by directory convention, no central manifest.
+Top-level directory names are stack IDs — discovery is by directory convention, with no central manifest.
 
 ## Supported stacks
 
@@ -31,7 +29,7 @@ vice versa). Current state:
 | `vite-react` | React + Vite SPA | ✅ | `plugin-guide`, `react-three-fiber` | [`coding-template-vite-react`](../../templates/vite-react) |
 | `html` | 妙搭 html，带 devserver | ✅ | `rich-interactive-design` | [`coding-template-html`](../../templates/html) |
 | `nestjs-react-fullstack` | NestJS + React 全栈 | — | `authn`/`authz`/`feishu`/`plugin`/`devops`/`trigger`/`user-*` … + `skills_local/` (`code-fix`, `coding-guide`) | [`coding-template-nestjs-react-fullstack`](../../templates/nestjs-react-fullstack) |
-| `design-html` | **无构建**纯静态 HTML 托管（源码即产物，类 Claude Design） | — | _（占位，待补）_ | [`coding-template-design-html`](../../templates/design-html) |
+| `design-html` | **无构建**纯静态 HTML 托管（源码即产物） | — | _（占位，待补）_ | [`coding-template-design-html`](../../templates/design-html) |
 | `design-stack` | **带构建**的 design / 创意栈（有工具链，区别于 buildless 的 `design-html`） | — | _（占位，待补）_ | _（暂无）_ |
 
 `design-html` 与 `design-stack` 是两个**有意分开**的 design 栈：前者无构建、纯静态托管；
@@ -41,20 +39,20 @@ vice versa). Current state:
 
 ## Sync mapping (executed by miaoda-cli)
 
-| Source in this package | Destination in user project |
-|---|---|
-| `steering/<stack>/tech.md` | `.agent/steering/tech.md` |
-| `steering/<stack>/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
-| `steering/<stack>/skills_local/<id>/**` | `.agent/steering/skills/<id>/**` (local-dev sync only) |
-| `steering/_common/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
+`MIAODA_DEP_CACHE_DIR` selects the source mode; `--local` selects only the output layout. Do not use a sandbox environment plus `--local` as evidence for either supported flow.
 
-Precedence when the same `<id>` exists in multiple sources (lowest → highest, later wins):
-`_common/skills` → `<stack>/skills` → `<stack>/skills_local` (local-dev sync only).
+| Source in this package                   | Local output (`MIAODA_DEP_CACHE_DIR` empty + `--local`) | Sandbox output (`MIAODA_DEP_CACHE_DIR` non-empty, no `--local`) |
+| ---------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
+| `steering/<stack>/skills_common/<id>/**` | `.agents/skills/<id>/**`                                | `.agent/skills/steering/<stack>/skills/<id>/**`                 |
+| `steering/<stack>/skills_local/<id>/**`  | Same local path, copied after common.                   | Not copied.                                                     |
+| `steering/<stack>/skills/<id>/**`        | Not copied.                                             | Same sandbox path, copied after common.                         |
 
-`skills_local` is a stack-specific variant intended for the local-development sync path
-(`miaoda skills sync --local`, driven by `lark-cli apps`). The cloud sandbox sync path
-ignores `skills_local` and uses `skills` as-is, so authors of `skills_local` content can
-assume "本地 agent" semantics (no `ddl_sql` / `plugin_instance` / sandbox-log tools, etc.).
+For a duplicated skill ID, the copy order is:
+
+- Local: `skills_common → skills_local`; the local variant wins.
+- Sandbox: `skills_common → skills`; the sandbox variant wins.
+
+Put a guide in `skills_common/<id>/SKILL.md` when it must reach both supported modes. Keep a same-name `skills/` or `skills_local/` copy only when a deliberate mode-specific override is required.
 
 ## Writing rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.18-dev.6de99aa",
+  "version": "0.1.18-dev.7f786ca",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/design-html/skills/animated-video/SKILL.md

@@ -9,11 +9,11 @@ metadata:
 
 # Animated video
 
-Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling with the Anthropic brand palette. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.
+Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.
 
 START by calling `copy_starter_component` with `kind: "animations.jsx"` — it gives you a ready-made timeline engine: `<Stage width height duration>` (auto-scales to viewport, scrubber + play/pause + ←/→ seek + space + 0-to-reset, persists playhead), `<Sprite start end>` to gate children to a time window, `useTime()` / `useSprite()` hooks, an `Easing` library, `interpolate()` / `animate()` tweens, and `TextSprite` / `ImageSprite` / `RectSprite` primitives with built-in entry/exit. Read the file after copying and build YOUR scenes by composing Sprites inside a Stage; only fall back to Popmotion (https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/popmotion@11.0.5/dist/popmotion.min.js) if the starter genuinely can't do what you need.
 
-Animations are complex code! Make reusable JSX components for each visual element and each scene. Invest in tweaking the timeline iteratively.
+Animations are complex code! Make reusable JSX components for each visual element and each scene. Every moment gets ONE definition; sprite-local times and offsets derive from it, never stored separately. The failure: `cardSelectStart = 1.2` inside a scene while the cursor holds `{ t: 9.2 }` for the same beat. Timing shared with nothing else — entry stagger, easing durations — stays local.
 
 Animation tips:
 - Storytelling is KEY! Before you create ANYTHING, identify the story arc, key tensions, characters, etc. Align on the message you want to convey. Run it by the user.

package/steering/design-html/skills/charts/SKILL.md

@@ -7,6 +7,8 @@ metadata:
     en-US: Charts
 ---
 
+{% raw %}
+
 # 图表
 
 你是用 ECharts 呈现信息的数据叙事设计者。你的图表会出现在创意 HTML 产物中，例如仪表盘、幻灯片、设计探索。ECharts 是你的媒介，不是目标；你的工作是让数据故事一眼可读，而不是堆配置项。一个图表只表达一个主要信息。
@@ -48,7 +50,7 @@ metadata:
 
 5. **编写 ECharts 代码。** 挂载模式和 API 约束见下方技术参考。
 
-6. **自检。** 截图检查结果。按文末清单验证。然后回到视觉编码步骤：渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
+6. **自检。** 按文末清单逐项检查你写出的 option 代码（源码级自查，不用打开浏览器截图）。然后回到视觉编码步骤：这套配置渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
 
 ## 图表类型映射
 
@@ -77,6 +79,44 @@ metadata:
 - **表达覆盖**：把用户需求拆成需要被回答的信息关系；每个被承诺的关系都要有对应的图表、表格、矩阵或文字证据承载。不要用少量通用指标和默认图表替代所有分析任务。
 - **小容器防崩**：小尺寸图表优先用 bar / line / number strip。饼图、雷达图、词云和外部标签很容易挤压重叠；空间不足时换图表类型，而不是缩小到不可读。
 
+## 窄屏适配
+
+图表出现在报表或看板中时，移动端（≤768px）的容器宽度可能压到 300px 以下。盲目把桌面端图表原样塞进窄容器，会导致 axis label 堆叠、legend 遮盖绘图区、饼图标签溢出。以下是在窄屏容器中保证可读性的规则：
+
+### 布局容器
+
+报表中承载图表的网格必须在窄屏时折叠为单列。写多列网格时，用 `auto-fit` + `minmax()` 让浏览器自动折叠，或配合 `@media` 断点显式切换：
+
+```css
+/* 自动折叠：每列最小 320px，不够就换行 */
+.chart-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  gap: 16px;
+}
+
+/* 或显式断点 */
+@media (max-width: 768px) {
+  .chart-grid { grid-template-columns: 1fr; }
+}
+```
+
+不要写死 `grid-template-columns: 1.2fr 2fr` 而不提供窄屏回退——390px 视口下，1.2fr 只有 146px，放不下任何图表。
+
+### ECharts option 适配
+
+在窄容器（宽度 <400px）中调整 ECharts option：
+
+- **legend**：改为 `orient: 'horizontal'` + `type: 'scroll'`，放在图表底部（`bottom: 0`），不要放在侧面挤占绘图区。
+- **grid**：增大 `left` / `right` 留白到 `'12%'` 以上，防止 axis label 被裁切。
+- **x 轴 label**：长文本加 `axisLabel: { rotate: 30, interval: 0 }` 或截断 formatter；分类超过 8 个时用 `interval: 'auto'` 让 ECharts 自动跳标签。
+- **tooltip**：窄屏下 tooltip 容易超出视口，设 `confine: true`。
+- **图表类型降级**：桌面端的并排双图在移动端改为上下堆叠；桌面端的 Pie 在容器宽度 <250px 时考虑改为横向 Bar。
+
+### 容器尺寸监听
+
+用 `ResizeObserver` 而非 `window.resize` 监听图表容器（见下方「技术参考 · 挂载」的封装代码）。当网格从双列折叠为单列时，window 尺寸不变但容器变宽，`resize` 事件不触发，图表不会重绘。
+
 ## 技术参考
 
 ### 加载 ECharts
@@ -94,23 +134,24 @@ metadata:
 <script>
   const chart = echarts.init(document.getElementById('chart'));
   chart.setOption({ /* ... */ });
-  window.addEventListener('resize', () => chart.resize());
+  new ResizeObserver(() => chart.resize()).observe(document.getElementById('chart'));
 </script>
 ```
 
 ### 挂载——React 封装
 
-定义一次，复用。**不要**添加 echarts-for-react。
+定义一次，复用。**不要**添加 echarts-for-react。用 `ResizeObserver` 而非 `window.resize` 监听容器尺寸变化（见「窄屏适配」说明）。
 
 ```jsx
 function EChart({ option, style }) {
   const ref = React.useRef(null);
   React.useEffect(() => {
-    const chart = echarts.init(ref.current);
+    const el = ref.current;
+    const chart = echarts.init(el);
     chart.setOption(option);
-    const onResize = () => chart.resize();
-    window.addEventListener('resize', onResize);
-    return () => { chart.dispose(); window.removeEventListener('resize', onResize); };
+    const ro = new ResizeObserver(() => chart.resize());
+    ro.observe(el);
+    return () => { ro.disconnect(); chart.dispose(); };
   }, [option]);
   return <div ref={ref} style={{ width: '100%', minHeight: 300, ...style }} />;
 }
@@ -152,6 +193,8 @@ Object.assign(window, { EChart });
 | 17 | 双 Y 轴零点未对齐 | 匹配 `\|min\| / max` 比例 |
 | 18 | 图表 series 或容器使用阴影/发光效果 | 移除 `shadowBlur`、`shadowColor`、容器 `box-shadow`，改用线宽、透明度、注释或面积大小表达层级 |
 | 19 | 图表或标签挤压、重叠、被容器裁切 | 增大容器、减少标签、改用 tooltip / inside label，或换成更稳的图表类型 |
+| 20 | 图表容器的父级网格在窄屏（≤768px）下没有折叠为单列 | 用 `auto-fit + minmax(320px, 1fr)` 或 `@media` 断点，保证每个图表容器至少 320px 宽 |
+| 21 | 使用 `window.addEventListener('resize', ...)` 监听图表尺寸 | 改用 `ResizeObserver`——网格列折叠时 window 尺寸不变但容器变宽，`resize` 事件不触发 |
 
 ### 不建议
 
@@ -161,3 +204,5 @@ Object.assign(window, { EChart });
 | Line 连接未按时间排序的点 | Bar 或 Scatter |
 | markPoint 重复（统计极值 = 业务事件） | 仅保留业务注释 |
 | 用 Stacked Bar 表示 Gantt | 使用带 `renderItem` 的 `custom` series |
+
+{% endraw %}

package/steering/design-html/skills/{data-report → data-viz}/SKILL.md

@@ -1,15 +1,15 @@
 ---
-name: data-report
-description: "数据驱动的报表与看板设计。从数据分析到报表规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化数据报表的场景。图表绘制部分由 charts skill 承担。触发词：数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data report, dashboard report, analytics report"
+name: data-viz
+description: "数据可视化设计。从数据分析到版面规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化报表、看板或可视化页面的场景。图表绘制部分由 charts skill 承担。触发词：数据可视化, 数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data visualization, data report, dashboard report, analytics report"
 metadata:
   display-names:
-    zh-CN: 数据看板
-    en-US: Data Dashboard
+    zh-CN: 数据可视化
+    en-US: Data Visualization
 ---
 
-# 数据报表
+# 数据可视化
 
-你是数据报表设计者。你的工作是把原始数据变成一份读者能直接用来做判断的报表——不只是画几张图，而是回答"这份数据在说什么、读者应该关注什么"。
+你是数据可视化设计者。你的工作是把原始数据变成一份读者能直接用来做判断的可视化页面——不只是画几张图，而是回答"这份数据在说什么、读者应该关注什么"。
 
 报表的价值不在图表数量，而在信息层级：读者能在 5 秒内抓到主要结论，30 秒内理解支撑证据，需要时能下钻到明细。
 
@@ -19,7 +19,9 @@ metadata:
 
 布局必须比普通上下堆叠更丰富。先根据数据任务选择版式骨架，再写代码：监控型、复盘型、诊断型、对比型、明细型、汇报型可以有完全不同的扫描路径。可以组合 KPI 指标条、左右不等分主分析区、辅助矩阵、排名/明细表、洞察侧栏、深色结论带、时间线或漏斗区，但不要每份报表都套成同一套 KPI 横条 + 主图 + 洞察卡。不要把每个章节都做成同宽标题加一张满宽卡片；核心模块占更大面积，支撑模块用不同宽度、密度和位置服务它。
 
-报表不是产品原型。内容型或分析型交付服务阅读和决策，不默认生成多页面后台导航、可下拉应用名、无意义返回按钮或设置菜单；只有用户明确要求交互式系统、后台、筛选操作或多页面应用时才做这些。标题、范围、口径、结论、图表、洞察和明细都是可用的信息部件，不是每份报表都必须同时出现的固定章节。
+报表不是产品原型。内容型或分析型交付服务阅读和决策，不默认生成多页面后台导航、可下拉应用名、无意义返回按钮或设置菜单。标题、范围、口径、结论、图表、洞察和明细都是可用的信息部件，不是每份报表都必须同时出现的固定章节。
+
+看板中的筛选器、标签页切换（如"今日/近7天/近30天"、"库存量/库存金额"、"30天/90天"）、下拉选择等控件如果出现在页面上，必须用 JavaScript 实现真实的切换逻辑——点击后切换数据视图、过滤图表或改变显示内容。不实现功能的控件不得使用 `<button>`、`cursor:pointer` 或 active/hover 样式暗示可点击；纯标注用 `<span>` 或静态文字呈现。
 
 不要让页面全是文字，也不要把所有章节都做成同一种"结论 + 指标 + 图表 + 洞察"结构。长材料先判断每段内容在当前报表里的作用：它是在给背景、定义口径、证明结论、展示变化、比较对象、解释异常、列明细，还是提出行动。每段只选择最适合的表达方式，可以是短结论、关键数字、对比、时间顺序、表格、矩阵、引用、图表、注释或截图。重要内容不能被塞进附录或角落；如果一个章节是汇报目标的核心，就给它相称的版面面积和区别于其他章节的版式处理。
 
@@ -50,6 +52,13 @@ metadata:
 
 产出：维度-指标清单，以及一句话叙事重点。
 
+**数据忠实度约束。** 在此步完成后，明确标注哪些指标可以直接从源数据计算、哪些缺少必要数据（如历史期、目标值、预算基线）。后续步骤中：
+
+- 可直接计算的指标：使用真实值。
+- 源数据不含的派生指标（同比/环比变化率、完成率、差额等需要两期或多源数据而只有单期的）：不编造数值，用"—"占位或省略该指标。
+- 超出数据时间范围的外推值：不补齐，图表只覆盖数据实际跨度。
+- 确需补充示例数据时：必须在页面上用视觉标记（虚线边框、"示例数据"标签、灰色斜体）明确区分。
+
 ### 3. 报表规划
 
 在写代码之前，先确定报表由哪些组件构成：
@@ -59,7 +68,7 @@ metadata:
 - **候选部件**：标题 / 范围 / 口径、摘要、KPI、主图表、辅助图表、文字洞察、明细表、时间线、矩阵、截图或注释都只是候选。需要哪个用哪个，不要为了"完整"把它们凑齐。
 - **核心承载**：只给真正承载核心问题的模块更大面积。核心可能是一张趋势图、一张排名表、一段异常解释、一个流程漏斗，也可能是一组明细，不固定。
 - **版式差异**：为不同信息角色安排不同形态，例如紧凑指标条、宽图、窄侧栏、表格区、注释带、对比矩阵或分段背景。避免每个章节都重复同一张满宽白卡。
-- **布局骨架**：明确每个模块的相对面积和扫描路径，例如 `1.2fr 2fr`、`1fr 1.6fr`、`repeat(4,1fr)`、`auto 1fr` 等混合栅格；移动端再自然折叠。
+- **布局骨架**：明确每个模块的相对面积和扫描路径，例如 `1.2fr 2fr`、`1fr 1.6fr`、`repeat(4,1fr)`、`auto 1fr` 等混合栅格。多列网格必须提供窄屏回退（`auto-fit + minmax()` 或 `@media` 断点），不要写死 fr 比例而不处理移动端——详见下方「移动端适配」。
 
 组件取舍由读者任务、数据复杂度和材料内容决定。
 
@@ -84,12 +93,53 @@ metadata:
 - 表格用于精确查数和比较对象，不要把长表伪装成密集柱状图。
 - KPI 用于概览，不要把每个字段都做成指标卡。
 - 没有真实依据时不编造结论；可写"待补充口径"或使用中性描述。
+- 页面中每个数值必须可溯源：源数据直读、或从源数据可验证计算得出。缺少计算所需数据时（如同比需要上期数据但只有本期），用"—"占位或省略，不编造。
+- 所有视觉上暗示可交互的控件（标签页、筛选器、按钮、下拉、日期切换）必须绑定真实 JS 逻辑。不实现切换功能就不画成可点击样式。
 
 产出：完整报表页面。
 
+### 5.5 移动端适配
+
+报表在桌面端的复杂网格不会自动适配移动端。写完桌面布局后，必须为 ≤768px 视口补充响应式处理：
+
+**页面基础**：HTML 必须包含 `<meta name="viewport" content="width=device-width, initial-scale=1">`，否则移动浏览器用 980px 默认视口渲染再缩小，所有字都变成蚊子大小。
+
+**模块折叠策略**：
+
+- **KPI 指标条**：桌面端横排 4 个时，移动端折叠为 2×2 网格。用 `repeat(auto-fit, minmax(160px, 1fr))` 自动处理，或 `@media (max-width: 768px)` 显式切到两列。
+- **主分析区（左右不等分）**：`1.2fr 2fr` 或 `auto 1fr` 这类侧栏 + 主区布局，移动端必须折叠为单列——侧栏内容移到主区上方或下方。
+- **并列图表**：两图并排在移动端改为上下堆叠，每个图表独占一行。图表容器的窄屏处理由 charts skill 的「窄屏适配」规则覆盖。
+- **明细表格**：宽表在窄屏下加 `overflow-x: auto` 让表格可横向滚动，不要压缩列宽到不可读。
+- **洞察侧栏 / 注释带**：移动端折叠到对应图表下方，不要浮动遮盖内容。
+
+**断点写法**（二选一）：
+
+```css
+/* 方式 A：auto-fit 自动折叠 */
+.report-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  gap: 16px;
+}
+
+/* 方式 B：显式断点 */
+.report-layout {
+  display: grid;
+  grid-template-columns: 1.2fr 2fr;
+  gap: 24px;
+}
+@media (max-width: 768px) {
+  .report-layout {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+**字号底线**：移动端正文不低于 14px，KPI 数字不低于 20px，图表标题不低于 13px。
+
 ### 6. 自检
 
-截图检查结果，验证以下几点：
+读一遍自己写出的代码（源码级自查），逐项验证以下几点：
 
 - 报表是否回答了步骤 1 确定的核心问题。
 - 信息层级是否清晰（读者能在 5 秒内抓到主要结论）。
@@ -101,5 +151,11 @@ metadata:
 - 文字洞察是否与图表数据互相支撑。
 - 图表部分是否通过了 charts skill 的自检清单。
 - 口径和单位是否全报表一致。
+- 页面中展示的每个数值是否可溯源到用户提供的数据；同比/环比/完成率等派生指标是否有对应的基准数据支撑，没有的是否已用"—"占位而非编造。
+- 所有视觉上可点击的控件（标签页、筛选器、按钮、下拉）是否都绑定了真实 JS 逻辑，点击后确实切换数据或视图；没有功能的元素是否已改为静态文字样式。
+- HTML 是否包含 `<meta name="viewport" content="width=device-width, initial-scale=1">`。
+- 多列网格是否提供了窄屏回退（`auto-fit + minmax()` 或 `@media` 断点），在 390px 视口下是否折叠为单列且无横向滚动。
+- 宽表格是否有 `overflow-x: auto` 容器包裹。
+- 移动端字号是否达到底线（正文 ≥14px、KPI 数字 ≥20px、图表标题 ≥13px）。
 
 产出：确认或修正。

package/steering/design-html/skills/frontend-design/SKILL.md

@@ -24,7 +24,7 @@ metadata:
 - **配色（Palette）**——哪些颜色承担语义或品牌职责，哪些是中性的支撑色，哪一个唯一的强调色赢得注意力？
 - **签名元素（Signature）**——整个页面靠它被记住的那一个手法。它必须只可能属于这个主题；一个换到下份 brief 也能复用的签名元素，是默认值，不是选择。
 
-风格不是版式排完后再涂上去的装饰。这个方向决定字体排印、间距、图表处理、章节节奏、边框、图标风格，以及哪些组件值得强调。
+风格不是版式排完后再涂上去的装饰。这个方向决定字体排印、间距、图表处理、图像质感、章节节奏、边框、图标风格，以及哪些组件值得强调。
 
 ## 设计原则
 
@@ -54,7 +54,7 @@ metadata:
 
 ## 克制与自我评审
 
-把大胆花在一个地方。让签名元素成为唯一被记住的东西，它周围的一切保持安静、克制，砍掉任何不服务于 brief 的装饰。不冒险本身也可能是一种冒险！默默守住质量底线，不必声张：响应式适配到移动端、键盘焦点可见、尊重 reduced motion。边构建边评审自己的作品，环境支持就截图看——一图胜千 token。想想香奈儿的忠告：出门前照照镜子，摘掉一件配饰。人类创作者有记忆，总在尝试新东西；如果你有地方快速记下自己试过什么，会对后续迭代有帮助。
+把大胆花在一个地方。让签名元素成为唯一被记住的东西，它周围的一切保持安静、克制，砍掉任何不服务于 brief 的装饰。不冒险本身也可能是一种冒险！默默守住质量底线，不必声张：响应式适配到移动端、键盘焦点可见、尊重 reduced motion。边构建边评审自己的作品——读你写出的代码，在脑子里过一遍它渲染成什么样。想想香奈儿的忠告：出门前照照镜子，摘掉一件配饰。人类创作者有记忆，总在尝试新东西；如果你有地方快速记下自己试过什么，会对后续迭代有帮助。
 
 ## 再谈设计中的写作
 

package/steering/design-html/skills/mini-game/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mini-game
+description: 创建有胜负、挑战目标或玩法循环的小游戏（休闲 / 益智 / 街机 / 答题 / 反应类）。触发词：game, 游戏, 小游戏, 玩法, 街机, 益智, 关卡, playable。产品界面与流程演示用 interactive-prototype；无胜负的系统模拟不适用。
+metadata:
+  display-names:
+    zh-CN: 小游戏
+    en-US: Mini Game
+---
+
+# 小游戏
+
+为有胜负 / 挑战目标 / 玩法循环的小游戏做玩法与工程决策。视觉方向仍由 `frontend-design` 先行确立；本 skill 条款与通用规则冲突时，以本 skill 为准。
+
+**边界**：产品界面与流程演示 → `interactive-prototype`；无胜负的系统模拟（元胞自动机 / 流体 / 粒子沙盒）与 3D 沉浸漫游 → 不套用本 skill。
+
+## Quick Reference
+
+| 决策 | 默认 | 例外 |
+|---|---|---|
+| 渲染层 | 回合 + 离散网格 → DOM Grid；实时连续 → Canvas 2D | 用户指定时尊重 |
+| 主循环 | 实时类 `requestAnimationFrame` | 回合类事件驱动，无主循环 |
+| 输入 | 桌面键鼠 + 移动 touch 同时支持 | 用户明确单端 |
+| 再来一局 | 真 reset 全部状态 | — |
+| 最高分 | localStorage 持久化 | 用户明确不要 |
+| 库 | 原生 Canvas / DOM / 原生 JS | 白名单按需行（物理 / 3D） |
+
+## 交互契约
+
+- 「再来一局」必须重置全部状态（分数 / 棋盘 / 计时器），禁 `location.reload()` 充当重启。
+- 报分、结束、确认一律游戏内 UI 面板，禁 `alert()` / `confirm()` / `prompt()`。
+- 结束面板至少含：本局分数、最高分、「再来一局」按钮。
+- 暂停必须真停主循环（`cancelAnimationFrame`），不是 dt 置 0 空转；监听 `visibilitychange`，切后台自动暂停。
+- 实时类主循环用 `requestAnimationFrame`，禁 `setInterval`；回合类事件驱动即可，不为「像游戏」硬塞 rAF。
+- 最高分读写 `localStorage` 包 `try/catch`（隐私模式会抛错）。
+
+## 渲染层
+
+- 回合驱动 + 离散网格（2048 / 三消 / 棋盘 / 卡牌 / 答题）→ DOM + CSS Grid（`grid-template-columns: repeat(N, 1fr)`），移动 / 合并动画走 `transform` + `transition`。不默认上 Canvas——会丢掉免费的过渡动画与清晰文字；也不要 `position: absolute` + 像素 left/top 排格子。
+- 实时连续运动（跑酷 / 弹幕 / 打砖块）→ Canvas 2D。
+
+## 双端输入
+
+- 桌面键鼠 + 移动 touch 必须同时支持（产物常在飞书容器内用手机打开），用户明确单端时除外。
+- 优先 Pointer Events 统一两端；键盘方向类操作在移动端补虚拟方向键或 swipe 手势。
+- 游戏容器设 `user-select: none; touch-action: none;`，防长按选中与手势拖动页面；触控目标 ≥ 44×44px。
+
+## 素材
+
+- 需要精灵 / 角色 / 背景图时用 `generate_image`，prompt 尾缀固定：`game asset, transparent background, flat icon, no text overlay`。写「epic / cinematic scene」会产出电影海报而非可用素材。
+- 纯数字 / 色块 / 几何即可成立的玩法（2048 类）不生图。
+
+## 难度
+
+- 进度感至少满足一种：得分递增 / 速度递增 / 关卡推进。禁从头到尾单一难度、单一速度。
+
+## 缩略图态
+
+平台在提交前会截 `index.html?thumbnail=1` 作为应用缩略图：菜单首屏按海报感设计；检测到 URL 带 `thumbnail` 参数时定格菜单态——不自动开局、不停在 loading。
+
+## 库白名单（CDN 锁定）
+
+| 用途 | 选型 | 默认/按需 | 引入方式 |
+|---|---|---|---|
+| 游戏渲染 | 原生 Canvas 2D / DOM / SVG | 默认 | 无需引入 |
+| 交互 / 动画 | 原生 JS + rAF / 原生 CSS | 默认 | 无需引入 |
+| 2D 物理 | Matter.js | 按需：真实刚体（抛体 / 碰撞堆叠 / 铰链）；简单弹跳自己写积分 | `<script src="https://cdn.jsdelivr.net/npm/matter-js@0.20.0/build/matter.min.js"></script>` |
+| 3D 游戏 | Three.js r147 UMD | 按需：用户明确要 3D。引入前先 Read 本 skill 的 `references/three-js.md` | `<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script>` |
+
+- CDN URL 原样复制，不自行替换版本号。明确不引入：Phaser 等游戏引擎（原生 Canvas 替代）、GSAP（原生 CSS / rAF 替代）。
+- 游戏主体不走 React+Babel 栈，用原生 JS 组织（本条按媒介 skill 优先规则覆盖系统级 React 指引）；仅在既有 React 产物内嵌游戏时保留 React 外壳，且每帧游戏状态不进 React state。
+- 音效仅在用户要求时做：Web Audio 合成，首次用户手势后 `AudioContext.resume()` 解锁，并提供静音开关。

package/steering/design-html/skills/mini-game/references/three-js.md

@@ -0,0 +1,54 @@
+# Three.js r147 UMD 引入指南（3D 小游戏按需）
+
+r147 是最后一个含 UMD `examples/js/` 的版本：经典 `<script>` 标签引入，全局 `THREE` 命名空间。无需 importmap、无需 `type="module"`。
+
+## 基础引入
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/controls/OrbitControls.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/loaders/GLTFLoader.js"></script>
+<script>
+  const controls = new THREE.OrbitControls(camera, renderer.domElement);
+  const loader = new THREE.GLTFLoader();
+</script>
+```
+
+覆盖路径：`examples/js/{controls,loaders,postprocessing,objects,shaders,exporters,...}/<Name>.js`。
+
+## extensions 隐式依赖（黑屏陷阱）
+
+**`examples/js` 下各文件之间有隐式全局依赖，且按 script 标签顺序求值。漏引或顺序错会直接抛 `TypeError` 并中断整个初始化脚本——页面卡在 loading 或永久黑屏，且没有任何报错提示。** 用到 addon 时整段复制下方清单，不要只挑名字对得上的那几个。
+
+## 后期处理（EffectComposer / Bloom 等）——整段复制，顺序不可调换
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script>
+<!-- EffectComposer.js 内部定义 THREE.Pass 基类，必须排在所有 *Pass 之前 -->
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/postprocessing/EffectComposer.js"></script>
+<!-- 纯 shader 对象，供下面的 Pass 引用 -->
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/shaders/CopyShader.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/shaders/LuminosityHighPassShader.js"></script>
+<!-- 各 Pass 均为 class X extends THREE.Pass，依赖上面的基类 -->
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/postprocessing/ShaderPass.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/postprocessing/RenderPass.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/postprocessing/UnrealBloomPass.js"></script>
+```
+
+| 你要用 | 必须同时引入 |
+|---|---|
+| `EffectComposer` | `CopyShader` + `ShaderPass`（构造函数里立即用到） |
+| `UnrealBloomPass` | `LuminosityHighPassShader` + `CopyShader` |
+| 任意 `*Pass` | `EffectComposer.js`（提供 `THREE.Pass` 基类），且必须排在它之后 |
+
+只引 `EffectComposer` + `RenderPass` + `UnrealBloomPass` 这三个是**错的**，会报 `THREE.ShaderPass is not a constructor`。
+
+## 色彩管理（r147 默认 Linear，必须显式启用 sRGB）
+
+```js
+renderer.outputEncoding = THREE.sRGBEncoding;          // 输出 sRGB
+texture.encoding = THREE.sRGBEncoding;                 // 颜色纹理（baseColor / albedo）
+// 注意：normalMap / roughnessMap / metalnessMap 保持默认 Linear，不要改
+```
+
+未启用会导致 PBR 材质看上去发淡 / 过饱和。