--- name: th1-ai-director description: TH1 project workflow for the new AI Director architecture, AI kernel switching, AI action generation, AI Director diagnostics, JSONL log analysis, infinite-loop/card/hero-task/action-repeat triage, and iterative fixes to the simplified non-behavior-tree AI. Use when working on TH1 新AI, AI Director, AI_Director_Diagnostics logs, AI卡死/死循环, AI行为不聪明, AI action filtering, AI replay/testing loops, or replacing/maintaining behavior-tree AI. --- # TH1 AI Director ## Scope Use this skill for the new non-behavior-tree AI under `Unity/Assets/Scripts/TH1_Logic/AI/Director`, AI kernel registration, AI action-pool filtering, and local diagnostic loops. Always layer these project skills first when editing code: - `th1-base` for broad Unity/hotfix constraints. - `th1-action-logic` for action execution, `CheckCan`, `CompleteExecute`, AI action generation, and replay/network implications. - `th1-hero-implementation` if changing hero task semantics or hero gameplay, not just AI filtering. ## Key Files - `Unity/Assets/Scripts/TH1_Logic/AI/Kernel/` - AI kernel abstraction and switching. - `Unity/Assets/Scripts/TH1_Logic/AI/Director/` - new AI Director decision/cache/index/diagnostics implementation. - `Unity/Assets/Scripts/TH1_Logic/AI/AIActionGenerator.cs` - shared AI action candidate generation used by Director and legacy AI paths. - `Unity/Assets/Scripts/TH1_Logic/AI/AILogic.cs` - AI update loop and action execution guard. - `Unity/Assets/Scripts/TH1_Logic/Core/GameLogic.cs` - AI update caller. - `MD/GameMDFramework/18-AI导演系统策划文档.md` - planning/design intent. - `MD/GameMDFramework/19-AI导演系统逻辑语言.md` - pseudocode/logic-language source. - `MD/GameMDFramework/20-AI导演系统测试与诊断流程.md` - logging and testing process. - `Unity/Logs/AI_Director_Diagnostics/*.jsonl` - local debug diagnostic output. ## Fast Log Triage Run the bundled analyzer before reading huge JSONL files manually: ```powershell python .codex/skills/th1-ai-director/scripts/analyze_ai_director_log.py ``` Useful options: ```powershell python .codex/skills/th1-ai-director/scripts/analyze_ai_director_log.py --log Unity/Logs/AI_Director_Diagnostics/ai_director_YYYYMMDD_HHMMSS.jsonl python .codex/skills/th1-ai-director/scripts/analyze_ai_director_log.py --last 50 --top 30 python .codex/skills/th1-ai-director/scripts/analyze_ai_director_log.py --json ``` For batch-level quality work, use the batch analyzer first: ```powershell python .codex/skills/th1-ai-director/scripts/analyze_ai_batch_quality.py python .codex/skills/th1-ai-director/scripts/analyze_ai_batch_quality.py --batch Unity/Logs/AI_Batch/YYYYMMDD_HHMMSS/batch_summary.json --top 12 python .codex/skills/th1-ai-director/scripts/analyze_ai_batch_quality.py --json ``` Read the analyzer output in this order: 1. Latest log path and event counts. 2. Executions by player and max actions per turn. 3. Decision/execution action distributions. 4. Repeated stable keys. 5. No-effect successful actions. 6. Last execution rows. Read the batch analyzer output in this order: 1. `Games` success/failure count and whether any run timed out or was manually interrupted. 2. Runtime throughput: `avgGame`, `actions/sec`, `frames/sec`, `actions/turn`. 3. Outcome shape: `avgTurn`, `avgSurvivors`, eliminations, and winners if present. 4. Expansion: alive average city count, all-player average city count, max city count, alive `>=2` and `>=3` city ratios. 5. Power and attrition: alive unit count, score p10/p50/p90, kills, acting-unit deaths. 6. Hero count: read both `HeroSummary` from `batch_summary.json` and detailed `Hero:` from JSONL. Prefer hero-eligible ratios when the batch includes non-hero factions. 7. Action quality: no-effect actions, repeated stable actions, max actions per player turn. 8. Decision time: average, p95, max, and top lanes/actions. Do not judge AI quality from a single interrupted or partial run. The batch analyzer filters incomplete logs when the summary only contains completed games, but final before/after claims should use completed batches with the same options. ## Self-Optimization Loop Use this loop for all long-running AI intelligence work. The goal is not just "no crash"; the AI must become measurably stronger without becoming slower or more brittle. 1. Establish a baseline before changing behavior. - Use the same map size, player count, turn limit, difficulty, and action budgets that will be used after the patch. - Save the `Unity/Logs/AI_Batch//batch_summary.json` path and the batch analyzer output. - If there is no usable baseline, run at least one compact baseline batch first. 2. Run a bounded local batch, never an open-ended Unity session. - Close the visible Unity Editor before batchmode runs. - Always use explicit `-TimeoutSeconds`, `-MaxActions`, and `-MaxActionsPerPlayerTurn`. - Prefer `-KeepGoing` for quality loops so one bad game still yields evidence. - If Unity appears slow, inspect `unity_batch.log`, `batch_summary.json`, latest JSONL logs, and the Unity process before killing it. - After killing or interrupting a batch, confirm no `Unity.exe` process remains. 3. Analyze metrics before reading raw logs. - Use `analyze_ai_batch_quality.py` for the batch. - Use `analyze_ai_director_log.py` only after the batch report points to repeated actions, no-effect actions, outlier players, or slow lanes. - If the log is too sparse to explain the issue, improve diagnostics before guessing at AI logic. 4. Classify the problem type. - Correctness: failed games, exceptions, null references, action timeout, action budget stop, no-effect successful actions, illegal repeated actions. - Intelligence: weak expansion, low city count, poor unit count, bad attrition, city loss, long capital threat, empty threatened cities, obvious idle/economic waste, bad hero task timing, weak hero style expression, weak special-unit skill expression, over-defense, under-attack. - Performance: low actions/sec, high avg game runtime, high decision p95/max, too many actions per player turn, oversized JSONL output. - Noise: legal repeated city upgrades, normal tactical move/attack chains, expected Steam warmup messages, incomplete logs from killed batches. 5. Fix in the right layer. - If the design intent is wrong, update `18-AI导演系统策划文档.md` and `19-AI导演系统逻辑语言.md` before or alongside code. - If action availability is wrong for every caller, fix `CheckCan` or action semantics. - If the action is only wrong for AI, filter/scoring-gate it in AI generation or Director indexing. - If scoring is wrong, adjust lane priority, target value, or cache features; do not add broad hardcoded hacks that only satisfy one replay. - If performance is wrong, prefer caching, indexed lookup, action-pool pruning, and cheaper diagnostics before reducing strategic search quality. 6. Re-run the same batch options and compare. - A change only counts as an AI improvement when the target metric improves and no core guardrail regresses. - If a performance shortcut improves p95 but hurts expansion/city count/action quality, revert it or redesign it. - Keep failed experiments out of the final patch; mention them in the final report only when they explain the chosen direction. 7. Commit only coherent, verified changes. - Stage AI code, docs, scripts, and diagnostics changes that belong together. - Do not stage Unity auto-generated side effects such as `Unity.sln`, `ProjectSettings.asset`, or `packages-lock.json` unless they are intentionally part of the task. ## Quality Metrics Primary guardrails: - `failedGames` must be `0` for normal quality claims. - `noEffect` should be `0`; any nonzero value needs raw-log explanation. - `repeated` should be `0` after excluding known legal repeats such as same-turn `CityLevelUpAction:Park` consuming city upgrade points. - `maxActions/playerTurn` should stay well below the forced-stop budget; investigate anything above `80`. - No AI loop, forced AI stop, fatal exception, or unresolved null reference is acceptable. - `cityLost` and `capitalOwnershipChanged` are high-severity intelligence/correctness signals; inspect the TurnStart-to-TurnStart city signature before changing combat weights. Intelligence targets for compact 17-player, 20x20, 20-turn Director batches: - Expansion should not trigger `LOW_EXPANSION`; target `aliveAvgCities >= 1.35`. - Second-city rate should not trigger `FEW_SECOND_CITIES`; target alive `>=2` city ratio at least `25%`. - Track max city count and alive `>=3` city ratio as snowball signals, but do not overfit to one high-roll player. - Unit count and score p10/p50/p90 should not collapse while expansion improves. - Attrition should be interpreted with context: more kills and more deaths may indicate stronger aggression, not necessarily worse play. - Defense should be read from `Defense:` in the batch analyzer: `cityLost=0` is the target for short compact batches; rising `capitalThreatTurns`, `emptyThreatTurns`, or `worsened > resolved` means Emergency, city production, or Hold/Front logic needs review. - Hero count should be read from `HeroSummary` first: in 17-player 20-turn batches, many players may be non-hero factions, so use `eligibleAvgSelected`, `eligibleAvgSpawned`, `eligibleAvgMaxSlots`, `eligibleSpawned>=1`, `eligibleSpawned>=2`, and `eligibleSelected>=2` for hero intelligence. The detailed JSONL `Hero final counts` remains useful for action-level deltas and style buckets. Low eligible hero count means review culture-slot unlock, hero selection timing, and spawn-city pressure before judging hero playbook quality. - Hero style should not collapse to only `General`; `style buckets` should show expected class/faction roles such as Defense, Recovery, Burst, Control, Summon, Economy, Mobility, and HeroLifecycle as heroes appear. - Hero personal expression must be checked through `Hero personal expression`: compare each hero's role, executions, kills, damage, healing, moves, skill changes, and top actions. A hero that is selected/spawned but only moves or has near-zero damage/healing/control should trigger HeroPlaybook review. - Unit role expression must be checked through `Unit role expression`: Mobility should create moves/captures and low waste, Melee should hold line and finish targets, Ranged/Siege should contribute damage with low deaths, Defender should resolve threats without excessive self-deaths, and Special/Summon should show concrete skill/action signatures. - Special-unit expression should be checked through `Unit skill expression`: `skill-bearing actor actions`, `signature-changing actions`, `actor signatures`, and `skill_signature_expression` reveal whether new faction units are actually participating. Performance targets: - `actions/sec` should stay at or above `15` in compact batches. - Decision p95 above `60ms` is a warning and above `100ms` should be treated as an optimization target. - If p95 is high and top slow lanes are Front/Expansion/Emergency, inspect action generation, move lookup, `CheckCan`, and world-cache computation before trimming strategic behavior. - Large diagnostic output is acceptable for local debug, but batch analysis JSON should remain compact enough for automated comparison. Recommended batch commands: ```powershell # Fast smoke after compile-sensitive changes. Tools/RunAIDirectorBatch.ps1 -Games 1 -Players 2 -Turns 1 -TimeoutSeconds 60 # Compact quality loop for before/after comparison. Tools/RunAIDirectorBatch.ps1 -Games 3 -Players 17 -Width 20 -Height 20 -Turns 20 -TimeoutSeconds 420 -MaxActions 9000 -MaxActionsPerPlayerTurn 120 -Difficulty LUNATIC -KeepGoing # Larger confidence loop when compact metrics look good. Tools/RunAIDirectorBatch.ps1 -Games 5 -Players 17 -Width 30 -Height 30 -Turns 30 -TimeoutSeconds 900 -MaxActions 16000 -MaxActionsPerPlayerTurn 160 -Difficulty LUNATIC -KeepGoing ``` ## Infinite Loop Triage Classify the repeated action before patching: - If `netActionDelta=1` and all gameplay deltas are zero, the action is probably not a valid AI autonomous action. Filter it from `AIActionGenerator` and, if needed, from `AIDirectorActionIndex.IsDangerousAction`. - If the action mutates state but remains repeatedly high priority, fix the Director lane priority or add once-per-turn/action-budget gating. - If `CompleteExecute` returns true but `CheckCan` remains true forever because the action's own state is not consumed, inspect the action layer. Do not change authoritative action semantics unless the action is actually wrong for player/network/replay use. - If an action is player-only, UI-only, debug-only, or a hidden milestone/card/task helper, prefer excluding it from AI candidate generation. - If the action should be AI-usable long term but currently has missing scoring conditions, temporarily filter it and leave a concise code comment; then update 18/19 before re-enabling. Known temporary filters from this iteration: - `CommonActionType.BuyCultureCard` is only generated for `SecondHero` and `ThirdHero` slot unlock cards; other culture cards remain disabled for AI generation. - `UnitActionType.ToggleShenlan` is filtered because it is a debug/visual toggle with no action-point cost. - `PlayerActionType.FinishHeroTask` is filtered because it can execute repeatedly without observable AI turn progress. ## Candidate Filtering Rules Keep filters near shared AI generation when the action should not be available to either Director or legacy behavior-tree AI. Use `AIDirectorActionIndex.IsDangerousAction` as a second safety net for Director-specific indexing and fallback selection. Do not fix AI loops by changing `CheckCan` unless the action is invalid for all callers. Player/UI, network, replay, and scripted effects share the action layer. ## Diagnostic Expectations A useful AI diagnostic log should explain: - Session and player turn boundaries. - Decision lane, priority, reason, fallback flag, stable action key. - Action pool counts by category. - World cache snapshot: posture, city threats, fronts, development targets, local battles, hero states, diplomacy. - Execution before/after/delta snapshots. - Guard/forced-stop reason when action count budget is exceeded. When adding diagnostics, keep them editor/debug gated. Do not add game-facing text. ## Verification After AI or action filtering changes, run: ```powershell dotnet build Unity/TH1.Hotfix.csproj --no-restore ``` For log-only script changes, run: ```powershell python .codex/skills/th1-ai-director/scripts/analyze_ai_director_log.py --top 10 --last 10 ``` For local autonomous smoke runs, close the Unity Editor first, then run: ```powershell Tools/RunAIDirectorBatch.ps1 -Games 1 -Players 2 -Turns 1 -TimeoutSeconds 60 ``` The runner writes `batch_summary.json` under `Unity/Logs/AI_Batch//`. Use `-Games 10`, higher `-Turns`, and the normal 17 players for larger AI quality loops. `Tools/RunAIDirectorBatch.ps1` defaults to not stopping on settlement/game-end checks so quality loops can run to the requested `-Turns` even if a settlement winner appears early. Pass `-StopOnGameEnd` only when validating settlement/endgame behavior.