deckkit-ppt-replica

DeckKit PPT 复刻

在使用 DeckKit 将源幻灯片图像重建为可重复使用且大部分可编辑的 PPTX 时，请使用此技能。

执行规范

此工作流会逐步审查。不要为了加快速度而跳过检查点、批量处理后续区域，或假设用户只会检查最终 PPTX。请将每个 bbox、区域渲染、图标并排对比结果和 qa.md 都视为用户可见的审查证据。请投入精力确保 bbox 准确、符合规则、完成当前步骤的既定目标、进行语义比较，并保证每一步的输出质量。如果未通过某个关卡，请停止、修正问题，或在继续之前记录验证缺口。

不可妥协的审查模式

此技能规定的是经过审查的重建工作流，而非尽力而为的 PPT 生成流程。如果 Agent 在所需关卡证据齐备之前，就优先生成完整 PPTX，则本次运行视为失败。

失败情形：

• 当前区域关卡通过之前，为后续区域编写 SVG 资源。
• 当前区域关卡通过之前，编写、启用或生成后续区域的 DeckKit 绘图代码。
• 之前所有区域关卡通过之前，生成完整幻灯片 PPTX。
• 在完整幻灯片实现完成后，才创建区域 QA。
• 在图标对应区域成为当前处理区域之前，就通过一次脚本运行批量编写所有图标/SVG。
• 未明确报告 PASS/缺口并等待用户确认，就继续处理下一个区域。

每个区域关卡通过后，都要停止并请求用户确认，然后再继续。不要将用户沉默或工作进度视为同意开始下一个区域。短期目标始终是“完成当前关卡并停止”，而不是“完成整套幻灯片”。

必需参考资料

开始实现之前，将 SKILL_DIR 确定为包含此 SKILL.md 的目录，然后阅读：

• $SKILL_DIR/reference/deckkit-capabilities.md，了解 DeckKit API 的能力、路由名称、图像辅助工具和实现注意事项。

使用此 SKILL.md 中嵌入的 bbox schema 作为 initial-bbox.json 的事实来源。无需依赖特定示例的 LESSONS-LEARNED.md；持久有效的经验应记录在此技能中。在维护此仓库本身时，可以将 docs/bbox-route-aware-segmentation-proposal.md、docs/deckkit-llm-capabilities.md 或 Workbench 源文件用作本地补充资料，但已发布的技能用户不应需要这些资料。

对于图标，请使用：

• $SKILL_DIR/reference/lucide/lucide-icons.jsonl
• $SKILL_DIR/reference/lucide/icons/<icon>.svg

请勿在当前仓库、父目录或用户主目录中搜索这些技能参考资料。在已安装的技能中，此参考目录可能位于 /Users/<USER>/.agents/skills/deckkit-ppt-replica/reference/；请直接使用该技能专属目录。切勿运行 find /Users/<user> ... 等宽泛命令来查找 lucide 资源。如果缺少必需的技能参考资料，请报告技能安装问题，而不要改用无关文件。

工作流

1. 创建工作文件夹

在受版本控制的源示例旁边创建一个已忽略的示例工作文件夹：

examples/<example-name>-bbox-work/
  input/
  manifests/
  scripts/
  crops/
  preview/
    regions/
    icons/
  svg/
  output/

将源图像保留在语义明确的受版本控制示例文件夹中，例如：

examples/<example-name>/source.png

创建文件夹之前，使用 pwd 确认当前可写的仓库根目录，并在可用时使用 git rev-parse --show-toplevel 确认。将工作文件夹创建在该可写仓库根目录下，而不是随意放在可能位于沙盒或工作区之外的源图像路径旁。如果预期路径不可写，请选择当前仓库内对应的路径，并说明这一选择。

将源图像复制或镜像到工作文件夹中，路径为：

examples/<example-name>-bbox-work/input/source.png

所有脚本都应将 input/source.png 作为本地源文件读取。仅在备注或清单中将原始源路径用作来源记录。所有生成的重建文件都必须放在 examples/<example-name>-bbox-work/ 下：npm 包文件、脚本、清单、裁剪图、SVG 资源、预览图、QA 产物和输出的 PPTX 文件。不要将生成的工作产物写入源示例文件夹或仓库根目录。

