@agents-uni/zhenhuan 0.1.0

package/dist/server/index.js

@@ -0,0 +1,202 @@
+/**
+ * Zhen Huan Palace Server - 后宫服务器
+ *
+ * HTTP API server for the palace competition system.
+ * Integrates agents-uni-core Dashboard as the homepage,
+ * and injects palace-specific extension panels (ELO, race history, factions, etc.)
+ * Uses Hono for lightweight, high-performance routing.
+ */
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { logger } from 'hono/logger';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { PalaceOrchestrator } from '../orchestrator/index.js';
+import { createRoutes } from './routes/index.js';
+import { createDashboardRoutes } from '@agents-uni/core';
+/**
+ * Build palace-specific extension panels for the core Dashboard homepage.
+ * These show live ELO leaderboard, recent race results, and faction map
+ * directly on the dashboard — no need to call raw API.
+ */
+function buildPalaceExtension(orchestrator) {
+    const extRoutes = new Hono();
+    // Extension API: live ELO leaderboard as JSON
+    extRoutes.get('/leaderboard', (c) => c.json(orchestrator.getLeaderboard()));
+    extRoutes.get('/factions', (c) => c.json(orchestrator.dynamics.getFactions()));
+    extRoutes.get('/state', (c) => c.json(orchestrator.getState()));
+    const panels = [
+        {
+            title: '🏆 ELO 排行榜',
+            renderHtml: () => {
+                const board = orchestrator.getLeaderboard();
+                if (board.length === 0) {
+                    return '<p class="text-gray-500 text-sm">暂无排名数据。先运行一次赛马吧！</p>';
+                }
+                const rows = board.slice(0, 8).map((r, i) => {
+                    const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `<span class="text-gray-500 w-5 inline-block text-center">${i + 1}</span>`;
+                    const winRate = r.matchCount > 0 ? Math.round(r.winCount / r.matchCount * 100) + '%' : '-';
+                    return `<tr class="border-b border-gray-700/30">
+            <td class="py-1.5 px-2">${medal}</td>
+            <td class="py-1.5 px-2 text-white font-medium">${escapeHtml(r.agentId)}</td>
+            <td class="py-1.5 px-2 text-yellow-400 text-right">${r.rating}</td>
+            <td class="py-1.5 px-2 text-gray-400 text-right">${r.winCount}W ${r.lossCount}L</td>
+            <td class="py-1.5 px-2 text-gray-500 text-right">${winRate}</td>
+          </tr>`;
+                }).join('');
+                return `<table class="w-full text-sm">
+          <thead><tr class="text-gray-500 text-xs">
+            <th class="px-2 py-1 text-left w-8"></th>
+            <th class="px-2 py-1 text-left">Agent</th>
+            <th class="px-2 py-1 text-right">ELO</th>
+            <th class="px-2 py-1 text-right">战绩</th>
+            <th class="px-2 py-1 text-right">胜率</th>
+          </tr></thead>
+          <tbody>${rows}</tbody>
+        </table>`;
+            },
+        },
+        {
+            title: '⚔️ 势力格局',
+            renderHtml: () => {
+                const factions = orchestrator.dynamics.getFactions();
+                if (factions.length === 0) {
+                    return '<p class="text-gray-500 text-sm">暂无势力数据。Agent 结盟后会在此显示。</p>';
+                }
+                return factions.map(f => `
+          <div class="flex items-center gap-3 py-2 border-b border-gray-700/30 last:border-0">
+            <span class="text-white font-medium">${escapeHtml(f.leader)}</span>
+            <span class="text-gray-500">派系</span>
+            <span class="text-gray-300 text-sm">${f.members.map((m) => escapeHtml(m)).join(', ')}</span>
+            <span class="ml-auto badge bg-accent/20 text-accent-light">影响力 ${f.influence}</span>
+          </div>
+        `).join('');
+            },
+        },
+        {
+            title: '🏛️ 后宫品级',
+            renderHtml: () => {
+                const state = orchestrator.getState();
+                const sorted = [...state.agents].sort((a, b) => b.rankLevel - a.rankLevel);
+                if (sorted.length === 0) {
+                    return '<p class="text-gray-500 text-sm">暂无 Agent 数据。</p>';
+                }
+                return `<div class="space-y-1.5">${sorted.map(a => {
+                    const isActive = a.status === 'active' || a.status === 'idle';
+                    return `<div class="flex items-center gap-2 text-sm">
+            <span class="${isActive ? 'text-green-400' : 'text-red-400'}">●</span>
+            <span class="text-white font-medium w-20 truncate">${escapeHtml(a.name)}</span>
+            <span class="text-cyan-400 w-12">${escapeHtml(a.rank)}</span>
+            <span class="text-yellow-400 text-xs">ELO ${a.elo}</span>
+            <span class="ml-auto text-purple-400 text-xs">圣宠 ${a.favor}</span>
+          </div>`;
+                }).join('')}</div>`;
+            },
+        },
+    ];
+    // Add cold palace panel if there are inmates
+    const coldPalaceInmates = orchestrator.coldPalace.getInmates();
+    if (coldPalaceInmates.length > 0) {
+        panels.push({
+            title: '🏚️ 冷宫',
+            renderHtml: () => {
+                return coldPalaceInmates.map(inmate => `
+          <div class="flex items-center gap-2 py-1.5 text-sm border-b border-gray-700/30 last:border-0">
+            <span class="text-gray-500">○</span>
+            <span class="text-gray-400">${escapeHtml(inmate.name ?? inmate.agentId)}</span>
+            <span class="ml-auto text-gray-600 text-xs">${escapeHtml(inmate.reason)}</span>
+          </div>
+        `).join('');
+            },
+        });
+    }
+    return {
+        uniId: 'zhenhuan-palace',
+        routes: extRoutes,
+        panels,
+    };
+}
+function escapeHtml(str) {
+    return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&#039;');
+}
+export async function startServer(config) {
+    const { port, specPath } = config;
+    // ─── Validate spec file exists ──────────────────
+    const resolvedSpec = resolve(specPath);
+    if (!existsSync(resolvedSpec)) {
+        console.error('');
+        console.error('  \x1b[31m✗ 找不到规范文件:\x1b[0m ' + resolvedSpec);
+        console.error('');
+        console.error('  \x1b[90m请先创建 universe.yaml，或指定路径:\x1b[0m');
+        console.error('    npm run zhenhuan serve -- --spec /path/to/universe.yaml');
+        console.error('');
+        console.error('  \x1b[90m或使用脚手架生成:\x1b[0m');
+        console.error('    npx uni init');
+        console.error('');
+        process.exit(1);
+    }
+    // ─── Initialize orchestrator ────────────────────
+    let orchestrator;
+    try {
+        orchestrator = await PalaceOrchestrator.fromSpec(resolvedSpec);
+    }
+    catch (err) {
+        console.error('');
+        console.error('  \x1b[31m✗ 规范文件解析失败:\x1b[0m');
+        console.error(`    ${err instanceof Error ? err.message : String(err)}`);
+        console.error('');
+        console.error('  \x1b[90m请检查 YAML 格式是否正确。可运行:\x1b[0m');
+        console.error(`    npx uni validate ${specPath}`);
+        console.error('');
+        process.exit(1);
+    }
+    // ─── Create Hono app ───────────────────────────
+    const app = new Hono();
+    // Middleware
+    app.use('*', cors());
+    app.use('*', logger());
+    // Health check
+    app.get('/health', (c) => c.json({ status: 'ok', universe: 'zhenhuan-palace' }));
+    // Mount zhenhuan-specific API routes at /api
+    const api = createRoutes(orchestrator);
+    app.route('/api', api);
+    // Build palace extension panels for Dashboard homepage
+    const palaceExtension = buildPalaceExtension(orchestrator);
+    // Mount core Dashboard with palace extensions injected
+    const dashboard = createDashboardRoutes({
+        port,
+        openclawDir: config.openclawDir,
+        extensions: [palaceExtension],
+    });
+    app.route('/', dashboard);
+    const url = `http://localhost:${port}`;
+    console.log('');
+    console.log('  \x1b[33m╔══════════════════════════════════════╗\x1b[0m');
+    console.log('  \x1b[33m║\x1b[0m   \x1b[1m\x1b[35m甄嬛后宫 · 你是皇帝\x1b[0m              \x1b[33m║\x1b[0m');
+    console.log('  \x1b[33m╚══════════════════════════════════════╝\x1b[0m');
+    console.log('');
+    console.log(`  \x1b[36m首页:\x1b[0m      ${url}`);
+    console.log(`  \x1b[36mAPI:\x1b[0m       ${url}/api`);
+    console.log(`  \x1b[36m管理:\x1b[0m      ${url}/manage`);
+    console.log(`  \x1b[36m手册:\x1b[0m      ${url}/guide`);
+    console.log(`  \x1b[36m规范文件:\x1b[0m   ${resolvedSpec}`);
+    console.log('');
+    console.log(`  \x1b[90mAgent 数: ${orchestrator.universe.config.agents.length}\x1b[0m`);
+    console.log('  \x1b[90m按 Ctrl+C 停止服务\x1b[0m');
+    console.log('');
+    serve({ fetch: app.fetch, port });
+}
+// ─── Main Entry Point ──────────────────────────────
+// Only start when this file is executed directly (not imported).
+const isDirectExecution = process.argv[1] &&
+    resolve(process.argv[1]) === resolve(import.meta.url.replace('file://', ''));
+if (isDirectExecution) {
+    const port = parseInt(process.env.PORT || '8089', 10);
+    const specPath = process.env.SPEC_PATH || resolve(process.cwd(), 'universe.yaml');
+    startServer({ port, specPath }).catch((err) => {
+        console.error('❌ 后宫服务器启动失败:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}

package/dist/server/routes/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * API Routes - 后宫 API 路由
+ */
+import { Hono } from 'hono';
+import type { PalaceOrchestrator } from '../../orchestrator/index.js';
+export declare function createRoutes(orchestrator: PalaceOrchestrator): Hono;

package/dist/server/routes/index.js

@@ -0,0 +1,287 @@
+/**
+ * API Routes - 后宫 API 路由
+ */
+import { Hono } from 'hono';
+import { registerAgentsInOpenClaw } from '@agents-uni/core';
+// ─── Input Validation Helpers ─────────────────
+function validateRequired(obj, fields) {
+    for (const field of fields) {
+        if (obj[field] === undefined || obj[field] === null || obj[field] === '') {
+            return `缺少必填字段: ${field}`;
+        }
+    }
+    return null;
+}
+function validateAgentInputs(agents) {
+    if (!Array.isArray(agents) || agents.length === 0) {
+        return '至少需要一个 agent';
+    }
+    for (let i = 0; i < agents.length; i++) {
+        const a = agents[i];
+        if (!a.id || typeof a.id !== 'string' || a.id.trim() === '') {
+            return `agents[${i}].id 不能为空`;
+        }
+        if (!a.name || typeof a.name !== 'string' || a.name.trim() === '') {
+            return `agents[${i}].name 不能为空`;
+        }
+        if (a.rank !== undefined && (typeof a.rank !== 'number' || a.rank < 0 || a.rank > 100)) {
+            return `agents[${i}].rank 应在 0-100 之间`;
+        }
+    }
+    return null;
+}
+export function createRoutes(orchestrator) {
+    const app = new Hono();
+    // ─── Global Error Handler ──────────────────
+    app.onError((err, c) => {
+        console.error('[API Error]', err);
+        return c.json({ error: err instanceof Error ? err.message : 'Internal server error' }, 500);
+    });
+    // ─── State ────────────────────────────────
+    /** Get current palace state */
+    app.get('/state', (c) => {
+        return c.json(orchestrator.getState());
+    });
+    /** Get ELO leaderboard */
+    app.get('/leaderboard', (c) => {
+        return c.json(orchestrator.getLeaderboard());
+    });
+    // ─── Agents ───────────────────────────────
+    /** Get all agents */
+    app.get('/agents', (c) => {
+        const state = orchestrator.getState();
+        return c.json(state.agents);
+    });
+    /** Get agent profile */
+    app.get('/agents/:id', (c) => {
+        const id = c.req.param('id');
+        const profile = orchestrator.getAgentProfile(id);
+        if (!profile) {
+            return c.json({ error: 'Agent not found' }, 404);
+        }
+        return c.json(profile);
+    });
+    // ─── Competition ──────────────────────────
+    /** Submit a horse race result for evaluation */
+    app.post('/race/evaluate', async (c) => {
+        const body = await c.req.json();
+        if (!body.task)
+            return c.json({ error: '缺少 task 字段' }, 400);
+        if (!body.entries || !Array.isArray(body.entries) || body.entries.length === 0) {
+            return c.json({ error: '缺少 entries 字段或为空' }, 400);
+        }
+        // Simple scoring judge: scores based on output length and completion time
+        const defaultJudge = async (task, entries) => {
+            const judgments = entries.map(entry => {
+                const criterionScores = new Map();
+                // Placeholder scoring - in production, this would call an LLM judge
+                for (const criterion of task.criteria) {
+                    criterionScores.set(criterion.name, 50 + Math.random() * 50);
+                }
+                let totalScore = 0;
+                let totalWeight = 0;
+                for (const criterion of task.criteria) {
+                    const score = criterionScores.get(criterion.name) ?? 50;
+                    totalScore += score * criterion.weight;
+                    totalWeight += criterion.weight;
+                }
+                if (totalWeight > 0) {
+                    totalScore /= totalWeight;
+                }
+                return {
+                    agentId: entry.agentId,
+                    criterionScores,
+                    totalScore,
+                    feedback: `评分完毕`,
+                };
+            });
+            return judgments;
+        };
+        const result = await orchestrator.runHorseRace(body.task, body.entries, defaultJudge);
+        return c.json(result);
+    });
+    /**
+     * Dispatch a task to OpenClaw workspaces, collect submissions, and run the race.
+     * This is the full automated pipeline: dispatch → poll → judge → ELO update.
+     */
+    app.post('/race/dispatch', async (c) => {
+        const body = await c.req.json();
+        // Validate required fields
+        if (!body.task)
+            return c.json({ error: '缺少 task 字段' }, 400);
+        const taskErr = validateRequired(body.task, ['id', 'title', 'description', 'timeoutMs', 'participants']);
+        if (taskErr)
+            return c.json({ error: taskErr }, 400);
+        if (!Array.isArray(body.task.participants) || body.task.participants.length < 2) {
+            return c.json({ error: '至少需要 2 名参赛者' }, 400);
+        }
+        // Default judge: placeholder scoring (replace with LLM judge in production)
+        const defaultJudge = async (task, entries) => {
+            const judgments = entries.map(entry => {
+                const criterionScores = new Map();
+                for (const criterion of task.criteria) {
+                    criterionScores.set(criterion.name, 50 + Math.random() * 50);
+                }
+                let totalScore = 0;
+                let totalWeight = 0;
+                for (const criterion of task.criteria) {
+                    const score = criterionScores.get(criterion.name) ?? 50;
+                    totalScore += score * criterion.weight;
+                    totalWeight += criterion.weight;
+                }
+                if (totalWeight > 0)
+                    totalScore /= totalWeight;
+                return { agentId: entry.agentId, criterionScores, totalScore, feedback: '评分完毕' };
+            });
+            return judgments;
+        };
+        const result = await orchestrator.dispatchAndRace(body.task, defaultJudge);
+        return c.json({
+            dispatch: {
+                taskId: result.dispatch.taskId,
+                submitted: result.dispatch.submissions.length,
+                timedOut: result.dispatch.timedOut,
+            },
+            race: result.race
+                ? {
+                    rankings: result.race.rankings,
+                    narrative: result.race.narrative,
+                }
+                : null,
+        });
+    });
+    /** Get race history */
+    app.get('/race/history', (c) => {
+        return c.json(orchestrator.horseRace.getHistory());
+    });
+    // ─── Ceremonies ───────────────────────────
+    /** Trigger a court assembly */
+    app.post('/ceremony/court-assembly', async (c) => {
+        await orchestrator.runCourtAssembly();
+        return c.json({ ok: true, message: '朝会已举行' });
+    });
+    /** Get ceremony history */
+    app.get('/ceremony/history', (c) => {
+        return c.json(orchestrator.ceremonies.getHistory());
+    });
+    // ─── Agent Registration ──────────────────
+    /**
+     * Selection ceremony: register new agents into the palace + ELO arena.
+     * Also auto-registers them in openclaw.json if the workspace exists.
+     */
+    app.post('/ceremony/selection', async (c) => {
+        const body = await c.req.json();
+        // Validate input
+        const agentErr = validateAgentInputs(body.agents);
+        if (agentErr)
+            return c.json({ error: agentErr }, 400);
+        // Convert to AgentDefinition format expected by conductSelection
+        const agentDefs = body.agents.map(a => ({
+            id: a.id,
+            name: a.name,
+            role: { title: a.role ?? '答应', duties: [], permissions: [] },
+            rank: a.rank ?? 10,
+        }));
+        const result = await orchestrator.ceremonies.conductSelection(agentDefs);
+        // Register selected agents in ELO arena
+        const selectedIds = result.outcomes
+            .filter(o => o.action === 'selected')
+            .map(o => o.agentId);
+        for (const agentId of selectedIds) {
+            orchestrator.arena.register(agentId, 1000);
+        }
+        return c.json({
+            ok: true,
+            selected: selectedIds,
+            failed: result.outcomes
+                .filter(o => o.action === 'selection_failed')
+                .map(o => ({ agentId: o.agentId, reason: o.details.reason })),
+            narrative: result.narrative,
+        });
+    });
+    /**
+     * Register agents in openclaw.json without going through the full deploy pipeline.
+     * Useful for adding existing agents to OpenClaw.
+     */
+    app.post('/agents/register', async (c) => {
+        const body = await c.req.json();
+        const universe = orchestrator.universe.config;
+        // Build a minimal universe config with just the agents to register
+        const miniConfig = {
+            ...universe,
+            agents: body.agents.map(a => ({
+                id: a.id,
+                name: a.name,
+                role: { title: '答应', duties: [], permissions: [] },
+                rank: 10,
+            })),
+        };
+        const registered = registerAgentsInOpenClaw(miniConfig, body.openclawDir);
+        return c.json({ ok: true, registered });
+    });
+    // ─── Dynamics ─────────────────────────────
+    /** Get factions */
+    app.get('/factions', (c) => {
+        return c.json(orchestrator.dynamics.getFactions());
+    });
+    /** Form an alliance */
+    app.post('/alliance', async (c) => {
+        const { agent1, agent2, reason } = await c.req.json();
+        const err = validateRequired({ agent1, agent2, reason }, ['agent1', 'agent2', 'reason']);
+        if (err)
+            return c.json({ error: err }, 400);
+        const success = orchestrator.dynamics.formAlliance(agent1, agent2, reason);
+        return c.json({ ok: success });
+    });
+    // ─── Cold Palace ──────────────────────────
+    /** Get cold palace inmates */
+    app.get('/cold-palace', (c) => {
+        return c.json(orchestrator.coldPalace.getInmates());
+    });
+    /** Banish an agent */
+    app.post('/cold-palace/banish', async (c) => {
+        const { agentId, reason, durationMs } = await c.req.json();
+        const err = validateRequired({ agentId, reason }, ['agentId', 'reason']);
+        if (err)
+            return c.json({ error: err }, 400);
+        const success = await orchestrator.coldPalace.banish(agentId, reason, durationMs);
+        return c.json({ ok: success });
+    });
+    /** Rehabilitate an agent */
+    app.post('/cold-palace/rehabilitate', async (c) => {
+        const { agentId } = await c.req.json();
+        if (!agentId)
+            return c.json({ error: '缺少必填字段: agentId' }, 400);
+        const success = await orchestrator.coldPalace.rehabilitate(agentId);
+        return c.json({ ok: success });
+    });
+    // ─── Resources ────────────────────────────
+    /** Get resource summary for an agent */
+    app.get('/resources/:agentId', (c) => {
+        const agentId = c.req.param('agentId');
+        return c.json(orchestrator.resources.getResourceSummary(agentId));
+    });
+    /** Grant favor */
+    app.post('/resources/favor', async (c) => {
+        const { agentId, amount, reason } = await c.req.json();
+        const err = validateRequired({ agentId, amount, reason }, ['agentId', 'amount', 'reason']);
+        if (err)
+            return c.json({ error: err }, 400);
+        if (typeof amount !== 'number' || amount <= 0) {
+            return c.json({ error: 'amount 必须是正数' }, 400);
+        }
+        const success = orchestrator.resources.grantFavor(agentId, amount, reason);
+        return c.json({ ok: success });
+    });
+    // ─── Season ───────────────────────────────
+    /** Start a new season */
+    app.post('/season/start', (c) => {
+        const season = orchestrator.seasonEngine.startSeason();
+        return c.json(season);
+    });
+    /** Get all seasons */
+    app.get('/season', (c) => {
+        return c.json(orchestrator.seasonEngine.getSeasons());
+    });
+    return app;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@agents-uni/zhenhuan",
+  "version": "0.1.0",
+  "description": "Zhen Huan palace drama themed agent competition system built on @agents-uni/core",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "zhenhuan": "dist/cli/index.ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "universe.yaml",
+    "README.md",
+    "README.en.md",
+    "DESIGN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsx --watch src/cli/index.ts serve",
+    "start": "tsx src/cli/index.ts serve",
+    "serve": "tsx src/cli/index.ts serve",
+    "zhenhuan": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agents",
+    "multi-agent",
+    "competition",
+    "elo",
+    "horse-race",
+    "openclaw",
+    "ai-agents"
+  ],
+  "author": "agents-uni",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agents-uni/zhenhuan.git"
+  },
+  "homepage": "https://github.com/agents-uni/zhenhuan#readme",
+  "bugs": {
+    "url": "https://github.com/agents-uni/zhenhuan/issues"
+  },
+  "dependencies": {
+    "@agents-uni/core": "^0.1.0",
+    "@hono/node-server": "^1.13.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "hono": "^4.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}