| name | feishu-cli-htmlbox |
| description | 在飞书云文档里画**会动的图 / 可交互图表 / 数据大屏**——妙笔BOX 是飞书文档里唯一能真实跑 CSS/JS 的载体 （iframe 沙箱）。能画：ECharts 全家桶（折线/柱/饼/雷达/散点/热力/桑基/漏斗/仪表/K线/箱线/平行坐标/旭日/treemap/ 力导向关系图/时序/甘特）、真实地图与经纬度飞线、echarts-gl 3D（map3D/3D柱/3D散点/3D曲面）、Three.js 真 3D 场景、 词云、水球、纯 CSS 动画、Canvas 粒子、SVG 矢量动画、KPI 滚动大屏。 当用户要"在飞书文档里画图/做动画/能动的图/可交互图表/数据大屏/Dashboard/折线图/柱状图/地图/飞线图/3D图/ 关系图/流程动画/ECharts/可视化"，或要做**能调 AI / 读写多维表 / 持久化状态 / 拿用户身份的交互式文档小程序**， 或提到"妙笔BOX/HTML 小组件/让飞书文档里的图动起来/嵌入网页到飞书文档/window.magic"时， **必须用本技能**。注意：要"动"只能用妙笔BOX；画板（feishu-cli-board）的 SVG 节点会被服务端栅格化成静态图、不会动。 |
| argument-hint | <document_id> [block_id] |
| user-invocable | true |
| allowed-tools | Bash(feishu-cli doc:*), Bash(feishu-cli perm:*), Bash(feishu-cli msg:*), Bash(agent-browser:*), Bash(playwright-cli:*), Read, Write |
在飞书文档里画会动的图（妙笔BOX）
你拿到「在飞书文档里画一个 X 图 / 做个能动的可视化 / 做数据大屏」这类任务时用本技能。
妙笔BOX 是飞书文档里唯一能真实执行 CSS/JS 的载体（iframe 沙箱），所以一切动画、ECharts、Three.js、Canvas
都能动。流程就三件事：照配方写一页自包含 HTML → 本地浏览器验证它真渲染 → 用 doc htmlbox 落库。
要"动"只能用妙笔BOX。画板（feishu-cli-board）的 SVG 节点会被飞书服务端栅格化成静态图、永远不动；
代价是妙笔BOX 是整体 iframe，内部元素不能像画板节点那样在飞书里单独点选编辑（鱼与熊掌不可兼得）。
第一步永远是选型：你要画什么 → 用什么 → 配方在哪
先在下表对号入座，再去对应 reference 抄骨架 + 配方。不要从零手搓 ECharts option——配方都验证过、能直接 create。
| 你要画的图 | 引擎 / 方案 | 配方位置 |
|---|
| 折线 / 面积 / 柱状 / 堆叠柱 / 柱状竞赛 BarRace / 玫瑰饼 / 雷达 | ECharts（换 series.type） | references/gallery.md › 数据对比 |
| 散点气泡 / 热力 / 日历热力 / 箱线 / K线蜡烛 / 平行坐标 | ECharts | references/gallery.md › 分布统计 |
| 饼 / 漏斗 / 桑基 Sankey / 主题河流 / 仪表盘 gauge / 水球 liquidFill | ECharts(+扩展) | references/gallery.md › 构成流向 |
| 力导向关系图（可拖拽）/ 组织树 tree / 旭日 sunburst / 矩形树图 treemap | ECharts | references/gallery.md › 关系层级 |
| 时序 / 状态机 / 甘特 / CI流水线 / 看板流动 | ECharts custom / CSS | references/gallery.md › 流程时序 |
| 词云 wordCloud | echarts-wordcloud | references/gallery.md › 构成流向 |
| 纯 CSS 动画（旋转/脉动/进度条/打字机/变色） | CSS @keyframes（最稳，不依赖外网） | references/gallery.md › 创意动画 |
| 粒子流 / 星空 / 自绘动画 | Canvas + requestAnimationFrame | references/gallery.md › 创意动画 |
| 矢量路径自绘 / morphing / 维恩图 | 内联 <svg> + SMIL/CSS | references/gallery.md › 创意动画 |
| KPI 数据大屏（数字滚动 + 迷你趋势） | HTML/CSS/JS | references/gallery.md › 创意动画 |
| 真实地图着色 choropleth / 经纬度 geo 飞线 | ECharts geo + registerMap | references/geo-3d.md |
| 3D 立体地图 map3D / 3D 柱 / 3D 散点 / 3D 曲面 | echarts-gl | references/geo-3d.md |
| 真 3D 场景（旋转星球 / GPU 粒子 / 几何体） | Three.js（WebGL） | references/geo-3d.md |
不确定用哪个？默认 ECharts（覆盖绝大多数统计/关系图）；只有要真实地理、可旋转 3D、或 ECharts 给不出的自由视觉，才上 geo-3d / Canvas / SVG。
不止画图：window.magic 文档小程序运行时
妙笔BOX 的 iframe 里，飞书注入了一个 window.magic 运行时——OpenAPI 建的块也有（已实测，注入认 component_type_id 不认来源）。所以它不只是画图，还能做会读数据、能交互、有状态的文档小程序。当任务需要下面任一项，看 references/window-magic.md：
| 需求 | 能力 |
|---|
| 当前用户身份（名字 / open_id，用于个性化或写人员字段） | window.magic.user |
| 读当前文档全文 / 元信息（喂 AI、统计、生成目录） | getDocAsMarkdown / getPageMeta |
| 持久化状态（计数器 / 抽奖 / 祝福墙 / 已读列表） | window.magic.redis / store（禁 localStorage，见 pitfalls） |
| 图表接真实数据源（活数据 Dashboard） | base_records_search 拉多维表 → ECharts |
| 文档内调 AI（摘要 / 问答 / 文案，无需自带 key） | window.magic.ai（豆包） |
⚠ window.magic 只在飞书文档端注入，本地 file:// 预览必为 undefined——所有用法都要判存兜底，否则本地白屏。
绘制工作流（每张图都照做）
- 照配方写一页自包含 HTML 到
/tmp/x.html。从 gallery.md / geo-3d.md 取对应骨架 + 配方；统一深色背景、容器固定高度（如 #chart{height:360px}）、width:100%、监听 resize 调 chart.resize()。
- 本地浏览器验证它真渲染、真在动——这步不能跳。iframe 里任何顶层 JS 错误会让整张图白屏且不报错（未捕获异常走 pageerror、不进 console），光读代码看不出来。直接跑封装好的验证脚本——它用全新浏览器 session 打开页面、抓 page error / console、数 canvas/svg 节点、截图，并据此给通过/未过判定：
scripts/verify.sh /tmp/x.html
退出码 0 才算初步通过；但「画对没画对、在不在动」机器判不了，务必再肉眼看它打印的那张截图。排查白屏见 references/pitfalls.md。
- 落库：
feishu-cli doc htmlbox create <doc_id> --html-file /tmp/x.html。
- 改图：
feishu-cli doc htmlbox update <doc_id> <block_id> --html-file /tmp/x2.html（block_id 会变，后续用返回的 new_block_id）。
命令速记
| 操作 | 命令 |
|---|
| 插入 | feishu-cli doc htmlbox create <doc_id> --html-file x.html（--index 控位置，默认末尾） |
| 替换 | feishu-cli doc htmlbox update <doc_id> <block_id> --html-file x2.html（返回 new_block_id） |
| 读回 | feishu-cli doc htmlbox get <doc_id> <block_id> --raw > cur.html |
| 删除 | feishu-cli doc htmlbox delete <doc_id> <block_id> |
输入也支持 --html '<...>' 或 --html-file -（stdin）。四个命令都支持 --format / --jq；写类 create/update/delete 另有 --dry-run 预览和 -o 写文件，get 用 --raw 出纯 HTML（get 无 --dry-run/-o）。默认 Bot 身份（操作 feishu-cli 自建文档无需登录）；改他人/手建文档传 --user-access-token。
画图必避的 5 个坑（详见 references/pitfalls.md）
- 白屏不报错 → 落库前本地浏览器必验（见工作流第 2 步）。这是最高频的坑。
- CDN
<script> 是异步的 → 用前轮询等库就绪（if(typeof echarts==='undefined') return setTimeout(boot,150)），每个 <script src> 加 onerror 兜底。飞书沙箱实测能联 jsdelivr。
- 真实地图 → ECharts 5 不带地图数据，直接
type:'map' 空白；先 fetch GeoJSON（借 echarts@4.9.0/map/json/china.json）再 registerMap。
- 极坐标 polar bar 不按值上色 →
visualMap 对它无效，给每个 data 项显式 itemStyle.color。
- 批量画多张 → 每次
create 之间 sleep 0.5s，否则触发飞书写限流 99991400；多图配标题用 doc content-update --mode append --markdown "## 标题" 与 create 交替追加。
创建后交付（按需）
文档要交给用户时：按 feishu-cli-write 的 owner 授权流程（perm add full_access + 视配置 perm transfer-owner），并按全局规则发一张飞书卡片通知。
参考文档与脚本
scripts/verify.sh <html> [等待秒数] — 落库前验证脚本（工作流第 2 步用它）：全新 session 打开 → 抓 page error/console → 数 canvas/svg → 截图 → 给通过判定；退出码 0 才算初步通过，仍须肉眼看截图references/gallery.md — 主力配方库：4 种通用骨架（ECharts/Canvas/Three.js/SVG-CSS）+ 按图表类型的可直接用配方references/geo-3d.md — 地图 / echarts-gl 3D / Three.js 的完整可跑模板（这几类有 CDN/registerMap/坐标系/着色坑）references/window-magic.md — 文档小程序运行时：window.magic 能力配方（用户身份 / 读文档 / 持久化 / 多维表 / AI），含判存兜底范式与活数据 Dashboard、文档内 AI 卡等组合配方references/pitfalls.md — 画图避坑与白屏排查（来自真实创建一篇 47 图大文档）references/mechanism.md — 块机制 / 身份 / update 速查（只在排查 token、组件 ID、update 行为时才需要）
