dapt-generator

name

dapt-generator

description

Generate DAPT (.dapt) pet asset packages for DeepSeek Agents — character reference sheets, animation frame strips, and final packaging. Use this skill when the user wants to create a new desktop pet, generate pet sprites, create animation frames, build a .dapt package, or mentions "pet asset", "dapt", "桌宠素材", "宠物动画", "角色三视图". Also trigger when the user asks to generate character designs for agent pets or wants to batch-produce animation sprite sheets.

DAPT Generator — AI 驱动的桌宠素材生成

通过 AI 生图 API 自动生成符合 DAPT 标准的桌宠素材包。

核心工作流

用户提供设定 → 生成角色三视图 → 用户确认 → 批量生成动作帧 → 色键去背 → 帧切割 → 打包 .dapt

铁律：禁止代替用户做创作决策

以下内容必须由用户明确提供，Agent 不得自行编造、推测或预设：

1. 角色设定 — 角色的外观、服装、配色、配饰等描述
2. 画风 — 赛璐璐、像素风、扁平矢量、水彩等风格选择
3. 参考图片 — 用户提供的 Logo、风格参考、角色草稿等

如果用户没有提供以上信息，必须主动询问并等待确认后才能执行生成。 创作决策权属于用户，Agent 的角色是执行工具而非创作者。 自行编造设定会导致返工和用户不满。

第一步：收集用户设定

向用户询问以下信息（可分步骤）：

1. 角色设定：请描述你想要的桌宠形象（外观、服装、配色、特征等）
2. 画风：请描述期望的画风（如"Q版赛璐璞"、"像素风"、"扁平矢量"等）
3. 参考图片：是否有 Logo 或风格参考图？（可选）
4. 动作集：需要哪些动作？（可选择标准集或自定义）

如果用户给出的描述比较简略，可以追问细节，但不要自行补充。 比如用户说"蓝色少女"，可以问"发型、服装风格、是否有特定配饰？"， 但不要自己决定"长直发、穿连帽外套"。

参考 references/style-prompts.md 和 references/action-prompts.md 获取灵感， 但只用于向用户展示选项，不用于自行决定。

第二步：生成角色三视图

确认用户设定后，使用脚本生成角色参考：

python scripts/dapt_generate_images.py ref \
    --character "用户提供的角色描述" \
    --style "用户提供的画风描述" \
    --ref-images ./logo.png \        # 可选：用户提供的参考图
    --count 3 \                       # 推荐生成3张供选择
    --size 1536x1024 \
    --output-dir ./refs/

生成后必须让用户查看并选择最满意的版本。用户可能：

• 选择其中一张
• 要求调整设定后重新生成
• 要求混合多张的优点

只有用户明确确认后才进入下一步。

第三步：批量生成动作帧

用户确认角色参考后，生成动作帧条带：

python scripts/dapt_generate_images.py action \
    --name idle \
    --desc "安静待机，微弱呼吸，身体轻微起伏" \
    --frames 8 \
    --layout 4x4 \
    --size 1024x1024 \
    --character "角色描述" \
    --style "画风描述" \
    --chroma "#FF3B00" \
    --ref-image ./refs/ref_01.png \
    --output-dir ./strips/

批量生成可使用 scripts/batch_generate.py 模板，修改 ACTIONS 列表即可。 参考 references/action-prompts.md 获取全部动作的推荐描述。

关键参数说明

参数	说明	注意事项
--layout	帧排列 列x行（如 4x4）	调用方自行确保与 size 和帧数合理匹配
--size	图片尺寸（如 1024x1024）	不同 API 对 size 的遵守程度不同，生成后需验证
--chroma	色键背景色	必须与角色主色调差距大
--frames	总帧数	超过 layout 容量时自动拆分为多张

多张拆分机制

当总帧数 > layout 容量（列x行）时，脚本自动拆分为多张图：

• 首张：仅输入角色参考图
• 续张：输入角色参考图 + 上一张条带（保持角色大小和动作衔接）
• 输出命名：{action}_strip_01.png, {action}_strip_02.png, ...

第四步：验证（关键步骤，不可跳过）

AI 生图的输出几乎不会完全遵守布局指令。实测中，指定 4x4 网格后模型可能 自行选择 4x2、3x2、2x2 等排列，帧尺寸不统一，间距不规则，帧数也可能与请求不符。 这是当前 AI 生图的固有局限，必须通过验证环节兜底。

验证内容：

1. 实际图片尺寸 — 是否与 --size 参数一致
2. 实际帧数 — 是否与 --frames 参数一致
3. 排列方式 — 是否遵守了 --layout 指定的网格

验证方式：通过子代理或脚本批量分析，不要在主对话中直接读取大量图片 （会超出请求体大小限制）。应列出文件列表，让用户指定要查看的具体文件。

验证后的两种处理方式（由用户选择）：

方式一：重新生成 适用于结果偏差太大、角色走形、帧数严重不符的情况。 调整 prompt 约束或更换 API 参数后重新生成。

方式二：具体分析具体处理（推荐） 适用于角色和动作内容本身质量好，仅布局不符预期的情况。 使用 scripts/extract_frames.py 对每张条带进行：

1. 色键去背（欧几里得 RGB 距离算法）
2. 连通域分析检测实际帧位置和数量
3. 裁剪每帧到 bounding box
4. 统一缩放到目标画布尺寸（居中放置）
5. 输出为独立的透明背景 PNG

可通过 Workflow 或子代理并行处理所有条带，处理完成后分配复审代理验证结果。

第五步：色键去背与帧提取

使用 scripts/extract_frames.py 处理条带图：

