@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f111120

package/miaoda/ai-data-processing/SKILL.md

@@ -47,6 +47,8 @@ SELECT * FROM rds_ai.list_model();
 
 按业务需求选定模型，取其 `model_name` 作为第二个参数。
 
+⚠️ **模型可用性由租户管理后台管控。** `list_model()` 返回的是平台预置清单；管理员下架或停用其中某个模型后，平台自动在其余可用预置模型中选择，业务 SQL 无需改动。因此除非用户明确要求锁定模型，否则不传 `model_name`；锁定的模型被停用时，加工结果可能出现风格波动。预置模型全部不可用时调用直接失败，处置见「关键注意事项」。
+
 ## 实现步骤
 
 以下 SQL 使用 `tickets` / `priority` 作为示例。Agent 生成实际方案时，必须替换成用户应用里的真实表名、字段名、主键和 `task_kind`。
@@ -378,10 +380,11 @@ LIMIT 20;
 | ❌ 业务事务路径（同步 trigger / 大批量 UPDATE）里直接调 `rds_ai.ai_query` | HTTP 调用会因网络抖动、限流、超时、模型异常抛错，阻塞业务写入、占锁并产生大额模型调用 | trigger 只入队，模型调用统一由 `ai_run_pending_jobs()` 的 EXCEPTION 块兜住；批量场景先小样本验证，再经 `ai_job` 分批处理 |
 | ❌ 422 / `quota_exceeded` 报错后继续重试 | 当前应用 AI 调用额度已用完，重试只会继续报错 | 任务直接置 `failed`、停止入队，续费后批量重跑；提示用户「AI 调用额度已耗尽，请联系应用 Owner 在控制台续费或升级套餐后再试」 |
 | ❌ 429 / `rate_limit_exceeded` 报错后原速重跑 | 调用过于密集触发限流 | 保持重试 + 指数退避；调小 `ai_run_pending_jobs` 单次批量、放慢 worker 节奏；提示用户「AI 调用过于频繁触发了限流，已自动放慢节奏，稍后会继续跑完」 |
+| ❌ 500 / `model_unavailable` 报错后继续重试或继续入队 | 租户预置模型已被全部下架或停用，平台无模型可选，重试不会恢复 | 任务置 `failed` 并停止入队；提示用户「当前租户无可用 AI 模型，请联系租户管理员恢复后再试」；模型恢复后重跑失败任务即可 |
 | ❌ prompt 不约束输出格式 | 解释性文本会作为脏值写回业务表 | 分类任务写清枚举值并在 SQL 函数里校验结果；JSON 抽取写清 JSON schema |
 | ❌ trigger 只靠 `UPDATE OF <col>` 判断变化 | 无关更新会重复入队、重复消耗 | 函数里再用 `IS NOT DISTINCT FROM` 判断源字段变化 |
 
