PPTClaw 技能参考文档

PPTClaw 是一款本地优先的演示文稿编辑器。幻灯片组（deck）以磁盘上的 JSON 文件形式存在——您直接创建和编辑这些文件，编辑器通过 WebSocket 实时同步变更。

环境准备

若尚未安装 pptclaw，请全局安装：

pnpm add -g pptclaw    # 或：npm install -g pptclaw

幻灯片组格式

一个幻灯片组是一个具有如下结构的文件夹：

my-deck/
├── manifest.json           # 标题、主题、视口尺寸、幻灯片顺序
├── slides/
│   ├── 001-abc123.json     # 幻灯片文件：-.json
│   ├── 002-def456.json
│   └── ...
└── assets/                 # 图像及其他媒体资源
    ├── hero.jpg
    └── ...

manifest.json

{
  "title": "My Presentation",
  "format": "1",
  "viewport": { "width": 1920, "ratio": 0.5625 },
  "theme": {
    "primary": "#2563eb",
    "secondary": "#7c3aed",
    "tx1": "#1e293b",
    "accents": ["#2563eb", "#7c3aed", "#5b9bd5", "#ff6b6b", "#4ecdc4", "#95e1d3"],
    "fontHeading": "YouSheBiaoTiHei",
    "fontBody": "Microsoft YaHei"
  }
}

• viewport.ratio 表示高宽比（height/width），0.5625 对应 16:9（即 1920×1080）
• theme.accents 是一个包含 6 种颜色的数组，按顺序用于图表系列、信息图元素等

幻灯片 JSON

每个幻灯片文件包含一个幻灯片对象：

{
  "id": "abc123",
  "elements": [ /* PPTElement 对象 */ ],
  "background": { "type": "solid", "color": "#ffffff" },
  "remark": "Speaker notes text",
  "type": "content"
}

• type：取值为 "cover"、"contents"、"transition"、"content" 或 "end"
• elements：类型化元素对象数组（详见下文）
• background：可选，缺省为白色
• remark：可选的演讲者备注（纯文本）

画布

• 尺寸：1920 × 1080 像素
• 坐标原点：左上角（0, 0）
• 所有位置与尺寸值均以像素（px）为单位

基础元素字段

所有元素共享以下字段：

id: string        // 唯一元素 ID
left: number      // X 坐标（距左侧边缘的像素数）
top: number       // Y 坐标（距顶部边缘的像素数）
width: number     // 元素宽度（px）
height: number    // 元素高度（px）
rotate: number    // 旋转角度（度），默认为 0
lock?: boolean    // 锁定元素，禁止编辑
groupId?: string  // 具有相同 groupId 的元素构成一组
name?: string     // 显示名称
link?: { type: 'web' | 'slide', target: string }

例外：line 类型元素不包含 height 和 rotate 字段——它们使用起点/终点坐标代替。

主题色

为保持与幻灯片组主题一致，请使用 CSS 变量引用而非硬编码十六进制值：

明度变体 —— 在任意主题变量后添加后缀：

• var(--primary-plus-50) —— 更浅（+50 明度）
• var(--primary-minus-25) —— 更深（−25 明度）
• 适用于所有主题色：secondary、tx1、accent1–6

主题字体：

• var(--font-heading) —— 用于标题、副标题、页眉
• var(--font-body) —— 用于正文、内容、列表项

常用样式类型

描边（outline）

{ style?: 'solid' | 'dashed' | 'dotted', width?: number, color?: string }

阴影（shadow）

{ offset: number, angle: number, blur: number, color: string, alpha: number }
// offset：0–100；angle：0–359；blur：0–100（pt）；alpha：0–100（0 = 完全透明）

渐变（gradient）

{
  type: 'linear' | 'radial',
  colors: [{ pos: number, color: string, alpha?: number }],  // pos：0–100%
  rotate?: number,
  radialStart?: 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
}

文本元素（内联参考）

文本是最常见的元素类型，因此其完整 Schema 在此处列出。其他元素类型的完整定义，请运行 pptclaw element-docs 查询。

interface PPTTextElement extends PPTBaseElement {
  type: 'text'
  content: string           // ProseMirror HTML
  defaultColor: string      // 回退颜色（可被内联 HTML 样式覆盖）
  fill?: string             // 背景填充色
  lineHeight?: number       // 行高倍率，默认 1.5
  wordSpace?: number        // 字母间距，默认 0
  paragraphSpace?: number   // 段落间距（px），默认 5
  opacity?: number          // 0–1，默认 1
  vertical?: boolean        // 垂直排版模式
  outline?: Outline
  shadow?: Shadow
  textType?: 'title' | 'subtitle' | 'content' | 'item' | 'itemTitle' | 'notes' | 'header' | 'footer'
}

