# 英雄配置 API 智能体调用规范

> 本文档面向 **Hermes / OpenClaw** 等智能体 Skill，说明如何通过 HTTP API 配置与修改英雄。
> 数据源头为 `heroes.json` / MongoDB，技能/光环/buff 底座定义请阅读 `heroes.json编辑指引.md`。

---

## 1. 服务信息

| 项 | 值 |
|---|---|
| 开发版地址 | `http://localhost:3001`（`MODE=local`） |
| 线上设计版地址 | 部署地址（`MODE=remote`，静态托管 `web/dist`） |
| 内容类型 | `application/json` |
| 认证 | 无（内网/本地环境） |

启动服务（在 `put` 目录）：
```bash
npm run dev          # 开发版
npm run dev:remote   # 线上设计版（本地模拟 remote）
```

---

## 2. 核心接口一览

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/meta` | 获取底座快照（技能/光环/buff/职业模板/版本） |
| `GET` | `/api/heroes` | 获取全部英雄列表 |
| `GET` | `/api/heroes/:uuid` | 获取单个英雄完整配置 |
| `POST` | `/api/heroes/:uuid` | **新增或覆盖**单个英雄（body 为完整英雄对象） |
| `PUT` | `/api/heroes/:uuid` | **局部更新**单个英雄（body 为需修改的字段，顶层浅合并） |
| `PATCH` | `/api/heroes/:uuid/skills/:skillUuid` | **技能级局部更新**：支持按 `lv` 合并 `lv_entries`，避免整表替换 `skills` |
| `DELETE` | `/api/heroes/:uuid` | 删除单个英雄 |
| `POST` | `/api/refresh` | 刷新底座缓存（修改 SkillSet.ts 等后调用） |

> **版本闸门**：线上设计版（remote）在库中 `schemaVersion` 高于服务内置版本时，写操作返回 `409`，需更新部署。

---

## 3. 英雄对象结构（Hero Schema）

智能体在构造或修改英雄时，必须遵循以下字段规范。

### 3.1 顶层字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `uuid` | number | 是 | 英雄唯一 ID，5000 段，新增从 5011 起（先 `GET /api/heroes` 查重） |
| `name` | string | 是 | 显示名 |
| `comment` | string | 否 | 设计说明/机制主题 |
| `path` | string | 是 | 美术资源名，需存在 `assets/resources/game/heros/{path}.prefab` |
| `rarity` | 1~5 | 是 | 稀有度，影响 lv1 基础属性缩放与卡池费用 |
| `roleKey` | string | 是 | 职业：`Tank`/`Warrior`/`Assassin`/`Archer`/`Mage`/`Support` |
| `growKey` | string | 是 | 成长曲线，通常与 `roleKey` 一致 |
| `typeKey` | string | 是 | 攻击定位：`Melee`/`Mid`/`Long` |
| `statBase` | `{hp,ap,def}` | 是 | 相对职业模板的偏移量，惯例 ±5/10/20/30 |
| `dis` / `speed` / `dodge` / `accuracy` | number\|null | 否 | 英雄一般 `null`，走默认 |
| `skills` | array | 是 | **恰好 2 个**：`[普攻, 大招]`，见 §3.2 |
| `atking`/`atked`/`fstart`/`fend`/`dead` | object | 是 | 触发组，见 §3.3；无则写 `{}` |
| `field` | array | 是 | 驻场光环档位，见 §3.4；无则写 `[]` |
| `bonus` | array | 是 | 额外属性加成，见 §3.5；常规英雄写 `[]` |
| `info` | string | 否 | 描述文案 |

### 3.2 skills 数组（恰好 2 项）

每项结构：`{uuid, name, cd, cdExpr, overrides, desc, lv_entries}`

| 字段 | 说明 |
|---|---|
| `uuid` | 技能底座 uuid，普攻必须 ∈ `ROLE_ATK_SKILL[roleKey]`，大招 ∈ `ROLE_ULT_SKILL[roleKey]` 或 `SUPPORT_ULT` |
| `name` | 留空回退底座名；建议起特色名 |
| `cd` | 数值冷却（普攻 0.75/0.9/1.05/1.2/1.5；大招 6/7/8/9/10） |
| `cdExpr` | 表达式，普攻=`AtkSpeedSet[AtkSpeedLv.X].cd`，大招=`UltCdSet[UltCdLv.X].cd` |
| `overrides` | 覆写键值对，见 §3.6 |
| `desc` | 描述模板，支持 `{target}` `{ap}` `{dur}` 等占位符 |
| `lv_entries` | 升级档位：普攻 1 档 `{lv:2,s_lv:2,...}`；大招 2 档 `{lv:8,s_lv:2,...}`、`{lv:16,s_lv:3,...}` |

### 3.3 触发组（atking / atked / fstart / fend / dead）

结构：`{ "<技能uuid字符串>": [条目, ...] }`

条目：`{lv, s_lv, name, t_num, t_chance?, pity_add?, overrides, desc}`

| 字段 | 说明 |
|---|---|
| `lv` | 解锁等级，惯例 **4** |
| `s_lv` | 技能等级，惯例 **1** |
| `t_num` | 触发间隔：atking/atked 为每 n 次；fstart/fend 固定 **1** |
| `t_chance` | 触发概率（0~100），仅 atking/atked 生效，缺省=100 |
| `pity_add` | 保底叠加，仅 atking/atked 生效，触发后清零 |
| `overrides` | 同技能覆写 |
| `desc` | 描述模板，支持 `{t_chance}` `{pity_add}` 占位符 |

**复活**：在 `dead` 组条目 `overrides` 中配置 `revive_hp`（回血%）+ `revive_count`（次数上限）。

### 3.4 field 光环

结构：`[{lv:4, uuids:[{uuid, value, name}], desc?}]`

- `uuid` 必须 ∈ `FieldSkillSet`（7001~7022 段）
- `value` 按光环类型：比例类为小数（如 0.15），次数/固定值类为整数
- 解锁等级惯例 **lv4**

### 3.5 bonus 额外属性

结构：`[{lv, attrs:{...}, name?, icon?, info?}]`

- `attrs` 键：`hp`/`ap`/`def`（百分比，基数=基础×品质+成长）、`crt`/`frz`/`stun`/`para`（固定百分点）
- 运行时累加所有 `lv ≤ 英雄等级` 的档位
- 配 `icon` 的档位在图鉴技能列表最末展示

### 3.6 overrides 白名单

可用键：
`ap, hit_count, hitcd, crt, frz, stun, para, bck, bck_chance, TGroup, buff_type, timed_buff_id, buff_value, buff_duration, buff_chance, buff_target, timed_debuff_id, debuff_value, debuff_duration, debuff_chance, call_hero, summon_count, is_accel, num, revive_hp, revive_count, proc_skill, icon`

特殊格式：
- `TGroup`：字符串 `"Self"`/`"Ally"`/`"Team"`/`"Enemy"`，导出还原枚举
- `buff_target`：数字 0~3（Hit/Self/Ally/Enemy）
- `proc_skill`：对象 `{s_uuid, chance?, overrides?}`
- `icon`：字符串图标帧名

**buff/debuff 语义**：
- `timed_buff_id`：增益，缺省挂施法者自身（伤害技能）或友方目标（辅助技能）
- `timed_debuff_id`：减益，命中后挂被命中者，目标不可覆写
- 对敌挂减益必须用 `timed_debuff_id`，误用 `timed_buff_id` 会把减益挂到自己身上

---

## 4. 调用示例

### 4.1 获取底座数据（修改前必读）

```http
GET /api/meta
```

返回包含 `SkillSet`、`FieldSkillSet`、`BuffList`、`HERO_ROLE_BASE`、`HERO_GROW_COEF`、`AtkSpeedSet`、`HeroDisVal` 等。

### 4.2 查询全部英雄

```http
GET /api/heroes
```

### 4.3 查询单个英雄

```http
GET /api/heroes/5001
```

### 4.4 新增英雄（完整对象）

```http
POST /api/heroes/5011
Content-Type: application/json

