feishu-cli-htmlbox

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: [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        # 地图/CDN 重的加等待秒数：scripts/verify.sh /tmp/x.html 5
```
退出码 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 行为时才需要）