Combat Planner 開發指南

提示：角色的具體程式碼實現可在 src/char 目錄中找到。

Planner 是隊伍大腦。角色只宣告一個 CombatPlan：

• actions：planner 可見的動作目錄，用於切人評分、route/request/reservation 匹配。
• claims：FieldClaim 入場訴求，用於表達“我現在應該被切進來”。
• entry：普通入場後的 Python generator 動作流。未提供時預設按 actions 順序執行。

公開匯入入口固定使用：

from src.combat.planner import ActionSlot, CombatContext, FieldClaim, Planner, RoleProfile

src.combat.planner 只匯出正式開發 API。角色程式碼不要直接匯入 planner/core.py、planner/requests.py、planner/state.py 等內部模組。

快速入口

普通角色通常只需要覆蓋 describe_role() 和 combat_plan(context)：

def describe_role(self):
    return RoleProfile(
        role=Planner.Role.SUB_DPS,
        field_preference=Planner.FieldPreference.SUB_DPS,
        max_field_time=1.5,
    )

def combat_plan(self, context: CombatContext):
    return self.plan(
        self.click_ultimate_action(),
        self.click_skill_action(),
    )

複雜動作順序用同一個 plan 裡的 action 變數寫 entry flow。一個 action 在一次 entry 中只能 執行一次；有限次的額外執行使用 repeat_for_entry()：

def combat_plan(self, context: CombatContext):
    skill = self.click_skill_action(reason="skill available")
    ultimate = self.click_ultimate_action(reason="ultimate available")

    def entry():
        skill_result = yield skill
        if skill_result and self.ultimate_available():
            self.sleep(0.6)

        ultimate_result = yield ultimate
        if ultimate_result:
            yield skill.repeat_for_entry()

    return self.plan(skill, ultimate, entry=entry)

yield action 會把 action 交給 planner 執行。planner 完成 reservation/can_execute 檢查、執行、記錄 result、推進 request 後，把 ActionResult 送回 generator。 bool(ActionResult) 等於 result.success，所以可以直接寫：

a = yield action_a
b = yield action_b

if a and b:
    yield action_c

if a and not b:
    yield fallback_action

CombatPlan

角色通過 self.plan(*actions, claims=None, entry=None) 建立 CombatPlan：

def combat_plan(self, context):
    setup = self.planner_action(...)
    claims = []
    if self.should_claim_field():
        claims.append(FieldClaim.high(reason="burst window"))

    return self.plan(setup, claims=claims)

規則：

• 建立 plan 時只宣告動作和入場訴求，不要傳送輸入。
• 不要在建立 plan 時呼叫 context.request_route()、reserve_actions() 或 request_tags()；這些一次性請求應在 action execute 中釋出，或在 entry flow 收到成功 result 後釋出。
• actions 是評分和協作匹配目錄；entry 是普通入場執行流程。
• claims 可以傳多個獨立入場理由；它們不會疊加分數，planner 只取當前匹配角色的最高優先順序 claim。
• strict route、expected entry、active request 的硬排程優先於普通 entry flow。
• 普通 entry flow 最多執行 MAX_ACTIONS_PER_ENTRY 個動作。
• 同一個 action 在同一次入場中只會真實執行一次。

ActionIntent

ActionIntent 表達“角色進場後可以嘗試做什麼”。不要把一次普攻、等待、連點等 內部細節拆成很多 action；這些應寫在一個 action 的 execute 內。

欄位：

• tags: set[ActionTag]：動作意義和評分依據。
• execute: Callable[[CombatContext], ActionResult | bool | None]：真正執行動作。
• name: str = ""：高階精確匹配和日誌名。
• slot: ActionSlot | None = None：動作槽位。協作路線和 reservation 優先用 slot 匹配。
• reason: str = ""：planner 日誌和切人理由。
• can_execute: Callable[[CombatContext], bool] | None：planner 層硬限制。
• priority_ready: Callable[[CombatContext], bool] | None：只用於切人評分。

