deckkit-ppt-replica

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DeckKit PPT Replica

Use this skill when reconstructing a source slide image into a repeatable, mostly editable PPTX with DeckKit.

当你需要使用DeckKit将源幻灯片图像重建为可重复生成、基本可编辑的PPTX文件时，请使用本技能。

Execution Discipline

执行规范

This workflow is audited step by step. Do not optimize for speed by skipping checkpoints, batching future regions, or assuming the user will only inspect the final PPTX. Treat every bbox, region render, icon side-by-side, and

qa.md

as user-visible review evidence. Put effort into bbox accuracy, rule compliance, completing the current step's stated goal, semantic comparison, and per-step output quality. If a gate is not satisfied, stop, fix it, or record the validation gap before proceeding.

本工作流会逐步骤进行审核。请勿通过跳过检查点、批量处理后续区域或假设用户仅会检查最终PPTX的方式来追求速度。请将每个bbox、区域渲染结果、图标对比图以及

qa.md

视为用户可见的审核证据。务必保证bbox的准确性、规则合规性、当前步骤目标的完成度、语义对比质量以及每一步的输出质量。若某个关卡未通过，请停止操作、修复问题或记录验证缺口后再继续。

Non-Negotiable Audit Mode

不可协商的审核模式

This skill is an audited reconstruction workflow, not a best-effort PPT generator. A run is considered failed if the agent optimizes for producing a complete PPTX before the required gate evidence exists.

Failure conditions:

Authoring SVG assets for a future region before the current region gate passes.
Writing, enabling, or generating DeckKit drawing code for a future region before the current region gate passes.
Generating a full-slide PPTX before every previous region gate has passed.
Creating region QA after the fact from a full-slide implementation.
Batch-authoring all icons/SVGs in one script run before their regions become current.
Proceeding past a region without explicitly reporting PASS/gaps and waiting for user confirmation.

After each region gate, stop and ask the user for confirmation before continuing. Do not interpret silence or momentum as approval to start the next region. The short-term goal is always "complete the current gate and stop", not "finish the deck".

本技能是一个经过审核的重构工作流，而非尽力而为的PPT生成器。若Agent在所需关卡证据未生成的情况下就优先生成完整PPTX，则视为运行失败。

失败条件：

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

每个区域关卡完成后，请停止操作并等待用户确认后再继续。请勿将沉默或操作惯性视为批准进入下一区域的信号。短期目标始终是“完成当前关卡并停止”，而非“完成整个演示文稿”。

Required References

必要参考资料

Before implementation, resolve

SKILL_DIR

as the directory containing this

SKILL.md

, then read:

```
$SKILL_DIR/reference/deckkit-capabilities.md
```
for DeckKit API capabilities, route names, image helpers, and implementation caveats.

Use the bbox schema embedded in this

SKILL.md

as the source of truth for

initial-bbox.json

. Do not require example-specific

LESSONS-LEARNED.md

; this skill is where durable lessons belong. When maintaining this repository itself,

docs/bbox-route-aware-segmentation-proposal.md

docs/deckkit-llm-capabilities.md

, or Workbench source files may be used as local supplements, but a published skill user should not need them.

For icons, use:

$SKILL_DIR/reference/lucide/lucide-icons.jsonl

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

Do not search the current repo, parent directories, or the user's home directory for these skill references. In an installed skill this reference directory may be

/Users/<USER>/.agents/skills/deckkit-ppt-replica/reference/

; use that skill-local directory directly. Never run broad commands such as

find /Users/<user> ...

to locate lucide assets. If a required skill reference is missing, report the skill installation problem instead of falling back to unrelated files.

开始实现前，请将

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资产。若所需技能参考资料缺失，请报告技能安装问题，而非使用无关文件作为替代。

Workflow

工作流

1. Create Work Folders

1. 创建工作文件夹

Create an ignored example work folder beside the tracked source example:

txt

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

Keep the source image in the semantic tracked example folder, such as:

txt

examples/<example-name>/source.png

Before creating folders, confirm the current writable repo root with

pwd

and, when available,

git rev-parse --show-toplevel

. Create the work folder under that writable repo root, not beside an arbitrary source image path that may be outside the sandbox or workspace. If the intended path is not writable, choose the matching path inside the current repo and state that choice.

