ZenlessZoneZero-OneDragon (Agent Skills)

# AGENTS.md

本文件是项目级 AI 编码协作入口，只保留会直接影响实现落点与提交流程的约束。
详细规范与背景资料不要堆在这里，按需继续阅读：
- 开发环境与打包：[docs/develop/README.md](docs/develop/README.md)
- 详细编码规范：[docs/develop/spec/agent_guidelines.md](docs/develop/spec/agent_guidelines.md)
- 一条龙整体架构：[docs/develop/one_dragon/one_dragon_architecture.md](docs/develop/one_dragon/one_dragon_architecture.md)
- 应用插件开发指引：[docs/develop/guides/application_plugin_guide.md](docs/develop/guides/application_plugin_guide.md)
- 应用设置界面开发指引：[docs/develop/guides/application_setting_guide.md](docs/develop/guides/application_setting_guide.md)

## 项目概述

- 项目：绝区零一条龙（ZenlessZoneZero-OneDragon），面向 Windows 的绝区零自动化工具。
- 语言与环境：Python 3.11、uv、PySide6。
- 代码布局：`src-layout`，源码在 `src/`，运行时配置在 `config/`，资源在 `assets/`，开发文档在 `docs/develop/`。
- 运行基准：1080p；配置以 YAML 为主。
- 所有测试统一在独立仓 `zzz-od-test/test/`(`.gitignore`,须 clone 到仓库根目录才能读/改;clone 见 [quickstart §②](docs/develop/setup/quickstart.md),测试规范见 [testing/](docs/develop/testing/README.md))。主仓不保留测试。AI 查测试用 `Read`/`grep` 显式指定 `zzz-od-test/`(默认搜索会跳过 .gitignore)。
- 相关仓库全貌(测试仓 / yolo 训练仓 / 数据集 / 官网 blog)见 [相关仓库](docs/develop/setup/repositories.md);外部贡献者需 fork 后开发。

## 常用命令

```shell
uv sync --group dev
uv run --env-file .env src/zzz_od/gui/app.py
uv run --env-file .env pytest zzz-od-test/
uv run --env-file .env ruff check src/你修改的文件.py
uv run --env-file .env ruff check --fix src/你修改的文件.py
```

- 只对自己修改的文件运行 `ruff check`。
- 不要对整个 `src/` 目录运行 ruff，现有仓库尚未全面适配。
- 优先使用 Windows PowerShell 可直接执行的命令。

## 架构落点

### 1. 核心分层

- `src/one_dragon/`：通用基础框架、配置、环境、工具、YOLO 能力。
- `src/one_dragon_qt/`：通用 Qt GUI 框架与公共组件。
- `src/onnxocr/`：OCR 引擎。
- `src/zzz_od/`：绝区零业务代码，包括 application、operation、context、gui、yolo 等。

### 2. 功能开发优先路径

- 新功能优先评估是否应做成 `Application`，放在 `src/zzz_od/application/`，并通过 `ApplicationFactory` 接入。
- 不要直接把新流程硬塞进主线逻辑；先复用现有 Application、Operation、配置体系与界面组件。
- 新的设置界面优先沿用现有 setting card、`YamlConfigAdapter`、`AdapterInitMixin` 等模式。

### 3. 关键运行机制

- `ZContext` 管理懒加载服务与配置；实例级配置变更要走 `reload_instance_config()` 对应机制。
- 这里的 `Operation` 指框架里的基础操作单元；文档里提到的“流转 / flow”是由这些 `Operation` 节点组成的执行链。
- 操作链基于 `ZOperation` / `Operation` 编排；状态流转沿用现有 round 系列接口与节点声明方式。
- GPU/onnx session 的异步调用必须通过 `gpu_executor.submit`，不要并发直调多个 session。

## 开发流程（端到端）

