Kun 内置 ad-creative 技能实战：用 Agent 规划与产出付费广告创意素材

本篇技术指南围绕 Kun 内置技能（bundled skill）ad-creative（见 SKILL.md）展开，讲解如何借助 Kun 的 Agent 运行时，为付费广告（paid campaigns）系统化地规划广告概念、产出文案变体（copy variants）、确定视觉方向（visual directions）并构建可量化的测试矩阵（test matrices）。读完本文，你将掌握该技能的触发方式、五步工作流、工具路由规则、完成门禁与合规边界，并从源码层面理解 generate_image、generate_video、render_chart 三个关键工具的真实实现与配置前提。

一、技能定位：ad-creative 是什么

ad-creative 是 Kun 随仓库内置的 38 个 bundled skills 之一（校验脚本 check-bundled-skills.mjs 中 expectedCount = 38）。其目标非常聚焦：为付费投放活动规划和产出广告概念、文案变体、视觉方向与测试矩阵，覆盖从策略到成稿再到可验证测试的完整链路。

与技能配套的清单文件 skill.json 定义了它的元数据与触发方式：

{
  "id": "ad-creative",
  "name": "Ad Creative",
  "version": "1.0.0",
  "description": "Plan and produce advertising concepts, copy variants, visual directions, and test matrices for paid campaigns.",
  "entry": "SKILL.md",
  "triggers": {
    "commands": ["/ad-creative"],
    "promptPatterns": [
      "Ad Creative", "ad creative", "ad-creative",
      "campaign variants", "广告创意", "投放素材"
    ],
    "fileTypes": []
  },
  "allowedTools": [],
  "assets": [],
  "priority": 0
}

要点解读：

• entry: "SKILL.md"：技能正文即 SKILL.md，Agent 会按该文件中的指令行事；
• triggers.commands：在对话中键入 /ad-creative 即可显式唤起；
• triggers.promptPatterns：当用户输入包含"广告创意""投放素材""campaign variants"等词时，技能会被自动激活——注意清单同时收录了中英文模式；
• allowedTools 为空：表示该技能不额外声明工具白名单，路由交由运行时统一处理（见下文"工具路由"）；
• assets 为空：该技能没有附带参考模板或图标资源。

从清单结构看（对应 skill-runtime-contracts.ts 中的 SkillManifest schema），id 必须与目录名一致，校验脚本对此有强制断言（manifest id must match directory name），这保证了技能目录与运行时索引的一一对应。

二、技能如何被装载与激活：理解 bundled skill 的运行机制

ad-creative 之所以能被 Agent 调用，依赖于 Kun 的 Skills 运行时。理解这一点，才能在实际使用中正确配置与排查问题。

2.1 内置技能的资源定位

Kun 通过 bundled-skill-resources.ts 定位内置技能目录：

• 开发模式：<appRoot>/resources/bundled-skills；
• 打包模式：<process.resourcesPath>/bundled-skills。

对应测试见 bundled-skill-resources.test.ts，例如打包场景会解析到 /Applications/Kun.app/Contents/Resources/bundled-skills。

2.2 技能发现、校验与加载

运行时在 skill-runtime-engine.ts 中完成技能发现与激活决策，核心约束包括：

• 目录约定：工作区技能可存放于 .agents/skills、.claude/skills、.codex/skills、.kun/skills 或 skills（见 skill-runtime-contracts.ts），内置技能则来自 builtinRoots；
• 规模限制：清单 skill.json 不超过 64 KiB，入口文件不超过 256 KiB（MAX_SKILL_MANIFEST_BYTES、MAX_SKILL_ENTRY_BYTES），超出会被校验拒绝；
• 安全约束：入口与资源路径必须位于技能包目录内，禁止路径穿越（path traversal 会被记录为 validation error 并跳过该技能，对应测试见 skill-service.test.ts）；
• 三档来源优先级：project（项目级）> global（全局）> builtin（内置只读兜底），用户技能可用同名覆盖内置技能。

2.3 触发与激活评分

当用户发起一轮对话时，SkillRuntime.resolveTurn 会依据技能清单的 triggers 做匹配打分：

触发类型	说明	基础分
显式提及技能名/ID	prompt 中直接出现技能标识	1000 + priority
命令（/ad-creative）	prompt 以命令开头	900 + priority
promptPatterns 子串匹配	如"广告创意""campaign variants"	500 + priority
fileTypes	命中指定文件类型	300 + priority

匹配结果按分数排序后，取前 DEFAULT_ACTIVE_LIMIT = 3 个技能注入系统提示，并受 DEFAULT_INSTRUCTION_BUDGET_BYTES = 24_000 的字节预算约束（见 skill-runtime-contracts.ts）。

