# 炸弹人资源包 CLI 2.0

`bomber-assets` 用于生成怪物概念图、管理独立资源文件、校验、构建、上传和下载资源包。调用链为 `CLI -> Creator API -> 火豹 MCP -> Image2.0`，模型和 OSS 密钥只保存在服务器。

机器可读规范：

- [Manifest v2 JSON Schema](/school/docs/asset-pack-v2.schema.json)
- [Creator API OpenAPI](/school/docs/creator-api-openapi.yaml)
- [WorkBuddy 调用示范](/school/docs/workbuddy-bomber-assets-cli.md)

## 1. 安装和登录

需要 Python 3.9 或更高版本。先在 [个人中心](/account#dashboard) 创建 Creator Token，然后下载 [`bomber_asset_cli.py`](/school/cli/bomber_asset_cli.py)：

```powershell
python bomber_asset_cli.py --version
python bomber_asset_cli.py auth set-token
python bomber_asset_cli.py auth whoami
```

Token 保存在 `~/.boooooom/credentials.json`，服务端只保存 SHA-256。删除本地凭据或撤销设备：

```powershell
python bomber_asset_cli.py auth logout
```

## 2. Manifest v2

v2 将资源分为三种用途：

- `concept`：概念图、造型方案和提示词，不能直接作为游戏实体加载。
- `runtime`：包含玩法参数、渲染规格、碰撞箱和动画，可由游戏加载器导入。
- `reference`：只用于学习和参考。

v1 包继续支持浏览和下载；新资源默认创建为 v2。

概念包示例：

```json
{
  "schema": "boooooom.asset-pack/v2",
  "id": "creator.demo.iron-grub",
  "version": "0.1.0",
  "category": "small_monster",
  "packageType": "concept",
  "name": "铁头猪儿虫",
  "description": "头部坚硬、移动缓慢的小怪物概念。",
  "author": "Creator Name",
  "license": "CC-BY-4.0",
  "read_only": false,
  "assets": [
    {
      "id": "preview",
      "path": "assets/preview.png",
      "role": "preview",
      "sha256": "64位小写SHA-256"
    }
  ]
}
```

运行时包还必须声明：

```json
{
  "packageType": "runtime",
  "engine": {"minVersion": "1.0.0"},
  "gameplay": {"hitPoints": 2, "speedMultiplier": 0.5, "behavior": "wall_patrol"},
  "render": {"tileSize": 96, "directions": 4},
  "collision": {"shape": "circle", "radius": 28},
  "animations": {
    "idle": {"asset": "idle_sheet", "frames": 4, "fps": 6, "loop": true}
  }
}
```

游戏加载器只加载 `packageType=runtime` 的声明式数据，不执行用户包中的任意代码。

### 运行包接入游戏

上传为 `runtime` 不会自动进入正式关卡。游戏维护受控登记表，只会为已审核的资源
提供运行包接口；客户端仍会校验资源 ID、类别、生命、速度、碰撞和技能参数。这样公开
展示区的资源保持安全、可下载，不会改变玩家正在进行的关卡。

首个标准接入示例是 `creator.u89f97aeba1cc.sonic-cricket@0.2.0`：个人闯关第 1 关会
用它替换一只普通怪。它以 `gameplay.hitPoints`、`speedMultiplier`、`collision.radius`
和 `gameplay.ability` 的声波预警、眩晕、冷却参数运行。

## 3. 创建概念包

```powershell
python bomber_asset_cli.py new .\packs\iron-grub `
  --id creator.yourname.iron-grub `
  --version 0.1.0 `
  --name "铁头猪儿虫" `
  --category small_monster `
  --package-type concept `
  --author "Creator Name" `
  --description "速度为普通怪物0.5倍，生命值2格的铁头猪儿虫" `
  --license CC-BY-4.0
```

生成概念图并直接挂入资源包：

```powershell
python bomber_asset_cli.py generate `
  --category small-monster `
  --archetype ground `
  --name "铁头猪儿虫" `
  --prompt "设计一只铁头猪儿虫，头甲坚硬，移动速度为普通怪物0.5倍，生命值2格，适合96像素格子动作游戏" `
  --attach .\packs\iron-grub
```

也可以加入已有文件。CLI 会复制文件、计算 SHA-256 并更新 Manifest：

```powershell
python bomber_asset_cli.py asset add .\packs\iron-grub .\art\preview.png `
  --id preview --role preview --path assets/preview.png
```

## 4. 校验、构建和发布

```powershell
python bomber_asset_cli.py validate .\packs\iron-grub
python bomber_asset_cli.py build .\packs\iron-grub `
  --output .\artifacts\creator.yourname.iron-grub-0.1.0.zip
python bomber_asset_cli.py upload .\artifacts\creator.yourname.iron-grub-0.1.0.zip
```

构建是可复现的，并生成 `checksums.sha256`。上传前 CLI 会检查 Manifest、全部资源路径、文件 SHA 和包内清单；服务端会独立重复检查。

资源 ID 首次上传后永久归属该创作者。已发布的 `id + version` 不可改变内容：相同 ZIP 可以幂等重传，内容变化必须提升版本，否则接口返回 `VERSION_IMMUTABLE`。

## 5. 生成任务

最多使用三张本地或公开 HTTPS 参考图：

```powershell
python bomber_asset_cli.py generate `
  --category boss-monster `
  --archetype mechanical `
  --name "熔炉巨像" `
  --prompt "三阶段机械Boss，攻击前核心发红，弱点清晰，适用于格子动作游戏" `
  --reference .\references\shape.png `
  --output .\artifacts\monsters\forge-colossus.png `
  --request-id forge-colossus-v1
```

`--request-id` 用于安全重试，重复提交不会重复生成。后台会持久保存任务状态；每个账号同一时间运行一个任务，默认每日最多 20 次。

## 6. 浏览和下载

```powershell
python bomber_asset_cli.py packs list
python bomber_asset_cli.py packs info official.small-monsters --version 1.0.0
python bomber_asset_cli.py packs download official.small-monsters
```

省略版本时选择最新语义化版本。下载先写入 `.part`，然后校验平台记录的 ZIP SHA-256、Manifest 身份和包内 `checksums.sha256`，全部成功后才生成最终文件。

## 7. 存储和发布规则

- ZIP、预览图和生成原图永久保存到 OSS。
- MySQL 保存作者、摘要、Manifest、SHA-256、任务状态和 OSS Key。
- 新上传作品默认进入[公共展示区](/school/art-animation.html#showcase)。
- 所有者可在[个人中心](/account#dashboard)编辑展示摘要、公开状态或删除作品。
- 页面摘要属于目录信息，不会修改已发布 ZIP 内的不可变 Manifest。
- 官方 `official.*` 包保持只读，只能浏览和下载。

CLI 退出码为 `0` 表示成功，`1` 表示校验、鉴权、网络或服务端操作失败。自动化程序应根据退出码判断结果，不应解析中文错误文本。