Copy or mirror the source image into the work folder as:

txt

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

All scripts should read

input/source.png

as the local source. Keep the original source path only as provenance in notes or manifests. All generated reconstruction files must stay under

examples/<example-name>-bbox-work/

: npm package files, scripts, manifests, crops, SVG assets, previews, QA artifacts, and output PPTX files. Do not write generated work artifacts into the source example folder or repository root.

在已跟踪的源示例旁创建一个被忽略的示例工作文件夹：

txt

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

将源图像保存在语义化的已跟踪示例文件夹中，例如：

txt

examples/<example-name>/source.png

创建文件夹前，请使用

pwd

确认当前可写入的仓库根目录，若可用也可使用

git rev-parse --show-toplevel

。请在该可写入仓库根目录下创建工作文件夹，而非在可能位于沙箱或工作区外的任意源图像路径旁创建。若预期路径不可写入，请选择当前仓库内的匹配路径并说明该选择。

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

txt

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

所有脚本应读取

input/source.png

作为本地源文件。仅在笔记或清单中保留原始源路径作为溯源信息。所有生成的重构文件必须保存在

examples/<example-name>-bbox-work/

下：npm包文件、脚本、清单、裁剪图、SVG资产、预览文件、QA工件以及输出PPTX文件。请勿将生成的工作工件写入源示例文件夹或仓库根目录。

2. Generate Initial BBox JSON

2. 生成初始BBox JSON

Generate

manifests/initial-bbox.json

in raw bbox review data format:

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": []
}

Each element should include

id

parentId

when useful,

label

kind

bbox

route

editability

renderRole

childrenPolicy

granularityFeedback

routeReason

, and

reviewStatus

Use this exact raw bbox review schema. Do not invent enum values.

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'

Schema rules:

Use
```
status: "needs-human"
```
for initial review JSON unless review is already complete.
Use
```
reviewStatus: "pending"
```
for first-pass elements.
Write a complete JSON file, not a partial snippet. Do not hard-wrap enum string values across lines; values such as
```
"architecture-\nbox"
```
are invalid.
Use stable unique
```
id
```
values and make every
```
parentId
```
point to an existing element.
Do not output
```
kind: "line"
```
; use
```
kind: "decorative-line"
```
for visible lines, dividers, arrows, connectors, and separators.

Do not invent kind values such as

arrow

rect

rounded-rect

title

body

, or

architecture-card

Keep visual implementation intent in
```
route
```
, not in unsupported
```
kind
```
values. For example, a connector should usually be
```
kind: "decorative-line"
```
with
```
route: "native-shape"
```
or
```
route: "editable-vector"
```
.
Before handing off the JSON, parse it and validate
```
kind
```
,
```
route
```
,
```
editability
```
,
```
renderRole
```
,
```
childrenPolicy
```
,
```
granularityFeedback
```
,
```
reviewStatus
```
, and top-level
```
status
```
against the enums above.

Route meanings:

```
layout-only
```
: grouping/alignment/context only; never render directly.
```
native-shape
```
: PPT primitive shape, line, arrow, card, band, or container.
```
native-text
```
: editable PowerPoint text box.
```
svg-image
```
: accepted SVG inserted as an image, vector-scalable but not path-editable.
```
editable-vector
```
: semantic vector visual that should become editable PPT shapes or an authored SVG/primitive group.
```
imagegen
```
: generated raster asset.
```
source-raster
```
: source crop or user-provided bitmap.
```
drawio-svg
```
: structured diagram exported to SVG and embedded.

Granularity rule:

Ask: "Will implementation place exactly one thing here?"
If yes, one render bbox is enough.
If no, split into the exact things implementation will place.

Parent boxes are allowed only as

renderRole: "layout"

renderRole: "context"

Do not create duplicate render boxes for the same visible object. For example, a section wrapper may be
```
layout-only
```
, while the body card is the
```
native-shape
```
render element.
If a section, card, or row parent describes the same visible object as a child, only one of them may be
```
renderRole: "render"
```
. Parent structure should usually be
```
route: "layout-only"
```
with
```
renderRole: "layout"
```
or
```
renderRole: "context"
```
.
Do not knowingly output
```
granularityFeedback: "too-coarse"
```
as the first-pass answer when the needed child boxes are visible and inferable. Split them now.
For editable icon rows, create child boxes for each icon and each label, or each icon+label pair plus child icon/text boxes. Do not use one render bbox for six icons if the intent is editable reconstruction.

