Menü
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
npx skills add https://github.com/OneDragon-Anything/ZenlessZoneZero-OneDragon --skill agent-definitionDer Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
当用户要把已开的 PR 推到「完善可合并」、处理 PR/CodeRabbit review、清 unresolved thread、问 PR 能不能 merge / checks 状态时用。英文:finish/get a PR mergeable、address review comments、PR not merging、CI red、unresolved threads。仅 PR 已开后的收尾;单条评论处理用 superpowers:receiving-code-review。
OneDragon ZZZ 脚本速成指南 - 自动战斗 YAML 配置的完整语法与设计模式
排查运行中的自动化 bug(用户反馈某玩法跑失败/卡住/行为异常)、定位根因前用
SKILL.md wird angezeigt
Basierend auf der SOC-Berufsklassifikation
| name | agent-definition |
| description | 角色模板配置指南 - 在一条龙中新增可自动战斗角色所需的 Agent 定义、头像模板、状态模板与自动战斗配置 |
| version | 1.1.0 |
| author | OneDragon-Anything |
| tags | ["zzz","agent","character","auto-battle","development"] |
新增一个可被自动战斗识别和使用的角色，通常包含四层：
AgentEnum 角色定义如果只是让程序“认识这个角色”，做到第 1、2 层即可；如果要写完整自动战斗模板，还要补第 3、4 层。
文件：src/zzz_od/game_data/agent.py
当前可用职业：
AgentTypeEnum.ATTACK # 强攻
AgentTypeEnum.STUN # 击破
AgentTypeEnum.SUPPORT # 支援
AgentTypeEnum.DEFENSE # 防护
AgentTypeEnum.ANOMALY # 异常
AgentTypeEnum.RUPTURE # 命破
当前可用属性：
DmgTypeEnum.ELECTRIC
DmgTypeEnum.ETHER
DmgTypeEnum.PHYSICAL
DmgTypeEnum.FIRE
DmgTypeEnum.ICE
DmgTypeEnum.WIND
稀有度：
RareTypeEnum.S
RareTypeEnum.A
AgentEnum 注册角色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：
['my_agent', 'my_agent_skin_name']
Agent.template_id 运行时会根据皮肤配置切换；不要只在代码里写死一个新皮肤模板。
头像模板用于识别当前队伍、连携技、快速支援和部分界面。
路径：assets/template/battle/
常用目录：
| 目录 | 用途 |
|---|---|
avatar_1_<template_id>/ | 前台头像 |
avatar_2_<template_id>/ | 后台头像 |
avatar_chain_<template_id>/ | 连携技头像 |
avatar_quick_<template_id>/ | 快速支援头像 |
每个模板目录通常包含：
mask.png
raw.png
以现有角色模板为准复制结构。模板 ID 要与 Agent.template_id_list 中的值一致。
| 路径 | 用途 |
|---|---|
assets/template/hollow/avatar_<template_id>/ | 空洞界面头像 |
assets/template/predefined_team/avatar_<template_id>/ | 预设队伍头像 |
不是所有角色都必须立刻补齐所有界面头像；缺哪类模板，就会在哪类场景识别不到。
角色独有资源条、层数、特殊状态写在 Agent.state_list。
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,
),
],
)
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 时是否清除状态 |
颜色范围无法从静态模板确定时，按以下步骤验证：
确保目标代理人在战斗画面中，状态区域与实际队伍位置一致。
运行采集脚本；脚本会从 AgentEnum 的 state_list 自动读取状态定义，并匹配已配置的状态模板区域和掩码。
uv run python skills/agent-definition/collect_agent_state_hsv.py --agent <agent-id>
脚本默认每 0.02 秒截图一次，采集 1 秒后输出每个状态的 H、S、V 连续区间；跳过坐标无效的模板区域。
从输出中区分资源颜色主区间和灰色背景、UI 边缘产生的零散区间。hsv_color 是中心值，hsv_color_diff 是三通道容差，实际范围为“中心值 ± 容差”。
以 H 作为主要颜色判据，按资源色相主区间设置较窄范围；S、V 应留出更宽的容差以覆盖抗锯齿、亮暗变化和特效。V 下限仍须排除暗色背景。
设定范围后，分别在资源可用、资源消耗中和资源不可用的画面重新运行或实测检测结果；只在可用状态命中才可采用。
脚本不发送游戏输入，也不写入采样文件。
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 | 三通道相等像素连通块数量 |
路径：assets/template/agent_state/
目录名由 AgentStateDef.template_id 和识别位置共同决定：
template_id。total 和 pos，实际读取 template_id_3_<pos>；双人队伍的 2 号位读取 template_id_2_2。因此一个角色独有状态通常需要准备这些目录：
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 号位需要时
每个目录内包含：
sub_dir: agent_state
template_id: my_agent
template_name: 角色状态-中文名-资源名
template_shape: rectangle
auto_mask: true
point_list:
- 100, 100
- 220, 120
坐标基准是项目默认 1080p。不要为新增角色额外设计分辨率适配。
如果要让角色可被通用自动战斗使用，继续补：
config/
├── auto_battle_operation/ # 底层连招动作
├── auto_battle_state_handler/ # 中层状态决策
└── auto_battle/ # 顶层战斗模板
常见接入点：
config/auto_battle_operation/<角色名>-*.ymlconfig/auto_battle_state_handler/<角色名>.ymlconfig/auto_battle_state_handler/速切模板-全角色.yml轮换-合轴-全角色.yml、轮换-紧急-全角色.yml自动战斗 YAML 语法见 skills/agent-auto-battle-config/SKILL.md。
AgentEnum 新增角色定义。AgentStateDef 和 agent_state 模板。检查：
Agent.template_id_list 是否包含对应模板 ID。assets/template/battle/avatar_*_<template_id>/ 是否存在。mask.png 是否遮掉了干扰背景。avatar_chain_、avatar_quick_。检查：
template_id 是否指向正确的 agent_state 模板目录。point_list 是否框住资源条有效区域。max_length 是否等于满条实际长度或最大值。connect_cnt 是否过高导致小图标识别不到。min_value_trigger_state 是否需要设为 0 来清除旧状态。检查：
速切模板-全角色.yml 引用。切换角色-<agent_name> 一致。operation_template 引用一致。states 条件是否过严，导致分支永远不命中。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/ 目录一致。uv run --env-file .env ruff check <file>。