2. 生成初始 BBox JSON

以原始 BBox 审核数据格式生成 manifests/initial-bbox.json：

{
  "title": "Example bbox review",
  "imageAssetId": "source",
  "image": { "width": 1672, "height": 941 },
  "activeElementId": "canvas",
  "instructions": "Review bbox geometry and route-aware reconstruction fields.",
  "status": "needs-human",
  "elements": []
}

每个元素都应包含 id、适用时的 parentId、label、kind、bbox、route、editability、renderRole、childrenPolicy、granularityFeedback、routeReason 和 reviewStatus。

请使用此精确的原始 BBox 审核架构。不要臆造枚举值。

interface BBoxReviewData {
  title?: string
  imageAssetId: string
  image: { width: number; height: number }
  activeElementId?: string
  instructions?: string
  status?: 'needs-human' | 'complete'
  elements: ElementNode[]
}

interface ElementNode {
  id: string
  parentId?: string
  label: string
  kind: ElementKind
  bbox: { x: number; y: number; w: number; h: number }
  description?: string
  reviewStatus?: ReviewStatus
  confidence?: number
  notes?: string
  route?: ReconstructionRoute
  editability?: Editability
  renderRole?: RenderRole
  childrenPolicy?: ChildrenPolicy
  granularityFeedback?: GranularityFeedback
  routeReason?: string
}

type ElementKind =
  | 'architecture-box'
  | 'canvas'
  | 'card'
  | 'content-row'
  | 'decorative-background'
  | 'decorative-line'
  | 'decorative-shape'
  | 'footer'
  | 'icon'
  | 'section'
  | 'section-body'
  | 'section-header'
  | 'text'
  | 'text-group'
  | 'group'
  | 'image'
  | 'shape'

type ReviewStatus = 'pending' | 'reviewing' | 'accepted' | 'needs-agent'

type ReconstructionRoute =
  | 'layout-only'
  | 'native-shape'
  | 'native-text'
  | 'svg-image'
  | 'editable-vector'
  | 'imagegen'
  | 'source-raster'
  | 'drawio-svg'

type Editability = 'none' | 'asset' | 'group' | 'element'
type RenderRole = 'render' | 'layout' | 'context'
type ChildrenPolicy = 'none' | 'optional' | 'required'
type GranularityFeedback = 'ok' | 'too-coarse' | 'too-fine'

架构规则：

• 除非审核已完成，否则初始审核 JSON 使用 status: "needs-human"。
• 首轮元素使用 reviewStatus: "pending"。
• 写入完整的 JSON 文件，而非部分代码片段。不要将枚举字符串值硬换行；"architecture-\nbox" 之类的值无效。
• 使用稳定且唯一的 id 值，并确保每个 parentId 都指向一个现有元素。
• 不要输出 kind: "line"；可见线条、分隔线、箭头、连接线和分隔符都使用 kind: "decorative-line"。
• 不要臆造 arrow、rect、rounded-rect、title、body 或 architecture-card 等 kind 值。
• 将视觉实现意图放在 route 中，而不是不受支持的 kind 值中。例如，连接线通常应使用 kind: "decorative-line"，并设置 route: "native-shape" 或 route: "editable-vector"。
• 交付 JSON 之前，解析并根据上述枚举验证 kind、route、editability、renderRole、childrenPolicy、granularityFeedback、reviewStatus 和顶层 status。

Route 含义：

• layout-only：仅用于分组、对齐或上下文；绝不直接渲染。
• native-shape：PPT 原生基本形状、线条、箭头、卡片、色带或容器。
• native-text：可编辑的 PowerPoint 文本框。
• svg-image：作为图像插入的合规 SVG，可缩放为矢量，但不可编辑路径。
• editable-vector：语义化矢量视觉元素，应转换为可编辑的 PPT 形状或自绘 SVG／基本形状组。
• imagegen：生成的栅格资源。
• source-raster：源图像裁剪内容或用户提供的位图。
• drawio-svg：导出为 SVG 并嵌入的结构化图表。