**涉及游戏流程的改动(新功能 / debug / 修 bug)—— 先理解玩法 + 画面,再动手;知识缺失主动补档**:
- 先读 gameplay(玩法机制)+ screen(画面)doc + screen_info + 相关代码,弄清「自动化当前走到哪个画面、按什么玩法逻辑走」。
- 知识缺失 / 过期(没建档、doc 陈旧、screen_info 没该画面)→ 主动按 skill 补档(画面 `zzz-od-dev-screen-onboarding`、玩法 `zzz-od-dev-gameplay-onboarding`),别凭猜改。
- 判据:改动碰自动化与游戏的交互 / 游戏机制 → 适用;纯代码改动(重构 / 性能 / UI / 基建)不适用。详细判据见 [development_workflow.md](docs/develop/development_workflow.md)。
- 为什么:不理解就改 → 只覆盖一种情况、漏另一种 → 回归(battle_fail rect 教训)。

游戏自动化功能的开发链路(涉及游戏流程的 bug 修复 / debug 也走这流程;纯代码改动不强制):

1. **画面建档**(涉及新画面时):按 `zzz-od-dev-screen-onboarding` skill 截图 / 分析 / 建模 / 留档。功能知识按**四文档分工**(gameplay 玩法 / mechanics 通用机制 / screen 画面 / develop application 自动化,见 [doc_organization.md](docs/develop/harness/doc_organization.md))。
2. **开发**:做成 `Application`(`ApplicationFactory` 接入)+ `Operation`,复用现有配置 / 界面模式(架构细则见上方「功能开发优先路径」)。
3. **测试**:用留档截图在测试仓补流程测试(见 [testing/](docs/develop/testing/))。
4. **提 PR**:assign **DoctorReid / ShadowLemoon**,按 `zzz-od-dev-pr-finishing` skill 走 review / resolve。
5. **配套(按需)**:模型 → [yolo/dataset 仓](docs/develop/setup/repositories.md);使用说明 → blog(**用户可见变化**才更新)。

## 开发硬约束

- 所有函数签名、类成员变量都要有类型注解；使用 `list[str]`、`X | Y`。
- 注释与 docstring 用中文，保持现有项目风格。
- 禁止相对导入；仅类型注解使用 `TYPE_CHECKING` 导入。
- `__init__.py` 默认不要暴露模块，除非已有明确模式或收到明确要求。
- 构造函数显式声明参数，不要用 `**kwargs`。
- 路径操作使用 `pathlib`，字符串格式化使用 f-string。
- GUI 优先复用 `pyside6-fluent-widgets` 与现有项目组件，保持 Fluent Design。
- 配置改动优先落到 YAML 与对应 `YamlConfig` 子类，不要随意散落硬编码配置。
- 1080p 坐标属于项目既有前提，可以按现有模式硬编码，不要额外做分辨率适配设计。
- **直白表述，禁自造黑话**：写文档 / skill / 代码注释 / 入口文件 / commit / PR 回复等**任何给人或 AI 读的文字**，用大白话。不造自造词、项目内部缩写、中英混杂的隐喻（反例：`load-bearing` / `bedrock` / `抓手` / `赋能` 这类）。行业通用术语可用，但**首次出现的项目术语给定义 + 例子**；一个词要解释半天别人才能懂，多半是自己还没想清 —— 先想清再换成大家都认的词。详见 [context_layering](docs/develop/harness/context_layering.md)。

## 文档与测试要求

- 修改代码后，同步更新对应的 `docs/develop/` 文档与 `zzz-od-test/` 测试。
- 测试方法论（测试基建 / FixtureController 流程测试 / 画面截图存档）见 [docs/develop/testing/](docs/develop/testing/README.md)。
- 若测试依赖截图或环境变量，按 [docs/develop/README.md](docs/develop/README.md) 中说明准备 `.env` 与测试仓。
- 提交前至少验证自己改动直接影响的部分；若无法本地完成，要明确说明缺失前提。
- 复杂功能、架构调整或新自动化流程，先补设计/说明文档，再继续实现。

## 提交流程与协作边界

