@agents-uni/zhenhuan 0.1.0

package/dist/competition/season.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Season System - 赛季制度
+ *
+ * Organizes competitions into seasons with clear start/end,
+ * promotion/relegation at season boundaries, and seasonal rewards.
+ */
+import type { EloArena } from './elo.js';
+import type { PalaceCeremonies } from '../palace/ceremonies.js';
+import type { PalaceResourceManager } from '../palace/resources.js';
+export interface SeasonConfig {
+    /** Season duration in days */
+    durationDays: number;
+    /** Minimum races to qualify for promotion/relegation */
+    minRaces: number;
+    /** Top N% get promoted */
+    promotionRate: number;
+    /** Bottom N% get relegated */
+    relegationRate: number;
+    /** Favor bonus for first place */
+    firstPlaceBonus: number;
+    /** Favor bonus for second place */
+    secondPlaceBonus: number;
+    /** Favor bonus for third place */
+    thirdPlaceBonus: number;
+}
+export interface Season {
+    id: string;
+    number: number;
+    startedAt: string;
+    endsAt: string;
+    status: 'active' | 'completed';
+    config: SeasonConfig;
+}
+export interface SeasonStanding {
+    agentId: string;
+    elo: number;
+    races: number;
+    wins: number;
+    rank: number;
+}
+export interface SeasonResult {
+    season: Season;
+    standings: SeasonStanding[];
+    promotions: string[];
+    relegations: string[];
+    rewards: Map<string, number>;
+    narrative: string;
+}
+/**
+ * Manages competitive seasons in the palace.
+ */
+export declare class SeasonEngine {
+    private arena;
+    private ceremonies;
+    private resources;
+    private seasons;
+    private config;
+    constructor(arena: EloArena, ceremonies: PalaceCeremonies, resources: PalaceResourceManager, config?: Partial<SeasonConfig>);
+    /** Start a new season */
+    startSeason(): Season;
+    /** Get current active season */
+    getCurrentSeason(): Season | undefined;
+    /** End the current season and process results */
+    endSeason(agentRankLevels: Map<string, number>): Promise<SeasonResult>;
+    /** Get all seasons */
+    getSeasons(): Season[];
+    private generateSeasonNarrative;
+}

package/dist/competition/season.js