粒度规则：

• 请问：“实现时会在这里恰好放置一个元素吗？”
• 如果是，一个渲染 bbox 就足够。
• 如果不是，请拆分为实现时会放置的确切元素。
• 仅当 renderRole: "layout" 或 renderRole: "context" 时，才允许使用父框。
• 不要为同一个可见对象创建重复的渲染框。例如，section 包装器可以是 layout-only，而主体卡片是 native-shape 渲染元素。
• 如果 section、卡片或行的父级与子级描述的是同一个可见对象，那么它们中只有一个可以是 renderRole: "render"。父级结构通常应设为 route: "layout-only"，并使用 renderRole: "layout" 或 renderRole: "context"。
• 当所需的子框清晰可见且可推断时，不要明知需要拆分，却在首轮回答中输出 granularityFeedback: "too-coarse"。现在就拆分。
• 对于可编辑的图标行，请为每个图标和每个标签创建子框，或者为每个图标 + 标签组合及其图标/文本子项创建子框。如果目标是可编辑重建，不要用一个渲染 bbox 包住六个图标。
• 对于带有不规则装饰边框、牌匾、飘带、标签、徽章，或围绕可编辑文本的非基础框架装饰的装饰性容器，请将视觉框架与文本拆分。框架通常应作为一个 kind: "decorative-shape" 渲染元素，并使用 route: "svg-image" 或 route: "editable-vector"；其中的可读文本应作为独立的 route: "native-text" 渲染元素。除非文本被有意设计为不可编辑的艺术图形，否则不要将文本合并到 SVG 框架中。

SVG 路由适用性：

• svg-image 或 editable-vector 渲染节点必须描述一个不可再拆分的矢量类视觉素材：图标、徽标、象形图、装饰框架、连接线组合或图表片段，且实现时会将其作为单个创作素材放置。
• 不要仅仅因为整个 UI/卡片/模块包含边框、文本和插图/图标，就将其标记为一个 svg-image。带有可读文本、边框/背景和视觉素材的卡片是一个复合布局，而不是单个 SVG 素材。
• 对于复合卡片，请创建一个 kind: "card" 或 kind: "group" 父节点，并设置 route: "layout-only"，以及 renderRole: "layout" 或 renderRole: "context"。然后拆分可见子项：边框/背景使用 native-shape，每个可读文本块使用 native-text，每个实际图标/插图使用独立的 icon/image/decorative-shape 节点，并选择适当的路由。
• 如果卡片内值得使用 SVG 的视觉元素很小，请用紧贴该内部视觉元素的 bbox 框选。不要将 SVG bbox 扩展到卡片框架、标签文本、说明文字、徽章或周围留白。
• 如果候选 SVG bbox 包含可编辑/可读文本以及无关的布局框架，则说明范围过粗，应在输出首轮 JSON 之前先拆分。

3. 必须完成的检查点：可选的 Workbench 审查

写入并验证 manifests/initial-bbox.json 后，请停止。暂时不要安装依赖项、创建重建脚本、编写 SVG 或生成幻灯片。

告知用户，他们可以选择使用 Workbench 生成更准确的 initial-bbox.final.json。请清楚说明其中的取舍：Workbench 可让他们在重建前修正 bbox 几何、层级、路由和粒度，这通常能减少后续的视觉修正迭代并节省 token。如果他们跳过此步骤，仍可基于 initial-bbox.json 继续重建，但由于 bbox 错误未经过人工修正，后续区域 QA 可能需要更多 AI 视觉调整。

提供以下准确操作步骤：

https://artifact-kit.github.io/artifact-kit/

1. 打开 URL。
2. 上传源图像。
3. 上传 manifests/initial-bbox.json。
4. 根据需要调整框和路由。
5. 下载 <input-file>.final.json。
6. 将下载的文件放入 manifests/ 并命名为 initial-bbox.final.json，或者将其路径/内容发回，以便继续。

只有当用户提供 initial-bbox.final.json，或明确表示跳过 Workbench 并使用 initial-bbox.json 继续时，才能继续。记录选择了哪种路径。不要默默跳过此检查点。