以原始bbox审核数据格式生成

manifests/initial-bbox.json

：

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审核schema。请勿自行发明枚举值。

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'

Schema规则：

初始审核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
```
是否符合上述枚举值。

路由含义：

```
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"

。

请勿为同一可见对象创建重复的渲染框。例如，区域包装器可设为
```
layout-only
```
，而主体卡片作为
```
native-shape
```
渲染元素。
若区域、卡片或行父级与子级描述同一可见对象，则其中仅能有一个设为
```
renderRole: "render"
```
。父级结构通常应设为
```
route: "layout-only"
```
并搭配
```
renderRole: "layout"
```
或
```
renderRole: "context"
```
。
当所需子框可见且可推断时，请勿在首次生成时故意输出
```
granularityFeedback: "too-coarse"
```
。请立即拆分。
对于可编辑的图标行，请为每个图标和每个标签，或每个图标+标签组合加上子图标/文本框创建子框。若意图是可编辑重构，请勿用一个渲染框包含六个图标。

3. Required Checkpoint: Optional Workbench Review

3. 必要检查点：可选Workbench审核

After writing and validating

manifests/initial-bbox.json

, stop. Do not install dependencies, create reconstruction scripts, author SVGs, or generate slides yet.

Tell the user they can optionally use Workbench to generate a more accurate

initial-bbox.final.json

. Explain the tradeoff clearly: Workbench lets them correct bbox geometry, hierarchy, routes, and granularity before reconstruction, which usually reduces later visual-fix iterations and token use. If they skip it, reconstruction can continue from

initial-bbox.json

, but later region QA may need more AI vision adjustments because bbox errors were not corrected by hand.

Give the exact operation steps:

txt

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

Open the URL.
Upload the source image.
Upload
```
manifests/initial-bbox.json
```
.
Adjust boxes/routes if needed.
Download
```
<input-file>.final.json
```
.
Put the downloaded file in
```
manifests/
```
as
```
initial-bbox.final.json
```
, or send its path/content back to continue.

Continue only after the user either provides

initial-bbox.final.json

or explicitly says to skip Workbench and proceed with

initial-bbox.json

. Record which path was chosen. Do not silently skip this checkpoint.

编写并验证

manifests/initial-bbox.json

后，请停止操作。请勿安装依赖、创建重构脚本、创作SVG或生成幻灯片。

告知用户可选择使用Workbench生成更准确的

initial-bbox.final.json

。请清晰说明利弊：Workbench允许他们在重构前修正bbox几何形状、层级、路由和粒度，通常可减少后续视觉修正迭代和令牌消耗。若跳过此步骤，可基于

initial-bbox.json

继续重构，但后续区域QA可能需要更多AI视觉调整，因为bbox错误未被人工修正。

提供确切操作步骤：

txt

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

打开上述URL。
上传源图像。
上传
```
manifests/initial-bbox.json
```
。
按需调整框/路由。
下载
```
<input-file>.final.json
```
。
将下载文件放入
```
manifests/
```
目录，命名为
```
initial-bbox.final.json
```
，或返回其路径/内容以继续。

仅当用户提供

initial-bbox.final.json

或明确表示跳过Workbench并基于

initial-bbox.json

继续时，才可继续操作。记录所选路径。请勿静默跳过此检查点。

4. Configure DeckKit Reconstruction

4. 配置DeckKit重构

Configure reconstruction inside the current

xxx-work

folder. Do not depend on repository-local package source folders such as

packages/deckkit

, because a published skill user will not have those files.

Recommended work-folder layout after this step:

txt

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/

Create or update

package.json

in the

xxx-work

folder:

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"
  }
}

Install dependencies from npm in that same work folder:

bash

npm install

Use imports from the npm-installed packages. For image operations, use DeckKit Pro exports instead of directly depending on

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',
}

Write all generated assets and outputs under the same

xxx-work

folder:

