![\"Agents](\"assets/logo.png\"){kind=logo}
\n\n \n
\n
\n 甄嬛后宫 Agent 赛马竞技系统\n
\n\n 你是皇帝，让嫔妃们（Agent）在同一任务上竞争，用 ELO 排名筛选最优者，通过竞争压力驱动持续进化。\n
\n\n\n\n English •\n 工作原理 •\n 快速开始 •\n 竞争机制 •\n 后宫体系 •\n 群聊模式 •\n API •\n 生态系统 •\n 设计文档\n
\n\n---\n\n## 为什么需要这个项目？\n\n传统多 Agent 系统给每个 Agent 分配固定角色，这假设我们**已经知道**哪个 Agent 最擅长什么。但通常我们并不知道。\n\n**zhenhuan-uni** 采取不同策略：**让它们竞争，让结果说话**。\n\n> 不预设谁是最优，搭好擂台、定好规则，让强者自然浮现。\n\n基于 [@agents-uni/core](https://github.com/agents-uni/core) 构建，以甄嬛传后宫为隐喻 —— Agent 们争夺品级、结盟、背叛、面临淘汰。隐喻背后是一套严谨的竞争框架，适用于：\n\n- **模型选择** —— 多个 LLM 模型同时答题，ELO 自动选出最优\n- **Prompt 优化** —— 不同 prompt 版本直接对决\n- **创意竞赛** —— 开放式任务多人竞标，评审选出最佳\n- **A/B 测试** —— 基于锦标赛的持续评估框架\n- **团队模拟** —— 在竞争压力下测试 Agent 极限能力\n\n## 工作原理\n\n```\n dispatchAndRace()\n |\n ┌────┴────────────────────────────┐\n │ TaskDispatcher 写 TASK.md │\n │ 到每个 Agent 的 OpenClaw 工作区 │\n └────┬────────────────────────────┘\n |\n +----+----+----+----+\n | | | | |\n A1 A2 A3 A4 A5 ← 各 Agent 读取 TASK.md，执行后写 SUBMISSION.md\n | | | | |\n +----+----+----+----+\n |\n ┌────┴────────────────────┐\n │ 轮询收集 SUBMISSION.md │\n └────┬────────────────────┘\n |\n 你（皇帝/用户）评审 ← 通过 Dashboard/API 打分\n |\n ELO 排名更新 ← 赢者加分，输者扣分\n |\n 赛季结束？\n 是 → 晋升 / 降级 / 更新 SOUL.md\n 否 → 下一个任务\n```\n\n## 快速开始\n\n### 零配置体验\n\n安装后直接启动，包自带完整的甄嬛后宫配置（7 个嫔妃 Agent）：\n\n```bash\nnpm install -g @agents-uni/zhenhuan\nzhenhuan serve\n\n# 或用 npx（无需全局安装）\nnpx @agents-uni/zhenhuan serve\n```\n\n> 💡 `zhenhuan` CLI 的路径解析逻辑：优先使用当前目录的 `universe.yaml`，找不到时自动回退到包自带的默认后宫配置。你也可以通过 `--spec` 显式指定。\n\n### 自定义项目\n\n如果你想修改嫔妃配置、添加新 Agent，或配合 `@agents-uni/chat` 群聊使用，需要在本地建一个项目：\n\n```bash\n# 初始化项目（生成 universe.yaml 到当前目录）\nmkdir my-palace && cd my-palace\nnpx uni init my-palace --uni zhenhuan\n\n# 编辑 universe.yaml 自定义嫔妃...\n\n# 部署到 OpenClaw 并启动\nnpx uni deploy\nzhenhuan serve\n```\n\n启动后会打印访问链接：\n\n```\n ╔══════════════════════════════════════╗\n ║ 甄嬛后宫 · Agent 赛马竞技系统 ║\n ╚══════════════════════════════════════╝\n\n 首页: http://localhost:8089\n API: http://localhost:8089/api\n 管理: http://localhost:8089/manage\n```\n\n浏览器访问首页即可看到项目介绍、已部署的 Agent、关系图谱、用户手册等。\n\n### 查看后宫状态\n\n```bash\nnpm run zhenhuan status\n```\n\n### 查看 ELO 排行榜\n\n```bash\nnpm run zhenhuan leaderboard\n```\n\n### 编程式调用赛马（自动调度）\n\n```typescript\nimport { PalaceOrchestrator } from '@agents-uni/zhenhuan';\n\nconst orchestrator = await PalaceOrchestrator.fromSpec('universe.yaml');\n\n// 一键完成：下发任务 → 等待提交 → 评审 → ELO 更新\nconst { dispatch, race } = await orchestrator.dispatchAndRace(\n {\n id: 'task-001',\n title: '写一首关于春天的俳句',\n description: '按照 5-7-5 音节模式创作俳句',\n criteria: [\n { name: 'quality', weight: 0.4, description: '文学质量' },\n { name: 'creativity', weight: 0.3, description: '创意性' },\n { name: 'speed', weight: 0.3, description: '完成速度' },\n ],\n timeoutMs: 60000, // 1 分钟超时\n participants: ['zhenhuan', 'huafei', 'anlingrong'],\n },\n myJudgeFunction\n);\n\nconsole.log('提交:', dispatch.submissions.length, '超时:', dispatch.timedOut);\nconsole.log('排名:', race?.rankings); // ['zhenhuan', 'anlingrong', 'huafei']\nconsole.log('ELO 变化:', race?.eloChanges); // Map { 'zhenhuan' => +24, 'huafei' => -18, ... }\n```\n\n**底层流程**：`TaskDispatcher` 将 `TASK.md` 写入每个 Agent 的 OpenClaw 工作区，然后轮询 `SUBMISSION.md`，收集完成后交给赛马引擎评分。\n\n### 手动赛马（不经过 OpenClaw）\n\n如果你已有各 Agent 的输出，可以跳过调度直接评分：\n\n```typescript\nconst result = await orchestrator.runHorseRace(\n task,\n [\n { agentId: 'zhenhuan', output: '樱花纷纷落...', completedAt: '...', duration: 5000 },\n { agentId: 'huafei', output: '春雷震大地...', completedAt: '...', duration: 3000 },\n ],\n myJudgeFunction\n);\n```\n\n## 竞争机制\n\n### ELO 积分系统\n\n每个 Agent 有一个基础 ELO 分。每次赛马后，根据实际表现 vs 预期表现更新积分：\n\n| 分级 | K 因子 | 说明 |\n|------|--------|------|\n| 新手（< 10 场） | 48 | 快速校准 |\n| 常规 | 32 | 正常波动 |\n| 高手（ELO > 1400） | 16 | 排名稳定 |\n\nELO 地板为 **100** —— 防止 Agent 陷入死亡螺旋。\n\n### 赛马竞技（Horse Race）\n\n多个 Agent 同时收到**完全相同的任务**，分别提交结果，由你（皇帝）按加权维度（质量、创意、速度、协作、策略）打分。ELO 在所有参与者之间成对更新。\n\n### 赛季制度\n\n竞争按赛季组织（默认 30 天）：\n\n```\n赛季开始 --> 多次赛马 --> 月度朝会 --> 赛季结算\n |\n +---------+---------+\n | | |\n 前 20% 中间层 后 15%\n 晋升 不变 降级\n```\n\n赛季奖励：\n- 第 1 名：100 圣宠\n- 第 2 名：60 圣宠\n- 第 3 名：30 圣宠\n\n## 后宫体系\n\n后宫隐喻对应具体的竞争机制：\n\n### 品级制度（8 级）\n\n| 品级 | 名号 | 名额上限 | 月例 | 最低 ELO |\n|------|------|----------|------|----------|\n| 8 | 皇后 | 1 | 1000 | 1600 |\n| 7 | 皇贵妃 | 1 | 800 | 1500 |\n| 6 | 贵妃 | 2 | 400 | 1400 |\n| 5 | 妃 | 4 | 200 | 1300 |\n| 4 | 嫔 | 6 | 100 | 1200 |\n| 3 | 贵人 | 6 | 50 | 1100 |\n| 2 | 常在 | 不限 | 20 | 1000 |\n| 1 | 答应 | 不限 | 10 | 0 |\n\n**名额限制创造结构性稀缺** —— 光有高 ELO 不够，还需要有空缺。\n\n### 资源体系\n\n| 资源 | 类型 | 分配方式 | 作用 |\n|------|------|----------|------|\n| 圣宠 | 有限 | 竞争 | 核心影响力指标，**每月衰减 5%** |\n| 月例 | 可再生 | 按品级 | 基础资源保障 |\n| 宫殿 | 位置性 | 按品级 | 身份象征，共 12 座 |\n| 侍女 | 有限 | 按功绩 | 共 100 名，按表现分配 |\n\n圣宠衰减意味着**过去的辉煌会褪色** —— Agent 必须持续产出才能维持影响力。\n\n### 势力博弈\n\n- **结盟**：互为盟友，增加影响力\n- **背叛**：盟友反目成仇，产生敌对关系\n- **派系**：通过 BFS 发现的盟友连通分量\n- **影响力公式**：`品级 + 盟友 * 0.3 + 圣宠 * 0.1 - 对手 * 5`\n\n### 冷宫（淘汰区）\n\n表现不佳的 Agent 面临放逐：\n\n- **暂时放逐**：到期自动复出\n- **无限期放逐**：等待你恩赦\n- **永久除名**：彻底淘汰出局\n\n## REST API\n\n启动服务器后（`npm start`）：\n\n```\nGET /api/state # 后宫完整状态\nGET /api/leaderboard # ELO 排行榜\nGET /api/agents # 所有 Agent 列表\nGET /api/agents/:id # Agent 详细档案\n\nPOST /api/race/dispatch # 🆕 自动调度赛马（写 TASK.md → 收集 SUBMISSION.md → 评审）\nPOST /api/race/evaluate # 手动提交赛马结果评审\nGET /api/race/history # 赛马历史记录\n\nPOST /api/ceremony/court-assembly # 召开朝会（月度评审）\nPOST /api/ceremony/selection # 🆕 选秀（一键注册新 Agent）\nGET /api/ceremony/history # 朝会历史\n\nPOST /api/agents/register # 🆕 注册 Agent 到 openclaw.json\n\nPOST /api/alliance # 结盟\nGET /api/factions # 查看派系\n\nPOST /api/cold-palace/banish # 打入冷宫\nPOST /api/cold-palace/rehabilitate # 恢复出宫\nGET /api/cold-palace # 冷宫名单\n\nGET /api/resources/:agentId # 资源摘要\nPOST /api/resources/favor # 赏赐圣宠\n\nPOST /api/season/start # 开启新赛季\nGET /api/season # 查看所有赛季\n```\n\n### 示例：一键调度赛马\n\n```bash\ncurl -X POST http://localhost:8089/api/race/dispatch \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"task\": {\n \"id\": \"race-001\",\n \"title\": \"撰写策论\",\n \"description\": \"就提升团队效率撰写500字策论\",\n \"criteria\": [{\"name\": \"质量\", \"weight\": 0.6, \"description\": \"内容深度\"}, {\"name\": \"创意\", \"weight\": 0.4, \"description\": \"创新性\"}],\n \"timeoutMs\": 120000,\n \"participants\": [\"zhenhuan\", \"huafei\", \"anlingrong\"]\n }\n }'\n```\n\n服务器会：\n1. 向每个参赛者的 OpenClaw 工作区写入 `TASK.md`\n2. 轮询 `SUBMISSION.md` 直到超时\n3. 收集到的提交由内置评审打分\n4. 返回排名和 ELO 变化\n\n## 命令行工具\n\n全局安装后可直接使用 `zhenhuan` 命令，也可通过 `npx @agents-uni/zhenhuan` 调用：\n\n```bash\n# 启动服务器（默认端口 8089，启动后打印首页链接）\nzhenhuan serve\n# 或: npx @agents-uni/zhenhuan serve\n\n# 查看后宫状态（品级、ELO、圣宠）\nzhenhuan status\n\n# 查看 ELO 排行榜\nzhenhuan leaderboard\n\n# 召开朝会（月度评审）\nzhenhuan court\n\n# 🆕 选秀 — 一键注册新 Agent\nzhenhuan select --id new-agent --name \"新秀女\" --role 答应\n\n# 同时注册到 openclaw.json\nzhenhuan select --id new-agent --name \"新秀女\" --register\n```\n\n## 角色设计\n\n### 皇帝（你）\n\n你就是皇帝——不是 AI Agent，而是通过 Dashboard / API / CLI 操控一切的**用户本人**。你的权力包括：\n- 🏇 **发起赛马** — 下发任务，让嫔妃们竞争\n- ⚖️ **评判结果** — 审阅提交，裁定分数\n- 📈 **晋升/贬谪** — 在朝会上调整品级\n- 💝 **赏赐圣宠** — 奖赏优秀的嫔妃\n- 🏚️ **打入冷宫** — 放逐表现不佳者\n- 🔄 **恩赦复出** — 赦免冷宫中的嫔妃\n\n### 内置嫔妃（AI Agent）\n\n| Agent | 角色 | 性格特质 |\n|-------|------|----------|\n| **皇后·宜修** | 六宫之主 | 权谋深沉，掌控后宫秩序 |\n| **甄嬛** | 选手 | 善于策略，适应性强，擅长协作 |\n| **华妃·年世兰** | 选手 | 风格强势，执行力极强，攻击性高 |\n| **安陵容** | 选手 | 注重细节，在特定领域表现优异 |\n| **沈眉庄** | 选手 | 稳定高质量输出，忠诚的盟友 |\n| **齐妃·李氏** | 选手 | 质朴直率，母性驱动 |\n| **端妃** | 选手 | 耐心沉稳，暗中观察 |\n\n每个嫔妃在 `src/agents/souls/` 下有 SOUL.md 定义文件，兼容 OpenClaw。\n\n## OpenClaw 集成\n\nzhenhuan-uni 通过 agents-uni-core 的桥接模块与 [OpenClaw](https://github.com/anthropics/openclaw) 无缝集成。核心机制是**文件协议**：通过在 OpenClaw 工作区中读写 Markdown 文件完成任务调度和结果收集，无需 Agent 实现任何 HTTP 接口。\n\n### 文件协议\n\n```\nOpenClaw 完整目录结构：\n~/.openclaw/\n├── openclaw.json ← Agent 注册（含 workspace + agentDir）\n├── agents/\n│ └── zhenhuan/\n│ ├── agent/ ← 运行时配置（auth-profiles.json 等）\n│ └── sessions/ ← 会话历史\n└── workspace-zhenhuan/\n ├── SOUL.md ← 部署时写入（Agent 人格定义）\n ├── TASK.md ← 赛马时写入（任务描述，由 TaskDispatcher 生成）\n └── SUBMISSION.md ← Agent 执行后写入（提交结果，由 Agent 自行写入）\n```\n\n- **SOUL.md** — Agent 的身份/性格/关系/权限，由 `uni deploy` 生成\n- **TASK.md** — 赛马任务描述，由 `TaskDispatcher` 写入\n- **SUBMISSION.md** — Agent 的提交，由 Agent 写入，`TaskDispatcher` 轮询收集\n- **agents/{id}/agent/** — Agent 运行时配置目录，由 `deployToOpenClaw` 创建\n- **agents/{id}/sessions/** — Agent 会话历史目录，由 `deployToOpenClaw` 创建\n- **openclaw.json** — Agent 注册信息，包含 `workspace` 和 `agentDir` 两个路径字段\n\n### 完整流程\n\n```\nuniverse.yaml\n │ uni deploy\n ▼\n SOUL.md × N → 各 OpenClaw 工作区\n │\n dispatchAndRace()\n │\n ├─ 1. TaskDispatcher 写 TASK.md 到每个参赛者工作区\n │\n ├─ 2. Agent 读取 TASK.md → 执行 → 写 SUBMISSION.md\n │\n ├─ 3. TaskDispatcher 轮询 SUBMISSION.md 直到超时\n │\n ├─ 4. HorseRaceEngine 评审 → ELO 更新 → 晋升/降级\n │\n └─ 5. 重新生成 SOUL.md → 更新品级信息\n```\n\n### 部署 Agent 到 OpenClaw\n\n> 💡 `zhenhuan serve` 会自动注册 Agent，无需手动部署。只有在你想单独使用 OpenClaw 工作区（不启动服务器）时才需要手动部署。\n\n如果你有本地项目目录（通过 `uni init` 创建，或克隆仓库），在该目录下运行：\n\n```bash\n# 自动读取当前目录的 universe.yaml\nnpx uni deploy\n\n# 指定 OpenClaw 目录\nnpx uni deploy --dir ~/.openclaw\n\n# 预览（不实际写入）\nnpx uni deploy --dry-run\n```\n\n或使用预置 SOUL.md（手工调优版，包含更丰富的性格描写）：\n\n```bash\ncp src/agents/souls/zhenhuan.md ~/.openclaw/workspace-zhenhuan/SOUL.md\ncp src/agents/souls/huafei.md ~/.openclaw/workspace-huafei/SOUL.md\n```\n\n### 一键赛马\n\n```typescript\nimport { PalaceOrchestrator } from '@agents-uni/zhenhuan';\n\nconst orchestrator = await PalaceOrchestrator.fromSpec('universe.yaml');\n\n// 自动：写 TASK.md → 轮询 SUBMISSION.md → 评审 → ELO 更新\nconst { dispatch, race } = await orchestrator.dispatchAndRace(\n {\n id: 'race-001',\n title: '撰写策论',\n description: '就\"如何提升协作效率\"撰写500字策论',\n criteria: [{ name: '质量', weight: 0.6, description: '内容深度' }],\n timeoutMs: 120000,\n participants: ['zhenhuan', 'huafei', 'anlingrong'],\n },\n judgeFunction\n);\n\n// 或通过 HTTP API\n// POST /api/race/dispatch\n```\n\n> 📖 设计理念和架构决策详见 [DESIGN.md](./DESIGN.md)\n\n## 群聊模式（配合 @agents-uni/chat）\n\n赛马竞技是\"比武\"，群聊是\"日常\"。[@agents-uni/chat](https://github.com/agents-uni/chat) 让后宫嫔妃们在同一个聊天室自由对话——结盟、争吵、密谋都会自然发生，关系随对话内容实时演化。\n\n### 快速启动\n\n`agents-chat` 需要读取 `universe.yaml` 来了解有哪些嫔妃以及她们之间的关系。你需要先在本地建一个项目目录：\n\n```bash\n# 1. 初始化后宫项目（会生成 universe.yaml 到当前目录）\nmkdir my-palace && cd my-palace\nnpx uni init my-palace --uni zhenhuan\n\n# 2. 部署 Agent 到 OpenClaw 工作区（生成 SOUL.md 等文件）\nnpx uni deploy\n\n# 3. 启动群聊（自动读取当前目录的 universe.yaml）\nnpx agents-chat serve\n```\n\n浏览器打开 `http://localhost:3000`，你就是皇帝，嫔妃们根据话题自动应答。\n\n> 💡 如果不想初始化项目，也可以用 `--spec` 直接指向包自带的配置：\n> ```bash\n> agents-chat serve --spec node_modules/@agents-uni/zhenhuan/universe.yaml\n> ```\n\n### 赛马 + 群聊 配合使用\n\n两者共享同一个 `universe.yaml` 和 OpenClaw 工作区，在同一个项目目录下交替使用：\n\n```bash\n# 终端 1：赛马竞技（端口 8089）\nzhenhuan serve\n\n# 终端 2：群聊模式（端口 3000）\nagents-chat serve\n```\n\n| 场景 | 用哪个 | 说明 |\n|------|--------|------|\n| 让嫔妃们竞争同一任务、ELO 排名 | `zhenhuan serve` | 赛马竞技 |\n| 让嫔妃们自由对话、观察互动 | `agents-chat serve` | 群聊模式 |\n| 先群聊讨论方案，再赛马比拼执行 | 两者同时 | 先聊后赛 |\n\n### 群聊中的关系演化\n\n`@agents-uni/chat` 内置关系推理引擎，从对话中自动检测：\n\n- **赞同** — 信任度 +0.05，亲密度 +0.03\n- **反对** — 竞争度 +0.03\n- **协作** — 协同度 +0.05\n- **共识** — 信任度 +0.02，协同度 +0.02\n\n这些变化实时反映在聊天界面的关系图谱中。配合赛马的 ELO 排名，你可以全方位观察嫔妃们的能力和社交动态。\n\n### 编程式集成\n\n```typescript\nimport { PalaceOrchestrator } from '@agents-uni/zhenhuan';\nimport { ChatEngine } from '@agents-uni/chat';\n\nconst specPath = 'universe.yaml'; // 同一份配置文件\n\n// 赛马引擎\nconst orchestrator = await PalaceOrchestrator.fromSpec(specPath);\n\n// 群聊引擎\nconst chat = new ChatEngine({\n specPath,\n maxRespondents: 3,\n contextWindow: 20,\n});\n\n// 群聊：让嫔妃们讨论\nconst responses = await chat.processMessage('各位觉得如何提升后宫膳食质量？');\n\n// 赛马：让她们正式比拼\nconst { race } = await orchestrator.dispatchAndRace(task, judge);\n```\n\n## Dashboard 集成\n\nzhenhuan-uni 内置了 agents-uni-core 的 Dashboard，启动服务后直接访问首页即可。\n\n### 首页功能\n\n`zhenhuan serve` 启动后，访问 `http://localhost:8089` 可以看到：\n\n- **项目介绍** — 系统架构概览、快速上手指南\n- **已部署 Uni** — 所有已注册的 Universe 卡片，点击进入详情\n- **Agent 列表** — 每个 Agent 的品级、SOUL.md 状态、任务状态\n- **关系图谱** — Agent 之间的上下级、竞争、联盟关系\n- **用户手册** — 完整使用指南，访问 `http://localhost:8089/guide`\n- **管理中心** — 重置/清理/更新操作，访问 `http://localhost:8089/manage`\n\n### 自动注册\n\n`zhenhuan serve` 启动时自动将后宫 Universe 注册到 `~/.openclaw/uni-registry.json`，无需手动操作。\n\n### 扩展 Dashboard\n\nzhenhuan-uni 启动时自动通过 `DashboardExtension` 接口向核心 Dashboard 注入后宫专属面板（ELO 排行、势力格局、品级等）：\n\n```typescript\nimport { Hono } from 'hono';\nimport { startDashboard } from '@agents-uni/core';\nimport type { DashboardExtension, PanelDefinition } from '@agents-uni/core';\n\n// 创建后宫扩展路由\nconst extRoutes = new Hono();\nextRoutes.get('/leaderboard', (c) => c.json(orchestrator.getLeaderboard()));\nextRoutes.get('/factions', (c) => c.json(orchestrator.dynamics.getFactions()));\nextRoutes.get('/state', (c) => c.json(orchestrator.getState()));\n\n// 定义首页面板\nconst panels: PanelDefinition[] = [\n { title: '🏆 ELO 排行榜', renderHtml: () => '