4. 配置 DeckKit 重建

在当前的 xxx-work 文件夹中配置重建。不要依赖仓库本地的包源文件夹，例如 packages/deckkit，因为已发布技能的用户不会有这些文件。

完成此步骤后的推荐工作文件夹布局：

examples/<example-name>-bbox-work/
  package.json
  node_modules/
  input/
    source.png
  manifests/
    initial-bbox.json
    initial-bbox.final.json
  scripts/
    crop-assets.mjs
    build-svg-assets.mjs
    generate.mjs
  crops/
  preview/
    regions/
    icons/
  svg/
  output/

在 xxx-work 文件夹中创建或更新 package.json：

{
  "type": "module",
  "scripts": {
    "crop": "node scripts/crop-assets.mjs",
    "svg": "node scripts/build-svg-assets.mjs",
    "generate": "node scripts/generate.mjs"
  },
  "dependencies": {
    "@artifact-kit/deckkit": "latest",
    "@artifact-kit/deckkit-pro": "latest"
  }
}

在同一个工作文件夹中从 npm 安装依赖：

npm install

使用从 npm 安装的包中的导入。处理图像时，使用 DeckKit Pro 导出内容，而不要直接依赖 sharp：

import DeckKit from '@artifact-kit/deckkit'
import deckkitPro, {
  compareImages,
  cropImage,
  getImageInfo,
  overlayImages,
  resizeImage,
  sampleColor,
  writeSvgToPng,
  writeImage,
} from '@artifact-kit/deckkit-pro'

const pptx = new DeckKit()
pptx.use(deckkitPro())
pptx.defineLayout({ name: 'SOURCE', width: 13.333, height: 7.5 })
pptx.layout = 'SOURCE'
pptx.theme = {
  headFontFace: 'Microsoft YaHei',
  bodyFontFace: 'Microsoft YaHei',
  lang: 'zh-CN',
}

将所有生成的资源和输出文件放在同一个 xxx-work 文件夹中：

• 源文件副本：input/source.png
• 裁剪图：crops/
• 编写的 SVG：svg/
• 视觉预览和 QA 产物：preview/
• 生成的 PPTX：output/
  • *-preview.pptx：用于视觉检查的构建版本，插入前先将 SVG 资源栅格化为 PNG。
  • *-deliverable.pptx：最终交付构建版本，直接插入 SVG 资源。

使用 DeckKit Pro 图像辅助工具处理所有位图：

const cropped = await cropImage(sourcePath, { x, y, width: w, height: h })
await writeImage(cropped, 'crops/asset.png')

将裁剪提取与演示文稿生成分开：

• scripts/crop-assets.mjs：读取最终 bbox JSON，使用 cropImage 裁剪每个 source-raster 渲染资源，将文件写入 crops/，并写入裁剪清单，例如 manifests/crop-assets.json。
• scripts/build-svg-assets.mjs：接收区域 ID，仅为该区域编写 SVG 资源，将最终 .svg 文件写入 svg/，并将 SVG 源代码放在 generate.mjs 之外。在该区域内，一次编写并 QA 一个 SVG／图标。
• scripts/generate.mjs：接收区域／阶段 ID，读取最终 bbox JSON、裁剪清单和现有 SVG 文件，然后仅为已完成的区域以及当前区域构建 PPTX。除非资源清单缺失或已过期，否则不得重新裁剪源图或编写 SVG 源代码。默认情况下，为指定阶段同时生成预览版和交付版。

脚本约定：

• build-svg-assets.mjs 必须要求提供一个明确的当前区域 ID。不得支持 all、默认使用 all，或为后续区域生成 SVG。
• generate.mjs 必须要求提供一个明确的当前区域／阶段 ID。在每个区域都有 PASS 状态的 qa.md 或明确记录的验证缺口之前，不得支持 all、full 或最终的整页生成。
• 如果需要最终整页构建，脚本必须先验证每个必需的 preview/regions/<region-id>/qa.md 文件都存在，且状态为 PASS 或已明确记录缺口。
• 必须通过 QA 文件强制执行阶段顺序，不得依赖信任。只有在所有前序区域关卡都有证据后，才能渲染后续区域。