- 默认不要主动执行 `git commit`、`git push`、`git reset`、删分支等版本控制操作，除非用户明确要求。
- 测试改动在独立仓 `zzz-od-test` 提交:主仓 `git add zzz-od-test/...` 会被 `.gitignore` **静默跳过**(不报错但未加入)→ 须 `git -C zzz-od-test add test/ && git -C zzz-od-test commit` 单独提交,否则 PR 丢测试。
- **两仓协同**(涉及测试仓改动时,主仓 + 测试仓配对;详见 [development_workflow.md](docs/develop/development_workflow.md) §4):
  - **同分支**:测试仓建同名分支(`feat/xxx` ↔ `feat/xxx`),测试改动落测试仓,不进主仓。
  - **配对提交**:主仓 commit + `git -C zzz-od-test commit` 同步推进,别只提交一仓。
  - **同开关联 PR**:开主仓 PR 时同开测试仓 PR,PR 描述互相挂链接(**跨仓链接用 `OneDragon-Anything/<repo>#<N>` 或完整 URL,禁裸 `#N`** —— 裸 `#N` 会被 GitHub 识别成本仓而非目标仓);别让测试仓分支挂着改动却没开 PR(主仓合了才补测试仓 = 漏)。
  - **合并顺序:测试仓先 → 主仓后**(主仓 main 的 test-check clone 测试仓 main,测试仓先合才稳)。
- 如果用户明确要求切换分支，先 `stash` 当前改动，再切换。
- **commit / PR 规范**(依据 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)):
  - **单个迭代 commit**(开发过程,会被 squash 压掉):写清这步干嘛即可,不强制格式;建议带 type 前缀(`fix:` / `docs:` / `chore:` / `wip:`)方便扫,但不要求 scope / 长度 / body。判据:不看 diff 也能知道这步干了啥(✅ `fix: Y 坐标分母` ❌ `update`)。
  - **PR title**:`type(scope): subject`(≤50、祈使句、无句号;type ∈ `feat / fix / docs / refactor / test / chore / perf / build / ci / style`,scope = 模块;PR 号不进 subject,squash 自动追加 `(#NNNN)`)—— = squash/merge commit 标题。
  - **PR description**(开 PR 时作者写,= commit body):写:
    - **为什么改**(why):解决什么问题 / 目标 + 非显然的决策(为什么这么做);1-3 句,不写实现细节(how 看代码)。
    - **改动要点**(what):多个改动**分行**(bullet,每条动宾简短,说清改了什么);可按 新增 / 变更 / 修复 / 移除 分组;只实质改动,不展开 how。
    - **关联**:`Closes #N`(本仓 issue)/ 测试仓 PR 用 `OneDragon-Anything/zzz-od-test#N`(跨仓全名,禁裸 `#N`)。
  - **merge 时**:commit message = PR title + description(取整段 desc)。作者按上面写好就直接 merge;不符合规范时(贡献者没按规范写、缺 why 等),合并者 merge 时编辑 commit message(网页 squash 框)按规范编写 —— why + 改动要点 + 关联。
  - **rebase / 直推**(无 merge commit,不进 squash/merge):靠 commit 本身规范。
- Review 关注逻辑错误、运行时崩溃、死循环、资源泄漏；不要为风格问题大改现有代码。
- 提交 PR 后，review comment 需要逐条回复或修正。

## 自维护指南（改 AI 入口文件）

`AGENTS.md` / `.claude/CLAUDE.md` / `.github/copilot-instructions.md` 是 **AI 入口文件**（每次会话完整进 context）。改它们时按 [entry_files.md](docs/develop/harness/entry_files.md)：
- **只放指令，不掺元信息**：入口只写给 AI 的指令（做什么）；维护注释 / TODO / 变更说明 → commit / docs，不进入口。
- **只留每次会话总要看的**：逐条问「删了会出错吗」，不会错就砍（入口要精简，不是知识库）；特定任务流程转 skill / 指针。
- **一处维护**：`AGENTS.md` 是源，其他入口（CLAUDE.md 等）`@import` 引入，不复制。
- **共享先确认**：入口文件团队共享，改前问用户，不静默重写。
- **入口文件尤甚**：入口文件每次进 context，更要守上面「开发硬约束」里的「直白表述」规则；术语怎么分层定义见 [context_layering](docs/develop/harness/context_layering.md) / [entry_files](docs/develop/harness/entry_files.md)。

## 改/建 skill

