AGENT SKILL

html-spec

转换 HTML 为 PPT 元素——把 HTML 转成可编辑 PPT 元素的契约:白名单决定可编辑范围,data-tabslide-rasterize 兜底复杂视觉。

License 许可
AGPL-3.0
所属仓库
tabtin-ai/TabTin
最近更新
2026-10-08
Stars
★ 454
Forks
115

01 前言 Front Matter

name
html-spec
metadata
{ "tabtin": { "category": "doc", "displayName": "TabSlide HTML 生成规范", "autoActivateFor": [ "tabslide" ] }, "version": "0.4.0" }
description
转换 HTML 为 PPT 元素——把 HTML 转成可编辑 PPT 元素的契约:白名单决定可编辑范围,data-tabslide-rasterize 兜底复杂视觉。

02 资源文件 2

03 SKILL.md 正文

TabSlide HTML 生成规范

TabSlide 的 HTML 转页能力(tabtin slide create --html / tabtin slide add-page --html;整份覆盖才用 tabtin slide generate --replace)会把你写的 HTML 转成可编辑的 PPTElement。这份文档定义两件事:

  1. 哪些 HTML 模式我们能完整解析为可编辑 PPTElement(用户能拖、能改文字、能改色)
  2. 超出白名单的视觉怎么用 data-tabslide-rasterize 兜底(截图为 image,视觉对但整块拖)

一、设计哲学:白名单 + SVG/栅格化兜底

我们不是 Chrome,只能识别 HTML 表现力的一个子集。约定如下:

  • 白名单内 → 可编辑 PPTElement(text / shape / image / line / table / chart)
  • 白名单外的矢量视觉 → 用 <svg> 画(转成清晰图片,视觉稳定)
  • 白名单外的复杂视觉 → 用 <div data-tabslide-rasterize>...</div> 主动包起来,整块截图为 image

这是契约:你写白名单内的内容,我保证可编辑;你写复杂装饰,主动标 rasterize,我保证视觉对。不要写"差不多能识别但又拿不准"的东西 —— 拿不准就 rasterize,宁可降级一块为图片,也别让整页错位。

⚠️ HTML 能做的样式,PPT 不一定能还原。 PPT 的元素模型比 CSS 窄得多——很多纯 CSS 装饰(径向渐变、滤镜、毛玻璃、裁剪形状、异形/曲线、复杂阴影、伪元素画的图形、CSS 画的图标/箭头/连接线等)在转成 PPTElement 时会丢失或走样。这类"用 CSS 硬凑的图形"应当改用 <svg> 画:SVG 会被转成一张清晰的图片元素,视觉在任何机器 / 导出的 .pptx 里都稳定一致,不受 CSS→PPT 能力差异影响。

原则:能进白名单的用白名单(可编辑);做不进白名单的矢量图形优先用 <svg>(视觉稳定);再不行才 data-tabslide-rasterize 截图兜底。 代价是 SVG / 栅格化产物是整块图片,不能在编辑器里改文字改色——所以正文、标题、可编辑数据不要塞进 SVG。

二、画布容器(必须)

每页用一个 .ppt-slide div 包裹,宽高固定 1280×720:

<div class="ppt-slide" style="width:1280px;height:720px;position:relative;overflow:hidden">
  <!-- 页面内容 -->
</div>

多页幻灯片在 <body> 中依次排列多个 .ppt-slide。