bbox JSON 用于定位和审查，并非运行时渲染 DSL。不要将 generate.mjs 实现为通用的、由 route／kind／id 驱动的渲染器，让它遍历 bbox 元素，并通过 fontSize(element)、textColor(element)、shapeStyle(element) 或 id.includes(...) 之类的宽泛辅助函数进行分发。这种失败模式会将视觉决策隐藏在传统的 if/else 代码中，从而违背由大模型驱动重建的初衷。

要求采用的方法：

• 仅使用 bbox 获取坐标、尺寸和源图裁剪内容。
• 让大模型为当前区域逐个语义对象编写明确的 DeckKit 命令。
• 在调用处明确展示视觉决策：文本内容、字号、颜色、字重、填充、线条、图层顺序、图标文件和裁剪文件。
• 辅助函数仅限于坐标转换、文件查找，以及那些视觉规格已根据源图验证过的真正重复组件。

错误示例：

for (const element of elements) {
  if (element.renderRole !== 'render') continue
  if (element.route === 'native-text') addText(slide, element)
  else if (element.route === 'native-shape') addShape(slide, element)
  else if (element.route === 'svg-image') addImage(slide, element)
}

function textColor(element) {
  if (element.id.includes('core')) return RED
  if (element.id.startsWith('sensing')) return BLUE
  return DARK_BLUE
}

正确示例：

function box(id) {
  return pbox(getElement(id).bbox)
}

async function drawProjectBackground(slide) {
  slide.addShape('roundRect', {
    ...box('project_background_card'),
    fill: { color: 'FFFFFF' },
    line: { color: 'B7CAF4', width: 0.8 },
  })
  slide.addImage({ path: 'svg/project_background_header.svg', ...box('project_background_header') })
  slide.addText('项目背景', {
    ...box('project_background_header_text'),
    fontSize: 15.5,
    bold: true,
    color: 'FFFFFF',
    margin: 0,
  })
  slide.addShape('ellipse', {
    ...box('project_background_row_1_icon_circle'),
    fill: { color: 'EEF5FF' },
    line: { color: 'D4DFF4', width: 0.8 },
  })
  slide.addImage({ path: 'svg/project_background_row_1_icon.svg', ...box('project_background_row_1_icon') })
}

不要将整张幻灯片写成数据解释器，然后再调整全局样式规则。重建代码应像是在语义上描述正在重建的区域。

不要为后续区域批量编写 SVG。可以整理简要的资源清单，但只有在某个区域成为当前重建目标时，才编写该区域的 SVG 源代码并进行视觉 QA。 资源文件必须使用真实且准确的扩展名。.svg 文件必须包含 SVG XML；.png 文件必须包含由 writeSvgToPng、writeImage 或其他 DeckKit Pro 图像辅助工具生成的真实 PNG 字节。不要将 SVG 文本写入 .png 路径，否则 Quick Look 和下游预览工具可能会错误地读取该文件。

将创作的 SVG 资源直接插入 PPTX：

slide.addImage({ path: 'svg/project_background_row_1_icon.svg', x, y, w, h })

不要将 SVG 资源转换为 PNG 再用于最终 PPTX。插入 SVG 可保留资源的矢量缩放能力。writeSvgToPng 只能用于辅助预览或调试图像，绝不能在路由为 svg-image 或 editable-vector 时用作插入 PPT 的资源。

对于 SVG 密集型阶段，请采用双输出策略：

• preview 模式：使用 DeckKit Pro 的 writeSvgToPng 将 SVG 资源转换为 PNG，插入 PNG，并且此 PPTX 仅用于 Quick Look 或其他视觉检查。
• deliverable 模式：使用 slide.addImage({ path: svgPath, ... }) 直接插入 SVG 文件；交付时应使用此版本，因为它能保留矢量缩放能力。
• 默认生成时，应通过同一份布局代码同时输出两个文件，以避免视觉检查版和交付版出现偏差：

npm run generate -- project-background
# writes output/...-project-background-preview.pptx
# writes output/...-project-background-deliverable.pptx

