From d9aee1a4c2b54b10888d8f8f40d940e8f29805e0 Mon Sep 17 00:00:00 2001
From: zhi <zhi@dev.hangman-lab.top>
Date: Tue, 3 Mar 2026 08:32:34 +0000
Subject: [PATCH] docs: update README for turn-based features

---
 README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 65 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 687c3fe..8a2bfd7 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,52 @@
 # WhisperGate
 
-Rule-based no-reply gate for OpenClaw.
+Rule-based no-reply gate + turn manager for OpenClaw (Discord).
 
 ## What it does
 
-WhisperGate adds a deterministic gate **before model selection**:
+WhisperGate adds deterministic logic **before model selection** and **turn-based speaking** for multi-agent Discord channels:
 
-1. If message is not from Discord → skip gate
-2. If sender is in bypass user list → skip gate
-3. If message ends with configured end-symbol → skip gate
-4. Otherwise switch this turn to a no-reply model/provider
+- **Rule gate (before_model_resolve)**
+  1. Non-Discord → skip
+  2. Sender in bypass list / human list → skip
+  3. Message ends with configured end symbol → skip
+  4. Otherwise → route to no-reply model/provider
 
-The no-reply provider returns `NO_REPLY` for any input.
+- **End-symbol enforcement**
+  - Injects instruction like: `你的这次发言必须以🔚作为结尾…`
+  - In group chats, also injects: “无关/不需要回应就 NO_REPLY”
+
+- **Turn-based speaking (multi-bot)**
+  - Only the current speaker is allowed to respond
+  - Others are forced to no-reply
+  - Turn advances on **end-symbol** or **NO_REPLY**
+  - If all bots NO_REPLY, channel becomes **dormant** until a new human message
+
+- **Moderator handoff (optional)**
+  - When the current speaker NO_REPLYs, a moderator bot can post a handoff message to wake the next speaker
+
+- **Per-channel policy runtime**
+  - Policies stored in a standalone JSON file
+  - Update at runtime via `whispergate_tools` (memory first → persist to file)
+
+- **Discord control actions (optional)**
+  - Private channel create/update + member list
+  - Unified via `whispergate_tools`
 
 ---
 
 ## Repo layout
 
-- `plugin/` — OpenClaw plugin (before_model_resolve hook)
-- `no-reply-api/` — OpenAI-compatible minimal API that always returns `NO_REPLY`
+- `plugin/` — OpenClaw plugin (gate + turn manager + moderator presence)
+- `no-reply-api/` — OpenAI-compatible API that always returns `NO_REPLY`
 - `discord-control-api/` — Discord 管理扩展 API（私密频道 + 成员列表）
-- `docs/` — rollout, integration, run-mode notes
+- `docs/` — rollout, integration, run-mode notes, turn-wakeup analysis
 - `scripts/` — smoke/dev/helper checks
 - `Makefile` — common dev commands (`make check`, `make check-rules`, `make test-api`, `make smoke-discord-control`, `make up`)
 - `CHANGELOG.md` — milestone summary
 
+---
+
 ## Quick start (no Docker)
 
 ```bash
@@ -39,11 +61,43 @@ node scripts/render-openclaw-config.mjs
 ```
 
 See `docs/RUN_MODES.md` for Docker mode.
-
 Discord 扩展能力见：`docs/DISCORD_CONTROL.md`。
 
 ---
 
+## Runtime tools & commands
+
+### Tool: `whispergate_tools`
+
+Actions:
+- `policy-get`, `policy-set-channel`, `policy-delete-channel`
+- `turn-status`, `turn-advance`, `turn-reset`
+- `channel-private-create`, `channel-private-update`, `member-list`
+
+### Slash command (Discord)
+
+```
+/whispergate status
+/whispergate turn-status
+/whispergate turn-advance
+/whispergate turn-reset
+```
+
+---
+
+## Config highlights
+
+Common options (see `docs/INTEGRATION.md`):
+
+- `listMode`: `human-list` or `agent-list`
+- `humanList`, `agentList`
+- `endSymbols`
+- `channelPoliciesFile` (per-channel overrides)
+- `moderatorBotToken` (handoff messages)
+- `enableDebugLogs`, `debugLogChannelIds`
+
+---
+
 ## Development plan (incremental commits)
 
 - [x] Task 1: project docs + structure