docs: 更新 API 文档并补充技能级局部更新说明

新增技能级 PATCH 接口说明，明确 PUT 浅合并规则与 PATCH 局部更新的适用场景
调整智能体操作流程，补充顶层字段与技能级的不同修改方式指引

put/server/data/api-skill-guide.md

@@ -221,7 +221,7 @@ Content-Type: application/json
 }
 ```
 
-> **注意**：`PUT` 是浅合并。若修改 `skills` 数组，必须传入**完整的新数组**（不能只传被修改的技能对象）。
+> **注意**：`PUT` 是**顶层字段浅合并**。若修改 `skills` 数组，必须传入**完整的新数组**（不能只传被修改的技能对象）。若只需改某个技能的局部字段，请用 `PATCH /api/heroes/:uuid/skills/:skillUuid`（见 §4.7）。
 
 ### 4.6 删除英雄
 
@@ -229,6 +229,41 @@ Content-Type: application/json
 DELETE /api/heroes/5011
 ```
 
+### 4.7 技能级局部更新（推荐智能体使用）
+
+当只需要修改某个技能的局部字段（如调整 lv8 档位的 ap 值）时，使用技能级 PATCH，避免整表替换 `skills` 数组。
+
+**合并规则**：
+- `name`/`cd`/`cdExpr`/`desc`：存在则直接覆盖
+- `overrides`：与现有 `overrides` **浅合并**（不是替换）
+- `lv_entries`：按 `lv` 合并——同 `lv` 更新该档（`overrides` 浅合并），不同 `lv` 新增
+
+```http
+PATCH /api/heroes/5011/skills/6200
+Content-Type: application/json
+
+{
+  "overrides": { "ap": 280 },
+  "lv_entries": [
+    { "lv": 8, "overrides": { "ap": 320 } },
+    { "lv": 20, "s_lv": 4, "overrides": { "ap": 500 }, "desc": "造成{ap}%伤害" }
+  ]
+}
+```
+
+**效果**：
+- 基础 `overrides.ap` 从 250 变为 280
+- `lv_entries` 中 `lv:8` 档的 `overrides.ap` 从 300 变为 320（其他字段保留）
+- `lv_entries` 中新增 `lv:20` 档
+
+**对比：三种修改方式的选择**
+
+| 场景 | 推荐接口 | 原因 |
+|---|---|---|
+| 只改英雄名/稀有度/statBase 等顶层字段 | `PUT /api/heroes/:uuid` | 简单直接，不涉及 skills |
+| 改某个技能的 name/cd/desc/overrides 或某一档 lv_entry | `PATCH /api/heroes/:uuid/skills/:skillUuid` | 避免整表替换 skills，最安全 |
+| 新增/删除技能、改技能 uuid、大规模重构 | `POST /api/heroes/:uuid`（全量覆盖） | 结构变动大，整表替换更清晰 |
+
 ---
 
 ## 5. 智能体操作流程（推荐）
@@ -238,7 +273,8 @@ DELETE /api/heroes/5011
 3. **构造英雄对象**：严格遵循 §3 结构，空组写 `{}`，空数组写 `[]`
 4. **提交**：
    - 新增/覆盖：`POST /api/heroes/:uuid`
-   - 局部修改：`PUT /api/heroes/:uuid`（传完整修改字段）
+   - 顶层字段局部修改：`PUT /api/heroes/:uuid`
+   - 技能级局部修改：`PATCH /api/heroes/:uuid/skills/:skillUuid`
 5. **验证**：`GET /api/heroes/:uuid` 确认数据已写入
 6. **（开发版）应用**：`POST /api/apply` 将 heroes.json 渲染进 `heroSet.ts`（线上设计版无此权限）