除了自动触发，Kun 还提供 load_skill 工具（实现在 skill-tool-provider.ts），允许 Agent 在 catalog 中看到某个技能但自动触发未命中时，主动按 skill_id 拉取完整指令——这是"Ad Creative"类请求兜底激活的常用路径，加载后的技能会以 load_skill 理由记入当前回合的激活列表。

2.4 启用前提

技能能力默认关闭，需要在配置中开启。以 config.example.json 为参考：

"capabilities": {
  "skills": {
    "enabled": true,
    "roots": [],
    "legacySkillMd": true
  }
}

• enabled：是否启用 Skills 运行时（false 时 load_skill 不可用、自动激活不生效）；
• roots：额外的技能根目录；
• legacySkillMd：是否兼容仅含 frontmatter 的旧式 SKILL.md。

三、工具路由：三个生成工具的分工与底层实现

ad-creative 技能将产出任务路由到三个工具，它们各有明确的职责边界：

工具或技能	用途
generate_image	每次调用生成一个视觉概念或细化版本
generate_video	仅在明确需要视频时，创建短时运动素材
render_chart	用结构化数据呈现测试结果或变体排名

下面分别结合源码说明其能力与限制。

3.1 generate_image：单次单图、可迭代

工具实现在 image-gen-tool-provider.ts，其设计原则是"一次调用只生成一张图，需要变体就再调用一次"（Generates exactly one image per call; call again for variations）。核心入参：

• prompt（必填）：图像的详细描述；
• aspect_ratio：可选，标准档位为 1:1、4:3、3:4、16:9、9:16、3:2、2:3、21:9；Grok Imagine 协议额外支持 2:1、1:2、19.5:9 等；
• image_size：可选分辨率覆盖，默认协议支持 1K/2K，Volcengine Ark 支持 2K/3K/4K——只在用户明确要求时传，否则交给设置中的默认分辨率；
• reference_image_paths / reference_attachment_ids：仅在协议真正支持图生图时提供（OpenAI-compat、Codex Responses、Volcengine Ark），用于给生成提供参照；MiniMax 的 subject_reference 属于身份/角色保持而非通用编辑，路由时会直接拒绝带参考图的编辑请求并提示重试（源码中 protocolSupportsImageEdit 的判定逻辑）。

生成结果统一保存到工作区 .kun/images/ 目录（见 generated-image-path.ts 中 KUN_GENERATED_IMAGE_DIR = '.kun/images'），并作为内联附件回显给 Agent——SKILL.md 的完成门禁要求"交付前检查生成媒体"，正是依赖这一回显能力。

对应的配置契约见 capabilities-media.ts：protocol 默认 openai-images、defaultResolution 默认 1K、quality 默认 auto、timeoutMs 默认 180000、maxReferenceImages 默认 4。

3.2 generate_video：短时动态素材

实现在 media-gen-tool-provider.ts，SKILL.md 强调"仅当视频明确被需要时才使用"——视频生成成本高、耗时长，属于按需工具。其入参包括：

• prompt（必填）；
• duration：默认协议 1–30 秒；Grok Imagine 仅支持 6/10 秒；Volcengine 4–15 秒；
• resolution：默认协议 768P/1080P；Grok 480P/720P；Volcengine 到 4K；
• first_frame_image_path / last_frame_image_path：可选首尾帧参考图（png/jpeg/webp，10 MB 以内，必须位于工作区内）；
• aspect_ratio：部分协议（Grok、Volcengine）支持。

生成结果保存至工作区 .deepseekgui-videos/。配置侧默认 defaultDuration = 6、defaultResolution = 1080P、timeoutMs = 900000、pollIntervalMs = 10000（capabilities-media.ts）。

3.3 render_chart：结构化数据的可视化呈现

实现在 chart-tool-provider.ts，用于把测试结果、变体排名等结构化数据渲染为受控图表。它的几条硬性约束直接呼应 ad-creative 的"测试矩阵"产出：

• 先结论后图表：在图表前先用文字陈述结论（State the conclusion in text before the chart）；
• 拒绝装饰性使用：用户只要纯文本或纯表格时不调用；
• GUI 限定：仅在 GUI 会话且启用 Lab 会话可视化时可用（render_chart is available only in the GUI...）；
• 渲染归 Kun：Agent 只提供结构化数据与语义化呈现意图（ChartSpecV1），不提供 HTML/CSS/JS 或图表库选项。

四、五步工作流：从需求萃取到可测试变体

SKILL.md 定义了严格的生产流程，这是本技能的方法论核心，实际执行时应按序推进、不可跳步：

