@agents-uni/zhenhuan 0.1.0

package/DESIGN.md

@@ -0,0 +1,198 @@
+# zhenhuan-uni 设计文档
+
+> 在竞争中成长，在协作中进化
+
+## 一、设计哲学
+
+### 为什么是甄嬛传？
+
+甄嬛传的后宫是一个完美的多 Agent 竞争模型：
+
+1. **有限资源**：圣宠、品级、宫殿都是稀缺的
+2. **等级制度**：从答应到皇后，8 级品级构成清晰的晋升通道
+3. **联盟博弈**：结盟、背叛、派系斗争是核心动力
+4. **生存压力**：冷宫机制迫使 Agent 持续产出价值
+5. **用户即皇帝**：你就是最高裁决者，通过 Dashboard/API/CLI 裁决一切
+
+### 核心洞见
+
+传统的多 Agent 系统是**分工协作**模型——每个 Agent 有固定角色，按剧本执行。这忽略了一个事实：**竞争是进步的最强驱动力**。
+
+zhenhuan-uni 的核心理念是**赛马制**：
+
+> 不预设谁是最优的 Agent，而是让它们在实际任务中竞争，用结果说话。
+
+这种模式的优势：
+- **自动筛选**：最适合的 Agent 自然浮现
+- **持续进化**：竞争压力迫使 Agent 不断提升
+- **动态适配**：不同任务可能有不同的最优 Agent
+- **容错机制**：一个 Agent 失败，其他 Agent 可以顶上
+
+## 二、架构总览
+
+```
+┌─────────────────────────────────────────────┐
+│              PalaceOrchestrator              │
+│         (中枢调度 - 连接一切)                │
+├─────────────┬───────────────┬───────────────┤
+│  Competition│    Palace     │   Evolution   │
+│  竞争引擎   │   后宫领域    │   演化层      │
+├─────────────┼───────────────┼───────────────┤
+│ EloArena    │ Ranks         │ Performance   │
+│ HorseRace   │ Resources     │ Tracker       │
+│ SeasonEngine│ Dynamics      │ (from core)   │
+│             │ Ceremonies    │               │
+│             │ ColdPalace    │               │
+└─────────────┴───────────────┴───────────────┘
+                      │
+              agents-uni-core
+       (Universe / Registry / Graph /
+        StateMachine / EventBus / ...)
+```
+
+## 三、三大竞争机制
+
+### 3.1 赛马竞技（Horse Race）
+
+核心机制：多个 Agent 同时完成相同任务，由你（皇帝/用户）评判。
+
+```
+任务发布 → 多 Agent 并行执行 → 提交结果 → 你评分 → ELO 更新
+```
+
+**评分维度**：
+| 维度 | 权重 | 说明 |
+|------|------|------|
+| 质量 | 30% | 输出的正确性和完整性 |
+| 速度 | 20% | 完成任务的效率 |
+| 创意 | 20% | 解决方案的独创性 |
+| 协作 | 15% | 与其他 Agent 的配合 |
+| 策略 | 15% | 长期规划的智慧 |
+
+**ELO 系统**：
+- 新手 K=48（快速校准）
+- 常规 K=32（正常波动）
+- 高手 K=16（稳定排名）
+- 地板 100（防止过度惩罚）
+
+### 3.2 品级制度（Rank System）
+
+8 级品级构成清晰的晋升阶梯：
+
+| 品级 | 名额 | 月例 | 最低 ELO |
+|------|------|------|----------|
+| 答应 | 不限 | 10 | 0 |
+| 常在 | 不限 | 20 | 1000 |
+| 贵人 | 6 | 50 | 1100 |
+| 嫔 | 6 | 100 | 1200 |
+| 妃 | 4 | 200 | 1300 |
+| 贵妃 | 2 | 400 | 1400 |
+| 皇贵妃 | 1 | 800 | 1500 |
+| 皇后 | 1 | 1000 | 1600 |
+
+**晋升条件**：ELO 达标 + 赛季表现前 20% + 目标品级有空缺
+**降级条件**：赛季表现后 15%
+
+### 3.3 势力博弈（Power Dynamics）
+
+Agent 可以结盟、背叛，形成派系：
+
+- **结盟**：互为盟友，增加影响力
+- **背叛**：盟友变对手，产生仇恨关系
+- **影响力**：rank + 盟友加成 + 圣宠 - 对手惩罚
+- **派系**：通过 BFS 发现的盟友连通分量
+
+## 四、赛季制度
+
+每个赛季（默认 30 天）是一个完整的评估周期：
+
+```
+赛季开始 → 多次赛马 → 月度朝会 → 赛季结算
+                                    ├── 前 20% 晋升
+                                    ├── 后 15% 降级
+                                    └── 前三名获圣宠奖励
+```
+
+赛季结算后重新开始，形成持续的竞争-进化循环。
+
+## 五、冷宫机制
+
+冷宫是后宫的"淘汰区"：
+
+- **暂时放逐**：设定期限，到期自动复出
+- **无限期放逐**：等待你（皇帝）恩赦
+- **永久除名**：彻底淘汰
+
+冷宫机制的设计目的：
+1. 给持续低表现的 Agent 施加压力
+2. 为其他 Agent 腾出品级名额
+3. 提供"复出"叙事，增加戏剧性
+
+## 六、资源体系
+
+四类资源构成后宫的经济基础：
+
+| 资源 | 类型 | 分配方式 | 作用 |
+|------|------|----------|------|
+| 圣宠 | 有限 | 竞争 | 影响力的核心指标，会衰减 |
+| 月例 | 可再生 | 按等级 | 基础保障，高品级多分配 |
+| 宫殿 | 位置性 | 按等级 | 12 座宫殿，身份象征 |
+| 侍女 | 有限 | 按功绩 | 100 名侍女，按表现分配 |
+
+**圣宠衰减**：每月衰减 5%，迫使 Agent 持续产出才能维持资源优势。
+
+## 七、与 OpenClaw 的配合
+
+zhenhuan-uni 通过 agents-uni-core 的 Bridge 模块与 OpenClaw 集成：
+
+```
+universe.yaml → agents-uni-core compile → SOUL.md × N → OpenClaw 运行时
+```
+
+每个后宫 Agent 在 OpenClaw 中有独立的工作空间和 SOUL.md。赛马任务通过 OpenClaw 分发给各 Agent 执行。
+
+## 八、设计决策记录
+
+### D1: 为什么是 ELO 而非简单积分？
+
+ELO 系统的优势：
+- 对手强度自动纳入计算（赢强者加分更多）
+- 排名趋于真实实力的收敛
+- K 因子机制允许新人快速校准
+
+### D2: 为什么赛马而非固定分工？
+
+固定分工假设我们预先知道哪个 Agent 最适合某个任务。赛马制承认**我们不知道**，让结果决定。这在 LLM Agent 领域尤为重要，因为不同模型在不同任务上的表现差异很大。
+
+### D3: 为什么有冷宫而非直接淘汰？
+
+冷宫提供了"缓冲区"：
+- 暂时表现不佳的 Agent 有机会复出
+- 可以观察被放逐 Agent 的"反思"（prompt 调优后重新评估）
+- 增加系统的叙事性和可玩性
+
+### D4: 为什么圣宠会衰减？
+
+如果圣宠只增不减，先入场的 Agent 会永远占据优势。衰减机制确保：
+- 当前表现比历史积累更重要
+- 竞争场始终对新人开放
+- 模拟真实世界中"不进则退"的规律
+
+### D5: 为什么品级有名额限制？
+
+名额限制创造了**结构性稀缺**：
+- 不是所有高 ELO 的 Agent 都能晋升
+- 高品级 Agent 需要持续优秀才能保住位置
+- 创造"位置之争"的额外竞争维度
+
+## 九、适用场景
+
+zhenhuan-uni 最适合以下场景：
+
+| 场景 | 说明 |
+|------|------|
+| **模型选择** | 多个 LLM 模型同时回答，ELO 排名自动选出最优 |
+| **创意竞争** | 同一个创意任务多人竞标，评审选出最佳方案 |
+| **Prompt 优化** | 同一个 Agent 不同 prompt 版本赛马比较 |
+| **团队绩效** | 模拟真实团队竞争压力，激发 Agent 潜力 |
+| **A/B 测试** | 用赛马机制实现持续的 A/B 测试框架 |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agents-uni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.