action.repeat_for_entry() 返回一個可在同一次 entry 中再次 yield 的動作副本。 它保留原 action 的執行、slot、標籤和 can_execute 限制，併為每次呼叫自動生成獨立 的 entry 去重結果。因此它適合 Q -> E -> 再尝试一次 E 這類有限 entry flow；副本通常 只在 entry flow 中 yield，不應加入 CombatPlan.actions。

每次 yield 都會計入單次 entry 的動作上限。不要在需要持續執行的長時間迴圈中 yield 它；此類迴圈應在呼叫已有動作 helper 前，先通過 context.is_action_allowed(self, action) 檢查完整 action 許可權。這樣迴圈保持由角色程式碼 控制，同時仍遵守 planner 的 can_execute 和 reservation 規則。

如果 action 設定了 slot，planner 會自動通過 context.can_execute_action(...) 檢查 reservation。開發者傳入的 can_execute 只需要表達額外機制限制。需要在 entry flow 外預查詢完整 action 時，使用 context.is_action_allowed(self, action)；它同時檢查 can_execute 和 slot reservation。普通或有限 entry 動作仍直接 yield action。

execute 返回規則：

• 返回 True：成功。
• 返回 False / None / 沒寫 return：失敗。
• 返回 ActionResult：使用 ActionResult.success。
• 返回 1、"ok" 這類 truthy 值不會被當成成功。

普通角色不需要手寫 ActionResult。只有需要自定義 result name/tags/slot/reason 時才手寫。

ActionTag

ActionTag 表達動作意義和評分，不能表達某個角色專屬機制。

常用標籤：

• ULTIMATE_ACTION：Q。
• SKILL_ACTION：E。
• ARC_ACTION：弧盤動作，評分為 0。
• SUPPORT：輔助/治療/增益類動作。
• COORDINATION：釋出協作路線或視窗的動作。
• COORDINATION_FINISHER：協作完成後的收尾動作。
• FIELD_TIME：planner 內建站場動作，角色不應自己宣告。
• LEGACY_COMBO：舊出招表動作。
• DEFAULT_ACTION：低價值兜底入口。

切人評分不會累加同一角色所有 action；planner 只挑該角色當前最高分的 ready action 代表該角色參賽。tag 不控制普通入場流程；普通入場由 CombatPlan.entry 控制。

ActionSlot

ActionSlot 是協作匹配用的動作槽位，比 action name 更推薦。

常用槽位：

• SKILL：E。
• ULTIMATE：Q。
• ARC：弧盤。
• ENTRY_REACTION：入場/環合反應，不是按鍵 action。
• FIELD_TIME：planner 內建站場。
• LEGACY_COMBO：舊出招表。
• CUSTOM：特殊動作。

協作和保留儘量寫：

FollowupStep.for_action(zero, ActionSlot.SKILL)
ActionReservation.for_action(nanally, ActionSlot.SKILL)
context.can_execute_action(self, slot=ActionSlot.SKILL)

BaseChar Helper

開戰會話與首次登場

BaseCombatTask.begin_combat_session() 是戰鬥正式開始時的統一入口。它會建立公開的 task.combat_session, 呼叫首切決策並記錄實際首發角色; CombatPlanner 只負責決定首切 目標, 不執行輸入或管理會話。CombatSession.combat_start 是本場戰鬥進入時刻; use_ultimate 與 switch_enabled 是本場固定的戰鬥策略。

BaseChar.perform() 開始時會記錄本場第一個實際執行戰鬥邏輯的角色。角色邏輯可用：

if self.is_first_engage():
    # 本场首次实际登场的角色
    ...

if self.consume_first_engage():
    # 全场仅成功一次
    ...

is_first_engage() 在本場戰鬥內穩定; consume_first_engage() 全場僅返回一次 True。 兩者都不依賴首切耗時或時間視窗。task.combat_session 在首次讀取時會建立預設會話; 任務若需要禁止首切和後續切人, 應在呼叫 begin_combat_session() 前設定 task.combat_session.switch_enabled = False, 不要在執行期替換切人方法。

click_ultimate_action

self.click_ultimate_action(
    name=None,
    tags=None,
    reason="ultimate action available",
    can_execute=None,
)