source copy:
```
input/source.png
```
crops:
```
crops/
```
authored SVGs:
```
svg/
```
visual previews and QA artifacts:
```
preview/
```
generated PPTX:
```
output/
```
- ```
*-preview.pptx
```
  : visual-check build with SVG assets rasterized to PNG before insertion.
- ```
*-deliverable.pptx
```
  : final delivery build with SVG assets inserted directly.

Use DeckKit Pro image helpers for all bitmap preparation:

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

Keep crop extraction separate from deck generation:

```
scripts/crop-assets.mjs
```
: reads the final bbox JSON, crops every
```
source-raster
```
render asset with
```
cropImage
```
, writes files under
```
crops/
```
, and writes a crop manifest such as
```
manifests/crop-assets.json
```
.
```
scripts/build-svg-assets.mjs
```
: accepts a region id, authors only that region's SVG assets, writes final
```
.svg
```
files under
```
svg/
```
, and keeps SVG source code out of
```
generate.mjs
```
. Within the region, author and QA one SVG/icon at a time.
```
scripts/generate.mjs
```
: accepts a region/stage id, reads the final bbox JSON, crop manifest, and existing SVG files, then builds the PPTX for completed regions plus the current region only. It should not recrop source images or author SVG source code unless an asset manifest is missing or stale. By default, generate both preview and deliverable builds for the requested stage.

Script contract:

```
build-svg-assets.mjs
```
must require one explicit current region id. It must not support
```
all
```
, default to
```
all
```
, or generate SVGs for future regions.
```
generate.mjs
```
must require one explicit current region/stage id. It must not support
```
all
```
,
```
full
```
, or final full-slide generation until every region has a PASS
```
qa.md
```
or explicitly recorded validation gap.
If a final full-slide build is needed, the script must first verify every required
```
preview/regions/<region-id>/qa.md
```
exists and is PASS or has explicit gaps.
Stage order must be enforced by QA files, not by trust. A later region may only render after all previous region gates have evidence.

The bbox JSON is positioning and review evidence, not a runtime rendering DSL. Do not implement

generate.mjs

as a generic route/kind/id-driven renderer that loops through bbox elements and dispatches through broad helpers such as

fontSize(element)

textColor(element)

shapeStyle(element)

, or

id.includes(...)

rules. This failure mode hides visual decisions in traditional if/else code and defeats the purpose of LLM-driven reconstruction.

Required approach:

Use bbox only to retrieve coordinates, sizes, and source crops.
Let the LLM write explicit DeckKit commands for the current region, one semantic object at a time.
Make the visual decision visible at the call site: text content, font size, color, weight, fill, line, layer order, icon file, and crop file.
Keep helpers limited to coordinate conversion, file lookup, and truly repeated components whose visual spec has been verified against the source.

Bad pattern:

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
}

Good pattern:

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') })
}

Do not write the whole slide as a data interpreter and then tune global style rules. The reconstruction code should read like a semantic description of the region being rebuilt.

Do not batch-author SVGs for future regions. A light asset inventory is fine, but SVG source creation and visual QA happen when that region is the current reconstruction target.

Asset files must have truthful extensions. A

.svg

file must contain SVG XML; a

.png

file must contain real PNG bytes produced by

writeSvgToPng

writeImage

, or another DeckKit Pro image helper. Do not write SVG text to a

.png

path, because Quick Look and downstream preview tools can misread the file.

Insert authored SVG assets directly into the PPTX:

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

Do not convert SVG assets to PNG for the final PPTX. SVG insertion keeps the asset vector-scalable.

writeSvgToPng

may be used only for auxiliary preview/debug images, never as the inserted PPT asset when the route is

svg-image

editable-vector

Use a dual-output strategy for SVG-heavy stages:

```
preview
```
mode: convert SVG assets to PNG with DeckKit Pro
```
writeSvgToPng
```
, insert the PNGs, and use this PPTX only for Quick Look or other visual checks.
```
deliverable
```
mode: insert the SVG files directly with
```
slide.addImage({ path: svgPath, ... })
```
; this is the version to hand off because it preserves vector scalability.
Default generation should output both files from the same layout code so visual-check and delivery builds cannot drift:

bash

npm run generate -- project-background

在当前

xxx-work

文件夹内配置重构。请勿依赖仓库本地的包源文件夹（如

