asset-spec

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation

资源规格

如果未提供参数，请检查 design/assets/entity-inventory.md 是否存在：

• 如果存在：读取该文件，找到第一个状态为 "Needed" 但尚无规格文件的实体或屏幕，并使用 AskUserQuestion：
  • 提示：“下一个尚未编写规格的项目是 [name]。要为它生成规格吗？”
  • 选项：[A] 是 — 为 [name] 编写规格 / [B] 选择其他项目 / [C] 到此为止
• 如果没有实体清单：检查 design/assets/asset-manifest.md。如果清单存在，按上述流程读取清单。
• 如果两者都不存在：开始实体与屏幕清单流程（下文的第 0b 阶段），而不是报错退出。

每次调用 AskUserQuestion 都遵循 .claude/docs/automation-modes.md （协作模式始终询问 · 引导模式仅对重大事项询问 · 自主模式记录并继续； automation_always_ask 中的类别始终询问）。注意：实际调用外部图像生成器（调用图像 API）始终需要询问，不受 modes.automation 影响——这是一项不可逆的外部操作，无条件受到保护， 与 external_calls 是否列在 automation_always_ask 中无关。（目前，此技能仅生成 生成提示词文本；如果将来接入实时生成，则此保护仍适用。）

第 0b 阶段：实体与屏幕清单（在无参数且不存在现有清单时运行）

此流程将生成 design/assets/entity-inventory.md——游戏所需视觉资产的主清单。 应在开始编写资产规格前运行一次。

步骤 1 — 从文档中收集信息

并行阅读所有可用源材料，并按文档分节处理：使用 Grep 工具查找所需标题（模式 ^#，内容模式），再通过 offset 和 limit 读取对应范围。

• design/gdd/systems-index.md — 提取其中列出的所有系统
• GDD 资产内容 — 不要完整读取每份 GDD。所需的两个部分均为标准标题，命名实体位于注册表中：

  Grep pattern="## (Visual/Audio Requirements|UI Requirements)" glob="design/gdd/*.md" output_mode="content" -A 25
  

  对于命名实体（角色、敌人、建筑、物品），如果 design/registry/entities.yaml 存在且包含条目，则读取其中的 entities/items；否则，在 GDD 中搜索命名内容。仅当视觉/音频部分缺失或内容为 [To be designed] 时，才完整读取一份 GDD（第 1 阶段已处理这种情况）。VFX 事件会出现在视觉/音频搜索结果的上下文中。
• design/art/art-bible.md — 提取任何具名视觉类别、资产类型要求
• design/narrative/ — 如果存在角色或世界实体文档，则扫描它们（可选，不作要求）

步骤 2 — 编制拟议清单

将找到的所有内容归入以下类别：

Characters / Protagonists
Enemies / Creatures
Buildings / Structures
Environment / Terrain
Items / Props
VFX / Particles
UI Screens (list each screen by name)
HUD Elements
Audio (SFX, music — descriptions only, no generation prompts)
Other

为每个项目注明其来源文档。

步骤 3 — 展示并协作

在对话中向用户展示完整的拟议清单。然后使用 AskUserQuestion：

• 提示：“我在你的 GDD 和艺术圣经中找到了 [N] 个视觉实体和 [N] 个 UI 屏幕。请查看清单——有什么遗漏，或哪些内容不需要？”
• 选项：
  • [A] 看起来不错——保存此清单
  • [B] 添加我描述的项目
  • [C] 删除不适用的项目
  • [D] 既添加也删除——让我编辑

如果选择 [B] 或 [D]：请用户描述其他项目。简短描述（“一座用作关卡背景的中世纪要塞”）或详细描述均可。与用户协作处理，直到用户满意为止。

如果选择 [C] 或 [D]：询问用户要删除哪些项目以及原因。将它们从清单中删除。

第 4 步 — 编写清单

获得用户批准后，询问：“我可以将实体清单写入 design/assets/entity-inventory.md 吗？”

写入文件：

# Visual Entity & Screen Inventory