python scripts/extract_frames.py \
    --input-dir ./strips/ \
    --output-dir ./frames/ \
    --chroma "#FF3B00" \
    --threshold 96.0 \
    --canvas-width 256 \
    --canvas-height 256

处理流程：

1. 色键去背 — 欧几里得 RGB 距离算法，距离 <= 阈值的像素设为透明
2. 透明像素 RGB 归零 — 防止色彩残留和边缘溢色
3. 连通域分析 — 检测所有非透明的连续区域，过滤面积过小的噪点
4. 帧排序 — 按从左到右、从上到下排序
5. 裁剪 — 每帧裁剪到 bounding box
6. 缩放居中 — 缩放到目标画布并居中放置
7. 保存 — 输出为 {action}/0001.png, {action}/0002.png, ...

关键要点：

• 必须使用连通域分析而非等分切割，因为 AI 生成的帧不会精确对齐网格
• canvas 尺寸应在所有动作中保持统一，确保 .dapt 包内帧尺寸一致
• 处理完成后应分配复审代理检查帧数、尺寸、透明度是否符合预期

第六步：打包 .dapt

（待实现）按照 DAPT v1.0.0 标准打包为 .dapt 文件。 参考 references/dapt-standard-v1.md。

API 与脚本

本工具提供两个版本的生成脚本，适配不同的 API 接口：

脚本	API 端点	说明
dapt_generate.py	/v1/responses（Responses API）	支持模型文本回复，可获取模型的思考和选色报告
dapt_generate_images.py	/v1/images/generations + /edits	纯图片生成，无参考图走 generations，有参考图走 edits

两个脚本使用相同的 prompt 模板，区别仅在 API 调用方式。 根据实际使用的 API 服务选择合适的脚本。

实践经验

有效做法

1. 角色参考用三视图（正面/侧面/背面），比单张正面图提供更完整的角色信息
2. 生成多张供选择（推荐3张），并行生成不额外耗时，给用户选择权
3. 色键背景方案 — 在 prompt 中要求纯色背景，后处理去背。 比依赖 API 原生透明参数更通用，因为不同 API 对透明背景的支持不一致
4. 色键颜色由模型自动选择，在 prompt 中要求分析角色用色后选最远色
5. 续张条带附加上一张作为参考，保持角色大小和动作衔接一致性
6. 生成后必须验证实际输出 — 尺寸、布局、帧数都可能与请求不完全一致， 这是 AI 生图的固有特性，需要自动化检查脚本兜底
7. prompt 中网格行列必须与帧数一致 — 如果告诉模型"4 列 4 行"但只要 8 帧， 模型会填满整个 16 格。脚本会根据实际帧数自动调整行数，避免矛盾
8. 动作描述应描述整体动作而非逐帧分期 — 如果 prompt 把动作硬拆为 "帧1-4做A、帧5-8做B"这样的分期，模型会在分期边界产生不连贯。 应描述动作的整体流程，让模型自行分配帧间过渡。 正确示例："开心地跳一段可爱的舞蹈，身体左右摇摆扭动，双手随节奏挥舞， 偶尔转圈和蹦跳，表情活泼快乐，动作循环流畅" 错误示例："帧1-4起手双手合十，帧5-8旋转，帧9-12蹦跳，帧13-16摇摆"

后处理流水线

生成的条带图需要经过以下后处理才能成为可用的独立帧。 使用 scripts/extract_frames.py 一键完成：

python scripts/extract_frames.py \
    --input-dir ./strips/ \
    --output-dir ./frames/ \
    --chroma "#FF3B00" \
    --threshold 96.0 \
    --canvas 256x256

处理步骤：

1. 色键去背 — 计算每个像素与色键颜色的欧几里得 RGB 距离， 距离 <= 阈值（默认 96.0）的像素设为完全透明 (0,0,0,0)。 公式：sqrt((R-Cr)^2 + (G-Cg)^2 + (B-Cb)^2)

2. 透明 RGB 归零 — 所有 alpha=0 的像素强制 R=G=B=0， 防止色彩残留导致边缘溢色或压缩异常

3. 连通域分析检测帧 — 使用 scipy.ndimage.label 找到所有非透明的连续区域， 过滤面积过小的噪点（< 总面积 0.5%），按从左到右、从上到下排序。 不依赖固定网格切割，因为 AI 生成的帧不会精确对齐网格

4. 裁剪到 bounding box — 每个连通域裁剪到其最小包围矩形

5. 缩放居中到统一画布 — 按比例缩放（保留 5% 边距）后居中放置到 指定的 canvas 尺寸上，使用 LANCZOS 重采样

6. 按编号保存 — 输出为 {action}/0001.png, 0002.png, ... 同一动作的多张条带帧编号自动接续（strip_01 的帧 0001-0016， strip_02 从 0017 开始）

关键设计决策：

• 必须用连通域分析而非等分切割，因为 AI 不会精确对齐网格
• canvas 尺寸在所有动作中保持统一，确保 .dapt 包内帧尺寸一致
• 阈值 96.0 对应 RGB 空间约 22% 的范围，足以覆盖色键及其近似色

禁止事项

1. 禁止 Agent 自行编造角色设定或画风 — 这是用户的创作决策
2. 禁止一次性读取大量图片 — 会触发请求体大小限制， 应通过子代理或脚本分析，或逐张查看
3. 禁止假设生图结果完全符合预期 — AI 生图有随机性， 布局可能不严格遵守网格、尺寸可能被 API 调整、角色一致性可能漂移， 必须有验证环节
4. 禁止在动作提示词中逐帧分期描述 — 会导致分期边界动作不连贯