调试时可以采用单模式生成：

npm run generate -- project-background preview
npm run generate -- project-background deliverable

除非用户明确要求在 DeckKit Pro 之外进行底层图像处理，否则不要在生成的工作文件夹中将 sharp 添加为直接依赖。

请根据源尺寸进行像素到英寸的换算：

function pbox(x, y, w, h) {
  return {
    x: (x / SOURCE_W) * SLIDE_W,
    y: (y / SOURCE_H) * SLIDE_H,
    w: (w / SOURCE_W) * SLIDE_W,
    h: (h / SOURCE_H) * SLIDE_H,
  }
}

绝不要创建宽度 w 或高度 h 为负值的形状或线条。

5. 按阅读顺序重建

按阅读顺序重建，而不是从粗略到精细。按从上到下、从左到右的顺序进行。尚未重建的区域应留白，不要到处放置粗略占位内容。

原因：

• 保留未完成区域空白的部分幻灯片，能让新完成区域中的视觉差异一目了然。
• 粗略的整页草稿会让各区域的对齐、排版和图标错误难以察觉，因为所有内容同时都只是近似效果。
• 每次迭代都应先将一个新完成的区域与源图裁剪进行核对，再继续下一个区域。

实现也必须按相同顺序逐步扩展。先编写只渲染页眉的代码。页眉 QA 通过后，再追加或启用下一个区域的代码，然后重复此流程。不要先编写整张幻灯片的完整实现，再将最终整页渲染作为主要审查依据。只有当前区域通过关卡后，才允许查看整页预览。

密集单页信息图的建议区域顺序：

1. 页眉标题／副标题区域。
2. 左上区域。
3. 上方中间／右侧区域。
4. 左下区域。
5. 右下区域。
6. 页脚。

每个阶段只渲染已完成区域和当前区域。除非未来区域是对齐参考所必需的，否则不要将其作为粗略占位内容添加；如果使用这类占位内容，应标记为临时非输出参考线。

根据已审查的 bbox JSON 选择下一个边界明确的区域，例如一个分区或卡片组。

区域关卡要求：

• 仅处理一个当前区域。
• 允许修改的内容仅限此区域使用的 SVG 资源、已完成区域及当前区域的 DeckKit 绘图代码，以及此区域和其图标的 QA 文件。
• 当前区域通过之前，禁止创建未来区域的 SVG 资源、未来区域的绘图代码、整页输出、all 阶段生成，以及基于完整整页实现事后生成的 QA。

对于该区域：

1. 将 native-text 作为 DeckKit 文本框放置。
2. 将 native-shape 作为 DeckKit 形状、线条、箭头、渐变和简单容器放置。
3. 只有当位图就是预期的最终资源时，才放置 source-raster 裁剪图。
4. 仅为此区域编写、渲染和 QA 所需的 SVG 资源。
5. 使用 slide.addImage({ path: svgPath, x, y, w, h }) 放置已验收的 svg-image 资源。
6. 渲染幻灯片预览，从源图和渲染图中裁剪出已完成区域，生成并检查并排 QA 图像，完成对比后再继续下一个区域。

对于每个已完成区域，都要编写 QA 文件：

preview/regions/<region-id>/source.png
preview/regions/<region-id>/render.png
preview/regions/<region-id>/side-by-side.png
preview/regions/<region-id>/qa.md

将 side-by-side.png 作为主要语义对比图：源图在左，渲染图在右；根据需要留出足够边距，并使用中性、棋盘格或深色背景，以便白色或透明元素清晰可见。overlay.png 为可选项，仅有助于检查几何位置，不能替代并排语义审查。

创建区域 QA 文件后，打开并目视检查 render.png 和 side-by-side.png。编写 qa.md，记录 PASS 或具体问题／修复。在此区域的 QA 阶段解决文本溢出、换行、图标尺寸、缺失元素和语义不匹配问题。不要将明显的区域问题留到最终整页预览时再处理。

这是硬性关卡：当前区域的 QA 文件必须已存在并经过目视检查，且问题已修复或明确记录为验证缺口，之后才能开始下一个区域。