1. 萃取要素（Extract）：先提取投放的 offer（产品/服务卖点）、audience（受众）、channel（渠道）、objective（目标）、constraints（约束）与 proof points（证据点）。这一步是后续一切产出的地基——缺少任何一项，后续概念与文案都可能跑偏；
2. 先定义单一信息层级（Message hierarchy）：在产出任何变体之前，先确定一条主信息（hero message）及其支撑层级。没有 hierarchy 就批量产出文案，只会得到一盘散沙；
3. 创造真正不同的概念（Distinct concepts）：要求产出的是彼此有结构差异的概念，而不是"同义词替换"式的表面改动（Create distinct concepts rather than superficial synonym swaps）——这是衡量创意质量的关键标准；
4. 匹配投放位（Match placement）：文案长度与格式必须匹配目标投放位（如搜索广告字符限制、信息流图文规格、视频时长），避免"一套文案通吃所有渠道"；
5. 为每个可测变体挂上假设与成功指标（Hypothesis + success metric）：每个变体都必须附带一个可验证的假设（如"强调价格透明可提升点击率"）与一个成功指标（CTR、CVR 等），从而形成真正的测试矩阵。

完成后，用 render_chart 将变体排名或测试结果从结构化数据渲染为图表，即可形成"假设 → 产出 → 测试 → 可视化复盘"的闭环。

五、完成门禁：交付前的三条检查线

SKILL.md 明确了三项必须全部通过的完成门禁（completion gates），属于强制性要求：

• 证据核对（Claims vs evidence）：所有声明都必须对照用户提供的证据核验。任何无法从证据推导出的说法（效果承诺、背书、价格、稀缺性）都不能写进素材；
• 合规核对（Constraints）：逐项检查品牌（brand）、平台（platform）、法律（legal）与无障碍（accessibility）约束。例如平台广告政策、可读性/对比度、敏感品类限制等；
• 媒体检查（Media inspection）：凡是生成过图片/视频的，交付前必须检查实际生成结果——依托 generate_image/generate_video 的内联回显与 .kun/images/、.deepseekgui-videos/ 目录中的产物核对，不合格就再次调用工具细化，而不是直接交付。

六、边界与交付规范：Agent 的合规护栏

技能对 Agent 的行为边界做了明确限定，这也是使用时应向 Agent 强调的硬约束：

边界（Boundaries）

• 不得虚构背书（endorsements）、性能声明（performance claims）、价格（prices）或稀缺性（scarcity）——这些都属于"未经证据支撑的声明"；
• 除非用户明确要求执行外部动作，否则不得发布或启动广告活动（Do not publish or launch a campaign unless the user explicitly requests the external action）。也就是说，Agent 的职责止于"产出素材与方案"，不越界到真实投放。

交付（Delivery）

• 结论先行：先给出最终产出/核心结论；
• 点名证据：说明验证所依据的证据是什么（对应"完成门禁"第一条）；
• 披露局限：如实披露仍存在的真实限制（如"该视觉方案尚未经过 A/B 测试""转化数据待投放验证"），不掩盖不确定因素。

七、实战组合示例：一次完整的 ad-creative 使用

结合上述机制，一个典型的使用路径如下：

1. 在 Kun 中确保 capabilities.skills.enabled = true，并配置好 capabilities.imageGen（protocol、baseUrl、apiKey、model）与可选 capabilities.videoGen；
2. 输入含"广告创意"或"投放素材"的提示词（或直接使用 /ad-creative 命令），触发技能自动激活；若未自动激活，Agent 可通过 load_skill（skill_id: "ad-creative"）主动加载指令；
3. Agent 按五步工作流萃取 offer/audience/channel/objective/constraints/proof points，产出信息层级与 3–5 个结构差异明确的概念；
4. 对每个概念调用 generate_image 生成视觉方向（一次一图，不满意再调用细化），必要时用 generate_video 产出短时动态素材；
5. 为每个变体标注假设与成功指标，形成测试矩阵；如需可视化呈现变体排名，在 GUI 会话中用 render_chart 渲染；
6. 交付前逐条执行完成门禁（证据、品牌/平台/法律/无障碍、生成媒体检查），按"结论先行 + 点名证据 + 披露局限"的格式输出，且不执行任何真实投放动作。

结语

ad-creative 是 Kun 内置技能体系中面向营销投放场景的典型代表：它把"创意产出"这一原本高度依赖经验判断的工作，拆解成可执行、可验证、可量化的 Agent 流程。从技能清单（skill.json）到运行时激活评分（skill-runtime-engine.ts），再到三个生成工具的底层实现（image-gen-tool-provider.ts、media-gen-tool-provider.ts、chart-tool-provider.ts），整条链路在仓库中均可追溯验证。理解技能指令与运行机制的双层结构，是在实际项目中正确使用并扩展内置技能的前提。