packages/deckkit

），因为已发布技能的用户不会拥有这些文件。

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

txt

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

：

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安装依赖：

bash

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

实现为通用的路由/类型/id驱动渲染器，通过遍历bbox元素并调用

fontSize(element)

、

textColor(element)

、

shapeStyle(element)

或

id.includes(...)

这类通用助手进行分发。这种失败模式会将视觉决策隐藏在传统的if/else代码中，违背LLM驱动重构的目的。

必需实现方式：

仅使用bbox获取坐标、尺寸和源图裁剪。
让LLM为当前区域编写明确的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 })

最终PPTX请勿将SVG资产转换为PNG。SVG插入可保持资产的矢量可缩放性。

writeSvgToPng

仅可用于辅助预览/调试图像，当路由为

svg-image

或

editable-vector

时，绝不能作为插入PPT的资产。

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

```
preview
```
模式：使用DeckKit Pro的
```
writeSvgToPng
```
将SVG资产转换为PNG，插入PNG文件，此PPTX仅用于Quick Look或其他视觉检查。
```
deliverable
```
模式：使用
```
slide.addImage({ path: svgPath, ... })
```
直接插入SVG文件；这是交付版本，因为它保留了矢量可缩放性。
默认生成应从同一布局代码输出两个文件，以确保视觉检查和交付版本不会出现偏差：

bash

npm run generate -- project-background

writes output/...-project-background-preview.pptx

写入 output/...-project-background-preview.pptx

writes output/...-project-background-deliverable.pptx

写入 output/...-project-background-deliverable.pptx


Single-mode generation is acceptable for debugging:

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

Do not add

sharp

as a direct dependency in generated work folders unless the user explicitly asks for low-level image processing outside DeckKit Pro.

Use pixel-to-inch conversion from the source dimensions:

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,
  }
}

Never create shapes or lines with negative


调试时可使用单模式生成：