@@ -0,0 +1,150 @@
+/**
+ * Season System - 赛季制度
+ *
+ * Organizes competitions into seasons with clear start/end,
+ * promotion/relegation at season boundaries, and seasonal rewards.
+ */
+import { canPromote, getNextRank, getPreviousRank } from '../palace/ranks.js';
+const DEFAULT_SEASON_CONFIG = {
+    durationDays: 30,
+    minRaces: 3,
+    promotionRate: 0.2,
+    relegationRate: 0.15,
+    firstPlaceBonus: 100,
+    secondPlaceBonus: 60,
+    thirdPlaceBonus: 30,
+};
+/**
+ * Manages competitive seasons in the palace.
+ */
+export class SeasonEngine {
+    arena;
+    ceremonies;
+    resources;
+    seasons;
+    config;
+    constructor(arena, ceremonies, resources, config) {
+        this.arena = arena;
+        this.ceremonies = ceremonies;
+        this.resources = resources;
+        this.seasons = [];
+        this.config = { ...DEFAULT_SEASON_CONFIG, ...config };
+    }
+    /** Start a new season */
+    startSeason() {
+        const now = new Date();
+        const endsAt = new Date(now.getTime() + this.config.durationDays * 24 * 60 * 60 * 1000);
+        const season = {
+            id: `season-${this.seasons.length + 1}`,
+            number: this.seasons.length + 1,
+            startedAt: now.toISOString(),
+            endsAt: endsAt.toISOString(),
+            status: 'active',
+            config: { ...this.config },
+        };
+        this.seasons.push(season);
+        return season;
+    }
+    /** Get current active season */
+    getCurrentSeason() {
+        return this.seasons.find(s => s.status === 'active');
+    }
+    /** End the current season and process results */
+    async endSeason(agentRankLevels) {
+        const season = this.getCurrentSeason();
+        if (!season) {
+            throw new Error('No active season');
+        }
+        season.status = 'completed';
+        // Build standings from ELO leaderboard
+        const leaderboard = this.arena.getLeaderboard();
+        const standings = leaderboard.map((record, index) => ({
+            agentId: record.agentId,
+            elo: record.rating,
+            races: record.matchCount,
+            wins: record.winCount,
+            rank: index + 1,
+        }));
+        // Filter qualified agents
+        const qualified = standings.filter(s => s.races >= this.config.minRaces);
+        // Determine promotions (top N%)
+        const promotionCount = Math.max(1, Math.floor(qualified.length * this.config.promotionRate));
+        const promotionCandidates = qualified.slice(0, promotionCount);
+        const promotions = [];
+        for (const candidate of promotionCandidates) {
+            const currentLevel = agentRankLevels.get(candidate.agentId) ?? 1;
+            if (canPromote(currentLevel, candidate.elo)) {
+                const nextRank = getNextRank(currentLevel);
+                if (nextRank) {
+                    // Count occupants (simplified - caller should provide accurate data)
+                    try {
+                        await this.ceremonies.conductPromotion(candidate.agentId, nextRank.level);
+                        promotions.push(candidate.agentId);
+                    }
+                    catch {
+                        // Promotion failed (rank full, etc.)
+                    }
+                }
+            }
+        }
+        // Determine relegations (bottom N%)
+        const relegationCount = Math.max(1, Math.floor(qualified.length * this.config.relegationRate));
+        const relegationCandidates = qualified.slice(-relegationCount);
+        const relegations = [];
+        for (const candidate of relegationCandidates) {
+            const currentLevel = agentRankLevels.get(candidate.agentId) ?? 1;
+            if (currentLevel > 1) {
+                const prevRank = getPreviousRank(currentLevel);
+                if (prevRank) {
+                    try {
+                        await this.ceremonies.conductDemotion(candidate.agentId, prevRank.level);
+                        relegations.push(candidate.agentId);
+                    }
+                    catch {
+                        // Demotion failed
+                    }
+                }
+            }
+        }
+        // Distribute rewards
+        const rewards = new Map();
+        if (qualified.length >= 1) {
+            this.resources.grantFavor(qualified[0].agentId, this.config.firstPlaceBonus, '赛季冠军');
+            rewards.set(qualified[0].agentId, this.config.firstPlaceBonus);
+        }
+        if (qualified.length >= 2) {
+            this.resources.grantFavor(qualified[1].agentId, this.config.secondPlaceBonus, '赛季亚军');
+            rewards.set(qualified[1].agentId, this.config.secondPlaceBonus);
+        }
+        if (qualified.length >= 3) {
+            this.resources.grantFavor(qualified[2].agentId, this.config.thirdPlaceBonus, '赛季季军');
+            rewards.set(qualified[2].agentId, this.config.thirdPlaceBonus);
+        }
+        const result = {
+            season,
+            standings,
+            promotions,
+            relegations,
+            rewards,
+            narrative: this.generateSeasonNarrative(season, standings, promotions, relegations),
+        };
+        return result;
+    }
+    /** Get all seasons */
+    getSeasons() {
+        return [...this.seasons];
+    }
+    generateSeasonNarrative(season, standings, promotions, relegations) {
+        const parts = [`第${season.number}赛季落幕。`];
+        if (standings.length > 0) {
+            parts.push(`本季魁首：${standings[0].agentId}（${standings[0].elo}分）。`);
+        }
+        if (promotions.length > 0) {
+            parts.push(`${promotions.length}人晋升品级。`);
+        }
+        if (relegations.length > 0) {
+            parts.push(`${relegations.length}人遭贬谪。`);
+        }
+        return parts.join('');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * zhenhuan-uni — 甄嬛后宫 Agent 赛马系统
+ *
+ * 基于 agents-uni-core 构建的后宫竞争体系。
+ * 通过品级晋升、ELO 赛马、势力博弈三大机制激发 Agent 潜力。
+ *
+ * @module zhenhuan-uni
+ */
+export { PalaceResourceManager, PALACE_RESOURCE_DEFINITIONS, PALACE_NAMES } from './palace/resources.js';
+export type { ResourceSummary } from './palace/resources.js';
+export { PALACE_RANKS, getRankByLevel, getRankByTitle, getNextRank, getPreviousRank, canPromote, isRankFull } from './palace/ranks.js';
+export type { PalaceRank } from './palace/ranks.js';
+export { PalaceDynamics } from './palace/dynamics.js';
+export type { AllianceRecord, BetrayalRecord, Faction } from './palace/dynamics.js';
+export { PalaceCeremonies } from './palace/ceremonies.js';
+export type { CeremonyResult, CeremonyOutcome } from './palace/ceremonies.js';
+export { ColdPalace } from './palace/cold-palace.js';
+export type { ColdPalaceInmate } from './palace/cold-palace.js';
+export { EloArena } from './competition/elo.js';
+export type { EloRecord, EloChange, MatchResult } from './competition/elo.js';
+export { HorseRaceEngine } from './competition/horse-race.js';
+export type { HorseRaceTask, EvaluationCriterion, RaceEntry, JudgmentScore, RaceResult, JudgeFunction, } from './competition/horse-race.js';
+export { SeasonEngine } from './competition/season.js';
+export type { Season, SeasonConfig, SeasonResult, SeasonStanding } from './competition/season.js';
+export { PalaceOrchestrator } from './orchestrator/index.js';
+export type { OrchestratorConfig, PalaceState } from './orchestrator/index.js';
+export type { DispatchTask, DispatchResult, AgentSubmission, WorkspaceIO, } from '@agents-uni/core';
+export { TaskDispatcher, FileWorkspaceIO, MemoryWorkspaceIO } from '@agents-uni/core';

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * zhenhuan-uni — 甄嬛后宫 Agent 赛马系统
+ *
+ * 基于 agents-uni-core 构建的后宫竞争体系。
+ * 通过品级晋升、ELO 赛马、势力博弈三大机制激发 Agent 潜力。
+ *
+ * @module zhenhuan-uni
+ */
+// Palace domain modules
+export { PalaceResourceManager, PALACE_RESOURCE_DEFINITIONS, PALACE_NAMES } from './palace/resources.js';
+export { PALACE_RANKS, getRankByLevel, getRankByTitle, getNextRank, getPreviousRank, canPromote, isRankFull } from './palace/ranks.js';
+export { PalaceDynamics } from './palace/dynamics.js';
+export { PalaceCeremonies } from './palace/ceremonies.js';
+export { ColdPalace } from './palace/cold-palace.js';
+// Competition engine
+export { EloArena } from './competition/elo.js';
+export { HorseRaceEngine } from './competition/horse-race.js';
+export { SeasonEngine } from './competition/season.js';
+// Orchestrator
+export { PalaceOrchestrator } from './orchestrator/index.js';
+export { TaskDispatcher, FileWorkspaceIO, MemoryWorkspaceIO } from '@agents-uni/core';

package/dist/orchestrator/index.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Palace Orchestrator - 后宫调度中枢
+ *
+ * The central coordination engine that ties together:
+ * - Universe (agents-uni-core) for organizational structure
+ * - ELO Arena for competitive ratings
+ * - Horse Race Engine for task competitions
+ * - Season Engine for periodic evaluation
+ * - Palace modules for domain-specific mechanics
+ *
+ * 设计理念：用户就是皇帝。所有嫔妃 Agent 为用户竞争，
+ * 用户通过 API / Dashboard / CLI 以皇帝身份裁决一切。
+ */
+import { Universe, PerformanceTracker, TaskDispatcher } from '@agents-uni/core';
+import type { DispatchTask, DispatchResult, WorkspaceIO } from '@agents-uni/core';
+import { EloArena } from '../competition/elo.js';
+import { HorseRaceEngine } from '../competition/horse-race.js';
+import type { HorseRaceTask, RaceEntry, JudgeFunction, RaceResult } from '../competition/horse-race.js';
+import { SeasonEngine } from '../competition/season.js';
+import type { SeasonConfig } from '../competition/season.js';
+import { PalaceResourceManager } from '../palace/resources.js';
+import { PalaceDynamics } from '../palace/dynamics.js';
+import { PalaceCeremonies } from '../palace/ceremonies.js';
+import { ColdPalace } from '../palace/cold-palace.js';
+export interface OrchestratorConfig {
+    specPath?: string;
+    seasonConfig?: Partial<SeasonConfig>;
+    autoStartSeason?: boolean;
+    /** OpenClaw workspace directory for file-based dispatch */
+    openclawDir?: string;
+    /** Custom WorkspaceIO backend (overrides openclawDir) */
+    workspaceIO?: WorkspaceIO;
+    /** Dispatcher polling interval in ms */
+    pollIntervalMs?: number;
+}
+export interface PalaceState {
+    agents: Array<{
+        id: string;
+        name: string;
+        rank: string;
+        rankLevel: number;
+        elo: number;
+        status: string;
+        favor: number;
+    }>;
+    currentSeason: number | null;
+    factions: Array<{
+        id: string;
+        members: string[];
+        leader: string;
+        influence: number;
+    }>;
+    coldPalaceInmates: string[];
+    recentEvents: Array<{
+        type: string;
+        description: string;
+        timestamp: string;
+    }>;
+}
+/**
+ * Central orchestrator for the Zhen Huan palace universe.
+ */
+export declare class PalaceOrchestrator {
+    readonly universe: Universe;
+    readonly arena: EloArena;
+    readonly horseRace: HorseRaceEngine;
+    readonly seasonEngine: SeasonEngine;
+    readonly resources: PalaceResourceManager;
+    readonly dynamics: PalaceDynamics;
+    readonly ceremonies: PalaceCeremonies;
+    readonly coldPalace: ColdPalace;
+    readonly performanceTracker: PerformanceTracker;
+    readonly dispatcher: TaskDispatcher;
+    private initialized;
+    constructor(universe: Universe, config?: Partial<OrchestratorConfig>);
+    /**
+     * Create an orchestrator from a universe spec file.
+     */
+    static fromSpec(specPath: string, config?: Partial<OrchestratorConfig>): Promise<PalaceOrchestrator>;
+    /**
+     * Create an orchestrator from a Universe instance.
+     */
+    static fromUniverse(universe: Universe, config?: Partial<OrchestratorConfig>): PalaceOrchestrator;
+    /** Initialize the orchestrator: register agents in ELO arena */
+    initialize(): Promise<void>;
+    /** Register all agents in the ELO arena based on their rank */
+    private initializeElo;
+    /**
+     * Run a horse race: multiple agents compete on the same task.
+     */
+    runHorseRace(task: HorseRaceTask, entries: RaceEntry[], judge: JudgeFunction): Promise<RaceResult>;
+    /**
+     * Full dispatch→collect→judge pipeline:
+     * 1. Write TASK.md to each agent's OpenClaw workspace
+     * 2. Poll for SUBMISSION.md until timeout
+     * 3. Feed submissions into the horse race engine for scoring + ELO update
+     *
+     * This is the primary "one-click race" API that closes the loop between
+     * OpenClaw workspaces and the competition engine.
+     */
+    dispatchAndRace(task: DispatchTask & {
+        difficulty?: number;
+        category?: string;
+    }, judge: JudgeFunction): Promise<{
+        dispatch: DispatchResult;
+        race: RaceResult | null;
+    }>;
+    /**
+     * Run a monthly court assembly: review all agents and process promotions/demotions.
+     */
+    runCourtAssembly(): Promise<void>;
+    /** Get a snapshot of the current palace state */
+    getState(): PalaceState;
+    /** Get ELO leaderboard */
+    getLeaderboard(): import("../index.js").EloRecord[];
+    /** Get an agent's comprehensive profile */
+    getAgentProfile(agentId: string): {
+        elo: import("../index.js").EloRecord | {
+            agentId: string;
+            rating: number;
+            winCount: number;
+            lossCount: number;
+            drawCount: number;
+            matchCount: number;
+        };
+        resources: import("../index.js").ResourceSummary;
+        influence: number;
+        raceStats: {
+            totalRaces: number;
+            firstPlace: number;
+            topThree: number;
+            averageScore: number;
+        };
+        performance: number;
+        inColdPalace: boolean;
+        definition: import("@agents-uni/core").AgentDefinition;
+        status: import("@agents-uni/core").CitizenStatus;
+        performanceScore: number;
+        joinedAt: string;
+        state: Record<string, unknown>;
+    } | null;
+}

package/dist/orchestrator/index.js

@@ -0,0 +1,268 @@
+/**
+ * Palace Orchestrator - 后宫调度中枢
+ *
+ * The central coordination engine that ties together:
+ * - Universe (agents-uni-core) for organizational structure
+ * - ELO Arena for competitive ratings
+ * - Horse Race Engine for task competitions
+ * - Season Engine for periodic evaluation
+ * - Palace modules for domain-specific mechanics
+ *
+ * 设计理念：用户就是皇帝。所有嫔妃 Agent 为用户竞争，
+ * 用户通过 API / Dashboard / CLI 以皇帝身份裁决一切。
+ */
+import { PerformanceTracker, parseSpecFile, compileUniverse, TaskDispatcher, FileWorkspaceIO, } from '@agents-uni/core';
+import { EloArena } from '../competition/elo.js';
+import { HorseRaceEngine } from '../competition/horse-race.js';
+import { SeasonEngine } from '../competition/season.js';
+import { PalaceResourceManager } from '../palace/resources.js';
+import { PalaceDynamics } from '../palace/dynamics.js';
+import { PalaceCeremonies } from '../palace/ceremonies.js';
+import { ColdPalace } from '../palace/cold-palace.js';
+import { getRankByLevel } from '../palace/ranks.js';
+/** Default evolution config for the palace */
+const DEFAULT_EVOLUTION = {
+    performanceWindow: 50,
+    promotionThreshold: 75,
+    demotionThreshold: 30,
+    memoryRetention: 1000,
+};
+/**
+ * Central orchestrator for the Zhen Huan palace universe.
+ */
+export class PalaceOrchestrator {
+    // Core infrastructure
+    universe;
+    // Competition
+    arena;
+    horseRace;
+    seasonEngine;
+    // Palace domain
+    resources;
+    dynamics;
+    ceremonies;
+    coldPalace;
+    // Evolution
+    performanceTracker;
+    // Dispatcher (file-based task dispatch to OpenClaw workspaces)
+    dispatcher;
+    initialized = false;
+    constructor(universe, config) {
+        this.universe = universe;
+        // Initialize competition layer
+        this.arena = new EloArena();
+        this.horseRace = new HorseRaceEngine(this.arena);
+        // Initialize palace domain
+        this.resources = new PalaceResourceManager(universe.resources);
+        this.dynamics = new PalaceDynamics(universe.graph, universe.agents, universe.resources);
+        this.ceremonies = new PalaceCeremonies(universe.agents, universe.events);
+        this.coldPalace = new ColdPalace(universe.agents, universe.events);
+        this.performanceTracker = new PerformanceTracker(DEFAULT_EVOLUTION);
+        // Initialize dispatcher
+        const io = config?.workspaceIO ?? new FileWorkspaceIO({
+            openclawDir: config?.openclawDir,
+        });
+        this.dispatcher = new TaskDispatcher(io, {
+            pollIntervalMs: config?.pollIntervalMs,
+            eventBus: universe.events,
+        });
+        // Season engine needs ceremonies and resources
+        this.seasonEngine = new SeasonEngine(this.arena, this.ceremonies, this.resources);
+    }
+    /**
+     * Create an orchestrator from a universe spec file.
+     */
+    static async fromSpec(specPath, config) {
+        const uniConfig = parseSpecFile(specPath);
+        const universe = await compileUniverse(uniConfig, { autoInit: true });
+        const orchestrator = new PalaceOrchestrator(universe, config);
+        await orchestrator.initialize();
+        return orchestrator;
+    }
+    /**
+     * Create an orchestrator from a Universe instance.
+     */
+    static fromUniverse(universe, config) {
+        const orchestrator = new PalaceOrchestrator(universe, config);
+        orchestrator.initializeElo();
+        orchestrator.initialized = true;
+        return orchestrator;
+    }
+    /** Initialize the orchestrator: register agents in ELO arena */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.initializeElo();
+        // Subscribe to key events for automatic reactions
+        this.universe.events.subscribe(['agent.promoted'], async (event) => {
+            const agentId = event.actors[0];
+            if (agentId) {
+                this.resources.grantFavor(agentId, 20, '晋升恩赐');
+            }
+        });
+        this.universe.events.subscribe(['agent.demoted'], async (event) => {
+            const agentId = event.actors[0];
+            if (agentId) {
+                this.resources.revokeFavor(agentId, 30, '贬谪扣减');
+            }
+        });
+        this.initialized = true;
+    }
+    /** Register all agents in the ELO arena based on their rank */
+    initializeElo() {
+        for (const citizen of this.universe.agents.getAll()) {
+            const rank = citizen.definition.rank ?? 10;
+            const startingElo = 1000 + rank * 5;
+            this.arena.register(citizen.definition.id, startingElo);
+        }
+    }
+    // ─── Competition API ─────────────────────────
+    /**
+     * Run a horse race: multiple agents compete on the same task.
+     */
+    async runHorseRace(task, entries, judge) {
+        const result = await this.horseRace.evaluateRace(task, entries, judge);
+        // Record performance for all participants
+        for (const judgment of result.judgments) {
+            this.performanceTracker.record(judgment.agentId, task.id, judgment.totalScore, Object.fromEntries(judgment.criterionScores));
+        }
+        // Grant favor to top performers
+        const rankings = result.rankings;
+        if (rankings.length >= 1) {
+            this.resources.grantFavor(rankings[0], 30, `赛马冠军: ${task.title}`);
+        }
+        if (rankings.length >= 2) {
+            this.resources.grantFavor(rankings[1], 15, `赛马亚军: ${task.title}`);
+        }
+        return result;
+    }
+    /**
+     * Full dispatch→collect→judge pipeline:
+     * 1. Write TASK.md to each agent's OpenClaw workspace
+     * 2. Poll for SUBMISSION.md until timeout
+     * 3. Feed submissions into the horse race engine for scoring + ELO update
+     *
+     * This is the primary "one-click race" API that closes the loop between
+     * OpenClaw workspaces and the competition engine.
+     */
+    async dispatchAndRace(task, judge) {
+        // 1. Dispatch task to OpenClaw workspaces and collect submissions
+        const dispatchResult = await this.dispatcher.run(task);
+        if (dispatchResult.submissions.length < 2) {
+            // Not enough submissions for a race
+            return { dispatch: dispatchResult, race: null };
+        }
+        // 2. Convert AgentSubmission → RaceEntry
+        const entries = dispatchResult.submissions.map((sub) => ({
+            agentId: sub.agentId,
+            output: sub.output,
+            completedAt: sub.submittedAt,
+            duration: sub.duration,
+        }));
+        // 3. Build HorseRaceTask from DispatchTask
+        const horseRaceTask = {
+            id: task.id,
+            title: task.title,
+            description: task.description,
+            timeLimit: task.timeoutMs,
+            difficulty: task.difficulty ?? 3,
+            category: task.category ?? 'general',
+            criteria: task.criteria,
+        };
+        // 4. Run the horse race (scoring + ELO update)
+        const raceResult = await this.runHorseRace(horseRaceTask, entries, judge);
+        return { dispatch: dispatchResult, race: raceResult };
+    }
+    /**
+     * Run a monthly court assembly: review all agents and process promotions/demotions.
+     */
+    async runCourtAssembly() {
+        const performances = new Map();
+        const eloRatings = new Map();
+        for (const citizen of this.universe.agents.getAll()) {
+            const id = citizen.definition.id;
+            const avg = this.performanceTracker.getAverageScore(id);
+            performances.set(id, avg);
+            eloRatings.set(id, this.arena.getRating(id));
+        }
+        const result = await this.ceremonies.conductCourtAssembly(performances, eloRatings);
+        for (const outcome of result.outcomes) {
+            if (outcome.action === 'promotion_eligible') {
+                const targetLevel = outcome.details.targetLevel;
+                try {
+                    await this.ceremonies.conductPromotion(outcome.agentId, targetLevel);
+                }
+                catch {
+                    // Rank full or other issue
+                }
+            }
+            else if (outcome.action === 'demotion_recommended') {
+                const targetLevel = outcome.details.targetLevel;
+                try {
+                    await this.ceremonies.conductDemotion(outcome.agentId, targetLevel);
+                }
+                catch {
+                    // Already at lowest rank
+                }
+            }
+        }
+        this.resources.applyFavorDecay();
+        const eligible = this.coldPalace.checkParole();
+        for (const inmate of eligible) {
+            await this.coldPalace.rehabilitate(inmate.agentId);
+        }
+    }
+    // ─── State Query API ─────────────────────────
+    /** Get a snapshot of the current palace state */
+    getState() {
+        const agents = this.universe.agents.getAll().map((citizen) => {
+            const id = citizen.definition.id;
+            const rankLevel = Math.round((citizen.definition.rank ?? 10) / 10);
+            const rank = getRankByLevel(rankLevel);
+            return {
+                id,
+                name: citizen.definition.name,
+                rank: rank?.title ?? '未知',
+                rankLevel,
+                elo: this.arena.getRating(id),
+                status: citizen.status,
+                favor: this.resources.getResourceSummary(id).favor,
+            };
+        });
+        const currentSeason = this.seasonEngine.getCurrentSeason();
+        const factions = this.dynamics.getFactions();
+        const inmates = this.coldPalace.getInmates().map(i => i.agentId);
+        const allEvents = this.universe.events.getLog(20);
+        const recentEvents = allEvents.map((e) => ({
+            type: e.type,
+            description: e.narrative,
+            timestamp: e.timestamp,
+        }));
+        return {
+            agents,
+            currentSeason: currentSeason?.number ?? null,
+            factions,
+            coldPalaceInmates: inmates,
+            recentEvents,
+        };
+    }
+    /** Get ELO leaderboard */
+    getLeaderboard() {
+        return this.arena.getLeaderboard();
+    }
+    /** Get an agent's comprehensive profile */
+    getAgentProfile(agentId) {
+        const citizen = this.universe.agents.get(agentId);
+        if (!citizen)
+            return null;
+        return {
+            ...citizen,
+            elo: this.arena.getRecord(agentId) ?? { agentId, rating: 1000, winCount: 0, lossCount: 0, drawCount: 0, matchCount: 0 },
+            resources: this.resources.getResourceSummary(agentId),
+            influence: this.dynamics.calculateInfluence(agentId),
+            raceStats: this.horseRace.getAgentStats(agentId),
+            performance: this.performanceTracker.getAverageScore(agentId),
+            inColdPalace: this.coldPalace.isInColdPalace(agentId),
+        };
+    }
+}