• 自動設定 slot=ActionSlot.ULTIMATE。
• 預設 tags={ActionTag.ULTIMATE_ACTION}。
• 預設 name=f"{角色名}_ultimate"。
• priority_ready 自動使用 self.ultimate_available()。
• execute 呼叫 self.click_ultimate()。

click_skill_action

self.click_skill_action(
    name=None,
    tags=None,
    reason="skill action available",
    down_time=0.01,
    can_execute=None,
)

• 自動設定 slot=ActionSlot.SKILL。
• 預設 tags={ActionTag.SKILL_ACTION}。
• 預設 name=f"{角色名}_skill"。
• priority_ready 自動使用 self.skill_available()。
• execute 呼叫 self.click_skill(down_time=down_time)。

planner_action

self.planner_action(
    tags={ActionTag.SKILL_ACTION},
    execute=self.some_action,
    name=None,
    slot=None,
    reason="",
    can_execute=None,
    priority_ready=None,
)

用於建立自定義 action。長動作應在 execute 內完成。

FieldClaim

FieldClaim 表達“我應該被切進來”，不是動作。它只抬高目標角色的普通入場評分； 角色切入後仍由 planner 從 actions、strict route/request 或 entry 中選擇動作。

def combat_plan(self, context):
    claims = []
    if self.has_burst_window():
        claims.append(
            FieldClaim.high(
                reason="burst window active",
                expected_entry=ExpectedEntry(slot=ActionSlot.ULTIMATE),
            )
        )
    return self.plan(self.click_ultimate_action(), claims=claims)

使用建議：

• 只是 Q/E 可用，不需要 FieldClaim；action 本身會參與評分。
• 需要“之後搶回場”時用 FieldClaim。
• 搶回場後需要優先做某動作時，加 expected_entry。
• 多個 FieldClaim 適合表達多個獨立機制入口；planner 不累加 claim 分，只選擇最高等級的匹配 claim。

combat_policies

combat_policies(context) 用於隨隊伍生命週期長期生效的策略。planner reset 當前隊伍 時會呼叫。適合釋出常駐 reservation，不適合釋出“本次 Q/E 成功後才出現”的臨時視窗。

def combat_policies(self, context: CombatContext):
    context.reserve_actions(
        [ActionReservation.for_action(zero, ActionSlot.SKILL)],
        reason="reserve Zero skill",
        until=Planner.NEVER_EXPIRES,
    )

協作請求

協作請求必須在 action 執行成功後釋出，或者在 combat_policies() 裡釋出長期策略。

def combat_plan(self, context):
    setup = self.click_skill_action()

    def entry():
        setup_result = yield setup
        if setup_result:
            context.request_route(
                [FollowupStep.for_action(zero, ActionSlot.SKILL, reason="Zero E")],
                reason="setup route",
            )

    return self.plan(setup, entry=entry)

常用 API：

• context.request_route(...)：固定順序協作路線。
• context.request_switch(...)：請求下一次普通排程切給某角色。
• context.request_role(...)：請求下一次普通排程切給某個隊伍定位的角色；多個 匹配角色時按普通切人評分選擇。它不指定動作，也不打斷當前 entry flow。
• context.reserve_actions(...)：保留隊友動作。
• context.request_tags(...)：請求一定數量的 tag 動作。

request_role(Planner.Role.SUPPORT) 請求的是角色的靜態隊伍定位； request_tags({Planner.ActionTag.SUPPORT}) 請求的是任意支援類動作。前者適合 “讓任一輔助角色進場”，後者適合“讓任一隊友完成一次治療/增益動作”。

context.request_role(Planner.Role.SUPPORT, reason="need a support role")

行為摘要

• 切人評分與普通 entry 執行分離。
• 評分使用 actions 中最高分 ready action，再疊加 FieldClaim、request 和站場偏好分。
• 當前角色普通入場執行由 entry 控制；未寫 entry 時按 actions 順序執行。
• priority_ready=False 只降低切人吸引力，不是硬阻止。
• can_execute=False 是硬阻止；被阻止的 entry action 會得到失敗 result，不會真實執行。
• strict route、expected entry、active request 優先於普通 entry flow。
• ActionResult.tags 不控制 entry flow。