```bash
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,
  }
}

请勿创建宽度或高度为负的形状或线条。

5. Reconstruct In Reading Order

5. 按阅读顺序重构

Reconstruct in reading order, not coarse-to-fine. Work from top to bottom and left to right. Leave all not-yet-reconstructed regions blank instead of placing rough placeholders everywhere.

Why:

A partial slide with blank unfinished regions makes visual differences in the newly completed region obvious.
A coarse full-slide draft can hide regional alignment, typography, and icon errors because everything is approximate at once.
Each iteration should validate one newly completed region against the source crop before moving on.

Implementation must grow in the same order. Start with code that renders only the header. After header QA passes, append or enable the next region's code, then repeat. Do not write the entire slide implementation first and use the final full-slide render as the primary review surface. Full-slide previews are allowed only after the current region gate has passed.

Recommended region order for dense single-slide infographics:

Header title/subtitle area.
Top-left section.
Top-middle / top-right section.
Bottom-left section.
Bottom-right section.
Footer.

For each stage, render only completed regions and the current region. Do not add future regions as rough placeholders unless they are needed as alignment guides, and if used, mark them as temporary non-output guides.

Pick the next bounded region from the reviewed bbox JSON, such as a section or card group.

Required region gate:

Work on exactly one current region.
Allowed changes are limited to SVG assets used by this region, DeckKit drawing code for completed regions plus the current region, and QA files for this region and its icons.
Forbidden before the current region passes: future region SVG assets, future region drawing code, full-slide output,
```
all
```
stage generation, and post-hoc QA generated from a completed full-slide implementation.

For that region:

Place
```
native-text
```
as DeckKit text boxes.
Place
```
native-shape
```
as DeckKit shapes, lines, arrows, gradients, and simple containers.
Place
```
source-raster
```
crops only when the bitmap is the intended final asset.
Author, render, and QA only the SVG assets needed by this region.

Place accepted

svg-image

assets with

slide.addImage({ path: svgPath, x, y, w, h })

Render the slide preview, crop the completed region from source and render, generate a side-by-side QA image, inspect it, and compare before moving to the next region.

For every completed region, write QA files:

txt

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

Use

side-by-side.png

as the primary semantic comparison: source on the left, render on the right, with enough padding and a neutral/checker/dark background when needed so white or transparent elements are visible.

overlay.png

is optional and only helps geometry checks; it is not a substitute for semantic side-by-side review.

After creating region QA files, open/read

render.png

and

side-by-side.png

with visual inspection. Write

qa.md

with PASS or concrete issues/fixes. Fix text overflow, wrapping, icon scale, missing elements, and semantic mismatches during that region's QA pass. Do not defer obvious region problems to the final full-slide preview.

This is a hard gate: do not start the next region until the current region's QA files exist, have been visually inspected, and issues are either fixed or explicitly recorded as validation gaps.

After the current region gate is complete, report the PASS/gaps and stop. Wait for the user to approve continuing to the next region. Do not continue automatically, even if the next region is obvious.

请按阅读顺序重构，而非从粗到细。从上到下、从左到右进行操作。所有尚未重构的区域请留空，而非到处放置粗略占位符。

原因：

未完成区域留空的部分幻灯片，可使新完成区域的视觉差异更加明显。
粗略的全幻灯片草稿可能会掩盖区域对齐、排版和图标错误，因为所有元素都是近似的。
每次迭代应在进入下一区域前，验证新完成区域与源图裁剪的匹配度。

实现必须按相同顺序逐步推进。从仅渲染页眉的代码开始。页眉QA通过后，追加或启用下一区域的代码，然后重复此过程。请勿先编写整张幻灯片的实现，再将最终全幻灯片渲染作为主要审核界面。仅当前区域关卡通过后，才可生成全幻灯片预览。

密集型单幻灯片信息图的推荐区域顺序：

页眉标题/副标题区域。
左上区域。
中上/右上区域。
左下区域。
右下区域。
页脚。

每个阶段仅渲染已完成区域和当前区域。除非需要作为对齐参考，否则请勿添加未来区域的粗略占位符；若使用，请标记为临时非输出参考线。

从已审核的bbox JSON中选择下一个有界区域，例如某个区域或卡片组。

必需区域关卡：

仅处理一个当前区域。
允许的更改仅限于该区域使用的SVG资产、已完成区域加当前区域的DeckKit绘图代码，以及该区域及其图标的QA文件。
当前区域通过前禁止操作：未来区域的SVG资产、未来区域的绘图代码、全幻灯片输出、
```
all
```
阶段生成，以及从已完成的全幻灯片实现事后生成QA。

对于该区域：

将
```
native-text
```
作为DeckKit文本框放置。
将
```
native-shape
```
作为DeckKit形状、线条、箭头、渐变和简单容器放置。
仅当位图为预期最终资产时，才放置
```
source-raster
```
裁剪图。
仅创作、渲染和QA该区域所需的SVG资产。

使用

slide.addImage({ path: svgPath, x, y, w, h })

放置已验收的

svg-image

资产。

渲染幻灯片预览，从源图和渲染结果中裁剪已完成区域，生成并排QA图像，检查对比后再进入下一区域。

每个已完成区域请编写QA文件：

txt

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. Icon Reconstruction

6. 图标重构

For every icon:

Identify the icon's semantic meaning from the surrounding text and visual shape.

Search skill-local lucide metadata with

rg

, for example:

bash

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

Read the most relevant SVG source:

txt

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

You MUST read the relevant reference SVG source code before drawing the new icon. The reference is not for copying blindly; it is to understand which concrete primitives communicate the meaning, such as outline shape, inner symbol, connector, leaf vein, gauge arc, bell body, or node graph.
Reconstruct the icon semantically. It does not need to be pixel-identical; it must communicate the same concept and match the slide's stroke weight, color, scale, and visual style.
If the icon is a semantic composition, draw it as multiple sub-icons or subgroups in one SVG instead of forcing all paths into one connected shape. For example, a "low-power sensing" icon can be one battery/lightning subgroup plus a separately positioned leaf subgroup:
svg
```
<svg viewBox="0 0 48 72" ...>
  <g id="battery-lightning">...</g>
  <g id="leaf" transform="translate(...) scale(...)">...</g>