-`rds_ai.ai_query` 抛错时，PG 错误信息通常带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` 关键字；失败任务停在 `ai_job` 表，错误码可从 `error_message` 字段读出供 UI 展示和告警归类。
+`rds_ai.ai_query` 抛错时，PG 错误信息通常带 HTTP 状态码（422 / 429 / 500）或 `quota_exceeded` / `rate_limit_exceeded` / `model_unavailable` 关键字；失败任务停在 `ai_job` 表，错误码可从 `error_message` 字段读出供 UI 展示和告警归类。
 
 **禁止**的写法（会阻塞业务写入事务）：
 

package/miaoda/animation-skill/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: animation-skill
+description: "React 动画动效开发规范（Framer Motion + AutoAnimate）。只要页面/组件涉及任何动画或动效——无论大小、无论是否紧急——都调用本 skill 获取实现规范再动手。选型优先级：列表增量增删/排序/accordion/toast/form-error 场景优先 AutoAnimate（3.28KB、零配置）；退场/手势/布局/stagger 序列/滚动揭示/批量替换才用 Framer Motion（34KB）。"
+---
+
+## 依赖安装（前置动作）
+
+使用 Framer Motion 或 AutoAnimate 前，**必须先检查 `package.json`，缺失则调用 `依赖管理工具` 安装**，禁止在未安装时直接写 `import` 代码。
+
+| 场景 | 包名 | 安装命令 |
+|------|------|---------|
+| Framer Motion（退场/手势/布局/滚动驱动/序列） | `framer-motion` | `npm install framer-motion` |
+| AutoAnimate（列表增删/排序/accordion/toast） | `@formkit/auto-animate` | `npm install @formkit/auto-animate` |
+
+**检查流程**：
+1. 读 `package.json`，确认所需包是否存在
+2. 不存在 → 调用依赖管理工具安装（禁止手动改 `package.json` 或跑 `npm i` 之外的命令）
+3. 已存在 → 直接使用，无需重复安装
+
+---
+
+## 选型决策流程
+
+```
+需要动画 → 能用 CSS/Tailwind 解决？ → 是 → CSS transition / @keyframes
+                                    → 否 ↓
+          是否列表增量增删/排序/accordion/toast/form-error？
+            → 是 → AutoAnimate（3.28KB gzip）
+            → 否 ↓
+          需要手势/退场/布局/滚动驱动/stagger 序列/整批替换？
+            → 否 → CSS transition（同第一步）
+            → 是 → Framer Motion（~34KB gzip）
+```
+
+**「增量增删」与「整批替换」的区分**（常见误判，AutoAnimate 的边界）：
+
+| 场景 | 属于 | 正确方案 |
+|------|------|---------|
+| Todo 列表新增一项 / 删除一项 / 拖动排序 | 增量增删 | **AutoAnimate** |
+| Kanban 任务在列间移动 / 新增卡片 | 增量增删 | **AutoAnimate** |
+| Accordion 展开/折叠子项 | 直接子元素显隐 | **AutoAnimate** |
+| Toast 通知栈 push/pop | 增量进出 | **AutoAnimate** |
+| Form 错误信息出现/消失 | 直接子元素显隐 | **AutoAnimate** |
+| 搜索/筛选结果**整列表重新生成** | 整批替换 | **Framer Motion `AnimatePresence mode="wait"`** |
+| 分组算法重新洗牌，所有卡片重建 | 整批替换 | **Framer Motion `AnimatePresence + stagger`** |
+| Diff 结果重新比对，所有 diff 块重建 | 整批替换 | **Framer Motion `AnimatePresence mode="wait"`** |
+| Tab 切换导致内容区整体替换 | 整批替换 | **Framer Motion `AnimatePresence`** |
+
+> 判断要点：**同一批数据增减 1~几个条目 → 增量（AutoAnimate）；数据源整体换新 → 批量（Framer Motion）**。
+
+**优先级原则**：命中「列表增量增删 / 排序 / accordion / toast / form-error」先选 AutoAnimate，体积小、零配置；只有需要退场 mode、手势、布局 FLIP、stagger 序列、滚动揭示、整批替换这些 AutoAnimate 覆盖不到的能力时，才升级到 Framer Motion。不要为了统一技术栈把所有动画都塞进 Framer Motion。
+
+**包体积对比：**
+
+| 方案 | Gzip 体积 | 覆盖能力 |
+|------|----------|---------|
+| AutoAnimate | ~3.28 KB | 列表增量增删排序、accordion、toast、form-error |
+| Framer Motion | ~34 KB | 全部（退场、手势、布局、MotionValue、stagger 序列、整批替换） |
+
+---
+
+## L2 禁止事项
+
+> 生成代码后须逐条核对，每一条都不可跳过。
+
+| # | 禁止 | 应该 |
+|---|------|------|
+| 1 | 动画 `width`/`height`/`top`/`left` 等触发 layout 的属性 | 使用 `transform`（`x`/`y`/`scale`/`rotate`）+ `opacity` |
+| 2 | 在 Next.js Server Component 中使用 `motion` | 添加 `"use client"`，动画部分提取为 Client Component |
+| 3 | `AnimatePresence` 内条件渲染子组件不给 `key` | 必须有唯一 `key`，否则退场动画不触发 |
+| 4 | 弹窗/toast 退场无动画直接卸载 | 用 `AnimatePresence` 包裹 + `exit` prop |
+| 5 | `spring` 不设 `damping` 导致无限弹跳 | 设置 `stiffness`（100-300）+ `damping`（10-30） |
+| 6 | AutoAnimate 期望对孙元素生效 | 只对**直接子元素**生效；嵌套层级需逐层挂 ref |
+
+---
+
+## Framer Motion 核心用法
+
+{% raw %}
+
+### 1. 基础动画（initial / animate / transition）
+
+```tsx
+import { motion } from "framer-motion";
+
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.5 }}
+>
+  内容
+</motion.div>
+```
+
+### 2. 退场动画（AnimatePresence）
+
+```tsx
+import { AnimatePresence, motion } from "framer-motion";
+
+<AnimatePresence>
+  {show && (
+    <motion.div
+      key="modal"
+      initial={{ opacity: 0, scale: 0.95 }}
+      animate={{ opacity: 1, scale: 1 }}
+      exit={{ opacity: 0, scale: 0.95 }}
+      transition={{ duration: 0.2 }}
+    />
+  )}
+</AnimatePresence>
+```
+
+### 3. Variants + Stagger
+
+```tsx
+const container = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.1, delayChildren: 0.2 } },
+};
+const item = {
+  hidden: { opacity: 0, y: 20 },
+  visible: { opacity: 1, y: 0 },
+};
+
+<motion.ul variants={container} initial="hidden" animate="visible">
+  {items.map((i) => (
+    <motion.li key={i.id} variants={item}>{i.name}</motion.li>
+  ))}
+</motion.ul>
+```
+
+### 4. 手势动画
+
+```tsx
+<motion.button
+  whileHover={{ scale: 1.05, backgroundColor: "#3b82f6" }}
+  whileTap={{ scale: 0.95 }}
+  whileFocus={{ boxShadow: "0 0 0 3px rgba(59,130,246,0.5)" }}
+>
+  按钮
+</motion.button>
+
+// 拖拽
+<motion.div
+  drag="x"
+  dragConstraints={{ left: -100, right: 100 }}
+  dragElastic={0.2}
+  dragMomentum={false}       // 关闭释放后惯性（默认 true）
+  onDragStart={(e, info) => { /* 用 info.point 更新 state 或触发副作用，禁止 console.log */ }}
+  onDrag={(e, info) => { /* 用 info.delta 计算偏移，可结合 useTransform 派生动画值 */ }}
+  onDragEnd={(e, info) => { /* 用 info.velocity 决定释放后行为（如滑动到吸附点） */ }}
+/>
+```
+
+### 5. 滚动动画
+
+**whileInView（最常用）：**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 50 }}
+  whileInView={{ opacity: 1, y: 0 }}
+  viewport={{ once: true, margin: "-100px" }}
+  transition={{ duration: 0.6 }}
+>
+  滚动到视口时显现
+</motion.div>
+```
+
+**useScroll 进度驱动：**
+
+```tsx
+import { motion, useScroll, useTransform } from "framer-motion";
+
+const { scrollYProgress } = useScroll();
+const opacity = useTransform(scrollYProgress, [0, 0.5, 1], [1, 0.5, 0]);
+const y = useTransform(scrollYProgress, [0, 1], [0, -200]);
+
+<motion.div style={{ y, opacity }}>视差内容</motion.div>
+```
+
+### 6. 布局动画
+
+**layout prop（位置/尺寸 FLIP 动画）：**
+
+```tsx
+<motion.div
+  layout
+  style={{ width: expanded ? 300 : 100 }}
+  transition={{ layout: { duration: 0.3 } }}
+>
+  {expanded && <motion.p layout="position">详情</motion.p>}
+</motion.div>
+```
+
+**LayoutGroup + layoutId（Tabs underline 经典用例）：**
+
+```tsx
+import { LayoutGroup, motion } from "framer-motion";
+
+<LayoutGroup>
+  {tabs.map((tab, i) => (
+    <button key={tab} onClick={() => onSelect(i)} style={{ position: "relative" }}>
+      {tab}
+      {selected === i && (
+        <motion.div
+          layoutId="underline"
+          style={{
+            position: "absolute", bottom: 0, left: 0, right: 0,
+            height: 2, background: "#3b82f6",
+          }}
+        />
+      )}
+    </button>
+  ))}
+</LayoutGroup>
+```
+
+### 7. useAnimate 命令式序列
+
+```tsx
+import { useAnimate, motion } from "framer-motion";
+
+const [scope, animate] = useAnimate();
+
+const handleClick = async () => {
+  await animate(scope.current, { scale: 1.2 });
+  await animate(scope.current, { rotate: 180 });
+  await animate(scope.current, { scale: 1, rotate: 0 });
+};
+
+<motion.div ref={scope} onClick={handleClick}>点击播放序列</motion.div>
+```
+
+### 8. MotionValue 响应式联动
+
+```tsx
+import { motion, useMotionValue, useTransform } from "framer-motion";
+
+const x = useMotionValue(0);
+const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0]);
+const background = useTransform(x, [-200, 0, 200], ["#ff0000", "#00ff00", "#0000ff"]);
+
+<motion.div drag="x" style={{ x, opacity, background }} />
+```
+
+### 9. 实用模式
+
+**Loading Skeleton：**
+
+```tsx
+<motion.div
+  animate={{ opacity: [0.5, 1, 0.5] }}
+  transition={{ duration: 1.5, repeat: Infinity }}
+  className="bg-gray-200 rounded h-4"
+/>
+```
+
+**Number Counter：**
+
+```tsx
+import { useEffect } from "react";
+import { useSpring, useTransform, motion } from "framer-motion";
+
+const spring = useSpring(0, { stiffness: 100, damping: 30 });
+const display = useTransform(spring, (v) => Math.round(v));
+
+useEffect(() => { spring.set(value); }, [value, spring]);
+
+<motion.span>{display}</motion.span>
+```
+
+{% endraw %}
+
+---
+
+## Transition 速查
+
+| 类型 | 关键参数 | 适用场景 | 示例 |
+|------|---------|---------|------|
+| `spring` | `stiffness`, `damping`, `mass` | 自然弹性效果（默认） | `{ type: "spring", stiffness: 200, damping: 20 }` |
+| `tween` | `duration`, `ease` | 精确时长控制 | `{ type: "tween", duration: 0.3, ease: "easeOut" }` |
+| `inertia` | `velocity`, `power` | 拖拽释放惯性 | `{ type: "inertia", velocity: 200 }` |
+
+**Ease presets：** `linear` · `easeIn` · `easeOut` · `easeInOut` · `circIn` · `circOut` · `backIn` · `backOut` · `anticipate`
+
+**时长原则：** UI 动画 200-500ms；微交互 100-200ms；退场比进场短。
+
+---
+
+## AutoAnimate 用法
+
+### 安装
+
+```bash
+npm install @formkit/auto-animate
+```
+
+### React Hook
+
+```tsx
+import { useAutoAnimate } from "@formkit/auto-animate/react";
+
+function TodoList({ items }: { items: Item[] }) {
+  const [parent] = useAutoAnimate({ duration: 250, easing: "ease-in-out" });
+
+  return (
+    <ul ref={parent}>
+      {items.map((item) => (
+        <li key={item.id}>{item.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### 适用场景
+
+| 场景 | 说明 |
+|------|------|
+| 列表增删排序 | 自动检测 DOM 变更，零配置 |
+| Accordion 展开/折叠 | 子元素显隐时自动过渡 |
+| Toast 通知 | 通知项进出自动动画 |
+| 表单错误提示 | 错误信息出现/消失自动过渡 |
+
+### 适用边界
+
+| 有效 | 无效 |
+|------|------|
+| 直接子元素增删 | 孙元素变更 |
+| 子元素排序 | CSS `display: contents` 的子元素 |
+| 子元素属性变化 | `position: fixed` 的子元素 |
+
+禁用动画：`const [parent, enable] = useAutoAnimate(); enable(false);`
+
+---
+
+## 性能优化
+
+| 要点 | 做法 |
+|------|------|
+| 避免 layout thrashing | 只动画 `transform` + `opacity` |
+| 控制并发 | 同屏 ≤ 3 组动画；stagger 避免 50+ 项同时启动 |
+| 避免重渲染 | `useMotionValue` / `useTransform` 不触发 React 重渲染 |
+| 跳过首次动画 | `initial={false}` |
+| 滚动只触发一次 | `viewport` 设 `once: true, amount: 0.2` |
+
+---

package/miaoda/authz-cli/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: authz-cli
 description: "Use when AI Agent needs to run miaoda-auth-cli commands in sandbox to manage roles, or run `miaoda db sql` in sandbox to manage permission point tables (create, seed, add, update, delete). All commands are executed by the Agent in its sandbox terminal. NOT for writing permission control code — CanRole/@Can coding should use authz-guide skill instead. 触发词：miaoda-auth-cli, authz-cli, 查询角色列表, 模拟角色, 创建角色, 批量创建角色, 权限点位, 权限表, 新增点位, 更新点位, 删除点位, role mock, role list CLI"
+control-by-feature-ab: true
 ---
 
 # authz CLI — 权限管理工具

package/miaoda/charts-skill/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: charts-skill
+description: "shadcn/ui + ReactECharts 图表开发规范。Use when creating or modifying charts/visualizations with ECharts. Covers 18 chart types (Line, Bar, Pie, Radar, Scatter, Heatmap, Sankey, Map, WordCloud, etc.) with strict constraints. 触发词：图表, chart, ECharts, 可视化, 饼图, 柱状图, 折线图, 数据图表, visualization, 甘特图, 词云, 热力图, 数据展示"
+---
+
+## L0 基础配置
+
+- **库**: `import ReactECharts from 'echarts-for-react'` (echarts v6.1.x)
+- **主题**: `theme="ud"`
+- **颜色**: 🚨 只能用 hex（如 `#1890ff`），禁止 hsl/rgb
+- **高度**: ≥300px (`className='h-[300px]'`)
+- **地图**: 需引入 `@/lib/echartsMap`
+- **必须配置**: tooltip.trigger + legend + grid.containLabel（坐标系图表）
+
+### TypeScript 类型定义
+
+编写 ECharts option 时，**必须**为 option 对象补充 `EChartsOption` 类型定义，确保类型安全：
+
+```tsx
+import ReactECharts from 'echarts-for-react';
+import type { EChartsOption } from 'echarts';
+
+const option: EChartsOption = {
+  tooltip: { trigger: 'axis' },
+  legend: { bottom: 0 },
+  grid: { left: '3%', right: '4%', bottom: '20%', containLabel: true },
+  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
+  yAxis: { type: 'value' },
+  series: [{ type: 'line', data: [120, 200, 150] }],
+};
+
+<ReactECharts option={option} theme="ud" className="h-[300px]" />;
+```
+
+**关键点：** 从 `echarts` 导入 `EChartsOption` 类型（使用 `import type`），为 option 变量显式标注类型。复杂场景可按需使用更精确的子类型（如 `LineSeriesOption`、`BarSeriesOption`）。
+
+### Callback 参数类型
+
+`tooltip.formatter` / `label.formatter` / `itemStyle.color` 三类 callback 入参类型不同。自定义参数 shape（如 `(params: { name: string; value: number }) => ...`）会触发 TS2322。直接抄下面范例：
+
+```tsx
+import type { EChartsOption } from 'echarts';
+import type { CallbackDataParams, TopLevelFormatterParams } from 'echarts/types/dist/shared';
+
+const option: EChartsOption = {
+  tooltip: {
+    trigger: 'axis',
+    // axis 触发是数组，item 触发是单对象；先 Array.isArray 分流
+    formatter: (params: TopLevelFormatterParams) => {
+      const list = Array.isArray(params) ? params : [params];
+      return list.map((p) => `${p.name}: ${p.value}`).join('<br/>');
+    },
+  },
+  series: [{
+    type: 'bar',
+    data: [120, 200, 150],
+    label: {
+      show: true,
+      formatter: (p: CallbackDataParams) => `${p.value}`,
+    },
+    itemStyle: {
+      color: (p: CallbackDataParams) => (Number(p.value) > 150 ? '#f00' : '#00f'),
+    },
+  }],
+};
+```
+
+`xAxis.axisLabel.formatter` / `yAxis.axisLabel.formatter` 入参是 `(value, index)`，与上面三类不同，按需查 ECharts 类型，不要套用上面 callback 写法。
+
+### 渐变色用法
+
+需要额外导入并注册 GraphicComponent：
+
+```tsx
+import * as echarts from 'echarts/core';
+import { GraphicComponent } from 'echarts/components';
+echarts.use([GraphicComponent]);
+
+// 线性渐变 (x, y, x2, y2, colorStops)
+new echarts.graphic.LinearGradient(0, 0, 0, 1, [
+  { offset: 0, color: '#fff' },
+  { offset: 1, color: '#000' }
+])
+
+// 径向渐变 (cx, cy, r, colorStops)
+new echarts.graphic.RadialGradient(0.5, 0.5, 0.5, [...colorStops])
+```
+
+### 甘特图用法
+
+🚫 禁止用堆叠柱状图模拟甘特图，必须使用 custom 系列：
+
+```tsx
+const timelineData = [
+  { name: '设计阶段', start: '2024-11-20', end: '2024-11-30', days: 10 },
+  { name: '开发阶段', start: '2024-12-01', end: '2024-12-30', days: 30 },
+];
+
+const option = {
+  tooltip: {
+    trigger: 'item',
+    formatter: (params) => {
+      const item = timelineData[params.dataIndex];
+      return `${item.name}<br/>${item.start} 至 ${item.end}<br/>共 ${item.days} 天`;
+    },
+  },
+  grid: { left: '3%', right: '4%', bottom: '3%', top: '3%', containLabel: true },
+  xAxis: {
+    type: 'time',
+    min: new Date('2024-11-15').getTime(),
+    max: new Date('2025-01-31').getTime(),
+  },
+  yAxis: {
+    type: 'category',
+    data: timelineData.map((item) => item.name),
+  },
+  series: [{
+    type: 'custom',
+    renderItem: (params, api) => {
+      const categoryIndex = api.value(0);
+      const start = api.coord([api.value(1), categoryIndex]);
+      const end = api.coord([api.value(2), categoryIndex]);
+      const height = api.size([0, 1])[1] * 0.5;
+      return {
+        type: 'rect',
+        shape: { x: start[0], y: start[1] - height / 2, width: end[0] - start[0], height },
+        style: { fill: ['#3370eb', '#1bcebf', '#ffc60a'][categoryIndex], radius: 4 },
+      };
+    },
+    encode: { x: [1, 2], y: 0 },
+    data: timelineData.map((item, i) => [i, new Date(item.start).getTime(), new Date(item.end).getTime()]),
+  }],
+};
+```
+
+**关键点：** xAxis 用 `type: 'time'`，yAxis 用 `type: 'category'`，通过 `api.coord()` 计算坐标。
+
+### markPoint 最佳实践
+
+🚫 避免语义重复或位置重叠的 markPoint：
+
+```tsx
+// ❌ 错误：双十一和 max 指向同一个 x 轴位置
+markPoint: {
+  data: [
+    { type: 'max', name: '最大值' },
+    { name: '双十一', coord: ['2024-11-11', 1000] }  // 恰好也是最大值
+  ]
+}
+
+// ✅ 正确：只保留业务语义更强的标注
+markPoint: {
+  data: [
+    { name: '双十一', coord: ['2024-11-11', 1000] }  // 业务含义优先于统计含义
+  ]
+}
+```
+
+**原则：** 当 max/min 与业务事件（如促销日）重合时，只保留业务标注。
+
+### 双 Y 轴组合图零点对齐
+
+🚫 双 Y 轴（正负值混合）时，左右零点必须对齐：
+
+```tsx
+// ❌ 错误：左轴 [0, 100]，右轴 [-50, 50]，零点不对齐
+yAxis: [
+  { type: 'value' },
+  { type: 'value' }
+]
+
+// ✅ 正确：手动计算 min/max 确保零点对齐
+const leftMax = 100, rightMax = 50, rightMin = -50;
+const leftMin = (rightMin / rightMax) * leftMax;  // -100
+
+yAxis: [
+  { type: 'value', min: leftMin, max: leftMax },
+  { type: 'value', min: rightMin, max: rightMax }
+]
+```
+
+**原则：** 两轴的 `|min| / max` 比例必须相同，零点才能对齐。
+
+### 词云用法
+
+WordCloud 非 ECharts 内置图表，系列类型为 `type: 'wordCloud'`。
+
+⚠️ 使用前必须通过**依赖安装工具**安装 `echarts-wordcloud`。
+
+安装后在组件顶部引入（无需解构，导入即注册）：
+
+```tsx
+import 'echarts-wordcloud';
+
+// 系列配置
+series: [{ type: 'wordCloud', data: [...] }]
+```
+
+---
+
+## L1 支持的图表类型
+
+**允许使用的 18 种图表：**
+
+| 类型 | 图表 | 关键约束 |
+| ---- | ---- | -------- |
+| 趋势 | Line, Area, ThemeRiver | Line ≤5 系列 |
+| 比较 | Bar, Radar, Parallel | Radar ≤8 维度且禁止设各 indicator 项的 max，Bar 必须 boundaryGap: true |
+| 占比 | Pie, Treemap, Sunburst | Pie ≤5 类别，禁止 itemStyle，🚨 必须隐藏 label（按 L2 CRITICAL #13 规则） |
+| 分布 | Scatter, Heatmap, Boxplot | Scatter symbolSize ≤20，Heatmap 必须配 visualMap 且 grid.bottom ≥ '20%'（见 L2 CRITICAL #16） |
+| 关系 | Graph, Tree, Sankey | - |
+| 转化 | Funnel | label 必须显示且 `position: 'inside'`，禁止设 color |
+| 金融 | Candlestick | - |
+| 地理 | Map | 需引入 `@/lib/echartsMap` |
+| 词云 | WordCloud | 非内置，需安装 echarts-wordcloud，安装后必须在组件顶部 `import 'echarts-wordcloud'`，见 L0 词云用法 |
+
+**未列出的图表类型不要使用。**
+
+---
+
+## L2 禁止事项
+
+> ⚠️ **违反将导致图表异常**
+
+### 🚨 FATAL
+
+- **颜色格式** - 只能用 hex，禁止 hsl/hsla/rgb/rgba（hover 透明度计算异常）
+
+### 🔴 CRITICAL
+
+> 生成代码后须逐条核对，每一条都不可跳过。
+
+| # | 禁止 | 应该 |
+|---|------|------|
+| 1 | 饼图超过 5 个类别 | 改用横向柱状图 |
+| 2 | 折线图超过 5 个系列 | 拆分图表或添加筛选 |
+| 3 | Radar 的 indicator 各项设置 max 字段 | 禁止在 `radar.indicator` 数组的每一项中设置 `max`，让 ECharts 自动计算各维度范围 |
+| 4 | Radar 多系列使用不同量纲 | 先归一化到相同量纲 |
+| 5 | Bar 的 xAxis 不设 boundaryGap | 必须 `boundaryGap: true` |
+| 6 | Funnel 隐藏 label 或 label 使用非 inside 位置 | 必须 `label: { show: true, position: 'inside' }`，禁止设 color |
+| 7 | 图表高度小于 300px | 最小 `className='h-[300px]'` |
+| 8 | 单图使用超过 8 种颜色 | 分组或聚合数据 |
+| 9 | 饼图添加 itemStyle.border | 移除 itemStyle 配置 |
+| 10 | 折线图连接时间无序的数据点 | 改用 Bar 或 Scatter |
+| 11 | Scatter 的 symbolSize 超过 20 | 控制在 20 以内防止溢出 |
+| 12 | 图表宽高超出容器导致溢出 | 使用相对单位或 `w-full`，禁止固定像素宽度 |
+| 13 | 饼图（`type: 'pie'`）使用 label | 🚨 饼图必须同时关闭两处：`label: { show: false }` + `emphasis: { label: { show: false } }`，改用 tooltip |
+| 14 | label 中设置 `color` 属性 | 🚨 所有 series 的 `label` 中禁止声明 `color`（如 `label: { color: '#333' }` ），颜色由主题自动控制 |
+| 15 | label.formatter 使用字符串模板 | 禁止 `formatter: '{b}: {c}'` 等模板写法（`{a}/{b}/{c}/{d}` 易拼错），如需格式化请用回调函数 `formatter: (params) => ...` |
+| 16 | legend 或 visualMap 与图表绘图区域重叠 | 有 legend 或 visualMap 时统一放底部：`legend: { type: 'scroll', bottom: 0 }`，`visualMap` 设 `orient: 'horizontal', left: 'center', bottom: 0`。坐标系图表（Bar/Line/Scatter/Heatmap 等）设 `grid.bottom` 至少 `'20%'`，x 轴标签较长或旋转时酌情增大；非坐标系图表（Pie/Radar 等）减小 `center` 纵向值上移避让（如 `['50%', '45%']`，不够则继续减小）。🚨 **Heatmap 底部同时存在 visualMap 和 x 轴标签，grid.bottom 酌情增至 `'25%'` 以上** |
+| 17 | 桑基图（Sankey）数据存在环形引用 | Sankey links 必须构成有向无环图（DAG），禁止出现 A→B→…→A 的循环链路，生成数据后须验证无环 |
+| 18 | 柱状图（Bar）正负数据共存时所有柱子使用相同 borderRadius | 按数据正负动态设置：正值圆角在顶部，负值圆角在底部 |
+| 19 | option 对象不写 TypeScript 类型 | 必须 `const option: EChartsOption = { ... }`，从 `echarts` 导入 `EChartsOption`（`import type`），callback 参数类型见 L0 「Callback 参数类型」段 |
+
+### 🟡 SHOULD NOT
+
+| 不建议 | 建议 |
+|--------|------|
+| Radar 超过 8 个维度 | 改用 Parallel 坐标图 |
+| Heatmap 不配置 visualMap | 必须添加 visualMap |
+| legend 与 title 位置重叠 | legend 放 `bottom: 0` |
+| 小尺寸图表（<400px）显示 legend | 隐藏 legend |
+| 用 Bar/堆叠柱状图绘制甘特图 | 使用 custom 系列，见 L0 甘特图用法 |
+| 饼图/环形图 legend 放侧面 | legend 放顶部或底部，避免与图表重叠 |