**创建 / 修改任何 skill 前，先触发 `zzz-od-dev-skill-guide`**（即使你正在另一个 skill 的流程里，如改 `zzz-od-dev-screen-onboarding` 时 —— 改 skill = 触发 skill-guide，不论当前在哪个流程）。它的 4 条硬规范里两条最易漏、现普遍未遵循：
- **同步该 skill 的 `design.md`（若有）**：改重要决策时，在该 skill 的 `design.md` 记「为什么这么定」（不只改 SKILL.md），避免后续不知道原意改坏。**这是项目 `zzz-od-dev-*` skill 的约定**（`zzz-od-dev-skill-guide` 规范 1），第三方 / `superpowers:*` skill 无此约定 → **先看 skill 目录有没有 design.md，有就更新**。⚠️ skill **本体在根 `skills/<name>/`**（项目源、稳定）；各 AI 工具用各自方式加载（可能映射 / 链接到别处，那是工具特定的加载路径）→ **查 / 改 skill 文件到本体（根 `skills/`），别查工具的加载映射路径**（映射不一定是真文件，搜索会漏）。
- **SKILL.md 写方法论，不写跟外部代码强相关的具体内容**（函数名 / 测试 API / 具体代码路径 / 行号）—— 易变，外部代码改了 skill 没跟上会误导；**但 runtime 资产路径（docs/game、screen_info 等 skill 读写的操作对象）+ skill 目录内自带工具 + 框架地基级接口名（skill 要搜 / 要调的接口，如 `@operation_node` 装饰器；判据见 `zzz-od-dev-skill-guide` 规范3）可引**；具体例子 / 踩坑进 design.md。

## 产出前先判断：信息放哪、写什么

写 doc / skill 前（以及信息重复、边界不清时），先判断放哪层、写什么，别盲目堆：
- **方法 → skill，具体 → doc**：方法 = 怎么做（建档流程 / 判据 / 排查思路）；具体 = 是什么（键位 / 坐标 / 游戏机制）。详见 [doc_organization](docs/develop/harness/doc_organization.md) + [context_layering](docs/develop/harness/context_layering.md)。
- **玩法 vs 自动化 分开**：玩法机制（玩家视角：目标 / 循环 / 资源）和自动化实现（脚本流程 / config / 节点编排）是两个维度，各进各的 doc、互引不混写。
- **不重复（单一源）**：同一事实只留一处；复述 → 引用；多 doc 共有的共性 → 抽到上一层 doc（如通用机制抽进 `mechanics/`）。
- **分不清 / 不确定 → 问用户，或把判据写进对应方法论 skill**（别含混带过）。

## 深入阅读

只在当前任务确实需要时继续看这些文档：
- AI 协作 harness（知识分层 / 上下文工程）：[harness/README.md](docs/develop/harness/README.md)
- 框架与模块架构：`docs/develop/one_dragon/`、`docs/develop/one_dragon/modules/`
- 游戏业务与专项设计：`docs/develop/zzz/`
- 游戏知识库（给智能体理解游戏）：`docs/game/`（画面描述 `screens/` + 玩法 `gameplay/`）
- 后端服务 / MCP 对外能力：`docs/develop/zzz/backend/`（入口 README；开发 MCP tool 前先看 design-principles）
- 打包与 RuntimeLauncher：`docs/develop/README.md`、`docs/develop/one_dragon/runtime_launcher.md`

---
applyTo: "**"
---

# General Instructions
- **Language**: 请始终使用 **简体中文** 回复。
- **Thinking**: 遇到复杂问题时，优先使用 `sequential-thinking` 工具制定计划。
- **Documentation**: 使用 `context7` 工具查找文档。
- **Environment**: 项目启动前要 `activate uv`，把源根加入 `PYTHONPATH`。
- **项目上下文**: 完整的项目结构、架构概念、编码规范、文档索引请阅读根目录 `AGENTS.md`。

# Coding Standards (Best Practices)
- **Python Version**: 目标 Python 3.11+。使用现代特性（如 `list[str]` 代替 `List[str]`，`|` 代替 `Union`）。
- **Type Hinting**: 所有函数和方法必须包含类型注解 (Type Hints)。
- **Path Handling**: 优先使用 `pathlib` 库处理路径，而非 `os.path`。
- **String Formatting**: 优先使用 f-string 进行字符串格式化。
- **Error Handling**: 避免不必要的 try-catch。除非能进行有意义的处理，否则让异常抛出。
- **KISS Principle**: 保持代码简单。不要增加无用的代码、过度设计或非必要的抽象。
- **Testing/Docs**: 除非明确要求，否则不要主动创建测试脚本或文档。