当前区域关卡完成后，报告 PASS／缺口并停止。等待用户批准继续下一个区域。即使下一个区域显而易见，也不要自动继续。

6. 图标重建

对于每个图标：

1. 根据周围文本和视觉形状判断图标的语义含义。

2. 使用 grep 或 jq 搜索技能本地的 lucide 元数据。例如：

   grep -Ei "thermometer|temperature|wifi|cloud|database" "$SKILL_DIR/reference/lucide/lucide-icons.jsonl"
   

3. 阅读最相关的 SVG 源文件：

   $SKILL_DIR/reference/lucide/icons/<name>.svg
   

4. 绘制新图标前，必须先阅读相关参考 SVG 的源代码。参考图标并非用于盲目照搬；你需要了解哪些具体图形元素传达了其含义，例如轮廓形状、内部符号、连接线、叶脉、仪表弧线、铃铛主体或节点图。

5. 从语义上重构图标。无需做到像素级一致，但必须传达相同概念，并与幻灯片的线条粗细、颜色、尺寸和视觉风格相符。

6. 如果图标由多个语义元素组成，应在一个 SVG 中绘制多个子图标或子组，而不是强行将所有路径合并为一个连通形状。例如，“低功耗感知”图标可以由一个电池／闪电子组和一个单独放置的叶子子组组成：

   <svg viewBox="0 0 48 72" ...>
     <g id="battery-lightning">...</g>
     <g id="leaf" transform="translate(...) scale(...)">...</g>
   </svg>
   

   将各子组视为可独立定位的语义单元。这样可以避免缩放后形状意外合并，看起来像支架、链条、尾巴或其他非预期物体。

7. 使用 DeckKit Pro writeSvgToPng 将重构后的 SVG 按目标 bbox 尺寸渲染为 PNG，然后在确认图标可用前，对图标本身进行目视检查。不要只依赖完整幻灯片预览；缩小到整页尺寸时，小图标的问题可能会被忽略。

8. 裁剪源图标，与渲染后的图标进行比较；如果语义匹配度、线条粗细、比例、透明度表现或子组位置不理想，则进行调整。

对于新绘制的 SVG，绝不能跳过本地的图标目视检查。

针对当前区域，一次只绘制一个 SVG 文件。不要通过一个对象映射，再配合 directIconRefs[id] ?? ...、id.startsWith('sensing') ? BLUE : ... 或 id.includes('header_icon') ? WHITE : ... 之类的默认样式分支，来生成整张幻灯片的 SVG 图标库。问题不在于使用脚本写入文件，而在于强行让不同视觉组遵循相同的默认样式规则。

将视觉组归属视为图标规范的一部分。在不同区域，即使是语义相同的图标，也可能需要不同的 SVG 代码或不同的参数：

• 浅色圆形中的大型项目背景温湿度图标，与小型感知层温度传感器图标不是同一种视觉素材。
• 同一系统架构感知组内的图标也可能有局部例外，例如，蓝色传感器图标中有一个绿色的空气质量／叶子图标。
• 页眉图标、页脚图标、服务图标、场景图标和核心创新图标各自有独立的颜色、尺寸、线条粗细和背景环境。

不要仅仅因为语义相近，就复用图标文件、颜色规则、尺寸规则、线条粗细规则或变换。只有在比较源图裁剪结果并确认视觉组规范一致后，才允许复用。如果规范不一致，则应创建单独的 SVG 文件和单独的 QA 记录。

每个图标的 reference.txt 和 qa.md 必须在目视检查后编写，不得自动生成 PASS 文本。qa.md 必须明确确认或修正以下各项：

• 与源图标的语义匹配度；
• 图标实际背景环境中的颜色和对比度；
• 线条粗细和填充表现；
• 尺寸、留白和 bbox 占用情况；
• 方向／朝向；
• 组合图标的子组位置；
• 与同一视觉组中相邻图标的一致性。

对于每个绘制的图标，都要编写 QA 文件：

preview/icons/<icon-id>/source.png
preview/icons/<icon-id>/render.png
preview/icons/<icon-id>/side-by-side.png
preview/icons/<icon-id>/reference.txt
preview/icons/<icon-id>/qa.md