</svg>
```
Treat subgroups as independently positioned semantic units. This avoids accidental merged shapes that read as stands, chains, tails, or other unintended objects after scaling.
Render the reconstructed SVG to PNG with DeckKit Pro
```
writeSvgToPng
```
at the target bbox size, then visually inspect the icon itself before accepting it. Do not rely only on the full-slide preview; small icon errors can disappear at full-slide scale.
Crop the source icon, compare it with the rendered icon, and adjust if the semantic match, weight, proportions, transparency behavior, or subgroup placement are off.

Never skip the local icon visual check for newly authored SVGs.

Author SVG files one at a time for the current region. Do not generate a whole slide's SVG library through one object map plus default style branches such as

directIconRefs[id] ?? ...

id.startsWith('sensing') ? BLUE : ...

, or

id.includes('header_icon') ? WHITE : ...

. The problem is not using a script to write files; the problem is forcing different visual groups through the same default style rules.

Treat visual group membership as part of the icon spec. The same semantic icon can require separate SVG code or separate parameters in different regions:

A large project-background temperature/humidity icon in a pale circle is not the same visual asset as a small sensing-layer temperature sensor icon.
Icons inside the same system-architecture sensing group may still have local exceptions, such as a green air-quality/leaf icon among blue sensor icons.
Header icons, footer icons, service icons, scenario icons, and core-innovation icons each have their own color, scale, stroke weight, and background context.

Do not reuse an icon file, color rule, scale rule, stroke-width rule, or transform just because the semantic meaning is similar. Reuse is allowed only after comparing source crops and confirming that the visual group specifications match. If they do not match, create separate SVG files and separate QA records.

Each icon's

reference.txt

and

qa.md

must be written after visual inspection, not emitted as automatic PASS text.

qa.md

must explicitly confirm or fix:

semantic match to the source icon;
color and contrast in the icon's real background context;
stroke weight and fill behavior;
size, padding, and bbox occupancy;
direction/orientation;
subgroup placement for composed icons;
consistency with neighboring icons in the same visual group.

For every authored icon, write QA files:

txt

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

must list the lucide SVG file path(s) read before drawing the icon, plus any semantic notes used to adapt them. If no good lucide reference exists, record the attempted searches and the chosen fallback before drawing.

side-by-side.png

must place source and render on a background that makes the icon visible. For white or transparent icons, use a dark, checker, or original-context background; never review a white icon on a white background. After creating the files, open/read

side-by-side.png

with visual inspection and write

qa.md

with PASS or concrete issues/fixes. Do not move to the next icon or accept the region until every authored icon in that region has been visually inspected.

If transparent PNG previews render with black or incorrect backgrounds in Quick Look or region QA, fix the preview export pipeline immediately. The deliverable may still use direct SVG insertion, but the preview PNGs must be visually reliable for QA.

每个图标请按以下步骤处理：

从周围文本和视觉形状中识别图标的语义含义。

使用

rg

搜索技能本地的lucide元数据，例如：

bash

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

读取最相关的SVG源文件：

txt

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

绘制新图标前，你必须阅读相关的参考SVG源代码。参考并非用于盲目复制；而是为了理解哪些具体基元传达了含义，例如轮廓形状、内部符号、连接线、叶脉、仪表弧线、钟体或节点图。
语义化重构图标。无需像素级完全一致；但必须传达相同概念，并匹配幻灯片的描边粗细、颜色、缩放比例和视觉风格。
若图标为语义组合，请在一个SVG中绘制为多个子图标或子组，而非将所有路径合并为一个连接形状。例如，“低功耗传感”图标可分为一个电池/闪电子组和一个单独定位的叶子子组：
svg
```
<svg viewBox="0 0 48 72" ...>
  <g id="battery-lightning">...</g>
  <g id="leaf" transform="translate(...) scale(...)">...</g>