# Code Review Guidelines (PR Review)
在进行代码审查或生成代码时，请严格遵守以下规则以减少无用的噪音：
1. **环境假设**：本项目主要针对 **1080p 分辨率** 和 **PC 平台**。
   - **允许** 硬编码像素坐标（基于 1080p）。
   - **允许** 硬编码键盘按键（如 '`', 'esc'）。
   - **不要** 建议添加分辨率适配或控制器类型检查，除非逻辑完全错误。
2. **代码风格**：
   - **忽略** 缩进、空行、空格等格式微调（由 Ruff/Linter 处理）。
   - **允许** 在逻辑简单时使用 Magic Number（如 `1000`），不要强制要求提取常量。
3. **审查重点**：
   - **只关注**：严重的逻辑错误、死循环、潜在的运行时崩溃 (Runtime Error)、资源泄漏。
   - **不关注**：代码风格、过度工程化的“最佳实践”、非必要的抽象。

---
name: agent-definition
description: 角色模板配置指南 - 在一条龙中新增可自动战斗角色所需的 Agent 定义、头像模板、状态模板与自动战斗配置
version: 1.1.0
author: OneDragon-Anything
tags: [zzz, agent, character, auto-battle, development]
---

# 新增角色配置指南

新增一个可被自动战斗识别和使用的角色，通常包含四层：

1. `AgentEnum` 角色定义
2. 头像模板
3. 角色状态模板
4. 自动战斗 YAML

如果只是让程序“认识这个角色”，做到第 1、2 层即可；如果要写完整自动战斗模板，还要补第 3、4 层。

## 1. Agent 定义

文件：`src/zzz_od/game_data/agent.py`

### 1.1 基础枚举

当前可用职业：

```python
AgentTypeEnum.ATTACK   # 强攻
AgentTypeEnum.STUN     # 击破
AgentTypeEnum.SUPPORT  # 支援
AgentTypeEnum.DEFENSE  # 防护
AgentTypeEnum.ANOMALY  # 异常
AgentTypeEnum.RUPTURE  # 命破
```

当前可用属性：

```python
DmgTypeEnum.ELECTRIC
DmgTypeEnum.ETHER
DmgTypeEnum.PHYSICAL
DmgTypeEnum.FIRE
DmgTypeEnum.ICE
DmgTypeEnum.WIND
```

稀有度：

```python
RareTypeEnum.S
RareTypeEnum.A
```

### 1.2 在 `AgentEnum` 注册角色

```python
class AgentEnum(Enum):
    MY_AGENT = Agent(
        'my_agent',                  # agent_id，全局唯一，使用 snake_case
        '中文名',                     # 游戏内中文名
        RareTypeEnum.S,
        AgentTypeEnum.ATTACK,
        DmgTypeEnum.FIRE,
        ['my_agent'],                # template_id_list，头像模板 ID 列表
    )
```

如果角色有皮肤头像或不同 UI 头像，把所有模板 ID 放进 `template_id_list`：

```python
['my_agent', 'my_agent_skin_name']
```

`Agent.template_id` 运行时会根据皮肤配置切换；不要只在代码里写死一个新皮肤模板。

## 2. 头像模板

头像模板用于识别当前队伍、连携技、快速支援和部分界面。

### 2.1 战斗头像

路径：`assets/template/battle/`

常用目录：

| 目录 | 用途 |
|---|---|
| `avatar_1_<template_id>/` | 前台头像 |
| `avatar_2_<template_id>/` | 后台头像 |
| `avatar_chain_<template_id>/` | 连携技头像 |
| `avatar_quick_<template_id>/` | 快速支援头像 |

每个模板目录通常包含：

```text
mask.png
raw.png
```

以现有角色模板为准复制结构。模板 ID 要与 `Agent.template_id_list` 中的值一致。

### 2.2 其他界面头像

| 路径 | 用途 |
|---|---|
| `assets/template/hollow/avatar_<template_id>/` | 空洞界面头像 |
| `assets/template/predefined_team/avatar_<template_id>/` | 预设队伍头像 |