reference.txt 必须列出绘制图标前读取的 lucide SVG 文件路径，以及用于改编的语义说明。如果没有合适的 lucide 参考图标，则应记录尝试过的搜索内容和绘制前选定的替代方案。

side-by-side.png 必须将源图和渲染图放在能清晰显示图标的背景上。对于白色或透明图标，应使用深色、棋盘格或原始环境背景；绝不能在白色背景上检查白色图标。创建这些文件后，打开／读取 side-by-side.png 进行目视检查，并在 qa.md 中记录 PASS 或具体问题／修复。在该区域内完成所有绘制图标的目视检查之前，不得继续处理下一个图标或确认该区域可用。 如果透明 PNG 预览在 Quick Look 或区域 QA 中显示为黑色或其他错误背景，请立即修复预览导出流程。最终交付物仍可直接插入 SVG，但预览 PNG 必须在视觉上可靠，以便进行 QA。

7. 非基础装饰形状

对于无法用简单 PPT 基础形状实现的装饰，例如弧形章节标题、飘带、丝带、不对称标签或自定义边框装饰：

1. 从视觉上识别其语义作用：标题标签、章节边界、动态弧线、品牌点缀、分隔符或背景外观。
2. 使用 SVG、DeckKit 基础图形或自定义几何形状，从语义层面重建。
3. 将渲染结果与源图裁剪区域进行比较。
4. 反复调整，直至保留相同的布局作用和视觉节奏。

除非随机的图像生成伪影构成边界、层级、重复样式或阅读顺序，否则不要复现它们。

对于明显的渐变色带、条形、丝带和页眉/页脚条，优先使用 DeckKit/DeckKit Pro 的渐变支持。如果不清楚确切 API，请检查已安装的包/类型，或在工作目录中进行最小化实验，然后再退而使用纯色块。只有在记录了渐变尝试失败及其视觉影响（作为验证缺口）后，才允许使用纯色近似。

8. 位图素材

对于无法通过 SVG/基础图形合理重建的素材：

1. 首先判断能否从源图中干净地裁剪出目标素材。如果可以，请裁剪源图。
2. 如果无法干净地裁剪，请编写 Seedream/图生图提示词。
3. 提示词必须要求模型仅输出目标对象/区域，并根据预期裁剪效果，将所有不相关区域留空或设为透明/白色。
4. 保留语义内容和透视关系；不要要求无关的重新设计。

将提示词保存在工作目录中，以便重新生成素材。

9. 验证

完成每个区域后：

• 将当前阶段的 PPTX 渲染为预览图像。
• 确认每个 preview/regions/<region-id>/qa.md 均注明 PASS 或记录明确的缺口。
• 确认每个 preview/icons/<icon-id>/qa.md 均注明 PASS 或记录明确的缺口。
• 直接查看当前区域/图标的 QA 图像；不要用整页渲染来代替。
• 检查文本是否可按计划编辑。
• 检查是否存在尚未解决的文本溢出、标签裁切或意外换行。
• 检查仅用于布局的方框是否生成了 PPT 对象。

最后：

• 只有所有区域关卡均通过后，才比较整页；绝不能用整页检查代替区域/图标 QA。
• 使用 unzip -t 或可用的包完整性检查来验证预览版和交付版 PPTX 文件。
• 对于大量使用 SVG 的交付物，确认最终 PPTX 中包含直接插入的 SVG 素材，而不仅仅是栅格化的 PNG 替代品。
• 检查 PowerPoint 是否能打开文件，且不会提示修复。

在最终回复中，明确区分已完成的输出和验证缺口。如果跳过了 Workbench 最终 JSON、逐区域 QA、逐图标 QA、PowerPoint 打开检查或其他任何必需的验证，请明确说明，不要暗示已全部完成。

如果重建过程中发现可复用的 DeckKit 功能或限制，请更新此技能附带的 reference/deckkit-capabilities.md。如果维护的是 artifact-kit 仓库本身，也请更新 docs/deckkit-llm-capabilities.md（如果该本地文档是其他工具所读取的来源）。