@agents-uni/zhenhuan 0.1.5 → 0.1.6

package/README.en.md

@@ -75,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:
 
@@ -417,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):
@@ -463,34 +466,48 @@ const { dispatch, race } = await orchestrator.dispatchAndRace(
 
 ## Group Chat (with @agents-uni/chat)
 
-Horse racing is the "arena"; group chat is "daily life". With [@agents-uni/chat](https://github.com/agents-uni/chat), your concubines can talk freely in a shared chat room — forming alliances, arguing, scheming — and their relationships evolve in real time based on the conversation.
+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
-# Install the chat package
-npm install -g @agents-uni/chat
+# 1. Initialize a palace project (generates universe.yaml)
+mkdir my-palace && cd my-palace
+npx uni init my-palace --uni zhenhuan
 
-# Deploy agents first (if not already deployed)
-uni deploy
+# 2. Deploy agents to OpenClaw workspaces (generates SOUL.md etc.)
+npx uni deploy
 
-# Start group chat in the directory containing universe.yaml
-agents-chat serve
-# Or specify the config file
-agents-chat serve --spec /path/to/universe.yaml
+# 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, and can be used simultaneously or alternately:
+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
 
-| Scenario | Which to use | Command |
-|----------|-------------|---------|
+# 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 alternately | Chat then race |
+| Discuss approaches first, then compete on execution | Both together | Chat then race |
 
 ### Relationship Evolution in Chat
 
@@ -509,12 +526,14 @@ These changes are reflected in real time on the chat UI's relationship graph. Co
 import { PalaceOrchestrator } from '@agents-uni/zhenhuan';
 import { ChatEngine } from '@agents-uni/chat';
 
-// Initialize the palace
-const orchestrator = await PalaceOrchestrator.fromSpec('universe.yaml');
+const specPath = 'universe.yaml'; // same config file
+
+// Horse racing engine
+const orchestrator = await PalaceOrchestrator.fromSpec(specPath);
 
-// Start chat engine with the same config
+// Group chat engine
 const chat = new ChatEngine({
-  specPath: 'universe.yaml',
+  specPath,
   maxRespondents: 3,
   contextWindow: 20,
 });

package/README.md

@@ -75,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
+```
 
 启动后会打印访问链接：
 
@@ -417,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（手工调优版，包含更丰富的性格描写）：
@@ -463,45 +466,59 @@ const { dispatch, race } = await orchestrator.dispatchAndRace(
 
 ## 群聊模式（配合 @agents-uni/chat）
 
-赛马竞技是"比武"，群聊是"日常"。通过 [@agents-uni/chat](https://github.com/agents-uni/chat) 可以让后宫嫔妃们在同一个聊天室里自由对话——结盟、争吵、密谋都会自然发生，关系也会随对话内容实时演化。
+赛马竞技是"比武"，群聊是"日常"。[@agents-uni/chat](https://github.com/agents-uni/chat) 让后宫嫔妃们在同一个聊天室自由对话——结盟、争吵、密谋都会自然发生，关系随对话内容实时演化。
 
 ### 快速启动
 
+`agents-chat` 需要读取 `universe.yaml` 来了解有哪些嫔妃以及她们之间的关系。你需要先在本地建一个项目目录：
+
 ```bash
-# 安装 chat 包
-npm install -g @agents-uni/chat
+# 1. 初始化后宫项目（会生成 universe.yaml 到当前目录）
+mkdir my-palace && cd my-palace
+npx uni init my-palace --uni zhenhuan
 
-# 先部署 Agent（如果还没部署过）
-uni deploy
+# 2. 部署 Agent 到 OpenClaw 工作区（生成 SOUL.md 等文件）
+npx uni deploy
 
-# 在甄嬛后宫的 universe.yaml 目录下启动群聊
-agents-chat serve
-# 或指定配置文件
-agents-chat serve --spec /path/to/universe.yaml
+# 3. 启动群聊（自动读取当前目录的 universe.yaml）
+npx agents-chat serve
 ```
 
-浏览器打开 `http://localhost:3000`，你就是皇帝，嫔妃们会根据话题自动应答。
+浏览器打开 `http://localhost:3000`，你就是皇帝，嫔妃们根据话题自动应答。
+
+> 💡 如果不想初始化项目，也可以用 `--spec` 直接指向包自带的配置：
+> ```bash
+> agents-chat serve --spec node_modules/@agents-uni/zhenhuan/universe.yaml
+> ```
 
 ### 赛马 + 群聊 配合使用
 
-两者共享同一个 `universe.yaml` 和 OpenClaw 工作区，可以同时或交替使用：
+两者共享同一个 `universe.yaml` 和 OpenClaw 工作区，在同一个项目目录下交替使用：
+
+```bash
+# 终端 1：赛马竞技（端口 8089）
+zhenhuan serve
 
-| 场景 | 用哪个 | 命令 |
+# 终端 2：群聊模式（端口 3000）
+agents-chat serve
+```
+
+| 场景 | 用哪个 | 说明 |
 |------|--------|------|
 | 让嫔妃们竞争同一任务、ELO 排名 | `zhenhuan serve` | 赛马竞技 |
 | 让嫔妃们自由对话、观察互动 | `agents-chat serve` | 群聊模式 |
-| 先群聊讨论方案，再赛马比拼执行 | 两者交替 | 先聊后赛 |
+| 先群聊讨论方案，再赛马比拼执行 | 两者同时 | 先聊后赛 |
 
 ### 群聊中的关系演化
 
-`@agents-uni/chat` 内置了关系推理引擎，会从对话中自动检测：
+`@agents-uni/chat` 内置关系推理引擎，从对话中自动检测：
 
 - **赞同** — 信任度 +0.05，亲密度 +0.03
 - **反对** — 竞争度 +0.03
 - **协作** — 协同度 +0.05
 - **共识** — 信任度 +0.02，协同度 +0.02
 
-这些关系变化会实时反映在聊天界面的关系图谱中。配合赛马的 ELO 排名，你可以全方位观察嫔妃们的能力和社交动态。
+这些变化实时反映在聊天界面的关系图谱中。配合赛马的 ELO 排名，你可以全方位观察嫔妃们的能力和社交动态。
 
 ### 编程式集成
 
@@ -509,12 +526,14 @@ agents-chat serve --spec /path/to/universe.yaml
 import { PalaceOrchestrator } from '@agents-uni/zhenhuan';
 import { ChatEngine } from '@agents-uni/chat';
 
-// 先初始化后宫
-const orchestrator = await PalaceOrchestrator.fromSpec('universe.yaml');
+const specPath = 'universe.yaml'; // 同一份配置文件
+
+// 赛马引擎
+const orchestrator = await PalaceOrchestrator.fromSpec(specPath);
 
-// 用同一份配置启动群聊引擎
+// 群聊引擎
 const chat = new ChatEngine({
-  specPath: 'universe.yaml',
+  specPath,
   maxRespondents: 3,
   contextWindow: 20,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-uni/zhenhuan",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Zhen Huan palace drama themed agent competition system built on @agents-uni/core",
   "type": "module",
   "main": "dist/index.js",