{
  "uuid": 5011,
  "name": "烈焰法师",
  "comment": "群体火伤+燃烧",
  "path": "mage_fire",
  "rarity": 4,
  "roleKey": "Mage",
  "growKey": "Mage",
  "typeKey": "Long",
  "statBase": { "hp": -5, "ap": 30, "def": 0 },
  "dis": null,
  "speed": null,
  "dodge": null,
  "accuracy": null,
  "skills": [
    {
      "uuid": 6009,
      "name": "火球术",
      "cd": 1.2,
      "cdExpr": "AtkSpeedSet[AtkSpeedLv.Slow].cd",
      "overrides": { "ap": 120 },
      "desc": "对{target}造成{ap}%伤害",
      "lv_entries": [
        { "lv": 2, "s_lv": 2, "overrides": { "ap": 150 }, "desc": "造成{ap}%伤害" }
      ]
    },
    {
      "uuid": 6200,
      "name": "烈焰风暴",
      "cd": 8,
      "cdExpr": "UltCdSet[UltCdLv.Normal].cd",
      "overrides": { "ap": 200, "timed_debuff_id": 7002, "debuff_value": 30, "debuff_chance": 50 },
      "desc": "对全体敌人造成{ap}%伤害，{debuff_chance}%附加燃烧",
      "lv_entries": [
        { "lv": 8, "s_lv": 2, "overrides": { "ap": 250 }, "desc": "造成{ap}%伤害" },
        { "lv": 16, "s_lv": 3, "overrides": { "ap": 350 }, "desc": "造成{ap}%伤害" }
      ]
    }
  ],
  "atking": {},
  "atked": {},
  "fstart": {},
  "fend": {},
  "dead": {},
  "field": [],
  "bonus": [],
  "info": "掌控火焰的法师"
}
```

### 4.5 局部修改英雄（如只改大招数值）

```http
PUT /api/heroes/5011
Content-Type: application/json