> Generated: [date]
> Sources: [list of source docs read]

## Entities

| # | Name | Type | Description | Source | Status |
|---|------|------|-------------|--------|--------|
| 1 | [name] | Character / Enemy / Building / Environment / Item / Other | [brief description] | [source doc] | Needed |

## UI Screens

| # | Screen Name | Description | Source | Status |
|---|-------------|-------------|--------|--------|
| 1 | Main Menu | [description] | [source] | Needed |

## HUD Elements

| # | Element | Description | Source | Status |
|---|---------|-------------|--------|--------|

## Audio

| # | Name | Type (SFX / Music / Ambient) | Description | Source | Status |
|---|------|------------------------------|-------------|--------|--------|

写入后，告知用户：

“实体清单已保存。后续步骤：

• 对清单中的每个 UI 屏幕运行 /ux-design [screen name]
• 对每个视觉实体运行 /asset-spec system:[name]、level:[name] 或 character:[name]，具体取决于该实体所属的类别
• 或再次运行 /asset-spec，逐项处理清单”

---

阶段 0：解析参数

提取：

• 目标类型：system、level 或 character
• 目标名称：冒号后面的名称（规范化为 kebab-case）
• 审查模式：如果存在，则为 --review [full|lean|solo]

生效模式是在本技能开头通过 resolve_config --keys review_mode 解析的模式，该命令会应用完整的优先级链；如果没有设置，则遵循 modes.rigor——minimal（默认值）对应 solo，standard 对应 lean，full 对应 full。--review 参数仅覆盖本次运行的模式。

模式行为：

• full：并行启动 art-director 和 technical-artist
• lean：仅启动 art-director——速度更快，跳过技术约束检查
• solo：不启动 Agent——主会话仅根据艺术圣经规则编写规范。适用于简单的资产类别，或速度比深度更重要的情况。

---

阶段 1：收集上下文

在询问用户任何内容之前，先阅读所有源材料。按章节阅读艺术圣经和 GDD：使用 Grep 工具查找所需标题（模式 ^#，内容模式），然后使用 offset 和 limit 读取对应范围。

必须阅读的内容：

• 艺术圣经：读取 design/art/art-bible.md——如果文件不存在，则停止：

  “未找到艺术圣经。请先运行 /art-bible——资产规范以艺术圣经中的视觉规则和资产标准为依据。”

  例外情况——最简路径。 如果没有艺术圣经，但存在 design/game-brief.md（在 rigor: minimal 下不要求提供艺术圣经），则不要停止：以简介中的 Art & audio direction 一行为依据，并在输出开头说明：“以简介中的单行艺术指导为依据；由于没有艺术圣经，以下颜色、形状和资产标准规则均为建议，而非约束。”可将 /art-bible 作为可选项提供一次。书面规范也应遵循同一依据：其标题写为 > **Art direction**: design/game-brief.md (Art & audio direction) — no art bible 以替代 > **Art Bible**: 行；每项资产都应包含 **Brief anchor:** [the brief line applied]，以替代 Art Bible Anchors 块；且规范中不得引用艺术圣经章节或 §8 层级。 提取：视觉识别声明、色彩系统（语义颜色）、形状语言、资产标准（艺术圣经第 8 节——尺寸、格式、多边形数量预算、纹理分辨率等级）。

• 项目配置：从 project.yaml 读取 performance.* 和 naming.*；对于缺失或为空的任何键（包括 project.yaml 中没有 performance 或 naming 块的情况），回退到 .claude/docs/technical-preferences.md。提取性能预算和命名约定。

按目标类型读取源文档：

• system：读取 design/gdd/[target-name].md，提取 Visual/Audio Requirements 部分。如果该部分不存在或内容为 [To be designed]：

  "design/gdd/[target-name].md 的 Visual/Audio 部分为空。请运行 /design-system [target-name] 完成 GDD，或手动描述视觉需求。" 使用 AskUserQuestion：[A] 手动描述需求 / [B] 停止——先完成 GDD

