@agents-uni/zhenhuan 0.1.4 → 0.1.6

package/README.en.md

@@ -21,6 +21,7 @@
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#competition-mechanics">Competition</a> &bull;
   <a href="#palace-system">Palace System</a> &bull;
+  <a href="#group-chat-with-agents-unichat">Group Chat</a> &bull;
   <a href="#rest-api">API</a> &bull;
   <a href="./DESIGN.md">Design Doc</a>
 </p>
@@ -74,36 +75,35 @@ Built on [@agents-uni/core](https://github.com/agents-uni/core), it models a com
 
 ## Quick Start
 
-### Install
+### Zero-config Experience
 
-```bash
-# Use as a dependency
-npm install @agents-uni/zhenhuan
-
-# Or clone the repo for local development
-git clone https://github.com/agents-uni/zhenhuan.git
-cd zhenhuan
-npm install
-```
-
-### Start the server
+Install and launch immediately — the package ships with a complete palace configuration (7 concubine agents):
 
 ```bash
-# Global install, then use from any directory
 npm install -g @agents-uni/zhenhuan
 zhenhuan serve
 
-# Or in the project directory
-npm start
-
 # Or with npx (no global install needed)
 npx @agents-uni/zhenhuan serve
-
-# Use a custom spec file
-zhenhuan serve --spec /path/to/my-universe.yaml
 ```
 
-> 💡 **Path resolution**: `zhenhuan` first looks for `universe.yaml` in the current directory. If not found, it automatically uses the built-in default palace configuration. You can also specify a custom spec file with `--spec`.
+> 💡 `zhenhuan` CLI path resolution: first checks for `universe.yaml` in the current directory; if not found, falls back to the built-in palace configuration. You can also specify a custom path with `--spec`.
+
+### Custom Project
+
+If you want to modify concubine configurations, add new agents, or use group chat with `@agents-uni/chat`, create a local project:
+
+```bash
+# Initialize a project (generates universe.yaml in current directory)
+mkdir my-palace && cd my-palace
+npx uni init my-palace --uni zhenhuan
+
+# Edit universe.yaml to customize concubines...
+
+# Deploy to OpenClaw and start
+npx uni deploy
+zhenhuan serve
+```
 
 On startup, it prints the access URLs:
 
@@ -416,15 +416,19 @@ universe.yaml
 
 ### Deploy Agents to OpenClaw
 
+> 💡 `zhenhuan serve` auto-registers agents on startup — manual deployment is only needed when using OpenClaw workspaces without the server.
+
+If you have a local project directory (created via `uni init` or cloned from the repo), run in that directory:
+
 ```bash
-# One-command deploy
-npx uni deploy universe.yaml
+# Auto-detects universe.yaml in current directory
+npx uni deploy
 
-# Custom directory
-npx uni deploy universe.yaml --dir ~/.openclaw
+# Custom OpenClaw directory
+npx uni deploy --dir ~/.openclaw
 
 # Dry run (preview only)
-npx uni deploy universe.yaml --dry-run
+npx uni deploy --dry-run
 ```
 
 Or use pre-built SOUL.md files (hand-tuned with richer personality descriptions):
@@ -460,6 +464,87 @@ const { dispatch, race } = await orchestrator.dispatchAndRace(
 
 > 📖 Full integration tutorial: [OPENCLAW_INTEGRATION_GUIDE.md](https://github.com/agents-uni/zhenhuan/blob/main/OPENCLAW_INTEGRATION_GUIDE.md)
 
+## Group Chat (with @agents-uni/chat)
+
+Horse racing is the "arena"; group chat is "daily life". [@agents-uni/chat](https://github.com/agents-uni/chat) lets your concubines talk freely in a shared chat room — forming alliances, arguing, scheming — and their relationships evolve in real time based on the conversation.
+
+### Quick Start
+
+`agents-chat` needs to read `universe.yaml` to know which concubines exist and their relationships. You need a local project directory:
+
+```bash
+# 1. Initialize a palace project (generates universe.yaml)
+mkdir my-palace && cd my-palace
+npx uni init my-palace --uni zhenhuan
+
+# 2. Deploy agents to OpenClaw workspaces (generates SOUL.md etc.)
+npx uni deploy
+
+# 3. Start group chat (auto-detects universe.yaml in current directory)
+npx agents-chat serve
+```
+
+Open `http://localhost:3000` in your browser. You are the Emperor — concubines respond automatically based on the topic.
+
+> 💡 If you don't want to initialize a project, you can point directly to the bundled config:
+> ```bash
+> agents-chat serve --spec node_modules/@agents-uni/zhenhuan/universe.yaml
+> ```
+
+### Racing + Chat Combined
+
+Both share the same `universe.yaml` and OpenClaw workspaces. Run them side by side from the same project directory:
+
+```bash
+# Terminal 1: Horse racing (port 8089)
+zhenhuan serve
+
+# Terminal 2: Group chat (port 3000)
+agents-chat serve
+```
+
+| Scenario | Which to use | Notes |
+|----------|-------------|-------|
+| Concubines compete on the same task, ELO ranking | `zhenhuan serve` | Horse race |
+| Concubines chat freely, observe interactions | `agents-chat serve` | Group chat |
+| Discuss approaches first, then compete on execution | Both together | Chat then race |
+
+### Relationship Evolution in Chat
+
+`@agents-uni/chat` includes a built-in relationship inference engine that detects signals from conversations:
+
+- **Agreement** — trust +0.05, affinity +0.03
+- **Disagreement** — rivalry +0.03
+- **Collaboration** — synergy +0.05
+- **Consensus** — trust +0.02, synergy +0.02
+
+These changes are reflected in real time on the chat UI's relationship graph. Combined with ELO rankings from horse racing, you get a full picture of each concubine's ability and social dynamics.
+
+### Programmatic Integration
+
+```typescript
+import { PalaceOrchestrator } from '@agents-uni/zhenhuan';
+import { ChatEngine } from '@agents-uni/chat';
+
+const specPath = 'universe.yaml'; // same config file
+
+// Horse racing engine
+const orchestrator = await PalaceOrchestrator.fromSpec(specPath);
+
+// Group chat engine
+const chat = new ChatEngine({
+  specPath,
+  maxRespondents: 3,
+  contextWindow: 20,
+});
+
+// Chat: let concubines discuss
+const responses = await chat.processMessage('How should we improve palace cuisine?');
+
+// Race: let them compete formally
+const { race } = await orchestrator.dispatchAndRace(task, judge);
+```
+
 ## Dashboard Integration
 
 zhenhuan-uni integrates deeply with the agents-uni-core Dashboard, providing a unified web UI for managing the palace system.
@@ -568,6 +653,7 @@ npm run build
 ## Related Projects
 
 - [**@agents-uni/core**](https://github.com/agents-uni/core) — The universal protocol layer this project is built on ([npm](https://www.npmjs.com/package/@agents-uni/core))
+- [**@agents-uni/chat**](https://github.com/agents-uni/chat) — Group chat service for agent universes with real-time relationship evolution ([npm](https://www.npmjs.com/package/@agents-uni/chat))
 
 ## License
 

package/README.md

@@ -21,6 +21,7 @@
   <a href="#快速开始">快速开始</a> &bull;
   <a href="#竞争机制">竞争机制</a> &bull;
   <a href="#后宫体系">后宫体系</a> &bull;
+  <a href="#群聊模式配合-agents-unichat">群聊模式</a> &bull;
   <a href="#rest-api">API</a> &bull;
   <a href="./DESIGN.md">设计文档</a>
 </p>
@@ -74,36 +75,35 @@
 
 ## 快速开始
 
-### 安装
+### 零配置体验
 
-```bash
-# 作为依赖使用
-npm install @agents-uni/zhenhuan
-
-# 或克隆仓库本地开发
-git clone https://github.com/agents-uni/zhenhuan.git
-cd zhenhuan
-npm install
-```
-
-### 启动服务器
+安装后直接启动，包自带完整的甄嬛后宫配置（7 个嫔妃 Agent）：
 
 ```bash
-# 全局安装后，在任意目录直接使用
 npm install -g @agents-uni/zhenhuan
 zhenhuan serve
 
-# 或在项目目录中
-npm start
-
 # 或用 npx（无需全局安装）
 npx @agents-uni/zhenhuan serve
-
-# 使用自定义规范文件
-zhenhuan serve --spec /path/to/my-universe.yaml
 ```
 
-> 💡 **路径解析逻辑**：`zhenhuan` 会优先查找当前目录下的 `universe.yaml`，找不到时自动使用包自带的默认甄嬛后宫配置。你也可以通过 `--spec` 显式指定规范文件路径。
+> 💡 `zhenhuan` CLI 的路径解析逻辑：优先使用当前目录的 `universe.yaml`，找不到时自动回退到包自带的默认后宫配置。你也可以通过 `--spec` 显式指定。
+
+### 自定义项目
+
+如果你想修改嫔妃配置、添加新 Agent，或配合 `@agents-uni/chat` 群聊使用，需要在本地建一个项目：
+
+```bash
+# 初始化项目（生成 universe.yaml 到当前目录）
+mkdir my-palace && cd my-palace
+npx uni init my-palace --uni zhenhuan
+
+# 编辑 universe.yaml 自定义嫔妃...
+
+# 部署到 OpenClaw 并启动
+npx uni deploy
+zhenhuan serve
+```
 
 启动后会打印访问链接：
 
@@ -416,15 +416,19 @@ universe.yaml
 
 ### 部署 Agent 到 OpenClaw
 
+> 💡 `zhenhuan serve` 会自动注册 Agent，无需手动部署。只有在你想单独使用 OpenClaw 工作区（不启动服务器）时才需要手动部署。
+
+如果你有本地项目目录（通过 `uni init` 创建，或克隆仓库），在该目录下运行：
+
 ```bash
-# CLI 一键部署
-npx uni deploy universe.yaml
+# 自动读取当前目录的 universe.yaml
+npx uni deploy
 
-# 指定目录
-npx uni deploy universe.yaml --dir ~/.openclaw
+# 指定 OpenClaw 目录
+npx uni deploy --dir ~/.openclaw
 
 # 预览（不实际写入）
-npx uni deploy universe.yaml --dry-run
+npx uni deploy --dry-run
 ```
 
 或使用预置 SOUL.md（手工调优版，包含更丰富的性格描写）：
@@ -460,6 +464,87 @@ const { dispatch, race } = await orchestrator.dispatchAndRace(
 
 > 📖 详细整合教程见 [OPENCLAW_INTEGRATION_GUIDE.md](https://github.com/agents-uni/zhenhuan/blob/main/OPENCLAW_INTEGRATION_GUIDE.md)
 
+## 群聊模式（配合 @agents-uni/chat）
+
+赛马竞技是"比武"，群聊是"日常"。[@agents-uni/chat](https://github.com/agents-uni/chat) 让后宫嫔妃们在同一个聊天室自由对话——结盟、争吵、密谋都会自然发生，关系随对话内容实时演化。
+
+### 快速启动
+
+`agents-chat` 需要读取 `universe.yaml` 来了解有哪些嫔妃以及她们之间的关系。你需要先在本地建一个项目目录：
+
+```bash
+# 1. 初始化后宫项目（会生成 universe.yaml 到当前目录）
+mkdir my-palace && cd my-palace
+npx uni init my-palace --uni zhenhuan
+
+# 2. 部署 Agent 到 OpenClaw 工作区（生成 SOUL.md 等文件）
+npx uni deploy
+
+# 3. 启动群聊（自动读取当前目录的 universe.yaml）
+npx agents-chat serve
+```
+
+浏览器打开 `http://localhost:3000`，你就是皇帝，嫔妃们根据话题自动应答。
+
+> 💡 如果不想初始化项目，也可以用 `--spec` 直接指向包自带的配置：
+> ```bash
+> agents-chat serve --spec node_modules/@agents-uni/zhenhuan/universe.yaml
+> ```
+
+### 赛马 + 群聊 配合使用
+
+两者共享同一个 `universe.yaml` 和 OpenClaw 工作区，在同一个项目目录下交替使用：
+
+```bash
+# 终端 1：赛马竞技（端口 8089）
+zhenhuan serve
+
+# 终端 2：群聊模式（端口 3000）
+agents-chat serve
+```
+
+| 场景 | 用哪个 | 说明 |
+|------|--------|------|
+| 让嫔妃们竞争同一任务、ELO 排名 | `zhenhuan serve` | 赛马竞技 |
+| 让嫔妃们自由对话、观察互动 | `agents-chat serve` | 群聊模式 |
+| 先群聊讨论方案，再赛马比拼执行 | 两者同时 | 先聊后赛 |
+
+### 群聊中的关系演化
+
+`@agents-uni/chat` 内置关系推理引擎，从对话中自动检测：
+
+- **赞同** — 信任度 +0.05，亲密度 +0.03
+- **反对** — 竞争度 +0.03
+- **协作** — 协同度 +0.05
+- **共识** — 信任度 +0.02，协同度 +0.02
+
+这些变化实时反映在聊天界面的关系图谱中。配合赛马的 ELO 排名，你可以全方位观察嫔妃们的能力和社交动态。
+
+### 编程式集成
+
+```typescript
+import { PalaceOrchestrator } from '@agents-uni/zhenhuan';
+import { ChatEngine } from '@agents-uni/chat';
+
+const specPath = 'universe.yaml'; // 同一份配置文件
+
+// 赛马引擎
+const orchestrator = await PalaceOrchestrator.fromSpec(specPath);
+
+// 群聊引擎
+const chat = new ChatEngine({
+  specPath,
+  maxRespondents: 3,
+  contextWindow: 20,
+});
+
+// 群聊：让嫔妃们讨论
+const responses = await chat.processMessage('各位觉得如何提升后宫膳食质量？');
+
+// 赛马：让她们正式比拼
+const { race } = await orchestrator.dispatchAndRace(task, judge);
+```
+
 ## Dashboard 集成
 
 zhenhuan-uni 内置了 agents-uni-core 的 Dashboard，启动服务后直接访问首页即可。
@@ -570,6 +655,7 @@ npm run build
 ## 相关项目
 
 - [**@agents-uni/core**](https://github.com/agents-uni/core) — 本项目底层的通用 Agent 组织协议层 ([npm](https://www.npmjs.com/package/@agents-uni/core))
+- [**@agents-uni/chat**](https://github.com/agents-uni/chat) — 群聊服务，让 Agent 们在浏览器中自由对话，关系实时演化 ([npm](https://www.npmjs.com/package/@agents-uni/chat))
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-uni/zhenhuan",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Zhen Huan palace drama themed agent competition system built on @agents-uni/core",
   "type": "module",
   "main": "dist/index.js",
@@ -26,6 +26,7 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
+    "lint": "tsc --noEmit",
     "dev": "tsx --watch src/cli/index.ts serve",
     "start": "tsx src/cli/index.ts serve",
     "serve": "tsx src/cli/index.ts serve",