{
  "skills": [
    { "uuid": 6009, "name": "火球术", "cd": 1.2, "cdExpr": "AtkSpeedSet[AtkSpeedLv.Slow].cd", "overrides": { "ap": 120 }, "desc": "对{target}造成{ap}%伤害", "lv_entries": [{ "lv": 2, "s_lv": 2, "overrides": { "ap": 150 }, "desc": "造成{ap}%伤害" }] },
    { "uuid": 6200, "name": "烈焰风暴", "cd": 8, "cdExpr": "UltCdSet[UltCdLv.Normal].cd", "overrides": { "ap": 250, "timed_debuff_id": 7002, "debuff_value": 50, "debuff_chance": 80 }, "desc": "对全体敌人造成{ap}%伤害，{debuff_chance}%附加燃烧", "lv_entries": [{ "lv": 8, "s_lv": 2, "overrides": { "ap": 300 }, "desc": "造成{ap}%伤害" }, { "lv": 16, "s_lv": 3, "overrides": { "ap": 400 }, "desc": "造成{ap}%伤害" }] }
  ]
}
```

> **注意**：`PUT` 是浅合并。若修改 `skills` 数组，必须传入**完整的新数组**（不能只传被修改的技能对象）。

### 4.6 删除英雄

```http
DELETE /api/heroes/5011
```

---

## 5. 智能体操作流程（推荐）

1. **读取底座**：`GET /api/meta`，确认技能/光环/buff 可用值与职业模板
2. **查询现有英雄**：`GET /api/heroes`，确定新 uuid 不冲突（当前已用 5001~5010）
3. **构造英雄对象**：严格遵循 §3 结构，空组写 `{}`，空数组写 `[]`
4. **提交**：
   - 新增/覆盖：`POST /api/heroes/:uuid`
   - 局部修改：`PUT /api/heroes/:uuid`（传完整修改字段）
5. **验证**：`GET /api/heroes/:uuid` 确认数据已写入
6. **（开发版）应用**：`POST /api/apply` 将 heroes.json 渲染进 `heroSet.ts`（线上设计版无此权限）

---

## 6. 错误码与处理

| 状态码 | 场景 | 处理 |
|---|---|---|
| 400 | 参数错误（uuid 非数字、body 非对象/数组、heroes 为空等） | 检查请求格式 |
| 403 | 线上设计版调用本地专属接口（如 `/api/apply`） | 切换至开发版或放弃该操作 |
| 404 | 英雄不存在 | 先 `GET /api/heroes` 确认 uuid |
| 409 | 线上设计版结构版本落后 | 更新部署后再试 |
| 500 | 服务端错误（MongoDB 连接失败、文件读写失败等） | 查看服务日志 |

---

## 7. 常见陷阱（智能体必读）

- **不要手改 `heroSet.ts` 英雄区**：`POST /api/apply` 会整体覆盖标记区内容
- **新增英雄后必须手动把 uuid 加入 `HeroList`**（`heroSet.ts` 标记区之外），否则英雄不进卡池
- **触发组解锁等级是 lv4，大招档位是 lv8+lv16**，不要写 lv6/lv9
- **普攻 cdExpr 用 `AtkSpeedSet`，大招 cdExpr 用 `UltCdSet`**，两套体系不可混用
- **档位 overrides 与基础 overrides 浅合并**，档位只写变化键，不要全量复制
- **desc 用占位符 `{ap}`**，不要硬编码数字，避免与 overrides 数值脱节
- **对敌 debuff 用 `timed_debuff_id`，吸血/自强化用 `timed_buff_id`**，两者目标语义相反
- **复活已废弃独立 `revive` 字段**，改在 `dead` 组 overrides 配 `revive_hp`/`revive_count`

---

## 8. 参考文档

- 详细字段规则与数据源：`put/server/data/heroes.json编辑指引.md`
- 编辑器枚举与默认值：`put/web/src/constants.js`
- 技能底座定义：`assets/script/game/common/config/SkillSet.ts`
- Buff 底座定义：`assets/script/game/common/config/BuffSet.ts`
- 职业模板与成长：`assets/script/game/common/config/heroSet.ts`