# Agent Auto Battle Config

> OneDragon ZZZ 脚本速成指南 - 自动战斗 YAML 配置的完整语法与设计模式

- Skill: `onedragon-anything/agent-auto-battle-config` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add onedragon-anything/agent-auto-battle-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onedragon-anything/agent-auto-battle-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: onedragon-anything (https://skillmd.com/u/onedragon-anything)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/onedragon-anything/agent-auto-battle-config

---


# OneDragon ZZZ 脚本速成指南

#----------------------------------------------------------------------
# 1. 操作 (Operations)
# `operations` 是所有动作的基础，它是一个包含多个原子操作的列表，会按顺序执行。
#----------------------------------------------------------------------

## 1.1 操作的语法

### 基础操作：`op_name`
`op_name` 定义了要执行的按键操作。

**可用 `op_name` 列表:**
```
  战斗相关: 按键-闪避, 按键-普通攻击, 按键-特殊攻击, 按键-终结技, 按键-快速支援
  角色切换: 按键-切换角色-下一个, 按键-切换角色-上一个, 按键-切换角色 (需 agent_name 参数)
  连携技:   按键-连携技-左, 按键-连携技-右, 按键-连携技-取消
  移动:     按键-移动-前, 按键-移动-后, 按键-移动-左, 按键-移动-右
  其他:     按键-锁定敌人
```

### 操作变体 (点击, 按下, 松开)
每个按键都支持三种模式：

**1. 点击 (默认)**
执行一次快速的按下和松开。
```yaml
operations:
  - op_name: "按键-普通攻击"
```

**2. 按下**
只执行"按下"动作，通常用于长按。
```yaml
operations:
  - op_name: "按键-特殊攻击-按下"
```

**3. 松开**
只执行"松开"动作，用于结束长按或防止按键卡住。
```yaml
operations:
  - op_name: "按键-特殊攻击-松开"
```

## 1.2 如何编写连贯的操作 (连招)

通过组合操作和使用参数，可以编写出连贯的连招。

**核心参数:**
- `repeat`: 重复执行同一操作的次数。
- `post_delay`: 在操作执行**后**等待的秒数。此参数不支持在长按操作中用于定义按住时间！禁止接在长按后面。
- `op_name: "等待秒数"`: 在两个操作之间插入明确的停顿。

**重要规则:** 绝区零游戏引擎目前只接受0.1秒以上的按键间隔。因此，在连续操作之间，必须使用 `post_delay` 或 `等待秒数` 来确保每个动作之间至少有0.1秒的间隔。

**示例 1: "普攻x2 -> 停0.5秒 -> 特殊攻击"**
```yaml
operations:
  - op_name: "按键-普通攻击"
    repeat: 2
    post_delay: 0.1
  - op_name: "等待秒数"
    seconds: 0.5
  - op_name: "按键-特殊攻击"
```

**示例 2: 长按特殊攻击 1.5 秒**
```yaml
operations:
  - op_name: "按键-特殊攻击-按下"
  - op_name: "等待秒数"
    seconds: 0.5
  - op_name: "按键-特殊攻击-按下"
  - op_name: "等待秒数"
    seconds: 0.5
  - op_name: "按键-特殊攻击-按下"
  - op_name: "等待秒数"
    seconds: 0.5
  - op_name: "按键-特殊攻击-松开"
```

**长按规则:** 使用“按下 → 每 0.5 秒重复按下 → 松开”。不要只按下一次后长时间等待：其他并发操作可能发出松开事件，导致长按提前结束。

#----------------------------------------------------------------------
# 2. 状态 (States)
# `states` 是决策的核心，它定义了执行某个 `operations` 列表所需满足的条件。
#----------------------------------------------------------------------

## 2.1 状态语法

**基本格式:** `[状态名, 时间下限, 时间上限]{值下限, 值上限}`

-   **时间窗口**: `[状态名, 时间下限, 时间上限]` 检查状态的触发时间是否在此范围内。
  - 例如 `[状态名, 2, 10]` 表示"状态在过去2到10秒内触发过"。
  - 时间下限为负数时，表示"倒计时"或"未来事件"。例如 `[状态名, -5, -1]` 表示"状态将在未来1到5秒内触发"。
-   **数值范围**: `[耀嘉音-能量]{0, 120}` 表示"耀嘉音的能量值在 0 到 120 之间"。仅使用 `{下限, 上限}`，**不要把时间段和数值段拼在一起**（错误写法：`[能量值, 0, 999]{50, 120}`）。
-   **数值相等**: `[敌人数量]{3}` 表示"敌人数量等于3"。
-   **逻辑运算**: 使用 `&` (与), `|` (或), `!` (非) 和 `()` 括号来组合复杂逻辑。
    -   示例: `([状态A] | [状态B]) & ![状态C]`

## 2.2 如何设置与清除状态

通过 `设置状态` 和 `清除状态` 操作，可以精准地管理自定义状态，实现脚本不同部分的通信。

### 1. 设置状态 (AtomicSetState)

**推荐格式:**
```yaml
- op_name: "设置状态"
  state: "状态名"
  seconds: 5.0
  seconds_add: 2.0
  value: 100
  add: 50
```

### 2. 清除状态 (AtomicClearState)

```yaml
- op_name: "清除状态"
  state_list: ["状态1", "状态2"]
```

## 2.3 如何编写状态树 (IF-ELIF-ELSE)

状态树通过 `handlers` 列表构建，它是一个从上到下匹配的 **IF-ELIF-ELSE** 逻辑链。

**处理器结构:**
```yaml
- states: "[条件A] & ![条件C]"
  debug_name: "简要说明此分支意图"
  interrupt_states: "[紧急条件]"
  operations:
    # ... 执行动作 ...
```

**示例: 安比的技能决策树**
```yaml
handlers:
  - states: "[前台-安比]"
    sub_handlers:
      - states: "[安比-能量]{80, 120} & [安比-终结技可用]"
        operations:
          - op_name: "按键-终结技"
      - states: "[安比-特殊技可用]"
        operations:
          - op_name: "按键-特殊攻击"
      - states: ""
        operations:
          - op_name: "按键-普通攻击"
```

## 2.4 高阶技巧：使用负数时间实现动态倒计时

### 核心机制
- **设置倒计时**: 使用 `seconds: -N` 设置一个持续 `N` 秒的倒计时。
- **延长倒计时**: 使用 `seconds_add: -M` 为倒计时**增加** `M` 秒。
- **补偿 CG 暂停的失衡计时**: 若终结技或其他演出期间游戏内失衡计时暂停，按实测 CG 时长设置 `state: "自定义-失衡时间"` 与 `seconds_add: -<CG秒数>`，补回脚本仍按真实时间流逝而错误扣除的时长。
- **判断倒计时**: 使用 `[状态名, -N, 0]` 判断一个倒计时是否仍在生效。

#----------------------------------------------------------------------
# 3. 场景 (Scenes)
# `scenes` 是组织所有决策逻辑的顶层容器。
#----------------------------------------------------------------------

## 3.1 如何构建 Scenes

一个完整的脚本由一个 `scenes` 列表构成。每个 `scene` 包含：

1.  **`triggers` (触发器)**: 定义什么事件会"激活"这个场景。
2.  **`priority` (优先级)**: 数字越大，优先级越高。
3.  **`handlers` (处理器)**: 状态树。

## 3.2 Scenes 的运作机制：事件驱动与抢占

`Scenes` 运作方式是**事件驱动与抢占**模型：

1. **事件驱动激活**: 每个 `scene` 监听其 `triggers`，当状态被检测到或更新时唤醒对应 scene。
2. **执行与抢占**: 执行中会屏蔽 ≤ 当前优先级的触发器，但持续监听 > 当前优先级的触发器，高优场景可立即抢占。

#----------------------------------------------------------------------
# 4. 模板 (Templates) - 模块化与代码复用
#----------------------------------------------------------------------

## 4.1 模板的层级与引用规则

1.  **战斗模板** (`config/auto_battle/*.yml`): 顶层策略，定义 `scenes` 和 `priority`。
2.  **状态模板** (`config/auto_battle_state_handler/*.yml`): 中层决策树。
3.  **操作模板** (`config/auto_battle_operation/*.yml`): 底层原子化连招。

**引用规则:** 只能引用同层级或更低层级的模板。

## 4.2 语法与用法

- `state_template: "模板名"`: 调用状态模板
- `operation_template: "模板名"`: 调用操作模板

## 4.4 合并运行配置

只编辑 `sample.yml`，不要手动编辑 `.merged.yml`。

修改或新增自动战斗的操作、状态处理或顶层配置后，按 `new-config` 的流程运行：

```powershell
powershell -File skills/new-config/new-config.ps1
```

该脚本会从全部 `sample.yml` 生成 `.merged.yml`。构建成功后检查生成文件的差异，并将相关 `sample.yml` 与 `.merged.yml` 一并提交。

#----------------------------------------------------------------------
# 5. 全局参数
#----------------------------------------------------------------------

- `check_dodge_interval`: 闪避识别检测间隔（秒）
- `check_agent_interval`: 代理人状态检测间隔（秒）
- `check_chain_interval`: 连携技检测间隔（秒）
- `check_quick_interval`: 快速支援检测间隔（秒）
- `auto_lock_interval`: 自动锁定敌人间隔（-1 表示不自动锁定）
- `auto_turn_interval`: 镜头自动转向间隔

#----------------------------------------------------------------------
# 6. 设计思路：全配队通用
#----------------------------------------------------------------------

"全配队通用"脚本的核心设计思想是**模块化**与**事件驱动分层**，将**战略 (何时做)**、**决策 (做什么)** 和 **动作 (如何做)** 分离。

文件结构：
```
config/
├── auto_battle/                # 顶层战略（战斗模板）
│   └── 全配队通用.yml
├── auto_battle_state_handler/  # 中层决策（状态模板）
│   ├── 速切模板-全角色.yml
│   └── ...
└── auto_battle_operation/      # 底层动作（操作模板）
    └── ...
```

## 6.3 实践：如何新增一个角色

1. 创建角色的操作模板（`config/auto_battle_operation/`）
2. 创建角色的状态模板（`config/auto_battle_state_handler/`）
3. 注册到分派器（`速切模板-全角色.yml` 中增加引用）
4. 融入团队轮换（修改 `轮换-合轴-全角色.yml` 和 `轮换-紧急-全角色.yml`）

#----------------------------------------------------------------------
# 7. 参考脚本示例
#----------------------------------------------------------------------

- 星见雅：最复杂示例，含多种形态切换、资源条管理、连招嵌套
- 普罗米娅：最典型示例，含标准站场循环、连携技、长按模式