TH1/.codex/skills/th1-ai-director/SKILL.md

name, description

name

description

th1-ai-director

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:

python .codex/skills/th1-ai-director/scripts/analyze_ai_director_log.py

Useful options:

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:

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/<timestamp>/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:

# 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:

dotnet build Unity/TH1.Hotfix.csproj --no-restore

For log-only script changes, run:

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:

Tools/RunAIDirectorBatch.ps1 -Games 1 -Players 2 -Turns 1 -TimeoutSeconds 60

The runner writes batch_summary.json under Unity/Logs/AI_Batch/<timestamp>/. 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.