不是所有角色都必须立刻补齐所有界面头像；缺哪类模板，就会在哪类场景识别不到。

## 3. 角色状态定义

角色独有资源条、层数、特殊状态写在 `Agent.state_list`。

```python
MY_AGENT = Agent(
    'my_agent',
    '中文名',
    RareTypeEnum.S,
    AgentTypeEnum.ATTACK,
    DmgTypeEnum.FIRE,
    ['my_agent'],
    state_list=[
        AgentStateDef(
            '中文名-资源名',
            AgentStateCheckWay.FOREGROUND_COLOR_RANGE_LENGTH,
            template_id='my_agent',
            hsv_color=(0, 255, 255),
            hsv_color_diff=(30, 80, 80),
            max_length=120,
        ),
    ],
)
```

### 3.1 `AgentStateDef` 常用参数

| 参数 | 说明 |
|---|---|
| `state_name` | 状态名，会进入自动战斗状态系统 |
| `check_way` | 检测方式 |
| `template_id` | 对应 `assets/template/agent_state/<template_id>/` |
| `lower_color` / `upper_color` | RGB 范围 |
| `hsv_color` / `hsv_color_diff` | HSV 中心值与容差 |
| `connect_cnt` | 连通块或像素数量阈值 |
| `split_color_range` | 条形资源中间有空隙时，用于切分 |
| `max_length` | 资源条满值对应长度或最大值 |
| `min_value_trigger_state` | 最小触发值；为 0 时可用于清除/记录 0 值 |
| `template_threshold` | 模板匹配阈值 |
| `clear_on_zero` | 检测值为 0 时是否清除状态 |

### 3.2 采集 HSV 样本

颜色范围无法从静态模板确定时，按以下步骤验证：

1. 确保目标代理人在战斗画面中，状态区域与实际队伍位置一致。
2. 运行采集脚本；脚本会从 `AgentEnum` 的 `state_list` 自动读取状态定义，并匹配已配置的状态模板区域和掩码。

   ```shell
   uv run python skills/agent-definition/collect_agent_state_hsv.py --agent <agent-id>
   ```

3. 脚本默认每 0.02 秒截图一次，采集 1 秒后输出每个状态的 H、S、V 连续区间；跳过坐标无效的模板区域。
4. 从输出中区分资源颜色主区间和灰色背景、UI 边缘产生的零散区间。`hsv_color` 是中心值，`hsv_color_diff` 是三通道容差，实际范围为“中心值 ± 容差”。
5. 以 H 作为主要颜色判据，按资源色相主区间设置较窄范围；S、V 应留出更宽的容差以覆盖抗锯齿、亮暗变化和特效。V 下限仍须排除暗色背景。
6. 设定范围后，分别在资源可用、资源消耗中和资源不可用的画面重新运行或实测检测结果；只在可用状态命中才可采用。

脚本不发送游戏输入，也不写入采样文件。

### 3.3 常用检测方式

| `AgentStateCheckWay` | 用途 |
|---|---|
| `COLOR_RANGE_CONNECT` | RGB/HSV 范围内找连通块数量 |
| `COLOR_RANGE_EXIST` | 指定颜色范围是否出现 |
| `FOREGROUND_COLOR_RANGE_LENGTH` | 彩色前景条长度 |
| `FOREGROUND_GRAY_RANGE_LENGTH` | 灰白前景条长度 |
| `BACKGROUND_GRAY_RANGE_LENGTH` | 通过背景灰度反推条长度 |
| `TEMPLATE_FOUND` | 模板存在 |
| `TEMPLATE_NOT_FOUND` | 模板不存在 |
| `COLOR_CHANNEL_MAX_RANGE_EXIST` | 某颜色通道最大值范围是否出现 |
| `COLOR_CHANNEL_EQUAL_RANGE_CONNECT` | 三通道相等像素连通块数量 |

## 4. 角色状态模板

路径：`assets/template/agent_state/`

目录名由 `AgentStateDef.template_id` 和识别位置共同决定：

- 未传入队伍位置时，直接使用 `template_id`。
- 角色独有状态会传入 `total` 和 `pos`，实际读取 `template_id_3_<pos>`；双人队伍的 2 号位读取 `template_id_2_2`。