</svg>
```
将子组视为独立定位的语义单元。这可避免缩放后意外合并的形状被误读为支架、链条、尾部或其他非预期对象。
使用DeckKit Pro的
```
writeSvgToPng
```
将重构后的SVG渲染为目标bbox尺寸的PNG，然后在验收前单独视觉检查图标本身。请勿仅依赖全幻灯片预览；小图标错误在全幻灯片比例下可能会消失。
裁剪源图标，与渲染图标对比，若语义匹配度、粗细、比例、透明度行为或子组位置不符合要求，请进行调整。

新创作的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文件：

txt

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. Non-Basic Decorative Shapes

7. 非基础装饰形状

For decorations that are not simple PPT primitives, such as curved section headers, swooshes, ribbons, asymmetric tabs, or custom frame chrome:

Visually identify the semantic role: header tab, section boundary, motion sweep, brand accent, separator, or background skin.
Reconstruct at the semantic level using SVG, DeckKit primitives, or custom geometry.
Compare the rendered result against the source crop.
Iterate until it carries the same layout role and visual rhythm.

Do not reproduce random image-generation artifacts unless they define a boundary, hierarchy, repeated style, or reading order.

For obvious gradient bands, bars, ribbons, and header/footer strips, use DeckKit/DeckKit Pro gradient support first. If the exact API is unclear, inspect the installed package/types or run a minimal experiment in the work folder before falling back to solid blocks. A solid-color approximation is allowed only when the failed gradient attempt and visual impact are recorded as validation gaps.

对于非简单PPT基元的装饰元素，例如弧形区域页眉、曲线条、丝带、不对称标签或自定义框架边框：

视觉识别其语义角色：页眉标签、区域边界、动态曲线、品牌强调、分隔符或背景外观。
使用SVG、DeckKit基元或自定义几何形状在语义层面重构。
将渲染结果与源图裁剪对比。
迭代调整，直到其具备相同的布局角色和视觉节奏。

除非随机图像生成的伪影定义了边界、层级、重复样式或阅读顺序，否则请勿重现这些伪影。

对于明显的渐变条、带状物、丝带和页眉/页脚条，请优先使用DeckKit/DeckKit Pro的渐变支持。若确切API不明确，请在回退到纯色块前，检查已安装包的类型或在工作文件夹中运行最小化实验。仅当渐变尝试失败且视觉影响已记录为验证缺口时，才允许使用纯色近似。

8. Hard Bitmap Assets

8. 复杂位图资产

For assets that cannot reasonably be rebuilt with SVG/primitives:

First decide whether the desired asset can be cropped cleanly from the source. If yes, use a source crop.
If it cannot be cropped cleanly, write a Seedream/image-to-image prompt.
The prompt must instruct the model to output only the desired object/region and leave every unrelated area blank or transparent/white, depending on the intended crop.
Preserve semantic content and perspective; do not ask for unrelated redesign.

Keep prompts in the work folder so the asset can be regenerated.

对于无法合理使用SVG/基元重建的资产：

首先判断所需资产是否可从源图中干净裁剪。若是，则使用源图裁剪。
若无法干净裁剪，请编写Seedream/图生图提示词。
提示词必须指示模型仅输出所需对象/区域，并将所有无关区域留空或设为透明/白色（取决于预期裁剪方式）。
保留语义内容和透视效果；请勿要求无关的重新设计。

请将提示词保存在工作文件夹中，以便重新生成资产。

9. Validation

9. 验证

After each region:

Render the current-stage PPTX to preview images.
Confirm each
```
preview/regions/<region-id>/qa.md
```
says PASS or records explicit gaps.
Confirm each
```
preview/icons/<icon-id>/qa.md
```
says PASS or records explicit gaps.
Read the current region/icon QA images directly; do not use a full-slide render as a shortcut.
Check that text is editable where planned.
Check that no region has unresolved text overflow, clipped labels, or unintended wrapping.
Check that layout-only boxes did not produce PPT objects.

At the end:

Compare the full slide only after all region gates pass; never use it as a replacement for region/icon QA.
Validate preview and deliverable PPTX files with
```
unzip -t
```
or the available package integrity check.
For SVG-heavy deliverables, confirm the final PPTX contains direct SVG assets, not only rasterized PNG substitutes.
Check that PowerPoint opens without repair prompts.

In the final response, clearly separate completed outputs from validation gaps. If Workbench final JSON, per-region QA, per-icon QA, PowerPoint open-check, or any other required validation was skipped, say so explicitly instead of implying full completion.

If reconstruction uncovers a reusable DeckKit capability or limitation, update this skill's bundled

reference/deckkit-capabilities.md

. When maintaining the artifact-kit repository itself, also update

docs/deckkit-llm-capabilities.md

if that local doc is the source consumed by other tools.

每个区域完成后：

渲染当前阶段的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

是其他工具使用的源文件，也请更新该文档。