• level：读取 design/levels/[target-name].md。提取 Step 4 中的美术需求、资源列表、VFX 需求和美术指导的制作概念规格。
• character 或 entity：读取 design/narrative/characters/[target-name].md，或在 design/narrative/ 和 design/assets/entity-inventory.md 中搜索匹配的条目。提取视觉描述、角色定位和任何指定的辨识特征。
  • 如果不存在源文档：不要报错。改用 AskUserQuestion：
    • 提示："未找到 [name] 的角色档案。请简要描述一下——一两句话即可。"
    • 选项：[A] 现在描述 / [B] 跳过此实体 / [C] 在此处停止
    • 如果选择 [A]：用户的描述将作为源文档。简短回答生成简洁的规格；详细回答生成详细的规格。接受用户提供的任何详细程度，并据此开展工作。

可选读取：

• 此目标已有的规格：如果存在 design/assets/specs/[target-name]-assets.md，请读取——这是一次重新运行，Phase 2 只提出新增或变更的内容（Phase 5 会就地更新该文件）。
• 现有清单：如果存在 design/assets/asset-manifest.md，请读取——提取此目标已有规格的资源，以避免重复。
• 相关规格：对 design/assets/specs/*.md 执行 Glob——扫描可共享的资源（例如，为某个系统编写规格的通用 UI 元素也可能适用于此处）。

展示上下文摘要：

资源规格：[Target Type] — [Target Name]

• 源文档：[path] — 已识别 [N] 种资源类型
• 美术圣经：已找到 — 第 8 节中的资源标准
• 此目标的现有规格：[已编写规格 [N] 项 / 无]
• 在其他规格中找到的共享资源：[list or "无"]

---

Phase 2：资源识别

从源文档中提取提及的每种资源类型——包括明确提及和隐含提及的内容。

对于系统：查找 VFX 事件、精灵图引用、UI 元素、音频触发器、粒子效果、图标需求，以及任何关于“视觉反馈”的描述。

对于关卡：查找独特的环境道具、氛围 VFX、灯光设置、环境音频、天空盒／背景，以及任何区域专属材质。

对于角色：查找精灵图集（待机、行走、攻击、死亡）、肖像／头像、附加到技能上的 VFX、UI 表现形式（图标、生命条皮肤）。

将资源归入以下类别：

• 精灵／2D 美术 — 角色精灵图、UI 图标、图块集
• VFX／粒子 — 命中效果、环境粒子、屏幕效果
• 环境 — 道具、图块、背景、天空盒
• UI — HUD 元素、菜单美术、字体（如为自定义字体）
• 音频 — SFX、音乐曲目、环境循环音频 （注意：音频规格仅作描述，不包含生成提示词）
• 3D 资源 — 网格、材质（视引擎情况而定）

向用户展示完整的已识别资源列表。使用 AskUserQuestion：

• 提示："我在 [target] 中识别出 [N] 种类别的 [N] 项资源。请在编写规格前进行审核："
• 先在对话文本中展示分组列表
• 选项：[A] 继续——为所有这些资源编写规格 / [B] 移除部分资源 / [C] 添加我遗漏的资源 / [D] 调整类别

在用户确认资源列表之前，不要进入 Phase 3。

---

Phase 3：规格生成

根据审核模式启动专业 Agent。同时发出所有 Agent 调用，不要等待一个调用完成后再启动下一个。

完整模式 — 并行启动：

通过 Agent 启动 art-director：

• 提供：Phase 2 的完整资源列表、艺术圣经中的 Visual Identity Statement、Color System、Shape Language、源文档的视觉要求，以及艺术圣经第 9 节中提及的任何参考游戏／美术风格
• 询问：“请针对列表中的每项资源，提供：（1）一段 2–3 句的视觉描述，描述应以艺术圣经的 Shape Language 和 Color System 为依据，具体到两位不同的美术人员也能创作出一致的效果；（2）一条可直接用于 AI 图像工具的生成提示词（Midjourney／Stable Diffusion 风格——包含风格关键词、构图、色彩方案锚点和负面提示词）；（3）直接适用于该资源的艺术圣经规则（注明章节）。对于音频资源，请描述其声音特征，而非提供生成提示词。”

通过 Agent 启动 technical-artist：

• 提供：完整资源列表、艺术圣经中的 Asset Standards（第 8 节）、性能预算（project.yaml 中的 performance.*，否则使用 technical-preferences.md）、引擎名称和版本
• 询问：“请针对列表中的每项资源，说明：（1）确切尺寸或面数（遵循艺术圣经 Asset Standards 的等级，不要自行设定新尺寸）；（2）文件格式和导出设置；（3）命名约定（project.yaml 中的 naming.*，否则使用 technical-preferences.md）；（4）该资源类型必须遵循的引擎特定限制；（5）适用时的 LOD 要求。若艺术圣经的首选标准与引擎限制冲突，请标出。”

精简模式 — 仅启动 art-director（跳过 technical-artist）。

单人模式 — 两者都跳过。仅根据艺术圣经规则推导规格，并注明技术限制未经验证。

在规格之前，于输出中逐一说明跳过的 Agent 名称： “technical-artist skipped — Lean mode: technical constraints not validated.” / “art-director and technical-artist skipped — Solo mode: specs derived in this session; technical constraints not validated.” 未经 Agent 审核而起草的规格，不得写得像是经过 Agent 审核的。

在进入 Phase 4 前，收集两个 Agent 的回复。 如果 art-director 和 technical-artist 的回复存在任何冲突（例如，art-director 指定 4K 纹理，但 technical-artist 指出引擎预算要求 512px），请明确指出，不要擅自解决冲突。

---

Phase 4：编译与审查

将 Agent 的输出汇总为每项资源的规格草案。按以下格式在对话中展示所有规格：

## ASSET-[NNN] — [Asset Name]

| Field | Value |
|-------|-------|
| Category | [Sprite / VFX / Environment / UI / Audio / 3D] |
| Dimensions | [e.g. 256×256px, 4-frame sprite sheet] |
| Format | [PNG / SVG / WAV / etc.] |
| Naming | [e.g. vfx_frost_hit_01.png] |
| Polycount | [if 3D — e.g. <800 tris] |
| Texture Res | [e.g. 512px — matches Art Bible §8 Tier 2] |

**Visual Description:**
[2–3 sentences. Specific enough for two artists to produce consistent results.]

**Art Bible Anchors:**
- §3 Shape Language: [relevant rule applied]
- §4 Color System: [color role — e.g. "uses Threat Blue per semantic color rules"]

**Generation Prompt:**
[Ready-to-use prompt. Include: style keywords, composition notes, color palette anchors, lighting direction, negative prompts.]

**Status:** Needed

展示所有规格后，使用 AskUserQuestion：

• 提示：“[target] 的资源规格——共 [N] 项资源。是否已完成审查？”
• 选项：[A] 全部批准 — 写入文件 / [B] 修改特定资源 / [C] 按不同方向重新生成

如果选择 [B]：询问要修改哪项资源以及修改内容。直接修改并重新展示。对于细微的文字修改，不要重新启动 Agent——只有视觉方向本身需要改变时才重新启动。

如果选择 [C]：询问要改变什么方向。使用更新后的简报重新启动相关 Agent。

---

Phase 5：写入规格文件

批准后，询问：“可以将规格写入 design/assets/specs/[target-name]-assets.md 吗？”

如果该文件已存在（针对同一目标重新运行），请原位更新，切勿整体覆盖。保留现有的 ASSET-NNN 区块和 ID，仅应用用户批准的修改，并使用项目范围内的下一个 ID 追加新资源。展示变更内容，然后询问“可以更新 design/assets/specs/[target-name]-assets.md 吗？”，而不是询问“可以写入吗？”

按以下内容写入文件：

# Asset Specs — [Target Type]: [Target Name]

> **Source**: [path to source GDD/level/character doc]
> **Art Bible**: design/art/art-bible.md
> **Generated**: [date]
> **Status**: [N] assets specced / [N] approved / [N] in production / [N] done

[all asset specs in ASSET-NNN format]

然后更新 design/assets/asset-manifest.md。如果该文件不存在，则创建：

# Asset Manifest

> Last updated: [date]

## Progress Summary

| Total | Needed | In Progress | Done | Approved |
|-------|--------|-------------|------|----------|
| [N] | [N] | [N] | [N] | [N] |

## Assets by Context

### [Target Type]: [Target Name]
| Asset ID | Name | Category | Status | Spec File |
|----------|------|----------|--------|-----------|
| ASSET-001 | [name] | [category] | Needed | design/assets/specs/[target]-assets.md |

如果清单已存在，则追加新的上下文区块；若针对同一目标重新运行，则将新行添加到其现有区块，而不是追加第二个区块，并更新 Progress Summary 中的计数。

询问：“可以更新 design/assets/asset-manifest.md 吗？”

---

阶段 6：结束

使用 AskUserQuestion：

• 提示词："[target] 的资产规格已完成。接下来要做什么？"
• 选项：
  • [A] 为另一个系统编写规格 — /asset-spec system:[next-system]
  • [B] 为一个关卡编写规格 — /asset-spec level:[level-name]
  • [C] 为一个角色编写规格 — /asset-spec character:[character-name]
  • [D] 运行 /asset-audit — 根据规格验证已交付资产
  • [E] 到此为止

---

资产 ID 分配

资产 ID 在整个项目中按顺序分配，而非按上下文分别分配。分配 ID 前，请先阅读清单以查找当前最高编号：

Grep pattern="ASSET-" path="design/assets/asset-manifest.md"

新资产从 ASSET-[highest + 1] 开始。这样可确保 ID 在整个项目中稳定且唯一。

如果清单尚不存在，则从 ASSET-001 开始。

---

共享资产协议

为资产编写规格前，请检查其他上下文的规格中是否已有等效资产：

• 常见 UI 元素（生命值条、分数显示）通常会在多个系统中共享
• 通用环境道具可能会出现在多个关卡中
• 角色 VFX（受击火花、死亡特效）可能会复用基础规格并采用不同颜色

如果找到匹配项：引用现有的 ASSET-ID，而不要创建重复项。在清单的 referenced-by 列中注明共享用途。

"ASSET-012（通用受击火花）已为 Combat 系统编写规格。正在为 Tower Defense 复用 — 将 tower-defense 添加到 referenced-by。"

---

错误恢复协议

如果任何启动的 Agent 返回 BLOCKED 或无法完成：

1. 立即说明："[AgentName]：BLOCKED — [reason]"
2. 在 lean 模式下，或 technical-artist 受阻时：仅根据 art-director 的输出继续 — 注明技术约束尚未验证
3. 在 solo 模式下，或 art-director 受阻时：根据 art bible 规则推导描述 — 标记为“未咨询美术指导 — 生产前请对照 art bible 验证”
4. 始终生成部分规格 — 绝不因一个 Agent 受阻而丢弃已有成果

---

协作协议

适用于 collaborative 模式（默认模式）。 关于 guided 和 autonomous 模式，请参阅 .claude/docs/automation-modes.md — 以下规则 说明的是协作模式的要求，而非通用行为。

每个阶段均遵循：识别 → 确认 → 生成 → 审查 → 批准 → 写入

• 未先与用户确认资产列表，不得编写资产规格
• 始终以 art bible 为依据 — 与 art bible 矛盾的规格就是错误的
• 明确指出所有 Agent 之间的分歧 — 不要默默地自行取舍
• 仅在获得明确批准后，才写入规格文件
• 写入规格后立即更新清单

---

建议的后续步骤

• 运行 /asset-spec [next-context]，继续为剩余系统、关卡或角色编写规格
• 运行 /asset-audit，根据已编写的规格验证已交付资产，并找出缺漏或不匹配之处