因此一个角色独有状态通常需要准备这些目录：

```text
assets/template/agent_state/my_agent_3_1/
assets/template/agent_state/my_agent_3_2/
assets/template/agent_state/my_agent_3_3/
assets/template/agent_state/my_agent_2_2/   # 双人 2 号位需要时
```

每个目录内包含：

```yaml
sub_dir: agent_state
template_id: my_agent
template_name: 角色状态-中文名-资源名
template_shape: rectangle
auto_mask: true
point_list:
  - 100, 100
  - 220, 120
```

坐标基准是项目默认 1080p。不要为新增角色额外设计分辨率适配。

## 5. 自动战斗 YAML

如果要让角色可被通用自动战斗使用，继续补：

```text
config/
├── auto_battle_operation/       # 底层连招动作
├── auto_battle_state_handler/   # 中层状态决策
└── auto_battle/                 # 顶层战斗模板
```

常见接入点：

1. 新增角色操作模板：`config/auto_battle_operation/<角色名>-*.yml`
2. 新增角色状态模板：`config/auto_battle_state_handler/<角色名>.yml`
3. 注册到角色分派器：`config/auto_battle_state_handler/速切模板-全角色.yml`
4. 纳入轮换逻辑：`轮换-合轴-全角色.yml`、`轮换-紧急-全角色.yml`

自动战斗 YAML 语法见 `skills/agent-auto-battle-config/SKILL.md`。

## 6. 推荐顺序

1. 在 `AgentEnum` 新增角色定义。
2. 添加基础战斗头像模板，让战斗中能识别队伍成员。
3. 运行识别或进入战斗观察角色识别是否稳定。
4. 如有专属资源条，添加 `AgentStateDef` 和 `agent_state` 模板。
5. 用图像分析/模板工具调色值、区域和阈值。
6. 编写角色操作模板和状态模板。
7. 接入全角色分派器与轮换模板。
8. 运行自动战斗验证。

## 7. 常见问题定位

### 7.1 识别不到角色

检查：

- `Agent.template_id_list` 是否包含对应模板 ID。
- `assets/template/battle/avatar_*_<template_id>/` 是否存在。
- `mask.png` 是否遮掉了干扰背景。
- 连携技、快速支援是否分别补了 `avatar_chain_`、`avatar_quick_`。
- 皮肤头像是否使用了另一个 template id。

### 7.2 状态数值不准

检查：

- `template_id` 是否指向正确的 `agent_state` 模板目录。
- `point_list` 是否框住资源条有效区域。
- RGB/HSV 颜色空间是否混用。
- `max_length` 是否等于满条实际长度或最大值。
- `connect_cnt` 是否过高导致小图标识别不到。
- `min_value_trigger_state` 是否需要设为 0 来清除旧状态。

### 7.3 自动战斗不使用新角色逻辑

检查：

- 角色状态模板是否被 `速切模板-全角色.yml` 引用。
- 角色名状态是否与代码生成的 `切换角色-<agent_name>` 一致。
- 操作模板名是否与 `operation_template` 引用一致。
- `states` 条件是否过严，导致分支永远不命中。
- 高优先级 scene 是否抢占了角色分支。

## 8. 校验清单

- [ ] `src/zzz_od/game_data/agent.py` 的 `AgentEnum` 已新增角色。
- [ ] `agent_id` 使用 snake_case，且全局唯一。
- [ ] `AgentTypeEnum`、`DmgTypeEnum`、`RareTypeEnum` 选择正确。
- [ ] `template_id_list` 包含所有头像模板 ID，包括皮肤。
- [ ] 战斗头像模板至少覆盖实际会出现的队伍头像。
- [ ] 连携技/快速支援需要识别时，已补对应模板。
- [ ] 独有状态的 `state_name` 能被自动战斗 YAML 引用。
- [ ] `AgentStateDef.template_id` 与 `assets/template/agent_state/` 目录一致。
- [ ] 自动战斗 YAML 已接入全角色分派器和轮换模板。
- [ ] 修改代码后只对改动文件运行 `uv run --env-file .env ruff check <file>`。