三、可用资源(自动注入)

  • 样式:只用原生 CSS — 用 <style> 写 class 或元素上写 style="..."。不提供 Tailwind,不要写 class="bg-blue-500 p-8" / bg-[#2563EB] 这类工具类(不会生效)。也不要用与常见框架同名的 class(如 list-item/grid/flex/block/table/hidden),用语义化命名(如 .bullet-row)。
  • Font Awesome 6 — <i class="fa-solid fa-...">(⚠️ 必须 rasterize 才能出现在 PPT 里,详见 §五)
  • ECharts — echarts.init(dom).setOption({...})(图表容器必须同时声明确定的 width 和 height;不要只依赖 flex:1 或百分比高度)
  • Chart.js — new Chart(ctx, {...})
  • MathJax — $$E=mc^2$$
  • 字体 — Inter(英文)、Noto Sans SC(中文),自动应用

四、可编辑白名单(推荐写法)

8 类可编辑元素(文字 / 简单形状 / 线段 / 线性渐变 / 图片 / SVG 图标 / 图表 / 表格)的逐项推荐写法与示例见 references/editable-whitelist.md。

真实图片必须内嵌数据,别只贴外链(重要):把网页 / 素材里的真实图片(截图、产品图、logo)放进 PPT 时,先把图下载到本地,再读成 data:image/(png|jpeg|gif|webp|bmp);base64,... 写进 <img src>——这样图数据会落到 slide 自己的存储、长期不掉。<img src="https://第三方..."> 是原样引用第三方链接,会过期 / 防盗链 / 离线掉图。绝不要用文字 / 色块假装图片。 细节见 references/editable-whitelist.md §4.5。

资源导航(按需读取)

  • references/editable-whitelist.md:当你要判断某个元素是否可编辑、以及该怎么写成稳定白名单形态时读取。
  • examples/page-templates.md:仅在需要快速起草整页结构或复用模板时读取;示例用于套版,不默认整份注入上下文。

五、栅格化兜底(⚠️ 写法)

5.1 何时用

主动选择 rasterize 的场景:

视觉效果 为什么走 rasterize
Font Awesome 图标(<i class="fa-*">) dom_extractor 会把 FA 元素 display:none 隐藏,直接写不会出现在 PPT 里
径向渐变(radial-gradient) 仅支持 linear
毛玻璃(backdrop-filter: blur) PPT 无对应能力
裁剪形状(clip-path、mask-image) PPT 无对应能力
混合模式(mix-blend-mode) PPT 无对应能力
复杂 filter(drop-shadow、多个 filter 叠加) 转换不稳定
复杂 SVG(含动画 / 滤镜 / 渐变填充) 序列化后可能视觉退化
拿不准能不能识别的复杂视觉 主动声明意图,避免错位

5.2 怎么写

把要整块截图的内容包在 <div data-tabslide-rasterize> 里:

<!-- Font Awesome 图标兜底(极其常用) -->
<div data-tabslide-rasterize
     style="position:absolute;top:80px;left:80px;width:48px;height:48px;
            display:flex;align-items:center;justify-content:center;
            color:#2563EB;font-size:32px">
  <i class="fa-solid fa-chart-line"></i>
</div>

<!-- 复杂 SVG 装饰兜底 -->
<div data-tabslide-rasterize
     style="position:absolute;top:80px;left:80px;width:200px;height:60px">
  <svg viewBox="0 0 200 60">
    <defs>
      <linearGradient id="g">
        <stop offset="0" stop-color="#2563EB"/>
        <stop offset="1" stop-color="#7C3AED"/>
      </linearGradient>
    </defs>
    <path d="M0,30 Q50,0 100,30 T200,30" stroke="url(#g)" stroke-width="3" fill="none"/>
  </svg>
</div>

<!-- 径向渐变兜底 -->
<div data-tabslide-rasterize
     style="width:300px;height:300px;border-radius:50%;
            background:radial-gradient(circle at 30% 30%, #FFD700, #FF8C00)"></div>

dom_extractor 看到 data-tabslide-rasterize 属性后:

  1. 截图整个 div(含所有子元素,@2x 分辨率)
  2. 上传到 OSS
  3. 当一个 image PPTElement 输出
  4. 子元素不再被其他识别函数提取(不会有"图片 + 文字"双重提取)

5.3 规则

  • ✅ rasterize 区域必须有明确的 width / height(截图 clip 来自 getBoundingClientRect,无尺寸截不出来)
  • ✅ 在编辑器里 rasterize 出的 image 只能整块拖动、缩放,不能改文字 / 颜色
  • ❌ 别用 rasterize 包裹本来就能识别的简单卡片 / 文字 —— 浪费,且失去可编辑性
  • ❌ rasterize 内不要再嵌套 rasterize(只截最外层)

六、明确禁止 / 不识别

以下用法即使写了也会被忽略或导致异常 —— 看到下表的视觉需求第一反应应该是走 rasterize:

用法 后果
<i class="fa-*"> 不包 rasterize 图标被 display:none 隐藏,PPT 里看不到
radial-gradient 不包 rasterize 形状仍输出但渐变丢失(保留 bg / 边框)
backdrop-filter 不包 rasterize 毛玻璃丢失
clip-path / mask-image / mix-blend-mode 不包 rasterize 视觉丢失
<p> / <h*> 上写 background / border / box-shadow 文字识别成功,但背景边框丢失
position: fixed 坐标计算异常(相对视口而非 .ppt-slide)
CSS animation / transition / @keyframes PPT 不支持,渲染期被忽略
<iframe> <video> <audio> 不识别(slide generate 不输出此类元素)
<ul> / <ol> 嵌套结构(多层) 识别不稳;改用 <div> 排列

七、配色与样式约定

7.1 颜色写法(任选其一,能识别)

  • ✅ CSS 变量:var(--slide-primary)(保证全局一致,推荐多页演示统一用)
  • ✅ 直接写 hex / rgb / rgba:style="background:#2563EB" / style="color:rgba(255,255,255,0.7)"
  • ✅ 自定义 class 里写原生 CSS:.title{color:#1F2937}

优先使用 CSS 变量 —— 主题切换时统一更新。多页演示混着用容易出现某页跳色。不要用 Tailwind 工具类(bg-blue-500/bg-[#2563EB] 等不会生效)。

7.2 CSS 变量速查

变量 默认值 用途
--slide-primary #2563EB 主色
--slide-accent #DC2626 强调色
--slide-text / --slide-text-secondary #1F2937 / #64748B 正文 / 辅助文字
--slide-bg / --slide-bg-subtle #FFFFFF / #F8FAFC 背景白 / 浅底
--slide-border #E2E8F0 边框色
--slide-success/warning/error/info 绿/橙/红/蓝 状态色
--slide-blue/teal/green/orange/red/purple — 六色板(图表 / 卡片配色)
--slide-radius-sm/md/lg/xl/full 8 / 12 / 16 / 24 / 9999 px 圆角
--slide-shadow-sm/md/lg/xl — 阴影

7.3 组件 class 速查

class 说明
.slide-cover 居中封面页(flex column center)
.slide-content 标准内容页(纵向 + 60/80 px 内边距)
.slide-split / .slide-split-40-60 1:1 / 2:3 分栏
.slide-grid-2/3/4 等宽网格
.slide-title / .slide-title-lg / .slide-subtitle 48 / 64 / 28 px
.slide-heading / .slide-body / .slide-caption / .slide-label 36 / 20 / 14 / 14 px
.slide-number 56 px 数字高亮
.slide-card / .slide-card-bordered / .slide-card-accent / .slide-card-filled 卡片变体
.slide-card-glass ⚠️ 含 backdrop-filter,毛玻璃效果必须 rasterize
.slide-kpi(内含 .kpi-label / .kpi-value / .kpi-change.up/.down) KPI 指标卡
.slide-table / .slide-table-minimal 表格主题
.slide-badge / -primary/success/warning/error 标签(不要塞 FA 图标)
.slide-list 带圆点列表(CSS ::before 实现,识别为 div 文字)
.slide-divider / .slide-divider-accent / .slide-accent-bar 装饰线 / 条
.slide-step-number 数字圆圈(识别为 shape + text)
.slide-timeline + .slide-timeline-item 时间线

八、页面模板

6 套可直接套用的整页 HTML 模板(封面 / KPI 仪表盘 / 图表页 / 对比分析 / 表格页 / 总结页)见 examples/page-templates.md。

九、自查清单(生成前过一遍)

  • [ ] 复杂装饰 / 图标 / 示意图 / 渐变描边优先用内联 <svg> 矢量,而不是 CSS 硬凑再 rasterize
  • [ ] 自定义 class 没有与 Tailwind 工具类同名(list-item / grid / flex / block / hidden / table / container 等)
  • [ ] 每个 <i class="fa-*"> 都包在 data-tabslide-rasterize 容器内
  • [ ] 没有用到 radial-gradient / backdrop-filter / clip-path / mask-image / mix-blend-mode(除非包 rasterize)
  • [ ] <p> / <h*> 上没有 background / border / box-shadow(搬到外层 div)
  • [ ] 渐变只用 linear-gradient,stop 位置和颜色清晰
  • [ ] rasterize 容器都有明确的 width / height
  • [ ] 没有 CSS animation / transition / @keyframes
  • [ ] 元素不超出 1280×720 边界(遵守 design-guide 容量预算;slide render 对 html_overflow 默认拒绝导出)
  • [ ] 图表用 ECharts / Chart.js canvas,不是手画的 div 柱状图
  • [ ] 每个图表容器都有非零的显式 width / height;初始化放在布局完成后,并在需要时调用 chart.resize()
  • [ ] 表格用 <table> 而不是 div 网格模拟
  • [ ] 真实图片走 data:image/*;base64 内嵌(不是只贴第三方外链,更不是用文字/色块假装)

04 同仓库更多 Skills

tabtin-ai
tabtin-ai/TabTin

tabtracker

管理自动化任务——创建、列出、暂停、恢复、立即触发(产品模块名「自动化」, 具体条目称「自动化任务」;CLI 命令仍为 tabtin tracker)。当用户表达"派活"意图时使用: 关键词包括"帮我..."、"以后..."、"每天..."、"工作日..."、 "提醒我..."、"定时..."、"每周..."。区分一次性指令(直接执行)和长期任务(创建 自动化任务,由调度器在指定时间唤起 Agent)。

★ 454
tabtin-ai
tabtin-ai/TabTin

tabtin-project

在 Project Task 执行会话中工作:先读取当前任务工作面,再优先修改既有中间产物。 当系统上下文表明当前会话是 Project Task,或用户要求继续修改过程中的中间产物时使用。

★ 454
tabtin-ai
tabtin-ai/TabTin

skill-market

管理 Skill 生命周期——列出已装、看详情、搜索市场、 安装、卸载、启用、禁用、更新。当用户表达"装个技能 / 卸载技能 / 看看有什么技能 / 启用禁用技能"意图时使用。

★ 454
tabtin-ai
tabtin-ai/TabTin

tabtin-widget

渲染可视化组件——用 show_widget 编译 SVG / HTML(no-script) / Mermaid 图做自由可视化。内容能落 present_to_user 4 类 kind → 不用 widget;长期可编辑产物 → TabData/ TabDoc/TabSlide。

★ 454
tabtin-ai
tabtin-ai/TabTin

resource-link

插入资源链接——在 chat 文字流里给资源链接,markdown link 形态 [显示文本](tabtin://resource/<type>/<id>?hint=<carrierApp>), 用户点击直接在 Space 内打开。行业格式(http/https/ file/mailto)也兼容;不要写 file:// 让用户自己复制粘贴。

★ 454
tabtin-ai
tabtin-ai/TabTin

mcp-operations

操作本机 MCP 连接——通过 `tabtin mcp` CLI 查看当前 Space 已挂载的本机 MCP servers、tools/resources/ prompts,并用 `mcp_call_tool` 调用指定 MCP tool。 用户提到"使用 Playwright MCP""调用本机安装的 MCP 工具""读取某个 MCP resource""获取某个 MCP prompt"时激活。

★ 454