HTML 内容格式

content 字段采用带内联样式的 ProseMirror HTML：

Title Text
Body paragraph

支持的内联样式： font-size（px）、color、font-weight、font-style、text-decoration、text-align、font-family。

字号规则

HTML 中的字号单位为 px，其数值等于 PowerPoint 点值（pt）的 2 倍。这一点至关重要，因为演示文稿在大屏幕上展示——过小的文字将无法辨识。

常见错误：误用网页尺度字号（如 14px、16px、18px）——这些字号对演示文稿而言过小。

幻灯片背景

{
  "background": {
    "type": "solid",
    "color": "var(--primary-plus-80)"
  }
}

背景类型包括："solid"（需指定 color）或 "gradient"（需指定 gradient 对象）。请直接在幻灯片对象上设置背景，而非通过创建满画布形状实现。

布局规范

标准内容页

• 标题：left = 80，top = 80，font-size = 72px，加粗
• 内容区：left = 80，top = 200，width = 1760，height = 800
• 大型元素（图表、信息图、表格）单独展示时应填满整个内容区

水平居中

使元素水平居中： left = (1920 - width) / 2

注意：left: 960 并非居中——它将元素左边缘置于画布中点，导致整体右偏。

布局自查清单

在最终确认元素位置前，请验证以下各项：

1. 无重叠 —— 元素矩形区域未发生意外交叠
2. 文字可读 —— 所有字号 ≥ 32px，内容完全容纳于元素边界内
3. 边缘留白 —— 元素距画布边缘 ≥ 60px
4. 元素间距 —— 元素之间间隙 ≥ 20px
5. 风格统一 —— 所有幻灯片统一使用 20px 卡片间距与 10px 边框圆角

元素类型

除上述已详述的文本元素外，PPTClaw 还支持以下元素类型：

获取任意类型的完整 Schema：

pptclaw element-docs            # 例如：pptclaw element-docs image
pptclaw element-docs chart table      # 同时查询多个类型
pptclaw element-docs                  # 列出所有支持的类型

CLI 参考文档

所有命令均支持 -p, --port 参数（默认端口：3059）。

pptclaw serve [deck]

以后台守护进程方式启动编辑器服务。可选：立即打开指定幻灯片组。

pptclaw serve                    # 启动服务
pptclaw serve ./my-deck          # 启动并打开幻灯片组
pptclaw serve --port 4000        # 自定义端口

退出码：成功返回 0；服务启动失败返回 1。

pptclaw open

在已运行的编辑器中打开幻灯片组文件夹。

pptclaw open ./my-deck
pptclaw open ./my-deck --session custom-id

输出：会话 ID、路径、幻灯片数量。

pptclaw validate

校验幻灯片组文件夹结构与内容。返回包含 valid、errors、warnings 字段的 JSON。

pptclaw validate ./my-deck

退出码：有效返回 0；发现错误返回 1。需服务正在运行。

pptclaw list-decks

列出当前活跃会话（已打开的幻灯片组）及其幻灯片数量。

pptclaw list-decks

pptclaw status

以 JSON 格式显示服务器状态、认证状态及活跃会话。

pptclaw init

将 PPTClaw 技能文件复制至当前目录下的 .claude/skills/pptclaw/SKILL.md。

pptclaw element-docs [type...]

打印指定元素类型的文档说明。

pptclaw element-docs              # 列出所有可用类型
pptclaw element-docs image        # 打印 image 元素文档
pptclaw element-docs chart table  # 打印多个类型文档

pptclaw search-images

搜索 Unsplash 图像。返回包含 id、description、dimensions 字段的 JSON 数组。

pptclaw download-image --deck

将图像下载至幻灯片组的 assets 文件夹。

工作流

新建幻灯片组

1. 创建文件夹结构：

   mkdir -p my-deck/slides my-deck/assets
   

2. 编写 manifest.json，填写标题、主题与视口配置

3. 在 slides/ 目录中创建幻灯片文件（编号格式：001-.json、002-.json，依此类推）

4. 执行校验：

   pptclaw validate ./my-deck
   

5. 在编辑器中打开：

   pptclaw serve ./my-deck
   

编辑现有幻灯片

1. 读取幻灯片 JSON 文件
2. 修改 elements 数组——新增、更新或删除元素
3. 将文件写回磁盘——编辑器通过文件监听器自动捕获变更
4. 如有需要，执行校验：pptclaw validate ./my-deck

添加图像

1. 搜索图像：

   pptclaw search-images "mountain landscape"
   

2. 下载至幻灯片组 assets 目录：

   pptclaw download-image  --deck ./my-deck
   

3. 在幻灯片 JSON 中，通过 imageSource 字段在 image 元素上引用该图像